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

Применимо к:Applies to: даSQL ServerSQL Server (все поддерживаемые версии) yesSQL ServerSQL Server (all supported versions) да Azure-SSIS Integration Runtime в Фабрике данных AzureSSIS Integration Runtime in Azure Data Factoryyes Azure-SSIS Integration Runtime в Фабрике данных AzureSSIS Integration Runtime in Azure Data FactoryПрименимо к:Applies to: даSQL ServerSQL Server (все поддерживаемые версии) yesSQL ServerSQL Server (all supported versions) да Azure-SSIS Integration Runtime в Фабрике данных AzureSSIS Integration Runtime in Azure Data Factoryyes Azure-SSIS Integration Runtime в Фабрике данных AzureSSIS Integration Runtime in Azure Data Factory

После создания класса, наследующего от базового класса Microsoft.SqlServer.Dts.Runtime.Task, и применения к нему атрибута DtsTaskAttribute необходимо переопределить реализацию свойств и методов базового класса, чтобы обеспечить ваши пользовательские функциональные возможности.After you have created a class that inherits from the Microsoft.SqlServer.Dts.Runtime.Task base class, and applied the DtsTaskAttribute attribute to the class, you must override the implementation of the properties and methods of the base class to provide your custom functionality.

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

Проверка задачиValidating the Task

При разработке пакета служб Службы Integration ServicesIntegration Services можно использовать проверку, чтобы убедиться в правильности настроек каждой задачи. Проверка позволит отследить неверные или неподходящие настройки сразу же после их задания, вместо того, чтобы обнаруживать их лишь во время выполнения.When you are designing an Службы Integration ServicesIntegration Services package, you can use validation to verify settings on each task, so that you can catch incorrect or inappropriate settings as soon as they are set, instead of finding all errors at run-time only. Цель проверки состоит в том, чтобы определить, содержит ли задача недопустимые настройки или соединения, которые могут помешать ее успешному выполнению.The purpose of validation is to determine whether the task contains invalid settings or connections that will prevent it from running successfully. Таким образом, можно убедиться в том, что пакет содержит только те задачи, выполнение которых будет успешным с первой попытки.This makes sure that the package contains tasks that have a good chance of running on their first run.

Можно реализовать проверку с помощью метода Validate в пользовательском коде.You can implement validation by using the Validate method in custom code. Подсистема среды выполнения проверяет задачу путем вызова метода Validate для этой задачи.The run-time engine validates a task by calling the Validate method on the task. Разработчику задачи следует определить критерии успешной или неуспешной проверки задачи, а также обеспечить уведомление обработчика времени выполнения о результатах этой оценки.It is the responsibility of the task developer to define the criteria that give you a successful or failed task validation, and to notify the run-time engine of the result of this evaluation.

Абстрактный базовый класс TaskTask Abstract Base Class

Абстрактный базовый класс Microsoft.SqlServer.Dts.Runtime.Task предоставляет метод Validate, переопределяемый каждой задачей для установки собственных критериев проверки.The Microsoft.SqlServer.Dts.Runtime.Task abstract base class provides the Validate method that each task overrides to define its validation criteria. Конструктор служб Integration ServicesSSIS автоматически вызывает метод Validate неоднократно во время разработки пакета и предоставляет пользователю визуальные подсказки при появлении предупреждений или возникновении ошибок, чтобы помочь в выявлении проблем с конфигурацией задачи.The Integration ServicesSSIS Designer automatically calls the Validate method multiple times during package design, and provides visual cues to the user when warnings or errors occur to help identify problems with the configuration of the task. Задачи предоставляют результаты проверки, возвращая значение из перечисления DTSExecResult и формируя события с предупреждениями и ошибками.Tasks provide validation results by returning a value from the DTSExecResult enumeration, and by raising warning and error events. Эти события содержат сведения, которые отображаются пользователю в конструкторе служб Integration ServicesSSIS.These events contain information that is displayed to the user in Integration ServicesSSIS Designer.

