Erstellen einer Quelle mit der Skriptkomponente

Artikel
05/23/2023

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

Quellkomponenten dienen im Datenfluss eines Integration Services-Pakets dazu, Daten aus einer Datenquelle zu laden, um sie an Downstreamtransformationen und -ziele zu übergeben. Gewöhnlich stellen Sie über einen vorhandenen Verbindungs-Manager eine Verbindung mit der Datenquelle her.

Eine Übersicht der Skriptkomponenten finden Sie unter Extending the Data Flow with the Script Component (Erweitern des Datenflusses mit der Skriptkomponente).

Die Skriptkomponente und der Infrastrukturcode, den sie generieren, erleichtern Ihnen die Entwicklung benutzerdefinierter Datenflusskomponenten deutlich. Um die Funktionsweise der Skriptkomponente zu verstehen, kann es jedoch hilfreich sein, sich mit den Schritten, die bei der Entwicklung einer benutzerdefinierten Datenflusskomponente durchlaufen werden, vertraut zu machen. Weitere Informationen finden Sie im Abschnitt Developing a Custom Data Flow Component (Entwickeln einer benutzerdefinierten Datenflusskomponente). Beachten Sie dabei insbesondere das Thema Developing a Custom Source Component (Entwickeln einer benutzerdefinierten Quellkomponente).

Erste Schritte mit einer Quellkomponente

Wenn Sie im Bereich Datenfluss des SSIS-Designers eine Skriptkomponente hinzufügen, wird das Dialogfeld Skriptkomponententyp auswählen geöffnet, und Sie werden zur Auswahl eines Quell-, Ziel- oder Transformationsskripts aufgefordert. Klicken Sie in diesem Dialogfeld auf Quelle.

Konfigurieren einer Quellkomponente im Metadatenentwurfsmodus

Nachdem Sie die Erstellung einer Quellkomponente ausgewählt haben, konfigurieren Sie die Komponente mit dem Transformations-Editor für Skripterstellung. Weitere Informationen finden Sie unter Configuring the Script Component in the Script Component Editor (Konfigurieren der Skriptkomponente im Skriptkomponenten-Editor).

Eine Datenflussquellkomponente verfügt über keine Eingaben und unterstützt eine oder mehrere Ausgaben. Die Konfiguration der Ausgaben für die Komponente ist einer der Schritte, den Sie mithilfe des Transformations-Editors für Skripterstellung im Metadatenentwurfsmodus abschließen müssen, bevor Sie das benutzerdefinierte Skript schreiben.

Sie können zudem die Skriptsprache über die ScriptLanguage-Eigenschaft auf der Seite Skript im Transformations-Editor für Skripterstellung festlegen.

Hinweis

Verwenden Sie im Dialogfeld Optionen auf der Seite Allgemein die Option Skriptsprache, um die Standardskriptsprache für Skriptkomponenten und Skripttasks festzulegen. Weitere Informationen finden Sie unter General Page.

Hinzufügen von Verbindungs-Managern

Eine Quellkomponente verwendet normalerweise einen vorhandenen Verbindungs-Manager zum Herstellen einer Verbindung mit der Datenquelle, aus der Daten in den Datenfluss geladen werden. Klicken Sie im Transformations-Editor für Skripterstellung auf der Seite Verbindungs-Manager auf Hinzufügen, um den passenden Verbindungs-Manager hinzuzufügen.

Ein Verbindungs-Manager ist jedoch nur eine praktische Einheit, die Daten kapselt und speichert, die sie benötigt, um eine Verbindung mit einer bestimmten Art von Datenquelle herzustellen. Sie müssen, um Daten zu laden und zu speichern sowie möglicherweise auch um eine Verbindung mit der Datenquelle herzustellen und diese zu beenden, eigenen benutzerdefinierten Code schreiben.

Allgemeine Informationen zum Verwenden von Verbindungs-Managern mit der Skriptkomponente finden Sie unter Connecting to Data Sources in the Script Component (Herstellen einer Verbindung mit Datenquellen in der Skriptkomponente).

Weitere Informationen über die Seite Verbindungs-Manager im Transformations-Editor für Skripterstellung finden Sie unter Transformations-Editor für Skripterstellung (Seite „Verbindungs-Manager“).

Konfigurieren von Ausgaben und Ausgabespalten

