Property Expressions

Property expressions are as the name impliesexpressions on properties. It is a way to have the value of a property automatically set to the result of an expression.

Suppose you want a property on a task to have the value of 42. You could simply set the property value directly by typing it into the task's user interface or into the property grid in the designer. Property expressions allow you to assign an expression to that property, for example 11+31. From that time forward, the value of the property is the result of the expression in the propertynot the value you set. It is still 42, but the value of the property is actually the result of the expression, not a static value typed into the property directly. In addition, variables can be referenced in expressions. Because variable values can be set in so many waysfor example, configurations, other tasks, or the package writerexpressions can be applied in virtually unlimited ways to affect the execution of packages based on dynamic input from external influences. If you set a value of a property or variable, but the package seems to be using a different value, check to see if there are any property expressions for the variable or property because the current designer does not provide any indication where property expressions exist.

A Simple Example

Property expressions are easiest to understand when you see them in action. You can put property expressions to work in a simple example. You'll create an expression on the Send Mail Task that will generate the Subject line for the email that will reflect the execution time of a given package.

1. Start up the IS designer and create a new package.

2. Drag and drop a Send Mail Task onto the designer.

3. Right-click on the task, and select Properties from the shortcut menu.

4. In the Properties grid, click the Expressions property. An ellipsis button becomes visible.

5. Click the ellipsis button to open the Property Expressions Editor shown in Figure 9.1.

   Figure 9.1. The Property Expressions Editor is used for adding property expressions

   

This is one way to access property expressions to a package.

Tip

On all stock tasks, you can also access the Property Expressions Editor from the task user interface on the Expressions tab.

Notice that there are two columns. The Property column allows you to select the property you want to associate with an expression. The Expression column allows you to enter the associated expression. There is also an ellipsis button next to the Expression field. Although you can type or paste the expression directly into the field, select a property and click on the ellipsis button to launch the Expression Builder dialog box shown in Figure 9.2.

Figure 9.2. The Expression Builder dialog box simplifies expression building

The Expression Builder dialog box has four main areas. The upper-left area is the Variables pane that lists all the variables in scope with the object where you are creating the property expression, in this case the Send Mail Task. The upper-right area is the Functions pane that shows all the available functions and operators for use in expressions. You can drag variables and functions from the Variables and Functions panes and drop them in the large window in the center of the Expression Builder, which is the Expression edit box. You can also directly modify the expression in the center Expression window.

When you finish your expression, you can click on the Evaluate Expression button to test your expression. If your expression is valid, the results of the expression show in the Evaluated Value box. If your expression has errors, an error dialog box opens with detailed errors.

Type in the following expression and click the Evaluate Expression button.

"The following package : " + @[System::PackageName] + ", started at : " +  (DT_WSTR, 20)@[System::StartTime] 

If you correctly typed in the expression, you should get a result similar to the following:

The following package : SimpleExpression, started at : 7/1/2006 5:20:26 PM 

If you want to see this in action, complete the rest of the properties on the Send Mail Task so that it successfully sends mail and executes the package. The email will have the updated Subject line with the time you ran the package. From this example, you can see how simple it is to add property expressions to your packages.

Sample: This package is also available in the samples in the Chapter 9 subdirectory.

Accessing Property Expressions for Other Object Types

The pattern for adding property expressions is the same for containers, connection managers, log providers, and Foreach Enumerators as it is for tasks. However, where you access the property expressions for log providers and Foreach Enumerators is a little different.

Property expressions for log providers are only available in the Package Explorer tab. To add or edit property expressions for log providers, you must first add a log provider to the package. See Chapter 11, "Logging and the Stock Log Providers," for more information on setting up log providers. Select the Package Explorer tab at the top of the designer and then open the Log Providers node. Right-click on the log provider for which you want to add an expression and select Properties. You can click the ellipsis button for the expressions property to access the Property Expressions Editor, as shown in Figure 9.3.

Figure 9.3. Property expressions for log providers are available in the properties grid for the log provider in the package explorer

If you need to access the property expressions on Foreach Enumerators, open the Foreach Loop Editor by double-clicking on it. Click on the Collection tab and then select the expressions property as with other object types. Figure 9.4 shows the Collection tab in the Foreach Loop Editor with the expressions property selected.

Figure 9.4. Property expressions for Foreach Enumerators are available in the properties grid on the Collection tab in the Foreach Loop Editor

Caution

In the left pane of the Foreach Loop Editor, there is also an Expressions tab. This tab allows you access to the Property Expressions Editor for the ForEach Loop , not the Foreach Enumerator. It's the same Property Expressions Editor you would get via the property grid for the ForEach Loop. It can be a bit confusing, but just remember that the property expressions for the Foreach Enumerator are only available on the Collection tab.