Ниже приведены примеры проверки:Some examples for validation follow:

  • Диспетчер соединений проверяет имя определенного файла.A connection manager validates the specific file name.

  • Диспетчер соединений проверяет, является ли тип входа ожидаемым типом, например, XML-файлом.A connection manager validates that the type of input is the expected type, such as an XML file.

  • Задача, которой на входе необходима база данных, убеждается в невозможности получения данных из подключения, не являющегося подключением к базе данных.A task that expects database input verifies that it cannot receive data from a non-database connection.

  • Задача убеждается в отсутствии противоречий между заданными для нее свойствами.A task guarantees that none of its properties contradicts other properties set on the same task.

  • Задача убеждается в доступности всех необходимых ресурсов, используемых ею во время выполнения.A task guarantees that all required resources used by the task at execution time are available.

Оценивая необходимость проверки тех или иных факторов, следует учитывать производительность системы.Performance is something to consider in determining what is validated and what is not. Например, входом задачи может быть соединение по сети с низкой пропускной способностью или большим трафиком.For example, the input to a task might be a connection over a network that has low bandwidth or heavy traffic. При выполнении проверки может потребоваться несколько секунд на обработку, если необходимо проверить доступность ресурса.The validation may take several seconds to process if you decide to validate that the resource is available. Еще одна проверка может привести к полном обходу сервера с высокой загрузкой, в результате выполнение проверки замедлится.Another validation may cause a round-trip to a server that is in high demand, and the validation routine might be slow. Хотя можно проверять многие из свойств и настроек, не все они нуждаются в проверке.Although there are many properties and settings that can be validated, not everything should be validated.

  • Код в методе Validate также вызывается сервером задач TaskHost перед выполнением задачи, и TaskHost отменяет выполнение задачи, если проверка завершается неудачно.The code in the Validate method is also called by the TaskHost before the task is run, and the TaskHost cancels execution if validation fails.

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

Базовый класс Microsoft.SqlServer.Dts.Runtime.Task включает интерфейс IDTSComponentEvents в качестве параметра для метода Validate.The Microsoft.SqlServer.Dts.Runtime.Task includes an IDTSComponentEvents interface as a parameter to the Validate method. Интерфейс IDTSComponentEvents содержит методы, вызываемые задачей для формирования событий в обработчике среды выполнения.The IDTSComponentEvents interface contains the methods that are called by the task in order to raise events to the run-time engine. Методы FireWarning и FireError вызываются при возникновении ошибки или выдаче предупреждения во время проверки.The FireWarning and FireError methods are called when a warning or error condition occurs during validation. Для обоих методов требуются одни и те же параметры. В их число входит код ошибки, исходный компонент, описание, файл справки и данные контекста справки.Both warning methods require the same parameters, which include an error code, source component, description, Help file, and Help context information. Конструктор служб Integration ServicesSSIS использует эти сведения для отображения визуальных подсказок в области конструктора.The Integration ServicesSSIS Designer uses this information to display visual cues on the design surface. К визуальным подсказкам, предоставляемым конструктором, относится значок восклицания, который отображается рядом с задачей в области конструктора.The visual cues that are provided by the designer include an exclamation icon that appears next to the task on the designer surface. Эта визуальная подсказка указывает пользователю на то, что необходима дополнительная настройка задачи прежде, чем ее выполнение может быть продолжено.This visual cue signals to the user that the task requires additional configuration before execution can continue.

Значок восклицания также отображает подсказку, содержащую сообщение об ошибке.The exclamation icon also displays a ToolTip that contains an error message. Сообщение об ошибке предоставляется задачей в параметре описания события.The error message is provided by the task in the description parameter of the event. Кроме того, сообщения об ошибках отображаются на панели Список задач среды SQL Server Data Tools (SSDT)SQL Server Data Tools (SSDT), что позволяет пользователю просматривать все ошибки проверки в одном месте.Error messages are also displayed in the Task List pane of SQL Server Data Tools (SSDT)SQL Server Data Tools (SSDT), providing the user with a central location for viewing all validation errors.

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

В приведенном ниже примере кода показана задача со свойством UserName.The following code example shows a task with a UserName property. Это свойство было задано как обязательное для успешного завершения проверки.This property has been specified as required for validation to succeed. Если свойство не задано, задача выдает ошибку и возвращает значение Failure из перечисления DTSExecResult.If the property is not set, the task posts an error, and returns Failure from the DTSExecResult enumeration. Метод Validate упакован в блок Try/Catch и приводит к неудачному завершению проверки при возникновении исключения.The Validate method is wrapped in a try/catch block, and fails validation if an exception occurs.

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  

