Compilazione, distribuzione e debug di oggetti personalizzati

Articolo
05/23/2023

Si applica a:SQL Server Integration Runtime SSIS in Azure Data Factory

Dopo avere scritto il codice di un oggetto personalizzato per Integration Services, è necessario compilare l'assembly, distribuirlo e integrarlo in Progettazione SSIS per renderlo disponibile per l'uso nei pacchetti e quindi sottoporlo a test e debug.

Passaggi per la compilazione, la distribuzione e il debug di un oggetto personalizzato per Integration Services

La funzionalità personalizzata per l'oggetto è già stata scritta. A questo punto, è necessario testarla e renderla disponibile per gli utenti. I passaggi sono molto simili per tutti i tipi di oggetti personalizzati che è possibile creare per Integration Services.

Ecco i passaggi per compilarlo, distribuirlo e testarlo.

Firmare l'assembly da generare con un nome sicuro.
Compilare l'assembly.
Distribuire l'assembly spostandolo o copiandolo nella cartella appropriata di Integration Services.
Installare l'assembly nella Global Assembly Cache.

L'oggetto viene automaticamente aggiunto alla Casella degli strumenti.
Se necessario, risolvere i problemi della distribuzione.
Eseguire il test e il debug del codice.

È ora possibile usare Progettazione SSIS in SQL Server Data Tools (SSDT) per creare, gestire ed eseguire pacchetti destinati a versioni diverse di SQL Server. Per altre informazioni sull'impatto di questo miglioramento sulle estensioni personalizzate, vedere Getting your SSIS custom extensions to be supported by the multi-version support of SSDT 2015 for SQL Server 2016 (Supportare le estensioni SSIS personalizzate in più versioni di SSDT 2015 per SQL Server 2016).

Firma dell'assembly

Quando un assembly deve essere condiviso, è necessario installarlo nella Global Assembly Cache. Dopo l'aggiunta alla Global Assembly Cache, l'assembly può essere usato da applicazioni come SQL Server Data Tools (SSDT). Un requisito della Global Assembly Cache è che l'assembly deve essere firmato con un nome sicuro che garantisca che sia globalmente univoco. Un assembly con nome sicuro dispone di un nome completo che include il nome, la lingua, la chiave pubblica e il numero di versione dell'assembly. Tali informazioni vengono utilizzate dal runtime per individuare l'assembly e distinguerlo da altri assembly aventi lo stesso nome.

Per firmare un assembly con un nome sicuro, è innanzitutto necessario avere o creare una coppia di chiavi pubblica/privata. Questa coppia di chiavi di crittografia, pubblica e privata, viene utilizzata durante la compilazione per creare un assembly con nome sicuro.

Per altre informazioni sui nomi sicuri e sui passaggi che è necessario eseguire per firmare un assembly, vedere gli argomenti seguenti nella documentazione relativa a .NET Framework SDK:

Assembly con nomi sicuri
Creazione di una coppia di chiavi
Firma di un assembly con un nome sicuro

È possibile firmare facilmente l'assembly con un nome sicuro in Visual Studio durante la compilazione. Nella finestra di dialogo Proprietà progetto selezionare la scheda Firma. Selezionare l'opzione Firma assembly e quindi specificare il percorso del file di chiave (con estensione snk).

Compilazione dell'assembly

Dopo aver firmato il progetto, è necessario compilare o ricompilare il progetto o la soluzione tramite i comandi disponibili nel menu Compila di SQL Server Data Tools. La soluzione può contenere un progetto distinto per un'interfaccia utente personalizzata, che deve essere firmato con un nome sicuro e può essere compilato contemporaneamente.

Il metodo più semplice per eseguire i due passaggi successivi, ovvero la distribuzione dell'assembly e l'installazione nella Global Assembly Cache, consiste nel generare script per questi passaggi come evento di post-compilazione in Visual Studio. Gli eventi di compilazione sono disponibili dalla pagina Compilazione di Proprietà progetto per un progetto di Visual Studio e dalla pagina Eventi di compilazione per un progetto C#. Per utilità del prompt dei comandi come gacutil.exe è necessario specificare il percorso completo. È necessario racchiudere tra virgolette i percorsi che contengono spazi e le macro, ad esempio $(TargetPath), che si espandono in percorsi che contengono spazi.

