Erstellen einer synchronen Transformation mit der Skriptkomponente

Gilt für:yes SQL Server (alle unterstützten Versionen) yes SSIS Integration Runtime in Azure Data Factory

Sie verwenden eine Transformationskomponente im Datenfluss eines Integration Services-Pakets, um Daten zu ändern und zu analysieren, während sie von der Quelle an das Ziel übergeht. Eine Transformation mit synchronen Ausgaben verarbeitet jede eingegebene Zeile, während sie die Komponente durchläuft. Eine Transformation mit asynchronen Ausgaben wartet, bis alle Eingabezeilen empfangen wurden, bevor die Verarbeitung abgeschlossen wird. In diesem Thema wird eine synchrone Transformation erläutert. Informationen zur asynchronen Transformation finden Sie unter Creating an Asynchronous Transformation with the Script Component (Erstellen einer asynchronen Transformationen mit der Skriptkomponente). Weitere Informationen zu den Unterschieden zwischen synchronen und asynchronen Komponenten finden Sie unter Grundlegendes zu synchronen und asynchronen Transformationen.

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 im Abschnitt Developing a Custom Data Flow Component (Entwickeln einer benutzerdefinierten Datenflusskomponente) beschriebenen Schritten vertraut zu machen, die Sie bei der Entwicklung einer benutzerdefinierten Datenflusskomponente durchführen müssen. Sehen Sie sich dabei insbesondere den Schritt Developing a Custom Transformation Component with Synchronous Outputs (Entwickeln einer benutzerdefinierten Transformationskomponente mit synchronen Ausgaben) an.

Erste Schritte mit einer synchronen Transformationskomponente

Wenn Sie dem Bereich Daten Flow des SSIS-Designers eine Skriptkomponente hinzufügen, wird das Dialogfeld Skriptkomponententyp auswählen geöffnet, und Sie werden aufgefordert, einen Quell-, Ziel- oder Transformationskomponententyp auszuwählen. Wählen Sie in diesem Dialogfeld die Option Transformation aus.

Konfigurieren einer synchronen Transformationskomponente im Metadatenentwurfsmodus

Nachdem Sie die Option zur Erstellung einer Transformationskomponente 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).

Zum Bestimmen der Skriptsprache für die Skriptkomponente wird die ScriptLanguage-Eigenschaft auf der Seite Skript des Transformations-Editors für Skripterstellung festgelegt.

Hinweis

Verwenden Sie im Dialogfeld Optionen auf der Seite Allgemein die Option Skriptsprache, um die Standardskriptsprache für die Skriptkomponente festzulegen. Weitere Informationen finden Sie unter General Page (Allgemeines).

Eine Datenfluss-Transformationskomponente verfügt über eine Eingabe und unterstützt mindestens eine Ausgabe. Die Konfiguration der Eingabe und der Ausgaben für die Komponente ist einer der Schritte, die Sie mithilfe des Transformations-Editors für Skripterstellung im Metadatenentwurfsmodus ausführen müssen, bevor Sie das benutzerdefinierte Skript schreiben.

Konfigurieren von Eingabespalten

Eine Transformationskomponente verfügt über eine Eingabe.

Die Spaltenliste auf der Seite Eingabespalten im Transformations-Editor für Skripterstellung zeigt die von der Ausgabe der Upstreamkomponente im Datenfluss verfügbaren Spalten an. Markieren Sie die Spalten, die Sie transformieren oder durchlaufen möchten. Markieren Sie alle Spalten, die Sie an Ort und Stelle transformieren möchten, als Lesen/Schreiben.

Weitere Informationen zur Seite Eingabespalten des Transformations-Editors für Skripts finden Sie unter Transformations-Editor für Skripts (Seite Eingabespalten).

Konfigurieren von Eingaben, Ausgaben und Ausgabespalten

Eine Transformationskomponente unterstützt eine oder mehrere Ausgaben.

