Codieren und Debuggen des Skripttasks

Gilt für: SQL Server SSIS Integration Runtime in Azure Data Factory

Nach dem Konfigurieren des Skripttasks im Skripttask-Editor schreiben Sie den benutzerdefinierten Code in der Skripttask-Entwicklungsumgebung.

Skripttask-Entwicklungsumgebung

Der Skripttask verwendet Microsoft Visual Studio-Tools für Anwendungen (VSTA) als Entwicklungsumgebung für das Skript selbst.

Skriptcode wird in Microsoft Visual Basic oder Microsoft Visual C# geschrieben. Sie geben die Skriptsprache an, indem Sie die ScriptLanguage-Eigenschaft im Skripttask-Editor festlegen. Falls Sie lieber eine andere Programmiersprache verwenden möchten, können Sie in Ihrer bevorzugten Sprache eine benutzerdefinierte Assembly entwickeln und ihre Funktionen aus dem Code im Skripttask aufrufen.

Das im Skripttask erstellte Skript wird in der Paketdefinition gespeichert. Es gibt keine separate Skriptdatei. Deshalb hat die Verwendung des Skripttasks keinen Einfluss auf die Paketbereitstellung.

Hinweis

Wenn Sie das Paket entwerfen und das Skript debuggen, wird der Skriptcode vorübergehend in eine Projektdatei geschrieben. Da das Speichern vertraulicher Informationen in einer Datei ein Sicherheitsrisiko darstellt, sollte der Skriptcode keine vertraulichen Daten wie Kennwörter enthalten.

Standardmäßig ist Option Strict in der IDE deaktiviert.

Skripttask-Projektstruktur

Wenn Sie das in einem Skripttask enthaltene Skript erstellen oder ändern, öffnet VSTA ein neues leeres Projekt oder erneut das vorhandene Projekt. Die Erstellung dieses VSTA-Projekts wirkt sich nicht auf die Paketbereitstellug aus, da das Projekt in der Paketdatei gespeichert wird. Der Skripttask erstellt keine weiteren Dateien.

Projektelemente und -klassen im Skripttaskprojekt

Standardmäßig umfasst das im VSTA-Projektexplorer-Fenster angezeigte Skripttaskprojekt nur ein Element, nämlich ScriptMain. Das ScriptMain-Element enthält wiederum eine einzelne Klasse, die ebenfalls ScriptMain heißt. Die Codeelemente in der Klasse variieren abhängig davon, welche Programmiersprache Sie für den Skripttask gewählt haben:

• Wenn der Skripttask für die Programmiersprache Visual Basic konfiguriert ist, enthält die ScriptMain-Klasse eine öffentliche Unterroutine namens Main. Die ScriptMain.Main-Unterroutine ist die Methode, die die Laufzeit beim Ausführen des Skripttasks aufruft.

  Standardmäßig enthält die Main-Unterroutine eines neuen Skripts als einzigen Code die Zeile Dts.TaskResult = ScriptResults.Success. Diese Zeile informiert die Laufzeit, dass der Task erfolgreich durchgeführt wurde. Die Dts.TaskResult-Eigenschaft wird im Artikel Zurückgeben von Ergebnissen aus dem Skripttask thematisiert.

• Wenn der Skripttask für die Programmiersprache Visual C# konfiguriert ist, enthält die ScriptMain-Klasse die öffentliche Methode Main. Die Methode wird aufgerufen, wenn der Skripttask ausgeführt wird.

  Standardmäßig enthält die Main-Methode die Zeile Dts.TaskResult = (int)ScriptResults.Success. Diese Zeile informiert die Laufzeit, dass der Task erfolgreich durchgeführt wurde.

Das ScriptMain-Element kann andere Klassen als die ScriptMain-Klasse enthalten. Klassen stehen nur dem Skripttask, in dem sie sich befinden, zur Verfügung.

Standardmäßig enthält das ScriptMain-Projektelement den folgenden automatisch generierten Code. Die Codevorlage bietet auch eine Übersicht über den Skripttask, und zusätzliche Informationen über das Abrufen und Bearbeiten von SSIS-Objekten, z. B. Variablen, Ereignisse und Verbindungen.

' 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;  
        }  
    }  

Zusätzliche Projektelemente im Skripttaskprojekt

Das Skripttaskprojekt kann neben dem Standardelement ScriptMain noch weitere Elemente einschließen. Sie können Klassen, Module und Codedateien zum Projekt hinzufügen. Außerdem können Sie Ordner verwenden, um Elementgruppen zu organisieren. Alle Elemente, die Sie hinzufügen, werden im Paket beibehalten.

Verweise im Skripttaskprojekt

