Erstellen einer synchronen Transformation mit der Skriptkomponente

Transformationskomponenten dienen im Datenfluss eines Integration Services-Pakets dazu, Daten auf dem Weg von der Quelle zum Ziel zu ändern und zu analysieren. 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. Weitere Informationen über asynchrone Transformationen finden Sie unter Erstellen einer asynchronen Transformation mit der Skriptkomponente. Weitere Informationen zu den Unterschieden zwischen synchronen und asynchronen Komponenten finden Sie unter Grundlegendes zu synchronen und asynchronen Transformationen.

Eine Übersicht über die Skriptkomponente finden Sie unter Erweitern des Datenflusses mit der Skriptkomponente.

Die Skriptkomponente und der Infrastrukturcode, den sie generiert, erleichtern deutlich den Prozess der Entwicklung von benutzerdefinierten Datenflusskomponenten. Um die Funktionsweise der Skriptkomponente zu verstehen, kann es jedoch hilfreich sein, sich mit den Schritten im Entwickeln einer benutzerdefinierten Datenflusskomponente-Abschnitt vertraut zu machen, die Sie bei der Entwicklung einer benutzerdefinierten Datenflusskomponente befolgen müssen, und zwar insbesondere mit Entwickeln einer benutzerdefinierten Transformationskomponente mit synchronen Ausgaben.

Erste Schritte mit einer synchronen Transformationskomponente

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 Transformationskomponententyps aufgefordert. Wählen Sie in diesem Dialogfeld die Option Transformation.

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 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
Um die Standardskriptsprache für die Skriptkomponente festzulegen, verwenden Sie im Dialogfeld Optionen auf der Seite Allgemein die Option Skriptsprache. Weitere Informationen finden Sie unter Seite Allgemein.

Eine Datenfluss-Transformationskomponente verfügt über eine Eingabe und unterstützt eine oder mehrere Ausgaben. Die Konfiguration der Eingaben und Ausgaben der 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 über die Seite Eingabespalten im Transformations-Editor für Skripterstellung finden Sie unter Transformations-Editor für Skripterstellung (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 eingerichtet wurde. Ausgabespalten sind 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 null für die ExclusionGroup-Eigenschaft der Ausgaben erreicht. Der in ExclusionGroup eingegebene spezifische Ganzzahlwert zum Identifizieren der Ausgaben ist nicht von Bedeutung, es muss jedoch darauf geachtet werden, dass für die spezifische Ausgabegruppe durchgängig dieselbe ganze Zahl verwendet wird.

  Hinweis
  Sie können auch einen Wert ungleich 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 DirectRowTo<outputbuffer>-Methode aufrufen.

• 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 haben mehrere Ausgaben in der gleichen ExclusionGroup die gleiche Gruppe von Ausgabespalten. Falls Sie eine simulierte Fehlerausgabe erstellen, sollten Sie jedoch mehrere Spalten hinzufügen, um Fehlerinformationen zu speichern. Informationen dazu, wie das Datenflussmodul Fehlerzeilen verarbeitet, finden Sie unter 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 Simulieren einer Fehlerausgabe für die Skriptkomponente.

Weitere Informationen über die Seite Eingaben und Ausgaben des Transformations-Editors für Skripterstellung finden Sie unter Transformations-Editor für Skripterstellung (Seiten 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 für 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 Auslassungszeichen (…) 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 Verwenden von Variablen in der Skriptkomponente.

Weitere Informationen zur Seite Skript des Transformations-Editors für Skripterstellung finden Sie unter Transformations-Editor für Skripterstellung (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 auf der Seite Skript im Transformations-Editor für Skripterstellung auf Skript bearbeiten, um die Microsoft Visual Studio Tools for Applications (VSTA)-IDE zu öffnen und Ihr benutzerdefiniertes Skript hinzuzufügen. Welche Skriptsprache Sie verwenden, hängt davon ab, ob Sie auf der Seite Skript Microsoft Visual Basic oder Microsoft Visual C# als Skriptsprache für die ScriptLanguage-Eigenschaft festgelegt haben.

Wichtige Informationen, die alle Arten von Komponenten betreffen, die mithilfe der Skriptkomponente erstellt wurden, finden Sie unter 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. In der ScriptMain-Klasse schreiben Sie Ihren benutzerdefinierten Code, und ProcessInputRow ist die wichtigste Methode in einer Transformationskomponente.

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

Zur Laufzeit ruft das Datenflussmodul die ProcessInput-Methode in der UserComponent-Klasse auf, die die ProcessInput-Methode der übergeordneten ScriptComponent-Klasse überschreibt. Die ProcessInput-Methode durchläuft der Reihe nach in Schleifen die Zeilen im Eingabepuffer 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();

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

Je nach Ihren Anforderungen können Sie auch Skript in der PreExecute-Methode und in der PostExecute-Methode 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 werden von der Skriptkomponente auf Grundlage der von Ihnen konfigurierten Ausgabenamen die DirectRowTo<OutputBufferX>-Methoden für Sie erstellt. 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, die Spalten int AddressID und nvarchar(30) City, 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 diesen 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 Sie die Ausgabe einer Quelle oder einer anderen Transformation mit der neuen 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 SynchronousInputID der Ausgabe 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 aufnimmt, 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 diesen 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 Sie die Ausgabe einer Quelle oder einer anderen Transformation mit der neuen 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 die SynchronousInputID der Ausgabe als 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 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 für die Spalten AddressID and City, z. B. ein SQL Server-Ziel, ein Flatfileziel oder die unter Erstellen eines Ziels mit der Skriptkomponente erläuterte Beispielzielkomponente. Verbinden Sie daraufhin alle Ausgaben der Transformation mit einer der Zielkomponenten. Sie können Zieltabellen erstellen, indem Sie einen Transact-SQL-Befehl ähnlich dem im Folgenden dargestellten Befehl (mit eindeutigen Tabellennamen) in der AdventureWorks-Datenbank ausführen:

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

    }
}

Siehe auch

Konzepte

Grundlegendes zu synchronen und asynchronen Transformationen

Erstellen einer asynchronen Transformation mit der Skriptkomponente

Entwickeln einer benutzerdefinierten Transformationskomponente mit synchronen Ausgaben