Eine Quellkomponente verfügt über keine Eingaben und unterstützt eine oder mehrere Ausgaben. Auf der Seite Eingaben und Ausgaben im Transformations-Editor für Skripterstellung wurde standardmäßig eine Ausgabe, jedoch keine Ausgabespalten erstellt. Auf dieser Seite des Editors haben Sie die Möglichkeit, die folgenden Elemente zu konfigurieren.

Sie müssen Ausgabespalten für jede Ausgabe manuell hinzufügen und konfigurieren. Wählen Sie den Ausgabespaltenordner für die jeweilige Ausgabe aus, und verwalten Sie anschließend die Ausgabespalten für alle Ausgaben der Quellkomponente mithilfe der Schaltflächen Spalte hinzufügen und Spalte entfernen. Die Namen, die Sie den Ausgabespalten hier zuweisen, verwenden Sie später mithilfe der typisierten Accessoreigenschaften, die im automatisch generierten Code erstellt wurden, für Verweise im Skript.
Sie haben die Möglichkeit, eine oder mehrere zusätzliche Ausgaben zu erstellen, beispielsweise eine simulierte Fehlerausgabe für Zeilen, die unerwartete Werte aufweisen. Verwenden Sie die Schaltflächen Ausgabe hinzufügen und Ausgabe entfernen, um die Ausgaben der Quellkomponente zu verwalten. Alle Eingabezeilen werden an alle verfügbaren Ausgaben weitergeleitet, außer Sie legen einen identischen Wert ungleich Null für die ExclusionGroup-Eigenschaft der Ausgaben fest, bei denen Sie jede Zeile nur an eine der Ausgaben weiterleiten möchten, die denselben ExclusionGroup-Wert aufweisen. Der spezifische ganzzahlige Wert, den Sie auswählen, um ExclusionGroup zu kennzeichnen, ist nicht von Bedeutung.

Hinweis

Sie können auch einen Wert ungleich 0 (null) für die ExclusionGroup-Eigenschaft für eine einzelne Ausgabe verwenden, wenn Sie nicht alle Zeilen ausgeben möchten. In diesem Fall müssen Sie jedoch für alle Zeilen, die an die Ausgabe gesendet werden sollen, explizit die Methode DirectRowTo<outputbuffer> aufrufen.
Sie können allen Ausgaben einen Anzeigenamen zuweisen. Sie verwenden die Namen der Ausgaben in Ihrem Skript später für Verweise mithilfe der typisierten Accessoreigenschaften, die im automatisch generierten Code erstellt wurden.
Üblicherweise besitzen mehrere Ausgaben in derselben ExclusionGroup die gleichen Ausgabespalten. Falls Sie eine simulierte Fehlerausgabe erstellen, sollten Sie jedoch mehrere Spalten hinzufügen, um Fehlerinformationen zu speichern. Informationen dazu, wie die Datenfluss-Engine Fehlerzeilen verarbeitet, finden Sie unter Using Error Outputs in a Data Flow Component (Verwenden von Fehlerausgaben in einer Datenflusskomponente). In der Skriptkomponente müssen Sie hingegen eigenen Code schreiben, um geeignete Fehlerinformationen für die zusätzlichen Spalten zu erhalten. Weitere Informationen finden Sie unter Simulating an Error Output for the Script Component (Simulieren einer Fehlerausgabe für die Skriptkomponente).

Weitere Informationen über die Seite Eingaben und Ausgaben im Transformations-Editor für Skripterstellung finden Sie unter Script Transformation Editor (Inputs and Outputs Page) (Transformations-Editor für Skripterstellung (Seite „Eingaben und Ausgaben“)).

Hinzufügen von Variablen

Wenn Sie die Werte von vorhandenen Variablen in Ihrem Skript verwenden möchten, können Sie diese in den Eigenschaftsfeldern ReadOnlyVariables und ReadWriteVariables auf der Seite Skript im Transformations-Editor für Skripterstellung hinzufügen.

Wenn Sie mehrere Variablen in die Eigenschaftenfelder eingeben, trennen Sie die Variablennamen durch Kommas. Sie können auch mehrere Variablen auswählen, indem Sie auf die Schaltfläche mit den Auslassungspunkten ( … ) neben den Eigenschaftenfeldern für ReadOnlyVariables und ReadWriteVariables klicken und dann die Variablen im Dialogfeld Variablen auswählen festlegen.

Allgemeine Informationen über das Verwenden von Variablen mit der Skriptkomponente finden Sie unter Using Variables in the Script Component (Verwenden von Variablen in der Skriptkomponente).

Weitere Informationen über die Seite Skript im Transformations-Editor für Skripterstellung finden Sie unter Transformations-Editor für Skripterstellung (Seite „Skript“).

Schreiben einer Quellkomponente im Codeentwurfsmodus

Nachdem Sie die Metadaten für Ihre Komponente konfiguriert haben, öffnen Sie die IDE der Microsoft Visual Studio-Tools für Anwendungen (VSTA), um das benutzerdefinierte Skript zu schreiben. Klicken Sie im Transformations-Editor für Skripterstellung auf der Seite Skript auf Skript bearbeiten, um VSTA zu öffnen. Abhängig von der Skriptsprache, die für die Eigenschaft ScriptLanguage ausgewählt ist, können Sie das Skript entweder in Microsoft Visual Basic oder in Microsoft Visual C# schreiben.

Wichtige Informationen, die alle Arten von Komponenten betreffen, die mithilfe der Skriptkomponente erstellt wurden, finden Sie unter Coding and Debugging the Script Component (Codieren und Debuggen der Skriptkomponente).

Grundlegendes zum automatisch generierten Code

Wenn Sie nach der Erstellung und Konfiguration einer Quellkomponente die VSTA-IDE öffnen, wird die bearbeitbare ScriptMain-Klasse im Code-Editor angezeigt. Sie schreiben den benutzerdefinierten Code in der ScriptMain-Klasse.

Die ScriptMain-Klasse enthält einen Stub für die CreateNewOutputRows-Methode. CreateNewOutputRows ist die wichtigste Methode in einer Quellkomponente.

Wenn Sie das Fenster Projektexplorer in VSTA öffnen, können Sie sehen, dass die Skriptkomponente auch schreibgeschützte BufferWrapper- und ComponentWrapper-Projektelemente generiert hat. Die ScriptMain-Klasse erbt von der UserComponent-Klasse im ComponentWrapper-Projektelement.

Zur Laufzeit ruft die Datenfluss-Engine die PrimeOutput-Methode in der UserComponent-Klasse auf, die die PrimeOutput-Methode der übergeordneten ScriptComponent-Klasse überschreibt. Die PrimeOutput-Methode ruft anschließend die folgenden Methoden auf:

Die CreateNewOutputRows-Methode, die Sie in ScriptMain überschreiben können, um den Ausgabepuffern, die zunächst leer sind, Zeilen der Datenquelle hinzuzufügen.
Die FinishOutputs-Methode, die standardmäßig leer ist. Überschreiben Sie diese Methode in ScriptMain, um Verarbeitungsschritte auszuführen, die zum Abschluss der Ausgabe erforderlich sind.
Die private MarkOutputsAsFinished-Methode, die die SetEndOfRowset-Methode der übergeordneten ScriptBuffer-Klasse aufruft, um die Datenfluss-Engine über die Fertigstellung der Ausgabe in Kenntnis zu setzen. Sie müssen SetEndOfRowset nicht explizit im Code aufrufen.

Schreiben von benutzerdefiniertem Code

Sie können Skripts in den folgenden Methoden schreiben, die in der ScriptMain-Klasse zur Verfügung stehen, um die Erstellung einer benutzerdefinierten Quellkomponente abzuschließen.

Überschreiben Sie die AcquireConnections-Methode, um eine Verbindung mit der externen Datenquelle herzustellen. Extrahieren Sie das Verbindungsobjekt bzw. die erforderlichen Verbindungsinformationen vom Verbindungs-Manager.
Überschreiben Sie die PreExecute-Methode, um Daten zu laden, falls Sie alle Quelldaten gleichzeitig laden können. Sie können beispielsweise einen SqlCommand für eine ADO.NET-Verbindung mit einer SQL Server-Datenbank ausführen und alle Quelldaten gleichzeitig in einen SqlDataReader laden. Falls Sie die Quelldaten zeilenweise laden müssen (z.B. beim Lesen einer Textdatei), können Sie die Daten beim Durchlaufen der Zeilen in CreateNewOutputRows laden.
Mithilfe der überschriebenen CreateNewOutputRows-Methode können Sie leere Ausgabepuffer um neue Zeilen ergänzen und die Werte der einzelnen Spalten den neuen Ausgabezeilen hinzufügen. Verwenden Sie die AddRow-Methode der einzelnen Ausgabepuffer, um leere neue Zeilen hinzuzufügen, und legen Sie anschließend die Werte der einzelnen Spalten fest. Üblicherweise kopieren Sie die Werte aus den Spalten, die aus der externen Quelle geladen werden.
Überschreiben Sie die PostExecute-Methode, um die Verarbeitung der Daten abzuschließen. Sie können beispielsweise den SqlDataReader schließen, mit dem Sie die Daten geladen haben.
Überschreiben Sie bei Bedarf die ReleaseConnections-Methode, um die Verbindung mit der externen Datenquelle zu trennen.

