Criando um código-fonte com o componente Script

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

Utiliza-se um componente de origem no fluxo de dados de um pacote de Serviços de Integração para carregar dados de uma fonte de dados e passar para transformações e destinos a jusante. Normalmente, liga-se à fonte de dados através de um gestor de ligação já existente.

Para uma visão geral do componente Script, veja Extensão do Fluxo de Dados com o Componente Script.

O componente Script e o código de infraestrutura que gera para si simplificam significativamente o processo de desenvolvimento de um componente personalizado de fluxo de dados. No entanto, para compreender como funciona o componente Script, pode ser útil ler os passos envolvidos no desenvolvimento de um componente personalizado de fluxo de dados. Consulte a secção Desenvolvimento de um Componente de Fluxo de Dados Personalizado, especialmente o tópico Desenvolvimento de um Componente de Fonte Personalizado.

Começar com um Componente Source

Quando adiciona um componente de Script ao painel de Fluxo de Dados do SSIS Designer, a caixa de diálogo Selecionar Tipo de Componente de Script abre-se e pede para selecionar um script de Origem, Destino ou Transformação. Nesta caixa de diálogo, selecione Fonte.

Configuração de um Componente de Origem em Modo Metadata-Design

Depois de selecionar a criação de um componente de origem, configura o componente usando o Script Transformation Editor. Para mais informações, consulte Configurar o Componente de Script no Editor de Componentes de Script.

Um componente fonte de fluxo de dados não tem entradas e suporta uma ou mais saídas. Configurar as saídas do componente é um dos passos que deve completar no modo de design de metadados, usando o Script Transformation Editor, antes de escrever o seu script personalizado.

Também pode especificar a linguagem de scripts definindo a propriedade ScriptLanguage na página Script do Script Transformation Editor.

Observação

Para definir a linguagem de script padrão para componentes de script e tarefas de script, use a opção Linguagem de Scripting na página Geral da caixa de diálogo Opções . Para mais informações, consulte a Página Geral.

Adição de Gestores de Ligação

Normalmente, um componente de origem utiliza um gestor de ligação existente para se ligar à fonte de dados a partir da qual carrega dados para o fluxo de dados. Na página de Gestores de Ligação do Editor de Transformação de Scripts, clique em Adicionar para adicionar o gestor de conexões apropriado.

No entanto, um gestor de ligação é apenas uma unidade conveniente que encapsula e armazena a informação necessária para se ligar a uma fonte de dados de um determinado tipo. Deves escrever o teu próprio código personalizado para carregar ou guardar os teus dados, e possivelmente também para abrir e fechar a ligação à fonte de dados.

Para informações gerais sobre como usar gestores de ligação com o componente Script, consulte Ligar a Fontes de Dados no Componente Script.

Para mais informações sobre a página de Gestores de Ligação do Editor de Transformação de Scripts, consulte Editor de Transformação de Scripts (Página de Gestores de Ligações).

Configuração de Saídas e Colunas de Saída

Um componente fonte não tem entradas e suporta uma ou mais saídas. Na página de Entradas e Saídas do Editor de Transformação de Scripts, uma única saída foi criada por defeito, mas nenhuma coluna de saída foi criada. Nesta página do editor, pode precisar ou querer configurar os seguintes itens.

Tens de adicionar e configurar manualmente as colunas de saída 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 gerir as colunas de saída de cada saída do componente de origem. Mais tarde, refere-se às colunas de saída no seu script pelos nomes que atribui aqui, usando as propriedades de acessório digitadas criadas para si no código gerado automaticamente.
Pode querer criar uma ou mais saídas adicionais, como uma saída de erro simulada para linhas que contenham valores inesperados. Use os botões Adicionar Saída e Remover Saída para gerir as saídas do componente de origem. Todas as linhas de entrada são direcionadas para todas as saídas disponíveis, a menos que também especifique um valor idêntico não nulo para a propriedade ExclusionGroup dessas saídas, onde pretende direcionar cada linha para apenas uma das saídas que partilham o mesmo valor ExclusionGroup . O valor inteiro particular selecionado para identificar o Grupo de Exclusão não é significativo.

Observação

Também pode usar um valor de propriedade ExclusionGroup não nulo com uma única saída quando não quiser exportar todas as linhas. Neste caso, no entanto, deve chamar explicitamente o método DirectRowTo<outputbuffer> para cada linha que pretende enviar para a saída.
Pode querer atribuir um nome amigável às saídas. Mais tarde, refere-se às saídas pelos seus nomes no seu script, usando as propriedades digitadas do acessório criadas para si no código gerado automaticamente.
Normalmente, múltiplas saídas no mesmo Grupo de Exclusão têm as mesmas colunas de saída. No entanto, se estiver a criar uma saída de erro simulada, pode querer adicionar mais colunas para armazenar a informação do erro. Para informações sobre como o motor de fluxo de dados processa linhas de erro, veja Utilização de Saídas de Erro num Componente de Fluxo de Dados. No componente Script, no entanto, deve escrever o seu próprio código para preencher as colunas adicionais com a informação de erro apropriada. Para mais informações, veja Simulação de uma Saída de Erro para o Componente de Script.

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

Adição de variáveis

Se existirem variáveis existentes cujos valores queiras usar no teu script, podes adicioná-las nos campos de propriedades ReadOnlyVariables e ReadWriteVariables na página Script do Script Transformation Editor.

Quando inserires várias variáveis nos campos de propriedades, separa os nomes das variáveis por vírgulas. Também pode introduzir várias variáveis clicando no botão de reticências (...) ao lado dos campos de propriedades ReadOnlyVariables e ReadWriteVariables e selecionando variáveis na caixa de diálogo Selecionar variáveis .

