Menggunakan Output Kesalahan dalam Komponen Aliran Data

Berlaku untuk: SQL Server SSIS Integration Runtime di Azure Data Factory

Objek khusus IDTSOutput100 yang disebut output kesalahan dapat ditambahkan ke komponen untuk membiarkan komponen mengalihkan baris yang tidak dapat diproses selama eksekusi. Masalah yang mungkin dihadapi komponen umumnya dikategorikan sebagai kesalahan atau pemotongan, dan khusus untuk setiap komponen. Komponen yang memberikan output kesalahan memberi pengguna komponen fleksibilitas untuk menangani kondisi kesalahan dengan memfilter baris kesalahan dari kumpulan hasil, dengan menggagalkan komponen ketika masalah terjadi, atau dengan mengabaikan kesalahan dan melanjutkan.

Untuk menerapkan dan mendukung output kesalahan dalam komponen, Anda harus terlebih dahulu mengatur UsesDispositions properti komponen ke true. Kemudian Anda harus menambahkan output ke komponen yang propertinya IsErrorOut diatur ke true. Terakhir, komponen harus berisi kode yang mengalihkan baris ke output kesalahan saat kesalahan atau pemotongan terjadi. Topik ini mencakup tiga langkah ini dan menjelaskan perbedaan antara output kesalahan sinkron dan asinkron.

Membuat Output Kesalahan

Anda membuat output kesalahan dengan memanggil New metode OutputCollection, lalu mengatur IsErrorOut properti output baru ke true. Jika output tidak sinkron, tidak ada yang lain yang harus dilakukan pada output. Jika output sinkron, dan ada output lain yang sinkron ke input yang sama, Anda juga harus mengatur ExclusionGroup properti dan SynchronousInputID . Kedua properti harus memiliki nilai yang sama dengan output lain yang sinkron dengan input yang sama. Jika properti ini tidak diatur ke nilai bukan nol, baris yang disediakan oleh input dikirim ke kedua output yang sinkron ke input.

Ketika komponen mengalami kesalahan atau pemotongan selama eksekusi, komponen melanjutkan berdasarkan pengaturan ErrorRowDisposition dan TruncationRowDisposition properti input atau output, atau kolom input atau output, tempat kesalahan terjadi. Nilai properti ini harus diatur secara default ke RD_NotUsed. Ketika output kesalahan komponen terhubung ke komponen hilir, properti ini diatur oleh pengguna komponen dan memungkinkan pengguna mengontrol bagaimana komponen menangani kesalahan atau pemotongan.

Mengisi Kolom Kesalahan

Saat output kesalahan dibuat, tugas aliran data secara otomatis menambahkan dua kolom ke kumpulan kolom output. Kolom ini digunakan oleh komponen untuk menentukan ID kolom yang menyebabkan kesalahan atau pemotongan, dan untuk memberikan kode kesalahan khusus komponen. Kolom ini dihasilkan secara otomatis, tetapi nilai yang terkandung dalam kolom harus diatur oleh komponen.

Metode yang digunakan untuk mengatur nilai kolom ini tergantung pada apakah output kesalahan sinkron atau asinkron. Komponen dengan output sinkron memanggil DirectErrorRow metode , dibahas secara lebih rinci di bagian berikutnya, dan menyediakan kode kesalahan dan nilai kolom kesalahan sebagai parameter. Komponen dengan output asinkron memiliki dua pilihan untuk mengatur nilai kolom ini. Mereka dapat memanggil SetErrorInfo metode buffer output dan menyediakan nilai, atau menemukan kolom kesalahan di buffer dengan menggunakan FindColumnByLineageID dan mengatur nilai untuk kolom secara langsung. Namun, karena nama kolom mungkin telah diubah, atau lokasinya dalam koleksi kolom output mungkin telah dimodifikasi, metode terakhir mungkin tidak dapat diandalkan. Metode ini SetErrorInfo secara otomatis mengatur nilai dalam kolom kesalahan ini tanpa harus menemukannya secara manual.

Jika Anda perlu mendapatkan deskripsi kesalahan yang sesuai dengan kode kesalahan tertentu, Anda dapat menggunakan GetErrorDescription metode IDTSComponentMetaData100 antarmuka, yang tersedia melalui properti komponen ComponentMetaData .

Contoh kode berikut menunjukkan komponen yang memiliki input dan dua output, termasuk output kesalahan. Contoh pertama menunjukkan cara membuat output kesalahan yang sinkron dengan input. Contoh kedua menunjukkan cara membuat output kesalahan yang asinkron.

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  

Contoh kode berikut membuat output kesalahan yang asinkron.

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  

Mengalihkan Baris ke Output Kesalahan

Setelah menambahkan output kesalahan ke komponen, Anda harus memberikan kode yang menangani kesalahan atau kondisi pemotongan khusus untuk komponen dan mengalihkan baris kesalahan atau pemotongan ke output kesalahan. Anda dapat melakukan ini dengan dua cara, tergantung pada apakah output kesalahan sinkron atau asinkron.

Mengalihkan Baris dengan Output Sinkron

Baris dikirim ke output sinkron dengan memanggil DirectErrorRow metode PipelineBuffer kelas. Panggilan metode mencakup sebagai parameter ID output kesalahan, kode kesalahan yang ditentukan komponen, dan indeks kolom yang tidak dapat diproses komponen.

Contoh kode berikut menunjukkan cara mengarahkan baris dalam buffer ke output kesalahan sinkron menggunakan DirectErrorRow metode .

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  

Mengalihkan Baris dengan Output Asinkron

Alih-alih mengarahkan baris ke output, seperti yang dilakukan dengan output kesalahan sinkron, komponen dengan output asinkron mengirim baris ke output kesalahan dengan secara eksplisit menambahkan baris ke output PipelineBuffer. Menerapkan komponen yang menggunakan output kesalahan asinkron memerlukan penambahan kolom ke output kesalahan yang disediakan untuk komponen hilir, dan penembolokan buffer output untuk output kesalahan yang disediakan untuk komponen selama PrimeOutput metode. Detail penerapan komponen dengan output asinkron dibahas secara rinci dalam topik Mengembangkan Komponen Transformasi Kustom dengan Output Asinkron. Jika kolom tidak secara eksplisit ditambahkan ke output kesalahan, baris buffer yang ditambahkan ke buffer output hanya berisi dua kolom kesalahan.

Untuk mengirim baris ke output kesalahan asinkron, Anda harus menambahkan baris ke buffer output kesalahan. Terkadang, baris mungkin sudah ditambahkan ke buffer output non-kesalahan dan Anda harus menghapus baris ini dengan menggunakan RemoveRow metode . Selanjutnya Anda mengatur nilai kolom buffer output, dan akhirnya, Anda memanggil SetErrorInfo metode untuk memberikan kode kesalahan khusus komponen dan nilai kolom kesalahan.

Contoh berikut menunjukkan cara menggunakan output kesalahan untuk komponen dengan output asinkron. Ketika kesalahan yang disimulasikan terjadi, komponen menambahkan baris ke buffer output kesalahan, menyalin nilai yang sebelumnya ditambahkan ke buffer output non-kesalahan ke buffer output kesalahan, menghapus baris yang ditambahkan ke buffer output non-kesalahan, dan, akhirnya, mengatur kode kesalahan dan nilai kolom kesalahan dengan memanggil SetErrorInfo metode .

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  

Lihat Juga

Penanganan Kesalahan dalam Data
Menggunakan Output Kesalahan