以指令碼元件建立來源

發行項
05/04/2023

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

您在 Integration Services 封裝的資料流程中使用來源元件，以從資料來源載入資料，進而將其傳遞至下游轉換與目的地。通常您會透過現有的連接管理員來連接到資料來源。

如需指令碼元件的概觀，請參閱使用指令碼元件擴充資料流程。

指令碼元件以及它為您產生的基礎結構程式碼，可大幅簡化開發自訂資料流程元件的程序。不過，若要了解指令碼元件如何運作，全部讀完開發自訂資料流程元件所需的步驟，可能會非常有用。請參閱開發自訂資料流程元件一節，尤其是開發自訂來源元件主題。

開始使用來源元件

當您將指令碼元件新增至 SSIS Designer 的 [資料流程] 窗格時，就會開啟 [選取指令碼元件類型] 對話方塊，並提示您選取 [來源]、[目的地] 或 [轉換] 指令碼。在這個對話方塊中，選取 [來源] 。

在中繼資料設計模式中設定來源元件

選擇建立來源元件之後，您可以使用 [指令碼轉換編輯器] 來設定元件。如需詳細資訊，請參閱在指令碼元件編輯器中設定指令碼元件。

資料流程來源元件沒有輸入，而且支援一或多個輸出。設定元件的輸出是您必須在中繼資料設計模式下完成的其中一個步驟，方法是在撰寫自訂指令碼之前先使用 [指令碼轉換編輯器] 。

您也可以在 [指令碼轉換編輯器] 的 [指令碼] 頁面上設定 [ScriptLanguage] 屬性，來指定指令碼語言。

注意

若要為指令碼元件和指令碼工作設定預設指令碼語言，請使用 [選項] 對話方塊的 [一般] 頁面上的 [指令碼語言] 選項。如需相關資訊，請參閱 General Page。

加入連接管理員

通常來源元件使用現有的連接管理員，以連接到它將資料載入資料流程的資料來源。在 [指令碼轉換編輯器] 的 [連線管理員] 頁面上，按一下 [新增] 新增適當的連線管理員。

然而，連接管理員只是一種便利的單位，用以封裝和儲存連接至特定類型的資料來源所需的資訊。您必須撰寫自己的自訂程式碼，以載入或是儲存資料，以及 (可能的話) 開啟和關閉連至資料來源的連接。

如需如何利用指令碼元件以使用連線管理員的一般資訊，請參閱在指令碼元件中連線至資料來源。

如需 [指令碼轉換編輯器] 的 [連線管理員] 頁面詳細資訊，請參閱指令碼轉換編輯器 (連線管理員頁面)。

設定輸出和輸出資料行

來源元件沒有輸入，而且支援一或多個輸出。在 [指令碼轉換編輯器] 的 [輸入及輸出] 頁面上，預設已建立單一輸出，但是尚未建立輸出資料行。在編輯器的此頁面上，您可能會需要或想要設定下列項目。

您必須為每個輸出手動加入和設定輸出資料行。為每個輸出選取 [輸出資料行] 資料夾，然後使用 [新增資料行] 和 [移除資料行] 按鈕，為來源元件的每個輸出管理輸出資料行。之後，您將在指令碼中使用這裡所指派的名稱來參考輸出資料行，方法是使用在自動產生的程式碼中為您建立的具有類型之存取子屬性。
您可能會想要建立一或多個其他輸出，例如含有非預期值的資料列之模擬錯誤輸出。使用 [新增輸出] 和 [移除輸出] 按鈕管理來源元件的輸出。所有的輸入資料列都會導向至所有可用的輸出，除非您也為那些輸出的 ExclusionGroup 屬性指定相同的非零值，也就是您想要將每個輸入資料列導向至有著相同 ExclusionGroup 值的其中一個輸出。至於選取哪一個特定的整數值以識別 ExclusionGroup 則無關緊要。

注意

當您不想要輸出所有的資料列時，也可以使用具有單一輸出的非零 ExclusionGroup 屬性值。不過，在此情況下，您必須為要傳送至輸出的每個資料列，明確地呼叫 DirectRowTo<輸出緩衝區> 方法。
您可能會想要將易記名稱指派給輸出。之後，您將在指令碼中使用輸出的名稱來加以參考，方法是使用在自動產生的程式碼中為您建立的具有類型之存取子屬性。
通常，在相同 ExclusionGroup 中的多個輸出都有相同的輸出資料行。然而，如果您正在建立模擬的錯誤輸出，可能會想要加入更多的資料行以儲存錯誤資訊。如需資料流程引擎如何處理錯誤資料列的資訊，請參閱使用資料流程元件中的錯誤輸出。不過，在指令碼元件中，您必須撰寫自已的程式碼，以適當的錯誤資訊填入其他資料行。如需詳細資訊，請參閱模擬指令碼元件的錯誤輸出。

