- allows to specify the progress of the task
- allows describing the overall operation
- allows describing the 'instant' state
- allows determinate status (x/y)
- allows indeterminate status
Example API usage:
var reporter = LoggingService.GetProgressReporter("Test under linux-x64");
// Terminal Logger at this point starts rendering a progress tracker that looks something like
// Test under linux-x64: [-------------------]
int succeeded = 10;
int failed = 5;
int skipped = 2;
int total = 100;
// run tests
// periodically report progress. percentage is optional, if not specified an indeterminate progress is shown
// description is optional, if not specified only a progress bar is shown
// if description is too long to render a reasonable progress, description may be truncated
reporter.ReportProgress(percentage: (10 + 5 + 2)/100, description: $"{succeeded} succeeded, {failed} failed, {skipped} skipped");
// Terminal Logger at this point renders a progress tracker that looks something like
// Test under linux-x64: [##########---------] 10 succeeded, 5 failed, 2 skipped (17%)
// NOTE: the layout coulod change - for example this might also be viable:
// Test under linux-x64: [##########---------(10 succeeded, 5 failed, 2 skipped)] (17%)
// The key concept is that these are just rearrangements of the same core sections (defined below).
// finish the operation
reporter.CompleteProgress(finalMessage: $"{succeeded} succeeded, {failed} failed, {skipped} skipped, {total} tests run.");
// the MSbuild Logging engine would send a final summary message to the binlog
// terminal logger may show the completed progress item for a period of time, but the progress-reporting area may clear
// as the overall projects are completed.
The overall progress reporting in Terminal Logger specifically should be thought of as a new 'area' of the rendering. Today we have a 'project summary' area and a 'node status' area. Progress would be reported in a new area in between the two. Each progress item would have its own line, and each line would have up to 4 components:
- The name of the progress item, set by
GetProgressReporter
- The progress bar, which is a visual representation of the progress. This could be showing a known or unknown quantity of work items.
- An optional description, which is a textual representation/summary of the progress shown in the bar.
- An optional percentage, which is shown if the progress is deterministic.
Questions for the engine:
- what frequency/how should messages from child nodes be sent to the central node, to not swamp the system?
- how should rendering of the description be controlled? Is allowing users to emit their own ANSI codes for color/etc fine for now?
References:
Feedback from meeting today:
Agreed - the overall duration of the 'progress operation' should be reportable
This seems very reasonable - the example above is meant to be illustrative but not exhaustive.
This might be solvable when an MSBuild XML expression of the Task API - e.g. CreateProgress/ReportProgress/FinishProgress Tasks that authors could use in their targets.
We want to not solve this with the progress APIs - we want to solve this uniformly across MSBuild's Message logging infrastructure in another issue.
We need to do more design work here, the above examples aren't locked-in by any means! The team already has a few ideas to try out around where the progress should appear and how it should render in circumstances like small viewports, etc.