Utilizzo degli output degli errori in un componente del flusso di dati
Si applica a:
SQL Server Integration Runtime SSIS in Azure Data Factory
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. Informazioni dettagliate sull'implementazione di un componente con output asincroni sono disponibili 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
Vedere anche
Gestione degli errori nei dati
Using Error Outputs (Uso degli output degli errori)
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per