public sealed class BackgroundWorker : Component

Public NotInheritable Class BackgroundWorker _
	Inherits Component

The BackgroundWorker class inherits from the .NET framework System.ComponentModel.Component class. It provides a similar programming experience to using the System.ComponentModel.BackgroundWorker class which is part of the .NET framework itself. Use the BackgroundWorker class to write add-ins for ArcGIS Explorer by making use of asynchronous operations on a worker thread, leaving the main user interface (UI) thread responsive.

For more information on using the BackgroundWorker, see the Threading Namespace Overview.

You can create the BackgroundWorker programmatically or you can drag it onto a DockWindow or other Form from the Components tab of the Toolbox. If you create the BackgroundWorker in the Windows Forms Designer, it will appear in the Component Tray, and its properties will be displayed in the Properties window.

To execute a time-consuming operation on a worker thread:

1. Create a BackgroundWorker object.
2. Define an event handler for the DoWork event and associate it with the event on the BackgroundWorker object you created.
3. Add code to the DoWork event handler to perform the worker thread operation.
4. Call the RunWorkerAsync method on the BackgroundWorker object to start the worker thread operation.

Optionally you may also wish to:

• Pass information to the DoWork event handler by using the argument parameter, and then use this information from the Argument property of the DoWorkEventArgs parameter.
• Define an event handler for the ProgressChanged event and associate it with the event on the BackgroundWorker object. Call the ReportProgress method one or multiple times from the DoWork event handler to raise the ProgressChanged event, passing in progress and message information. Write code in the ProgressChanged event handler to update the user with progress information, using the Progress and Message properties of the ProgressChangedEventArgs, generally by showing and updating a non-modal dialog.
• Define an event handler for the RunWorkerCompleted event and associate it with the event on the BackgroundWorker object. Set the Result property of the DoWorkEventArgs parameter in the DoWork method with information about the result of this operation. Write code in the RunWorkerCompleted event handler to report a result to the user or otherwise update the user interface, using the Result property of the RunWorkerCompletedEventArgs.

Note:

You must be careful not to manipulate any user-interface objects in your DoWork event handler, which is called on a worker thread and not on the UI thread. Instead, communicate to the user interface through the arguments of the ProgressChanged and RunWorkerCompleted events. Consider the following rules for using a worker thread: ArcGIS Explorer objects are not thread safe; however you can serialize many ArcGIS Explorer objects and pass them from the UI thread to the worker thread (or vice-versa) and create new objects with the same state. The ToXmlString and CreateFromXmlString methods are helper methods to perform the serialization simply. These methods are supported on Geometries, Graphics, MapItems, Symbols, and Viewpoints. Use the arguments as described above to pass data passed between threads - you should not generally store member variables and access them from different threads. This type of usage is possible by reference to the .NET Framework help topics about thread synchronization but is considered an advanced usage and outside the scope of this documentation, and is still subject to the limitation of the ArcGIS Explorer objects not being thread-safe.

The following example shows a simple case of using a BackgroundWorker to perform work against ArcGIS Explorer objects on a background thread. A BackgroundWorker is created, and a Point geometry is created, serialized, and passed to the worker. In the DoWork method, which is called on a background thread, the Point is written out to a file; meanwhile, the user interface thread is not blocked.

CopyC#

using System;
using System.Collections.Generic;
using System.Text;
using ESRI.ArcGISExplorer.Geometry;
using ESRI.ArcGISExplorer.Mapping;

namespace ThreadingExample
{
  public class SimpleButton : ESRI.ArcGISExplorer.Application.Button
  {
    // References to the MapDisplay and BackgroundWorker are created, 
    // and therefore only used, on the UI thread.
    MapDisplay _md;
    ESRI.ArcGISExplorer.Threading.BackgroundWorker _bgWorker;
    // Constructor is called on the UI thread.
    public SimpleButton()
    {
      _md = ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay;

      // Create an Explorer BackgroundWorker component and hook 
      // up the DoWork event handler.
      _bgWorker = new ESRI.ArcGISExplorer.Threading.BackgroundWorker();
      _bgWorker.DoWork += new ESRI.ArcGISExplorer.Threading.DoWorkEventHandler(DoWork);
    }
    // OnClick is called on the UI thread.
    public override void OnClick()
    {
      // Access the active display and track a Point.
      Point ptOnUIThread = _md.TrackPoint();
      if (!_bgWorker.IsBusy)
      {
        // Trigger the DoWork event handler.
        _bgWorker.RunWorkerAsync(ptOnUIThread.ToXmlString());
      }
    }
    // DoWork is called on a worker thread.
    private void DoWork(object sender, ESRI.ArcGISExplorer.Threading.DoWorkEventArgs args)
    {
      Point ptOnBgThread = Point.CreateFromXmlString((string)args.Argument);

      // Perform some work on the background thread, such as
      // saving the clicked locations to a file.
      string filename = System.IO.Path.GetTempFileName();
      System.IO.StreamWriter sw = System.IO.File.CreateText(filename);
      sw.Write(ptOnBgThread.ToString());
      sw.Close();
    }
  }
}

CopyVB.NET

Imports System
Imports System.Collections.Generic
Imports System.Text
Imports ESRI.ArcGISExplorer.Geometry
Imports ESRI.ArcGISExplorer.Mapping

Public Class SimpleButton
  Inherits ESRI.ArcGISExplorer.Application.Button
  ' References to the MapDisplay and BackgroundWorker are created,
  ' and therefore only used, on the UI thread.
  Private _md As MapDisplay
  Private _bgWorker As ESRI.ArcGISExplorer.Threading.BackgroundWorker
  ' Constructor is called on the UI thread.


  Public Sub New()
    _md = ESRI.ArcGISExplorer.Application.Application.ActiveMapDisplay
    ' Create an Explorer BackgroundWorker component and hook
    ' up the DoWork event handler.
    _bgWorker = New ESRI.ArcGISExplorer.Threading.BackgroundWorker()
    AddHandler _bgWorker.DoWork, AddressOf DoWork
  End Sub

  ' OnClick is called on the UI thread.
  Public Overrides Sub OnClick()
    ' Access the active display and track a Point.
    Dim ptOnUIThread As ESRI.ArcGISExplorer.Geometry.Point = _md.TrackPoint()
    If (Not _bgWorker.IsBusy) Then
      ' Trigger the DoWork event handler.
      _bgWorker.RunWorkerAsync(ptOnUIThread.ToXmlString())
    End If
  End Sub

  ' DoWork is called on a worker thread.


  Private Sub DoWork(ByVal sender As Object, ByVal args As ESRI.ArcGISExplorer.Threading.DoWorkEventArgs)
    Dim ptOnBgThread As ESRI.ArcGISExplorer.Geometry.Point = ESRI.ArcGISExplorer.Geometry.Point.CreateFromXmlString(CStr(args.Argument))
    ' Perform some work on the background thread, such as
    ' saving the clicked locations to a file.
    Dim filename As String = System.IO.Path.GetTempFileName()
    Dim sw As System.IO.StreamWriter = System.IO.File.CreateText(filename)
    sw.Write(ptOnBgThread.ToString())
    sw.Close()
  End Sub

End Class

System..::.Object

  System..::.MarshalByRefObject

    System.ComponentModel..::.Component

      ESRI.ArcGISExplorer.Threading..::.BackgroundWorker