Scrittura del codice di un'attività personalizzataCoding a Custom Task

Dopo avere creato una classe che eredita dalla classe di base Task e avere applicato l'attributo DtsTaskAttribute alla classe, è necessario eseguire l'override dell'implementazione delle proprietà e dei metodi della classe di base per fornire la funzionalità personalizzata.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.

Configurazione dell'attivitàConfiguring the Task

Convalida dell'attivitàValidating the Task

Quando si progetta un pacchetto di Integration ServicesIntegration Services, è possibile utilizzare la convalida per verificare le impostazioni per ogni attività, in modo da rilevare impostazioni non corrette o non appropriate non appena vengono specificate, anziché trovare tutti gli errori solo in fase di esecuzione.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. Scopo della convalida è determinare se l'attività contiene impostazioni o connessioni non valide che ne impediranno la corretta esecuzione.The purpose of validation is to determine whether the task contains invalid settings or connections that will prevent it from running successfully. In questo modo è possibile assicurarsi che il pacchetto contenga attività che con buone probabilità verranno eseguite al primo tentativo.This makes sure that the package contains tasks that have a good chance of running on their first run.

È possibile implementare la convalida utilizzando il convalida metodo nel codice personalizzato.You can implement validation by using the Validate method in custom code. Il motore di runtime convalida un'attività chiamando il convalida metodo sull'attività.The run-time engine validates a task by calling the Validate method on the task. È responsabilità dello sviluppatore dell'attività definire i criteri che determinano l'esito positivo o negativo della convalida dell'attività e notificare al motore di runtime il risultato di questa valutazione.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.

Classe di base astratta TaskTask Abstract Base Class

Il Task fornisce la classe base astratta di convalida metodo che ogni attività esegue l'override per definire i criteri della convalida.The Task abstract base class provides the Validate method that each task overrides to define its validation criteria. Il SSISSSIS finestra di progettazione chiama automaticamente il convalida metodo più volte durante la progettazione del pacchetto e fornisce indicazioni visive per l'utente quando si verificano avvisi o errori per identificare i problemi con la configurazione dell'attività.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. Le attività forniscono i risultati della convalida restituendo un valore dall'enumerazione DTSExecResult e generando eventi di avviso e di errore.Tasks provide validation results by returning a value from the DTSExecResult enumeration, and by raising warning and error events. Questi eventi contengono informazioni visualizzate all'utente in Progettazione SSISSSIS.These events contain information that is displayed to the user in SSISSSIS Designer.

Di seguito sono riportati alcuni esempi di convalida:Some examples for validation follow:

  • Una gestione connessione convalida il nome di file specifico.A connection manager validates the specific file name.

  • Una gestione connessione convalida che l'input è del tipo previsto, ad esempio un file XML.A connection manager validates that the type of input is the expected type, such as an XML file.

  • Un'attività che prevede input di database verifica che non è in grado di ricevere dati da una connessione non di database.A task that expects database input verifies that it cannot receive data from a non-database connection.

  • Un'attività garantisce che nessuna delle proprie proprietà sia in conflitto con altre proprietà impostate per la stessa attività.A task guarantees that none of its properties contradicts other properties set on the same task.

  • Un'attività garantisce che tutte le risorse richieste utilizzate dall'attività in fase di esecuzione siano disponibili.A task guarantees that all required resources used by the task at execution time are available.

    Le prestazioni sono un aspetto da considerare quando si determinano gli elementi da convalidare.Performance is something to consider in determining what is validated and what is not. Ad esempio, l'input di un'attività potrebbe essere una connessione su una rete caratterizzata da una larghezza di banda insufficiente o da un traffico elevato.For example, the input to a task might be a connection over a network that has low bandwidth or heavy traffic. L'elaborazione della convalida può richiedere diversi secondi se si decide di verificare che la risorsa sia disponibile.The validation may take several seconds to process if you decide to validate that the resource is available. Un'altra convalida può generare un round trip a un server con un carico elevato, quindi la routine di convalida può essere lenta.Another validation may cause a round-trip to a server that is in high demand, and the validation routine might be slow. Anche se è possibile convalidare molte proprietà e impostazioni, questa operazione non è sempre necessaria.Although there are many properties and settings that can be validated, not everything should be validated.

  • Il codice di convalida metodo viene chiamato anche dal TaskHost prima dell'esecuzione dell'attività e il TaskHost Annulla l'esecuzione se la convalida non riesce.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.

Considerazioni sull'interfaccia utente durante la convalidaUser Interface Considerations during Validation

