Codieren eines benutzerdefinierten Protokollanbieters

Gilt für: SQL Server SSIS Integration Runtime in Azure Data Factory

Nachdem Sie eine Klasse erstellt haben, die von der LogProviderBase-Basisklasse erbt, und das DtsLogProviderAttribute-Attribut auf die Klasse angewendet haben, müssen Sie die Implementierung der Eigenschaften und Methoden der Basisklasse überschreiben, um die benutzerdefinierte Funktionalität bereitzustellen.

Funktionstüchtige Beispiele benutzerdefinierter Protokollanbieter finden Sie unter Entwickeln einer Benutzeroberfläche für einen benutzerdefinierten Protokollanbieter.

Konfigurieren des Protokollanbieters

Initialisieren des Protokollanbieters

Sie überschreiben die InitializeLogProvider-Methode, um Verweise auf die Connections-Auflistung und die Ereignisschnittstelle zwischenzuspeichern. Sie können diese zwischengespeicherten Verweise später in anderen Methoden des Protokollanbieters verwenden.

Verwenden der ConfigString-Eigenschaft

Zur Entwurfszeit erhält ein Protokollanbieter Konfigurationsinformationen aus der Spalte Konfiguration. Diese Konfigurationsinformationen entsprechen der ConfigString-Eigenschaft des Protokollanbieters. Standardmäßig enthält diese Spalte ein Textfeld, aus dem Sie alle Zeichenfolgeninformationen abrufen können. Die meisten in Integration Services integrierten Protokollanbieter verwenden diese Eigenschaft, um den Namen des Verbindungs-Managers zu speichern, den der Anbieter zur Verbindung mit einer externen Datenquelle verwendet. Falls Ihr Protokollanbieter die ConfigString-Eigenschaft verwendet, wenden Sie die Validate-Methode an, um diese Eigenschaft zu überprüfen und sicherzustellen, dass sie richtig eingestellt ist.

Überprüfen des Protokollanbieters

Sie überschreiben die Validate-Methode, um sicherzustellen, dass der Anbieter ordnungsgemäß konfiguriert wurde und zum Ausführen bereit ist. In der Regel genügt eine minimale Überprüfung, um sich zu vergewissern, dass ConfigString richtig eingestellt ist. Die Ausführung kann erst fortgesetzt werden, wenn der Protokollanbieter Success von der Validate-Methode zurückgibt.

Im folgenden Beispiel wird eine Implementierung von Validate gezeigt, die sicherstellt, dass der Name eines Verbindungs-Managers angegeben ist, dass der Verbindungs-Manager im Paket enthalten ist und dass er einen Dateinamen in der ConfigString-Eigenschaft zurückgibt.

public override DTSExecResult Validate(IDTSInfoEvents infoEvents)  
{  
    if (this.ConfigString.Length == 0 || connections.Contains(ConfigString) == false)  
    {  
        infoEvents.FireError(0, "MyTextLogProvider", "The ConnectionManager " + ConfigString + " specified in the ConfigString property cannot be found in the collection.", "", 0);  
        return DTSExecResult.Failure;  
    }  
    else  
    {  
        string fileName = connections[ConfigString].AcquireConnection(null) as string;  
  
        if (fileName == null || fileName.Length == 0)  
        {  
            infoEvents.FireError(0, "MyTextLogProvider", "The ConnectionManager " + ConfigString + " specified in the ConfigString property cannot be found in the collection.", "", 0);  
            return DTSExecResult.Failure;  
        }  
    }  
    return DTSExecResult.Success;  
}  

Public Overrides Function Validate(ByVal infoEvents As IDTSInfoEvents) As DTSExecResult  
    If Me.ConfigString.Length = 0 Or connections.Contains(ConfigString) = False Then  
        infoEvents.FireError(0, "MyTextLogProvider", "The ConnectionManager " + ConfigString + " specified in the ConfigString property cannot be found in the collection.", "", 0)  
        Return DTSExecResult.Failure  
    Else   
        Dim fileName As String =  connections(ConfigString).AcquireConnectionCType(as string, Nothing)  
  
        If fileName = Nothing Or fileName.Length = 0 Then  
            infoEvents.FireError(0, "MyTextLogProvider", "The ConnectionManager " + ConfigString + " specified in the ConfigString property cannot be found in the collection.", "", 0)  
            Return DTSExecResult.Failure  
        End If  
    End If  
    Return DTSExecResult.Success  
End Function  

Beibehalten des Protokollanbieters

In der Regel müssen Sie keine benutzerdefinierte Persistenz für einen Verbindungs-Manager implementieren. Die benutzerdefinierte Persistenz ist nur erforderlich, wenn die Eigenschaften eines Objekts komplexe Datentypen verwenden. Weitere Informationen finden Sie unter Developing Custom Objects for Integration Services (Entwickeln von benutzerdefinierten Objekten für Integration Services).

Protokollieren mit dem Protokollanbieter

Es gibt drei Laufzeitmethoden, die von allen Protokollanbietern überschrieben werden müssen: OpenLog, Log und CloseLog.

Wichtig

Während der Überprüfung und Ausführung eines einzelnen Pakets werden die Methoden OpenLog und CloseLog mehrmals aufgerufen. Stellen Sie sicher, dass mit Ihrem benutzerdefinierten Code keine früheren Protokolleinträge beim nächsten Öffnen und Schließen des Protokolls überschrieben werden. Falls Sie die Protokollierung von Überprüfungsereignissen in Ihrem Testpaket festgelegt haben, sollte als erstes protokolliertes Ereignis OnPreValidate angezeigt werden. Falls als erstes Ereignis PackageStart angezeigt wird, wurden die anfänglichen Überprüfungsereignisse überschrieben.

