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.
Contains a collection of ConnectionManager objects available to the task.
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.
Contains the methods called by the task to raise events to the run-time engine.
Contains methods and properties used by the task to write entries to the event log.
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.
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