Compilando, implantando e depurando objetos personalizados

Artigo
05/23/2023

Aplica-se a:SQL Server SSIS Integration Runtime no Azure Data Factory

Depois de escrever o código de um objeto personalizado do Integration Services, você deve compilar o assembly, implantá-lo e integrá-lo ao Designer SSIS para disponibilizar seu uso em pacotes, além de testá-lo e depurá-lo.

Etapas para compilar, implantar e depurar um objeto personalizado para serviços de integração

Você já gravou a funcionalidade personalizada para seu objeto. Agora você tem que testá-la e disponibilizá-la aos usuários. As etapas são bem similares para todos os tipos de objetos personalizados que você pode criar para o Integration Services.

Aqui estão as etapas para compilar, implantar e testar esse objeto.

Assine o assembly para que ele seja gerado com um nome forte.
Compile o assembly.
Implante o assembly movendo-o ou copiando-o até a pasta do Integration Services apropriada.
Instale o assembly no GAC (cache de assembly global).

O objeto é automaticamente adicionado à Caixa de Ferramentas.
Solucione problemas de implantação, se necessário.
Teste e depure seu código.

Agora você pode usar o Designer SSIS no SSDT (SQL Server Data Tools) para criar, manter e executar pacotes destinados a diferentes versões do SQL Server. Para obter mais informações sobre o impacto desta melhoria em suas extensões personalizadas, consulte Tornando as extensões personalizadas do SSIS compatíveis com o suporte a várias versões do SSDT 2015 para SQL Server 2016

Assinando o assembly

Quando um assembly for compartilhado, ele deverá ser instalado no cache de assembly global. Depois de acrescentado ao cache de assembly global, ele poderá ser usado por aplicativos como SQL Server Data Tools (SSDT). Um requisito do cache de assembly global é que o assembly seja assinado com um nome forte, que garante que ele seja globalmente único. Um assembly com nome forte tem um nome totalmente qualificado que inclui nome, cultura, chave pública e número da versão do assembly. O runtime usa essas informações para localizar o assembly e diferenciá-lo de outros assemblies com o mesmo nome.

Para assinar um assembly com um nome forte, você deve primeiro ter ou criar um par de chaves pública/privada. Esse par de chaves criptográficas pública e privada é usado na hora da compilação para criar um assembly com nome forte.

Para obter mais informações sobre nomes fortes e sobre as etapas que você deve seguir para assinar um assembly, consulte os tópicos a seguir na documentação do SDK .NET Framework:

Assembly de nome forte
Criando um par de chaves
Assinando um assembly com um nome forte

Você pode assinar seu assembly facilmente com um nome forte em Visual Studio no momento da compilação. Na caixa de diálogo Propriedades do Projeto, selecione a guia Assinatura. Selecione a opção Assinar o assembly e forneça o caminho do arquivo da chave (.snk).

Compilando o assembly

Depois de assinar o projeto, você deve compilar ou recompilar o projeto ou a solução usando os comandos disponíveis no menu Compilar do SQL Server Data Tools. Sua solução pode conter um projeto separado para uma interface do usuário personalizada, que também deve ser assinada com um nome forte e pode ser compilada ao mesmo tempo.

O método mais conveniente para realizar as próximas duas etapas – implantação e instalação do assembly no cache de assembly global – é gerar o script dessas etapas como um evento pós-build em Visual Studio. Os eventos de build estão disponíveis na página Compilar de Propriedades do Projeto para um projeto do Visual Basic e na página Eventos de Build para um projeto em C#. O caminho completo é obrigatório para utilitários de prompt de comando, como gacutil.exe. São necessárias aspas nos caminhos que contêm espaços e nas macros, como $ (TargetPath) que se expande para caminhos que contêm espaços.

Eis um exemplo de uma linha de comando de evento pós-compilação para um provedor de log personalizado:

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

Implantando o assembly

O Designer do SSIS localiza os objetos personalizados disponíveis para serem usados em pacotes, enumerando os arquivos encontrados em uma série de pastas que são criadas quando o SQL Server Integration Services é instalado. Quando as configurações de instalação do SQL Server padrão são usadas, esse conjunto de pastas é localizado sob C:\Arquivos de Programas\Microsoft SQL Server\130\DTS. Entretanto, se você criar um programa de instalação para seu objeto personalizado, você deverá checar o valor da chave do Registro HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\130\SSIS\Setup\DtsPath para verificar o local dessa pasta.

Observação

Para obter informações sobre como implantar componentes personalizados para funcionarem bem com o suporte a várias versões do SQL Server Data Tools, consulte Tornando as extensões personalizadas do SSIS compatíveis com o suporte a várias versões do SSDT 2015 para SQL Server 2016.

Você pode colocar o assembly na pasta de dois modos:

Mova ou copie o assembly para a pasta apropriada após compilá-lo. (Para sua conveniência, você pode incluir o comando de cópia em um Evento de Pós-Compilação).
Compile o assembly diretamente na pasta apropriada.

As seguintes pastas de implantação em C:\Arquivos de Programas\Microsoft SQL Server\130\DTS são usadas para os vários tipos de objetos personalizados:

Objeto personalizado	Pasta de implantação
Tarefa	Tarefas
Gerenciador de conexões	conexões
Provedor de log	LogProviders
Componente de fluxo de dados	PipelineComponents

Observação

