ConnectorLib .NET 24.2

# 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 the `using` 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` block, the progress of the stage jumps from 30% to 100%.

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.

Copyright 2024 Open Text
Version 24.2 | Last updated March 2024

Send documentation feedback

Close

Send documentation feedback

To send feedback using your default email client, open an email window.

Otherwise, send your feedback and the information below to MFI-swpdl.idoldocsfeedback@opentext.com.

We appreciate your feedback!

Product: IDOL ConnectorLib .NET 24.2

Topic Title: Progress with Stages