Статья
04/01/2012

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

После создания класса, наследующего базовый класс Task, и применения к нему атрибута DtsTaskAttribute, необходимо переопределить реализацию свойств и методов базового класса, чтобы обеспечить пользовательские функциональные возможности.

Настройка задачи

Проверка задачи

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

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

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

Абстрактный базовый класс Task предоставляет метод Validate, переопределяемый каждой задачей для установки собственных критериев проверки. Конструктор служб SSIS автоматически вызывает метод Validate неоднократно во время разработки пакета и предоставляет пользователю визуальные подсказки при появлении предупреждений или возникновении ошибок, чтобы помочь в выявлении проблем с конфигурацией задачи. Задачи предоставляют результаты проверки, возвращая значение из перечисления DTSExecResult и формируя события с предупреждениями и ошибками. Эти события содержат сведения, которые отображаются пользователю в конструкторе служб SSIS.

Ниже приведены примеры проверки:

Диспетчер соединений проверяет имя определенного файла.
Диспетчер соединений проверяет, является ли тип входа ожидаемым типом, например, XML-файлом.
Задача, которой на входе необходима база данных, убеждается в невозможности получения данных из соединения, не являющегося соединением с базой данных.
Задача убеждается в отсутствии противоречий между заданными для нее свойствами.
Задача убеждается в доступности всех необходимых ресурсов, используемых ею во время выполнения.

Оценивая необходимость проверки тех или иных факторов, следует учитывать производительность системы. Например, входом задачи может быть соединение по сети с низкой пропускной способностью или большим трафиком. При выполнении проверки может потребоваться несколько секунд на обработку, если необходимо проверить доступность ресурса. Еще одна проверка может привести к полном обходу сервера с высокой загрузкой, в результате выполнение проверки замедлится. Хотя можно проверять многие из свойств и настроек, не все они нуждаются в проверке.

Код в методе Validate также вызывается сервером задач TaskHost перед выполнением задачи, и TaskHost отменяет выполнение задачи, если проверка завершается неуспешно.

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

В следующем примере кода показана задача со свойством UserName. Это свойство было задано как обязательное для успешного завершения проверки. Если свойство не задано, задача выдает ошибку и возвращает значение Failure из перечисления DTSExecResult. Метод Validate упакован в блок Try/Catch и приводит к неуспешному завершению проверки при возникновении исключения.

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.

Выполнение задачи

В этом разделе описывается, как использовать метод Execute, который наследуется и переопределяется задачами. В разделе также поясняются различные способы предоставления сведений о результатах выполнения задачи.

Метод Execute

Задачи, содержащиеся в пакете, выполняются, когда среда выполнения служб Integration Services вызывает их метод Execute. Задачи реализуют свою основную бизнес-логику и функциональность в этом методе и предоставляют результаты выполнения, выдавая сообщения, возвращая значение из перечисления DTSExecResult и переопределяя свойство get свойства ExecutionValue.

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

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

Параметр	Описание
Connections	Содержит коллекцию объектов ConnectionManager, доступных для задачи.
VariableDispenser	Содержит переменные, доступные для задачи. Переменные используются задачами через свойство VariableDispenser, а не напрямую. Свойство VariableDispenser осуществляет блокировку и разблокирование переменных, а также предотвращает взаимоблокировки или перезаписи.
IDTSComponentEvents	Содержит методы, вызываемые задачей для вызова событий в обработчике среды выполнения.
IDTSLogging	Содержит методы и свойства, используемые задачей для внесения записей в журнал событий.
Object	Содержит объект транзакции (при наличии такового), частью которого является контейнер. Это значение передается в качестве параметра методу AcquireConnection объекта ConnectionManager.

Обеспечение обратной связи при выполнении

Задачи упаковывают свой код в блоки 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

Будьте в курсе новых возможностей cлужб Integration Services

Чтобы загружать новейшую документацию, статьи, образцы и видеоматериалы от корпорации Майкрософт, а также лучшие решения от участников сообщества, посетите страницу служб Integration Services на сайтах MSDN или TechNet:

Чтобы получать автоматические уведомления об этих обновлениях, подпишитесь на RSS-каналы, предлагаемые на этой странице.

См. также

Основные понятия

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

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

Разработка пользовательского интерфейса для пользовательской задачи

Share via

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

Настройка задачи

Проверка задачи

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

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

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

Сохранение задачи

Выполнение задачи

Метод Execute

Обеспечение обратной связи при выполнении

Пример выполнения

См. также

Основные понятия

Дополнительные ресурсы