Package configuration files are a great way of providing the values of SSIS package properties so that packages can be used in a far more versatile way. They make the deployment of SSIS packages easier and can provide parameters that are based on the server configuration, or which change for each runtime. They’re easy to understand, especially when explained by Rob Sheldon. 

When you develop a SQL Server Integration Services (SSIS) package, you can add package configurations in order to provide property values to the package at runtime. A package configuration is a defined property/value pair that can be modified without updating the package itself. Package configurations are useful when you want to deploy packages to multiple servers, when you move your packages from a development to production environment, or in any situation in which you want to provide property values to a package at runtime.

SSIS provides several methods for storing package configurations. One of the most flexible of those methods is the XML configuration file. The file lets you store one or more package configurations that can be used by one or more packages. The easiest way to create an XML configuration file is to use the Package Configuration wizard after you’ve set up your package. The wizard walks you through the steps necessary to create the file and lets you choose which property values you want to include in that file.

In this article, I walk you through the steps necessary to create an XML configuration file. To demonstrate these steps, I first used the following Transact-SQL code to create the People table in the AdventureWorks2008R2 database:

Notice that I inserted only one row. I simply wanted to create the table and use the simplest method for doing so. The table will be truncated when you run the package, so it doesn’t matter how many rows you insert into the table.

After I created the People table, I created an SSIS project in SQL Server Business Intelligence Development Studio (BIDS) and renamed the default package LoadPersonData.

I then added two OLE DB connection managers, which each point to the AdventureWorks2008R2 database on the same instance of SQL Server. (Normally, they would point to two different instances, but for testing purposes, this is fine.) The first connection manager is named Server A. The second one is named Server B.

After I added the connection managers, I defined a string variable named ConnectMngr and set its default value to “Server A.” The variable will be used in the control flow to indicate which connection manager to use. I then added an Execute SQL task and two Data Flow tasks to the control flow, as shown in Figure 1.

Figure 1: The control flow in the LoadPersonData SSIS package

The Execute SQL task truncates the People table. The precedence constraints that connect to the Data Flow tasks are each configured to evaluate to an expression. For example, Figure 2 shows how I configured the precedence constraint that connects to the Server A Data Flow task. Notice that the expression specifies that the ConnectMngr variable must equal “Server A” in order to evaluate to True.

Figure 2: Configuring the precedence constraint to evaluate to an expression

I configured the second precedence constraint just like the first one, except that the expression specifies “Server B” as the variable value.

Next I configured each Data Flow task with an OLE DB source and an OLE DB destination. The sources and destination use their respective connection managers. For example, the Server A data flow uses the Server A connection manager. Figure 3 shows the Server A data flow components. Each data flow retrieves data from the Person table in the AdventureWorks2008R2 database and inserts that data in the People table.

Figure 3: Configuring the data flow for the Server A connection manager

That’s all there is to setting up your SSIS package. Although this is a very simple package, it’s all we need to demonstrate how to implement XML configuration files. (Actually, we don’t even need that much.) If you don’t want to create this package, and instead want to use a package you’ve already created, you should have no trouble applying the steps in the rest of the article to your situation.

Setting Up Your XML Configuration File

After you’ve set up your package, the first step in setting up the XML configuration file is to enable package configurations. To do so, click the Package Configurations option on the SSIS menu. This launches the Package Configuration Organizer, shown in Figure 4.

Figure 4: The Package Configuration Organizer in SSIS

To enable package configurations on your package, select the Enable package configurations checkbox. You can then add your package configurations to the package. To do so, click Add to launch the Package Configuration wizard. When the wizard appears, click Next to skip the Welcome screen. The Select Configuration Type screen will appear, as shown in Figure 5.

Figure 5: The Select Configuration Type screen in the Package Configuration wizard

From the Configuration type drop-down list, select XML configuration file. You can then choose to specify your configuration settings directly or specify a Windows environment variable that stores the path and file names for the configuration file. For this example, I selected the Specify configuration settings directly option and specified the following path and file name: C:\Projects\SsisConfigFiles\LoadPersonData.dtsConfig. The main thing to notice is that the file should use the extension dtsConfig.

The next screen in the wizard is Select Properties to Export. As the name implies, this is where you select the properties for which you want package configurations. In this case, I selected the Value property for the ConnectMngr variable and the ServerName property for each of the two connections managers, as shown in Figure 6.

