사용자 지정 태스크 코딩

아티클
07/04/2024

적용 대상: Azure Data Factory의 SQL Server SSIS Integration Runtime

Microsoft.SqlServer.Dts.Runtime.Task 기본 클래스에서 상속하는 클래스를 만들고 이 클래스에 DtsTaskAttribute 특성을 적용한 후에는 기본 클래스의 속성 및 메서드 구현을 재정의하여 사용자 지정 기능을 제공해야 합니다.

태스크 구성

작업 유효성 검사

Integration Services 패키지를 디자인할 때 유효성 검사를 사용하여 각 작업에 대한 설정을 확인할 수 있으므로 런타임에만 모든 오류를 찾는 대신 설정되는 즉시 올바르지 않거나 부적절한 설정을 catch할 수 있습니다. 유효성 검사의 목적은 작업이 성공적으로 실행되지 않도록 하는 잘못된 설정 또는 연결이 포함되어 있는지 여부를 확인하는 것입니다. 이렇게 하면 패키지에 첫 번째 실행에서 실행 가능성이 높은 태스크가 포함되어 있는지 확인합니다.

사용자 지정 코드에서 Validate 메서드를 사용하여 유효성 검사를 구현할 수 있습니다. 런타임 엔진은 태스크에 대한 Validate 메서드를 호출하여 해당 태스크의 유효성을 검사합니다. 태스크 개발자는 성공 또는 실패한 태스크 유효성 검사를 제공하는 기준을 정의하고 런타임 엔진에 이 평가 결과를 알릴 책임이 있습니다.

태스크 추상 기본 클래스

Microsoft.SqlServer.Dts.Runtime.Task 추상 기본 클래스는 각 태스크가 유효성 검사 조건을 정의하기 위해 재정의하는 Validate 메서드를 제공합니다. SSIS 디자이너는 패키지 디자인 중에 유효성 검사 메서드를 여러 번 자동으로 호출하고 경고 또는 오류가 발생할 때 사용자에게 시각적 신호를 제공하여 작업 구성 문제를 식별합니다. 태스크는 열거형에서 DTSExecResult 값을 반환하고 경고 및 오류 이벤트를 발생시켜 유효성 검사 결과를 제공합니다. 이러한 이벤트에는 SSIS 디자이너에서 사용자에게 표시되는 정보가 포함됩니다.

유효성 검사에 대한 몇 가지 예는 다음과 같습니다.

연결 관리자는 특정 파일 이름의 유효성을 검사합니다.
연결 관리자가 입력 형식이 XML 파일과 같은 필요한 형식인지 확인합니다.
데이터베이스 입력이 예상되는 작업은 데이터베이스가 아닌 연결에서 데이터를 수신할 수 없음을 확인합니다.
태스크에서 해당 태스크에 설정된 다른 속성과 충돌하는 속성이 없는지 확인합니다.
태스크는 실행 시 태스크에서 사용하는 모든 필수 리소스를 사용할 수 있도록 보장합니다.

성능은 유효성이 검사되는 항목과 그렇지 않은 항목을 결정할 때 고려해야 할 사항입니다. 예를 들어 태스크에 대한 입력이 대역폭이 낮거나 트래픽이 많은 네트워크 연결을 통해 이루어지는 경우 유효성 검사를 통해 리소스의 사용 가능성을 확인하는 데는 몇 초 정도만 소요되지만 다른 유효성 검사 작업에는 사용량이 많은 서버로의 왕복이 필요하므로 유효성 검사 루틴의 속도가 느릴 수 있습니다. 유효성을 검사할 수 있는 속성과 설정이 많지만 모든 속성의 유효성을 검사해야 하는 것은 아닙니다.

Validate 메서드의 코드는 태스크가 실행되기 전에 호출 TaskHost 되며 TaskHost 유효성 검사가 실패하면 실행을 취소합니다.

유효성 검사 중 사용자 인터페이스 고려 사항