如需 [指令碼轉換編輯器] 的 [輸入和輸出] 頁面詳細資訊，請參閱指令碼轉換編輯器 (輸入和輸出頁面)。

加入變數

如果有任何要在指令碼中使用其值的現有變數，則可以在 [指令碼轉換編輯器] 的 [指令碼] 頁面上，將它們新增至 ReadOnlyVariables 和 ReadWriteVariables 屬性欄位中。

當您在屬性欄位中輸入多個變數時，請用逗號分隔變數名稱。您也可以按一下 ReadOnlyVariables 和 ReadWriteVariables 屬性欄位旁邊的省略符號 ( ... ) 按鈕，然後在 [選取變數] 對話方塊中選取變數，以輸入多個變數。

如需如何利用指令碼元件使用變數的一般資訊，請參閱在指令碼元件中使用變數。

如需 [指令碼轉換編輯器] 的 [指令碼] 頁面詳細資訊，請參閱指令碼轉換編輯器 (指令碼頁面)。

在程式碼設計模式中編寫來源元件的指令碼

在您已為元件設定中繼資料之後，請開啟 Microsoft Visual Studio Tools for Applications (VSTA) IDE 以撰寫自訂指令碼。若要開啟 VSTA，請在 [指令碼轉換編輯器] 的 [指令碼] 頁面上，按一下 [編輯指令碼] 。您可以使用 Microsoft Visual Basic 或 Microsoft Visual C# 撰寫指令碼，視為 ScriptLanguage 屬性選取的指令碼語言而定。

如需使用指令碼元件所建立之各種元件都適用的重要資訊，請參閱編碼和偵錯指令碼元件。

了解自動產生的程式碼

當您在建立和設定來源元件之後開啟 VSTA IDE，可編輯的 ScriptMain 類別會出現在程式碼編輯器中。您在 ScriptMain 類別中撰寫自訂程式碼。

ScriptMain 類別包含 CreateNewOutputRows 方法的虛設常式。 CreateNewOutputRows 是來源元件中最重要的方法。

如果您在 VSTA 中開啟 [專案總管] 視窗，則可以看到指令碼元件也會產生唯讀的 BufferWrapper 和 ComponentWrapper 專案項目。 ScriptMain 類別繼承自 ComponentWrapper 專案項目中的 UserComponent 類別。

在執行階段，資料流程引擎會叫用 UserComponent 類別中的 PrimeOutput 方法，它會覆寫 ScriptComponent 父類別的 PrimeOutput 方法。 PrimeOutput 方法會依序呼叫下列方法：

您在 ScriptMain 中覆寫以便從資料來源將資料列新增至輸出緩衝區的 CreateNewOutputRows 方法，一開始會是空的。
FinishOutputs 方法預設是空的。在 ScriptMain 中覆寫此方法以執行完成輸出所需的處理。
私用 MarkOutputsAsFinished 方法 (呼叫 ScriptBuffer 父類別的 SetEndOfRowset 方法) 用以指出輸出已完成的資料流程引擎。您在自己的程式碼中不需要明確地呼叫 SetEndOfRowset。

撰寫您的自訂程式碼

為了完成建立自訂來源元件，您可能會想要以 ScriptMain 類別中提供的下列方法來撰寫指令碼。

覆寫 AcquireConnections 方法以連線至外部資料來源。從連接管理員擷取連接物件，或是必要的連接資訊。
如果您可以同時載入所有的來源資料，請覆寫 PreExecute 方法以載入資料。例如，您可以針對連線到 SQL Server 資料庫的 ADO.NET 連線執行 SqlCommand，並同時將所有來源資料載入 SqlDataReader。如果您必須一次載入一個資料列的來源資料 (例如，在讀取文字檔時)，可以在 CreateNewOutputRows 中循環使用資料列時載入資料。
使用覆寫的 CreateNewOutputRows 方法將新資料列新增至空的輸出緩衝區，並將新輸出資料列中的每個資料行填入值。使用每個輸出緩衝區的 AddRow 方法，新增空的新資料列，然後設定每個資料行的值。通常您會複製從外部來源載入的資料行值。
覆寫 PostExecute 方法以完成處理資料。例如，您可以關閉用以載入資料的 SqlDataReader。
視需要，覆寫 ReleaseConnections 方法從外部資料來源中斷連線。

範例

下列範例示範建立來源元件時，ScriptMain 類別中所需的自訂程式碼。

注意

