Codificando e depurando o componente Script

No Designer SSIS, o componente Script tem dois modos: modo de design de metadados e modo de design de código. Quando você abre o Editor de Transformação Scripts, o componente digita o modo de design de metadados no qual você configura metadados e define propriedades do componente. Depois de definir as propriedades do componente Script e configurar a entrada e as saídas em modo de design de metadados, você pode alternar para o modo de design de código para gravar seu script personalizado. Para obter mais informações sobre o modo de design de metadados e o modo de design de código, consulte Configurando o componente Script no Editor de Componentes de Script.

Escrevendo o Script em modo de design de código

Ambiente de desenvolvimento do componente Script

Para gravar seu script, clique em Editar Script na página Script do Editor de Transformação Scripts para abrir o Microsoft Visual Studio Tools for Applications (VSTA) IDE. O VSTA IDE inclui todos os recursos padrão do ambiente Visual Studio.NET, como o editor Visual Studio codificado por cor, o IntelliSense e o Pesquisador de Objetos.

O código de Script é escrito em Microsoft Visual Basic 2008 ou Microsoft Visual C# 2008. Você especifica a linguagem de script definindo a propriedade ScriptLanguage no Editor de Transformação Scripts. Caso prefira usar outra linguagem de programação, você pode desenvolver um assembly personalizado na linguagem de sua escolha e chamar sua funcionalidade do código no componente Script.

O script criado no componente Script é armazenado na definição do pacote. Não há arquivo de script separado. Portanto, o uso do componente Script não afeta a implantação do pacote.

Observação
Enquanto você projeta o pacote, o código de script é gravado temporariamente em um arquivo de projeto. Como o fato de armazenar informações confidenciais em um arquivo representa um potencial risco à segurança, recomendamos não incluir informações, como senhas, no código de script.

Por padrão, Option Strict fica desabilitado no IDE.

Estrutura do projeto do componente Script

O poder do componente Script reside em poder gerar código de infraestrutura que reduz a quantidade de códigos que você deve gravar. Esse recurso se baseia no fato de que entradas e saídas e suas colunas e propriedades são fixadas e conhecidas com antecedência. Portanto, qualquer alteração subsequente que você faça nos metadados do componente poderá invalidar o código que você gravou. Isso causa erros de compilação durante a execução do pacote.

Itens e classes de projeto no projeto do componente Script

Quando você alterna para o modo de design de código, o VSTA IDE abre e exibe o item de projeto ScriptMain. O item de projeto ScriptMain contém a classe ScriptMain editável, que serve como ponto de entrada para o script e fica onde você grava seu código. Os elementos de código na classe variam dependendo da linguagem de programação que você selecionou para a tarefa Script.

O projeto de script contém dois itens de projeto somente leitura adicionais gerados automaticamente:

• O item de projeto ComponentWrapper contém três classes:

  • A classe UserComponent, que herda de ScriptComponent e contém os métodos e propriedades que você vai usar para processar dados e interagir com o pacote. A classe ScriptMain herda da classe UserComponent.

  • Uma classe de coleção Connections que contém referências às conexões selecionadas na página Gerenciador de Conexões do Editor de Transformação Scripts.

  • Uma classe de coleção Variables que contém referências às variáveis inseridas nas propriedades ReadOnlyVariable e ReadWriteVariables na página Script do Editor de Transformação Scripts.

• O item de projeto BufferWrapper contém uma classe que herda do ScriptBuffer para cada entrada e saída configurada na página Entradas e Saídas do Editor de Transformação Scripts. Cada uma dessas classes contém propriedades de acessador digitadas que correspondem às colunas de entrada e saída configuradas e os buffers de fluxo de dados que contêm as colunas.

Para obter mais informações sobre como usar esses objetos, métodos e propriedades, consulte Compreendendo o Component Object Model Script. Para obter informações sobre como usar os métodos e propriedades dessas classes em um tipo específico de componente Script, consulte a seção Exemplos de componentes Script adicionais. Os tópicos de exemplo também contêm exemplos de código completos.

Quando você configura o componente Script como uma transformação, o item de projeto ScriptMain contém o seguinte código gerado automaticamente:

' Microsoft SQL Server Integration Services Script Component
' Write scripts using Microsoft Visual Basic 2008.
' ScriptMain is the entry point class of the script.

Imports System
Imports System.Data
Imports System.Math
Imports Microsoft.SqlServer.Dts.Pipeline.Wrapper
Imports Microsoft.SqlServer.Dts.Runtime.Wrapper

<Microsoft.SqlServer.Dts.Pipeline.SSISScriptComponentEntryPointAttribute> _
<CLSCompliant(False)> _
Public Class ScriptMain
    Inherits UserComponent

    Public Overrides Sub PreExecute()
        MyBase.PreExecute()
        '
        ' Add your code here for preprocessing or remove if not needed
        '
    End Sub

    Public Overrides Sub PostExecute()
        MyBase.PostExecute()
        '
        ' Add your code here for postprocessing or remove if not needed
        ' You can set read/write variables here, for example:
        ' Me.Variables.MyIntVar = 100
        '
    End Sub

    Public Overrides Sub Input0_ProcessInputRow(ByVal Row As Input0Buffer)
        '
        ' Add your code here
        '
    End Sub

End Class

