Progress with Stages
Instead of updating the progress of the task stage directly, you can split it into multiple child stages. This provides more detail in the progress report.
Add Stages
Each stage is given a weight and a maximum value:
IStage stage1 = task.TaskStage.AddChild("Searching for new Documents", 1, 10); IStage stage2 = task.TaskStage.AddChild("Processing Documents", 8, 80); IStage stage3 = task.TaskStage.AddChild("Deleting unseen documents", 1, 100);
Weight
The first number passed to AddChild
is the weight. The weights of the child stages are used to split the progress of the parent stage between the children. In the example above this means the first stage accounts for 10% (1/10) of the work, the second for 80% (8/10) and the third for 10% (1/10).
The weights of child stages only have any meaning when compared to each other, because the weights indicate how much of the work the stage is predicted to contain. Instead of using the weights 1
, 8
and 1
the example could have used 2
, 16
and 2
to achieve exactly the same effect.
Maximum Value
The maximum value for each stage has exactly the same meaning as in the basic progress example. The progress of stage 1 is measured on a scale of 0 to 10, stage 2 on a scale of 0 to 80 and stage 3 on a scale of 0 to 100.
Process Stages
When the synchronize
action begins, each stage is in the “Pending” state with a progress of 0%. The following code shows how to update the progress for a stage when it is time to process it:
using (ActiveStage activeStage = new ActiveStage(stage1)) { for (int ii = 0; ii < 15; ++ii) { // Do work activeStage.Stage.IncrementProgress(); } }
When the ActiveStage
is created, stage 1 moves to the "Processing" state. Progress is incremented gradually as work is done and then the stage moves into the "Finished" state when theusing
block ends
You might notice that although the maximum for stage 1 was set to 10, the loop above increments 15 times. This demonstrates what happens when the maximum is estimated but the actual amount of work ends up being greater. In this case progress is incremented to the maximum in the first 10 iterations, and then stays at 100% for the remaining 5 – progress never exceeds 100%.
Similarly, in the following example there was less work to do than expected:
using (ActiveStage activeStage = new ActiveStage(stage3)) { for (int ii = 0; ii < 30; ++ii) { // Do work activeStage.Stage.IncrementProgress(); } }
In this case the maximum was set to 100 but there were actually only 30 units of work to complete. In this case, when the stage is finished at the end of the using
Progress reporting is most accurate when the stage weights and maximums are accurate, but ConnectorLib .NET ensures that progress does not exceed 100% and does not go backwards. Using ActiveStage
also ensures that completed stages are set to 100% even if the progress for the stage was not set to the maximum value.