Veri Akışı Bileşeninde Hata Çıkışlarını Kullanma

Şunlar için geçerlidir:SQL Server Azure Data Factory'de SSIS Entegrasyon Çalışma Zamanı

Hata çıkışları olarak adlandırılan özel IDTSOutput100 nesneler, bileşenin yürütme sırasında işleyemediği satırları yeniden yönlendirmesine izin vermek için bileşenlere eklenebilir. Bir bileşenin karşılaşabileceği sorunlar genellikle hatalar veya kesmeler olarak kategorilere ayrılır ve her bileşene özeldir. Hata çıkışları sağlayan bileşenler, bileşen kullanıcılarına hata satırlarını sonuç kümesinin dışına filtreleyerek, bir sorun oluştuğunda bileşenin başarısız olmasına veya hataları yoksayarak ve devam ederek hata koşullarını işleme esnekliği sağlar.

Bir bileşende hata çıkışlarını uygulamak ve desteklemek için önce bileşenin UsesDispositions özelliğini true olarak ayarlamanız gerekir. Ardından, özelliği IsErrorOut olarak ayarlanmış bileşene bir çıkış eklemeniz gerekir. Son olarak bileşen, hatalar veya kesmeler oluştuğunda satırları hata çıkışına yönlendiren kod içermelidir. Bu konu, bu üç adımı kapsar ve zaman uyumlu ve zaman uyumsuz hata çıkışları arasındaki farkları açıklar.

Hata Çıkışı Oluşturma

yöntemini çağırıp yeni çıkışın New özelliğini OutputCollection olarak ayarlayarak IsErrorOut bir hata çıkışı oluşturursunuz. Çıkış zaman uyumsuzsa, çıkışa başka hiçbir şey yapılmamalıdır. Çıkış zaman uyumluysa ve aynı girişle zaman uyumlu başka bir çıkış varsa ve ExclusionGroup özelliklerini de ayarlamanız SynchronousInputID gerekir. Her iki özellik de aynı girişle zaman uyumlu olan diğer çıkışla aynı değerlere sahip olmalıdır. Bu özellikler sıfır olmayan bir değere ayarlanmamışsa, giriş tarafından sağlanan satırlar girişle zaman uyumlu olan her iki çıkışa da gönderilir.

Bir bileşen yürütme sırasında hata veya kesmeyle karşılaştığında, hatanın oluştuğu giriş veya çıkışın ya da giriş veya çıkış sütununun ve ErrorRowDisposition özelliklerine TruncationRowDisposition göre devam eder. Bu özelliklerin değeri varsayılan olarak RD_NotUsedolarak ayarlanmalıdır. Bileşenin hata çıkışı bir aşağı akış bileşenine bağlandığında, bu özellik bileşenin kullanıcısı tarafından ayarlanır ve kullanıcının bileşenin hatayı veya kesme işlemini nasıl işlediğini denetlemesine olanak tanır.

Hata Sütunlarını Doldurma

Hata çıkışı oluşturulduğunda, veri akışı görevi çıkış sütunu koleksiyonuna otomatik olarak iki sütun ekler. Bu sütunlar bileşenler tarafından hataya veya kesmeye neden olan sütunun kimliğini belirtmek ve bileşene özgü hata kodunu sağlamak için kullanılır. Bu sütunlar otomatik olarak oluşturulur, ancak sütunlarda yer alan değerler bileşen tarafından ayarlanmalıdır.

Bu sütunların değerlerini ayarlamak için kullanılan yöntem, hata çıkışının zaman uyumlu mu yoksa zaman uyumsuz mu olduğuna bağlıdır. Zaman uyumlu çıkışlara sahip bileşenler, sonraki bölümde daha ayrıntılı olarak ele alınan yöntemini çağırır DirectErrorRow ve hata kodu ile hata sütunu değerlerini parametre olarak sağlar. Zaman uyumsuz çıkışlara sahip bileşenler, bu sütunların değerlerini ayarlamak için iki seçeneğe sahiptir. Çıkış arabelleğinin SetErrorInfo yöntemini çağırıp değerleri sağlayabilir veya kullanarak FindColumnByLineageID arabellekteki hata sütunlarını bulabilir ve sütunların değerlerini doğrudan ayarlayabilirler. Ancak, sütunların adları değiştirilmiş olabileceğinden veya çıkış sütunu koleksiyonundaki konumları değiştirilmiş olabileceğinden, ikinci yöntem güvenilir olmayabilir. yöntemi, SetErrorInfo bu hata sütunlarındaki değerleri el ile bulmak zorunda kalmadan otomatik olarak ayarlar.

