Condividi tramite


Utilizzo degli output degli errori in un componente del flusso di dati

Ai componenti è possibile aggiungere oggetti IDTSOutput100 speciali, denominati output degli errori, in modo che il componente possa reindirizzare le righe che non è in grado di elaborare durante l'esecuzione. I problemi che si possono verificare con un componente sono in genere classificati come errori o troncamenti e sono specifici per ogni componente. I componenti che forniscono output degli errori offrono agli utenti la flessibilità di gestire le condizioni di errore filtrando le righe di errore dal set di risultati, interrompendo il componente quando si verifica un problema oppure ignorando gli errori e continuando.

Prima di implementare e supportare gli output degli errori in un componente, è necessario impostare la proprietà UsesDispositions del componente su true. Quindi, è necessario aggiungere al componente un output la cui proprietà IsErrorOut è impostata su true. Infine, il componente deve contenere codice che reindirizza le righe all'output degli errori quando si verificano errori o troncamenti. In questo argomento vengono descritti questi tre passaggi e vengono illustrate le differenze tra output degli errori sincroni e asincroni.

Creazione di un output degli errori

Per creare un output degli errori, chiamare il metodo New di OutputCollection, quindi impostare la proprietà IsErrorOut del nuovo output su true. Se l'output è asincrono, non è necessario eseguire altre operazioni. Se l'output è sincrono ed è disponibile un altro output che è sincrono con lo stesso input, è anche necessario impostare le proprietà ExclusionGroup e SynchronousInputID. Entrambe le proprietà devono avere gli stessi valori dell'altro output sincrono con lo stesso input. Se queste proprietà non sono impostate su un valore diverso da zero, le righe fornite dall'input vengono inviate a entrambi gli output sincroni con l'input.

Quando si verifica un errore o un troncamento durante l'esecuzione di un componente, l'operazione prosegue in base alle impostazioni delle proprietà ErrorRowDisposition e TruncationRowDisposition dell'input o dell'output oppure della colonna di input o di output in cui è stato riscontrato l'errore. Il valore di queste proprietà dovrebbe essere impostato per impostazione predefinita su RD_NotUsed. Quando l'output degli errori del componente è connesso a un componente a valle, questa proprietà viene impostata dall'utente del componente e gli consente di controllare la modalità con cui il componente stesso gestisce l'errore o il troncamento.

Popolamento di colonne di errore

Quando viene creato un output degli errori, l'attività Flusso di dati aggiunge automaticamente due colonne alla raccolta di colonne di output. Tali colonne vengono utilizzate dai componenti per specificare l'ID della colonna che ha generato l'errore o il troncamento e per fornire il codice di errore specifico del componente. Le colonne vengono generate automaticamente, ma i valori contenuti al loro interno devono essere impostati dal componente.

Il metodo utilizzato per impostare i valori di queste colonne varia a seconda che l'output degli errori sia sincrono o asincrono. I componenti con output sincroni chiamano il metodo DirectErrorRow, descritto in maggior dettaglio nella sezione successiva, e forniscono il codice di errore e i valori delle colonne di errore come parametri. I componenti con output asincroni possono impostare i valori di queste colonne in due modi: chiamando il metodo SetErrorInfo del buffer di output e specificando i valori oppure individuando le colonne di errore nel buffer tramite FindColumnByLineageID e impostando direttamente i valori per le colonne. Tuttavia, poiché è possibile che siano state apportate modifiche ai nomi delle colonne o alla relativa posizione nella raccolta di colonne di output, il secondo metodo può non essere affidabile. Il metodo SetErrorInfo imposta automaticamente i valori in queste colonne di errore senza la necessità di individuarle manualmente.

Se è necessario ottenere la descrizione dell'errore che corrisponde a un codice di errore specifico, è possibile utilizzare il metodo GetErrorDescription dell'interfaccia IDTSComponentMetaData100, disponibile tramite la proprietà ComponentMetaData del componente.

Negli esempi di codice seguenti è illustrato un componente con un input e due output, incluso un output degli errori. Nel primo esempio è illustrata la creazione di un output degli errori sincrono con l'input. Nel secondo esempio è illustrata la creazione di un output degli errori asincrono.