Di seguito è riportato un esempio di una riga di comando per eventi di post-compilazione per un provider di log personalizzato:

"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 "

Distribuzione dell'assembly

Progettazione SSIS individua gli oggetti personalizzati disponibili per l'uso nei pacchetti enumerando i file trovati in una serie di cartelle create durante l'installazione di SQL Server Integration Services. Se si usano le impostazioni di installazione predefinite di SQL Server, nel percorso C:\Programmi\Microsoft SQL Server\130\DTS è presente questo set di cartelle. Se invece si crea un programma di installazione per l'oggetto personalizzato, è necessario controllare il valore della chiave del Registro di sistema HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\130\SSIS\Setup\DtsPath per verificare il percorso della cartella.

Nota

Per informazioni su come distribuire i componenti personalizzati per un uso efficiente con il supporto di più versioni in SQL Server Data Tools, vedere Getting your SSIS custom extensions to be supported by the multi-version support of SSDT 2015 for SQL Server 2016 (Supportare le estensioni SSIS personalizzate con il supporto di più versioni di SSDT 2015 per SQL Server 2016).

È possibile inserire l'assembly nella cartella in due modi:

Spostare o copiare l'assembly compilato nella cartella appropriata dopo averlo compilato. Per praticità, è possibile includere il comando di copia in un evento di post-compilazione.
Compilare l'assembly direttamente nella cartella appropriata.

Per i vari tipi di oggetti personalizzati, vengono usate le cartelle di distribuzione presenti nel percorso C:\Programmi\Microsoft SQL Server\130\DTS:

Oggetto personalizzato	Cartella di distribuzione
Attività	Attività
Gestione connessione	Connessioni
Provider di log	LogProviders
Componente del flusso di dati	PipelineComponents

Nota

Gli assembly vengono copiati in queste cartelle per supportare l'enumerazione degli oggetti personalizzati disponibili, quali attività, gestioni connessioni e così via. Pertanto, non è necessario distribuire in queste cartelle gli assembly che contengono solo l'interfaccia utente personalizzata per gli oggetti personalizzati.

Installazione dell'assembly nella Global Assembly Cache (CAG)

Per installare l'assembly attività nella Global Assembly Cache, usare lo strumento da riga di comando gacutil.exe oppure trascinare gli assembly nella directory %system%\assembly. Per praticità, è anche possibile includere la chiamata a gacutil.exe in un evento di post-compilazione.

Il comando seguente installa un componente denominato MyTask.dll nella Global Assembly Cache tramite gacutil.exe.

gacutil /iF MyTask.dll

Dopo l'installazione di una nuova versione dell'oggetto personalizzato, è necessario chiudere e riaprire Progettazione SSIS. Se sono state installate versioni precedenti dell'oggetto personalizzato nella Global Assembly Cache, è necessario rimuoverle prima di installare la nuova versione. Per disinstallare un assembly, eseguire gacutil.exe e specificare il nome dell'assembly con l'opzione /u.

Per altre informazioni sulla Global Assembly Cache, vedere lo strumento Global Assembly Cache (Gactutil.exe) in .NET Framework Tools.

Risoluzione dei problemi della distribuzione

Se l'oggetto personalizzato è visualizzato nella casella degli strumenti o nell'elenco di oggetti disponibili ma non è possibile aggiungerlo a un pacchetto, provare a effettuare le operazioni seguenti:

Verificare se nella Global Assembly Cache sono disponibili più versioni del componente. In caso affermativo, è possibile che la finestra di progettazione non sia in grado di caricare il componente. Eliminare tutte le istanze dell'assembly dalla Global Assembly Cache, quindi aggiungere nuovamente l'assembly.
Verificare che nella cartella di distribuzione esista una singola istanza dell'assembly.
Aggiornare la casella degli strumenti.
Connettere Visual Studio a devenv.exe e impostare un punto di interruzione per eseguire le istruzioni del codice di inizializzazione e assicurarsi che non si verifichino eccezioni.