這些範例使用 AdventureWorks 範例資料庫中的 Person.Address 資料表，並透過資料流程傳遞其第一個和第四個資料行：intAddressID 和 nvarchar(30)City 資料行。在本章節中的來源、轉換和目的地範例使用相同的資料。每個範例都會記載其他必要條件與假設。

ADO.NET 來源範例

此範例示範一個來源元件如何使用現有的 ADO.NET 連線管理員，將 SQL Server 資料表中的資料載入資料流程。

如果您要執行這個範例程式碼，必須依下列方式設定封裝與元件：

建立 ADO.NET 連線管理員，以使用 SqlClient 提供者連線到 AdventureWorks 資料庫。
將新指令碼元件加入資料流程設計師介面，並將它設定為來源。
開啟指令碼轉換編輯器。在 [輸入及輸出] 頁面上，以更具描述性的名稱重新命名預設輸出，例如 MyAddressOutput，以及新增和設定兩個輸出資料行：AddressID 和 City。

注意

務必將 City 輸出資料行的資料類型變更為 DT_WSTR。
在 [連線管理員] 頁面上，新增或建立 ADO.NET 連線管理員，並指定一個名稱 (例如 MyADONETConnection)。
在 [指令碼] 頁面上，按一下 [編輯指令碼] ，並輸入以下指令碼。然後關閉指令碼開發環境以及 [指令碼轉換編輯器] 。
建立和設定目的地元件，例如 SQL Server 目的地，或是使用指令碼元件建立目的地中所示範需要 AddressID 和 City 資料行的範例目的地元件。然後將來源元件連接到目的地 (您不需要進行任何轉換，就可以直接將來源連線到目的地)。您可以在 AdventureWorks 資料庫中執行下列 Transact-SQL 命令，來建立目的地資料表：
```
CREATE TABLE [Person].[Address2]([AddressID] [int] NOT NULL,  
    [City] [nvarchar](30) NOT NULL)  
```

執行範例。

Imports System.Data.SqlClient  
...  
Public Class ScriptMain  
    Inherits UserComponent  

    Dim connMgr As IDTSConnectionManager100  
    Dim sqlConn As SqlConnection  
    Dim sqlReader As SqlDataReader  

    Public Overrides Sub AcquireConnections(ByVal Transaction As Object)  

        connMgr = Me.Connections.MyADONETConnection  
        sqlConn = CType(connMgr.AcquireConnection(Nothing), SqlConnection)  

    End Sub  

    Public Overrides Sub PreExecute()  

        Dim cmd As New SqlCommand("SELECT AddressID, City, StateProvinceID FROM Person.Address", sqlConn)  
        sqlReader = cmd.ExecuteReader  

    End Sub  

    Public Overrides Sub CreateNewOutputRows()  

        Do While sqlReader.Read  
            With MyAddressOutputBuffer  
                .AddRow()  
                .AddressID = sqlReader.GetInt32(0)  
                .City = sqlReader.GetString(1)  
            End With  
        Loop  

    End Sub  

    Public Overrides Sub PostExecute()  

        sqlReader.Close()  

    End Sub  

    Public Overrides Sub ReleaseConnections()  

        connMgr.ReleaseConnection(sqlConn)  

    End Sub  

End Class

using System.Data.SqlClient;  
public class ScriptMain:  
    UserComponent  

{  
    IDTSConnectionManager100 connMgr;  
    SqlConnection sqlConn;  
    SqlDataReader sqlReader;  

    public override void AcquireConnections(object Transaction)  
    {  
        connMgr = this.Connections.MyADONETConnection;  
        sqlConn = (SqlConnection)connMgr.AcquireConnection(null);  

    }  

    public override void PreExecute()  
    {  

        SqlCommand cmd = new SqlCommand("SELECT AddressID, City, StateProvinceID FROM Person.Address", sqlConn);  
        sqlReader = cmd.ExecuteReader();  

    }  

    public override void CreateNewOutputRows()  
    {  

        while (sqlReader.Read())  
        {  
            {  
                MyAddressOutputBuffer.AddRow();  
                MyAddressOutputBuffer.AddressID = sqlReader.GetInt32(0);  
                MyAddressOutputBuffer.City = sqlReader.GetString(1);  
            }  
        }  

    }  

    public override void PostExecute()  
    {  

        sqlReader.Close();  

    }  

    public override void ReleaseConnections()  
    {  

        connMgr.ReleaseConnection(sqlConn);  

    }  

}

一般檔案來源範例

這個範例示範一個來源元件，它使用現有的一般檔案連接管理員，從一般檔案將資料載入資料流程。從 SQL Server 匯出一般檔案來源資料，即會建立該資料。