Sie können Verweise auf verwaltete Assemblys hinzufügen, indem Sie im Projektexplorer mit der rechten Maustaste auf das Skripttaskprojekt und anschließend auf Verweis hinzufügen klicken. Weitere Informationen finden Sie unter Verweisen auf andere Assemblys in Skriptlösungen.

Hinweis

Sie können Projektverweise in der VSTA-IDE in der Klassenansicht oder im Projektexplorer anzeigen. Diese Fenster öffnen Sie über das Menü Ansicht. Einen neuen Verweis können Sie über das Menü Projekt, den Projektexplorer oder die Klassenansicht hinzufügen.

Interagieren mit Paketen im Skripttask

Ein Skripttask interagiert mit dem entsprechenden Paket und der Integration Services-Laufzeit über das globale Dts-Objekt, eine Instanz der ScriptObjectModel-Klasse, und ihre Elemente.

Die folgende Tabelle enthält die wichtigsten öffentlichen Elemente der ScriptObjectModel-Klasse, die für den Skripttaskcode über das globale Dts-Objekt verfügbar gemacht wird. In den Themen in diesem Abschnitt wird die Verwendung dieser Elemente detaillierter erläutert.

Member	Zweck
Connections	Bietet Zugriff auf im Paket definierte Verbindungs-Manager.
Events	Liefert eine Ereignisschnittstelle, damit der Skripttask Fehler, Warnungen und Informationsmeldungen auslösen kann.
ExecutionValue	Bietet eine einfache Möglichkeit, ein einzelnes Objekt (zusätzlich zu TaskResult) an die Laufzeit auszugeben, das auch für die Workflowverzweigung verwendet werden kann.
Log	Protokolliert Informationen wie den Taskstatus und die Ergebnisse bei aktivierten Protokollanbietern.
TaskResult	Meldet den Erfolg oder Misserfolg des Tasks.
Transaction	Stellt ggf. die Transaktion bereit, innerhalb derer der Taskcontainer ausgeführt wird.
Variables	Bietet Zugriff auf die Variablen in den Taskeigenschaften ReadOnlyVariables und ReadWriteVariables zur Verwendung im Skript.

Die ScriptObjectModel-Klasse enthält auch einige öffentliche Elemente, die Sie wahrscheinlich nicht verwenden.

Member	BESCHREIBUNG
VariableDispenser	Die Variables-Eigenschaft ermöglicht einen einfacheren Zugriff auf Variablen. Sie können zwar VariableDispenser verwenden, müssen jedoch explizit Methoden aufrufen, um Variablen für das Lesen und Schreiben zu sperren und die Sperre wieder aufzuheben. Der Skripttask erledigt die Sperrsemantik für Sie, wenn Sie die Variables-Eigenschaft verwenden.

Debuggen des Skripttasks

Legen Sie zum Debuggen des Codes im Skripttask mindestens einen Breakpoint fest, und schließen Sie dann die VSTA IDE, um das Paket in SQL Server Data Tools (SSDT) auszuführen. Wenn die Ausführung des Skripttasks beginnt, wird die VSTA IDE erneut geöffnet und der Code schreibgeschützt angezeigt. Nachdem die Ausführung den Breakpoint erreicht hat, können Sie die Variablenwerte untersuchen und den übrigen Code schrittweise durchgehen.

Warnung

Sie können den Skripttask nicht debuggen, wenn Sie das Paket im 64-Bit-Modus ausführen.

Hinweis

Sie müssen das Paket ausführen, um den Skripttask zu debuggen. Wenn Sie nur den einzelnen Task ausführen, werden Breakpoints im Skripttaskcode ignoriert.

Hinweis

Sie können einen Skripttask nicht debuggen, wenn Sie ihn als Teil eines untergeordneten Pakets aus dem Task Paket ausführen ausführen. Breakpoints, die Sie im Skripttask in dem untergeordneten Paket festlegen, werden unter diesen Umständen ignoriert. Sie können das untergeordnete Paket normalerweise debuggen, indem Sie es getrennt ausführen.

Hinweis

Wenn Sie ein Paket debuggen, das mehrere Skripttasks enthält, debuggt der Debugger einen Skripttask. Das System kann einen anderen Skripttask debuggen, wenn der Debugger wie im Fall eines Foreach- oder For-Schleifencontainers abgeschlossen wird.

Externe Ressourcen

• Blogeintrag: VSTA setup and configuration troubles for SSIS 2008 and R2 installations (Probleme mit der VSTA-Einrichtung und -Konfiguration bei SSIS 2008- und R2-Installationen) (auf blogs.msdn.com).

Weitere Informationen

Verweisen auf andere Assemblys in Skriptlösungen
Konfigurieren des Skripttasks im Skripttask-Editor