Создание кода пользовательской задачи

При разработке пакета служб Integration Services можно использовать проверку, чтобы убедиться в правильности настроек каждой задачи. Проверка позволит отследить неверные или неподходящие настройки сразу же после их задания, вместо того, чтобы обнаруживать их лишь во время выполнения. Цель проверки состоит в том, чтобы определить, содержит ли задача недопустимые настройки или соединения, которые могут помешать ее успешному выполнению. Таким образом, можно убедиться в том, что пакет содержит только те задачи, выполнение которых будет успешным с первой попытки.

Можно реализовать проверку с помощью метода Validate в пользовательском коде. Обработчик среды выполнения осуществляет проверку задачи путем вызова метода Validate для этой задачи. Разработчику задачи следует определить критерии успешной или неуспешной проверки задачи, а также обеспечить уведомление обработчика времени выполнения о результатах этой оценки.

Абстрактный базовый класс Task

Рекомендации по пользовательскому интерфейсу во время проверки

Пример проверки

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 и переопределяя свойство get свойства ExecutionValue.

Базовый класс Task предоставляет реализацию по умолчанию метода Execute. Пользовательские задачи переопределяют этот метод, чтобы определить собственную функциональность времени выполнения. Объект TaskHost упаковывает задачу, изолируя ее от обработчика среды выполнения и других объектов в пакете. В результате этой изоляции задача не имеет сведений о своем местоположении в пакете с учетом порядка выполнения. Она выполняется только после вызова средой выполнения. Такая архитектура предотвращает проблемы, которые могут возникнуть при изменении задачами пакета в процессе выполнения. Задаче предоставляется доступ к другим объектам в пакете только через объекты, передаваемые ей в качестве параметров в методе Execute. Эти параметры позволяют задачам вызывать события, делать записи в журнале событий, обращаться к коллекции Variables и прикреплять соединения к источникам данных в транзакциях, одновременно сохраняя изоляцию, которая необходима для обеспечения стабильности и надежности пакета.

В следующей таблице перечислены параметры, передаваемые задаче в методе Execute.

Задачи упаковывают свой код в блоки try/catch, чтобы предотвратить возникновение исключений в обработчике среды выполнения. Таким образом, гарантируется, что выполнение пакета будет завершено, и не произойдет неожиданной остановки. Однако обработчик среды выполнения предоставляет и другие механизмы обработки ошибок, которые могут возникать во время выполнения задачи. К ним относится выдача сообщений об ошибках и предупреждений, возвращение значения из структуры DTSExecResult, выдача сообщений, возвращение значения DTSExecResult и раскрытие сведений о результатах выполнения задачи с помощью свойства ExecutionValue.

Интерфейс IDTSComponentEvents содержит методы FireWarning и FireError, которые могут быть вызваны задачей для выдачи сообщений об ошибках и предупреждений в обработчике среды выполнения. Обоим методам требуются такие параметры, как код ошибки, исходный компонент, описание, файл справки и данные контекста справки. В зависимости от конфигурации задачи, среда выполнения отвечает на эти сообщения, вызывая события и точки останова либо записывая данные в журнал событий.

Объект TaskHost также предоставляет свойство ExecutionValue, которое можно использовать для предоставления дополнительных сведений о результатах выполнения. Например, если задача удаляет строки из таблицы в рамках своего метода Execute, в качестве значения свойства ExecutionValue может быть возвращено число удаленных строк. Кроме того, объект TaskHost предоставляет свойство ExecValueVariable. С помощью этого свойства пользователь может сопоставить значение ExecutionValue, возвращаемое задачей, с любой другой переменной, доступной для задачи. Затем указанную переменную можно использовать для настройки элементов управления очередностью между задачами.

В следующем примере кода показана реализация метода Execute и переопределенное свойство ExecutionValue. Задача удаляет файл, указанный свойством fileName задачи. Задача выдает предупреждение, если файл не существует либо если свойство fileName является пустой строкой. Задача возвращает значение типа Boolean для свойства ExecutionValue, чтобы указать, был ли файл удален.

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