Criando uma fonte com o componente Script

Em geral, um componente de origem usa um gerenciador de conexões existente para se conectar à fonte de dados da qual ele carrega dados para o 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 também 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 de Script.

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

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

• Adicione e configure colunas de saída manualmente para cada saída. Selecione a pasta Colunas de Saída para cada saída e depois use os botões Adicionar Coluna e Remover Coluna para gerenciar as colunas de saída para cada saída do componente de origem. Posteriormente, você fará referência às colunas de saída do seu script pelos nomes atribuídos aqui, usando as propriedades de acessador digitadas criadas para você no código gerado automaticamente.

• Talvez você queira criar uma ou mais saídas adicionais, tais 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 do componente de origem. Todas as linhas de entrada são direcionadas a todas as saídas disponíveis, a menos que você também especifique um valor idêntico diferente de zero para a propriedade ExclusionGroup das saídas onde você pretende direcionar cada linha a apenas uma das saídas que compartilham o mesmo valor ExclusionGroup. O valor de inteiro específico selecionado para identificar o ExclusionGroup não é significante.

  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. Porém, nesse caso, você deve chamar explicitamente o método DirectRowTo<outputbuffer> para cada linha a ser enviada à saída.

• Talvez você queira atribuir um nome amigável às saídas. Posteriormente, você fará referência às saídas pelos nomes no seu script, usando as propriedades de acessador digitadas, criadas para você no código gerado automaticamente.

• Em geral, várias saídas no mesmo ExclusionGroup têm as mesmas colunas de saída. Porém, se você estiver criando uma saída de erro simulada, talvez queira adicionar mais colunas para armazenar 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. No componente Script, contudo, escreva 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).

Caso existam variáveis cujos valores você deseja utilizar em seu script, será possível adicioná-las nos campos de propriedade ReadOnlyVariables e ReadWriteVariables da página Script do Editor de Transformação Scripts.

Ao inserir diversas variáveis nos campos de propriedade, separe os nomes delas por vírgulas. Outra alternativa é inserir diversas variáveis, clicando no botão de reticências (…) que fica ao lado dos campos de propriedade ReadOnlyVariables e ReadWriteVariables e, depois, 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 Scripts, consulte Editor de Transformação Scripts (página Script).

Quando você abrir o VSTA IDE depois de criar e configurar um componente de origem, a classe editável ScriptMain aparecerá no editor de códigos. Você escreve seu código personalizado na classe ScriptMain.

A classe ScriptMain inclui um stub para o método CreateNewOutputRows. O CreateNewOutputRows é o método mais importante em um componente de origem.

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 herda da classe UserComponent no item de projeto ComponentWrapper.

Em tempo de execução, o mecanismo de fluxo de dados invoca o método PrimeOutput na classe UserComponent, que substitui o método PrimeOutput da classe pai ScriptComponent. O método PrimeOutput, por sua vez, chama os seguintes métodos:

1. O método CreateNewOutputRows, que você substitui em ScriptMain para adicionar linhas da fonte de dados aos buffers de saída, que estão vazios no início.

2. O método FinishOutputs que está vazio por padrão. Substitua esse método em ScriptMain para executar qualquer processamento requerido para concluir a saída.

3. O método MarkOutputsAsFinished particular, que chama o método SetEndOfRowset da classe pai ScriptBuffer para indicar ao mecanismo de fluxo de dados que a saída está concluída. Você não precisa chamar o SetEndOfRowset explicitamente em seu próprio código.

Para terminar de criar um componente de origem personalizado, você pode 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 carregar dados, caso possa carregar todos os dados de origem ao mesmo tempo. Por exemplo, você pode executar um SqlCommand em relação à conexão ADO.NET para um banco de dados SQL Server e carregar todos os dados de origem ao mesmo tempo em um SqlDataReader. Se você precisar carregar os dados de origem em uma linha de cada vez (por exemplo, ao ler um arquivo de texto), poderá carregar os dados ao executar um loop nas linhas de CreateNewOutputRows.

3. Use o método CreateNewOutputRows substituído para adicionar novas linhas nos buffers de saída vazios e preencher os valores de cada coluna nas novas linhas de saída. Use o método AddRow de cada buffer de saída para adicionar uma linha nova vazia e, depois, defina os valores de cada coluna. Em geral, você copia valores das colunas carregadas a partir da origem externa.

4. Substitua o método PostExecute para concluir o processamento de dados. Por exemplo, você pode fechar o SqlDataReader usado para carregar dados.

5. Substitua o método ReleaseConnections para desconectar-se da fonte de dados externa, caso necessário.

Esse exemplo demonstra um componente de origem que usa um gerenciador de conexões ADO.NET existente para carregar dados de uma tabela SQL Server no fluxo de dados.

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

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

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

3. Abra o Editor de Transformação Scripts. Na página Entradas e Saídas, renomeie a saída padrão com um nome mais descritivo como MyAddressOutput, e adicione e configure as duas colunas de saída AddressID e City.

   Observação
   Verifique se você alterou o tipo de dados da coluna de saída City para DT_WSTR.

4. Na página Gerenciadores de Conexões, adicione ou crie o gerenciador de conexões ADO.NET e atribua a ele um nome como MyADONETConnection.

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, como, por exemplo, um destino SQL Server, ou o componente de destino de exemplo demonstrado em Criando um destino com o componente Script, que espera as colunas AddressID e City. Depois, conecte o componente de origem ao destino. (Você pode conectar uma origem diretamente a um destino, sem transformações.) É 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.

   Imports System.Data.SqlClient
   ...
   Public Class ScriptMain
       Inherits UserComponent
   
       Dim connMgr As IDTSConnectionManager100
       Dim sqlConn As SqlConnection
       Dim sqlReader As SqlDataReader
   
       Public Overrides Sub AcquireConnections(ByVal Transaction As Object)
   
           connMgr = Me.Connections.MyADONETConnection
           sqlConn = CType(connMgr.AcquireConnection(Nothing), SqlConnection)
   
       End Sub
   
       Public Overrides Sub PreExecute()
   
           Dim cmd As New SqlCommand("SELECT AddressID, City, StateProvinceID FROM Person.Address", sqlConn)
           sqlReader = cmd.ExecuteReader
   
       End Sub
   
       Public Overrides Sub CreateNewOutputRows()
   
           Do While sqlReader.Read
               With MyAddressOutputBuffer
                   .AddRow()
                   .AddressID = sqlReader.GetInt32(0)
                   .City = sqlReader.GetString(1)
               End With
           Loop
   
       End Sub
   
       Public Overrides Sub PostExecute()
   
           sqlReader.Close()
   
       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;
       SqlDataReader sqlReader;
   
       public override void AcquireConnections(object Transaction)
       {
           connMgr = this.Connections. MyADONETConnection;
           sqlConn = (SqlConnection)connMgr.AcquireConnection(null);
   
       }
   
       public override void PreExecute()
       {
   
           SqlCommand cmd = new SqlCommand("SELECT AddressID, City, StateProvinceID FROM Person.Address", sqlConn);
           sqlReader = cmd.ExecuteReader();
   
       }
   
       public override void CreateNewOutputRows()
       {
   
           while (sqlReader.Read())
           {
               {
                   MyAddressOutputBuffer.AddRow();
                   MyAddressOutputBuffer.AddressID = sqlReader.GetInt32(0);
                   MyAddressOutputBuffer.City = sqlReader.GetString(1);
               }
           }
   
       }
   
       public override void PostExecute()
       {
   
           sqlReader.Close();
   
       }
   
       public override void ReleaseConnections()
       {
   
           connMgr.ReleaseConnection(sqlConn);
   
       }
   
   }
   

