指令碼元件的程式碼撰寫和偵錯

發行項
03/06/2017

在 SSIS 設計師中，指令碼元件有中繼資料設計與程式碼設計兩種模式。當您開啟 [指令碼轉換編輯器] 時，元件就會進入中繼資料設計模式，您可在其中設定中繼資料及元件屬性。在您於中繼資料設計模式設定好指令碼元件的屬性和輸入及輸出後，就可以切換到程式碼設計模式編寫自訂的指令碼。如需中繼資料設計模式和程式碼設計模式的詳細資訊，請參閱在指令碼元件編輯器中設定指令碼元件。

在程式碼設計模式中撰寫指令碼

指令碼元件開發環境

若要撰寫指令碼，請在 [指令碼轉換編輯器] 的 [指令碼] 頁面上按一下 [編輯指令碼] 以開啟 Microsoft Visual Studio Tools for Applications (VSTA) IDE。 VSTA IDE 包含 Visual Studio .NET 環境的所有標準功能，例如色彩編碼的 Visual Studio 編輯器、IntelliSense 和物件瀏覽器。

指令碼程式碼是以 Microsoft Visual Basic 或 Microsoft Visual C# 撰寫。您可以在 [指令碼轉換編輯器] 中，藉由設定 ScriptLanguage 屬性來指定指令碼語言。如果想要使用其他的程式語言，可以用您所選的語言開發自訂組件，然後在指令碼元件中，從程式碼呼叫其功能。

您在指令碼元件中建立的指令碼會儲存在封裝定義中，而沒有個別的指令碼檔案。因此，使用指令碼元件並不會影響封裝部署。

注意

在您設計封裝時，指令碼會暫時寫入專案檔。因為將敏感性資訊儲存在檔案中會造成潛在的安全性風險，所以我們建議您不要在指令碼中包含密碼之類的敏感性資訊。

根據預設， Option Strict 會在 IDE 中停用。

指令碼元件專案結構

指令碼元件的優點在於可以產生基礎結構程式碼，所以能夠減少所必須撰寫的程式碼量。這項功能的前提是，輸入和輸出及其資料行和屬性都是固定的，而且已預先知道。因此，對元件中繼資料所進行的任何後續變更，都可能會造成已撰寫的程式碼無效。這會在封裝執行期間造成編譯錯誤。

指令碼元件專案中的專案項目和類別

當您切換到程式碼設計模式時，VSTA IDE 會開啟並顯示 ScriptMain 項目專案。項目 ScriptMain 專案包含可 ScriptMain 編輯的類別，做為腳本的進入點，以及撰寫程式代碼的位置。類別中的程式碼項目會根據您針對指令碼工作所選取的程式語言而變更。

指令碼專案包含兩個額外的、自動產生的唯讀專案項目：

專案 ComponentWrapper 專案包含三個類別：
- 類別 UserComponent ，繼承自 ScriptComponent ，並包含您將用來處理數據和與封裝互動的方法和屬性。 ScriptMain 類別繼承自 UserComponent 類別。
- Connections集合類別，其中包含文稿轉換編輯器之 [連線管理員] 頁面上所選取之連接的參考。
- Variables集合類別，其中包含文稿轉換編輯器 [腳本] 頁面上輸入之和 ReadWriteVariables 屬性中ReadOnlyVariable輸入之變數的參考。
BufferWrapper項目專案包含類別，繼承自 ScriptBuffer 文稿轉換編輯器之 [輸入與輸出] 頁面上所設定的每個輸入和輸出。這其中每個類別所包含的類型存取子屬性，都與設定的輸入和輸出資料行以及包含這些資料行的資料流緩衝區相對應。

如需如何使用這些物件、方法和屬性的資訊，請參閱了解指令碼元件物件模型。如需如何在特定的指令碼元件類型中使用這些類別的方法和屬性的資訊，請參閱其他指令碼元件範例。範例主題也包含完整的程式碼範例。

當您將文本元件設定為轉換時， ScriptMain 專案專案會包含下列自動產生的程式代碼。程式碼範本也會提供指令碼元件的概觀，以及有關如何擷取與操作 SSIS 物件 (例如變數、事件與連接) 的其他資訊。

' Microsoft SQL Server Integration Services Script Component
' Write scripts using Microsoft Visual Basic 2008.
' ScriptMain is the entry point class of the script.

Imports System
Imports System.Data
Imports System.Math
Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper
Imports Microsoft.SqlServer.Dts.Runtime.Wrapper

<Microsoft.SqlServer.Dts.Pipeline.SSISScriptComponentEntryPointAttribute> _
<CLSCompliant(False)> _
Public Class ScriptMain
    Inherits UserComponent

    Public Overrides Sub PreExecute()
        MyBase.PreExecute()
        '
        ' Add your code here for preprocessing or remove if not needed
        '
    End Sub

    Public Overrides Sub PostExecute()
        MyBase.PostExecute()
        '
        ' Add your code here for postprocessing or remove if not needed
        ' You can set read/write variables here, for example:
        ' Me.Variables.MyIntVar = 100
        '
    End Sub

    Public Overrides Sub Input0_ProcessInputRow(ByVal Row As Input0Buffer)
        '
        ' Add your code here
        '
    End Sub

End Class

/* Microsoft SQL Server Integration Services user script component
*  Write scripts using Microsoft Visual C# 2008.
*  ScriptMain is the entry point class of the script.*/

using System;
using System.Data;
using Microsoft.SqlServer.Dts.Pipeline.Wrapper;
using Microsoft.SqlServer.Dts.Runtime.Wrapper;

[Microsoft.SqlServer.Dts.Pipeline.SSISScriptComponentEntryPointAttribute]
public class ScriptMain : UserComponent
{

    public override void PreExecute()
    {
        base.PreExecute();
        /*
          Add your code here for preprocessing or remove if not needed
        */
    }

    public override void PostExecute()
    {
        base.PostExecute();
        /*
          Add your code here for postprocessing or remove if not needed
          You can set read/write variables here, for example:
          Variables.MyIntVar = 100
        */
    }

    public override void Input0_ProcessInputRow(Input0Buffer Row)
    {
        /*
          Add your code here
        */
    }

}

指令碼元件專案中的其他專案項目

文本元件專案可以包含預設 ScriptMain 專案以外的專案。您可以在專案中加入類別、模組、程式碼檔案和資料夾，也可以使用資料夾來整理項目群組。

所有您加入的項目都會保存在封裝內。

指令碼元件專案中的參考

您可以在 [專案總管] 中以滑鼠右鍵按一下「指令碼」工作專案，再按 [新增參考] ，新增 Managed 組件的參考。如需詳細資訊，請參閱參考指令碼解決方案中的其他組件。

注意

您可以在 VSTA IDE 中的 [類別檢視] 或 [專案總管] 中，檢視專案參考。您可以從 [檢視] 功能表中開啟任一個視窗。您可以從 [專案] 功能表、[專案總管] 或 [類別檢視] 新增參考。

與指令碼元件中的封裝互動

在指令碼元件中撰寫的自訂指令碼可以在自動產生的基底類別中，透過強型別 (Strongly-Typed) 的存取子從包含的封裝存取及使用變數和連接管理員。不過，如果想要在指令碼中使用變數和連接管理員，則必須先設定變數和連接管理員，才能進入程式碼設計模式。您也可以從指令碼元件程式碼引發事件和執行記錄。

指令碼元件專案中自動產生的專案項目會提供下列物件、方法和屬性，可用於與封裝互動。

封裝功能	存取方法
變數	使用項目專案中集合類別中的具名和具型別存取子屬性`Variables`，透過類別的 `ScriptMain` 屬性公開`Variables`。`ComponentWrapper` 方法 `PreExecute` 只能存取唯讀變數。方法 `PostExecute` 可以存取唯讀和讀取/寫入變數。
連線	使用項目專案中集合類別中的具名和具型別存取子屬性`Connections`，透過類別的 `ScriptMain` 屬性公開`Connections`。`ComponentWrapper`
事件	使用 ComponentMetaData 類別的 `ScriptMain` 屬性和介面的 IDTSComponentMetaData100 Fire<X> 方法引發事件。
記錄	使用 Log 類別的 `ScriptMain` 方法執行記錄。

偵錯指令碼元件

若要在指令碼元件中對程式碼進行偵錯，請在程式碼中設定至少一個中斷點，然後關閉 VSTA IDE 以便在 SQL Server Data Tools (SSDT) 中執行套件。當封裝執行進入指令碼元件時，VSTA IDE 會在唯讀模式下重新開啟並顯示您的程式碼。在執行到達中斷點之後，您可以檢查變數值並逐步完成其餘的程式碼。

注意

當您在執行封裝工作的子封裝內執行指令碼元件時，將無法偵錯指令碼元件。在這些情況下，系統會略過您在子封裝的指令碼元件中設定的中斷點。您可以分開執行子封裝，以利正常地偵錯子封裝。

注意

當您偵錯包含多個指令碼元件的封裝時，偵錯工具會偵錯其中一個指令碼元件。如果偵錯工具完成，系統就可以偵錯另一個指令碼元件，如同 Foreach 迴圈或 For 迴圈容器的情況。

您也可以使用下列方法來監視指令碼元件的執行：

中斷執行，並使用 MessageBox.Show System.Windows.Forms 命名空間中的方法顯示強制回應訊息。 (請在完成偵錯程序之後移除此程式碼)。
引發資訊訊息、警告和錯誤的事件。 FireInformation、FireWarning 和 FireError 方法會在 Visual Studio [輸出] 視窗中顯示事件描述。不過，FireProgress 方法、Console.Write 方法和 Console.WriteLine 方法不會在 [輸出] 視窗中顯示任何資訊。 FireProgress 事件的訊息會顯示在 SSIS 設計師的 [進度] 索引標籤上。如需詳細資訊，請參閱在指令碼元件中引發事件。
將事件或使用者定義的訊息記錄到啟用的記錄提供者。如需詳細資訊，請參閱在指令碼元件中記錄。

如果只需要檢查設定為來源或轉換的指令碼元件的輸出，而不將資料儲存到目的地，可以使用資料列計數轉換停止資料流程，並將資料檢視器附加到指令碼元件的輸出。如需資料檢視器的資訊，請參閱偵錯資料流程。

本節內容

如需有關撰寫指令碼元件程式碼的詳細資訊，請參閱此章節中的下列主題：

瞭解文本元件物件模型說明如何使用腳本元件中可用的物件、方法和屬性。

在文稿解決方案中參考其他元件說明如何在腳本元件中參考 .NET Framework 類別庫的物件。

模擬文稿元件的錯誤輸出說明如何模擬腳本元件處理期間引發錯誤之數據列的錯誤輸出。

外部資源

blogs.msdn.com 上的部落格文章：VSTA setup and configuration troubles for SSIS 2008 and R2 installations (SSIS 2008 和 R2 安裝的 VSTA 安裝與設定問題)。

Integration Services 圖示（小型） 使用 Integration Services 保持最新狀態
如需來自Microsoft的最新下載、文章、範例和影片，以及來自社群的所選解決方案，請流覽 MSDN 上的 Integration Services 頁面：

流覽 MSDN 上的 Integration Services 頁面

如需這些更新的自動通知，請訂閱頁面上可用的 RSS 摘要。

另請參閱

在指令碼元件編輯器中設定指令碼元件

共用方式為