Auf der Seite Eingaben und Ausgaben im Transformations-Editor für Skripterstellung können Sie erkennen, dass eine Ausgabe erstellt wurde. Spalten sind in der Ausgabe hingegen nicht vorhanden. Auf dieser Seite des Editors haben Sie die Möglichkeit, die folgenden Elemente zu konfigurieren.

  • Erstellen Sie eine oder mehrere zusätzliche Ausgaben, 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 synchronen Transformationskomponente zu verwalten. Alle Eingabezeilen werden an alle verfügbaren Ausgaben weitergeleitet, außer Sie geben an, dass jede Zeile nur an eine der Ausgaben weitergeleitet werden soll. Die Umleitung von Zahlen wird durch das Angeben eines ganzzahligen Werts ungleich 0 (null) für die ExclusionGroup-Eigenschaft der Ausgaben erreicht. Der für die ExclusionGroup-Eigenschaft eingegebene spezifische ganzzahlige Wert zum Identifizieren der Ausgaben ist nicht von Bedeutung, es muss jedoch darauf geachtet werden, dass für die angegebene Ausgabengruppe durchgängig dieselbe ganze Zahl verwendet wird.

    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 explizit die DirectRowTooutputbuffer-Methode> für jede Zeile aufrufen, die Sie an die Ausgabe senden möchten.

  • Zuweisen eines aussagekräftigeren Namens für Eingabe und Ausgaben In der Skriptkomponente werden diese Namen verwendet, um die typisierten Accessoreigenschaften zu erzeugen, mit denen Sie auf die Eingabe und die Ausgaben in Ihrem Skript verweisen.

  • Verändern Sie die Spalten für synchrone Transformationen nicht. Normalerweise werden bei einer synchronen Transformation dem Datenfluss keine Spalten hinzugefügt. Die Daten werden gleich im Puffer verändert, und der Puffer wird an die nächste Komponente im Datenfluss übergeben. Bei einer solchen Vorgehensweise müssen Sie den Transformationsausgaben keine Ausgabespalten explizit hinzufügen und diese dann konfigurieren. Die Ausgaben werden ohne explizit definierte Spalten im Editor angezeigt.

  • Fügen Sie simulierten Fehlerausgaben neue Spalten für Fehler auf Zeilenebene hinzu. Ü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). Beachten Sie, dass Sie in der Skriptkomponente eigenen Code schreiben müssen, 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 zur Seite Eingaben und Ausgaben des Transformations-Editors für Skripts finden Sie unter Transformations-Editor für Skripts (Seite Eingaben und Ausgaben).

Hinzufügen von Variablen

Wenn Sie die 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 Eigenschaftsfelder hinzufügen, 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 Eigenschaftsfeldern 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 zur Seite Skript des Transformations-Editors für Skripts finden Sie unter Transformations-Editor für Skripts (Seite Skript).

Skripterstellung für eine synchrone Transformationskomponente im Codeentwurfsmodus

Nachdem Sie die Metadaten für Ihre Komponente konfiguriert haben, können Sie das benutzerdefinierte Skript schreiben. Klicken Sie im Transformations-Editor für Skripts auf der Seite Skript auf Skript bearbeiten, um die Microsoft Visual Studio-Tools für Anwendungen-IDE (VSTA) zu öffnen, in der Sie Ihr benutzerdefiniertes Skript hinzufügen können. Die von Ihnen verwendete Skriptsprache hängt davon ab, ob Sie Microsoft Visual Basic oder Microsoft Visual C# als Skriptsprache für die ScriptLanguage-Eigenschaft auf der Seite Skript ausgewählt haben.

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 Transformationskomponente die VSTA-IDE öffnen, wird die bearbeitbare ScriptMain-Klasse im Code-Editor mit einem Stub für die ProcessInputRow-Methode angezeigt. Sie schreiben Ihren benutzerdefinierten Code in der ScriptMain-Klasse. ProcessInputRow ist die wichtigste Methode in einer Transformationskomponente.

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 ProcessInput-Methode in der UserComponent-Klasse auf, die die -Methode der übergeordneten Klasse überschreibt. Die ProcessInput-Methode durchläuft die Zeilen im Eingabepuffer der Reihe nach und ruft für jede Zeile einmal die ProcessInputRow-Methode auf.

Schreiben von benutzerdefiniertem Code

Eine Transformationskomponente mit synchronen Ausgaben ist die Datenflusskomponente, die am einfachsten geschrieben werden kann. Zum Beispiel besteht das später in diesem Thema dargestellte Beispiel mit einer einzigen Ausgabe aus dem folgenden benutzerdefinierten Code:

Row.City = UCase(Row.City)  
Row.City = (Row.City).ToUpper();  
  

Sie können mit der überschriebenen ProcessInputRow-Methode die Daten in jeder Zeile des Eingabepuffers transformieren, um die Erstellung einer benutzerdefinierten synchronen Transformationskomponente abzuschließen. Die Datenfluss-Engine leitet diesen Puffer an die nächste Komponente im Datenfluss weiter, sobald er voll ist.

Je nach Anforderung können Sie auch Skript in den Methoden PreExecute und PostExecute schreiben, die in der ScriptMain-Klasse verfügbar sind, um vorbereitende oder abschließende Verarbeitungsvorgänge auszuführen.

Arbeiten mit mehreren Ausgaben

Die Umleitung von Eingabezeilen an eine von zwei oder mehreren möglichen Ausgaben erfordert nicht viel mehr benutzerdefinierten Code als das Szenario mit einer einzigen Ausgabe, das bereits erläutert wurde. Zum Beispiel besteht das später in diesem Thema dargestellte Beispiel mit zwei Ausgaben aus dem folgenden benutzerdefinierten Code:

Row.City = UCase(Row.City)  
If Row.City = "REDMOND" Then  
    Row.DirectRowToMyRedmondAddresses()  
Else  
    Row.DirectRowToMyOtherAddresses()  
End If  
Row.City = (Row.City).ToUpper();  
  
if (Row.City=="REDMOND")  
{  
    Row.DirectRowToMyRedmondAddresses();  
}  
else  
{  
    Row.DirectRowToMyOtherAddresses();  
}  

In diesem Beispiel generiert die Skriptkomponente die DirectRowToOutputBufferX-Methoden> für Sie basierend auf den Namen der von Ihnen konfigurierten Ausgaben. Sie können ähnlichen Code verwenden, um Fehlerzeilen an eine simulierte Fehlerausgabe weiterzuleiten.

Beispiele

In diesem Beispiel wird der benutzerdefinierte Code veranschaulicht, der in der ScriptMain-Klasse zur Erstellung einer synchronen Transformationskomponente 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.

Beispiel einer synchronen Transformation mit einer Ausgabe

Dieses Beispiel zeigt eine synchrone Transformationskomponente mit einer Ausgabe. Diese Transformation durchläuft die Spalte AddressID und konvertiert die Spalte City in Großbuchstaben.

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

  1. Fügen Sie der Datenfluss-Designeroberfläche eine neue Skriptkomponente hinzu, und konfigurieren Sie sie als Transformation.

  2. Verbinden Ausgabe einer Quelle oder einer anderen Transformation an die neue Transformationskomponente im SSIS-Designer. Diese Ausgabe sollte Daten aus der Tabelle Person.Address der Beispieldatenbank AdventureWorks, die mindestens die Spalten AddressID und City enthält, bereitstellen.

  3. Öffnen Sie den Transformations-Editor für Skripterstellung. Wählen Sie auf der Seite Eingabespalten die Spalten AddressID und City aus. Markieren Sie die Spalte City als Lesen/Schreiben.

  4. Geben Sie auf der Seite Eingaben und Ausgaben der Eingabe und der Ausgabe aussagekräftigere Namen, z.B. MyAddressInput und MyAddressOutput. Beachten Sie, dass die SynchronousInputID der Ausgabe der ID der Eingabe entspricht. Sie müssen deshalb keine Ausgabespalten hinzufügen und konfigurieren.

  5. 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.

  6. Erstellen und konfigurieren Sie eine Zielkomponente, die die Spalten AddressID und City erwartet, z. B. ein SQL Server Ziel oder die Beispielzielkomponente, die unter Erstellen eines Ziels mit der Skriptkomponente veranschaulicht wird. Verbinden Sie daraufhin die Ausgabe der Transformation mit der Zielkomponente. 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)  
    
  7. Führen Sie das Beispiel aus.

Public Class ScriptMain  
    Inherits UserComponent  
  
    Public Overrides Sub MyAddressInput_ProcessInputRow(ByVal Row As MyAddressInputBuffer)  
  
        Row.City = UCase(Row.City)  
  
    End Sub  
  
End Class  
public class ScriptMain:  
    UserComponent  
  
