When you are designing an Integration Services package, you can use validation to verify settings on each task, so that you can catch incorrect or inappropriate settings as soon as they are set, instead of finding all errors at run-time only. The purpose of validation is to determine whether the task contains invalid settings or connections that will prevent it from running successfully. This makes sure that the package contains tasks that have a good chance of running on their first run.
You can implement validation by using the Validate method in custom code. The run-time engine validates a task by calling the Validate method on the task. It is the responsibility of the task developer to define the criteria that give you a successful or failed task validation, and to notify the run-time engine of the result of this evaluation.
Task Abstract Base Class
The Task abstract base class provides the Validate method that each task overrides to define its validation criteria. The SSIS Designer automatically calls the Validate method multiple times during package design, and provides visual cues to the user when warnings or errors occur to help identify problems with the configuration of the task. Tasks provide validation results by returning a value from the DTSExecResult enumeration, and by raising warning and error events. These events contain information that is displayed to the user in SSIS Designer.
Some examples for validation follow:
-
A connection manager validates the specific file name.
-
A connection manager validates that the type of input is the expected type, such as an XML file.
-
A task that expects database input verifies that it cannot receive data from a non-database connection.
-
A task guarantees that none of its properties contradicts other properties set on the same task.
-
A task guarantees that all required resources used by the task at execution time are available.
Performance is something to consider in determining what is validated and what is not. For example, the input to a task might be a connection over a network that has low bandwidth or heavy traffic. The validation may take several seconds to process if you decide to validate that the resource is available. Another validation may cause a round-trip to a server that is in high demand, and the validation routine might be slow. Although there are many properties and settings that can be validated, not everything should be validated.
-
The code in the Validate method is also called by the TaskHost before the task is run, and the TaskHost cancels execution if validation fails.
User Interface Considerations during Validation
The Task includes an IDTSComponentEvents interface as a parameter to the Validate method. The IDTSComponentEvents interface contains the methods that are called by the task in order to raise events to the run-time engine. The FireWarning and FireError methods are called when a warning or error condition occurs during validation. Both warning methods require the same parameters, which include an error code, source component, description, Help file, and Help context information. The SSIS Designer uses this information to display visual cues on the design surface. The visual cues that are provided by the designer include an exclamation icon that appears next to the task on the designer surface. This visual cue signals to the user that the task requires additional configuration before execution can continue.
The exclamation icon also displays a ToolTip that contains an error message. The error message is provided by the task in the description parameter of the event. Error messages are also displayed in the Task List pane of Business Intelligence Development Studio, providing the user with a central location for viewing all validation errors.
Validation Example
The following code example shows a task with a UserName property. This property has been specified as required for validation to succeed. If the property is not set, the task posts an error, and returns Failure from the DTSExecResult enumeration. The Validate method is wrapped in a try/catch block, and fails validation if an exception occurs.
We do not yet have a code sample for this language.