Figure 6: Selecting properties in the Package Configuration wizard

Because I chose three properties, three package configurations will be created in the XML file. You can choose as many properties as you want to add to your file.

On the next screen of the Package Configuration wizard, you provide a name for the configuration and review the settings (shown in Figure 7).

Figure 7: The Completing the Wizard screen in the Package Configuration wizard

If you’re satisfied with the settings, click Finish. The wizard will automatically generate the XML configuration file and add the properties that you’ve specified. The file will also be listed in the Package Configuration Organizer, as shown in Figure 8.

Figure 8: The XML package configuration as it’s listed in the Package Configuration Organizer

You should also verify whether the XML package configuration file has been created in the specified location. For this example, I added the file to the C:\Projects\SsisConfigFiles\ folder. The file is automatically saved with the dtsConfig extension. If you open the file in a text editor or browser, you should see the XML necessary for a configuration file. Figure 9 shows the LoadPersonData.dtsConfig file as it appears in Internet Explorer.

Figure 9: The XML in the LoadPersonData.dtsConfig file

As Figure 9 shows, the XML configuration file includes the <DTSConfigurationHeading> element. The element contains the attributes and their values that define when, who, and how the file was generated. The file also includes one <Configuration> element for each package configuration. Each <Configuration> element includes the attributes and their values necessary to determine which property is being referenced. Within each <Configuration> element is a nested <ConfiguredValue> element, which provides the property’s actual value.

Notice that the property values are the same as that of the package itself. When you first set up an XML configuration file, the current package value is used for each property. You can, of course, change those values, as I demonstrate later in the article.

Running Your SSIS Package

After you’ve created your XML configuration file, you’re ready to run your package. You run the package as you would any other SSIS package. However, because package configurations have been enabled, the package will check for any settings that have been predefined.

For the example I’ve been demonstrating here, the package will run as if nothing has changed because, as stated above, the XML configuration file contains the same values as the properties initially defined on the package. That means the ConnectMngr variable will still have a value of “Server A,” and the connection managers will still point to the same SQL Server computer. Figure 10 shows the package after it ran without modifying the XML configuration file.

Figure 10: Running the LoadPersonData package with the default settings

As you would expect, the Server A data flow ran, but not the Server B data flow. However, the advantage to using XML configuration files is that you can modify property settings without modifying the package itself. When the package runs, it checks the configuration file. If the file exists, it uses the values form the listed properties. That means if I change the property values in the file, the package will use those new values when it runs.

For instance, if I change the value of the ConnectMngr variable from “Server A” to “Server B,” the package will use the value. As a result, the precedence constraint that connects to the Server A Data Flow task will evaluate to False, and the precedence constraint that connects to the Server B Data Flow task will evaluate to True, and the Server B data flow will run. Figure 11 shows what happens if I change the variable’s value in the XML configuration file to “Server B.”

Figure 11: Running the Server B Data Flow task in the LoadPersonData SSIS package

As you would expect, the Server B Data Flow task ran, but not the Server A Data Flow task. If I had changed the values of the ServerName properties for the connection managers, my source and destination servers would also have been different.

Clearly, XML configuration files offer a great deal of flexibility for supplying property values to your packages. They are particularly handy when deploying your packages to different environments. Server and instance names can be easily changed, as can any other value. If you hard-code the path and file name of the XML configuration file into the package, as I’ve done in this example, then you must modify the package if that file location or name changes. You can get around this by using a Windows environment variable, but that’s not always a practical solution. In addition, you can override the configuration path and file names by using the /CONFIGURATION option with the DTExec utility.

Whatever approach you take, you’ll find XML configuration files to be a useful tool that can help streamline your development and deployment efforts. They’re easy to set up and maintain, and well worth the time it takes to learn how to use them and how to implement them into your solutions.

Script tasks are a great way of extending SSIS functionality, when none of the built-in components are quite right for the task you need to perform. But how to go about creating a script task? No worries, once again Robert Sheldon is on hand to provide easy instructions on how to do it.

One of the most effective ways to extend your SQL Server Integration Services (SSIS) control flow is to use aScript task to write custom code that perform tasks you cannot perform with the built-in components. For example, you can use the Script task to access Active Directory information or to create package-specific performance counters. You can also use the Script task to combine functions that might normally require multiple tasks and data flow components.