public override void ProvideComponentProperties()
{
    // Specify that the component has an error output.
    ComponentMetaData.UsesDispositions = true;
    // Create the input.
    IDTSInput100 input = ComponentMetaData.InputCollection.New();
    input.Name = "Input";
    input.ErrorRowDisposition = DTSRowDisposition.RD_NotUsed;
    input.ErrorOrTruncationOperation = "A string describing the possible error or truncation that may occur during execution.";

    // Create the default output.
    IDTSOutput100 output = ComponentMetaData.OutputCollection.New();
    output.Name = "Output";
    output.SynchronousInputID = input.ID;
    output.ExclusionGroup = 1;

    // Create the error output.
    IDTSOutput100 errorOutput = ComponentMetaData.OutputCollection.New();
    errorOutput.IsErrorOut = true;
    errorOutput.Name = "ErrorOutput";
    errorOutput.SynchronousInputID = input.ID;
    errorOutput.ExclusionGroup = 1;

}
Public  Overrides Sub ProvideComponentProperties() 

 ' Specify that the component has an error output.
 ComponentMetaData.UsesDispositions = True 

 Dim input As IDTSInput100 = ComponentMetaData.InputCollection.New 

 ' Create the input.
 input.Name = "Input" 
 input.ErrorRowDisposition = DTSRowDisposition.RD_NotUsed 
 input.ErrorOrTruncationOperation = "A string describing the possible error or truncation that may occur during execution." 

 ' Create the default output.
 Dim output As IDTSOutput100 = ComponentMetaData.OutputCollection.New 
 output.Name = "Output" 
 output.SynchronousInputID = input.ID 
 output.ExclusionGroup = 1 

 ' Create the error output.
 Dim errorOutput As IDTSOutput100 = ComponentMetaData.OutputCollection.New 
 errorOutput.IsErrorOut = True 
 errorOutput.Name = "ErrorOutput" 
 errorOutput.SynchronousInputID = input.ID 
 errorOutput.ExclusionGroup = 1 

End Sub

Nell'esempio di codice seguente viene creato un output degli errori asincrono.

public override void ProvideComponentProperties()
{
    // Specify that the component has an error output.
    ComponentMetaData.UsesDispositions = true;

    // Create the input.
    IDTSInput100 input = ComponentMetaData.InputCollection.New();
    input.Name = "Input";
    input.ErrorRowDisposition = DTSRowDisposition.RD_NotUsed;
    input.ErrorOrTruncationOperation = "A string describing the possible error or truncation that may occur during execution.";

    // Create the default output.
    IDTSOutput100 output = ComponentMetaData.OutputCollection.New();
    output.Name = "Output";

    // Create the error output.
    IDTSOutput100 errorOutput = ComponentMetaData.OutputCollection.New();
    errorOutput.Name = "ErrorOutput";
    errorOutput.IsErrorOut = true;
}
Public  Overrides Sub ProvideComponentProperties() 

 ' Specify that the component has an error output.
 ComponentMetaData.UsesDispositions = True 

 ' Create the input.
 Dim input As IDTSInput100 = ComponentMetaData.InputCollection.New 

 ' Create the default output.
 input.Name = "Input" 
 input.ErrorRowDisposition = DTSRowDisposition.RD_NotUsed 
 input.ErrorOrTruncationOperation = "A string describing the possible error or truncation that may occur during execution." 

 ' Create the error output.
 Dim output As IDTSOutput100 = ComponentMetaData.OutputCollection.New 
 output.Name = "Output" 
 Dim errorOutput As IDTSOutput100 = ComponentMetaData.OutputCollection.New 
 errorOutput.Name = "ErrorOutput" 
 errorOutput.IsErrorOut = True 

End Sub

Reindirizzamento di una riga a un output degli errori.

Dopo aver aggiunto un output degli errori a un componente, è necessario fornire il codice che gestisce le condizioni di errore o troncamento specifiche del componente e reindirizza le righe di errore o troncamento all'output degli errori. È possibile eseguire questa operazione in due modi, a seconda che l'output degli errori sia sincrono o asincrono.