Test e debug del codice

L'approccio più semplice per l'esecuzione del debug dei metodi di runtime di un oggetto personalizzato consiste nell'avviare dtexec.exe da Visual Studio dopo aver compilato l'oggetto e nell'eseguire quindi un pacchetto che usa il componente.

Se si vuole eseguire il debug dei metodi della fase di progettazione del componente, ad esempio il metodo Validate, aprire un pacchetto che usa il componente in una seconda istanza di Visual Studio e connettersi al relativo processo devenv.exe.

Se si vuole eseguire il debug anche dei metodi di runtime del componente quando un pacchetto è aperto e in esecuzione in Progettazione SSIS, è necessario forzare una pausa nell'esecuzione del pacchetto in modo che sia possibile connettersi anche al processo DtsDebugHost.exe.

Per eseguire il debug dei metodi di runtime di un oggetto tramite connessione a dtexec.exe

Firmare e compilare il progetto nella configurazione di debug, distribuirlo e installarlo nella Global Assembly Cache come descritto in questo argomento.
Nella scheda Debug di Proprietà progetto selezionare Avvia programma esterno come Azione di avvio e individuare dtexec.exe, installato per impostazione predefinita in C:\Programmi\Microsoft SQL Server\130\DTS\Binn.
Nella casella di testo Opzioni della riga di comando in Opzioni di avvio immettere gli argomenti della riga di comando richiesti per eseguire un pacchetto in cui viene usato il componente. In genere l'argomento della riga di comando sarà costituito dall'opzione /F[ILE] seguita dal percorso e dal nome del file con estensione dtsx. Per altre informazioni, vedere dtexec Utility.
Impostare i punti di interruzione nel codice sorgente, laddove appropriato, nei metodi di runtime del componente.
Eseguire il progetto.

Per eseguire il debug dei metodi della fase di progettazione di un oggetto personalizzato tramite connessione a SQL Server Data Tools

Firmare e compilare il progetto nella configurazione di debug, distribuirlo e installarlo nella Global Assembly Cache come descritto in questo argomento.
Impostare i punti di interruzione nel codice sorgente, laddove appropriato, nei metodi della fase di progettazione dell'oggetto personalizzato.
Aprire una seconda istanza di Visual Studio e caricare un progetto di Integration Services che contiene un pacchetto che usa l'oggetto personalizzato.
Dalla prima istanza di Visual Studio connettersi alla seconda istanza di devenv.exe in cui è caricato il pacchetto scegliendo Connetti a processo dal menu Debug della prima istanza.
Eseguire il pacchetto dalla seconda istanza di Visual Studio.

Per eseguire il debug dei metodi di runtime di un oggetto personalizzato tramite connessione a SQL Server Data Tools

Dopo avere completato i passaggi descritti nella procedura precedente, forzare una pausa nell'esecuzione del pacchetto in modo che sia possibile connettersi a DtsDebugHost.exe. Per forzare questa pausa, è possibile aggiungere un punto di interruzione all'evento OnPreExecute oppure aggiungere un'attività Script al progetto e passare allo script che visualizza una finestra di messaggio modale.
Eseguire il pacchetto. Quando si verifica la pausa, passare all'istanza di Visual Studio in cui è aperto il progetto di codice e scegliere Connetti a processo dal menu Debug. Assicurarsi di connettersi all'istanza di DtsDebugHost.exe riportata come Gestito, x86 nella colonna Tipo e non all'istanza indicata solo come x86.
Tornare al pacchetto in pausa e continuare oltre il punto di interruzione oppure fare clic su OK per annullare la finestra di messaggio generata dall'attività Script, quindi continuare con l'esecuzione e il debug del pacchetto.

Vedere anche

Sviluppo di oggetti personalizzati per Integration Services
Persistenza degli oggetti personalizzati
Strumenti per la risoluzione dei problemi di sviluppo di pacchetti