Microsoft.SqlServer.Dts.Runtime.Task에는 IDTSComponentEvents 인터페이스가 Validate 메서드에 대한 매개 변수로 포함되어 있습니다. 이 인터페이스에는 IDTSComponentEvents 런타임 엔진에 이벤트를 발생시키기 위해 태스크에서 호출하는 메서드가 포함되어 있습니다. FireWarning 유효성 검사 중에 경고 또는 오류 조건이 발생할 때 및 FireError 메서드가 호출됩니다. 두 경고 메서드 모두 오류 코드, 소스 구성 요소, 설명, 도움말 파일 및 도움말 컨텍스트 정보를 포함하는 동일한 매개 변수가 필요합니다. SSIS 디자이너는 이 정보를 사용하여 디자인 화면에 시각적 신호를 표시합니다. 디자이너에서 제공하는 시각적 표시로는 디자이너 화면에서 태스크 옆에 나타나는 느낌표 아이콘이 있습니다. 이 시각적 신호는 실행을 계속하기 전에 태스크에 추가 구성이 필요하다는 신호를 사용자에게 표시합니다.

느낌표 아이콘에는 오류 메시지가 포함된 도구 설명도 표시됩니다. 오류 메시지는 이벤트의 설명 매개 변수에 있는 태스크에 의해 제공됩니다. 오류 메시지는 SSDT(SQL Server Data Tools)의 작업 목록 창에도 표시되어 사용자에게 모든 유효성 검사 오류를 볼 수 있는 중앙 위치를 제공합니다.

유효성 검사 예제

다음 코드 예제에서는 UserName 속성이 있는 작업을 보여 있습니다. 이 속성은 유효성 검사가 성공하는 데 필요한 대로 지정되었습니다. 이 속성이 설정되어 있지 않으면 태스크에서는 오류를 게시하고 Failure 열거형의 DTSExecResult를 반환합니다. Validate 메서드는 try/catch 블록에 래핑되고 예외가 발생하면 유효성 검사에 실패합니다.

using System;  
using Microsoft.SqlServer.Dts.Runtime;  
  
public class SampleTask : Task  
{  
  private string userName = "";  
  
  public override DTSExecResult Validate(Connections connections,  
     VariableDispenser variableDispenser, IDTSComponentEvents events,  
     IDTSLogging log)  
  {  
    try  
    {  
      if (this.userName == "")  
      {  
        //   Raise an OnError event.  
        events.FireError(0, "SampleTask", "The UserName property must be configured.", "", 0);  
        //   Fail validation.  
        return DTSExecResult.Failure;  
      }  
      //   Return success.  
      return DTSExecResult.Success;  
    }  
    catch (System.Exception exception)  
    {  
      //   Capture exceptions, post an error, and fail validation.  
      events.FireError(0, "Sampletask", exception.Message, "", 0);  
      return DTSExecResult.Failure;  
    }  
  }  
  public string UserName  
  {  
    get  
    {  
      return this.userName;  
    }  
    set  
    {  
      this.userName = value;  
    }  
  }  
}

Imports System  
Imports Microsoft.SqlServer.Dts.Runtime  
  
Public Class SampleTask  
  Inherits Task  
  
  Private _userName As String = ""  
  
  Public Overrides Function Validate(ByVal connections As Connections, _  
     ByVal variableDispenser As VariableDispenser, _  
     ByVal events As IDTSComponentEvents, _  
     ByVal log As IDTSLogging) As DTSExecResult  
  
    Try  
      If Me._userName = "" Then  
        '   Raise an OnError event.  
        events.FireError(0, "SampleTask", "The UserName property must be configured.", "", 0)  
        '   Fail validation.  
        Return DTSExecResult.Failure  
      End If  
      '   Return success.  
      Return DTSExecResult.Success  
    Catch exception As System.Exception  
      '   Capture exceptions, post an error, and fail validation.  
      events.FireError(0, "Sampletask", exception.Message, "", 0)  
      Return DTSExecResult.Failure  
    End Try  
  
  End Function  
  
  Public Property UserName() As String  
    Get  
      Return Me._userName  
    End Get  
    Set(ByVal Value As String)  
      Me._userName = Value  
    End Set  
  End Property  
  
End Class

태스크 지속

일반적으로 작업에 대한 사용자 지정 지속성을 구현할 필요가 없습니다. 사용자 지정 지속성은 개체의 속성이 복잡한 데이터 형식을 사용하는 경우에만 필요합니다. 자세한 내용은Integration Services 사용자 지정 개체 개발을 참조하세요.