In this article, I demonstrate how to implement a Script task into the control flow of a basic SSIS package. The purpose of the package is to retrieve data from a comma-separated values (CSV) file, insert the data into a SQL Server table (though no data is actually loaded), and then delete the file. The package includes a Script task that will first determine if the file has been updated since the last data load and, if so, whether the file currently contains data. You can download the SSIS package file, along with the two data files (one with data, and one without) from the speech-bubble at the head of the article. You’ll have to rename the data file that you use to PersonData.CSV.

Setting Up Your SSIS Package

Before adding the Script task to your SSIS package, you should add and configure any components that are necessary to support the task, such as variables, connections managers, and other tasks. For the example in this article, however, I created a CSV file named PersonData.csv before adding any components to the package. To make it simpler for you to create the file, I’m including the bcp command I used to generate the file on my system:

Notice that the command retrieves Person data from the AdventureWorks2008R2 database and adds that data to the C:\DataFiles\PersonData.csv file. I also created a second bcp command to create an empty file with the same name. I did this in order to fully test the SSIS package. In the SELECT statement in the second command, I include a WHERE clause that references a nonexistent BusinessEntityID value:

Because I’m referencing a nonexistent BusinessEntityID value, the command creates an empty CSV file. You can use either file to test your SSIS package, should you decide to try the example I’m demonstrating in this article.

The Script task that I’ll be demonstrating will reference two SSIS user-defined variables, so after I created the CSV file, I added the following two variables to my package:

• IsEmpty: A Boolean variable with a package-level scope. The variable will be used by the Script task to specify whether the source CSV file contains data. I’ve set the initial value to False, but the Script task will set the final value, so you can set the initial value to either True or False.
• LastUpdate: A DateTime variable with a package-level scope. I’ve set the value as an arbitrary date that precedes the date that I created the CSV files. In theory, the LastUpdate variable stores the timestamp of the last time the package ran and updated the database. In reality, this date would probably come from a table or some other system that logged the updates. For this article, however, it serves our purposes to set a hard-coded date.

My next step was to create a Flat File connection manager named PersonData. The connection manager connects to the C:\DataFiles\PersonData.csv file. Other than naming the connection manager and providing a description, I retained the default settings for its other options.

The two variables and Flat File connection manager are the only SSIS components necessary to support the Scripttask that I’m going to demonstrate. So let’s look at how to add and configure that task.

Adding the Script Task to Your Package

After you add the Script task to your SSIS package, you can configure it by opening the Script Task Editor. On the editor’s General page, you should provide a name and description for the task. (I named the task Check file status.) Next, go to the editor’s Script page to configure the script-related properties, as shown in Figure 1.

Figure 1: Script page of the Script Task Editor

The first property that you need to set is ScriptLanguage. You can create your scripts in one of two languages: Visual Basic 2008 or Visual C# 2008. I used C# for the script that I created.

The next property on the Script page is EntryPoint. This is the method (specific to the selected script language) that the SSIS runtime calls as the entry point into your code. The Main method, in most cases, should work fine. However, if you choose another method, it must be in the ScriptMain class of the Visual Studio for Applications (VSTA) project.

The next two properties on the Script page are ReadOnlyVariables and ReadWriteVariables. As the names imply, you enter the name of any SSIS variables you want to use in your script. (Separate the names with commas for multiple variables of either type.) For instance, I added the LastUpdate variable to the ReadOnlyVariables property and the IsEmpty variable to the ReadWriteVariables property. As a result, my C# script will be able to retrieve the date from the LastUpdate variable and set the file status in the IsEmpty variable.

That’s all there is to configuring the Script task properties in preparation for creating the script itself, so once you’ve configured the properties, click the Edit Script button on the editor’s Script page to open the VSTA integrated development environment (IDE) window, shown in Figure 2. All script modifications are made in the VSTA development environment.

Figure 2: Default C# code in the VSTA IDE window

As Figure 2 shows, when you first open the VSTA window, you’ll see the default C# script, which includes the language necessary to work with the Main method of the ScriptMain class. Because Figure 2 shows only part of the script, I’m included the entire default code here for your convenience:

For the most part, you need to be concerned only with adding code to the Main method, specifically, to the section that is marked with the comment // TODO: Add your code here. (Comments are either preceded by double slashes for a single line or enclosed slashes and asterisks—/* and */—for multiple lines.) Usually, the only exception to where you enter code is at the beginning of the script, where you include the necessary usingstatements to define the relevant namespaces. For instance, the script includes the using System; statement so we can access classes in the System namespace, like those that reference components such as events, interfaces, and data types.

Other than the using statements and the Main method, you should, for the most part, leave the rest of the code alone, except for perhaps deleting comments. (Unless you’re a C# pro—then have add it.) Now let’s look how to modify the script to check the status of our flat file.

Writing Your C# Script

The first step I often take when working the code in the Script task is to get rid of the comments. In this case, I removed the comments before the Main method. You can also delete the opening comments, but I left them in just to provide a few reminders about the environment in which we’re working. So let’s look at how I’ve modified the script, and then I’ll explain the changes I’ve made. The following code shows how I’ve updated the original script and expanded the Main method:

Let’s start with the using statements at the beginning of the script. You might have noticed that I added the usingSystem.IO; statement. The System.IO namespace lets us access the language components we need in order to retrieve information about the flat file. I did not modify the script outside the Main method in any other way (except for deleting comments), so now let’s look at that method.

The first item I added after the Main method declaration is a DateTime variable named LastLoggedUpdate:

I’ve set the variable value to equal that of the SSIS LastUpdate variable that I defined on the package. To retrieve the value of the SSIS variable, I use the Dts object’s Variables property, which returns a Variable object. I then specify the name of the variable, enclosed in double-quotes and brackets, and tag on the Value property (available through the Variable object). This lets me retrieve the variable’s actual value. Note that I also cast the LastUpdate value to the DateTime data type by preceding the Dts variable construction by the name of the data type, just like I do when I declare the LastLoggedUpdate variable. I can now reference the LastLoggedUpdate variable within the Main method, and it will return the data currently stored the LastUpdate SSIS variable.

Next I declare a string variable named PersonDataConnection to hold the connection string I retrieve through thePersonData connection manager:

Notice that my declaration once again begins with the data type, followed by the name of the variable. I then set the variable’s value to equal the connection string. I retrieve the connection string by using the Dts object’sConnections property. This is followed by the name of the connection manager, enclosed in double-quotes and brackets, and then by the AcquireConnection method. The method takes one argument—the handle to a transaction type. In this case, we can specify NULL , which indicates that the container supports transactions but is not going to participate. In other words, you don’t need to worry about this. Just pass in NULL for this type of connection. Notice also that I’m explicitly converting the connection object to a string to pass into thePersonDataConnection variable.

The next variable I declare is PersonDataFile, which is defined with type FileInfo:

In this case, the variable’s value is based on a new instance of the FileInfo class. Because the FileInfo constructor takes the PersonDataConnection variable as an argument, you can use the methods and properties available to the FileInfo class to access information about the PersonData.csv file. That means you can access those properties and methods through the PersonDataFile variable, which is what I do in the next two variable declarations:

First, I declare a DateTime variable named LastModified and set its value to equal the value of the LastWriteTimeproperty of the PersonDataFile variable, which is a FileInfo object. This will provide me with a timestamp of the last time the file was modified. I declare the second variable with the long data type and name the variablePersonFileSize. I then set the variable value to equal that of the file object’s Length property.

After I’ve declared the necessary variables, I’m ready to implement the logic needed to check the status of the PersonData.csv file. In the next section of code, I include two if…else statements, one embedded in the other:

Let’s start by looking at the outer if…else construction. Essentially, what this is saying is, “If the last modified date is more recent that the last time data was loaded into the database, run the script in the if section. Otherwise, skip to the end of the script and show the Script task as having failed.

The if statement begins by specifying the condition that determines whether to run the code in the if section or in the else section. If the condition evaluates to True—in this case, the LastModified date is more recent that theLastLoggedUpdate date—the code in the rest of the if section should run. If the condition does not evaluate to true, the code in the if section does not run and the code in the else section runs, which sets the Dts object’s TaskResult property to Failure. (The TaskResult property tells the runtime whether the task succeeded or failed.)

The embedded if…else construction checks whether the value in the PersonFileSize variable is greater than 0, in other words, whether the file contains any data. If the file does contain data, the code in the if section runs, otherwise the code in the else section runs. As a result, if the file contains data, the SSIS IsEmpty variable is set to false. If the file contains no data, the variable is set to true. Notice that after the embedded if…else construction, I’ve set the value of the TaskResult property to show that the task has successfully run.

That’s all there is to the script. Normally, you would also include code to handle exceptions, but what I’ve shown you here should provide you with an overview of the script’s basics elements. You can now close the VSTA window and then click OK to close the Script Task Editor. Be sure to save your changes.

Adding Other Tasks to Your Package

After I completed configuring the Script task and writing the C# script, I added a Data Flow task to the control flow. The data flow should, in theory, retrieve the data from the PersonData.csv file and insert it into a SQL Server database. However, for the purposes of this exercise, the Data Flow task serves only as a placeholder. It will still run like any other Data Flow task, but no data will actually be moved. Even so, you can still verify whether your control flow is set up correctly.

Next, I connected a precedence constraint from the Script task to the Data Flow task. I then added a File Systemtask to the control flow and configured it to delete the PersonData.csv file. Next I connected a precedence constraint from the Script task to the File System task and one from the Data Flow task to the File System task. I then configured the two precedence constraints connecting to the File System task with the Logical OR option, which means that only one constraint must evaluate to True for the task to run. (By default, all constraints connected to a task must evaluate to True for the task to run.) Figure 3 shows what the control flow looked like after I added all the components.

Figure 3: Adding a Data Flow task and File System task to the control flow

Notice how the precedence constraints connecting to the File System task are dotted lines. This indicates that the constraints have been configured with the Logical OR option. Also notice that an expression is associated with each of the precedence constraints leading out of the Script task (as indicated by the fx label). Both constraints are configured so that the tasks down the line will run only if the Script task runs successfully and the expression evaluates to True. I defined the following expression on the precedence constraint that connects to the Data Flowtask:

This means that the IsEmpty variable must be set to False in order for the expression to evaluate to True. The expression defined on the precedence constraint that leads from the Script task to the File System task is as follows:

This means, of course, that the IsEmpty variable must be set to True for the expression to evaluate to True. And that about does it for setting up the SSIS package. The only other step I took was to add a breakpoint to the Script task, which I’ll explain in the following section.

Running Your SSIS Package

Before I ran the SSIS package, I added a breakpoint on the OnPostExecute event to the Script task. As a result, when I ran the package, it stopped running as it was about to complete the Script task. Figure 4 shows what the package looks like when it stopped running.

Figure 4: Using a breakpoint to view variable values

When the package stopped running, I added a watch (shown in the bottom pane in Figure 4) on each of the two variables I created early on. The watches show the variable values at the time the package reached the breakpoint. Notice that the IsEmpty variable is set to False. Had the PersonData.csv file contained no data, the variable would have been set to True.

Next, I resumed running the package until it executing all applicable tasks. As Figure 5 shows, every control flow task ran. That’s because the IsEmpty variable evaluated to False and the Data Flow task ran and then the File System task ran.

Figure 5: Running the SSIS package when IsEmpty is false.

If the IsEmpty variable had evaluated to True, the Data Flow task would not have run, which is what happened when I added an empty file to the C:\DataFiles folder. This time around, only the Script task and File System task ran, as shown in Figure 6.

Notice that the value of the IsEmpty variable shown in the Watch window is set to True. As a result, the file would have been deleted, but no attempts would have been made to load data into the database.

And It Doesn’t End There

In the example above, the SSIS package performed in two different ways, depending on whether the file contained data. But there is a third scenario: the file was not updated since the last data load. If that happens, the Script task fails and the package stops running, which is what we’d expect given the way the script is written in the Script task. Another thing that the example doesn’t reflect is what would happen if the script threw an exception. Given that I’ve included no exception handling, I would again expect the task to fail. What this points to is that the example I’ve shown you here is only a simple script that contains relatively few elements. A script can be far more complex and take many more actions than what I’ve demonstrated here. However, you should now at least have enough information to get started creating your own scripts and using the Script task to extend your control flow so you can perform the tasks that need to be performed.

SSIS event handlers are the simplest means of turning an SSIS script into a reliable system that is auditable, reacts appropriately to error conditions, reports progress and allows instrumentation and monitoring your SSIS packages. They are easy to implement, and provide a great deal of flexibility. Rob Sheldon once again provides the easy, clear introduction.

Since the release of SQL Server 2005, SQL Server Integration Services (SSIS) has proven to be an effective tool for managing extract, load, and transform (ETL) operations. However, most of the material you find about developing SSIS packages focuses on the control flow and data flow as they’re rendered in Business Intelligence Development Studio (BIDS). But another important—and often overlooked—feature in an SSIS package is the event handler.

Event handlers let you run SSIS components on a per-executable, per-event basis. For example, suppose your package includes a Foreach Loop container. You can associate one or more SSIS components with each event generated by that container when it is executed. This includes such events as OnError, OnInformation, andOnPostExecute. The components you associate with the container’s events are separate from the regular control flow. Consequently, you can configure them specifically to the needs of the associated event handler. This will all become clearer as I demonstrate how to configure an event handler.

In this article I explain how to add event handlers to an SSIS package. The package in this case inserts data into two tables I created in the AdventureWorks2008 sample database on a local instance of SQL Server 2008. The first table, People, will be the target of the package after that package extracts data from the Person.Person table in the AdventureWorks2008 database. The second table, RunInfo, will store data that is generated by the event handlers I’ll be adding to the package The following Transact-SQL script includes the CREATE TABLE statements necessary to add both tables:

After I added the two tables to the database, I created the SSIS package. Figure 1 shows the control flow of the package after I added the necessary components. As the figure indicates, the control flow includes an Execute SQL task to truncate the People table and includes a Sequence container that contains two Data Flow tasks.

Figure 1: Configuring the control flow

      Notice that Figure 1 also shows the AdventureWorks2008 connection manager, which is an OLE DBconnection manager that connects to the AdventureWorks2008 database on the local instance of SQL Server 2008. I use this connection manager for all my connections.

Next I configured the two data flows. The Load Data 1 data flow, shown in Figure 2, uses an OLE DB source to retrieve data from the Person.Person table and a SQL Server destination to insert data into the People table.

Figure 2: Configuring the Load Data 1 data flow

When I configured the OLE DB source, I used the following SELECT statement to retrieve data from the Person.Person table:

Notice that I retrieve only those rows whose BusinessEntityID value is less that 10000. The Load Data 2 data flow is identical to Load Data 1, except that I used the following SELECT statement:

As you can see, this time I’m retrieving only those rows whose BusinessEntityID value is greater than or equal to 10000. I set up the two data flows in this way to better demonstrate the relationship between executables and event handlers in the SSIS package. You can download the completed package from the speech-bubble at the head of this article, or you can simply create the package yourself. If you’re uncertain how to create an SSIS package or configure any of these components, be sure to check out SQL Server Books Online. Once you’ve set up your package, you’re ready to add the event handlers.

Selecting an Executable and Event

You configure your event handlers on the Event Handlers tab of SSIS Designer. The tab, shown in Figure 3, provides access to the package’s executables and to the events associated with each executable. The tab also provides the design surface necessary to add components to an event handler, just as you would add components to the control flow.

Figure 3: Accessing the Event Handlers tab

When you first access the Event Handlers tab, the selected executable is the package itself, which in this case, I’ve named EventHandlersPkg. In addition, the selected event is OnError. As a result, any components you would add to the design surface at this point would be specific to this combination of this executable and event pair. To view all the executables, click the down-arrow on the Executable text box and then expand the list of executables, as shown in Figure 4.

Figure 4: Viewing the package executables

Notice that the executables are listed hierarchically, with EventHandlersPkg at the top of the hierarchy and theExecute SQL task (Truncate People table) and the Sequence container (Load People data) at the second level of the hierarchy. At the third level, below the Sequence container, are the two Data Flow tasks (Load Data 1 and Load Data 2). For each executable, a folder named Event Handlers is listed. Any event handlers you configure for an executable are listed in that folder, with the event handlers sorted by event.

For each executable, you will find a list of events in the Event handler list. The list includes all the events associated with the selected executable. To select an event for an executable, click the down-arrow in the Event handler list, shown in Figure 5, and then select the event.

 

Figure 5: Viewing the package events

When working on the design surface of the Event Handlers tab, you are always working with a specific executable-event pair. That means, in order to configure an event handler, you must first select an executable and then select the event. For example, if you refer to Figure 6, you’ll see that I’ve selected the Truncate People table executable and then selected the OnError event. As a result, any components I add to this executable-event pair will run whenever the Truncate People table executable generates an OnError event.

Figure 6: Selecting an executable and event handler

Once you’ve selected your executable-event pair, you’re ready to add your components, so let’s take a look at how you do that.

Configuring the Event Handler

If you refer back to Figure 6, you’ll notice that the design surface includes a link that instructs you to click it in order to create an event handler for that specific event and executable. You’ll be presented with this link for any executable-event pair for which an event handler has not been configured. You must click this link to create the event handler and add any components.

The first event handler we’ll create is for the Load Data 1 executable and the OnPostExecute event. After you select the executable-event pair and click the link, you’re ready to go. For the EventHandlersPkg package, I’ve added anExecute SQL task, as shown in Figure 7. You add the task just as you would add any component to the control flow.

Figure 7: Adding an Execute SQL task to an event handler

When you configure an event handler, you can use any of the system or user variables available to the executable, so let’s look at the variables available to the Load Data 1 executable. To view these variables, open the Variablespane in SSIS Designer by clicking Variables in the SSIS menu. Then, in the Variables pane, click Show System Variables to list all variables available to your event handler components, as shown in Figure 8.

Figure 8: Viewing the variables in the Variables pane

In this case, we want to use the SourceID and SourceName system variables to identify the components that are generating the OnPostExecute events, which is what we’ll log to the RunInfo table. We’ll be adding the variables in the Execute SQL task, so let’s look at how you configure that task. Figure 9 shows the General page of the Execute SQL Task editor.

Figure 9: General tab of the Execute SQL Task Editor

Notice that I’ve specified the AdventureWorks2008 connection manager in the Connection property. Then, in theSQLStatement property, I added the following INSERT statement:

As you can see, I’ve included two question mark placeholders in the VALUES clause. The placeholders allow you to insert the values from the SourceID and SourceName system variables into the RunInfo table. However, to do this, you must also map the variables  to the statement. Figure 10 shows the Parameter Mapping page of theExecute SQL Task editor, which includes a listing for each variable that will be used by the INSERT statement.

Figure 10: Parameter Mapping tab of the Execute SQL Task Editor

As Figure 10 indicates, both variables are input variables configured with the NVARCHAR data type. In addition, the name of the first variable (SourceID) is 0, and the name of the second variable (SourceName) is 1. This follows the naming conventions necessary to pass parameter values into the INSERT statement. That’s all there is to configuring the Execute SQL task. And that’s also the only component I added to the Load Data 1 executable. However, I also configured the same event for the Load Data 2 executable and then added an Execute SQL task to the event handler, set up just like the task in Load Data 1. That means when the SSIS package runs, it will execute two event handlers, one for each data flow.

Running the SSIS Package

Once you’ve configured your event handlers, you’re ready to run the SSIS package. Running a package that contains event handlers is no different from running any other type of package. The event handlers will be executed as long as the executable issues the event for which SSIS components have been configured. That means, in this case, as long as the Data Flow tasks run successfully, the OnPostExecute events will be issued and the Execute SQL tasks will run. The INSERT statements within those tasks will then add the variable information to the RunInfo table.

After I ran the EventHandlersPkg package the first time, I queried the RunInfo table and received the following results:

RunID	TaskID	TaskName	TaskTime
1	{85B4ED54-D20D-4E90-B60C-E0151D7B1348}	Load Data 1	2011-04-17 19:25:13.370
2	{057C0C52-99B1-4B96-BDC8-923A6A85CCBE}	Load Data 2	2011-04-17 19:25:13.670

 

As you can see, the task ID and task names have been added to the table, and as expected, there is one row for each task. If you run the package multiple times, you will see additional rows.

Although the example I’ve demonstrated in this article is very basic, it does show you the power of event handlers to capture a variety of information under specific circumstances. And you can perform other actions as well. For example, in addition to being able to set up a system to audit your packages, you can take such steps as sending an email if an executable issues an OnError event. SSIS event handlers are flexible and provide many options for auditing and monitoring your SSIS packages. And given how easy they are to implement, it is well worth the time and effort to take full advantage of all that event handlers have to offer.