Utilizzo degli output degli errori in un componente del flusso di datiUsing Error Outputs in a Data Flow Component

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.Special IDTSOutput100 objects called error outputs can be added to components to let the component redirect rows that it cannot process during execution. I problemi che si possono verificare con un componente sono in genere classificati come errori o troncamenti e sono specifici per ogni componente.The problems a component may encounter are generally categorized as errors or truncations, and are specific to each component. 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.Components that provide error outputs give users of the component the flexibility to handle error conditions by filtering error rows out of the result set, by failing the component when a problem occurs, or by ignoring errors and continuing.

Per implementare e supportare gli output degli errori in un componente, è innanzitutto necessario impostare il UsesDispositions proprietà del componente da true.To implement and support error outputs in a component, you must first set the UsesDispositions property of the component to true. Quindi è necessario aggiungere un output al componente che ha il IsErrorOut proprietà impostata su true.Then you must add an output to the component that has its IsErrorOut property set to true. Infine, il componente deve contenere codice che reindirizza le righe all'output degli errori quando si verificano errori o troncamenti.Finally, the component must contain code that redirects rows to the error output when errors or truncations occur. In questo argomento vengono descritti questi tre passaggi e vengono illustrate le differenze tra output degli errori sincroni e asincroni.This topic covers these three steps and explains the differences between synchronous and asynchronous error outputs.

Creazione di un output degli erroriCreating an Error Output

Per creare un output degli errori, chiamare il New metodo il OutputCollectione quindi l'impostazione di IsErrorOut proprietà del nuovo output di true.You create an error output by calling the New method of the OutputCollection, and then setting the IsErrorOut property of the new output to true. Se l'output è asincrono, non è necessario eseguire altre operazioni.If the output is asynchronous, nothing else must be done to the output. Se l'output è sincrono ed è disponibile un altro output che è sincrono con lo stesso input, è anche necessario impostare le proprietà ExclusionGroup e SynchronousInputID.If the output is synchronous, and there is another output that is synchronous to the same input, you must also set the ExclusionGroup and SynchronousInputID properties. Entrambe le proprietà devono avere gli stessi valori dell'altro output sincrono con lo stesso input.Both properties should have the same values as the other output that is synchronous to the same 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.If these properties are not set to a non-zero value, the rows provided by the input are sent to both outputs that are synchronous to the 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.When a component encounters an error or truncation during execution, it proceeds based on the settings of the ErrorRowDisposition and TruncationRowDisposition properties of the input or output, or input or output column, where the error occurred. Il valore di queste proprietà dovrebbe essere impostato per impostazione predefinita su RD_NotUsed.The value of these properties should be set by default to 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.When the error output of the component is connected to a downstream component, this property is set by the user of the component and lets the user control how the component handles the error or truncation.

Popolamento di colonne di errorePopulating Error Columns

Quando viene creato un output degli errori, l'attività Flusso di dati aggiunge automaticamente due colonne alla raccolta di colonne di output.When an error output is created, the data flow task automatically adds two columns to the output column collection. 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.These columns are used by components to specify the ID of the column that caused the error or truncation, and to provide the component-specific error code. Le colonne vengono generate automaticamente, ma i valori contenuti al loro interno devono essere impostati dal componente.These columns are generated automatically, but the values contained in the columns must be set by the component.

Il metodo utilizzato per impostare i valori di queste colonne varia a seconda che l'output degli errori sia sincrono o asincrono.The method used to set the values of these columns depends on whether the error output is synchronous or asynchronous. 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.Components with synchronous outputs call the DirectErrorRow method, discussed in more detail in the next section, and provide the error code and error column values as parameters. I componenti con output asincroni possono impostare i valori di queste colonne in due modi:Components with asynchronous outputs have two choices for setting the values of these columns. 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.They can either call the SetErrorInfo method of the output buffer and supply the values, or locate the error columns in the buffer by using FindColumnByLineageID and set the values for the columns directly. 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.However, because the names of the columns may have been changed, or their location in the output column collection may have been modified, the latter method may not be reliable. Il metodo SetErrorInfo imposta automaticamente i valori in queste colonne di errore senza la necessità di individuarle manualmente.The SetErrorInfo method automatically sets the values in these error columns without having to locate them manually.

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.If you need to obtain the error description that corresponds to a specific error code, you can use the GetErrorDescription method of the IDTSComponentMetaData100 interface, available through the component's ComponentMetaData property.