Il Task include un IDTSComponentEvents interfaccia come parametro per il convalida metodo.The Task includes an IDTSComponentEvents interface as a parameter to the Validate method. L'interfaccia IDTSComponentEvents contiene i metodi chiamati dall'attività per generare eventi nel motore di runtime.The IDTSComponentEvents interface contains the methods that are called by the task in order to raise events to the run-time engine. I metodi FireWarning e FireError vengono chiamati quando si verifica una condizione di avviso o di errore durante la convalida.The FireWarning and FireError methods are called when a warning or error condition occurs during validation. Entrambi i metodi di avviso richiedono gli stessi parametri, che includono un codice di errore, un componente di origine, una descrizione, un file della Guida e informazioni di contesto della Guida.Both warning methods require the same parameters, which include an error code, source component, description, Help file, and Help context information. Progettazione SSISSSIS utilizza queste informazioni per visualizzare indicatori visivi nell'area di progettazione.The SSISSSIS Designer uses this information to display visual cues on the design surface. Gli indicatori visivi forniti dalla finestra di progettazione includono l'icona di un punto esclamativo visualizzata accanto all'attività nell'area di progettazione.The visual cues that are provided by the designer include an exclamation icon that appears next to the task on the designer surface. Tale icona indica all'utente che l'attività richiede procedure aggiuntive di configurazione prima che l'esecuzione possa continuare.This visual cue signals to the user that the task requires additional configuration before execution can continue.

L'icona del punto esclamativo visualizza inoltre una descrizione comando contenente un messaggio di errore.The exclamation icon also displays a ToolTip that contains an error message. Il messaggio di errore viene fornito dall'attività nel parametro di descrizione dell'evento.The error message is provided by the task in the description parameter of the event. I messaggi di errore vengono visualizzati anche nella elenco attività riquadro di SQL Server Data Tools (SSDT)SQL Server Data Tools (SSDT), garantendo all'utente una posizione centrale per la visualizzazione di tutti gli errori di convalida.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.

Esempio di convalidaValidation Example

Esempio di codice seguente viene illustrata un'attività con un UserName proprietà.The following code example shows a task with a UserName property. Questa proprietà è stata specificata come richiesto per l'esito positivo della convalida.This property has been specified as required for validation to succeed. Se la proprietà non viene impostata, l'attività genera un errore e restituisce Failure dall'enumerazione DTSExecResult.If the property is not set, the task posts an error, and returns Failure from the DTSExecResult enumeration. Il convalida metodo viene eseguito il wrapping in un blocco try/catch e convalida non riesce se si verifica un'eccezione.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  

Persistenza dell'attivitàPersisting the Task

In genere non è necessario implementare la persistenza personalizzata per un'attività.Ordinarily you do not have to implement custom persistence for a task. La persistenza personalizzata è richiesta solo quando le proprietà di un oggetto utilizzano tipi di dati complessi.Custom persistence is required only when the properties of an object use complex data types. Per ulteriori informazioni, vedere lo sviluppo di oggetti personalizzati per Integration Services.For more information, see Developing Custom Objects for Integration Services.

Esecuzione dell'attivitàExecuting the Task

In questa sezione viene descritto come utilizzare il Execute metodo ereditato e sottoposto a override dalle attività.This section describes how to use the Execute method that is inherited and overridden by tasks. Vengono inoltre illustrate varie modalità con cui fornire informazioni sui risultati dell'esecuzione dell'attività.This section also explains various ways of providing information about the results of task execution.

Metodo ExecuteExecute Method

Quando l'esecuzione di attività che sono contenute in un pacchetto di Integration ServicesIntegration Services Common Language runtime chiama i relativi Execute metodo.Tasks that are contained in a package run when the Integration ServicesIntegration Services runtime calls their Execute method. Attività implementano la logica di business e le funzionalità in questo metodo e fornire i risultati dell'esecuzione inviando messaggi, restituendo un valore di DTSExecResult enumerazione e l'override della proprietà ottenere del ExecutionValue proprietà.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.

La classe di base Task fornisce un'implementazione predefinita del metodo Execute.The Task base class provides a default implementation of the Execute method. Le attività personalizzate eseguono l'override di questo metodo per definire le funzionalità di runtime.The custom tasks override this method to define their run-time functionality. L'oggetto TaskHost esegue il wrapping dell'attività, isolandola dal motore di runtime e dagli altri oggetti nel pacchetto.The TaskHost object wraps the task, isolating it from the run-time engine and the other objects in the package. A causa di questo isolamento, l'ordine di esecuzione dell'attività è indipendente dalla relativa posizione nel pacchetto e l'attività viene eseguita solo quando viene chiamata dal runtime.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. Questa architettura consente di evitare i problemi che possono verificarsi quando le attività modificano il pacchetto durante l'esecuzione.This architecture prevents problems that can occur when tasks modify the package during execution. L'attività dispone di accesso agli altri oggetti del pacchetto solo tramite gli oggetti forniti come parametri nel metodo 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. Questi parametri consentono alle attività di generare eventi, scrivere voci nel log eventi, accedere alla raccolta di variabili e integrare le connessioni a origini dati nelle transazioni, mantenendo allo stesso tempo l'isolamento necessario per garantire la stabilità e l'affidabilità del pacchetto.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.