/* Microsoft SQL Server Integration Services user script component
*  Write scripts using Microsoft Visual C# 2008.
*  ScriptMain is the entry point class of the script.*/

using System;
using System.Data;
using Microsoft.SqlServer.Dts.Pipeline.Wrapper;
using Microsoft.SqlServer.Dts.Runtime.Wrapper;

[Microsoft.SqlServer.Dts.Pipeline.SSISScriptComponentEntryPointAttribute]
public class ScriptMain : UserComponent
{

    public override void PreExecute()
    {
        base.PreExecute();
        /*
          Add your code here for preprocessing or remove if not needed
        */
    }

    public override void PostExecute()
    {
        base.PostExecute();
        /*
          Add your code here for postprocessing or remove if not needed
          You can set read/write variables here, for example:
          Variables.MyIntVar = 100
        */
    }

    public override void Input0_ProcessInputRow(Input0Buffer Row)
    {
        /*
          Add your code here
        */
    }

}

Itens de projeto adicionais no projeto do componente Script

O projeto do componente Script pode incluir itens diferentes do item ScriptMain padrão. Você pode adicionar classes, módulos, arquivos de código e pastas ao projeto, e você pode usar pastas para organizar grupos de itens.

Todos os itens que você adiciona persistem dentro do pacote.

Referências no projeto do componente Script

Você pode acrescentar referências a assemblies gerenciados clicando com o botão direito no projeto da tarefa Script no Explorador de Projeto e clicando em Adicionar Referência. Para obter mais informações, consulte Referenciando outros assemblies em soluções de script.

Observação
Você pode exibir as referências do projeto no VSTA IDE em Modo de Exibição de Classe ou em Explorador de Projeto. É possível abrir qualquer uma dessas janelas no menu Exibir. Você pode adicionar uma referência nova no menu Projeto, de Explorador de Projeto ou de Modo de Exibição de Classe.

Interagindo com o pacote no componente Script

O script personalizado que você grava no componente Script pode acessar e usar variáveis e gerenciadores de conexões do pacote que os contém através de acessadores de tipo mais acentuado nas classes base geradas automaticamente. Contudo, você deve configurar as variáveis e os gerenciadores de conexões antes de digitar o modo de design de código, se quiser disponibilizá-los para seu script. Você também pode gerar eventos e executar log do código do componente Script.

Os itens de projeto gerados automaticamente no projeto do componente Script fornecem os seguintes objetos, métodos e propriedades para interagir com o pacote.

Recurso do Pacote	Método de Acesso
Variáveis	Use as propriedades nomeadas e digitadas do acessador na classe de coleção Variables no item de projeto ComponentWrapper, expostas através da propriedade Variables da classe ScriptMain. O método PreExecute só pode acessar variáveis somente leitura. O método PostExecute pode acessar variáveis somente leitura e de leitura/gravação.
Conexões	Use as propriedades nomeadas e digitadas do acessador na classe de coleção Connections no item de projeto ComponentWrapper, expostas através da propriedade Connections da classe ScriptMain.
Eventos	Gere eventos usando a propriedade ComponentMetaData da classe ScriptMain e os métodos Fire<X> da interface IDTSComponentMetaData100.
Log	Execute log usando o método Log da classe ScriptMain.

Depurando o componente Script

O componente Script não suporta o uso de pontos de interrupção. Portanto, você não pode percorrer seu código e examinar valores enquanto o pacote é executado. Você pode monitorar a execução do componente Script usando os métodos seguintes:

• Interrompa a execução e exiba uma mensagem modal usando o método MessageBox.Show no namespace System.Windows.Forms. (Remova esse código após concluir o processo de depuração).

• Gere eventos para mensagens informativas, advertências e erros. Os métodos FireInformation, FireWarning e FireError exibem a descrição do evento na janela Saída do Visual Studio. Porém, o método FireProgress, o método Console.Write e o método Console.WriteLine não exibem qualquer informação na janela Saída. Mensagens do evento FireProgress aparecem na guia Progresso do SSIS Designer. Para obter mais informações, consulte Gerando eventos no componente Script.

• Eventos de log ou mensagens definidas pelo usuário para provedores de log habilitados. Para obter mais informações, consulte Registrando o componente Script.

Caso queira apenas examinar a saída de um componente Script configurado como uma origem ou uma transformação, sem salvar os dados em um destino, você pode parar o fluxo de dados com um Transformação Contagem de Linhas e anexar um visualizador de dados à saída do componente Script. Para obter informações sobre visualizadores de dados, consulte Depurando fluxo de dados.

Nesta seção

Para obter mais informações sobre como codificar o componente Script, consulte os tópicos seguintes nesta seção.

• Compreendendo o Component Object Model Script
  Explica como usar os objetos, métodos e propriedades disponíveis no componente Script.

• Referenciando outros assemblies em soluções de script
  Explica como referenciar objetos da biblioteca de classes .NET Framework no componente Script.

• Simulando uma saída de erro para o componente Script
  Explica como simular uma saída de erro para linhas que geram erros durante o processamento pelo componente Script.

Recursos externos

• Entrada de blog, Problemas de instalação e configuração de VSTA nas instalações de SSIS 2008 e R2, em blogs.msdn.com.

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

Consulte também

Conceitos

Configurando o componente Script no Editor de Componentes de Script