Negli esempi di codice seguenti è illustrato un componente con un input e due output, incluso un output degli errori.The following code examples show a component that has an input and two outputs, including an error output. Nel primo esempio è illustrata la creazione di un output degli errori sincrono con l'input.The first example shows how to create an error output that is synchronous to the input. Nel secondo esempio è illustrata la creazione di un output degli errori asincrono.The second example shows how to create an error output that is asynchronous.

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.The following code example creates an error output that is asynchronous.

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.Redirecting a Row to an Error Output

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.After adding an error output to a component, you must provide code that handles the error or truncation conditions specific to the component and redirects the error or truncation rows to the error output. È possibile eseguire questa operazione in due modi, a seconda che l'output degli errori sia sincrono o asincrono.You can do this in two ways, depending on whether the error output is synchronous or asynchronous.

Reindirizzamento di una riga con output sincroniRedirecting a Row with Synchronous Outputs

Le righe vengono inviate agli output sincroni chiamando il metodo DirectErrorRow della classe PipelineBuffer.Rows are sent to synchronous outputs by calling the DirectErrorRow method of the PipelineBuffer class. 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.The method call includes as parameters the ID of the error output, the component-defined error code, and the index of the column that the component was unable to process.

Nell'esempio di codice seguente è illustrato come indirizzare una riga in un buffer a un output degli errori sincrono utilizzando il metodo DirectErrorRow.The following code example demonstrates how to direct a row in a buffer to a synchronous error output using the DirectErrorRow method.

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 asincroniRedirecting a Row with Asynchronous Outputs

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.Instead of directing rows to an output, as is done with synchronous error outputs, components with asynchronous outputs send a row to an error output by explicitly adding a row to the output PipelineBuffer. 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.Implementing a component that uses asynchronous error outputs requires adding columns to the error output that are provided to downstream components, and caching the output buffer for the error output that is provided to the component during the PrimeOutput method. I dettagli di implementazione di un componente con output asincroni vengono descritti in dettaglio nell'argomento lo sviluppo di un componente di trasformazione personalizzato con output asincroni.The details of implementing a component with asynchronous outputs are covered in detail in the topic Developing a Custom Transformation Component with Asynchronous Outputs. 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.If columns are not explicitly added to the error output, the buffer row that is added to the output buffer contains only the two error columns.

Per inviare una riga a un output degli errori asincrono, è necessario aggiungere una riga al buffer dell'output degli errori.To send a row to an asynchronous error output, you must add a row to the error output buffer. Poiché è possibile che sia già stata aggiunta una riga al buffer dell'output non degli errori, è necessario rimuovere tale riga tramite il metodo RemoveRow.Sometimes, a row may have already been added to the non-error output buffer and you must remove this row by using the RemoveRow method. 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.Next you set the output buffer columns values, and finally, you call the SetErrorInfo method to provide the component-specific error code and the error column value.

Nell'esempio seguente è illustrato come utilizzare un output degli errori per un componente con output asincroni.The following example demonstrates how to use an error output for a component with asynchronous outputs. 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.When the simulated error occurs, the component adds a row to the error output buffer, copies the values that were previously added to the non-error output buffer to the error output buffer, removes the row that was added to the non-error output buffer, and, finally, sets the error code and error column values by calling the SetErrorInfo method.

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  

Vedere ancheSee Also

Gestione degli errori nei dati Error Handling in Data
Utilizzo di output degli erroriUsing Error Outputs