사용자 지정 태스크 코딩Coding a Custom Task

Task 기본 클래스에서 상속된 클래스를 만들고 이 클래스에 DtsTaskAttribute 특성을 적용한 후에는 기본 클래스의 속성 및 메서드 구현을 재정의하여 사용자 지정 기능을 제공해야 합니다.After you have created a class that inherits from the Task base class, and applied the DtsTaskAttribute attribute to the class, you must override the implementation of the properties and methods of the base class to provide your custom functionality.

태스크 구성Configuring the Task

태스크 유효성 검사Validating the Task

Integration ServicesIntegration Services 패키지를 디자인하는 경우 모든 오류를 런타임에만 찾는 것이 아니라 태스크에 대한 설정 작업이 수행되는 즉시 올바르지 않거나 적절하지 않은 설정을 catch할 수 있도록 유효성 검사를 통해 각 태스크에 대한 설정을 확인할 수 있습니다.When you are designing an Integration ServicesIntegration Services package, you can use validation to verify settings on each task, so that you can catch incorrect or inappropriate settings as soon as they are set, instead of finding all errors at run-time only. 유효성 검사의 목적은 태스크가 성공적으로 실행되지 못하게 하는 잘못된 설정이나 연결이 태스크에 포함되어 있는지 확인하는 것입니다.The purpose of validation is to determine whether the task contains invalid settings or connections that will prevent it from running successfully. 이렇게 하면 첫 번째 실행에서 실행될 가능성이 높은 태스크가 패키지에 포함되도록 할 수 있습니다.This makes sure that the package contains tasks that have a good chance of running on their first run.

사용 하 여 유효성 검사를 구현할 수는 유효성 검사 사용자 지정 코드에서 메서드.You can implement validation by using the Validate method in custom code. 런타임 엔진의 작업을 호출 하 여 유효성을 검사는 유효성 검사 태스크에서 메서드가 있습니다.The run-time engine validates a task by calling the Validate method on the task. 태스크 유효성 검사의 성공 여부를 결정하는 조건을 정의하고 평가 결과를 런타임 엔진에 알리는 작업은 태스크 개발자가 수행해야 합니다.It is the responsibility of the task developer to define the criteria that give you a successful or failed task validation, and to notify the run-time engine of the result of this evaluation.

태스크 추상 기본 클래스Task Abstract Base Class

Task 추상 기본 클래스를 제공는 유효성 검사 각 작업의 유효성 검사 기준을 정의를 재정의 하는 메서드.The Task abstract base class provides the Validate method that each task overrides to define its validation criteria. SSISSSIS 디자이너를 자동으로 호출 하는 유효성 검사 패키지를 디자인 하는 동안 여러 번 메서드 작업의 구성 문제를 식별 하려면 경고 또는 오류가 발생할 때 사용자에 게 시각적 표시를 제공 합니다.The SSISSSIS Designer automatically calls the Validate method multiple times during package design, and provides visual cues to the user when warnings or errors occur to help identify problems with the configuration of the task. 태스크에서는 DTSExecResult 열거형의 값을 반환하고 경고 및 오류 이벤트를 발생시켜 유효성 검사 결과를 제공합니다.Tasks provide validation results by returning a value from the DTSExecResult enumeration, and by raising warning and error events. 이러한 이벤트에는 SSISSSIS 디자이너에서 사용자에게 표시되는 정보가 들어 있습니다.These events contain information that is displayed to the user in SSISSSIS Designer.

