Compartilhar via

Criando um destino com o componente Script

  • Artigo

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

Você usa um componente de destino no fluxo de dados de um pacote do Integration Services para salvar dados recebidos de fontes upstream e transformações em uma fonte de dados. Em geral, o componente de destino se conecta à fonte de dados através de um gerenciador de conexões existente.

Para obter uma visão geral do componente Script, consulte Estendendo o fluxo de dados com o componente Script.

O componente Script e o código de infraestrutura gerado para você simplificam significativamente o processo de desenvolvimento de um componente de fluxo de dados personalizado. No entanto, para entender como funciona o componente Script, talvez seja útil ler as etapas de como desenvolver componentes de fluxo de dados personalizados na seção Desenvolvendo um componente de fluxo de dados personalizado e, especialmente, Desenvolvendo um componente de destino personalizado.

Guia de Introdução com um componente Destino

Quando você adiciona um componente Script à guia Fluxo de Dados do Designer do SSIS, a caixa de diálogo Selecionar Tipo de Componente Script é aberta e solicita a seleção de um script Origem, Destino ou Transformação. Nessa caixa de diálogo, selecione Destino.

Depois, conecte a saída de uma transformação ao componente de destino no Designer SSIS. Como teste, você pode conectar uma origem diretamente a um destino, sem qualquer transformação.

Configurando um componente Destino no modo do design de metadados

Depois de selecionar a opção para criar um componente de destino, configure o componente usando o Editor de Transformação Scripts. Para obter mais informações, consulte Configurando o componente Script no Editor de Componente Script.

Para selecionar a linguagem de script que será usada pelo destino Script, defina a propriedade ScriptLanguage na página Script da caixa de diálogo Editor de Transformação Scripts.

Observação

Para definir a linguagem de scripts padrão para o componente Script, use a opção Linguagem de scripts na página Geral da caixa de diálogo Opções. Para obter mais informações, consulte General Page.

Um componente de destino de fluxo de dados tem uma entrada e nenhuma saída. A configuração da entrada do componente é uma das etapas que devem ser concluídas no modo de design de metadados, usando o Editor de Transformação Scripts, antes de escrever o script personalizado.

Adicionando gerenciadores de conexões

Em geral, um componente de destino usa um gerenciador de conexões existente para se conectar à fonte de dados na qual ele salva dados do fluxo de dados. Na página Gerenciadores de Conexões do Editor de Transformação Scripts, clique em Adicionar para adicionar o gerenciador de conexões apropriado.

Contudo, um gerenciador de conexões é apenas uma unidade conveniente que encapsula e armazena as informações necessárias para a conexão a uma fonte de dados de um tipo específico. Escreva seu próprio código personalizado para carregar ou salvar seus dados e, possivelmente, para abrir e fechar a conexão à fonte de dados.

Para obter informações gerais sobre como usar gerenciadores de conexões com o componente Script, consulte Conectando-se a fontes de dados no componente Script.

Para obter mais informações sobre a página Gerenciadores de Conexões do Editor de Transformação Scripts, confira Editor de Transformação Scripts (Página Gerenciadores de Conexões).

Configurando entradas e colunas de entrada

Um componente de destino tem uma entrada e nenhuma saída.

Na página Colunas de Entrada do Editor de Transformação Scripts, a lista de colunas mostra as colunas disponíveis da saída do componente upstream no fluxo de dados. Selecione as colunas a serem salvas.

Para obter mais informações sobre a página Colunas de Entrada do Editor de Transformação de Scripts, confira Editor de Transformação de Scripts (página Colunas de Entrada).

A página Entradas e Saídas do Editor de Transformação Scripts mostra uma única entrada, que pode ser renomeada. Você fará referência à entrada pelo nome em seu script usando a propriedade de acessador criada no código gerado automaticamente.

Para obter mais informações sobre a página Entradas e Saídas do Editor de Transformação de Scripts, confira Editor de Transformação de Scripts (página Entradas e Saídas).

Adicionando variáveis

Se desejar usar variáveis existentes no script, adicione-as aos campos de propriedade ReadOnlyVariables e ReadWriteVariables na página Script do Editor de Transformação Scripts.

