Criando uma transformação síncrona com o componente Script

Você usa um componente de transformação no fluxo de dados de um pacote do Integration Services para modificar e analisar dados à medida que eles passam da origem ao destino. Uma transformação com saídas síncronas processa cada linha de entrada que passa pelo componente. Uma transformação com saídas assíncronas espera até receber todas as linhas de entrada para completar seu processamento. Este tópico discute uma transformação síncrona. Para obter informações sobre transformações assíncronas, consulte Criando uma transformação assíncrona com o componente Script. Para obter mais informações sobre a diferença entre componentes síncronos e assíncronos, consulte Compreendendo as transformações síncronas e assíncronas.

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. Contudo, para compreender o funcionamento do componente Script, talvez seja útil ler as etapas necessárias ao desenvolvimento de um componente de fluxo de dados personalizado, na seção Desenvolvendo um componente de fluxo de dados personalizado e, especialmente, Desenvolvendo um componente de transformação personalizado com saídas síncronas.

Guia de Introdução com um componente de transformação síncrono

Quando você adiciona um componente Script ao painel Fluxo de Dados do SSIS Designer, a caixa de diálogo Selecionar Tipo de Componente do Script é exibida e solicita que você selecione um tipo de componente de Origem, Destino ou Transformação. Nessa caixa de diálogo, selecione Transformação.

Configurando um componente de transformação síncrono em modo de design de metadados

Após selecionar a opção para criar um componente de transformação, configure o componente usando o Editor de Transformação Scripts. Para obter mais informações, consulte Configurando o componente Script no Editor de Componentes de Script.

Para definir a linguagem de script do componente Script, defina a propriedade ScriptLanguage na página Script do 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 Página Geral.

Um componente de transformação de fluxo de dados tem uma entrada e dá suporte a uma ou mais saídas. A configuração de entrada e de saídas do componente é uma das etapas que você deve concluir no modo de design de metadados, através do Editor de Transformação Scripts, antes de gravar seu script personalizado.

Configurando colunas de entrada

Um componente de transformação tem uma entrada.

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 que você deseja transformar ou percorrer. Marque qualquer coluna que você queira transformar no local como De leitura/gravação.

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

Configurando entradas, saídas e colunas de saída

Um componente de transformação dá suporte a uma ou mais saídas.

Na página Entradas e Saídas do Editor de Transformação Scripts, você pode ver que uma única saída foi criada, mas a saída não tem nenhuma coluna. Nessa página do editor, você pode precisar ou querer configurar os itens a seguir.

• Crie uma ou mais saídas adicionais, como uma saída de erro simulada para linhas que contêm valores inesperados. Use os botões Adicionar Saída e Remover Saída para gerenciar as saídas de seu componente de transformação síncrono. Todas as linhas de entrada são direcionadas para todas as saídas disponíveis, a menos que você indique que pretende redirecionar cada linha para uma ou outra saída. Você indica que pretende redirecionar linhas especificando um valor de inteiro diferente de zero para a propriedade ExclusionGroup nas saídas. O valor de inteiro específico inserido em ExclusionGroup para identificar as saídas não é significativo, mas você deve usar o mesmo inteiro de forma consistente para o grupo especificado de saídas.

  Observação
  Você também poderá usar um valor de propriedade ExclusionGroup diferente de zero com uma única saída quando não quiser gerar todas as linhas. No entanto, nesse caso você deve chamar explicitamente o método DirectRowTo<outputbuffer> para cada linha que queira enviar à saída.

• Atribua um nome mais descritivo para a entrada e as saídas. O componente Script utiliza esses nomes para gerar as propriedades de acessador digitadas que você utilizará para referenciar a entrada e as saídas no seu script.

• Deixe as colunas como estão nas transformações síncronas. Normalmente, uma transformação síncrona não acrescenta colunas ao fluxo de dados. Os dados são modificados no local no buffer, e o buffer é passado para o próximo componente do fluxo de dados. Se esse for o caso, você não terá que adicionar e configurar colunas de saída explicitamente nas saídas da transformação. As saídas aparecem no editor sem qualquer coluna explicitamente definida.

• Acrescente colunas novas a saídas de erro simuladas para erros em nível de linha. De maneira geral, múltiplas saídas no mesmo ExclusionGroup têm o mesmo conjunto de colunas de saída. Porém, se você estiver criando uma saída de erro simulada, pode ser que queira adicionar mais colunas para conter informações de erro. Para obter informações sobre como o mecanismo de fluxo de dados processa linhas de erro, consulte Usando saídas de erro em um componente de fluxo de dados. Observe que no componente Script você deve escrever seu próprio código para preencher as colunas adicionais com informações de erro apropriadas. Para obter mais informações, consulte Simulando uma saída de erro para o componente Script.

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

Adicionando variáveis

Se você quiser usar variáveis existentes em seu script, poderá adicioná-las nos 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 para selecionar diversas variáveis é clicar no botão de reticências (…) que fica ao lado dos campos de propriedade ReadOnlyVariables e ReadWriteVariables e depois selecione 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 Scripts, consulte Editor de Transformação Scripts (página Script).

Gerando scripts de um componente de transformação síncrono em modo de 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 Microsoft Visual Studio Tools for Applications (VSTA) IDE, onde você pode adicionar o script personalizado. Para saber a linguagem de scripts a ser usada, verifique se você selecionou a linguagem de script Microsoft Visual Basic ou Microsoft Visual C# para a propriedade ScriptLanguage na página Script.

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

Compreendendo o código gerado automaticamente

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

Se você abrir a janela Explorador de Projeto do VSTA, verificará que o componente Script também gerou BufferWrapper somente leitura e itens de projeto ComponentWrapper. A classe ScriptMain foi herdada 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

