Codificando e depurando a tarefa Script

Artigo
05/23/2023

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

Depois de configurar a tarefa Script no Editor da Tarefa Script, você escreve seu código personalizado no ambiente de desenvolvimento da tarefa Script.

Ambiente de desenvolvimento da tarefa Script

A tarefa Script usa o Microsoft Visual Studio VSTA (Tools for Applications) como o ambiente de desenvolvimento do script propriamente dito.

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

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

Observação

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

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

Estrutura do projeto da tarefa Script

Quando você cria ou modifica o script contido em uma tarefa Script, o VSTA abre um novo projeto vazio ou reabre o projeto existente. A criação desse projeto VSTA não afeta a implantação do pacote, pois o projeto é salvo dentro do arquivo de pacote; a tarefa Script não cria arquivos adicionais.

Itens e classes de projeto no projeto da tarefa Script

Por padrão, o projeto da tarefa Script exibido na janela Explorador de Projeto VSTA contém um único item, ScriptMain. O item ScriptMain, por sua vez, contém uma única classe, também nomeada ScriptMain. Os elementos de código na classe variam de acordo com a linguagem de programação selecionada para a tarefa Script:

Quando a tarefa Script é configurada para a linguagem de programação Visual Basic, a classe ScriptMain tem uma sub-rotina pública, Main. A sub-rotina ScriptMain.Main é o método que o runtime chama quando você executa sua tarefa Script.

Por padrão, o único código na sub-rotina Main de um script novo é a linha Dts.TaskResult = ScriptResults.Success. Essa linha informa o runtime em que a tarefa teve êxito em sua operação. A propriedade Dts.TaskResult é abordada em Retornando resultados da tarefa Script.
Quando a tarefa Script é configurada para a linguagem de programação Visual C#, a classe ScriptMain tem um método público, Main. O método é chamado quando a tarefa Script é executada.

Por padrão, o método Main inclui a linha Dts.TaskResult = (int)ScriptResults.Success. Essa linha informa o runtime em que a tarefa teve êxito em sua operação.

O item ScriptMain pode conter classes diferentes da classe ScriptMain. Classes só estão disponíveis à tarefa Script na qual elas residem.

Por padrão, o item de projeto ScriptMain contém o código a seguir gerado automaticamente. O modelo de código também fornece uma visão geral da tarefa Script e informações adicionais sobre como recuperar e manipular objetos SSIS, como variáveis, eventos e conexões.

' Microsoft SQL Server Integration Services Script Task  
' Write scripts using Microsoft Visual Basic 2008.  
' The ScriptMain is the entry point class of the script.  
  
Imports System  
Imports System.Data  
Imports System.Math  
Imports Microsoft.SqlServer.Dts.Runtime.VSTAProxy  
  
<System.AddIn.AddIn("ScriptMain", Version:="1.0", Publisher:="", Description:="")> _  
Partial Class ScriptMain  
  
Private Sub ScriptMain_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup  
  
End Sub  
  
