Codieren eines benutzerdefinierten Tasks

Wenn Sie ein Integration Services-Paket entwerfen, können Sie die Validierung verwenden, um Einstellungen für die einzelnen Tasks zu überprüfen, sodass falsche oder unpassende Einstellungen gleich nach dem Festlegen abgefangen werden können und nicht erst zur Laufzeit auffallen. Der Sinn und Zweck der Validierung besteht darin zu bestimmen, ob der Task ungültige Einstellungen oder Verbindungen umfasst, durch die das erfolgreiche Ausführen verhindert wird. Auf diese Weise wird sichergestellt, dass das Paket nur Tasks enthält, bei denen die Wahrscheinlichkeit groß ist, dass sie beim ersten Versuch korrekt ausgeführt werden.

Sie können die Validierung mithilfe der Validate-Methode in benutzerdefiniertem Code implementieren. Das Laufzeitmodul überprüft einen Task, indem die Validate-Methode im Task aufgerufen wird. Der Taskentwickler ist dafür verantwortlich, die Kriterien zu definieren, die eine erfolgreiche oder fehlgeschlagene Taskvalidierung ausmachen, und eine Benachrichtigung an das Laufzeitmodul mit dem Ergebnis dieser Auswertung auszugeben.

Abstrakte Basisklasse des Tasks

Überlegungen zur Benutzeroberfläche während der Validierung

Beispiel für die Validierung

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

In der Regel müssen Sie keine benutzerdefinierte Dauerhaftigkeit für einen Task implementieren. Die benutzerdefinierte Dauerhaftigkeit ist nur erforderlich, wenn die Eigenschaften eines Objekts komplexe Datentypen verwenden. Weitere Informationen finden Sie unter Entwickeln benutzerdefinierter Objekte für Integration Services.

Tasks, die in einem Paket enthalten sind, werden ausgeführt, wenn ihre Execute-Methode von der Integration Services-Laufzeit aufgerufen wird. Die grundlegende Geschäftslogik und Funktionalität von Tasks ist in dieser Methode implementiert. Die Ergebnisse der Ausführung werden durch Ausgeben von Meldungen, Zurückgeben eines Werts aus der DTSExecResult-Enumeration und Außerkraftsetzen der get-Eigenschaft der ExecutionValue-Eigenschaft bereitgestellt.

Die Task-Basisklasse stellt eine Standardimplementierung der Execute-Methode bereit. Die benutzerdefinierten Tasks setzen diese Methode außer Kraft, um ihre Laufzeitfunktionalität zu definieren. Das TaskHost-Objekt umschließt den Task, sodass dieser von dem Laufzeitmodul und den anderen Objekten in dem Paket isoliert wird. Aufgrund dieser Isolation erkennt der Task seine Stelle in dem Paket bezüglich der Ausführungsreihenfolge nicht und wird nur ausgeführt, wenn er durch die Laufzeit aufgerufen wird. Durch diese Architektur werden Probleme verhindert, die auftreten können, wenn Tasks während der Ausführung das Paket ändern. Der Task erhält nur durch die Objekte, die ihm in der Execute-Methode als Parameter bereitgestellt werden, Zugriff auf die anderen Objekte in dem Paket. Mithilfe dieser Parameter können Tasks Ereignisse auslösen, Einträge in das Ereignisprotokoll schreiben, auf die Variablenauflistung zugreifen und Verbindungen zu Datenquellen in Transaktionen eintragen, während gleichzeitig die Isolation beibehalten wird, die erforderlich ist, um die Stabilität und Zuverlässigkeit des Pakets zu garantieren.

In der folgenden Tabelle sind die für den Task in der Execute-Methode bereitgestellten Parameter aufgeführt.

Bei Tasks wird der Code in try/catch-Blöcke eingebunden, um zu verhindern, dass Ausnahmen im Laufzeitmodul ausgelöst werden. Dadurch wird sichergestellt, dass das Paket die Ausführung abschließt und nicht unerwartet beendet wird. Das Laufzeitmodul bietet jedoch andere Mechanismen zur Behandlung von Fehlerbedingungen, die während der Ausführung eines Tasks auftreten können. Dazu gehört das Ausgeben von Fehler- und Warnmeldungen, das Zurückgeben eines Werts aus der DTSExecResult-Struktur, das Ausgeben von Meldungen, das Zurückgeben des DTSExecResult-Werts sowie das Offenlegen von Informationen zu den Ergebnissen der Taskausführung durch die ExecutionValue-Eigenschaft.

Die IDTSComponentEvents-Schnittstelle enthält die FireWarning-Methode und die FireError-Methode, die von dem Task aufgerufen werden können, um Fehler- und Warnmeldungen für das Laufzeitmodul auszugeben. Für beide Methoden sind Parameter wie der Fehlercode, die Quellkomponente, die Beschreibung, die Hilfedatei sowie Hilfekontextinformationen erforderlich. Je nach der Konfiguration des Tasks reagiert die Laufzeit auf diese Meldungen, indem Ereignisse und Haltepunkte ausgelöst oder Informationen in das Ereignisprotokoll geschrieben werden.

Das TaskHost-Objekt stellt auch die ExecutionValue-Eigenschaft bereit, die verwendet werden kann, um zusätzliche Informationen zu den Ergebnissen der Ausführung bereitzustellen. Wenn ein Task beispielsweise Zeilen aus einer Tabelle als Teil seiner Execute-Methode löscht, wird möglicherweise die Anzahl von gelöschten Zeilen als Wert der ExecutionValue-Eigenschaft zurückgegeben. Darüber hinaus stellt das TaskHost-Objekt die ExecValueVariable-Eigenschaft bereit. Mithilfe dieser Eigenschaft kann der Benutzer den von dem Task zurückgegebenen ExecutionValue-Wert einer Variablen zuordnen, die für den Task sichtbar ist. Die angegebene Variable kann dann verwendet werden, um Rangfolgeneinschränkungen zwischen Tasks einzurichten.

Im folgenden Codebeispiel wird eine Implementierung der Execute-Methode veranschaulicht, und es wird eine außer Kraft gesetzte ExecutionValue-Eigenschaft gezeigt. Der Task löscht die Datei, die von der fileName-Eigenschaft des Tasks angegeben wird. Der Task gibt eine Warnung aus, wenn die Datei nicht vorhanden oder die fileName-Eigenschaft eine leere Zeichenfolge ist. Der Task gibt eine Boolean-Wert in der ExecutionValue-Eigenschaft zurück, um anzugeben, ob die Datei gelöscht wurde.

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