在自定义任务中引发和定义事件Raising and Defining Events in a Custom Task

适用于:Applies to: 是SQL ServerSQL Server(所有支持的版本)yesSQL ServerSQL Server (all supported versions) 是 Azure 数据工厂中的 SSIS Integration RuntimeSSIS Integration Runtime in Azure Data Factoryyes Azure 数据工厂中的 SSIS Integration RuntimeSSIS Integration Runtime in Azure Data Factory适用于:Applies to: 是SQL ServerSQL Server(所有支持的版本)yesSQL ServerSQL Server (all supported versions) 是 Azure 数据工厂中的 SSIS Integration RuntimeSSIS Integration Runtime in Azure Data Factoryyes Azure 数据工厂中的 SSIS Integration RuntimeSSIS Integration Runtime in Azure Data Factory

Integration ServicesIntegration Services 运行时引擎提供了一组事件,这些事件提供验证和执行任务时任务进度的状态。The Integration ServicesIntegration 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. IDTSComponentEvents 接口用于定义这些事件,并且该接口可作为 ValidateExecute 方法的参数提供给任务。The IDTSComponentEvents interface defines these events, and is provided to tasks as a parameter to the Validate and Execute methods.

此外,还有另一组在 IDTSEvents 接口中定义的事件,TaskHost 可代表任务引发这些事件。There is another set of events, which are defined in the IDTSEvents interface, that are raised on behalf of the task by the TaskHost. 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.

创建自定义事件Creating Custom Events

自定义任务开发人员可通过在其 EventInfo 方法的重写实现中创建新的 InitializeTask 来定义新的自定义事件。Custom task developers can define new, custom events by creating a new EventInfo in their overridden implementation of the InitializeTask method. 创建 EventInfo 后,可使用 Add 方法将其添加到 EventInfos 集合。After the EventInfo is created, it is added to the EventInfos collection by using the Add method. Add 方法的方法签名如下所示: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);

下面的代码示例介绍了自定义任务的 InitializeTask 方法,在该自定义任务中,创建了两个自定义事件并设置了其属性。The following code sample shows the InitializeTask method of a custom task, where two custom events are created and their properties are set. 然后,将新事件添加到 EventInfos 集合。The new events are then added to the EventInfos collection.

第一个自定义事件的事件名为 “OnBeforeIncrement”,说明为“更新初始值后触发”。The first custom event has an eventName of "OnBeforeIncrement" and description of "Fires after the initial value is updated." 下一个参数为 true 值,指示此事件应允许创建用于处理事件的事件处理程序容器。The next parameter, the true value, indicates that this event should allow an event handler container to be created to handle the event. 事件处理程序是一个可向任务提供包和服务中的结构的容器,像其他诸如包、序列、ForLoop 和 ForEachLoop 的其他容器一样。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. allowEventHandlers 参数为 true 时,会为该事件创建 DtsEventHandler 对象。When the allowEventHandlers parameter is true, DtsEventHandler objects are created for the event. 为事件定义的所有参数现在均可在 DtsEventHandler 的变量集合中用于 DtsEventHandlerAny 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"];  
}  
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

通过调用 FireCustomEvent 方法引发自定义事件。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);  
componentEvents.FireCustomEvent(Me.onBeforeIncrement.Name, _  
Me.onBeforeIncrement.Description, arguments, _  
Nothing,  bFireOnBeforeIncrement)  

示例Sample

下面的示例演示了一个任务,该任务在 InitializeTask 方法中定义一个自定义事件,再将该自定义事件添加到 EventInfos 集合,然后通过调用 FireCustomEvent 方法在其 Execute 方法中引发该自定义事件。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);  
  
        }  
   }  
<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) 事件处理程序 Integration Services (SSIS) Event Handlers
在包中添加事件处理程序Add an Event Handler to a Package