Ao adicionar diversas variáveis aos campos de propriedade, separe os nomes das variáveis com vírgulas. Outra alternativa é selecionar diversas variáveis clicando no botão de reticências ( ... ) ao lado dos campos de propriedade ReadOnlyVariables e ReadWriteVariables e, em seguida, selecionar as variáveis na caixa de diálogo Selecionar variáveis.

Para obter informações gerais sobre como usar variáveis com o componente Script, consulte Usando variáveis no componente Script.

Para obter mais informações sobre a página Script do Editor de Transformação de Scripts, confira Editor de Transformação de Scripts (Página Script).

Gerando scripts de um componente de destino em modo do design de código

Depois de configurar os metadados do seu componente, você poderá escrever seu script personalizado. No Editor de Transformação Scripts, na página Script, clique em Editar Script para abrir o IDE do VSTA (Microsoft Visual Studio Tools for Applications), no qual você pode adicionar o script personalizado. A linguagem de scripts usada depende se você selecionou o Microsoft Visual Basic ou o Microsoft Visual C# como a linguagem de scripts para a propriedade ScriptLanguage na página Script.

Para obter informações importantes que se aplicam a todos os tipos de componentes criados por meio do componente Script, consulte Codificando e depurando o componente Script.

Compreendendo o código gerado automaticamente

Quando você abre o IDE do VSTA depois de criar e configurar um componente de destino, a classe editável ScriptMain é exibida no editor de códigos com um stub para o método ProcessInputRow. A classe ScriptMain é o local em que você escreverá seu código personalizado e ProcessInputRow é o método mais importante em um componente de destino.

Se você abrir a janela Explorador de Projeto no VSTA, verá que o componente Script também gerou os itens de projeto BufferWrapper e ComponentWrapper somente leitura. A classe ScriptMain herda da classe UserComponent no item de projeto ComponentWrapper.

Em tempo de execução, o mecanismo de fluxo de dados invoca o método ProcessInput na classe UserComponent, que substitui o método ProcessInput da classe pai ScriptComponent. O método ProcessInput, por sua vez, executa um loop nas linhas do buffer de entrada e chama o método ProcessInputRow uma vez para cada linha.

Escrevendo seu código personalizado

Para concluir a criação de um componente de destino personalizado, é recomendável escrever um script nos métodos a seguir disponíveis na classe ScriptMain.

  1. Substitua o método AcquireConnections para se conectar à fonte de dados externa. Extraia o objeto de conexão, ou as informações de conexão requeridas, do gerenciador de conexões.

  2. Substitua o método PreExecute para se preparar para salvar os dados. Por exemplo, é recomendável criar e configurar um SqlCommand e seus parâmetros nesse método.

  3. Use o método ProcessInputRow substituído para copiar cada linha de entrada para a fonte de dados externa. Por exemplo, para um destino do SQL Server, você pode copiar os valores de coluna nos parâmetros de um SqlCommand e executar o comando uma vez para cada linha. Para um destino de arquivo simples, você pode escrever os valores de cada coluna para um StreamWriter, separando os valores pelo delimitador de coluna.

  4. Substitua o método PostExecute para se desconectar da fonte de dados externa, caso necessário e executar qualquer outra limpeza necessária.

Exemplos

Os exemplos a seguir demonstram o código que é necessário na classe ScriptMain para criar um componente de destino.

Observação

Esses exemplos usam a tabela Person.Address no banco de dados de exemplo AdventureWorks e passam a primeira e a quarta colunas, as colunas intAddressID e nvarchar(30)City, pelo fluxo de dados. Os mesmos dados são usados nos exemplos de origem, transformação e destino nessa seção. Pré-requisitos e suposições adicionais são documentados para cada exemplo.

Exemplo de destino ADO.NET

Esse exemplo demonstra um componente de destino que usa um gerenciador de conexões existente do ADO.NET para salvar dados do fluxo de dados em uma tabela do SQL Server.

