What is the purpose of the fireAgain parameter in the Dts.Events.FireInformation method?

Question

When firing Integration Services events from a script, I stumble a little on the FireInformation method from Microsoft.SqlServer.Dts.Tasks.ScriptTask.EventsObjectWrapper Dts property on Microsoft.SqlServer.Dts.Tasks.ScriptTask.VSTARTScriptObjectModelBase. The last parameter, fireAgain, is passed by reference. The documentation explains, "True to continue firing; otherwise, false." Why pass the parameter by reference? Are there conditions where the method set the value to true and require the caller to repeat the call? If the caller sets the value to false, what are the implications?

Spode

My quick guess, because I don't know for certain, is that this is a feature for those who implement their own custom logging provider. – Brassica

@billinkc, can you elaborate on why you think that a custom logging provider is germane? If it is, why is the parameter only used on the FireInformation method and not other events? – Spode

Answer 1

The reason the FirstInformation provides a mechanism for suppressing further events is the cost. Raising events can be costly and given that by definition, these messages are informational in nature, it makes sense to allow log providers, or custom tasks to stop raising the event.

From IDTSComponentEvents.FireInformation Method

Because firing of an event may be expensive, the run-time engine provides a mechanism for suppressing events that you are not interested in. Every event firing method has a FireAgain parameter. If the value of this variable is false, after the method returns, the caller will not fire this event again for the duration of the current execution.

Brassica

Well, this is tough. I think your answer points in the direction, but the documentation leaves me confused and wanting. Not every event method has a fireAgain parameter. FireError returns a boolean instead of providing a parameter. FireWarning provided neither. The line, "If the value of the variable is false, after the method returns, the caller will not fire this event again...", is difficult to interpret. I am let wondering if it is meant to be imperative. I've found no examples specifically handling this condition. – Spode

Answer 2

Like the comments say, I think the documentation on the event methods is inconsistent at best and definitely confusing. I think billinkc points us in an interesting direction with a custom logging provider. Also of interest, is documentation on handling events programmatically. Though the samples don't specifically indicate how callers should handle the fireAgain parameters or return values. I think the we are to respect the value for all subsequent attempts to fire a event of the types: custom, error, information, and progress. Though stated in the documentation, "Every event firing method has a FireAgain parameter." It's simply not the case. FireWarning provides no return or parameter for FireAgain.

In your custom ScriptTask you may want to implement wrapper methods to handle the FireAgain parameter or return value.

private bool shouldFireCustomEvent = true;
private void TaskLevelFireCustomEvent(string eventName, string eventText, ref object[] arguments, string subComponent)
{
    if (!shouldFireCustomEvent) { return; }
    Dts.Events.FireCustomEvent(eventName, eventText, ref arguments, subComponent, ref shouldFireCustomEvent);
}

private bool shouldFireError = true;
private void TaskLevelFireError(int errorCode, string subComponent, string description, string helpFile, int helpContext)
{
    if (!shouldFireError) { return; }
    this.shouldFireError = Dts.Events.FireError(errorCode, subComponent, description, helpFile, helpContext);
}

private bool shouldFireInformation = true;
private void TaskLevelFireInformation(int informationCode, string subComponent, string description, string helpFile, int helpContext)
{
    if (!shouldFireInformation) { return; }
    Dts.Events.FireInformation(informationCode, subComponent, description, helpFile, helpContext, ref shouldFireInformation);
}

private bool shouldFireProgress = true;
private void TaskLevelFireProgress(string progressDescription, int percentComplete, int progressCountLow, int progressCountHigh, string subComponent)
{
    if (!shouldFireProgress) { return; }
    Dts.Events.FireProgress(progressDescription, percentComplete, progressCountLow, progressCountHigh, subComponent, ref shouldFireProgress);
}

private void TaskLevelFireWarning(int warningCode, string subComponent, string description, string helpFile, int helpContext)
{
    Dts.Events.FireWarning(warningCode, subComponent, description, helpFile, helpContext);
}

In my few tests, I have not seen the included logging providers take advantage of the fireAgain parameter and would be interested to see a case where the value returned is actually false.

Spode