Siticone Background Worker

The SiticoneBackgroundWorker is an enhanced version of the standard .NET BackgroundWorker component. It simplifies asynchronous task management by providing extended progress reporting capabilities that include status messages alongside percentage updates. It is essential for building responsive UIs that need to perform long-running operations without freezing the main thread.

Extended Features

New capabilities that go beyond the standard BackgroundWorker.

Feature	Description
`ProgressChangedEx`	A specialized event that carries both the progress percentage and a custom string message. Eliminates the need to manually cast the `UserState` object.
`ReportProgressEx`	A dedicated method to trigger the extended progress event with a clear message, improving code readability.
`Smart Tags`	Integrated design-time actions to quickly enable progress reporting and cancellation support.

Public Methods

Methods for interacting with the worker thread.

Method	Description & Usage Example
`ReportProgressEx`	worker.ReportProgressEx(50, "Processing Data..."); Reports the current progress percentage along with a user-friendly status message.
`RunWorkerAsync`	worker.RunWorkerAsync(argument); Starts the execution of the background operation.
`CancelAsync`	worker.CancelAsync(); Requests cancellation of a pending background operation.

Events

ProgressChangedEx Event

// Subscribing to the extended progress event
worker.ProgressChangedEx += (s, e) => 
{
                // Directly access the message property
    lblStatus.Text = e.Message;
    progressBar1.Value = e.ProgressPercentage;
    
                Console.WriteLine($"Step: {e.ProgressPercentage}% - {e.Message}");
};

DoWork Event (Standard)

// The heavy lifting happens here on a background thread
worker.DoWork += (s, e) => 
{
                for (int i = 0; i <= 100; i += 10)
    {
                if (worker.CancellationPending) 
        {
            e.Cancel = true;
                return;
        }
        
                // Use the extended report method
        worker.ReportProgressEx(i, $"Processing batch {i/10}...");
                Thread.Sleep(500);
    }
};

Designer Experience

Includes a Smart Tag panel for quick configuration.

Category	Features
`Quick Actions`	Enable All Features: Sets both `WorkerReportsProgress` and `WorkerSupportsCancellation` to true with one click. Simulate Progress: Test your UI's response to progress updates directly in the designer.
`Utilities`	Copy/Paste Settings: Easily replicate worker configurations.

Detailed Usage Examples

Example 1: File Download with Status

Simulates a file download process, updating a progress bar and status label.

C# - File Download

private void StartDownload()
{
                var downloader = new SiticoneBackgroundWorker();
    
                // Configure
    downloader.WorkerReportsProgress = true;
    downloader.WorkerSupportsCancellation = true;
    
                // 1. DoWork: The background task
    downloader.DoWork += (s, e) => 
    {
                string[] files = { "data.json", "images.zip", "setup.exe" };
                for (int i = 0; i < files.Length; i++)
        {
                Thread.Sleep(1000); // Simulate network delay
            
                int percentage = (int)((i + 1) / (float)files.Length * 100);
            downloader.ReportProgressEx(percentage, $"Downloading {files[i]}...");
        }
    };
    
                // 2. ProgressChangedEx: Update UI safely
    downloader.ProgressChangedEx += (s, e) => 
    {
        lblStatus.Text = e.Message;
        progressBar1.Value = e.ProgressPercentage;
    };
    
                // 3. RunWorkerCompleted: Finalize
    downloader.RunWorkerCompleted += (s, e) => 
    {
        lblStatus.Text = "Download Complete!";
                MessageBox.Show("All files downloaded.");
    };
    
    downloader.RunWorkerAsync();
}

Example 2: Database Migration Tool

A robust example showing cancellation support and detailed step reporting.

C# - Database Migration

private SiticoneBackgroundWorker _dbWorker;

private void InitializeMigration()
{
    _dbWorker = new SiticoneBackgroundWorker();
    _dbWorker.WorkerReportsProgress = true;
    _dbWorker.WorkerSupportsCancellation = true;
    
    _dbWorker.DoWork += DbWorker_DoWork;
    _dbWorker.ProgressChangedEx += DbWorker_Progress;
    _dbWorker.RunWorkerCompleted += DbWorker_Completed;
}

private void DbWorker_DoWork(object sender, DoWorkEventArgs e)
{
                var worker = (SiticoneBackgroundWorker)sender;
    
                // Step 1: Backup
    worker.ReportProgressEx(10, "Backing up current database...");
                Thread.Sleep(500);
    
                if (worker.CancellationPending) { e.Cancel = true; return; }

                // Step 2: Schema Update
    worker.ReportProgressEx(40, "Updating table schema...");
                Thread.Sleep(500);
    
                // Step 3: Data Migration
    worker.ReportProgressEx(80, "Migrating user records...");
                Thread.Sleep(500);
    
    worker.ReportProgressEx(100, "Verification complete.");
}

private void DbWorker_Progress(object sender, SiticoneBackgroundWorker.ProgressChangedExEventArgs e)
{
                Console.WriteLine($"[{e.ProgressPercentage}%] {e.Message}");
}

private void DbWorker_Completed(object sender, RunWorkerCompletedEventArgs e)
{
                if (e.Cancelled)
                Console.WriteLine("Migration Cancelled.");
                else if (e.Error != null)
                Console.WriteLine($"Error: {e.Error.Message}");
                else
                Console.WriteLine("Migration Successful!");
}