Se você quiser executar esse código de exemplo, configure o pacote e o componente desta forma:

  1. Crie um gerenciador de conexões do ADO.NET que usa o provedor SqlClient para se conectar ao banco de dados AdventureWorks.

  2. Crie uma tabela de destino executando o comando Transact-SQL seguinte no banco de dados AdventureWorks:

    CREATE TABLE [Person].[Address2]([AddressID] [int] NOT NULL,  
    [City] [nvarchar](30) NOT NULL)

  3. Adicione um novo componente Script à superfície do designer de Fluxo de Dados e configure-o como um destino.

  4. Conecte a saída de uma origem ou transformação upstream para o componente de destino no Designer SSIS. (Você pode conectar uma origem diretamente a um destino, sem transformações.) Essa saída deve fornecer dados da tabela Person.Address do banco de dados de exemplo AdventureWorks que contêm, pelo menos, as colunas AddressID e City.

  5. Abra o Editor de Transformação Scripts. Na página Colunas de Entrada, selecione as colunas de entrada AddressID e City.

  6. Na página Entradas e Saídas, renomeie a entrada com um nome mais descritivo, como MyAddressInput.

  7. Na página Gerenciadores de Conexões, adicione ou crie o gerenciador de conexões do ADO.NET com um nome como MyADONETConnectionManager.

  8. Na página Script, clique em Editar Script e insira o script a seguir. Em seguida, feche o ambiente de desenvolvimento de script.

  9. Feche o Editor de Transformação Scripts e execute a amostra.

Imports System.Data.SqlClient  
...  
Public Class ScriptMain  
    Inherits UserComponent  
  
    Dim connMgr As IDTSConnectionManager100  
    Dim sqlConn As SqlConnection  
    Dim sqlCmd As SqlCommand  
    Dim sqlParam As SqlParameter  
  
    Public Overrides Sub AcquireConnections(ByVal Transaction As Object)  
  
        connMgr = Me.Connections.MyADONETConnectionManager  
        sqlConn = CType(connMgr.AcquireConnection(Nothing), SqlConnection)  
  
    End Sub  
  
    Public Overrides Sub PreExecute()  
  
        sqlCmd = New SqlCommand("INSERT INTO Person.Address2(AddressID, City) " & _  
            "VALUES(@addressid, @city)", sqlConn)  
        sqlParam = New SqlParameter("@addressid", SqlDbType.Int)  
        sqlCmd.Parameters.Add(sqlParam)  
        sqlParam = New SqlParameter("@city", SqlDbType.NVarChar, 30)  
        sqlCmd.Parameters.Add(sqlParam)  
  
    End Sub  
  
    Public Overrides Sub MyAddressInput_ProcessInputRow(ByVal Row As MyAddressInputBuffer)  
        With sqlCmd  
            .Parameters("@addressid").Value = Row.AddressID  
            .Parameters("@city").Value = Row.City  
            .ExecuteNonQuery()  
        End With  
    End Sub  
  
    Public Overrides Sub ReleaseConnections()  
  
        connMgr.ReleaseConnection(sqlConn)  
  
    End Sub  
  
End Class  

using System.Data.SqlClient;  
public class ScriptMain:  
    UserComponent  
  
{  
    IDTSConnectionManager100 connMgr;  
    SqlConnection sqlConn;  
    SqlCommand sqlCmd;  
    SqlParameter sqlParam;  
  
    public override void AcquireConnections(object Transaction)  
    {  
  
        connMgr = this.Connections.MyADONETConnectionManager;  
        sqlConn = (SqlConnection)connMgr.AcquireConnection(null);  
  
    }  
  
    public override void PreExecute()  
    {  
  
        sqlCmd = new SqlCommand("INSERT INTO Person.Address2(AddressID, City) " +  
            "VALUES(@addressid, @city)", sqlConn);  
        sqlParam = new SqlParameter("@addressid", SqlDbType.Int);  
        sqlCmd.Parameters.Add(sqlParam);  
        sqlParam = new SqlParameter("@city", SqlDbType.NVarChar, 30);  
        sqlCmd.Parameters.Add(sqlParam);  
  
    }  
  
    public override void MyAddressInput_ProcessInputRow(MyAddressInputBuffer Row)  
    {  
        {  
            sqlCmd.Parameters["@addressid"].Value = Row.AddressID;  
            sqlCmd.Parameters["@city"].Value = Row.City;  
            sqlCmd.ExecuteNonQuery();  
        }  
    }  
  
    public override void ReleaseConnections()  
    {  
  
        connMgr.ReleaseConnection(sqlConn);  
  
    }  
  
}