다음은 유효성 검사의 몇 가지 예입니다.Some examples for validation follow:

  • 연결 관리자가 특정 파일 이름의 유효성을 검사합니다.A connection manager validates the specific file name.

  • 연결 관리자가 입력 형식이 XML 파일과 같은 필요한 형식인지 확인합니다.A connection manager validates that the type of input is the expected type, such as an XML file.

  • 데이터베이스 입력이 필요한 태스크에서 데이터베이스 연결이 아닌 연결을 통해 데이터를 받을 수 없는지 확인합니다.A task that expects database input verifies that it cannot receive data from a non-database connection.

  • 태스크에서 해당 태스크에 설정된 다른 속성과 충돌하는 속성이 없는지 확인합니다.A task guarantees that none of its properties contradicts other properties set on the same task.

  • 태스크에서 실행 시 태스크에 사용되는 필수 리소스를 모두 사용할 수 있는지 확인합니다.A task guarantees that all required resources used by the task at execution time are available.

    유효성 검사를 수행할 대상 항목을 결정할 때는 성능을 고려해야 합니다.Performance is something to consider in determining what is validated and what is not. 예를 들어 태스크에 대한 입력이 대역폭이 낮거나 트래픽이 많은 네트워크 연결을 통해 이루어지는 경우For example, the input to a task might be a connection over a network that has low bandwidth or heavy traffic. 유효성 검사를 통해 리소스의 사용 가능성을 확인하는 데는 몇 초 정도만 소요되지만The validation may take several seconds to process if you decide to validate that the resource is available. 다른 유효성 검사 작업에는 사용량이 많은 서버로의 왕복이 필요하므로 유효성 검사 루틴의 속도가 느릴 수 있습니다.Another validation may cause a round-trip to a server that is in high demand, and the validation routine might be slow. 유효성을 검사할 수 있는 속성 및 설정은 여러 가지가 있지만 모든 속성 및 설정에 대해 유효성을 검사해야 하는 것은 아닙니다.Although there are many properties and settings that can be validated, not everything should be validated.

  • 코드는 유효성 검사 도 메서드는 TaskHost 태스크를 실행 하기 전에 및 TaskHost 유효성 검사가 실패 하면 실행을 취소 합니다.The code in the Validate method is also called by the TaskHost before the task is run, and the TaskHost cancels execution if validation fails.

유효성 검사 중 사용자 인터페이스 고려 사항User Interface Considerations during Validation

Task 포함는 IDTSComponentEvents 인터페이스에 대 한 매개 변수로 유효성 검사 메서드.The Task includes an IDTSComponentEvents interface as a parameter to the Validate method. IDTSComponentEvents 인터페이스에는 태스크에서 런타임 엔진에 이벤트를 발생시키기 위해 호출하는 메서드가 포함되어 있습니다.The IDTSComponentEvents interface contains the methods that are called by the task in order to raise events to the run-time engine. FireWarningFireError 메서드는 유효성 검사 중 경고 또는 오류 조건이 발생할 때 호출됩니다.The FireWarning and FireError methods are called when a warning or error condition occurs during validation. 두 경고 메서드에는 동일한 매개 변수가 필요하며 이러한 매개 변수에는 오류 코드, 원본 구성 요소, 설명, 도움말 파일, 및 도움말 컨텍스트 정보가 포함됩니다.Both warning methods require the same parameters, which include an error code, source component, description, Help file, and Help context information. SSISSSIS 디자이너에서는 이 정보를 사용하여 디자인 화면에 시각적 표시를 제공합니다.The SSISSSIS Designer uses this information to display visual cues on the design surface. 디자이너에서 제공하는 시각적 표시로는 디자이너 화면에서 태스크 옆에 나타나는 느낌표 아이콘이 있습니다.The visual cues that are provided by the designer include an exclamation icon that appears next to the task on the designer surface. 이 시각적 표시는 실행을 계속하기 전에 태스크에 추가 구성이 필요함을 나타냅니다.This visual cue signals to the user that the task requires additional configuration before execution can continue.

느낌표 아이콘에는 오류 메시지가 포함된 도구 설명도 표시됩니다.The exclamation icon also displays a ToolTip that contains an error message. 오류 메시지는 태스크에서 이벤트의 설명 매개 변수로 제공됩니다.The error message is provided by the task in the description parameter of the event. 오류 메시지에도 표시 됩니다는 작업 목록 의 창 SQL Server Data Tools(SSDT)SQL Server Data Tools (SSDT), 모든 유효성 검사 오류를 보기 위한 중앙 위치에 사용자를 제공 합니다.Error messages are also displayed in the Task List pane of SQL Server Data Tools(SSDT)SQL Server Data Tools (SSDT), providing the user with a central location for viewing all validation errors.

유효성 검사 예Validation Example

다음 코드 예제에서는 연결 된 작업을 보여 줍니다.는 UserName 속성입니다.The following code example shows a task with a UserName property. 이 속성은 유효성 검사를 성공적으로 수행하기 위한 필수 항목으로 지정되었습니다.This property has been specified as required for validation to succeed. 이 속성이 설정되어 있지 않으면 태스크에서는 오류를 게시하고 Failure 열거형의 DTSExecResult를 반환합니다.If the property is not set, the task posts an error, and returns Failure from the DTSExecResult enumeration. 유효성 검사 메서드는 try/catch 블록에서 되 고 예외가 발생 하면 유효성 검사에 실패 합니다.The Validate method is wrapped in a try/catch block, and fails validation if an exception occurs.

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  

태스크 지속Persisting the Task