Os assemblies são copiados para essas pastas para dar suporte à enumeração de tarefas disponíveis, gerenciadores de conexões, e assim por diante. Portanto, não é necessário implantar assemblies que contenham somente a interface do usuário personalizada para objetos personalizados nessas pastas.

Instalando o assembly no GAC

Para instalar o assembly da tarefa no GAC (cache de assembly global), use a ferramenta de linha de comando gacutil.exe ou arraste os assemblies até o diretório %system%\assembly. Para sua conveniência, também é possível incluir a chamada para gacutil.exe em um evento posterior ao build.

O comando a seguir instala um componente denominado MyTask.dll no GAC usando gacutil.exe.

gacutil /iF MyTask.dll

É necessário fechar e reabrir o SSIS Designer depois que você instalar uma versão nova de seu objeto personalizado. Se você instalou versões anteriores do seu objeto personalizado no GAC, deve removê-las antes de instalar a versão nova. Para desinstalar um assembly, execute gacutil.exe e especifique o nome do assembly com a opção /u.

Para obter mais informações sobre o GAC, consulte a Ferramenta Cache de Assembly Global (Gactutil.exe) nas Ferramentas .NET Framework.

Solucionando problemas de implantação

Se seu objeto personalizado aparecer na Caixa de Ferramentas ou na lista de objetos disponíveis mas você não conseguir adicioná-lo a um pacote, tente fazer o seguinte:

Procure múltiplas versões do seu componente no GAC. Se houver múltiplas versões do componente no GAC, o designer talvez não consiga carregar seu componente. Exclua todas as instâncias do assembly do GAC e adicione o assembly novamente.
Verifique se há somente uma única instância do assembly na pasta de implantação.
Atualize a caixa de ferramentas.
Anexe Visual Studio a devenv.exe e defina um ponto de interrupção para percorrer seu código de inicialização e assegurar que nenhuma exceção ocorra.

Testando e depurando seu código

A abordagem mais simples para depurar os métodos de tempo de execução de um objeto personalizado é iniciar dtexec.exe de Visual Studio depois de compilar seu objeto personalizado e executar um pacote que use o componente.

Para depurar os métodos de tempo de design do componente, tais como o método Validate, abra um pacote que use o componente em uma segunda instância de Visual Studio e anexe-o ao seu processo devenv.exe.

Se você também desejar depurar os métodos de tempo de execução do componente quando um pacote estiver aberto e em execução no designer SSIS, deverá forçar uma pausa na execução do pacote para que também seja possível anexar ao processo DtsDebugHost.exe.

Para depurar os métodos de tempo de execução de um objeto anexando a dtexec.exe

Assine e compile seu projeto na configuração de Depuração, implante-o e instale-o no cache de assembly global como descrito neste tópico.
Na guia Depurar de Propriedades do Projeto, selecione Iniciar programa externo como Iniciar Ação e localize dtexec.exe, que está instalado por padrão em C:\Arquivos de Programas\Microsoft SQL Server\130\DTS\Binn.
Na caixa de texto Opções da linha de comando, em Iniciar Opções, insira os argumentos de linha de comando necessários para executar um pacote que use o componente. Frequentemente, o argumento de linha de comando consistirá no comutador /F [ILE] seguido pelo caminho e pelo nome do arquivo .dtsx. Para saber mais, veja dtexec Utility.
Defina pontos de interrupção no código fonte, quando apropriado, nos métodos de tempo de execução de seu componente.
Execute seu projeto.

Para depurar os métodos de tempo de design de um objeto personalizado anexando às Ferramentas de Dados do SQL Server

Assine e compile seu projeto na configuração de Depuração, implante-o e instale-o no cache de assembly global como descrito neste tópico.
Defina pontos de interrupção no código fonte, quando apropriado, nos métodos de tempo de design de seu objeto personalizado.
Abra uma segunda instância de Visual Studio e carregue um projeto do Integration Services que contenha um pacote que use o objeto personalizado.
Da primeira instância do Visual Studio, anexe à segunda instância de devenv.exe na qual o pacote foi carregado selecionando Anexar ao Processo do menu Depurar da primeira instância.
Execute o pacote da segunda instância de Visual Studio.

Para depurar os métodos de tempo de execução de um objeto personalizado anexando às Ferramentas de Dados do SQL Server

Depois de concluir as etapas listadas no procedimento anterior, force uma pausa na execução do seu pacote para que você possa anexar ao DtsDebugHost.exe. Você pode forçar essa pausa adicionando um ponto de interrupção ao evento OnPreExecute ou adicionando uma tarefa Script ao seu projeto e inserindo um script que exiba uma caixa de mensagem modal.
Execute o pacote. Quando a pausa ocorrer, mude para a instância de Visual Studio em que seu projeto de código está aberto e selecione Anexar ao Processo do menu Depurar. Certifique-se de anexar à instância de DtsDebugHost.exe listada como Gerenciada, x86 na coluna Tipo, mas não à instância listada apenas como x86.
Retorne ao pacote em pausa e continue até o ponto de interrupção ou clique em OK para ignorar a caixa de mensagem gerada pela tarefa Script e continue a execução e a depuração do pacote.

Consulte Também

Desenvolvendo objetos personalizados para o Integration Services
Persistência de objetos personalizados
Ferramentas de solução de problemas para desenvolvimento de pacotes