Private Sub ScriptMain_Shutdown(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Shutdown  
Try  
' Unlock variables from the read-only and read-write variable collection properties  
If (Dts.Variables.Count <> 0) Then  
Dts.Variables.Unlock()  
End If  
Catch ex As Exception  
        End Try  
End Sub  
  
Enum ScriptResults  
Success = DTSExecResult.Success  
Failure = DTSExecResult.Failure  
End Enum  
  
' The execution engine calls this method when the task executes.  
' To access the object model, use the Dts property. Connections, variables, events,  
' and logging features are available as members of the Dts property as shown in the following examples.  
'  
' To reference a variable, call Dts.Variables("MyCaseSensitiveVariableName").Value  
' To post a log entry, call Dts.Log("This is my log text", 999, Nothing)  
' To fire an event, call Dts.Events.FireInformation(99, "test", "hit the help message", "", 0, True)  
'  
' To use the connections collection use something like the following:  
' ConnectionManager cm = Dts.Connections.Add("OLEDB")  
' cm.ConnectionString = "Data Source=localhost;Initial Catalog=AdventureWorks;Provider=SQLNCLI10;Integrated Security=SSPI;Auto Translate=False;"  
'  
' Before returning from this method, set the value of Dts.TaskResult to indicate success or failure.  
'   
' To open Help, press F1.  
  
Public Sub Main()  
'  
' Add your code here  
'  
Dts.TaskResult = ScriptResults.Success  
End Sub  
  
End Class

/*  
   Microsoft SQL Server Integration Services Script Task  
   Write scripts using Microsoft Visual C# 2008.  
   The ScriptMain is the entry point class of the script.  
*/  
  
using System;  
using System.Data;  
using Microsoft.SqlServer.Dts.Runtime.VSTAProxy;  
using System.Windows.Forms;  
  
namespace ST_1bcfdbad36d94f8ba9f23a10375abe53.csproj  
{  
    [System.AddIn.AddIn("ScriptMain", Version = "1.0", Publisher = "", Description = "")]  
    public partial class ScriptMain  
    {  
        private void ScriptMain_Startup(object sender, EventArgs e)  
        {  
  
        }  
  
        private void ScriptMain_Shutdown(object sender, EventArgs e)  
        {  
            try  
            {  
                // Unlock variables from the read-only and read-write variable collection properties  
                if (Dts.Variables.Count != 0)  
                {  
                    Dts.Variables.Unlock();  
                }  
            }  
            catch  
            {  
            }  
        }  
  
        #region VSTA generated code  
        private void InternalStartup()  
        {  
            this.Startup += new System.EventHandler(ScriptMain_Startup);  
            this.Shutdown += new System.EventHandler(ScriptMain_Shutdown);  
        }  
        enum ScriptResults  
        {  
            Success = DTSExecResult.Success,  
            Failure = DTSExecResult.Failure  
        };  
  
        #endregion  
  
        /*  
The execution engine calls this method when the task executes.  
To access the object model, use the Dts property. Connections, variables, events,  
and logging features are available as members of the Dts property as shown in the following examples.  
  
To reference a variable, call Dts.Variables["MyCaseSensitiveVariableName"].Value;  
To post a log entry, call Dts.Log("This is my log text", 999, null);  
To fire an event, call Dts.Events.FireInformation(99, "test", "hit the help message", "", 0, true);  
  
To use the connections collection use something like the following:  
ConnectionManager cm = Dts.Connections.Add("OLEDB");  
cm.ConnectionString = "Data Source=localhost;Initial Catalog=AdventureWorks;Provider=SQLNCLI10;Integrated Security=SSPI;Auto Translate=False;";  
  
Before returning from this method, set the value of Dts.TaskResult to indicate success or failure.  
  
To open Help, press F1.  
*/  
  
        public void Main()  
        {  
            // TODO: Add your code here  
            Dts.TaskResult = (int)ScriptResults.Success;  
        }  
    }

Itens de projeto adicionais no projeto da tarefa Script

O projeto da tarefa Script pode incluir itens que não sejam o item padrão ScriptMain. Você pode adicionar classes, módulos e arquivos de código ao projeto. Você também pode usar pastas para organizar grupos de itens. Todos os itens que você adiciona persistem dentro do pacote.

Referências no projeto da tarefa Script

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

Observação

Você pode exibir as referências do projeto no IDE VSTA no Modo de Exibição de Classe ou no 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 na tarefa Script

A tarefa Script usa o objeto global Dts, que é uma instância da classe ScriptObjectModel e de seus membros para interagir com o pacote que a contém e com o runtime do Integration Services.

A tabela a seguir lista os membros públicos principais da classe ScriptObjectModel, que é exposta ao código da tarefa Script através do objeto global Dts. Os tópicos dessa seção apresentam uma discussão detalhada sobre o uso desses membros.

Membro	Finalidade
Connections	Fornece acesso a gerenciadores de conexões definidos no pacote.
Events	Fornece uma interface de eventos para deixar a tarefa Script gerar erros, avisos e mensagens informativas.
ExecutionValue	Apresenta uma forma simples de retornar um único objeto ao runtime (além do TaskResult) que também pode ser usado para a ramificação de fluxos de trabalho.
Log	Registra informações tais como o progresso da tarefa e resultados para provedores de log habilitados.
TaskResult	Reporta o êxito ou falha da tarefa.
Transaction	Fornece a transação, caso exista, dentro da qual o contêiner da tarefa está em execução.
Variables	Fornece acesso às variáveis listadas nas propriedades de tarefa ReadOnlyVariables e ReadWriteVariables para uso dentro do script.

A classe ScriptObjectModel também contém alguns membros públicos que você provavelmente não usará.

Membro	DESCRIÇÃO
VariableDispenser	A propriedade Variables fornece acesso mais conveniente a variáveis. Embora você possa usar o VariableDispenser, chame explicitamente métodos para bloquear e desbloquear variáveis para leitura e gravação. A tarefa Script trata de semânticas de bloqueio quando você usa a propriedade Variables.

Depurando a tarefa Script

Para depurar o código na sua tarefa Script, defina pelo menos um ponto de interrupção no código e, depois, feche o VSTA IDE para executar o pacote no SQL Server Data Tools (SSDT). Quando a execução do pacote insere a tarefa Script, o VSTA IDE é reaberto e exibe seu código em modo somente leitura. Depois que a execução atingir seu ponto de interrupção, você poderá examinar valores de variáveis e passar pelo código restante.

Aviso

Você não pode depurar a tarefa Script quando executar o pacote no modo de 64 bits.

Observação

Execute o pacote para depurar em sua tarefa Script. Se você executar apenas a tarefa individual, os pontos de interrupção no código da tarefa Script serão ignorados.

Observação

Você não pode depurar uma tarefa Script quando executa-a como parte de um pacote filho que é executado a partir de uma tarefa Executar Pacote. Nessas circunstâncias, os pontos de interrupção definidos na tarefa Script no pacote filho são desconsiderados. Você pode depurar o pacote filho normalmente, executando-o separadamente.

Observação

Quando você depura um pacote que contém várias tarefas Script, o depurador depura uma tarefa Script. O sistema poderá depurar outra tarefa Script se o depurador for concluído, como no caso de um contêiner Loop Foreach ou Loop For.

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.

Consulte Também

Referenciar outros assemblies em soluções de script
Configurando a tarefa Script no Editor da Tarefa Script

Compartilhar via

Codificando e depurando a tarefa Script

Ambiente de desenvolvimento da tarefa Script

Estrutura do projeto da tarefa Script

Itens e classes de projeto no projeto da tarefa Script

Itens de projeto adicionais no projeto da tarefa Script

Referências no projeto da tarefa Script

Interagindo com o pacote na tarefa Script

Depurando a tarefa Script

Recursos externos

Consulte Também

Comentários

Recursos adicionais