Export (0) Print
Expand All

Implementing the Execute Method in a Custom Task 

This section describes how to use the Execute method that is inherited and overridden by tasks, and describes in detail various ways of providing information about the results of task execution.

Tasks that are contained in a package run when the Integration Services runtime calls their Execute method. 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.

The Task base class provides a default implementation of the Execute method. The custom tasks override this method to define their run-time functionality. The TaskHost object wraps the task, isolating it from the run-time engine and the other objects in the package. Because of its 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. Because of its isolation, the task is provided access to the objects in the package through the objects supplied to it as parameters in the Execute method. 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.

The following table lists the parameters provided to the task in the Execute method.

Parameter Description

Connections

Contains a collection of ConnectionManager objects available to the task.

VariableDispenser

Contains the variables available to the task. The tasks use variables through the VariableDispenser; the tasks do not use variables directly. 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. This value is passed as a parameter to the AcquireConnection method of a ConnectionManager object.

Tasks wrap their code in try/catch blocks to prevent exceptions from being raised to the run-time engine. This makes sure 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. These include posting error and warning messages, returning a value from the DTSExecResult structure, posting messages, returning the DTSExecResult value, and disclose information about the results of task execution by overriding the implementation of the get property on the ExecutionValue property.

The IDTSComponentEvents interface contains the FireWarning and FireError methods that 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 that the run-time engine uses to process the message. 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.

The TaskHost provides the ExecutionValue property through the ExecValueVariable property that is used by the task to provide information about the results of execution. This property lets the user map the ExecutionValue returned from the task to any variable visible to the task that could then be used as the criteria for determining the next task executed in the control flow. 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 ExecutionValue. Clients of the task could then use this value to establish precedence constraints between tasks.

Example

The following code example demonstrates an implementation of the Execute method, and shows an overridden ExecutionValue property. The task deletes the file that is specified by the fileName property of the task. The task posts a warning if the file does not exist, or if the fileName property is an empty string. The task returns a Boolean value in the ExecutionValue property to indicate whether the file was deleted.

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 Variables, ByVal events As IDTSComponentEvents, ByVal log As IDTSLogging, ByVal txn As DtsTransaction) As DTSExecResult
      Try
         If Me.fileName = "" Then
            events.OnWarning(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.OnError(0,"Sampletask",exception.Message,"",0) 
         Return DTSExecResult.FAILURE
      End Try
   End Function
   Public Property FileName() As Boolean
       Get 
          Return Me.fileName
       End Get
       Set (ByVal Value As Boolean) 
          Me.fileName = value
       End Set
   End Property
   Public Overrides ReadOnly Property ExecutionValue() As Object
       Get 
          Return Me.fileDeleted
       End Get
   End Property
End Class
Show:
© 2014 Microsoft