일반적으로 태스크의 사용자 지정 지속성은 구현할 필요가 없습니다.Ordinarily you do not have to implement custom persistence for a task. 사용자 지정 지속성은 개체의 속성이 복합 데이터 형식을 사용할 때만 필요합니다.Custom persistence is required only when the properties of an object use complex data types. 자세한 내용은 참조 Integration Services에 대 한 사용자 지정 개체 개발합니다.For more information, see Developing Custom Objects for Integration Services.

태스크 실행Executing the Task

이 섹션에서는 사용 하는 방법을 설명는 Execute 메서드를 상속 하 고 작업에 의해 재정의 됩니다.This section describes how to use the Execute method that is inherited and overridden by tasks. 태스크 실행 결과에 대한 정보를 제공하는 다양한 방법에 대해 설명합니다.This section also explains various ways of providing information about the results of task execution.

Execute 메서드Execute Method

패키지에 포함 된 작업 실행 시기는 Integration ServicesIntegration Services 런타임 호출의 Execute 메서드.Tasks that are contained in a package run when the Integration ServicesIntegration Services runtime calls their Execute method. 이 메서드에서 핵심 비즈니스 논리 및 기능을 구현 작업과의 값을 반환 하는 메시지를 게시 하 여 실행 결과 제공는 DTSExecResult 열거 및 속성을 재정의 가져오기ExecutionValue 속성입니다.Tasks implement their core business logic and functionality in this method, and provide the results of execution by posting messages, returning a value from the DTSExecResult enumeration, and overriding the property get of the ExecutionValue property.

Task 기본 클래스는 Execute 메서드의 기본 구현을 제공합니다.The Task base class provides a default implementation of the Execute method. 사용자 지정 태스크에서는 이 메서드를 재정의하여 해당 태스크의 런타임 기능을 정의합니다.The custom tasks override this method to define their run-time functionality. TaskHost 개체는 태스크를 런타임 엔진과 패키지의 다른 개체에서 격리하여 해당 태스크를 래핑합니다.The TaskHost object wraps the task, isolating it from the run-time engine and the other objects in the package. 이 격리로 인해 태스크는 실행 순서와 관련된 패키지 내에서의 태스크 위치를 알 수 없으므로 런타임에서 호출될 때만 실행됩니다.Because of this isolation, the task is unaware of its location in the package with regard to its execution order, and runs only when it is called by the runtime. 이 아키텍처를 통해 실행 중 태스크에서 패키지를 수정할 때 발생할 수 있는 문제를 방지할 수 있습니다.This architecture prevents problems that can occur when tasks modify the package during execution. 격리된 태스크에서는 Execute 메서드에 매개 변수로 지정된 개체를 통해서만 패키지의 다른 개체에 액세스할 수 있습니다.The task is provided access to the other objects in the package only through the objects supplied to it as parameters in the Execute method. 태스크에서는 이러한 매개 변수를 통해 패키지의 안정성을 보장하는 데 필요한 격리 상태를 유지하면서 이벤트를 발생시키고, 이벤트 로그에 항목을 기록하고, 변수 컬렉션에 액세스하고, 데이터 원본에 대한 연결을 트랜잭션에 참여시킬 수 있습니다.These parameters let tasks raise events, write entries to the event log, access the variables collection, and enlist connections to data sources in transactions, while still maintaining the isolation that is necessary to guarantee the stability and reliability of the package.

다음 표에서는 Execute 메서드에서 태스크에 제공되는 매개 변수를 설명합니다.The following table lists the parameters provided to the task in the Execute method.

매개 변수Parameter DescriptionDescription
Connections 태스크에서 사용할 수 있는 ConnectionManager 개체의 컬렉션을 포함합니다.Contains a collection of ConnectionManager objects available to the task.
VariableDispenser 태스크에서 사용할 수 있는 변수를 포함합니다.Contains the variables available to the task. 태스크에서는 변수를 직접 사용하는 것이 아니라 VariableDispenser를 통해 사용합니다.The tasks use variables through the VariableDispenser; the tasks do not use variables directly. VariableDispenser는 변수를 잠그거나 잠금 해제하고 교착 상태나 덮어쓰기를 방지합니다.The variable dispenser locks and unlocks variables, and prevents deadlocks or overwrites.
IDTSComponentEvents 태스크에서 런타임 엔진에 이벤트를 발생시키기 위해 호출하는 메서드를 포함합니다.Contains the methods called by the task to raise events to the run-time engine.
IDTSLogging 태스크에서 이벤트 로그에 항목을 기록하는 데 사용하는 메서드 및 속성을 포함합니다.Contains methods and properties used by the task to write entries to the event log.
개체Object 해당 컨테이너가 포함된 트랜잭션 개체가 있는 경우 이를 포함합니다.Contains the transaction object that the container is a part of, if any. 이 값은 AcquireConnection 개체의 ConnectionManager 메서드에 매개 변수로 전달됩니다.This value is passed as a parameter to the AcquireConnection method of a ConnectionManager object.