Reindirizzamento di una riga con output sincroni

Le righe vengono inviate agli output sincroni chiamando il metodo DirectErrorRow della classe PipelineBuffer. La chiamata al metodo include come parametri l'ID dell'output degli errori, il codice di errore definito dal componente e l'indice della colonna che il componente non è stato in grado di elaborare.

Nell'esempio di codice seguente è illustrato come indirizzare una riga in un buffer a un output degli errori sincrono utilizzando il metodo DirectErrorRow.

public override void ProcessInput(int inputID, PipelineBuffer buffer)
{
        IDTSInput100 input = ComponentMetaData.InputCollection.GetObjectByID(inputID);

        // This code sample assumes the component has two outputs, one the default,
        // the other the error output. If the errorOutputIndex returned from GetErrorOutputInfo
        // is 0, then the default output is the second output in the collection.
        int defaultOutputID = -1;
        int errorOutputID = -1;
        int errorOutputIndex = -1;

        GetErrorOutputInfo(ref errorOutputID,ref errorOutputIndex);

        if (errorOutputIndex == 0)
            defaultOutputID = ComponentMetaData.OutputCollection[1].ID;
        else
            defaultOutputID = ComponentMetaData.OutputCollection[0].ID;

        while (buffer.NextRow())
        {
            try
            {
                // TODO: Implement code to process the columns in the buffer row.

                // Ideally, your code should detect potential exceptions before they occur, rather
                // than having a generic try/catch block such as this. 
                // However, because the error or truncation implementation is specific to each component,
                // this sample focuses on actually directing the row, and not a single error or truncation.

                // Unless an exception occurs, direct the row to the default 
                buffer.DirectRow(defaultOutputID);
            }
            catch
            {
                // Yes, has the user specified to redirect the row?
                if (input.ErrorRowDisposition == DTSRowDisposition.RD_RedirectRow)
                {
                    // Yes, direct the row to the error output.
                    // TODO: Add code to include the errorColumnIndex.
                    buffer.DirectErrorRow(errorOutputID, 0, errorColumnIndex);
                }
                else if (input.ErrorRowDisposition == DTSRowDisposition.RD_FailComponent || input.ErrorRowDisposition == DTSRowDisposition.RD_NotUsed)
                {
                    // No, the user specified to fail the component, or the error row disposition was not set.
                    throw new Exception("An error occurred, and the DTSRowDisposition is either not set, or is set to fail component.");
                }
                else
                {
                    // No, the user specified to ignore the failure so 
                    // direct the row to the default output.
                    buffer.DirectRow(defaultOutputID);
                }

            }
        }
}
Public  Overrides Sub ProcessInput(ByVal inputID As Integer, ByVal buffer As PipelineBuffer) 
   Dim input As IDTSInput100 = ComponentMetaData.InputCollection.GetObjectByID(inputID) 

   ' This code sample assumes the component has two outputs, one the default,
   ' the other the error output. If the errorOutputIndex returned from GetErrorOutputInfo
   ' is 0, then the default output is the second output in the collection.
   Dim defaultOutputID As Integer = -1 
   Dim errorOutputID As Integer = -1 
   Dim errorOutputIndex As Integer = -1 

   GetErrorOutputInfo(errorOutputID, errorOutputIndex) 

   If errorOutputIndex = 0 Then 
     defaultOutputID = ComponentMetaData.OutputCollection(1).ID 
   Else 
     defaultOutputID = ComponentMetaData.OutputCollection(0).ID 
   End If 

   While buffer.NextRow 
     Try 
       ' TODO: Implement code to process the columns in the buffer row.

       ' Ideally, your code should detect potential exceptions before they occur, rather
       ' than having a generic try/catch block such as this. 
       ' However, because the error or truncation implementation is specific to each component,
       ' this sample focuses on actually directing the row, and not a single error or truncation.

       ' Unless an exception occurs, direct the row to the default 
       buffer.DirectRow(defaultOutputID) 
     Catch 
       ' Yes, has the user specified to redirect the row?
       If input.ErrorRowDisposition = DTSRowDisposition.RD_RedirectRow Then 
         ' Yes, direct the row to the error output.
         ' TODO: Add code to include the errorColumnIndex.
         buffer.DirectErrorRow(errorOutputID, 0, errorColumnIndex) 
       Else 
         If input.ErrorRowDisposition = DTSRowDisposition.RD_FailComponent OrElse input.ErrorRowDisposition = DTSRowDisposition.RD_NotUsed Then 
           ' No, the user specified to fail the component, or the error row disposition was not set.
           Throw New Exception("An error occurred, and the DTSRowDisposition is either not set, or is set to fail component.") 
         Else 
           ' No, the user specified to ignore the failure so 
           ' direct the row to the default output.
           buffer.DirectRow(defaultOutputID) 
         End If 
       End If 
     End Try 
   End While 