Сохранение задачиPersisting the Task

Как правило, нет необходимости реализовывать для задачи пользовательскую сохраняемость.Ordinarily you do not have to implement custom persistence for a task. Нестандартный механизм сохраняемости необходим только в случае, когда свойства объекта используют сложные типы данных.Custom persistence is required only when the properties of an object use complex data types. Дополнительные сведения см. в разделе Разработка пользовательских объектов для служб Integration Services.For more information, see Developing Custom Objects for Integration Services.

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

В этом разделе описывается, как использовать метод Execute, который наследуется и переопределяется задачами.This section describes how to use the Execute method that is inherited and overridden by tasks. В разделе также поясняются различные способы предоставления сведений о результатах выполнения задачи.This section also explains various ways of providing information about the results of task execution.

Метод ExecuteExecute Method

Задачи, содержащиеся в пакете, выполняются, когда среда выполнения служб Службы Integration ServicesIntegration Services вызывает их метод Execute.Tasks that are contained in a package run when the Службы Integration ServicesIntegration Services runtime calls their Execute method. Задачи реализуют свою основную бизнес-логику и функциональность в этом методе и предоставляют результаты выполнения, выдавая сообщения, возвращая значение из перечисления DTSExecResult и переопределяя свойство get свойства ExecutionValue.Tasks implement their core business logic and functionality in this method, and provide the results of execution by posting messages, returning a value from the DTSExecResult enumeration, and overriding the property get of the ExecutionValue property.

Базовый класс Microsoft.SqlServer.SqlServer.Dts.Runtime.Task предоставляет реализацию метода Execute по умолчанию.The Microsoft.SqlServer.Dts.Runtime.Task base class provides a default implementation of the Execute method. Пользовательские задачи переопределяют этот метод, чтобы определить собственную функциональность времени выполнения.The custom tasks override this method to define their run-time functionality. Объект TaskHost упаковывает задачу, изолируя ее от обработчика среды выполнения и других объектов в пакете.The TaskHost object wraps the task, isolating it from the run-time engine and the other objects in the package. В результате этой изоляции задача не имеет сведений о своем местоположении в пакете с учетом порядка выполнения. Она выполняется только после вызова средой выполнения.Because of this isolation, the task is unaware of its location in the package with regard to its execution order, and runs only when it is called by the runtime. Такая архитектура предотвращает проблемы, которые могут возникнуть при изменении задачами пакета в процессе выполнения.This architecture prevents problems that can occur when tasks modify the package during execution. Задаче предоставляется доступ к другим объектам в пакете только через объекты, передаваемые ей в качестве параметров в методе Execute.The task is provided access to the other objects in the package only through the objects supplied to it as parameters in the Execute method. Эти параметры позволяют задачам вызывать события, делать записи в журнале событий, обращаться к коллекции Variables и прикреплять соединения к источникам данных в транзакциях, одновременно сохраняя изоляцию, которая необходима для обеспечения стабильности и надежности пакета.These parameters let tasks raise events, write entries to the event log, access the variables collection, and enlist connections to data sources in transactions, while still maintaining the isolation that is necessary to guarantee the stability and reliability of the package.

В следующей таблице перечислены параметры, передаваемые задаче в методе Execute.The following table lists the parameters provided to the task in the Execute method.

ПараметрParameter ОписаниеDescription
Connections Содержит коллекцию объектов ConnectionManager, доступных для задачи.Contains a collection of ConnectionManager objects available to the task.
VariableDispenser Содержит переменные, доступные для задачи.Contains the variables available to the task. Переменные используются задачами через свойство VariableDispenser, а не напрямую.The tasks use variables through the VariableDispenser; the tasks do not use variables directly. Свойство VariableDispenser осуществляет блокировку и разблокирование переменных, а также предотвращает взаимоблокировки или перезаписи.The variable dispenser locks and unlocks variables, and prevents deadlocks or overwrites.
IDTSComponentEvents Содержит методы, вызываемые задачей для вызова событий в обработчике среды выполнения.Contains the methods called by the task to raise events to the run-time engine.
IDTSLogging Содержит методы и свойства, используемые задачей для внесения записей в журнал событий.Contains methods and properties used by the task to write entries to the event log.
ОбъектObject Содержит объект транзакции (при наличии такового), частью которого является контейнер.Contains the transaction object that the container is a part of, if any. Это значение передается в качестве параметра методу AcquireConnection объекта ConnectionManager.This value is passed as a parameter to the AcquireConnection method of a ConnectionManager object.

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

Задачи упаковывают свой код в блоки try/catch, чтобы предотвратить возникновение исключений в подсистеме среды выполнения.Tasks wrap their code in try/catch blocks to prevent exceptions from being raised to the run-time engine. Таким образом, гарантируется, что выполнение пакета будет завершено, и не произойдет неожиданной остановки.This ensures that the package finishes execution and does not stop unexpectedly. Однако обработчик среды выполнения предоставляет и другие механизмы обработки ошибок, которые могут возникать во время выполнения задачи.However, the run-time engine provides other mechanisms for handling error conditions that can occur during the execution of a task. К ним относится выдача сообщений об ошибках и предупреждений, возвращение значения из структуры DTSExecResult, выдача сообщений, возвращение значения DTSExecResult и раскрытие сведений о результатах выполнения задачи с помощью свойства ExecutionValue.These include posting error and warning messages, returning a value from the DTSExecResult structure, posting messages, returning the DTSExecResult value, and disclosing information about the results of task execution through the ExecutionValue property.

Интерфейс IDTSComponentEvents содержит методы FireWarning и FireError, которые могут быть вызваны задачей для выдачи сообщений об ошибках и предупреждений в обработчике среды выполнения.The IDTSComponentEvents interface contains the FireWarning and FireError methods, which can be called by the task to post error and warning messages to the run-time engine. Обоим методам требуются такие параметры, как код ошибки, исходный компонент, описание, файл справки и данные контекста справки.Both methods require parameters such as the error code, source component, description, Help file, and help context information. В зависимости от конфигурации задачи, среда выполнения отвечает на эти сообщения, вызывая события и точки останова либо записывая данные в журнал событий.Depending on the configuration of the task, the runtime responds to these messages by raising events and breakpoints, or by writing information to the event log.

Объект TaskHost также предоставляет свойство ExecutionValue, которое можно использовать для предоставления дополнительных сведений о результатах выполнения.The TaskHost also provides the ExecutionValue property that can be used to provide additional information about the results of execution. Например, если задача удаляет строки из таблицы в рамках своего метода Execute, в качестве значения свойства ExecutionValue может быть возвращено число удаленных строк.For example, if a task deletes rows from a table as part of its Execute method, it might return the number of rows deleted as the value of the ExecutionValue property. Кроме того, объект TaskHost предоставляет свойство ExecValueVariable.In addition, the TaskHost provides the ExecValueVariable property. С помощью этого свойства пользователь может сопоставить значение ExecutionValue, возвращаемое задачей, с любой другой переменной, доступной для задачи.This property lets the user map the ExecutionValue returned from the task to any variable visible to the task. Затем указанную переменную можно использовать для настройки элементов управления очередностью между задачами.The specified variable can then be used to establish precedence constraints between tasks.

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

В приведенном ниже примере кода показана реализация метода Execute и переопределенное свойство ExecutionValue.The following code example demonstrates an implementation of the Execute method, and shows an overridden ExecutionValue property. Задача удаляет файл, указанный в свойстве fileName задачи.The task deletes the file that is specified by the fileName property of the task. Задача выдает предупреждение, если файл не существует либо если свойство fileName является пустой строкой.The task posts a warning if the file does not exist, or if the fileName property is an empty string. Задача возвращает значение типа Boolean для свойства ExecutionValue, чтобы указать, был ли файл удален.The task returns a Boolean value in the ExecutionValue property to indicate whether the file was deleted.

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  

См. также:See Also

Создание пользовательской задачи Creating a Custom Task
Создание кода пользовательской задачи Coding a Custom Task
Разработка пользовательского интерфейса для пользовательской задачиDeveloping a User Interface for a Custom Task