Nella tabella seguente sono riportati i parametri forniti all'attività nel metodo Execute.The following table lists the parameters provided to the task in the Execute method.

ParametroParameter DescriptionDescription
Connections Contiene una raccolta di oggetti ConnectionManager disponibili per l'attività.Contains a collection of ConnectionManager objects available to the task.
VariableDispenser Contiene le variabili disponibili per l'attività.Contains the variables available to the task. Le attività utilizzano le variabili tramite VariableDispenser, non direttamente.The tasks use variables through the VariableDispenser; the tasks do not use variables directly. VariableDispenser blocca e sblocca le variabili e impedisce il verificarsi di deadlock o sovrascritture.The variable dispenser locks and unlocks variables, and prevents deadlocks or overwrites.
IDTSComponentEvents Contiene i metodi chiamati dall'attività per generare eventi nel motore di runtime.Contains the methods called by the task to raise events to the run-time engine.
IDTSLogging Contiene i metodi e le proprietà utilizzati dall'attività per scrivere voci nel registro eventi.Contains methods and properties used by the task to write entries to the event log.
OggettoObject Contiene l'oggetto transazione di cui fa parte il contenitore, se presente.Contains the transaction object that the container is a part of, if any. Questo valore viene passato come parametro al metodo AcquireConnection di un oggetto ConnectionManager.This value is passed as a parameter to the AcquireConnection method of a ConnectionManager object.

Feedback dell'esecuzioneProviding Execution Feedback

Attività includono il codice in try/catch blocchi per evitare eccezioni vengano generati per il motore di run-time.Tasks wrap their code in try/catch blocks to prevent exceptions from being raised to the run-time engine. In questo modo l'esecuzione del pacchetto viene completata senza arresti imprevisti.This ensures that the package finishes execution and does not stop unexpectedly. Tuttavia, il motore di runtime prevede altri meccanismi per la gestione delle condizioni di errore che possono verificarsi durante l'esecuzione di un'attività,However, the run-time engine provides other mechanisms for handling error conditions that can occur during the execution of a task. tra cui l'invio di messaggi di errore e di avviso, la restituzione di un valore dalla struttura DTSExecResult, l'invio di messaggi, la restituzione del valore DTSExecResult e la diffusione di informazioni sui risultati dell'esecuzione dell'attività tramite la proprietà 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.

L'interfaccia IDTSComponentEvents contiene i metodi FireWarning e FireError, che possono essere chiamati dall'attività per inviare messaggi di errore e di avviso al motore di runtime.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. Entrambi i metodi richiedono parametri quali il codice di errore, il componente di origine, il file della Guida e informazioni di contesto della Guida.Both methods require parameters such as the error code, source component, description, Help file, and help context information. A seconda della configurazione dell'attività, il runtime risponde a questi messaggi generando eventi e punti di interruzione oppure scrivendo informazioni nel registro eventi.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 fornisce anche la proprietà ExecutionValue, che può essere utilizzata per fornire informazioni aggiuntive sui risultati dell'esecuzione.The TaskHost also provides the ExecutionValue property that can be used to provide additional information about the results of execution. Ad esempio, se un'attività Elimina le righe da una tabella come parte del relativo Execute (metodo), potrebbe restituire il numero di righe eliminate come valore della ExecutionValue proprietà.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. Inoltre, TaskHost fornisce la proprietà ExecValueVariable.In addition, the TaskHost provides the ExecValueVariable property. Questa proprietà consente all'utente di eseguire il mapping dell'oggettoExecutionValue restituito dall'attività con qualsiasi variabile visibile all'attività.This property lets the user map the ExecutionValue returned from the task to any variable visible to the task. La variabile specificata può quindi essere utilizzata per stabilire vincoli di precedenza tra attività.The specified variable can then be used to establish precedence constraints between tasks.

Esempio di esecuzioneExecution Example

Esempio di codice seguente viene illustrata un'implementazione del Execute (metodo) e viene illustrato un override ExecutionValue proprietà.The following code example demonstrates an implementation of the Execute method, and shows an overridden ExecutionValue property. L'attività Elimina il file specificato da di fileName proprietà dell'attività.The task deletes the file that is specified by the fileName property of the task. L'attività Invia un avviso se il file non esiste o se il fileName proprietà è una stringa vuota.The task posts a warning if the file does not exist, or if the fileName property is an empty string. L'attività restituisce un booleano valore il ExecutionValue proprietà per indicare se il file è stato eliminato.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  

Vedere ancheSee Also

Creazione di un'attività personalizzata Creating a Custom Task
La codifica di un'attività personalizzata Coding a Custom Task
Sviluppo di un'interfaccia utente per un'attività personalizzataDeveloping a User Interface for a Custom Task