Esse exemplo demonstra um componente de origem que usa um gerenciador de conexões de arquivos simples existente para carregar dados de um arquivo simples no fluxo de dados. Os dados de fonte de arquivo simples são criados através de sua exportação do SQL Server.

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

1. Use o Assistente de Importação e Exportação do SQL Server para exportar a tabela Person.Address do banco de dados de exemplo AdventureWorks2008R2 para um arquivo simples delimitado por vírgulas. Esse exemplo usa o nome de arquivo ExportedAddresses.txt.

2. Crie um gerenciador de conexões de arquivos simples que se conecta ao arquivo de dados exportado.

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

4. Abra o Editor de Transformação Scripts. Na página Entradas e Saídas, renomeie a saída padrão com um nome mais descritivo, como MyAddressOutput. Adicione e configure as duas colunas de saída, AddressID e City.

5. Na página Gerenciadores de Conexões, adicione ou crie o gerenciador de conexões de arquivos simples através de um nome descritivo como MyFlatFileSrcConnectionManager.

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 um componente de destino, como, por exemplo, um destino SQL Server, ou o componente de destino de exemplo demonstrado em Criando um destino com o componente Script. Depois, conecte o componente de origem ao destino. (Você pode conectar uma origem diretamente a um destino, sem transformações.) É 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
   )
   

8. Execute o exemplo.

   Imports System.IO
   ...
   Public Class ScriptMain
       Inherits UserComponent
   
       Private textReader As StreamReader
       Private exportedAddressFile As String
   
       Public Overrides Sub AcquireConnections(ByVal Transaction As Object)
   
           Dim connMgr As IDTSConnectionManager100 = _
               Me.Connections.MyFlatFileSrcConnectionManager
           exportedAddressFile = _
               CType(connMgr.AcquireConnection(Nothing), String)
   
       End Sub
   
       Public Overrides Sub PreExecute()
           MyBase.PreExecute()
           textReader = New StreamReader(exportedAddressFile)
       End Sub
   
       Public Overrides Sub CreateNewOutputRows()
   
           Dim nextLine As String
           Dim columns As String()
   
           Dim delimiters As Char()
           delimiters = ",".ToCharArray
   
           nextLine = textReader.ReadLine
           Do While nextLine IsNot Nothing
               columns = nextLine.Split(delimiters)
               With MyAddressOutputBuffer
                   .AddRow()
                   .AddressID = columns(0)
                   .City = columns(3)
               End With
               nextLine = textReader.ReadLine
           Loop
   
       End Sub
   
       Public Overrides Sub PostExecute()
           MyBase.PostExecute()
           textReader.Close()
   
       End Sub
   
   End Class
   

   using System.IO;
   public class ScriptMain:
       UserComponent
   
   {
       private StreamReader textReader;
       private string exportedAddressFile;
   
       public override void AcquireConnections(object Transaction)
       {
   
           IDTSConnectionManager100 connMgr = this.Connections.MyFlatFileSrcConnectionManager;
           exportedAddressFile = (string)connMgr.AcquireConnection(null);
   
       }
   
       public override void PreExecute()
       {
           base.PreExecute();
           textReader = new StreamReader(exportedAddressFile);
       }
   
       public override void CreateNewOutputRows()
       {
   
           string nextLine;
           string[] columns;
   
           char[] delimiters;
           delimiters = ",".ToCharArray();
   
           nextLine = textReader.ReadLine();
           while (nextLine != null)
           {
               columns = nextLine.Split(delimiters);
               {
                   MyAddressOutputBuffer.AddRow();
                   MyAddressOutputBuffer.AddressID = columns[0];
                   MyAddressOutputBuffer.City = columns[3];
               }
               nextLine = textReader.ReadLine();
           }
   
       }
   
       public override void PostExecute()
       {
   
           base.PostExecute();
           textReader.Close();
   
       }
   
   }