指令碼工作的程式碼撰寫和偵錯

發行項
05/04/2023

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

在 [指令碼工作編輯器] 中設定指令碼工作之後，於指令碼工作開發環境中撰寫自訂程式碼。

指令碼工作開發環境

指令碼工作使用 Microsoft Visual Studio Tools for Applications (VSTA) 作為指令碼本身的開發環境。

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

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

注意

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

IDE 中預設會停用 Option Strict。

指令碼工作專案結構

當您建立或修改包含在指令碼工作中的指令碼時，VSTA 會開啟空的新專案或是重新開啟現有的專案。這個 VSTA 專案的建立不會影響專案的部署，因為專案是儲存在封裝檔案中；指令碼工作不會建立其他檔案。

指令碼工作專案中的專案項目和類別

顯示在 VSTA [專案總管] 視窗中的指令碼工作專案預設會包含單一項目：ScriptMain。 ScriptMain 項目則會包含單一類別，同樣名為 ScriptMain。類別中的程式碼項目會根據您針對指令碼工作所選取的程式語言而變更。

當為 Visual Basic 程式語言設定指令碼工作時，ScriptMain 類別具有公用副程式：Main。 ScriptMain.Main 副程式是執行階段在您執行指令碼工作時所呼叫的方法。

在新指令碼的 Main 副程式中的唯一程式碼預設是 Dts.TaskResult = ScriptResults.Success 這一行。這行會通知執行階段，工作的作業已成功。從指令碼工作中傳回結果會討論 Dts.TaskResult 屬性。
針對 Visual C# 程式設計語言設定指令碼工作時，ScriptMain 類別具有公用方法 Main。此方法是在指令碼工作執行時呼叫。

Main 方法預設會包含此行：Dts.TaskResult = (int)ScriptResults.Success。這行會通知執行階段，工作的作業已成功。

ScriptMain 項目可以包含 ScriptMain 類別以外的類別。類別僅可供其所在的指令碼工作使用。

ScriptMain 專案項目預設會包含下列自動產生的程式碼。程式碼範本也會提供指令碼工作的概觀，以及有關如何擷取與操作 SSIS 物件 (例如變數、事件與連接) 的其他資訊。

' Microsoft SQL Server Integration Services Script Task  
' Write scripts using Microsoft Visual Basic 2008.  
' The ScriptMain is the entry point class of the script.  
  
Imports System  
Imports System.Data  
Imports System.Math  
Imports Microsoft.SqlServer.Dts.Runtime.VSTAProxy  
  
<System.AddIn.AddIn("ScriptMain", Version:="1.0", Publisher:="", Description:="")> _  
Partial Class ScriptMain  
  
Private Sub ScriptMain_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup  
  
End Sub  
  
