Erstellen, Bereitstellen und Debuggen von benutzerdefinierten Objekten

Artikel
05/23/2023

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

Nachdem Sie den Code für ein benutzerdefiniertes Objekt für Integration Services geschrieben haben, müssen Sie die Assembly erstellen, bereitstellen und in SSIS-Designer integrieren, um sie für die Nutzung in Paketen verfügbar zu machen, sie zu testen und zu debuggen.

Schritte zum Erstellen, Bereitstellen und Debuggen eines benutzerdefinierten Objekts für Integration Services

Sie haben bereits die benutzerdefinierte Funktionalität für das Objekt geschrieben. Jetzt müssen Sie es testen und Benutzern zur Verfügung stellen. Die Schritte sind für alle Typen benutzerdefinierter Objekte, die Sie für Integration Services erstellen können, ähnlich.

Im Folgenden werden die einzelnen Schritte zum Erstellen, Bereitstellen und Testen erläutert.

Signieren Sie die zu generierende Assembly mit einem starken Namen.
Erstellen Sie die Assembly.
Stellen Sie die Assembly bereit, indem Sie sie verschieben oder in den entsprechenden Integration Services-Ordner kopieren.
Installieren Sie die Assembly im globalen Assemblycache (Global Assembly Cache, GAC).

Das Objekt wird der Toolbox automatisch hinzugefügt.
Beheben Sie ggf. Probleme bei der Bereitstellung.
Testen und debuggen Sie den Code.

Sie können den SSIS-Designer in den SQL Server Data Tools (SSDT) jetzt verwenden, um Pakete zu erstellen, zu verwalten und auszuführen, die auf verschiedene SQL Server-Versionen ausgerichtet sind. Weitere Informationen zum Umfang dieser Verbesserung Ihrer benutzerdefinierten Erweiterungen finden Sie unter Getting your SSIS custom extensions to be supported by the multi-version support of SSDT 2015 for SQL Server 2016 (Unterstützung benutzerdefinierter SSIS-Erweiterungen dank der Unterstützung mehrerer Versionen von SSDT 2015 für SQL Server 2016).

Signieren der Assembly

Wenn eine Assembly freigegeben werden soll, muss sie im GAC installiert sein. Nachdem die Assembly dem globalen Assemblycache hinzugefügt wurden, kann die Assembly von Anwendungen wie SQL Server Data Tools (SSDT) genutzt werden. Für den globalen Assemblycache muss die Assembly mit einem starken Namen signiert werden, um sicherzustellen, dass eine Assembly global eindeutig ist. Eine Assembly mit starkem Namen verfügt über einen vollqualifizierten Namen, der den Namen, öffentlichen Schlüssel und die Versionsnummer der Assembly umfasst. Anhand dieser Informationen wird die Assembly von der Laufzeit gefunden und von anderen Assemblys mit demselben Namen unterschieden.

Um eine Assembly mit einem starken Namen zu signieren, müssen Sie zuerst über ein Schlüsselpaar verfügen oder eines erstellen, das aus einem öffentlichen und einem privaten Schlüssel besteht. Dieses kryptografische Schlüsselpaar wird während der Erstellung zum Generieren einer Assembly mit starkem Namen verwendet.

Weitere Informationen zu starken Namen und zu den Schritten zum Signieren einer Assembly finden Sie in den folgenden Themen in der .NET Framework SDK-Dokumentation:

Assemblys mit starkem Namen
Erstellen eines Schlüsselpaars
Signieren einer Assembly mit einem starken Namen

Sie können die Assembly mühelos in Visual Studio beim Erstellen mit einem starken Namen signieren. Wählen Sie im Dialogfeld Projekteigenschaften die Registerkarte Signierung aus. Aktivieren Sie die Option Assembly signieren, und geben Sie dann den Pfad der Schlüsseldatei (.snk) an.

Erstellen der Assembly

Nach der Signierung des Projekts müssen Sie das Projekt oder die Projektmappe erstellen bzw. neu erstellen, indem Sie die im Build-Menü von SQL Server Data Tools verfügbaren Befehle verwenden. Die Lösung enthält möglicherweise ein separates Projekt für eine benutzerdefinierte Benutzeroberfläche, die ebenfalls mit einem starken Namen signiert sein muss und zur gleichen Zeit erstellt werden kann.

Der einfachste Weg, um die nächsten zwei Schritte (Bereitstellen der Assembly und Installieren im globalen Assemblycache) auszuführen, besteht darin, ein Skript für diese Schritte als Postbuildereignis in Visual Studio zu erstellen. Buildereignisse stehen unter „Projekteigenschaften“ auf der Seite Kompilieren für ein Visual Basic-Projekt und auf der Seite Buildereignisse für ein C#-Projekt zur Verfügung. Der vollständige Pfad ist für Eingabeaufforderungs-Hilfsprogramme wie gacutil.exe erforderlich. Pfade mit Leerzeichen und Makros wie $(TargetPath), mit denen Pfade mit Leerzeichen erweitert werden, müssen von Anführungszeichen umschlossen werden.

Nachfolgend finden Sie ein Beispiel einer Postbuildereignis-Befehlszeile für einen benutzerdefinierten Protokollanbieter:

"C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\bin\NETFX 4.0 Tools\gacutil.exe" -u $(TargetName)  
"C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\bin\NETFX 4.0 Tools\gacutil.exe" -i $(TargetFileName)  
copy $(TargetFileName) "C:\Program Files\Microsoft SQL Server\130\DTS\LogProviders "

Bereitstellen der Assembly

Der SSIS-Designer sucht die benutzerdefinierten Objekte, die in Paketen verwendet werden können, indem die Dateien in mehreren Ordnern aufgezählt werden, die bei der Installation von SQL Server Integration Services erstellt werden. Wenn die Standardeinstellungen für die SQL Server-Installation verwendet werden, befinden sich die Ordner im Verzeichnis C:\Programme\Microsoft SQL Server\130\DTS. Wenn Sie jedoch für Ihr benutzerdefiniertes Objekt ein Setupprogramm erstellen, sollten Sie den Wert des HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\130\SSIS\Setup\DtsPath-Registrierungsschlüssels überprüfen, um den Speicherort des Ordners zu überprüfen.

Hinweis

Informationen zur Bereitstellung von benutzerdefinierten Komponenten, die mit der Unterstützung mehrerer Versionen in SQL Server Data Tools zusammenarbeiten, finden Sie unter Getting your SSIS custom extensions to be supported by the multi-version support of SSDT 2015 for SQL Server 2016 (Unterstützung benutzerdefinierter SSIS-Erweiterungen dank der Unterstützung mehrerer Versionen von SSDT 2015 für SQL Server 2016).

Sie können die Assembly auf zwei Arten im Ordner platzieren:

Verschieben oder kopieren Sie die kompilierte Assembly nach der Erstellung in den entsprechenden Ordner. (Sie können auch einfach den Kopierbefehl in ein Postbuildereignis einschließen.)
Erstellen Sie die Assembly direkt im entsprechenden Ordner.

Die folgenden Bereitstellungsordner unter C:\Programme\Microsoft SQL Server\130\DTS werden für die unterschiedlichen Typen benutzerdefinierter Objekte verwendet:

Benutzerdefiniertes Objekt	Bereitstellungsordner
Aufgabe	Aufgaben
Ziel-Editor für Dimensionsverarbeitung	Verbindungen
Protokollanbieter	LogProviders
Datenflusskomponente	PipelineComponents

Hinweis

Assemblys werden in diese Ordner kopiert, um die Aufzählung der verfügbaren Tasks, Verbindungs-Manager usw. zu unterstützen. Sie müssen daher keine Assemblys, die nur die benutzerdefinierte Benutzeroberfläche für benutzerdefinierte Objekte enthalten, in diesen Ordnern bereitstellen.

Installieren der Assembly im globalen Assemblycache

Verwenden Sie das Befehlszeilentool gacutil.exe, oder ziehen Sie die Assemblys in das Verzeichnis %system%\assembly, um die Taskassembly im globalen Assemblycache (GAC) zu installieren. Sie können auch ganz einfach den Aufruf von gacutil.exe in ein Postbuildereignis einschließen.

Der folgende Befehl installiert eine Komponente namens MyTask.dll in den GAC mithilfe von gacutil.exe.

gacutil /iF MyTask.dll

Sie müssen SSIS Designer nach der Installation einer neuer Version des benutzerdefinierten Objekts schließen und erneut öffnen. Wenn Sie frühere Versionen des benutzerdefinierten Objekts im globalen Assemblycache installiert haben, müssen Sie sie vor der Installation der neuen Version entfernen. Führen Sie gacutil.exe aus, und geben Sie den Assemblynamen mit der /u-Option an, um eine Assembly zu deinstallieren.

Weitere Informationen zum globalen Assemblycache finden Sie unter Globales Assemblycache-Tool (Gactutil.exe) in den .NET Framework-Tools.

Behandeln von Problemen bei der Bereitstellung

Wenn das benutzerdefinierte Objekt in der Toolbox oder der Liste verfügbarer Objekte angezeigt wird, Sie es jedoch keinem Paket hinzufügen können, versuchen Sie Folgendes:

Suchen Sie im globalen Assemblycache nach mehreren Versionen der Komponente. Wenn im globalen Assemblycache mehrere Versionen der Komponente vorliegen, kann der Designer u. U. die Komponente nicht laden. Löschen Sie alle Instanzen der Assembly aus dem globalen Assemblycache, und fügen Sie die Assembly wieder hinzu.
Stellen Sie sicher, dass nur eine einzelne Instanz der Assembly im Bereitstellungsordner existiert.
Aktualisieren Sie die Toolbox.
Fügen Sie Visual Studio an devenv.exe an, und legen Sie einen Breakpoint fest, um den Initialisierungscode zu durchlaufen und sicherzustellen, dass keine Ausnahmen auftreten.

