カスタム タスクのコーディング

Integration Services パッケージのデザイン中に検証機能を使用して各タスクの設定を確認できるため、すべてのエラーを実行時にのみ見つけるのではなく、無効または不適切な設定が行われた場合、すぐにその問題を確認できます。検証の目的は、タスクの正常な実行を妨げる無効な設定または接続が、タスクに含まれているかどうかを判別することです。これによって、パッケージに含まれるタスクは、初回から正しく実行される可能性が高くなります。

検証機能は、カスタム コード内で Validate メソッドを使用することによって実装できます。ランタイム エンジンは、タスク上の Validate メソッドを呼び出すことにより、タスクを検証します。タスクの開発者は、タスクの検証が成功または失敗する条件を定義し、評価の結果をランタイム エンジンに通知する必要があります。

タスクの抽象基本クラス

検証時のユーザー インターフェイスについての検討事項

検証例

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

通常、タスクに対して、カスタムの永続性を実装する必要はありません。カスタムの永続性は、オブジェクトのプロパティで複合データ型が使用されている場合にのみ必要です。詳細については、「Integration Services 用のカスタム オブジェクトの開発」を参照してください。

パッケージに含まれるタスクは、Integration Services のランタイムが Execute メソッドを呼び出すと実行されます。タスクは、中心となるビジネス ロジックや機能をこのメソッドに実装し、メッセージを送信したり、DTSExecResult 列挙から値を返したり、ExecutionValue プロパティの get プロパティをオーバーライドしたりする方法で、実行結果を返します。

基本クラス Task には、既定で Execute メソッドが実装されています。カスタム タスクは、実行時の機能を定義するために、このメソッドをオーバーライドします。TaskHost オブジェクトはタスクをラップし、ランタイム エンジンやパッケージ内の他のオブジェクトと分離します。そのため、タスクはパッケージ内での実行順序に関する位置を認識しているわけではなく、ランタイムによって呼び出されたときにのみ実行されます。このアーキテクチャにより、実行中にタスクがパッケージを変更したときに発生する問題が回避されます。タスクがパッケージ内の他のオブジェクトにアクセスするには、Execute メソッド内のパラメータとして用意されているオブジェクトを使用する必要があります。これらのパラメータを使用すると、パッケージの安定度と信頼性を保証するために必要な分離性を保ちながら、イベントの発生、イベント ログへのエントリの記録、変数コレクションへのアクセス、およびトランザクション内のデータ ソースへの接続の登録を、タスクに実行させることができます。

次の表は、Execute メソッド内のタスクに対して提供されるパラメータの一覧です。

タスクは、タスクのコードを try/catch ブロックにラップし、ランタイム エンジンに例外が発生するのを防ぎます。これにより、パッケージは予期せず停止することなく、実行を完了します。ランタイム エンジンには、タスクの実行中に発生する可能性のあるエラー条件を処理するメカニズムが他にも用意されています。このメカニズムには、エラー メッセージや警告メッセージの通知、DTSExecResult 構造からの戻り値、メッセージの通知、DTSExecResult の戻り値、ExecutionValue プロパティによるタスクの実行結果に関する情報の公開などが含まれています。

IDTSComponentEvents インターフェイスには、FireWarning メソッドおよび FireError メソッドがあり、タスクはこれらを呼び出して、エラー メッセージや警告メッセージをランタイム エンジンに通知できます。どちらのメソッドにも、エラー コード、ソース コンポーネント、説明、ヘルプ ファイル、ヘルプ コンテキスト情報などのパラメータが必要です。タスクの構成に応じて、ランタイムは、イベントやブレークポイントを発生させたり、イベント ログに情報を記録したりする方法で、これらのメッセージに応答します。

TaskHost は、実行結果に関する追加情報を提供するために使用可能な ExecutionValue プロパティも提供します。たとえば、タスクがその Execute メソッドの一部としてテーブルから行を削除すると、削除された行数は ExecutionValue プロパティの値として返されます。また、TaskHost は ExecValueVariable プロパティを提供します。ユーザーはこのプロパティを使用して、タスクから返された ExecutionValue を、タスクで認識可能な任意の変数にマップすることができます。指定した変数を使用して、タスク間の優先順位制約を確立できます。

次のコード例では、Execute メソッドを実装する方法、およびオーバーライドされた ExecutionValue プロパティを示します。このタスクでは、タスクの fileName プロパティで指定されたファイルが削除されます。ファイルが存在しない場合、または fileName プロパティが空の文字列である場合、タスクは警告メッセージを通知します。タスクは、ExecutionValue プロパティで、ファイルが削除されたかどうかを示す Boolean 値を返します。

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