Private Sub ScriptMain_Shutdown(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Shutdown  
Try  
' Unlock variables from the read-only and read-write variable collection properties  
If (Dts.Variables.Count <> 0) Then  
Dts.Variables.Unlock()  
End If  
Catch ex As Exception  
        End Try  
End Sub  
  
Enum ScriptResults  
Success = DTSExecResult.Success  
Failure = DTSExecResult.Failure  
End Enum  
  
' The execution engine calls this method when the task executes.  
' To access the object model, use the Dts property. Connections, variables, events,  
' and logging features are available as members of the Dts property as shown in the following examples.  
'  
' To reference a variable, call Dts.Variables("MyCaseSensitiveVariableName").Value  
' To post a log entry, call Dts.Log("This is my log text", 999, Nothing)  
' To fire an event, call Dts.Events.FireInformation(99, "test", "hit the help message", "", 0, True)  
'  
' To use the connections collection use something like the following:  
' ConnectionManager cm = Dts.Connections.Add("OLEDB")  
' cm.ConnectionString = "Data Source=localhost;Initial Catalog=AdventureWorks;Provider=SQLNCLI10;Integrated Security=SSPI;Auto Translate=False;"  
'  
' Before returning from this method, set the value of Dts.TaskResult to indicate success or failure.  
'   
' To open Help, press F1.  
  
Public Sub Main()  
'  
' Add your code here  
'  
Dts.TaskResult = ScriptResults.Success  
End Sub  
  
End Class

/*  
   Microsoft SQL Server Integration Services Script Task  
   Write scripts using Microsoft Visual C# 2008.  
   The ScriptMain is the entry point class of the script.  
*/  
  
using System;  
using System.Data;  
using Microsoft.SqlServer.Dts.Runtime.VSTAProxy;  
using System.Windows.Forms;  
  
namespace ST_1bcfdbad36d94f8ba9f23a10375abe53.csproj  
{  
    [System.AddIn.AddIn("ScriptMain", Version = "1.0", Publisher = "", Description = "")]  
    public partial class ScriptMain  
    {  
        private void ScriptMain_Startup(object sender, EventArgs e)  
        {  
  
        }  
  
        private void ScriptMain_Shutdown(object sender, EventArgs e)  
        {  
            try  
            {  
                // Unlock variables from the read-only and read-write variable collection properties  
                if (Dts.Variables.Count != 0)  
                {  
                    Dts.Variables.Unlock();  
                }  
            }  
            catch  
            {  
            }  
        }  
  
        #region VSTA generated code  
        private void InternalStartup()  
        {  
            this.Startup += new System.EventHandler(ScriptMain_Startup);  
            this.Shutdown += new System.EventHandler(ScriptMain_Shutdown);  
        }  
        enum ScriptResults  
        {  
            Success = DTSExecResult.Success,  
            Failure = DTSExecResult.Failure  
        };  
  
        #endregion  
  
        /*  
The execution engine calls this method when the task executes.  
To access the object model, use the Dts property. Connections, variables, events,  
and logging features are available as members of the Dts property as shown in the following examples.  
  
To reference a variable, call Dts.Variables["MyCaseSensitiveVariableName"].Value;  
To post a log entry, call Dts.Log("This is my log text", 999, null);  
To fire an event, call Dts.Events.FireInformation(99, "test", "hit the help message", "", 0, true);  
  
To use the connections collection use something like the following:  
ConnectionManager cm = Dts.Connections.Add("OLEDB");  
cm.ConnectionString = "Data Source=localhost;Initial Catalog=AdventureWorks;Provider=SQLNCLI10;Integrated Security=SSPI;Auto Translate=False;";  
  
Before returning from this method, set the value of Dts.TaskResult to indicate success or failure.  
  
To open Help, press F1.  
*/  
  
        public void Main()  
        {  
            // TODO: Add your code here  
            Dts.TaskResult = (int)ScriptResults.Success;  
        }  
    }

指令碼工作專案中的其他專案項目

指令碼工作專案可以包含預設 ScriptMain 項目以外的項目。您可以將類別、模組和程式碼檔案加入專案。您也可以使用資料夾來組織項目的群組。所有您加入的項目都會保存在封裝內。

指令碼工作專案中的參考

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

注意

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

與指令碼工作中的封裝互動

指令碼工作使用全域 Dts 物件 (即 ScriptObjectModel 類別的執行個體) 和其成員，以與包含套件和 Integration Services 執行階段互動。

下表列出 ScriptObjectModel 類別的主要公用成員，這個類別是透過全域 Dts 物件向指令碼工作程式碼公開。本節中的主題會更詳細地討論這些成員的使用。

member	目的
Connections	提供定義在封裝中的連接管理員之存取權。
Events	提供事件介面，讓指令碼工作引發錯誤、警告及參考訊息。
ExecutionValue	提供簡單的方法將 TaskResult 以外的單一物件傳回執行階段，也可用於工作流程分支。
Log	將工作進度與結果等資訊記錄到啟用的記錄提供者。
TaskResult	報告工作的成功或失敗。
Transaction	提供工作的容器執行範圍內的交易 (如果有的話)。
Variables	提供 ReadOnlyVariables 和 ReadWriteVariables 工作屬性中所列的變數存取權，以在指令碼中使用。

ScriptObjectModel 類別也包含一些您可能不會使用的公用成員。

member	描述
VariableDispenser	Variables 屬性會提供更為便利的變數存取方式。雖然您可以使用 VariableDispenser，但是必須明確地呼叫方法以鎖定和解除鎖定要讀取和寫入的變數。當您使用 Variables 屬性時，指令碼工作會為您處理鎖定語意。

偵錯指令碼工作

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

警告

您無法在以 64 位元模式執行套件時，為指令碼工作偵錯。

注意

您必須執行封裝以進入指令碼工作中偵錯。如果您只執行個別的工作，則會忽略指令碼工作程式碼內的中斷點。

注意

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

注意

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

外部資源

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

另請參閱

參考指令碼解決方案中的其他組件
 在指令碼工作編輯器設定指令碼工作

共用方式為