raising-and-defining-events-in-a-custom-task.md

title	Raising and Defining Events in a Custom Task
description	Raising and Defining Events in a Custom Task
author	chugugrace
ms.author	chugu
ms.date	03/04/2017
ms.service	sql
ms.subservice	integration-services
ms.topic	reference
helpviewer_keywords	SSIS events, custom status information [SQL Server], task events custom tasks [Integration Services], events SSIS custom tasks, events IDTSComponentEvents interface events [Integration Services], custom events [Integration Services], runtime custom events [Integration Services] SSIS events, runtime IDTSEvents interface
dev_langs	VB CSharp

Raising and Defining Events in a Custom Task

[!INCLUDEsqlserver-ssis]

The [!INCLUDEssISnoversion] 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 xref:Microsoft.SqlServer.Dts.Runtime.IDTSComponentEvents interface defines these events, and is provided to tasks as a parameter to the xref:Microsoft.SqlServer.Dts.Runtime.Executable.Validate%2A and xref:Microsoft.SqlServer.Dts.Runtime.Executable.Execute%2A methods.

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

Creating Custom Events

Custom task developers can define new, custom events by creating a new xref:Microsoft.SqlServer.Dts.Runtime.EventInfo in their overridden implementation of the xref:Microsoft.SqlServer.Dts.Runtime.Task.InitializeTask%2A method. After the xref:Microsoft.SqlServer.Dts.Runtime.EventInfo is created, it is added to the EventInfos collection by using the xref:Microsoft.SqlServer.Dts.Runtime.EventInfos.Add%2A method. The method signature of the xref:Microsoft.SqlServer.Dts.Runtime.EventInfos.Add%2A 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 xref:Microsoft.SqlServer.Dts.Runtime.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, xref:Microsoft.SqlServer.Dts.Runtime.DtsEventHandler objects are created for the event. Any parameters that were defined for the event are now available to the xref:Microsoft.SqlServer.Dts.Runtime.DtsEventHandler in the variables collection of the xref:Microsoft.SqlServer.Dts.Runtime.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"];  
}  

Public Overrides Sub InitializeTask(ByVal connections As Connections, _  
ByVal variables As VariableDispenser, ByVal events As IDTSInfoEvents, _  
ByVal log As IDTSLogging, ByVal eventInfos As EventInfos, _  
ByVal logEntryInfos As LogEntryInfos, ByVal refTracker As ObjectReferenceTracker)   
  
    Dim paramNames(0) As String  
    Dim paramTypes(0) As TypeCode = {TypeCode.Int32}  
    Dim paramDescriptions(0) As String  
  
    Me.eventInfos = eventInfos  
  
    paramNames(0) = "InitialValue"  
    paramDescriptions(0) = "The value before it is incremented."  
  
    Me.eventInfos.Add("OnBeforeIncrement", _  
      "Fires before the task increments the value.", _  
      True, paramNames, paramTypes, paramDescriptions)  
    Me.onBeforeIncrement = Me.eventInfos("OnBeforeIncrement")  
  
    paramDescriptions(0) = "The value after it has been incremented."  
    Me.eventInfos.Add("OnAfterIncrement", _  
      "Fires after the initial value is updated.", True, _  
      paramNames, paramTypes, paramDescriptions)  
    Me.onAfterIncrement = Me.eventInfos("OnAfterIncrement")  
  
End Sub  

Raising Custom Events

Custom events are raised by calling the xref:Microsoft.SqlServer.Dts.Runtime.IDTSComponentEvents.FireCustomEvent%2A method. The following line of code raises a custom event.

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

componentEvents.FireCustomEvent(Me.onBeforeIncrement.Name, _  
Me.onBeforeIncrement.Description, arguments, _  
Nothing,  bFireOnBeforeIncrement)  

Sample

The following example shows a task that defines a custom event in the InitializeTask method, adds the custom event to the xref:Microsoft.SqlServer.Dts.Runtime.EventInfos collection, and then raises the custom event during its Execute method by calling the xref:Microsoft.SqlServer.Dts.Runtime.IDTSComponentEvents.FireCustomEvent%2A 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);  
  
        }  
   }  

<DtsTask(DisplayName = "CustomEventTask")> _   
    Public Class CustomEventTask  
     Inherits Task  
        Public Overrides Function Execute(ByVal connections As Connections, _  
          ByVal variableDispenser As VariableDispenser, _  
          ByVal componentEvents As IDTSComponentEvents, _  
          ByVal log As IDTSLogging, ByVal transaction As Object) _  
          As DTSExecResult  
  
            Dim fireAgain As Boolean  
            Dim args() As Object =  New Object(1) {"The value of the parameter."}  
  
            componentEvents.FireCustomEvent("MyCustomEvent", _  
              "Firing the custom event.", args, _  
              "CustomEventTask" ,  fireAgain)  
            Return DTSExecResult.Success  
        End Function  
  
        Public Overrides  Sub InitializeTask(ByVal connections As Connections, _  
          ByVal variableDispenser As VariableDispenser,  
          ByVal events As IDTSInfoEvents,  
          ByVal log As IDTSLogging, ByVal eventInfos As EventInfos, ByVal logEnTryInfos As LogEnTryInfos, ByVal refTracker As ObjectReferenceTracker)  
  
            Dim names() As String =  New String(1) {"Parameter1"}  
            Dim types() As TypeCode =  New TypeCode(1) {TypeCode.String}  
            Dim descriptions() As String =  New String(1) {"Parameter description."}  
  
            eventInfos.Add("MyCustomEvent", _  
              "Fires when my interesting event happens.", _  
              True, names, types, descriptions)  
  
        End Sub  
  
    End Class  

See Also

Integration Services (SSIS) Event Handlers
Add an Event Handler to a Package