Öffnen des Protokolls

Die meisten Protokollanbieter stellen eine Verbindung mit einer externen Datenquelle, wie z. B. einer Datei oder einer Datenbank her, um die Ereignisinformationen zu speichern, die während der Paketausführung gesammelt werden. Wie bei jedem anderen Objekt erfolgt die Verbindung mit der externen Datenquelle zur Laufzeit normalerweise über die Verwendung von Verbindungs-Manager-Objekten.

Die Methode OpenLog wird zu Beginn der Paketausführung aufgerufen. Überschreiben Sie diese Methode, um eine Verbindung mit der externen Datenquelle herzustellen.

Im folgenden Beispielcode wird ein Protokollanbieter gezeigt, der während OpenLog eine Textdatei zum Schreiben öffnet. Die Datei wird durch Aufrufen der Methode AcquireConnection des Verbindungs-Managers geöffnet, der in der ConfigString-Eigenschaft angegeben wurde.

public override void OpenLog()  
{  
    if(!this.connections.Contains(this.ConfigString))  
        throw new Exception("The ConnectionManager " + this.ConfigString + " does not exist in the Connections collection.");  
  
    this.connectionManager = connections[ConfigString];  
    string filePath = this.connectionManager.AcquireConnection(null) as string;  
  
    if(filePath == null || filePath.Length == 0)  
        throw new Exception("The ConnectionManager " + this.ConfigString + " is not a valid FILE ConnectionManager");  
  
    //  Create a StreamWriter to append to.  
    sw = new StreamWriter(filePath,true);  
  
    sw.WriteLine("Open log" + System.DateTime.Now.ToShortTimeString());  
}  

Public Overrides  Sub OpenLog()  
    If Not Me.connections.Contains(Me.ConfigString) Then  
        Throw New Exception("The ConnectionManager " + Me.ConfigString + " does not exist in the Connections collection.")  
    End If  
  
    Me.connectionManager = connections(ConfigString)  
    Dim filePath As String =  Me.connectionManager.AcquireConnectionCType(as string, Nothing)  
  
    If filePath = Nothing Or filePath.Length = 0 Then  
        Throw New Exception("The ConnectionManager " + Me.ConfigString + " is not a valid FILE ConnectionManager")  
    End If  
  
    '  Create a StreamWriter to append to.  
    sw = New StreamWriter(filePath,True)  
  
    sw.WriteLine("Open log" + System.DateTime.Now.ToShortTimeString())  
End Sub  

Schreiben von Protokolleinträgen

Die Methode Log wird immer dann aufgerufen, wenn ein Objekt im Paket ein Ereignis auslöst, indem es eine Methode vom Typ „Fire<Ereignis>“ für eine der Ereignisschnittstellen aufruft. Jedes Ereignis wird mit Informationen über seinen Kontext ausgelöst und enthält normalerweise eine erklärende Meldung. Aber nicht jeder Aufruf der Log-Methode enthält Informationen für jeden Methodenparameter. Beispielsweise liefern einige Standardereignisse, deren Namen selbsterklärend sind, keinen Meldungstext, und Datencode und Datenbytes sind für optionale Zusatzinformationen gedacht.

Im folgenden Codebeispiel wird die Log-Methode implementiert und die Ereignisse in den Datenstrom geschrieben, der im vorhergehenden Abschnitt geöffnet wurde.

public override void Log(string logEntryName, string computerName, string operatorName, string sourceName, string sourceID, string executionID, string messageText, DateTime startTime, DateTime endTime, int dataCode, byte[] dataBytes)  
{  
    sw.Write(logEntryName + ",");  
    sw.Write(computerName + ",");  
    sw.Write(operatorName + ",");  
    sw.Write(sourceName + ",");  
    sw.Write(sourceID + ",");  
    sw.Write(messageText + ",");  
    sw.Write(dataBytes + ",");  
    sw.WriteLine("");  
}  

Public Overrides  Sub Log(ByVal logEnTryName As String, ByVal computerName As String, ByVal operatorName As String, ByVal sourceName As String, ByVal sourceID As String, ByVal executionID As String, ByVal messageText As String, ByVal startTime As DateTime, ByVal endTime As DateTime, ByVal dataCode As Integer, ByVal dataBytes() As Byte)  
    sw.Write(logEnTryName + ",")  
    sw.Write(computerName + ",")  
    sw.Write(operatorName + ",")  
    sw.Write(sourceName + ",")  
    sw.Write(sourceID + ",")  
    sw.Write(messageText + ",")  
    sw.Write(dataBytes + ",")  
    sw.WriteLine("")  
End Sub  

Schließen des Protokolls

Die CloseLog-Methode wird am Ende der Paketausführung aufgerufen, nachdem die Ausführung aller Objekte im Paket abgeschlossen ist oder wenn das Paket aufgrund eines Fehlers gestoppt wird.

Im folgenden Codebeispiel wird die Implementierung der CloseLog-Methode veranschaulicht, die den Dateidatenstrom schließt, der von der OpenLog-Methode geöffnet wurde.

public override void CloseLog()  
{  
    if (sw != null)  
    {  
        sw.WriteLine("Close log" + System.DateTime.Now.ToShortTimeString());  
        sw.Close();  
    }  
}  

Public Overrides  Sub CloseLog()  
    If Not sw Is Nothing Then  
        sw.WriteLine("Close log" + System.DateTime.Now.ToShortTimeString())  
        sw.Close()  
    End If  
End Sub  

Weitere Informationen

Erstellen eines benutzerdefinierten Protokollanbieters
Entwickeln einer Benutzeroberfläche für einen benutzerdefinierten Protokollanbieter