데이터 흐름 구성 요소에서 오류 출력 사용
적용 대상: 
Azure Data Factory의 SQL Server SSIS Integration Runtime
구성 요소에서 실행 중에 처리할 수 없는 행을 리디렉션할 수 있도록 오류 출력이라는 특수 IDTSOutput100 개체를 구성 요소에 추가할 수 있습니다. 구성 요소에서 발생할 수 있는 문제는 일반적으로 오류 또는 잘림으로 분류되며 각 구성 요소에 따라 다릅니다. 오류 출력을 제공하는 구성 요소는 결과 집합에서 오류 행을 필터링하거나, 문제가 발생할 때 구성 요소를 실패하거나, 오류를 무시하고 계속하여 오류 조건을 유연하게 처리할 수 있는 유연성을 제공합니다.
구성 요소에서 오류 출력을 구현하고 지원하려면 먼저 구성 요소의 속성을 true로 설정 UsesDispositions 해야 합니다. 그런 다음 속성이 true로 설정된 구성 요소에 출력을 IsErrorOut 추가해야 합니다. 마지막으로 구성 요소에는 오류 또는 잘림이 발생할 때 행을 오류 출력으로 리디렉션하는 코드가 포함되어야 합니다. 이 항목에서는 이러한 세 단계를 설명하고 동기 오류 출력과 비동기 오류 출력 간의 차이점을 설명합니다.
오류 출력 만들기
의 메서드를 New 호출한 다음 새 출력의 OutputCollection속성을 true로 설정 IsErrorOut 하여 오류 출력을 만듭니다. 출력이 비동기적인 경우에는 출력에 대해 아무 작업도 수행하지 않아야 합니다. 출력이 동기식이고 동일한 입력과 동기식으로 다른 출력이 있는 경우 해당 및 SynchronousInputID 속성도 설정 ExclusionGroup 해야 합니다. 두 속성 모두 동일한 입력과 동기식인 다른 출력과 동일한 값을 가져야 합니다. 이러한 속성이 0이 아닌 값으로 설정되지 않은 경우 입력에서 제공하는 행이 입력과 동기식인 두 출력으로 전송됩니다.
구성 요소가 실행 중에 오류 또는 잘림이 발생하면 입력 또는 출력의 ErrorRowDisposition 설정 및 TruncationRowDisposition 속성 또는 오류가 발생한 입력 또는 출력 열에 따라 진행됩니다. 이러한 속성의 값은 기본적으로 .로 RD_NotUsed설정해야 합니다. 구성 요소의 오류 출력이 다운스트림 구성 요소에 연결된 경우 이 속성은 구성 요소의 사용자가 설정하며 사용자가 구성 요소에서 오류 또는 잘림을 처리하는 방법을 제어할 수 있도록 합니다.
오류 열 채우기
오류 출력이 만들어지면 데이터 흐름 태스크에서는 출력 열 컬렉션에 두 개의 열을 자동으로 추가합니다. 이러한 열은 구성 요소에서 오류 또는 잘림을 발생시킨 열의 ID를 지정하고 구성 요소별 오류 코드를 제공하는 데 사용됩니다. 이러한 열은 자동으로 생성되지만 열에 포함된 값은 구성 요소에서 설정해야 합니다.
이러한 열의 값을 설정하는 데 사용되는 메서드는 오류 출력이 동기 또는 비동기인지에 따라 달라집니다. 동기 출력이 있는 구성 요소는 다음 섹션에서 자세히 설명한 메서드를 호출 DirectErrorRow 하고 오류 코드 및 오류 열 값을 매개 변수로 제공합니다. 비동기 출력을 사용하는 구성 요소에서는 두 가지 방법 중 하나로 이러한 열의 값을 설정할 수 있습니다. 출력 버퍼의 SetErrorInfo 메서드를 호출하고 값을 지정하거나, FindColumnByLineageID를 사용하여 버퍼에서 오류 열을 찾고 해당 열의 값을 직접 설정할 수 있습니다. 그러나 열 이름이 변경되었거나 출력 열 컬렉션의 위치가 수정되었을 수 있으므로 후자의 메서드는 신뢰할 수 없을 수 있습니다. 이 메서드는 SetErrorInfo 이러한 오류 열의 값을 수동으로 찾을 필요 없이 자동으로 설정합니다.
특정 오류 코드에 해당하는 오류 설명을 가져와야 하는 경우 구성 요소 ComponentMetaData 의 속성을 통해 사용할 수 있는 인터페이스의 IDTSComponentMetaData100 메서드를 사용할 GetErrorDescription 수 있습니다.
다음 코드 예제에서는 오류 출력을 포함하여 입력과 두 개의 출력이 있는 구성 요소를 보여 줍니다. 첫 번째 예제에서는 입력과 동기식으로 오류 출력을 만드는 방법을 보여줍니다. 두 번째 예제에서는 비동기 오류 출력을 만드는 방법을 보여줍니다.
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
다음 코드 예제에서는 비동기 오류 출력을 만듭니다.
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
행을 오류 출력으로 리디렉션
구성 요소에 오류 출력을 추가한 후에는 구성 요소와 관련된 오류 또는 잘림 조건을 처리하고 오류 또는 잘림 행을 오류 출력으로 리디렉션하는 코드를 제공해야 합니다. 이 작업은 오류 출력이 동기적인지 비동기적인지에 따라 두 가지 방법 중 하나로 수행할 수 있습니다.
동기 출력을 사용하여 행 리디렉션
행은 클래스의 메서드를 호출하여 동기 출력으로 DirectErrorRow PipelineBuffer 전송됩니다. 메서드 호출에는 오류 출력의 ID, 구성 요소 정의 오류 코드 및 구성 요소가 처리할 수 없는 열의 인덱스가 매개 변수로 포함됩니다.
다음 코드 예에서는 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
비동기 출력을 사용하여 행 리디렉션
동기 오류 출력과 마찬가지로 행을 출력으로 보내는 대신 비동기 출력이 있는 구성 요소는 출력에 행을 명시적으로 추가하여 행 PipelineBuffer을 오류 출력으로 보냅니다. 비동기 오류 출력을 사용하는 구성 요소를 구현하려면 다운스트림 구성 요소에 제공되는 오류 출력에 열을 추가하고 메서드 중에 PrimeOutput 구성 요소에 제공된 오류 출력에 대한 출력 버퍼를 캐싱해야 합니다. 비동기 출력을 사용하여 구성 요소를 구현하는 방법에 대한 세부 정보는 비동기 출력을 사용하여 사용자 지정 변환 구성 요소 개발 항목 에서 자세히 설명합니다. 열이 오류 출력에 명시적으로 추가되지 않은 경우 출력 버퍼에 추가된 버퍼 행에는 두 개의 오류 열만 포함됩니다.
비동기 오류 출력에 행을 보내려면 오류 출력 버퍼에 행을 추가해야 합니다. 일부 경우에는 행이 이미 오류가 아닌 출력 버퍼에 추가되어 있을 수 있으며 이 경우 RemoveRow 메서드를 사용하여 해당 행을 제거해야 합니다. 그런 다음 출력 버퍼의 열 값을 설정하고, 마지막으로 SetErrorInfo 메서드를 호출하여 구성 요소별 오류 코드와 오류 열 값을 제공합니다.
다음 예제에서는 비동기 출력을 사용 하 여 구성 요소에 대 한 오류 출력을 사용 하는 방법을 보여 줍니다. 시뮬레이트된 오류가 발생하면 구성 요소는 오류 출력 버퍼에 행을 추가하고, 이전에 오류 출력 버퍼에 추가된 값을 오류 출력 버퍼에 복사하고, 오류가 아닌 출력 버퍼에 추가된 행을 제거하고, 마지막으로 메서드를 호출 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
참고 항목
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기