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.
Task Execution Method
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 |
|---|---|
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. |
|
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. |
Providing Execution Feedback
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.
using System;
using Microsoft.SqlServer.Dts.Runtime;
public class SampleTask : Task
{
private string fileName = "";
private bool fileDeleted = false;
public override DTSExecResult Execute(Connections cons, Variables vars, IDTSComponentEvents events, IDTSLogging log, DtsTransaction txn)
{
try
{
if(this.fileName == "")
{
events.OnWarning(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.OnError(0,"Sampletask",exception.Message,"",0) ;
return DTSExecResult.FAILURE;
}
}
public bool 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 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
See Also
Concepts
Developing a Custom Task
Integration Services Programming
Other Resources
Extending Packages with Custom Objects