Codificando uma tarefa personalizada

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

Depois de criar uma classe que herda da classe base Microsoft.SqlServer.Dts.Runtime.Task e aplicar o DtsTaskAttribute atributo à classe, você deve substituir a implementação das propriedades e métodos da classe base para fornecer sua funcionalidade personalizada.

Configurando a tarefa

Validando a tarefa

Ao criar um pacote do Integration Services, você pode usar a validação para verificar as configurações em cada tarefa, de modo que possa detetar configurações incorretas ou inadequadas assim que elas forem definidas, em vez de localizar todos os erros somente em tempo de execução. O objetivo da validação é determinar se a tarefa contém configurações inválidas ou conexões que impedirão que ela seja executada com êxito. Isso garante que o pacote contenha tarefas que tenham uma boa chance de serem executadas em sua primeira execução.

Você pode implementar a validação usando o método Validate no código personalizado. O mecanismo de tempo de execução valida uma tarefa chamando o método Validate na tarefa. É responsabilidade do desenvolvedor da tarefa definir os critérios que lhe dão uma validação de tarefa bem-sucedida ou falhada e notificar o mecanismo de tempo de execução do resultado dessa avaliação.

Classe base abstrata de tarefa

A classe base abstrata Microsoft.SqlServer.Dts.Runtime.Task fornece o método Validate que cada tarefa substitui para definir seus critérios de validação. O Designer SSIS chama automaticamente o método Validate várias vezes durante o design do pacote e fornece pistas visuais ao usuário quando ocorrem avisos ou erros para ajudar a identificar problemas com a configuração da tarefa. As tarefas fornecem resultados de validação retornando um valor da enumeração e gerando eventos de DTSExecResult aviso e erro. Esses eventos contêm informações que são exibidas para o usuário no Designer SSIS.

Seguem-se alguns exemplos de validação:

• Um gerenciador de conexões valida o nome de arquivo específico.

• Um gerenciador de conexões valida se o tipo de entrada é o tipo esperado, como um arquivo XML.

• Uma tarefa que espera a entrada do banco de dados verifica se não pode receber dados de uma conexão que não seja de banco de dados.

• Uma tarefa garante que nenhuma de suas propriedades contradiga outras propriedades definidas na mesma tarefa.

• Uma tarefa garante que todos os recursos necessários usados pela tarefa no tempo de execução estejam disponíveis.

O desempenho é algo a considerar para determinar o que é validado e o que não é. Por exemplo, a entrada para uma tarefa pode ser uma conexão através de uma rede que tem baixa largura de banda ou tráfego pesado. A validação pode levar vários segundos para ser processada se você decidir validar que o recurso está disponível. Outra validação pode causar uma viagem de ida e volta para um servidor que está em alta demanda, e a rotina de validação pode ser lenta. Embora existam muitas propriedades e configurações que podem ser validadas, nem tudo deve ser validado.

• O código no método Validate também é chamado pelo antes de a tarefa ser executada TaskHost e cancela a execução se a TaskHost validação falhar.

Considerações sobre a interface do usuário durante a validação

O Microsoft.SqlServer.Dts.Runtime.Task inclui uma IDTSComponentEvents interface como parâmetro para o método Validate . A IDTSComponentEvents interface contém os métodos que são chamados pela tarefa para gerar eventos para o mecanismo de tempo de execução. Os FireWarning métodos e FireError são chamados quando ocorre uma condição de aviso ou erro durante a validação. Ambos os métodos de aviso exigem os mesmos parâmetros, que incluem um código de erro, componente de origem, descrição, arquivo de Ajuda e informações de contexto da Ajuda. O Designer SSIS usa essas informações para exibir pistas visuais na superfície de design. As pistas visuais fornecidas pelo designer incluem um ícone de exclamação que aparece ao lado da tarefa na superfície do designer. Esta sugestão visual sinaliza ao usuário que a tarefa requer configuração adicional antes que a execução possa continuar.

O ícone de exclamação também exibe uma dica de ferramenta que contém uma mensagem de erro. A mensagem de erro é fornecida pela tarefa no parâmetro description do evento. As mensagens de erro também são exibidas no painel Lista de Tarefas do SSDT (SQL Server Data Tools), fornecendo ao usuário um local central para exibir todos os erros de validação.

Exemplo de validação

O exemplo de código a seguir mostra uma tarefa com uma propriedade UserName . Esta propriedade foi especificada como necessária para que a validação seja bem-sucedida. Se a propriedade não estiver definida, a tarefa lançará um erro e retornará Failure da DTSExecResult enumeração. O método Validate é encapsulado em um bloco try/catch e falha na validação se ocorrer uma exceção.

using System;  
using Microsoft.SqlServer.Dts.Runtime;  
  
public class SampleTask : Task  
{  
  private string userName = "";  
  
  public override DTSExecResult Validate(Connections connections,  
     VariableDispenser variableDispenser, IDTSComponentEvents events,  
     IDTSLogging log)  
  {  
    try  
    {  
      if (this.userName == "")  
      {  
        //   Raise an OnError event.  
        events.FireError(0, "SampleTask", "The UserName property must be configured.", "", 0);  
        //   Fail validation.  
        return DTSExecResult.Failure;  
      }  
      //   Return success.  
      return DTSExecResult.Success;  
    }  
    catch (System.Exception exception)  
    {  
      //   Capture exceptions, post an error, and fail validation.  
      events.FireError(0, "Sampletask", exception.Message, "", 0);  
      return DTSExecResult.Failure;  
    }  
  }  
  public string UserName  
  {  
    get  
    {  
      return this.userName;  
    }  
    set  
    {  
      this.userName = value;  
    }  
  }  
}  

Imports System  
Imports Microsoft.SqlServer.Dts.Runtime  
  
Public Class SampleTask  
  Inherits Task  
  
  Private _userName As String = ""  
  
  Public Overrides Function Validate(ByVal connections As Connections, _  
     ByVal variableDispenser As VariableDispenser, _  
     ByVal events As IDTSComponentEvents, _  
     ByVal log As IDTSLogging) As DTSExecResult  
  
    Try  
      If Me._userName = "" Then  
        '   Raise an OnError event.  
        events.FireError(0, "SampleTask", "The UserName property must be configured.", "", 0)  
        '   Fail validation.  
        Return DTSExecResult.Failure  
      End If  
      '   Return success.  
      Return DTSExecResult.Success  
    Catch exception As System.Exception  
      '   Capture exceptions, post an error, and fail validation.  
      events.FireError(0, "Sampletask", exception.Message, "", 0)  
      Return DTSExecResult.Failure  
    End Try  
  
  End Function  
  
  Public Property UserName() As String  
    Get  
      Return Me._userName  
    End Get  
    Set(ByVal Value As String)  
      Me._userName = Value  
    End Set  
  End Property  
  
End Class  

Persistindo a tarefa

Normalmente, você não precisa implementar persistência personalizada para uma tarefa. A persistência personalizada é necessária somente quando as propriedades de um objeto usam tipos de dados complexos. Para obter mais informações, consulte Desenvolvendo objetos personalizados para o Integration Services.

Executando a tarefa

Esta seção descreve como usar o método Execute que é herdado e substituído por tarefas. Esta seção também explica várias maneiras de fornecer informações sobre os resultados da execução de tarefas.

Método Execute

As tarefas contidas em um pacote são executadas quando o tempo de execução do Integration Services chama seu método Execute . As tarefas implementam sua lógica de negócios principal e funcionalidade nesse método e fornecem os resultados da execução postando mensagens, retornando um valor da DTSExecResult enumeração e substituindo a propriedade get da propriedade ExecutionValue .

A classe base Microsoft.SqlServer.Dts.Runtime.Task fornece uma implementação padrão do Execute método. As tarefas personalizadas substituem esse método para definir sua funcionalidade de tempo de execução. O TaskHost objeto encapsula a tarefa, isolando-a do mecanismo de tempo de execução e dos outros objetos no pacote. Devido a esse isolamento, a tarefa não está ciente de sua localização no pacote em relação à sua ordem de execução e é executada somente quando é chamada pelo tempo de execução. Essa arquitetura evita problemas que podem ocorrer quando tarefas modificam o pacote durante a execução. A tarefa é fornecida acesso aos outros objetos no pacote somente através dos objetos fornecidos a ela como parâmetros no Execute método. Esses parâmetros permitem que as tarefas gerem eventos, gravem entradas no log de eventos, acessem a coleta de variáveis e alistem conexões com fontes de dados em transações, mantendo o isolamento necessário para garantir a estabilidade e a confiabilidade do pacote.

A tabela a seguir lista os parâmetros fornecidos para a tarefa no Execute método.

Fornecendo feedback de execução

As tarefas encapsulam seu código em blocos try/catch para evitar que exceções sejam aumentadas para o mecanismo de tempo de execução. Isso garante que o pacote termine a execução e não pare inesperadamente. No entanto, o mecanismo de tempo de execução fornece outros mecanismos para lidar com condições de erro que podem ocorrer durante a execução de uma tarefa. Isso inclui postar mensagens de erro e aviso, retornar um valor da DTSExecResult estrutura, postar mensagens, retornar o DTSExecResult valor e divulgar informações sobre os resultados da execução da tarefa por meio da ExecutionValue propriedade.

