Codieren eines benutzerdefinierten Tasks

Artikel
05/07/2013

Nachdem Sie eine Klasse erstellt haben, die von der Task-Basisklasse erbt, und das DtsTaskAttribute-Attribut auf die Klasse angewendet haben, müssen Sie die Implementierung der Eigenschaften und Methoden der Basisklasse überschreiben, um die benutzerdefinierte Funktionalität bereitzustellen.

Konfigurieren des Tasks

Überprüfen des 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

Durch die abstrakte Task-Basisklasse wird die Validate-Methode bereitgestellt, die jeder Task überschreibt, um seine eigenen Validierungskriterien zu definieren. Der SSIS-Designer ruft die Validate-Methode automatisch mehrere Male während des Paketentwurfs auf und bietet dem Benutzer visuelle Hinweise, wenn Warnungen oder Fehler auftreten, sodass Probleme mit der Konfiguration des Tasks ermittelt werden können. Die Validierungsergebnisse von Tasks werden bereitgestellt, indem ein Wert aus der DTSExecResult-Enumeration zurückgegeben wird und Warnungs- und Fehlerereignisse ausgelöst werden. Diese Ereignisse enthalten Informationen, die dem Benutzer im SSIS-Designer angezeigt werden.

Nachfolgend finden Sie einige Beispiele für Validierungen:

Ein Verbindungs-Manager validiert den spezifischen Dateinamen.
Ein Verbindungs-Manager überprüft, dass der Typ der Eingabe der erwartete Typ ist, beispielsweise eine XML-Datei.
Ein Task, der eine Datenbankeingabe erwartet, überprüft, dass keine Daten von einer Nicht-Datenbankverbindung empfangen werden können.
Ein Task garantiert, dass keine seiner Eigenschaften mit anderen Eigenschaften, die für den gleichen Task festgelegt wurden, in Konflikt steht.
Ein Task garantiert, dass alle erforderlichen Ressourcen, die von dem Task bei der Ausführung verwendet werden, verfügbar sind.

Bei der Bestimmung, was validiert wird, spielt die Leistung eine wichtige Rolle. Die Eingabe für einen Task kann beispielsweise eine Verbindung über ein Netzwerk mit niedriger Bandbreite oder hohem Datenverkehr sein. Die Validierung kann möglicherweise mehrere Sekunden dauern, wenn Sie festlegen, dass überprüft werden soll, ob die Ressource verfügbar ist. Eine andere Validierung kann möglicherweise zu einem Roundtrip zu einem stark beanspruchten Server führen, und die Validierungsroutine kann langsam sein. Obwohl es viele Eigenschaften und Einstellungen gibt, die überprüft werden können, ist es nicht ratsam, alles zu überprüfen.

Der Code in der Validate-Methode wird auch von TaskHost aufgerufen, bevor der Task ausgeführt wird, und TaskHost bricht die Ausführung ab, wenn die Validierung fehlschlägt.

Überlegungen zur Benutzeroberfläche während der Validierung

Task umfasst eine IDTSComponentEvents-Schnittstelle als Parameter für die Validate-Methode. Die IDTSComponentEvents-Schnittstelle umfasst die Methoden, die von dem Task aufgerufen werden, um Ereignisse für das Laufzeitmodul auszulösen. Die FireWarning-Methode und die FireError-Methode werden aufgerufen, wenn eine Warnung oder eine Fehlerbedingung während der Validierung auftritt. Für beide Warnungsmethoden sind die gleichen Parameter erforderlich. Dazu gehören ein Fehlercode, eine Quellkomponente, eine Beschreibung, eine Hilfedatei sowie Hilfekontextinformationen. Der SSIS-Designer verwendet diese Informationen, um visuelle Hinweise auf der Entwurfsoberfläche anzuzeigen. Die vom Designer bereitgestellten visuellen Hinweise enthalten ein Ausrufezeichen, das neben dem Task auf der Entwurfsoberfläche angezeigt wird. Dieser visuelle Hinweis signalisiert dem Benutzer, dass der Task zusätzliche Konfiguration erfordert, bevor die Ausführung fortgesetzt werden kann.

Mit dem Ausrufezeichen wird auch eine QuickInfo angezeigt, die eine Fehlermeldung enthält. Die Fehlermeldung wird vom Task im Beschreibungsparameter des Ereignisses bereitgestellt. Fehlermeldungen werden auch in der Aufgabenliste von SQL Server-Datentools (SSDT) angezeigt, sodass der Benutzer einen zentralen Ort zur Anzeige aller Validierungsfehler erhält.

Beispiel für die Validierung

Im folgenden Codebeispiel wird ein Task mit einer UserName-Eigenschaft veranschaulicht. Diese Eigenschaft wurde angegeben, da sie für eine erfolgreiche Validierung erforderlich ist. Wenn die Eigenschaft nicht festgelegt wird, gibt der Task einen Fehler aus und gibt einen Failure aus der DTSExecResult-Enumeration zurück. Die Validate-Methode wird in einem try/catch-Block umschlossen und führt zu einem Fehler bei der Validierung, wenn eine Ausnahme auftritt.

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

Beibehalten des Tasks

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

Ausführen des Tasks

In diesem Abschnitt wird beschrieben, wie die Execute-Methode verwendet wird, die von Tasks geerbt und überschrieben wird. In diesem Abschnitt werden auch verschiedene Methoden zum Bereitstellen von Informationen zu den Ergebnissen der Taskausführung erläutert.

Execute-Methode

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 Überschreiben der get-Eigenschaft der ExecutionValue-Eigenschaft bereitgestellt.

Die Task-Basisklasse stellt eine Standardimplementierung der Execute-Methode bereit. Die benutzerdefinierten Tasks überschreiben diese Methode, 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.

Parameter	Beschreibung
Connections	Enthält eine Auflistung von ConnectionManager-Objekten, die für den Task verfügbar sind.
VariableDispenser	Enthält die Variablen, die für den Task verfügbar sind. Die Tasks verwenden Variablen durch den VariableDispenser; die Tasks verwenden keine Variablen direkt. Der VariableDispenser sperrt und entsperrt Variablen und verhindert Deadlocks oder Überschreibungen.
IDTSComponentEvents	Enthält die Methoden, die von dem Task zum Auslösen von Ereignissen im Laufzeitmodul aufgerufen werden.
IDTSLogging	Enthält Methoden und Eigenschaften, die von dem Task zum Schreiben von Ereignissen in das Ereignisprotokoll verwendet werden.
Objekt	Enthält ggf. das Transaktionsobjekt, von dem der Container ein Teil ist. Dieser Wert wird als Parameter an die AcquireConnection-Methode eines ConnectionManager-Objekts übergeben.

Bereitstellen von Feedback zur Ausführung

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 Breakpoints 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.

Ausführungsbeispiel

Im folgenden Codebeispiel wird eine Implementierung der Execute-Methode veranschaulicht, und es wird eine überschriebene 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

Bleiben Sie mit Integration Services auf dem neuesten Stand

Die neuesten Downloads, Artikel, Beispiele und Videos von Microsoft sowie ausgewählte Lösungen aus der Community finden Sie auf MSDN auf der Integration Services-Seite: