Codificar una tarea personalizadaCoding a Custom Task

Se aplica a:Applies to: síSQL ServerSQL Server (todas las versiones admitidas) yesSQL ServerSQL Server (all supported versions) sí SSIS Integration Runtime en Azure Data FactorySSIS Integration Runtime in Azure Data Factoryyes SSIS Integration Runtime en Azure Data FactorySSIS Integration Runtime in Azure Data FactorySe aplica a:Applies to: síSQL ServerSQL Server (todas las versiones admitidas) yesSQL ServerSQL Server (all supported versions) sí SSIS Integration Runtime en Azure Data FactorySSIS Integration Runtime in Azure Data Factoryyes SSIS Integration Runtime en Azure Data FactorySSIS Integration Runtime in Azure Data Factory

Una vez que haya creado una clase que herede de la clase base Microsoft.SqlServer.Dts.Runtime.Task y haya aplicado el atributo DtsTaskAttribute a la clase, debe invalidar la implementación de las propiedades y los métodos de la clase base para proporcionar la funcionalidad personalizada.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.

Configurar la tareaConfiguring the Task

Validar la tareaValidating the Task

Al diseñar un paquete de Integration ServicesIntegration Services, puede usar la validación para comprobar la configuración en cada tarea, de manera que pueda detectar los valores incorrectos o inadecuados en cuanto se establezcan, en lugar de buscar todos los errores solo en tiempo de ejecución.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. El propósito de la validación es determinar si la tarea contiene conexiones o valores no válidos que impedirán que se ejecute correctamente.The purpose of validation is to determine whether the task contains invalid settings or connections that will prevent it from running successfully. De esta manera se garantiza que el paquete contiene tareas con muchas posibilidades de que se ejecuten en su primera ejecución.This makes sure that the package contains tasks that have a good chance of running on their first run.

Puede implementar la validación mediante el método Validate en código personalizado.You can implement validation by using the Validate method in custom code. El motor en tiempo de ejecución valida una tarea mediante una llamada al método Validate en la tarea.The run-time engine validates a task by calling the Validate method on the task. Es responsabilidad del programador de la tarea definir los criterios que dan como correcta o errónea una validación de tarea, así como notificar el motor en tiempo de ejecución del resultado de esta evaluación.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.

Clase base abstracta TaskTask Abstract Base Class

La clase base abstracta Microsoft.SqlServer.Dts.Runtime.Task proporciona el método Validate que cada tarea invalida para definir sus criterios de validación.The Microsoft.SqlServer.Dts.Runtime.Task abstract base class provides the Validate method that each task overrides to define its validation criteria. El Diseñador SSISSSIS llama automáticamente varias veces al método Validate durante el diseño del paquete y, cuando se producen advertencias o errores, proporciona al usuario indicaciones visuales que le sirven de ayuda para identificar cualquier problema con la configuración de la tarea.The SSISSSIS 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. Las tareas proporcionan los resultados de la validación devolviendo un valor de la enumeración DTSExecResult y provocando eventos de errores y advertencias.Tasks provide validation results by returning a value from the DTSExecResult enumeration, and by raising warning and error events. Estos eventos contienen información que se muestra al usuario en el Diseñador SSISSSIS.These events contain information that is displayed to the user in SSISSSIS Designer.

A continuación, se enumeran algunos ejemplos de validación:Some examples for validation follow:

  • Un administrador de conexiones valida el nombre de archivo específico.A connection manager validates the specific file name.

  • Un administrador de conexiones valida que el tipo de entrada es el tipo esperado, como un archivo XML.A connection manager validates that the type of input is the expected type, such as an XML file.

  • Una tarea que espera la base de datos de entrada comprueba que no puede recibir datos de una conexión que no corresponde a una base de datos.A task that expects database input verifies that it cannot receive data from a non-database connection.

  • Una tarea garantiza que ninguno de sus propiedades contradice otras propiedades establecidas en la misma tarea.A task guarantees that none of its properties contradicts other properties set on the same task.

  • Una tarea garantiza que están disponibles todos los recursos necesarios que usa la tarea en tiempo de ejecución.A task guarantees that all required resources used by the task at execution time are available.

El rendimiento es algo que hay que tener en cuenta para determinar lo que se valida y lo que no.Performance is something to consider in determining what is validated and what is not. Por ejemplo, la entrada para una tarea podría ser una conexión a través de una red que tiene poco ancho banda o mucha intensidad de tráfico.For example, the input to a task might be a connection over a network that has low bandwidth or heavy traffic. La validación puede tardar varios segundos para procesar si decide validar que el recurso está disponible.The validation may take several seconds to process if you decide to validate that the resource is available. Otra validación puede producir un viaje de ida y vuelta (round trip) a un servidor de gran demanda y la rutina de validación podría ser lenta.Another validation may cause a round-trip to a server that is in high demand, and the validation routine might be slow. Aunque hay muchas propiedades y configuraciones que se pueden validar, no se debería validar todo.Although there are many properties and settings that can be validated, not everything should be validated.

  • La clase TaskHost también llama al código del método Validate antes de que se ejecute la tarea. Asimismo, la clase TaskHost cancela la ejecución si se produce un error en la validación.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.

Consideraciones de interfaz de usuario durante la validaciónUser Interface Considerations during Validation

Microsoft.SqlServer.Dts.Runtime.Task incluye una interfaz IDTSComponentEvents como parámetro para el método Validate.The Microsoft.SqlServer.Dts.Runtime.Task includes an IDTSComponentEvents interface as a parameter to the Validate method. La interfaz IDTSComponentEvents contiene los métodos a los que llama la tarea para producir eventos en el motor en tiempo de ejecución.The IDTSComponentEvents interface contains the methods that are called by the task in order to raise events to the run-time engine. Se llama a los métodos FireWarning y FireError cuando se produce una advertencia o condición de error durante la validación.The FireWarning and FireError methods are called when a warning or error condition occurs during validation. Ambos métodos de advertencia requieren los mismos parámetros que incluyen un código de error, componente de origen, descripción, archivo de Ayuda e información de contexto de ayuda.Both warning methods require the same parameters, which include an error code, source component, description, Help file, and Help context information. El Diseñador SSISSSIS usa esta información para mostrar indicaciones visuales en la superficie de diseño.The SSISSSIS Designer uses this information to display visual cues on the design surface. Las indicaciones visuales que proporciona el diseñador incluyen un icono de exclamación que aparece junto a la tarea en la superficie del diseñador.The visual cues that are provided by the designer include an exclamation icon that appears next to the task on the designer surface. Esta indicación visual muestra al usuario que la tarea requiere configuración adicional antes de que la ejecución pueda continuar.This visual cue signals to the user that the task requires additional configuration before execution can continue.

El icono de exclamación también muestra una información sobre herramientas que contiene un mensaje de error.The exclamation icon also displays a ToolTip that contains an error message. La tarea proporciona el mensaje de error en el parámetro de descripción del evento.The error message is provided by the task in the description parameter of the event. Los mensajes de error también se muestran en el panel Lista de tareas de SQL Server Data Tools (SSDT)SQL Server Data Tools (SSDT), que proporciona al usuario una ubicación central para ver todos los errores de validación.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.

Ejemplo de validaciónValidation Example

En el ejemplo de código siguiente se muestra una tarea con una propiedad UserName.The following code example shows a task with a UserName property. Esta propiedad se ha especificado como la propiedad necesaria para que la validación sea correcta.This property has been specified as required for validation to succeed. Si no se establece la propiedad, la tarea expone un error y devuelve Failure de la enumeración DTSExecResult.If the property is not set, the task posts an error, and returns Failure from the DTSExecResult enumeration. El método Validate se encapsula en un bloque try/catch y produce un error en la validación si se produce una excepción.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  

Conservar la tareaPersisting the Task

Normalmente, no tiene que implementar la persistencia personalizada para una tarea.Ordinarily you do not have to implement custom persistence for a task. Solo se requiere la persistencia personalizada cuando las propiedades de un objeto usan tipos de datos complejos.Custom persistence is required only when the properties of an object use complex data types. Para obtener más información, vea Developing Custom Objects for Integration Services (Desarrollar objetos personalizados para Integration Services).For more information, see Developing Custom Objects for Integration Services.

Ejecutar la tareaExecuting the Task

En esta sección se describe cómo usar el método Execute que las tareas heredan e invalidan.This section describes how to use the Execute method that is inherited and overridden by tasks. En esta sección también se explican varias maneras de proporcionar información sobre los resultados de la ejecución de la tarea.This section also explains various ways of providing information about the results of task execution.

Método ExecuteExecute Method

Las tareas que están incluidas en un paquete se ejecutan cuando el entorno en tiempo de ejecución de Integration ServicesIntegration Services llama a su método Execute.Tasks that are contained in a package run when the Integration ServicesIntegration Services runtime calls their Execute method. Las tareas implementan su lógica de negocios y funcionalidad principal en este método, y proporcionan los resultados de ejecución mediante la publicación de mensajes, la devolución de un valor de la enumeración DTSExecResult y la invalidación de la propiedad get de la propiedad 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.

La clase base Microsoft.SqlServer.Dts.Runtime.Task proporciona una implementación predeterminada del método Execute.The Microsoft.SqlServer.Dts.Runtime.Task base class provides a default implementation of the Execute method. Las tareas personalizadas invalidan este método para definir su funcionalidad en tiempo de ejecución.The custom tasks override this method to define their run-time functionality. El objeto TaskHost ajusta la tarea, aislándola del motor en tiempo de ejecución y de los demás objetos del paquete.The TaskHost object wraps the task, isolating it from the run-time engine and the other objects in the package. Debido a este aislamiento, la tarea no es consciente de su ubicación en el paquete con respecto a su orden de ejecución, y se ejecuta únicamente cuando se llama por el tiempo de ejecución.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. Esta arquitectura evita los problemas que se pueden producir cuando las tareas modifican el paquete durante la ejecución.This architecture prevents problems that can occur when tasks modify the package during execution. La tarea proporciona acceso a los demás objetos del paquete únicamente a través de los objetos que se le suministran como parámetros en el método 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. Estos parámetros permiten que las tareas produzcan eventos, escriban las entradas en el registro de eventos, tengan acceso a la colección de variables y den de alta las conexiones a los orígenes de datos en transacciones, a la vez que se mantiene todavía el aislamiento necesario para garantizar la estabilidad y confiabilidad del paquete.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.

