Export (0) Print
Expand All

Raising and Defining Events in a Custom Task

The Integration Services run-time engine provides a collection of events that provide status on the progress of a task as the task is validated and executed. The IDTSComponentEvents interface defines these events, and is provided to tasks as a parameter to the Validate and Execute methods.

There is another set of events, which are defined in the IDTSEvents interface, that are raised on behalf of the task by the TaskHost. The TaskHost raises events that occur before and after validation and execution, whereas the task raises the events that occur during execution and validation.

Custom task developers can define new, custom events by creating a new EventInfo in their overridden implementation of the InitializeTask method. After the EventInfo is created, it is added to the EventInfos collection by using the Add method. The method signature of the Add method is as follows:

public void Add(string eventName, string description, bool allowEventHandlers, string[] parameterNames, TypeCode[] parameterTypes, string[] parameterDescriptions);

The following code sample shows the InitializeTask method of a custom task, where two custom events are created and their properties are set. The new events are then added to the EventInfos collection.

The first custom event has an eventName of "OnBeforeIncrement" and description of "Fires after the initial value is updated." The next parameter, the true value, indicates that this event should allow an event handler container to be created to handle the event. The event handler is a container that provides structure in a package and services to tasks, like other containers such as the package, Sequence, ForLoop, and ForEachLoop. When the allowEventHandlers parameter is true, DtsEventHandler objects are created for the event. Any parameters that were defined for the event are now available to the DtsEventHandler in the variables collection of the DtsEventHandler.

public override void InitializeTask(Connections connections,
   VariableDispenser variables, IDTSInfoEvents events,
   IDTSLogging log, EventInfos eventInfos,
   LogEntryInfos logEntryInfos, ObjectReferenceTracker refTracker)
{
    this.eventInfos = eventInfos;
    string[] paramNames = new string[1];
    TypeCode[] paramTypes = new TypeCode[1]{TypeCode.Int32};
    string[] paramDescriptions = new string[1];

    paramNames[0] = "InitialValue";
    paramDescriptions[0] = "The value before it is incremented.";

    this.eventInfos.Add("OnBeforeIncrement", 
      "Fires before the task increments the value.",
      true,paramNames,paramTypes,paramDescriptions);
    this.onBeforeIncrement = this.eventInfos["OnBeforeIncrement"];

    paramDescriptions[0] = "The value after it has been incremented.";
    this.eventInfos.Add("OnAfterIncrement",
      "Fires after the initial value is updated.",
      true,paramNames, paramTypes,paramDescriptions);
    this.onAfterIncrement = this.eventInfos["OnAfterIncrement"];
}

Custom events are raised by calling the FireCustomEvent method. The following line of code raises a custom event.

componentEvents.FireCustomEvent(this.onBeforeIncrement.Name,
   this.onBeforeIncrement.Description, ref arguments,
   null, ref bFireOnBeforeIncrement);

The following example shows a task that defines a custom event in the InitializeTask method, adds the custom event to the EventInfos collection, and then raises the custom event during its Execute method by calling the FireCustomEvent method.

[DtsTask(DisplayName = "CustomEventTask")]
    public class CustomEventTask : Task
    {
        public override DTSExecResult Execute(Connections connections, 
          VariableDispenser variableDispenser, IDTSComponentEvents componentEvents,
           IDTSLogging log, object transaction)
        {
            bool fireAgain;
            object[] args = new object[1] { "The value of the parameter." };
            componentEvents.FireCustomEvent( "MyCustomEvent", 
              "Firing the custom event.", ref args,
              "CustomEventTask" , ref fireAgain );
            return DTSExecResult.Success;
        }

        public override void InitializeTask(Connections connections,
          VariableDispenser variableDispenser, IDTSInfoEvents events,
          IDTSLogging log, EventInfos eventInfos,
          LogEntryInfos logEntryInfos, ObjectReferenceTracker refTracker)
        {
            string[] names = new string[1] {"Parameter1"};
            TypeCode[] types = new TypeCode[1] {TypeCode.String};
            string[] descriptions = new string[1] {"Parameter description." };

            eventInfos.Add("MyCustomEvent",
             "Fires when my interesting event happens.",
             true, names, types, descriptions);

        }
   }
Integration Services icon (small) Stay Up to Date with Integration Services

For the latest downloads, articles, samples, and videos from Microsoft, as well as selected solutions from the community, visit the Integration Services page on MSDN:


For automatic notification of these updates, subscribe to the RSS feeds available on the page.

Community Additions

ADD
Show:
© 2014 Microsoft