Logging and Defining Log Entries in a Data Flow Component

Custom data flow components can post messages to an existing log entry by using the PostLogMessage method of the IDTSComponentMetaData100 interface. They can also present information to the user by using the FireInformation method or similar methods of the IDTSComponentMetaData100 interface. However, this approach incurs the overhead of raising and handling additional events, and forces the user to sift through verbose informational messages for the messages that may be of interest to them. You can use a custom log entry as described below to provide distinctly labeled custom log information to users of your component.

Registering and Using a Custom Log Entry

Registering a Custom Log Entry

To register a custom log entry for use by your component, override the RegisterLogEntries method of the PipelineComponent base class. The following example registers a custom log entry and provides a name and description.

using Microsoft.SqlServer.Dts.Runtime;
...
private const string MyLogEntryName = "My Custom Component Log Entry";
private const string MyLogEntryDescription = "Log entry from My Custom Component ";
...
    public override void RegisterLogEntries()
    {
      this.LogEntryInfos.Add(MyLogEntryName,
        MyLogEntryDescription,
        Microsoft.SqlServer.Dts.Runtime.Wrapper.DTSLogEntryFrequency.DTSLEF_CONSISTENT);
    }
Imports Microsoft.SqlServer.Dts.Runtime
...
Private Const MyLogEntryName As String = "My Custom Component Log Entry" 
Private Const MyLogEntryDescription As String = "Log entry from My Custom Component "
...
Public  Overrides Sub RegisterLogEntries() 
  Me.LogEntryInfos.Add(MyLogEntryName, _
    MyLogEntryDescription, _
    Microsoft.SqlServer.Dts.Runtime.Wrapper.DTSLogEntryFrequency.DTSLEF_CONSISTENT) 
End Sub

The DTSLogEntryFrequency enumeration provides a hint to the runtime about how frequently the event will be logged:

  • DTSLEF_OCCASIONAL: Event is logged only sometimes, not during every execution.

  • DTSLEF_CONSISTENT: Event is logged a constant number of times during every execution.

  • DTSLEF_PROPORTIONAL: Event is logged a number of times proportional to the amount of work completed.

The example above uses DTSLEF_CONSISTENT because the component expects to log an entry once per execution.

After registering the custom log entry and adding an instance of your custom component to the data flow designer surface, the Logging dialog box in the designer displays a new log entry with the name "My Custom Component Log Entry" in the list of available log entries.

Logging to a Custom Log Entry

After registering the custom log entry, the component can now log custom messages. The example below writes a custom log entry during the PreExecute method that contains the text of a SQL statement used by the component.

    public override void PreExecute()
    {
      DateTime now = DateTime.Now;
      byte[] additionalData = null;
      this.ComponentMetaData.PostLogMessage(MyLogEntryName,
        this.ComponentMetaData.Name,
        "Command Sent was: " + myCommand.CommandText,
        now, now, 0, ref additionalData);
    }
Public  Overrides Sub PreExecute() 
  Dim now As DateTime = DateTime.Now 
  Dim additionalData As Byte() = Nothing 
  Me.ComponentMetaData.PostLogMessage(MyLogEntryName, _
    Me.ComponentMetaData.Name, _
    "Command Sent was: " + myCommand.CommandText, _
    now, now, 0, additionalData) 
End Sub

Now when the user executes the package, after selecting the "My Custom Component Log Entry" in the Logging dialog box, the log will contain an entry clearly labeled as "User::My Custom Component Log Entry." This new log entry contains the text of the SQL statement, the timestamp, and any additional data logged by the developer.

Integration Services icon (small) Stay Up to Date with Integration Services

For the latest downloads, articles, samples, and videos from Microsoft, as well as selected solutions from the community, visit the Integration Services page on MSDN or TechNet:

For automatic notification of these updates, subscribe to the RSS feeds available on the page.