Codage d'une tâche personnalisée

Lorsque vous concevez un package Integration Services, vous pouvez utiliser la validation pour vérifier des paramètres sur chaque tâche, afin d'intercepter les paramètres incorrects ou inappropriés dès qu'ils sont définis, au lieu de détecter toutes les erreurs uniquement au moment de l'exécution. L'objectif de la validation est de déterminer si la tâche contient des paramètres ou connexions non valides qui l'empêcheront de s'exécuter avec succès. Elle permet de veiller à ce que le package contienne des tâches qui ont de bonnes chances de s'exécuter dès leur premier essai.

Vous pouvez implémenter la validation à l'aide de la méthode Validate dans du code personnalisé. Le moteur d'exécution valide une tâche en appelant la méthode Validate sur cette tâche. Il incombe au développeur de la tâche de définir les critères d'une validation de tâche réussie ou non réussie, et de notifier le moteur d'exécution du résultat de cette évaluation.

Classe de base abstraite d'une tâche

Considérations liées à l'interface utilisateur pendant la validation

Exemple de validation

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

En règle générale, vous n'avez pas à implémenter une persistance personnalisée pour une tâche. Une persistance personnalisée est uniquement requise lorsque les propriétés d'un objet utilisent des types de données complexes. Pour plus d'informations, consultez Développement d'objets personnalisés pour Integration Services.

Tâches contenues dans l'exécution d'un package lorsque le runtime Integration Services appelle leur méthode Execute. Les tâches implémentent leurs logique métier et fonctionnalités principales dans cette méthode, puis fournissent les résultats de l'exécution en publiant des messages, en renvoyant une valeur de l'énumération DTSExecResult et en remplaçant la propriété get de la propriété ExecutionValue.

La classe de base Task fournit une implémentation par défaut de la méthode Execute. Les tâches personnalisées substituent cette méthode pour définir leurs fonctionnalités d'exécution. L'objet TaskHost encapsule la tâche, en l'isolant du moteur d'exécution et des autres objets compris dans le package. En raison de cette isolation, la tâche n'a pas connaissance de son emplacement dans le package pour ce qui est de son ordre d'exécution et elle s'exécute uniquement lorsqu'elle est appelée par le runtime. Cette architecture empêche certains problèmes qui peuvent se produire lorsque les tâches modifient le package pendant l'exécution. La tâche peut accéder aux autres objets compris dans le package uniquement via les objets qui lui sont fournis comme paramètres dans la méthode Execute. Ces paramètres permettent aux tâches de déclencher des événements, d'écrire des entrées dans le journal des événements, d'accéder à la collection de variables et d'inscrire des connexions aux sources de données dans les transactions, tout en maintenant quand même l'isolation nécessaire pour garantir la stabilité et la fiabilité du package.

Le tableau suivant répertorie les paramètres fournis à la tâche dans la méthode Execute.

Les tâches encapsulent leur code dans des blocs try/catch pour empêcher le déclenchement d'exceptions sur le moteur d'exécution. Cela permet de veiller à ce que le package finisse l'exécution et ne s'arrête pas de façon inattendue. Toutefois, le moteur d'exécution fournit d'autres mécanismes pour gérer les conditions d'erreur qui peuvent se produire pendant l'exécution d'une tâche. Ceux-ci incluent la publication de messages d'erreur et d'avertissement, le renvoi d'une valeur de la structure DTSExecResult, la publication de messages, le renvoi de la valeur DTSExecResult et la divulgation d'informations sur les résultats de l'exécution des tâches via la propriété ExecutionValue.

L'interface IDTSComponentEvents contient les méthodes FireWarning et FireError, qui peuvent être appelées par la tâche pour publier des messages d'erreur et d'avertissement sur le moteur d'exécution. Ces deux méthodes requièrent des paramètres tels qu'un code d'erreur, un composant source, une description, un fichier d'aide et des informations d'aide contextuelles. Selon la configuration de la tâche, le runtime répond à ces messages en déclenchant des événements et des points d'arrêt, ou en écrivant des informations dans le journal des événements.

L'objet TaskHost fournit également la propriété ExecutionValue qui peut être utilisée pour fournir des informations supplémentaires à propos des résultats de l'exécution. Par exemple, si une tâche supprime des lignes d'une table dans le cadre de sa méthode Execute, elle peut retourner le nombre de lignes supprimées sous la forme de la valeur de la propriété ExecutionValue. En outre, l'objet TaskHost fournit la propriété ExecValueVariable. Cette propriété permet à l'utilisateur de mapper la propriété ExecutionValue renvoyée à partir de la tâche vers toute variable visible pour la tâche. Il est alors possible d'utiliser la variable spécifiée pour établir des contraintes de précédence entre les tâches.

L'exemple de code suivant montre une implémentation de la méthode Execute et affiche une propriété ExecutionValue substituée. La tâche supprime le fichier spécifié par la propriété fileName de la tâche. La tâche publie un avertissement si le fichier n'existe pas ou si la propriété fileName est une chaîne vide. La tâche renvoie une valeur Boolean dans la propriété ExecutionValue pour indiquer si le fichier a été supprimé.

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