En la tabla siguiente se enumeran los parámetros que se proporcionan a la tarea en el método Execute.The following table lists the parameters provided to the task in the Execute method.

ParámetroParameter DescripciónDescription
Connections Contiene una colección de objetos ConnectionManager disponibles para la tarea.Contains a collection of ConnectionManager objects available to the task.
VariableDispenser Contiene las variables disponibles para la tarea.Contains the variables available to the task. Las tareas usan variables a través de VariableDispenser; las tareas no usan directamente las variables.The tasks use variables through the VariableDispenser; the tasks do not use variables directly. VariableDispenser bloquea y desbloquea las variables y evita los interbloqueos o sobrescrituras.The variable dispenser locks and unlocks variables, and prevents deadlocks or overwrites.
IDTSComponentEvents Contiene los métodos que la tarea llama para producir eventos en el motor en tiempo de ejecución.Contains the methods called by the task to raise events to the run-time engine.
IDTSLogging Contiene los métodos y propiedades que usa la tarea para escribir entradas en el registro de eventos.Contains methods and properties used by the task to write entries to the event log.
ObjectObject Contiene el objeto de transacción del que forma parte el contenedor, si existe.Contains the transaction object that the container is a part of, if any. Este valor se pasa como un parámetro al método AcquireConnection de un objeto ConnectionManager.This value is passed as a parameter to the AcquireConnection method of a ConnectionManager object.

Proporcionar comentarios de ejecuciónProviding Execution Feedback

Las tareas ajustan su código en bloques try/catch para evitar que se generen excepciones en el motor en tiempo de ejecución.Tasks wrap their code in try/catch blocks to prevent exceptions from being raised to the run-time engine. Esto asegura que el paquete termina la ejecución y no se detiene de forma inesperada.This ensures that the package finishes execution and does not stop unexpectedly. Sin embargo, el motor en tiempo de ejecución proporciona otros mecanismos para controlar las condiciones de error que se pueden producir durante la ejecución de una tarea.However, the run-time engine provides other mechanisms for handling error conditions that can occur during the execution of a task. Estos mecanismos incluyen la exposición de mensajes de error y advertencia, la devolución de un valor de la estructura DTSExecResult, la exposición de mensajes, la devolución del valor DTSExecResult y la divulgación de información acerca de los resultados de ejecución de la tarea a través de la propiedad 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.

La interfaz IDTSComponentEvents contiene los métodos FireWarning y FireError, a los que la tarea puede llamar para exponer mensajes de error y advertencia en el motor en tiempo de ejecución.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. Ambos métodos requieren parámetros como el código de error, componente de origen, descripción, archivo de Ayuda e información de contexto de ayuda.Both methods require parameters such as the error code, source component, description, Help file, and help context information. Dependiendo de la configuración de la tarea, el tiempo de ejecución responde a estos mensajes provocando eventos y puntos de interrupción o escribiendo información en el registro de eventos.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 también facilita la propiedad ExecutionValue que se usa para proporcionar la información adicional sobre los resultados de ejecución.The TaskHost also provides the ExecutionValue property that can be used to provide additional information about the results of execution. Por ejemplo, si una tarea elimina las filas de una tabla como parte de su método Execute, podría devolver el número de filas eliminadas como el valor de la propiedad 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. Además, TaskHost proporciona la propiedad ExecValueVariable.In addition, the TaskHost provides the ExecValueVariable property. Esta propiedad permite al usuario asignar la propiedad ExecutionValue que devuelve la tarea a cualquier variable visible en la tarea.This property lets the user map the ExecutionValue returned from the task to any variable visible to the task. En ese momento la variable especificada se puede usar para establecer las restricciones de precedencia entre las tareas.The specified variable can then be used to establish precedence constraints between tasks.

Ejemplo de ejecuciónExecution Example

En el ejemplo de código siguiente se muestra una implementación del método Execute y se expone una propiedad ExecutionValue invalidada.The following code example demonstrates an implementation of the Execute method, and shows an overridden ExecutionValue property. La tarea elimina el archivo que especifica la propiedad fileName de la tarea.The task deletes the file that is specified by the fileName property of the task. La tarea expone una advertencia si el archivo no existe, o si la propiedad fileName es una cadena vacía.The task posts a warning if the file does not exist, or if the fileName property is an empty string. La tarea devuelve un valor booleanoExecutionValue en la propiedad para indicar si se eliminó el archivo.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  

Consulte tambiénSee Also

Creating a Custom Task (Crear una tarea personalizada)Creating a Custom Task
Programar una tarea personalizada Coding a Custom Task
Desarrollar una interfaz de usuario para una tarea personalizadaDeveloping a User Interface for a Custom Task