Testen und Debuggen des Codes

Am einfachsten können Sie die Laufzeitmethoden eines benutzerdefinierten Objekts debuggen, indem Sie nach dem Erstellen des benutzerdefinierten Objekts dtexec.exe von Visual Studio aus starten und ein Paket, das diese Komponente verwendet, ausführen.

Wenn Sie die Entwurfszeitmethoden der Komponente, z.B. die Validate-Methode, debuggen möchten, öffnen Sie ein Paket, das die Komponente in einer zweiten Instanz von Visual Studio verwendet, und hängen Sie es an den devenv.exe-Prozess an.

Wenn Sie auch die Laufzeitmethoden der Komponente debuggen möchten, wenn ein Paket offen ist und in SSIS-Designer ausgeführt wird, müssen Sie die Ausführung des Pakets anhalten, damit Sie auch für den DtsDebugHost.exe-Prozess einen Anfügevorgang durchführen können.

So debuggen Sie die Laufzeitmethoden eines Objekts durch das Anfügen an dtexec.exe

Signieren und erstellen Sie Ihr Projekt in der Debug-Konfiguration, stellen Sie es bereit, und installieren Sie es im globalen Assemblycache wie in diesem Thema beschrieben.
Wählen Sie unter Projekteigenschaften auf der Registerkarte Debuggen die Option Externes Programm starten als Startaktion aus, und gehen Sie zu dtexec.exe, standardmäßig unter „C:\Programme\Microsoft SQL Server\130\DTS\Binn“ installiert.
Geben Sie im Textfeld Befehlszeilenoptionen unter Startoptionen die Befehlszeilenargumente ein, die zum Ausführen eines Pakets erforderlich sind, das die Komponente verwendet. Oftmals besteht das Befehlszeilenargument aus dem /F[ILE]-Schalter gefolgt vom Pfad und dem Namen der .dtsx-Datei. Weitere Informationen finden Sie hier.
Legen Sie sofern erforderlich im Quellcode Breakpoints in den Laufzeitmethoden der Komponente fest.
Führen Sie Ihr Projekt aus.

So debuggen Sie die Entwurfszeitmethoden eines benutzerdefinierten Objekts durch das Anfügen zu SQL Server-Datentools

Signieren und erstellen Sie Ihr Projekt in der Debug-Konfiguration, stellen Sie es bereit, und installieren Sie es im globalen Assemblycache wie in diesem Thema beschrieben.
Legen Sie sofern erforderlich im Quellcode Breakpoints in den Entwurfszeitmethoden des benutzerdefinierten Objekts fest.
Öffnen Sie eine zweite Instanz von Visual Studio, und laden Sie ein Integration Services-Projekt, das ein Paket enthält, das das benutzerdefinierte Objekt verwendet.
Führen Sie von der ersten Instanz von Visual Studio einen Anfügevorgang für die zweite Instanz von devenv.exe durch, in der das Paket geladen wird, indem Sie aus dem Menü Debuggen der ersten Instanz die Option An den Prozess anhängen auswählen.
Führen Sie das Paket aus der zweiten Instanz von Visual Studio aus.

So debuggen Sie die Laufzeitmethoden eines benutzerdefinierten Objekts durch das Anfügen zu SQL Server-Datentools

Wenn Sie die in der vorherigen Prozedur aufgeführten Schritte ausgeführt haben, halten Sie die Ausführung des Pakets an, sodass Sie einen Anfügevorgang für DtsDebugHost.exe durchführen können. Sie können diese Pause erzwingen, indem Sie dem OnPreExecute-Ereignis einen Breakpoint hinzufügen, oder indem Sie dem Projekt einen Skripttask hinzufügen und ein Skript eingeben, das ein modales Meldungsfeld anzeigt.
Führen Sie das Paket aus. Wechseln Sie nach dem Anhalten des Vorgangs zur Instanz von Visual Studio, in der das Codeprojekt geöffnet ist, und wählen Sie aus dem Menü Debuggen die Option An den Prozess anhängen aus. Stellen Sie sicher, dass Sie an die Instanz von DtsDebugHost.exe anfügen, die in der Spalte Typ als Verwaltet, x86 aufgeführt wird, und nicht an die nur als x86 aufgeführte Instanz.
Kehren Sie zum angehaltenen Paket zurück, und setzen Sie den Vorgang über den Breakpoint hinaus fort, oder klicken Sie auf OK, um das Meldungsfeld, das vom Skripttask aufgerufen wird, zu verwenden, und setzen Sie die Paketausführung und den Debugvorgang fort.

Weitere Informationen

Entwickeln benutzerdefinierter Objekte für Integration Services
Beibehalten von benutzerdefinierten Objekten
Tools zur Problembehandlung für die Paketentwicklung