Um componente de transformação com saídas síncronas é o mais simples de todos os componentes de fluxo de dados para gravar. Por exemplo, o exemplo de saída única mostrado mais adiante neste tópico consiste no seguinte código personalizado:

    Row.City = UCase(Row.City)

    Row.City = (Row.City).ToUpper();

Para concluir a criação de um componente de transformação síncrono personalizado, use o método ProcessInputRow substituído para transformar os dados em cada linha do buffer de entrada. O mecanismo de fluxo de dados transmite esse buffer, quando cheio, para o próximo componente do fluxo de dados.

Dependendo dos seus requisitos, talvez você queira gravar o script nos métodos PreExecute e PostExecute disponíveis na classe ScriptMain para executar um processamento preliminar ou final.

Trabalhando com várias saídas

Direcionar linhas de entrada a uma de duas ou mais saídas possíveis não requer muito mais código personalizado do que o cenário de saída única discutido anteriormente. Por exemplo, o exemplo de duas saídas mostrado mais adiante neste tópico consiste no seguinte código personalizado:

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

Neste exemplo, o componente Script gera os métodos DirectRowTo<OutputBufferX> para você baseando-se nos nomes das saídas que foram configurados. Você pode usar um código semelhante para direcionar linhas de erro a uma saída de erro simulada.

Exemplos

Estes exemplos demonstram o código personalizado que é necessário na classe ScriptMain para criar um componente de transformação síncrono.

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 int AddressID e nvarchar(30) City, através do 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 transformação síncrona de saída única

Este exemplo demonstra um componente de transformação síncrono com uma única saída. Essa transformação passa pela coluna AddressID e converte a coluna City para escrever em letra maiúscula.

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

1. Adicione um novo componente Script à superfície de designer Fluxo de Dados e configure-o como uma transformação.

2. Conecte a saída de uma origem ou de uma outra transformação ao novo componente de transformação no SSIS Designer. Essa saída deve fornecer dados da tabela Person.Address do banco de dados de exemplo AdventureWorks, que contém as colunas AddressID e City.

3. Abra o Editor de Transformação Scripts. Na página Colunas de Entrada, selecione as colunas AddressID e City. Marque a coluna City como De leitura/gravação.

4. Na página Entradas e Saídas, renomeie a entrada e a saída com nomes mais descritivos, como MyAddressInput and MyAddressOutput. Note que o SynchronousInputID da saída corresponde ao ID da entrada. Portanto, não é necessário adicionar e configurar colunas de saída.

5. Na página Script, clique em Editar Script e digite o script a seguir. Em seguida, feche o ambiente de desenvolvimento de script e o Editor de Transformação Scripts.

6. Crie e configure um componente de destino que espera as colunas AddressID e City, tais como um destino SQL Server ou o componente de destino de exemplo demonstrado em Criando um destino com o componente Script. Então, conecte a saída da transformação ao componente de destino. É possível criar uma tabela de destino executando o seguinte comando Transact-SQL no banco de dados do AdventureWorks:

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

7. Execute o exemplo.

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

    }

}

Exemplo de transformação síncrona com duas saídas

Este exemplo demonstra um componente de transformação síncrono com duas saídas. Essa transformação passa pela coluna AddressID e converte a coluna City para escrever em letra maiúscula. Se o nome de cidade for Redmond, ele direcionará a linha para uma saída e todas as outras linhas para outra saída.

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

1. Adicione um novo componente Script à superfície de designer Fluxo de Dados e configure-o como uma transformação.

2. Conecte a saída de uma origem ou de uma outra transformação ao novo componente de transformação no SSIS Designer. 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.

3. Abra o Editor de Transformação Scripts. Na página Colunas de Entrada, selecione as colunas AddressID e City. Marque a coluna City como De leitura/gravação.

4. Na página Entradas e Saídas, crie uma segunda saída. Depois de adicionar a saída nova, defina seu SynchronousInputID como o ID da entrada. Essa propriedade já está definida na primeira saída, que é criada por padrão. Para cada saída, defina a propriedade ExclusionGroup com o mesmo valor diferente de zero com o qual você dividirá as linhas de entrada entre duas saída mutuamente exclusivas. Não é necessário acrescentar qualquer coluna de saída às saídas.

5. Renomeie a entrada e as saídas com nomes mais descritivos, como MyAddressInput, MyRedmondAddresses e MyOtherAddresses.

6. Na página Script, clique em Editar Script e digite o script a seguir. Em seguida, feche o ambiente de desenvolvimento de script e o Editor de Transformação Scripts.

7. Crie e configure dois componentes de destino que esperam as colunas AddressID e City, tais como um destino SQL Server, um destino de Arquivo Simples ou o componente de destino de exemplo demonstrado em Criando um destino com o componente Script. Em seguida, conecte cada uma das saídas da transformação a um dos componentes de destino. É possível criar tabelas de destino executando um comando Transact-SQL semelhante ao seguinte (com nomes de tabela exclusivos) no banco de dados AdventureWorks:

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

8. Execute o exemplo.

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

    }
}

Mantenha-se atualizado com o Integration Services Para obter os downloads, artigos, exemplos e vídeos mais recentes da Microsoft, assim como soluções selecionadas pela comunidade, visite a página do Integration Services no MSDN: Visite a página do Integration Services no MSDN Para receber uma notificação automática dessas atualizações, assine os RSS feeds disponíveis na página.

Consulte também

Conceitos

Compreendendo as transformações síncronas e assíncronas

Criando uma transformação assíncrona com o componente Script

Desenvolvendo um componente de transformação personalizado com saídas síncronas