在資料流程元件中引發和定義事件

發行項
05/04/2023

適用於：SQL Server Azure Data Factory 中的 SSIS Integration Runtime

元件開發人員可以引發 IDTSComponentEvents 介面中定義的事件子集，其方式是呼叫 ComponentMetaData 屬性上所公開的方法。您也可以使用 EventInfos 集合來定義自訂事件，然後在執行期間使用 FireCustomEvent 方法來引發這些事件。本章節描述如何建立及引發事件，並提供有關您在設計階段的何時應該引發事件的指引。

引發事件

元件會使用 IDTSComponentMetaData100 介面的 Fire<X> 方法來引發事件。您可以在元件的設計和執行期間引發事件。一般在元件設計期間，FireError 和 FireWarning 方法會在驗證期間呼叫。這些事件會在 SQL Server Data Tools (SSDT) 的 [錯誤清單] 窗格中顯示訊息，並在元件設定不正確時，提供意見給元件的使用者。

元件也可以在執行期間的任何時間點引發事件。事件可讓元件開發人員在執行元件時，提供意見給此元件的使用者。在執行期間呼叫 FireError 方法很可能會讓封裝失敗。

定義及引發自訂事件

定義自訂事件

自訂事件的建立是藉由呼叫 Add 集合的 EventInfos 方法。這個集合是由資料流程工作所設定，並透過 PipelineComponent 基底類別當做屬性提供給元件開發人員。這個類別包含資料流程工作所定義的自訂事件，以及此元件在 RegisterEvents 方法期間所定義的自訂事件。

元件的自訂事件不會保存在封裝 XML 中。因此，設計和執行期間會呼叫 RegisterEvents 方法，好讓此元件定義它所引發的事件。

Add 方法的 allowEventHandlers 參數會指定此元件是否允許針對此事件建立 DtsEventHandler 物件。請注意，DtsEventHandlers 是同步的。因此，要等到附加至自訂事件的 DtsEventHandler 已經完成執行以後，此元件才會繼續執行。若 allowEventHandlers 參數為 true，便會透過 SQL Server Integration Services 執行階段自動建立和植入的參數，自動將此事件的每一個參數提供給任何 DtsEventHandler 物件使用。

引發自訂事件

元件引發自訂事件的方式，是藉由呼叫 FireCustomEvent 方法及提供此事件的名稱、文字和參數。若 allowEventHandlers 參數為 true，則任何為自訂事件所建立的 DtsEventHandlers，都會由 SSIS 執行階段引擎執行。

自訂事件範例

下列程式碼範例示範一個元件，此元件會在 RegisterEvents 方法期間定義自訂事件，然後在執行階段藉由呼叫 FireCustomEvent 方法來引發此事件。

public override void RegisterEvents()  
{  
    string [] parameterNames = new string[2]{"RowCount", "StartTime"};  
    ushort [] parameterTypes = new ushort[2]{ DtsConvert.VarTypeFromTypeCode(TypeCode.Int32), DtsConvert.VarTypeFromTypeCode(TypeCode.DateTime)};  
    string [] parameterDescriptions = new string[2]{"The number of rows to sort.", "The start time of the Sort operation."};  
    EventInfos.Add("StartingSort","Fires when the component begins sorting the rows.",false,ref parameterNames, ref parameterTypes, ref parameterDescriptions);  
}  
public override void ProcessInput(int inputID, PipelineBuffer buffer)  
{  
    while (buffer.NextRow())  
    {  
       // Process buffer rows.  
    }  
  
    IDTSEventInfo100 eventInfo = EventInfos["StartingSort"];  
    object []arguments = new object[2]{buffer.RowCount, DateTime.Now };  
    ComponentMetaData.FireCustomEvent("StartingSort", "Beginning sort operation.", ref arguments, ComponentMetaData.Name, ref FireSortEventAgain);  
}

Public  Overrides Sub RegisterEvents()   
  Dim parameterNames As String() = New String(2) {"RowCount", "StartTime"}   
  Dim parameterTypes As System.UInt16() = New System.UInt16(2) {DtsConvert.VarTypeFromTypeCode(TypeCode.Int32), DtsConvert.VarTypeFromTypeCode(TypeCode.DateTime)}   
  Dim parameterDescriptions As String() = New String(2) {"The number of rows to sort.", "The start time of the Sort operation."}   
  EventInfos.Add("StartingSort", "Fires when the component begins sorting the rows.", False, parameterNames, parameterTypes, parameterDescriptions)   
End Sub   
  
Public  Overrides Sub ProcessInput(ByVal inputID As Integer, ByVal buffer As PipelineBuffer)   
  While buffer.NextRow   
  End While   
  Dim eventInfo As IDTSEventInfo100 = EventInfos("StartingSort")   
  Dim arguments As Object() = New Object(2) {buffer.RowCount, DateTime.Now}   
  ComponentMetaData.FireCustomEvent("StartingSort", _  
    "Beginning sort operation.", arguments, _  
    ComponentMetaData.Name, FireSortEventAgain)   
End Sub

另請參閱

Integration Services (SSIS) 事件處理常式
 將事件處理常式新增至套件

Share via