Belirli bir hata koduna karşılık gelen hata açıklamasını almanız gerekiyorsa, bileşenin GetErrorDescription özelliği aracılığıyla kullanılabilen arabiriminin IDTSComponentMetaData100 yöntemini kullanabilirsinizComponentMetaData.

Aşağıdaki kod örnekleri, bir girişi ve hata çıkışı dahil olmak üzere iki çıkışı olan bir bileşeni gösterir. İlk örnekte girişle zaman uyumlu bir hata çıkışının nasıl oluşturulacağı gösterilmektedir. İkinci örnekte zaman uyumsuz bir hata çıkışının nasıl oluşturulacağı gösterilmektedir.

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  

Aşağıdaki kod örneği zaman uyumsuz bir hata çıkışı oluşturur.

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  

Satırı Hata Çıkışına Yeniden Yönlendirme

Bir bileşene hata çıkışı ekledikten sonra, bileşene özgü hata veya kesme koşullarını işleyen ve hata veya kesme satırlarını hata çıkışına yönlendiren kod sağlamanız gerekir. Hata çıkışının zaman uyumlu mu yoksa zaman uyumsuz mu olduğuna bağlı olarak bunu iki şekilde yapabilirsiniz.

Zaman Uyumlu Çıkışlarla Satırı Yeniden Yönlendirme

Satırlar, sınıfının yöntemi DirectErrorRow çağrılarak PipelineBuffer zaman uyumlu çıkışlara gönderilir. Yöntem çağrısı parametre olarak hata çıkışının kimliğini, bileşen tanımlı hata kodunu ve bileşenin işleyemediği sütunun dizinini içerir.

Aşağıdaki kod örneği, yöntemini kullanarak arabellekteki bir satırı zaman uyumlu bir hata çıkışına yönlendirmeyi DirectErrorRow gösterir.

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  

Zaman Uyumsuz Çıkışlarla Satırı Yeniden Yönlendirme

Zaman uyumlu hata çıkışlarında olduğu gibi satırları çıkışa yönlendirmek yerine, zaman uyumsuz çıkışlara sahip bileşenler çıkışa açıkça satır ekleyerek bir hata çıkışına PipelineBuffersatır gönderir. Zaman uyumsuz hata çıkışları kullanan bir bileşeni uygulamak için aşağı akış bileşenlerine sağlanan hata çıkışına sütun eklenmesi ve yöntem sırasında bileşene sağlanan hata çıkışı için çıkış arabelleğinin PrimeOutput önbelleğe alınmasını gerektirir. Zaman uyumsuz çıkışlarla bileşen uygulama ayrıntıları, Zaman Uyumsuz Çıkışlarla Özel Dönüştürme Bileşeni Geliştirme konusunda ayrıntılı olarak ele alınmıştır. Sütunlar hata çıkışına açıkça eklenmiyorsa, çıkış arabelleğine eklenen arabellek satırı yalnızca iki hata sütununu içerir.

Zaman uyumsuz bir hata çıkışına satır göndermek için hata çıkış arabelleğine bir satır eklemeniz gerekir. Bazen, hata olmayan çıkış arabelleğine zaten bir satır eklenmiş olabilir ve yöntemini kullanarak RemoveRow bu satırı kaldırmanız gerekir. Ardından çıkış arabelleği sütun değerlerini ayarlarsınız ve son olarak bileşene özgü hata kodunu ve hata sütunu değerini sağlamak için yöntemini çağırırsınız SetErrorInfo .

Aşağıdaki örnekte, zaman uyumsuz çıkışlara sahip bir bileşen için hata çıkışının nasıl kullanılacağı gösterilmektedir. Simülasyon hatası oluştuğunda, bileşen hata çıkış arabelleğine bir satır ekler, hata dışı çıkış arabelleğine daha önce eklenmiş olan değerleri hata çıkış arabelleğine kopyalar, hata olmayan çıkış arabelleğine eklenen satırı kaldırır ve son olarak yöntemini çağırarak SetErrorInfo hata kodunu ve hata sütunu değerlerini ayarlar.

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  

Ayrıca Bkz.

Verilerde Hata İşleme
Hata Çıkışlarını Kullanma