작업 실행

이 섹션에서는 태스크에서 상속되고 재정의 되는 Execute 메서드를 사용하는 방법을 설명합니다. 또한 이 섹션에서는 태스크 실행 결과에 대한 정보를 제공하는 다양한 방법을 설명합니다.

Execute 메서드

패키지에 포함된 작업은 Integration Services 런타임에서 Execute 메서드를 호출할 때 실행됩니다. 태스크는 이 메서드에서 핵심 비즈니스 논리 및 기능을 구현하고, 메시지를 게시하고, 열거형에서 DTSExecResult 값을 반환하고, ExecutionValue 속성의 속성 가져오기를 재정의하여 실행 결과를 제공합니다.

Microsoft.SqlServer.Dts.Runtime.Task 기본 클래스는 메서드의 기본 구현을 Execute 제공합니다. 사용자 지정 작업은 런타임 기능을 정의하기 위해 이 메서드를 재정의합니다. 개체는 TaskHost 태스크를 래핑하여 런타임 엔진 및 패키지의 다른 개체에서 격리합니다. 이러한 격리로 인해 태스크는 실행 순서와 관련하여 패키지의 위치를 인식하지 못하며 런타임에서 호출할 때만 실행됩니다. 이 아키텍처는 태스크가 실행 중에 패키지를 수정할 때 발생할 수 있는 문제를 방지합니다. 격리된 태스크에서는 Execute 메서드에 매개 변수로 지정된 개체를 통해서만 패키지의 다른 개체에 액세스할 수 있습니다. 태스크에서는 이러한 매개 변수를 통해 패키지의 안정성을 보장하는 데 필요한 격리 상태를 유지하면서 이벤트를 발생시키고, 이벤트 로그에 항목을 기록하고, 변수 컬렉션에 액세스하고, 데이터 원본에 대한 연결을 트랜잭션에 참여시킬 수 있습니다.

다음 표에서는 Execute 메서드에서 태스크에 제공되는 매개 변수를 설명합니다.

매개 변수	설명
Connections	태스크에서 사용할 수 있는 ConnectionManager 개체의 컬렉션을 포함합니다.
VariableDispenser	태스크에서 사용할 수 있는 변수를 포함합니다. 태스크는 VariableDispenser를 통해 변수를 사용합니다. 태스크는 변수를 직접 사용하지 않습니다. 변수 디스펜서는 변수를 잠그고 잠금을 해제하며 교착 상태 또는 덮어쓰기를 방지합니다.
IDTSComponentEvents	런타임 엔진에 이벤트를 발생하기 위해 태스크에서 호출하는 메서드를 포함합니다.
IDTSLogging	태스크에서 이벤트 로그에 항목을 기록하는 데 사용하는 메서드 및 속성을 포함합니다.
Object	컨테이너가 속한 트랜잭션 개체(있는 경우)를 포함합니다. 이 값은 개체의 메서드에 AcquireConnection 매개 변수로 ConnectionManager 전달됩니다.

실행 피드백 제공

태스크는 런타임 엔진에 예외가 발생하지 않도록 해당 코드를 try/catch 블록으로 래핑합니다. 이렇게 하면 패키지 실행이 완료되고 예기치 않게 중지되지 않습니다. 그러나 런타임 엔진에서는 태스크 실행 중 발생할 수 있는 오류 조건을 처리하기 위한 다른 메커니즘을 제공합니다. 이러한 메커니즘에는 오류 및 경고 메시지 게시, DTSExecResult 구조의 값 반환, 메시지 게시, DTSExecResult 값 반환 및 ExecutionValue 속성을 통한 태스크 실행 결과에 대한 정보 공개 등이 포함됩니다.

IDTSComponentEvents 인터페이스에는 태스크에서 런타임 엔진에 오류 및 경고 메시지를 게시하기 위해 호출할 수 있는 FireWarning 및 FireError 메서드가 포함되어 있습니다. 두 방법 모두 오류 코드, 소스 구성 요소, 설명, 도움말 파일 및 도움말 컨텍스트 정보와 같은 매개 변수가 필요합니다. 태스크의 구성에 따라 런타임은 이벤트 및 중단점을 발생하거나 이벤트 로그에 정보를 작성하여 이러한 메시지에 응답합니다.