A IDTSComponentEvents interface contém os FireWarning métodos and FireError , que podem ser chamados pela tarefa para postar mensagens de erro e aviso para o mecanismo de tempo de execução. Ambos os métodos exigem parâmetros como o código de erro, o componente de origem, a descrição, o arquivo de Ajuda e as informações de contexto da ajuda. Dependendo da configuração da tarefa, o tempo de execução responde a essas mensagens gerando eventos e pontos de interrupção ou gravando informações no log de eventos.

O TaskHost também fornece a ExecutionValue propriedade que pode ser usada para fornecer informações adicionais sobre os resultados da execução. Por exemplo, se uma tarefa excluir linhas de uma tabela como parte de seu método Execute , ela poderá retornar o número de linhas excluídas como o valor da ExecutionValue propriedade. Além disso, o TaskHost fornece o ExecValueVariable imóvel. Essa propriedade permite que o usuário mapeie o ExecutionValue retorno da tarefa para qualquer variável visível para a tarefa. A variável especificada pode então ser usada para estabelecer restrições de precedência entre tarefas.

Exemplo de execução

O exemplo de código a seguir demonstra uma implementação do método Execute e mostra uma propriedade ExecutionValue substituída. A tarefa exclui o arquivo especificado pela propriedade fileName da tarefa. A tarefa publica um aviso se o arquivo não existir ou se a propriedade fileName for uma cadeia de caracteres vazia. A tarefa retorna um valor booleano na ExecutionValue propriedade para indicar se o arquivo foi excluído.

using System;  
using Microsoft.SqlServer.Dts.Runtime;  
  
public class SampleTask : Task  
{  
  private string fileName = "";  
  private bool fileDeleted = false;  
  
  public override DTSExecResult Execute(Connections cons,  
     VariableDispenser vars, IDTSComponentEvents events,  
     IDTSLogging log, Object txn)  
  {  
    try  
    {  
      if (this.fileName == "")  
      {  
        events.FireWarning(0, "SampleTask", "No file specified.", "", 0);  
        this.fileDeleted = false;  
      }  
      else  
      {  
        if (System.IO.File.Exists(this.fileName))  
        {  
          System.IO.File.Delete(this.fileName);  
          this.fileDeleted = true;  
        }  
        else  
          this.fileDeleted = false;  
      }  
      return DTSExecResult.Success;  
    }  
    catch (System.Exception exception)  
    {  
      //   Capture the exception and post an error.  
      events.FireError(0, "Sampletask", exception.Message, "", 0);  
      return DTSExecResult.Failure;  
    }  
  }  
  public string FileName  
  {  
    get { return this.fileName; }  
    set { this.fileName = value; }  
  }  
  public override object ExecutionValue  
  {  
    get { return this.fileDeleted; }  
  }  
}  

Imports System  
Imports Microsoft.SqlServer.Dts.Runtime  
  
Public Class SampleTask  
  Inherits Task  
  
  Private _fileName As String = ""  
  Private _fileDeleted As Boolean = False  
  
  Public Overrides Function Execute(ByVal cons As Connections, _  
     ByVal vars As VariableDispenser, ByVal events As IDTSComponentEvents, _  
     ByVal log As IDTSLogging, ByVal txn As Object) As DTSExecResult  
  
    Try  
      If Me._fileName = "" Then  
        events.FireWarning(0, "SampleTask", "No file specified.", "", 0)  
        Me._fileDeleted = False  
      Else  
        If System.IO.File.Exists(Me._fileName) Then  
          System.IO.File.Delete(Me._fileName)  
          Me._fileDeleted = True  
        Else  
          Me._fileDeleted = False  
        End If  
      End If  
      Return DTSExecResult.Success  
    Catch exception As System.Exception  
      '   Capture the exception and post an error.  
      events.FireError(0, "Sampletask", exception.Message, "", 0)  
      Return DTSExecResult.Failure  
    End Try  
  
  End Function  
  
  Public Property FileName() As String  
    Get  
      Return Me._fileName  
    End Get  
    Set(ByVal Value As String)  
      Me._fileName = Value  
    End Set  
  End Property  
  
  Public Overrides ReadOnly Property ExecutionValue() As Object  
    Get  
      Return Me._fileDeleted  
    End Get  
  End Property  
  
End Class  

Ver também

Criando uma tarefa personalizada
Codificando uma tarefa personalizada
Desenvolvendo uma interface de usuário para uma tarefa personalizada