{  
    public override void MyAddressInput_ProcessInputRow(MyAddressInputBuffer Row)  
    {  
  
        Row.City = (Row.City).ToUpper();  
  
    }  
  
}  

Beispiel einer synchronen Transformation mit zwei Ausgaben

Dieses Beispiel zeigt eine synchrone Transformationskomponente mit zwei Ausgaben. Diese Transformation durchläuft die Spalte AddressID und konvertiert die Spalte City in Großbuchstaben. Wenn der Name der Stadt Redmond ist, wird die Zeile an eine bestimmte Ausgabe weitergeleitet, während alle anderen Zeilen zu einer anderen Ausgabe weitergeleitet werden.

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

  1. Fügen Sie der Datenfluss-Designeroberfläche eine neue Skriptkomponente hinzu, und konfigurieren Sie sie als Transformation.

  2. Verbinden die Ausgabe einer Quelle oder einer anderen Transformation an die neue Transformationskomponente im SSIS-Designer. Diese Ausgabe sollte Daten aus der Tabelle Person.Address der Beispieldatenbank AdventureWorks bereitstellen, die mindestens die Spalten AddressID und City enthält.

  3. Öffnen Sie den Transformations-Editor für Skripterstellung. Wählen Sie auf der Seite Eingabespalten die Spalten AddressID und City aus. Markieren Sie die Spalte City als Lesen/Schreiben.

  4. Erstellen Sie auf der Seite Eingaben und Ausgaben eine zweite Ausgabe. Stellen Sie nach dem Hinzufügen der neuen Ausgabe sicher, dass SynchronousInputID der Ausgabe als die ID der Eingabe festgelegt wird. Diese Eigenschaft ist für die erste Ausgabe bereits festgelegt, die standardmäßig erstellt wird. Legen Sie für jede Ausgabe die ExclusionGroup-Eigenschaft auf denselben Wert ungleich 0 (null) fest, um anzugeben, dass die Eingabezeilen auf zwei sich gegenseitig ausschließende Ausgaben verteilt werden. Sie müssen den Ausgaben keine Ausgabezeilen hinzufügen.

  5. Geben Sie der Eingabe und den Ausgaben aussagekräftigere Namen, z.B. MyAddressInput, MyRedmondAddresses und MyOtherAddresses.

  6. 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.

  7. Erstellen und konfigurieren Sie zwei Zielkomponenten, die die Spalten AddressID und City erwarten, z. B. ein SQL Server Ziel, ein Flatfileziel oder die Beispielzielkomponente, die unter Erstellen eines Ziels mit der Skriptkomponente veranschaulicht wird. Verbinden Sie daraufhin alle Ausgaben der Transformation mit einer der Zielkomponenten. Sie können Zieltabellen erstellen, indem Sie einen Transact-SQL Befehl ausführen, der dem folgenden Befehl (mit eindeutigen Tabellennamen) in der AdventureWorks-Datenbank ähnelt:

    CREATE TABLE [Person].[Address2](  
        [AddressID] [int] NOT NULL,  
        [City] [nvarchar](30) NOT NULL  
    
  8. Führen Sie das Beispiel aus.

Public Class ScriptMain  
    Inherits UserComponent  
  
    Public Overrides Sub MyAddressInput_ProcessInputRow(ByVal Row As MyAddressInputBuffer)  
  
        Row.City = UCase(Row.City)  
  
        If Row.City = "REDMOND" Then  
            Row.DirectRowToMyRedmondAddresses()  
        Else  
            Row.DirectRowToMyOtherAddresses()  
        End If  
  
    End Sub  
  
End Class  
public class ScriptMain:  
    UserComponent  
  
public override void MyAddressInput_ProcessInputRow(MyAddressInputBuffer Row)  
    {  
  
        Row.City = (Row.City).ToUpper();  
  
        if (Row.City == "REDMOND")  
        {  
            Row.DirectRowToMyRedmondAddresses();  
        }  
        else  
        {  
            Row.DirectRowToMyOtherAddresses();  
        }  
  
    }  
}  

Weitere Informationen

Grundlegendes zu synchronen und asynchronen Transformationen
Erstellen einer asynchronen Transformation mit der Skriptkomponente
Entwickeln einer benutzerdefinierten Transformationskomponente mit synchronen Ausgaben