TaskHost 또한 실행 결과에 대한 추가 정보를 제공하는 데 사용할 수 있는 속성을 제공합니다ExecutionValue. 예를 들어 태스크가 Execute 메서드의 일부로 테이블에서 행을 삭제하는 경우 삭제된 행 수를 속성 값 ExecutionValue 으로 반환할 수 있습니다. 또한 속성을 TaskHost 제공합니다 ExecValueVariable . 이 속성을 통해 사용자는 태스크에서 반환된 ExecutionValue를 태스크에 표시되는 변수에 매핑할 수 있습니다. 그런 다음 지정된 변수를 사용하여 작업 간에 선행 제약 조건을 설정할 수 있습니다.

실행 예제

다음 코드 예제에서는 Execute 메서드의 구현과 재정의된 ExecutionValue 속성을 보여 줍니다. 태스크는 태스크의 fileName 속성으로 지정된 파일을 삭제합니다. 파일이 없거나 fileName 속성이 빈 문자열인 경우 태스크에서 경고를 게시합니다. 작업이 속성의 ExecutionValue 부울 값을 반환하여 파일이 삭제되었는지 여부를 나타냅니다.

using System;  
using Microsoft.SqlServer.Dts.Runtime;  
  
public class SampleTask : Task  
{  
  private string fileName = "";  
  private bool fileDeleted = false;  
  
  public override DTSExecResult Execute(Connections cons,  
     VariableDispenser vars, IDTSComponentEvents events,  
     IDTSLogging log, Object txn)  
  {  
    try  
    {  
      if (this.fileName == "")  
      {  
        events.FireWarning(0, "SampleTask", "No file specified.", "", 0);  
        this.fileDeleted = false;  
      }  
      else  
      {  
        if (System.IO.File.Exists(this.fileName))  
        {  
          System.IO.File.Delete(this.fileName);  
          this.fileDeleted = true;  
        }  
        else  
          this.fileDeleted = false;  
      }  
      return DTSExecResult.Success;  
    }  
    catch (System.Exception exception)  
    {  
      //   Capture the exception and post an error.  
      events.FireError(0, "Sampletask", exception.Message, "", 0);  
      return DTSExecResult.Failure;  
    }  
  }  
  public string FileName  
  {  
    get { return this.fileName; }  
    set { this.fileName = value; }  
  }  
  public override object ExecutionValue  
  {  
    get { return this.fileDeleted; }  
  }  
}

Imports System  
Imports Microsoft.SqlServer.Dts.Runtime  
  
Public Class SampleTask  
  Inherits Task  
  
  Private _fileName As String = ""  
  Private _fileDeleted As Boolean = False  
  
  Public Overrides Function Execute(ByVal cons As Connections, _  
     ByVal vars As VariableDispenser, ByVal events As IDTSComponentEvents, _  
     ByVal log As IDTSLogging, ByVal txn As Object) As DTSExecResult  
  
    Try  
      If Me._fileName = "" Then  
        events.FireWarning(0, "SampleTask", "No file specified.", "", 0)  
        Me._fileDeleted = False  
      Else  
        If System.IO.File.Exists(Me._fileName) Then  
          System.IO.File.Delete(Me._fileName)  
          Me._fileDeleted = True  
        Else  
          Me._fileDeleted = False  
        End If  
      End If  
      Return DTSExecResult.Success  
    Catch exception As System.Exception  
      '   Capture the exception and post an error.  
      events.FireError(0, "Sampletask", exception.Message, "", 0)  
      Return DTSExecResult.Failure  
    End Try  
  
  End Function  
  
  Public Property FileName() As String  
    Get  
      Return Me._fileName  
    End Get  
    Set(ByVal Value As String)  
      Me._fileName = Value  
    End Set  
  End Property  
  
  Public Overrides ReadOnly Property ExecutionValue() As Object  
    Get  
      Return Me._fileDeleted  
    End Get  
  End Property  
  
End Class

참고 항목

사용자 지정 작업 만들기
사용자 지정 작업 코딩
사용자 지정 태스크의 사용자 인터페이스 개발

다음을 통해 공유