Beispiele

In den folgenden Beispielen wird der benutzerdefinierte Code veranschaulicht, der in der ScriptMain-Klasse zur Erstellung einer Quellkomponente erforderlich ist.

Hinweis

In diesen Beispielen werden die erste und die vierte Spalte der Tabelle Person.Address in der Beispieldatenbank AdventureWorks verwendet, und die Spalten intAddressID und nvarchar(30)City werden durch den Datenfluss weitergeleitet. Die gleichen Daten werden in den Quellen-, Transformations- und Zielbeispielen in diesem Abschnitt verwendet. Zusätzliche Voraussetzungen und Annahmen werden für jedes Beispiel dokumentiert.

ADO.NET-Quellenbeispiel

Dieses Beispiel zeigt eine Quellkomponente, die einen vorhandenen ADO.NET-Verbindungs-Manager zum Laden von Daten aus einer SQL Server-Tabelle in den Datenfluss verwendet.

Wenn Sie den Beispielcode ausführen möchten, müssen Sie das Paket und die Komponente folgendermaßen konfigurieren:

Erstellen Sie einen ADO.NET-Verbindungs-Manager, der mithilfe des SqlClient-Anbieters eine Verbindung mit der AdventureWorks-Datenbank herstellt.
Fügen Sie der Datenfluss-Designeroberfläche eine neue Skriptkomponente hinzu, und konfigurieren Sie sie als Quelle.
Öffnen Sie den Transformations-Editor für Skripterstellung. Geben Sie auf der Seite Eingaben und Ausgaben der Standardausgabe einen aussagekräftigeren Namen ein, z.B. MyAddressOutput. Fügen Sie die zwei Ausgabespalten AddressID und City hinzu, und konfigurieren Sie diese.

Hinweis

Achten Sie darauf, den Datentyp der City-Ausgabespalte in DT_WSTR zu ändern.
Fügen Sie auf der Seite Verbindungs-Manager den ADO.NET-Verbindungs-Manager hinzu, oder erstellen Sie diesen, und geben Sie ihm einen Namen wie z. B. MeineADONETVerbindung.
Klicken Sie auf der Seite Skript auf Skript bearbeiten, und geben Sie das folgende Skript ein. Schließen Sie anschließend die Skriptentwicklungsumgebung und den Transformations-Editor für Skripterstellung.
Erstellen und konfigurieren Sie eine Zielkomponente – z. B. ein SQL Server-Ziel –, oder verwenden Sie die Beispielzielkomponente, die unter Erstellen eines Ziels mit der Skriptkomponente veranschaulicht wird und die Spalten AddressID und City erwartet. Stellen Sie anschließend eine Verbindung der Quellkomponente mit dem Ziel her. (Sie können eine Quelle ohne Transformationen direkt mit einem Ziel verbinden.) Sie können eine Zieltabelle erstellen, indem Sie den folgenden Transact-SQL-Befehl in der AdventureWorks-Datenbank ausführen:
```
CREATE TABLE [Person].[Address2]([AddressID] [int] NOT NULL,  
    [City] [nvarchar](30) NOT NULL)  
```

Führen Sie das Beispiel aus.

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);  

    }  

}

Flatfilequellenbeispiel

Diese Beispiel zeigt eine Quellkomponente, die einen vorhandenen Verbindungs-Manager für Flatfiles zum Laden von Daten aus einer Flatfile in den Datenfluss einsetzt. Die Flatfilequelldaten werden per Export aus SQL Server erstellt.