End Sub

Reindirizzamento di una riga con output asincroni

Anziché indirizzare le righe a un output, come per gli output degli errori sincroni, i componenti con output asincroni inviano una riga a un output degli errori aggiungendo in modo esplicito una riga all'oggetto PipelineBuffer dell'output. L'implementazione di un componente che utilizza output degli errori asincroni richiede l'aggiunta di colonne all'output degli errori che vengono forniti ai componenti a valle e la memorizzazione nella cache del buffer di output per l'output degli errori fornito al componente durante l'esecuzione del metodo PrimeOutput. I dettagli dell'implementazione di un componente con output asincroni vengono descritti nell'argomento Sviluppo di un componente di trasformazione personalizzato con output asincroni. Se non vengono aggiunte colonne in modo esplicito all'output degli errori, la riga del buffer aggiunta al buffer di output contiene solo le due colonne di errore.

Per inviare una riga a un output degli errori asincrono, è necessario aggiungere una riga al buffer dell'output degli errori. Poiché è possibile che sia già stata aggiunta una riga al buffer dell'output non degli errori, è necessario rimuovere tale riga tramite il metodo RemoveRow. Successivamente, impostare i valori delle colonne del buffer di output e infine chiamare il metodo SetErrorInfo per fornire il codice di errore specifico del componente e il valore della colonna di errore.

Nell'esempio seguente è illustrato come utilizzare un output degli errori per un componente con output asincroni. Quando si verifica l'errore simulato, il componente aggiunge una riga al buffer dell'output degli errori, copia nel buffer dell'output degli errori i valori aggiunti in precedenza al buffer dell'output non degli errori, rimuove la riga aggiunta al buffer dell'output non degli errori e infine imposta il codice di errore e i valori delle colonne di errore chiamando il metodo SetErrorInfo.

int []columnIndex;
int errorOutputID = -1;
int errorOutputIndex = -1;

public override void PreExecute()
{
    IDTSOutput100 defaultOutput = null;

    this.GetErrorOutputInfo(ref errorOutputID, ref errorOutputIndex);
    foreach (IDTSOutput100 output in ComponentMetaData.OutputCollection)
    {
        if (output.ID != errorOutputID)
            defaultOutput = output;
    }

    columnIndex = new int[defaultOutput.OutputColumnCollection.Count];

    for(int col =0 ; col < defaultOutput.OutputColumnCollection.Count; col++)
    {
        IDTSOutputColumn100 column = defaultOutput.OutputColumnCollection[col];
        columnIndex[col] = BufferManager.FindColumnByLineageID(defaultOutput.Buffer, column.LineageID);
    }
}