Exemplo de Destino de Arquivos Simples

Esse exemplo demonstra um componente de destino que usa um gerenciador de conexões de arquivos simples existente para salvar dados do fluxo de dados em um arquivo simples.

Se você quiser executar esse código de exemplo, configure o pacote e o componente desta forma:

  1. Crie um gerenciador de conexões de arquivos simples que se conecte a um arquivo de destino. Não é necessário que o arquivo já exista; o componente de destino irá criá-lo. Configure o arquivo de destino como um arquivo delimitado por vírgula que contém as colunas AddressID e City.

  2. Adicione um novo componente Script à superfície do designer de Fluxo de Dados e configure-o como um destino.

  3. Conecte a saída de uma origem ou transformação upstream para o componente de destino no Designer SSIS. (Você pode conectar uma origem diretamente a um destino, sem transformações.) Essa saída deve fornecer dados da tabela Person.Address do banco de dados de exemplo AdventureWorks e deve conter, pelo menos, as colunas AddressID e City.

  4. Abra o Editor de Transformação Scripts. Na página Colunas de Entrada, selecione as colunas AddressID e City.

  5. Na página Entradas e Saídas, renomeie a entrada com um nome mais descritivo, como MyAddressInput.

  6. Na página Gerenciadores de Conexões, adicione ou crie o gerenciador de conexões de Arquivos Simples com um nome descritivo como MyFlatFileDestConnectionManager.

  7. Na página Script, clique em Editar Script e insira o script a seguir. Em seguida, feche o ambiente de desenvolvimento de script.

  8. Feche o Editor de Transformação Scripts e execute a amostra.

Imports System.IO  
...  
Public Class ScriptMain  
    Inherits UserComponent  
  
    Dim copiedAddressFile As String  
    Private textWriter As StreamWriter  
    Private columnDelimiter As String = ","  
  
    Public Overrides Sub AcquireConnections(ByVal Transaction As Object)  
  
        Dim connMgr As IDTSConnectionManager100 = _  
            Me.Connections.MyFlatFileDestConnectionManager  
        copiedAddressFile = CType(connMgr.AcquireConnection(Nothing), String)  
  
    End Sub  
  
    Public Overrides Sub PreExecute()  
  
        textWriter = New StreamWriter(copiedAddressFile, False)  
  
    End Sub  
  
    Public Overrides Sub MyAddressInput_ProcessInputRow(ByVal Row As MyAddressInputBuffer)  
  
        With textWriter  
            If Not Row.AddressID_IsNull Then  
                .Write(Row.AddressID)  
            End If  
            .Write(columnDelimiter)  
            If Not Row.City_IsNull Then  
                .Write(Row.City)  
            End If  
            .WriteLine()  
        End With  
  
    End Sub  
  
    Public Overrides Sub PostExecute()  
  
        textWriter.Close()  
  
    End Sub  
  
End Class  

using System.IO;  
public class ScriptMain:  
    UserComponent  
  
{  
    string copiedAddressFile;  
    private StreamWriter textWriter;  
    private string columnDelimiter = ",";  
  
    public override void AcquireConnections(object Transaction)  
    {  
  
        IDTSConnectionManager100 connMgr = this.Connections.MyFlatFileDestConnectionManager;  
        copiedAddressFile = (string) connMgr.AcquireConnection(null);  
  
    }  
  
    public override void PreExecute()  
    {  
  
        textWriter = new StreamWriter(copiedAddressFile, false);  
  
    }  
  
    public override void MyAddressInput_ProcessInputRow(MyAddressInputBuffer Row)  
    {  
  
        {  
            if (!Row.AddressID_IsNull)  
            {  
                textWriter.Write(Row.AddressID);  
            }  
            textWriter.Write(columnDelimiter);  
            if (!Row.City_IsNull)  
            {  
                textWriter.Write(Row.City);  
            }  
            textWriter.WriteLine();  
        }  
  
    }  
  
    public override void PostExecute()  
    {  
  
        textWriter.Close();  
  
    }  
  
}

Consulte Também

Criando uma fonte com o componente Script
Desenvolvendo um componente de destino personalizado