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

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).

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).

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).

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.

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.

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:

 [Visual Basic]
    Row.City = UCase(Row.City)
    If Row.City = "REDMOND" Then
        Row.DirectRowToMyRedmondAddresses()
    Else
        Row.DirectRowToMyOtherAddresses()
    End If

 [C#]
        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.

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 do AdventureWorks2008R2 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 e 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, como um componente de destino do SQL Server ou do destino de exemplo demonstrado em Criando um destino com o componente de 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 AdventureWorks2008R2:

   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

 [C#]
public class ScriptMain:
    UserComponent

{
    public override void MyAddressInput_ProcessInputRow(MyAddressInputBuffer Row)
    {

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

    }

}

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 do AdventureWorks2008R2 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, 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 de 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 AdventureWorks2008R2:

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

    }
}