public override void PrimeOutput(int outputs, int[] outputIDs, PipelineBuffer[] buffers)
{
    for( int x=0; x < outputs; x++ )
    {
        if (outputIDs[x] == errorOutputID)
            this.errorBuffer = buffers[x];
        else
            this.defaultBuffer = buffers[x];
    }

    int rows = 100;

    Random random = new Random(System.DateTime.Now.Millisecond);

    for (int row = 0; row < rows; row++)
    {
        try
        {
            defaultBuffer.AddRow();

            for (int x = 0; x < columnIndex.Length; x++)
                defaultBuffer[columnIndex[x]] = random.Next();

            // Simulate an error.
            if ((row % 2) == 0)
                throw new Exception("A simulated error.");
        }
        catch
        {
            // Add a row to the error buffer.
            errorBuffer.AddRow();

            // Get the values from the default buffer
            // and copy them to the error buffer.
            for (int x = 0; x < columnIndex.Length; x++)
                errorBuffer[columnIndex[x]] = defaultBuffer[columnIndex[x]];

            // Set the error information.
            errorBuffer.SetErrorInfo(errorOutputID, 1, 0);

            // Remove the row that was added to the default buffer.
            defaultBuffer.RemoveRow();
        }
    }

    if (defaultBuffer != null)
        defaultBuffer.SetEndOfRowset();

    if (errorBuffer != null)
        errorBuffer.SetEndOfRowset();
}
Private columnIndex As Integer() 
Private errorOutputID As Integer = -1 
Private errorOutputIndex As Integer = -1 

Public  Overrides Sub PreExecute() 
 Dim defaultOutput As IDTSOutput100 = Nothing 
 Me.GetErrorOutputInfo(errorOutputID, errorOutputIndex) 
 For Each output As IDTSOutput100 In ComponentMetaData.OutputCollection 
   If Not (output.ID = errorOutputID) Then 
     defaultOutput = output 
   End If 
 Next 
 columnIndex = New Integer(defaultOutput.OutputColumnCollection.Count) {} 
 Dim col As Integer = 0 
 While col < defaultOutput.OutputColumnCollection.Count 
   Dim column As IDTSOutputColumn100 = defaultOutput.OutputColumnCollection(col) 
   columnIndex(col) = BufferManager.FindColumnByLineageID(defaultOutput.Buffer, column.LineageID) 
   System.Math.Min(System.Threading.Interlocked.Increment(col),col-1) 
 End While 
End Sub 

Public  Overrides Sub PrimeOutput(ByVal outputs As Integer, ByVal outputIDs As Integer(), ByVal buffers As PipelineBuffer()) 
 Dim x As Integer = 0 
 While x < outputs 
   If outputIDs(x) = errorOutputID Then 
     Me.errorBuffer = buffers(x) 
   Else 
     Me.defaultBuffer = buffers(x) 
   End If 
   System.Math.Min(System.Threading.Interlocked.Increment(x),x-1) 
 End While 
 Dim rows As Integer = 100 
 Dim random As Random = New Random(System.DateTime.Now.Millisecond) 
 Dim row As Integer = 0 
 While row < rows 
   Try 
     defaultBuffer.AddRow 
     Dim x As Integer = 0 
     While x < columnIndex.Length 
       defaultBuffer(columnIndex(x)) = random.Next 
       System.Math.Min(System.Threading.Interlocked.Increment(x),x-1) 
     End While 
     ' Simulate an error.
     If (row Mod 2) = 0 Then 
       Throw New Exception("A simulated error.") 
     End If 
   Catch 
     ' Add a row to the error buffer.
     errorBuffer.AddRow 
     ' Get the values from the default buffer
     ' and copy them to the error buffer.
     Dim x As Integer = 0 
     While x < columnIndex.Length 
       errorBuffer(columnIndex(x)) = defaultBuffer(columnIndex(x)) 
       System.Math.Min(System.Threading.Interlocked.Increment(x),x-1) 
     End While 
     ' Set the error information.
     errorBuffer.SetErrorInfo(errorOutputID, 1, 0) 
     ' Remove the row that was added to the default buffer.
     defaultBuffer.RemoveRow 
   End Try 
   System.Math.Min(System.Threading.Interlocked.Increment(row),row-1) 
 End While 
 If Not (defaultBuffer Is Nothing) Then 
   defaultBuffer.SetEndOfRowset 
 End If 
 If Not (errorBuffer Is Nothing) Then 
   errorBuffer.SetEndOfRowset 
 End If 
End Sub
Icona di Integration Services (piccola) Rimanere aggiornati con Integration Services

Per informazioni sui download, gli articoli, gli esempi e i video Microsoft più recenti, nonché sulle soluzioni selezionate dalla community, visitare la pagina Integration Services su MSDN o Technet:

Per ricevere notifica automatica su questi aggiornamenti, sottoscrivere i feed RSS disponibili nella pagina.