실행 피드백 제공Providing Execution Feedback

작업의 코드 줄 바꿈 try/catch 런타임 엔진에 발생 한 예외를 방지 하기 위해 블록입니다.Tasks wrap their code in try/catch blocks to prevent exceptions from being raised to the run-time engine. 이렇게 하면 패키지 실행이 끝까지 완료되며 예기치 않게 중지되는 경우가 없습니다.This ensures that the package finishes execution and does not stop unexpectedly. 그러나 런타임 엔진에서는 태스크 실행 중 발생할 수 있는 오류 조건을 처리하기 위한 다른 메커니즘을 제공합니다.However, the run-time engine provides other mechanisms for handling error conditions that can occur during the execution of a task. 이러한 메커니즘에는 오류 및 경고 메시지 게시, DTSExecResult 구조의 값 반환, 메시지 게시, DTSExecResult 값 반환 및 ExecutionValue 속성을 통한 태스크 실행 결과에 대한 정보 공개 등이 포함됩니다.These include posting error and warning messages, returning a value from the DTSExecResult structure, posting messages, returning the DTSExecResult value, and disclosing information about the results of task execution through the ExecutionValue property.

IDTSComponentEvents 인터페이스에는 태스크에서 런타임 엔진에 오류 및 경고 메시지를 게시하기 위해 호출할 수 있는 FireWarningFireError 메서드가 포함되어 있습니다.The IDTSComponentEvents interface contains the FireWarning and FireError methods, which can be called by the task to post error and warning messages to the run-time engine. 두 메서드에는 오류 코드, 원본 구성 요소, 설명, 도움말 파일 및 도움말 컨텍스트 정보와 같은 매개 변수가 필요합니다.Both methods require parameters such as the error code, source component, description, Help file, and help context information. 런타임에서는 태스크의 구성에 따라 이벤트 및 중단점을 발생시키거나 이벤트 로그에 정보를 기록하는 방식으로 이러한 메시지에 응답합니다.Depending on the configuration of the task, the runtime responds to these messages by raising events and breakpoints, or by writing information to the event log.

TaskHost에서는 실행 결과에 대한 추가 정보를 제공하는 데 사용할 수 있는 ExecutionValue 속성도 제공합니다.The TaskHost also provides the ExecutionValue property that can be used to provide additional information about the results of execution. 예를 들어, 작업의 일환으로 테이블에서 행을 삭제 하는 경우 해당 Execute 메서드를 값으로 삭제 된 행 수 반환할 수 있습니다는 ExecutionValue 속성입니다.For example, if a task deletes rows from a table as part of its Execute method, it might return the number of rows deleted as the value of the ExecutionValue property. 또한 TaskHost에서는 ExecValueVariable 속성을 제공합니다.In addition, the TaskHost provides the ExecValueVariable property. 이 속성을 통해 사용자는 태스크에서 반환된 ExecutionValue를 태스크에 표시되는 변수에 매핑할 수 있습니다.This property lets the user map the ExecutionValue returned from the task to any variable visible to the task. 그런 다음 지정한 변수를 사용하여 태스크 간에 선행 제약 조건을 설정할 수 있습니다.The specified variable can then be used to establish precedence constraints between tasks.

실행 예Execution Example

다음 코드 예제에서는의 구현을 보여 줍니다.는 Execute 메서드를 재정의 된 표시 ExecutionValue 속성입니다.The following code example demonstrates an implementation of the Execute method, and shows an overridden ExecutionValue property. 이 작업에 지정 된 파일 삭제는 fileName 태스크의 속성입니다.The task deletes the file that is specified by the fileName property of the task. 파일 존재 하지 않는 경우 또는 경우 경고를 게시는 fileName 속성은 빈 문자열입니다.The task posts a warning if the file does not exist, or if the fileName property is an empty string. 작업 반환는 부울 값에 ExecutionValue 파일이 삭제 여부를 나타내는 속성을 합니다.The task returns a Boolean value in the ExecutionValue property to indicate whether the file was deleted.

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  

관련 항목:See Also

사용자 지정 작업 만들기 Creating a Custom Task
사용자 지정 태스크 코딩 Coding a Custom Task
사용자 지정 태스크에 대 한 사용자 인터페이스 개발Developing a User Interface for a Custom Task