Para informações gerais sobre como usar variáveis com o componente Script, consulte Utilização de Variáveis no Componente Script.

Para mais informações sobre a página de Script do Script Transformation Editor, consulte Script Transformation Editor (Script Page).

Scripting de um componente de origem em modo Code-Design

Depois de configurar os metadados do seu componente, abra o Microsoft Visual Studio Tools for Applications (VSTA) IDE para programar o seu script personalizado. Para abrir o VSTA, clique em Editar Script na página de Script do Script Transformation Editor. Pode escrever o seu script usando Microsoft Visual Basic ou Microsoft Visual C#, dependendo da linguagem de script selecionada para a propriedade ScriptLanguage .

Para informações importantes que se aplicam a todos os tipos de componentes criados usando o componente Script, veja Codificação e Depuração do Componente Script.

Compreender o Código Gerado Automaticamente

Quando abres o IDE VSTA depois de criares e configurares um componente fonte, a classe editável ScriptMain aparece no editor de código. Escreves o teu código personalizado na classe ScriptMain .

A classe ScriptMain inclui um stub para o método CreateNewOutputRows . O CreateNewOutputRows é o método mais importante num componente de código-fonte.

Se abrires a janela do Project Explorer no VSTA, podes ver que o componente Script também gerou itens de projeto BufferWrapper e ComponentWrapper apenas de leitura. A classe ScriptMain herda da classe UserComponent no item do projeto ComponentWrapper .

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

O método CreateNewOutputRows , que se sobrepõe no ScriptMain para adicionar linhas da fonte de dados aos buffers de saída, que inicialmente estão vazios.
O método FinishOutputs , que está vazio por defeito. Substitua este método no ScriptMain para realizar qualquer processamento necessário para completar a saída.
O método privado MarkOutputsAsFinified , que chama o SetEndOfRowset método da ScriptBuffer classe mãe para indicar ao motor de fluxo de dados que a saída está concluída. Não tens de chamar SetEndOfRowset explicitamente no teu próprio código.

Escrever o Seu Código Personalizado

Para terminar de criar um componente fonte personalizado, pode querer escrever scripts nos seguintes métodos disponíveis na classe ScriptMain .

Substitua o método AcquireConnections para se ligar à fonte de dados externa. Extraia o objeto de ligação, ou a informação de ligação necessária, do gestor de ligações.
Sobrescrita o método PreExecute para carregar os dados, se conseguires carregar todos os dados de origem ao mesmo tempo. Por exemplo, pode executar um SqlCommand numa ligação ADO.NET a uma base de dados SQL Server e carregar todos os dados de origem ao mesmo tempo num SqlDataReader. Se tiver de carregar os dados de origem uma linha de cada vez (por exemplo, ao ler um ficheiro de texto), pode carregar os dados enquanto percorre linhas no CreateNewOutputRows.
Use o método sobreposto CreateNewOutputRows para adicionar novas linhas aos 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 nova linha vazia e depois defina os valores de cada coluna. Normalmente, copia-se valores das colunas carregadas da fonte externa.
Substitua o método PostExecute para terminar o processamento dos dados. Por exemplo, pode fechar o SqlDataReader que usou para carregar dados.
Substitua o método ReleaseConnections para desligar da fonte de dados externa, se necessário.

Exemplos

Os exemplos seguintes demonstram o código personalizado necessário na classe ScriptMain para criar um componente fonte.

Observação

Estes exemplos utilizam a tabela Person.Address na base de dados de exemplos AdventureWorks e passam a primeira e quarta colunas, as colunas intAddressID e nvarchar(30)City , pelo fluxo de dados. Os mesmos dados são usados nas amostras de origem, transformação e destino nesta secção. Pré-requisitos e pressupostos adicionais são documentados para cada exemplo.

ADO.NET Exemplo de Fonte

Este exemplo demonstra um componente de origem que utiliza um gestor de conexões ADO.NET existente para carregar dados de uma tabela SQL Server para o fluxo de dados.

Se quiser executar este código de exemplo, deve configurar o pacote e o componente da seguinte forma:

Crie um gestor de ligações ADO.NET que utilize o fornecedor SqlClient para se ligar à base de dados AdventureWorks .
Adicione um novo componente Script à superfície do Data Flow designer e configure-o como fonte.
Abre o Editor de Transformação de Scripts. Na página de 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

Certifique-se de alterar o tipo de dados da coluna de saída da Cidade para DT_WSTR.
Na página de Gestores de Ligações , adicione ou crie o gestor de conexões ADO.NET e dei-lhe um nome como MyADONETConnection.
Na página de Guião , clique em Editar Guião e insira o guião que se segue. Depois fecha o ambiente de desenvolvimento de scripts e o Editor de Transformação de Scripts.
Crie e configure um componente de destino, como um destino SQL Server, ou o componente de destino de exemplo demonstrado em Criar um Destino com o Componente Script, que espera as colunas AddressID e City . Depois liga o componente de origem ao destino. (Pode ligar uma fonte diretamente a um destino sem quaisquer transformações.) Pode criar uma tabela de destino executando o seguinte comando Transact-SQL na base de dados AdventureWorks :
```
CREATE TABLE [Person].[Address2]([AddressID] [int] NOT NULL,  
    [City] [nvarchar](30) NOT NULL)  
```

Execute o exemplo.

Imports Microsoft.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 Microsoft.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);  

    }  

}

Exemplo de Fonte de Ficheiro Plano

Este exemplo demonstra um componente de origem que utiliza um gestor de ligação Flat File existente para carregar dados de um flat file para o fluxo de dados. Os dados de origem do ficheiro plano são criados exportando-os a partir do SQL Server.