Delen via

Een aangepaste taak coderen

van toepassing op:SQL Server SSIS Integration Runtime in Azure Data Factory

Nadat u een klasse hebt gemaakt die de klasse Microsoft.SqlServer.Dts.Runtime.Task base heeft overgenomen en het DtsTaskAttribute kenmerk op de klasse heeft toegepast, moet u de implementatie van de eigenschappen en methoden van de basisklasse overschrijven om uw aangepaste functionaliteit te bieden.

De taak configureren

De taak valideren

Wanneer u een Integration Services-pakket ontwerpt, kunt u validatie gebruiken om de instellingen voor elke taak te controleren, zodat u onjuiste of ongepaste instellingen kunt ondervangen zodra deze zijn ingesteld, in plaats van dat alle fouten alleen tijdens runtime worden gevonden. Het doel van validatie is om te bepalen of de taak ongeldige instellingen of verbindingen bevat waardoor deze niet kan worden uitgevoerd. Dit zorgt ervoor dat het pakket taken bevat die een goede kans hebben om te worden uitgevoerd tijdens de eerste uitvoering.

U kunt validatie implementeren met behulp van de methode Validate in aangepaste code. De runtime-engine valideert een taak door de validatiemethode voor de taak aan te roepen. Het is de verantwoordelijkheid van de taakontwikkelaar om de criteria te definiëren die u een geslaagde of mislukte taakvalidatie geven en om de runtime-engine op de hoogte te stellen van het resultaat van deze evaluatie.

Taakabstractiebasisklasse

De abstracte basisklasse Microsoft.SqlServer.Dts.Runtime.Task biedt de validatiemethode die elke taak overschrijft om de validatiecriteria te definiëren. SSIS Designer roept de methode Validate automatisch meerdere keren aan tijdens het ontwerp van het pakket en biedt visuele aanwijzingen aan de gebruiker wanneer er waarschuwingen of fouten optreden om problemen met de configuratie van de taak te helpen identificeren. Taken bieden validatieresultaten door een waarde uit de DTSExecResult opsomming te retourneren en door waarschuwings- en foutevenementen op te geven. Deze gebeurtenissen bevatten informatie die wordt weergegeven aan de gebruiker in SSIS Designer.

Enkele voorbeelden voor validatie volgen:

  • Een verbindingsbeheerder valideert de specifieke bestandsnaam.

  • Een verbindingsbeheer controleert of het type invoer het verwachte type is, zoals een XML-bestand.

  • Een taak die verwacht dat databaseinvoer controleert of deze geen gegevens van een niet-databaseverbinding kan ontvangen.

  • Een taak garandeert dat geen van de eigenschappen in strijd is met andere eigenschappen die zijn ingesteld voor dezelfde taak.

  • Een taak garandeert dat alle vereiste resources die tijdens de uitvoering door de taak worden gebruikt, beschikbaar zijn.

Prestaties zijn iets waarmee u rekening moet houden bij het bepalen wat er wordt gevalideerd en wat niet. De invoer voor een taak kan bijvoorbeeld een verbinding zijn via een netwerk met een lage bandbreedte of intensief verkeer. Het kan enkele seconden duren voordat de validatie wordt verwerkt als u besluit te valideren dat de resource beschikbaar is. Een andere validatie kan leiden tot een retour naar een server die veel vraag heeft en de validatieroutine kan traag zijn. Hoewel er veel eigenschappen en instellingen zijn die kunnen worden gevalideerd, moet niet alles worden gevalideerd.

  • De code in de validatiemethode wordt ook aangeroepen door de TaskHost voordat de taak wordt uitgevoerd en de TaskHost uitvoering wordt geannuleerd als de validatie mislukt.

Overwegingen voor de gebruikersinterface tijdens de validatie

Microsoft.SqlServer.Dts.Runtime.Task bevat een IDTSComponentEvents interface als parameter voor de validatiemethode. De IDTSComponentEvents interface bevat de methoden die door de taak worden aangeroepen om gebeurtenissen naar de runtime-engine te genereren. De FireWarning en FireError methoden worden aangeroepen wanneer er een waarschuwing of foutvoorwaarde optreedt tijdens de validatie. Voor beide waarschuwingsmethoden zijn dezelfde parameters vereist, waaronder een foutcode, broncode, beschrijving, Help-bestand en Help-contextinformatie. De SSIS Designer gebruikt deze informatie om visuele aanwijzingen weer te geven op het ontwerpoppervlak. De visuele aanwijzingen die door de ontwerper worden geleverd, bevatten een uitroepteken dat naast de taak op het ontwerpoppervlak wordt weergegeven. Deze visuele aanwijzing geeft de gebruiker aan dat voor de taak aanvullende configuratie is vereist voordat de uitvoering kan worden voortgezet.

Het uitroeptekenpictogram geeft ook een knopinfo weer die een foutbericht bevat. Het foutbericht wordt door de taak opgegeven in de beschrijvingsparameter van de gebeurtenis. Foutberichten worden ook weergegeven in het deelvenster Takenlijst van SQL Server Data Tools (SSDT), zodat de gebruiker een centrale locatie heeft voor het weergeven van alle validatiefouten.

Voorbeeld van validatie

In het volgende codevoorbeeld ziet u een taak met een eigenschap UserName . Deze eigenschap is opgegeven als vereist om de validatie te voltooien. Als de eigenschap niet is ingesteld, plaatst de taak een fout en retourneert Failure deze uit de DTSExecResult opsomming. De validatiemethode wordt verpakt in een try/catch-blok en mislukt de validatie als er een uitzondering optreedt.

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

De taak behouden

Normaal gesproken hoeft u geen aangepaste persistentie voor een taak te implementeren. Aangepaste persistentie is alleen vereist wanneer de eigenschappen van een object complexe gegevenstypen gebruiken. Zie Aangepaste objecten ontwikkelen voor Integration Services voor meer informatie.

De taak uitvoeren

In deze sectie wordt beschreven hoe u de methode Execute gebruikt die wordt overgenomen en overschreven door taken. In deze sectie worden ook verschillende manieren uitgelegd om informatie te verstrekken over de resultaten van taakuitvoering.

Methode uitvoeren

Taken die zijn opgenomen in een pakket worden uitgevoerd wanneer de Integration Services-runtime de execute-methode aanroept. Taken implementeren hun belangrijkste bedrijfslogica en functionaliteit in deze methode en bieden de resultaten van de uitvoering door berichten te posten, een waarde te retourneren uit de DTSExecResult opsomming en de eigenschap Get van de eigenschap ExecutionValue te overschrijven.

De klasse Microsoft.SqlServer.Dts.Runtime.Task base biedt een standaardimplementatie van de Execute methode. De aangepaste taken overschrijven deze methode om hun runtimefunctionaliteit te definiëren. Het TaskHost object verpakt de taak, waarbij deze wordt geïsoleerd van de runtime-engine en de andere objecten in het pakket. Vanwege deze isolatie is de taak zich niet bewust van de locatie in het pakket met betrekking tot de uitvoeringsvolgorde en wordt deze alleen uitgevoerd wanneer deze wordt aangeroepen door de runtime. Deze architectuur voorkomt problemen die kunnen optreden wanneer taken het pakket wijzigen tijdens de uitvoering. De taak krijgt alleen toegang tot de andere objecten in het pakket via de objecten die eraan zijn geleverd als parameters in de Execute methode. Met deze parameters kunnen taken gebeurtenissen genereren, vermeldingen schrijven naar het gebeurtenislogboek, toegang krijgen tot de verzameling variabelen en verbindingen inschakelen naar gegevensbronnen in transacties, terwijl de isolatie die nodig is om de stabiliteit en betrouwbaarheid van het pakket te garanderen, behouden blijft.

De volgende tabel bevat de parameters die aan de taak in de Execute methode zijn opgegeven.

Kenmerk Beschrijving
Connections Bevat een verzameling ConnectionManager objecten die beschikbaar zijn voor de taak.
VariableDispenser Bevat de variabelen die beschikbaar zijn voor de taak. De taken gebruiken variabelen via de VariableDispenser; de taken gebruiken geen variabelen rechtstreeks. De variabele dispenser vergrendelt en ontgrendelt variabelen en voorkomt impasses of overschrijven.
IDTSComponentEvents Bevat de methoden die door de taak worden aangeroepen om gebeurtenissen te genereren voor de runtime-engine.
IDTSLogging Bevat methoden en eigenschappen die door de taak worden gebruikt om vermeldingen naar het gebeurtenislogboek te schrijven.
Voorwerp Bevat het transactieobject waarvan de container deel uitmaakt, indien van toepassing. Deze waarde wordt doorgegeven als een parameter aan de AcquireConnection methode van een ConnectionManager object.

Feedback geven over uitvoering

Taken verpakken hun code in try/catch-blokken om te voorkomen dat uitzonderingen worden gegenereerd naar de runtime-engine. Dit zorgt ervoor dat het pakket de uitvoering voltooit en niet onverwacht stopt. De runtime-engine biedt echter andere mechanismen voor het afhandelen van foutvoorwaarden die kunnen optreden tijdens de uitvoering van een taak. Dit zijn onder andere het posten van fout- en waarschuwingsberichten, het retourneren van een waarde uit de DTSExecResult structuur, het posten van berichten, het retourneren van de DTSExecResult waarde en het vrijgeven van informatie over de resultaten van de uitvoering van de taak via de ExecutionValue eigenschap.

De IDTSComponentEvents interface bevat de FireWarning en FireError methoden die door de taak kunnen worden aangeroepen om foutberichten en waarschuwingsberichten te posten naar de runtime-engine. Voor beide methoden zijn parameters vereist, zoals de foutcode, het brononderdeel, de beschrijving, het Help-bestand en de help-contextinformatie. Afhankelijk van de configuratie van de taak reageert de runtime op deze berichten door gebeurtenissen en onderbrekingspunten te genereren of door informatie naar het gebeurtenislogboek te schrijven.

De TaskHost eigenschap biedt ook de ExecutionValue eigenschap die kan worden gebruikt om aanvullende informatie te geven over de resultaten van de uitvoering. Als een taak bijvoorbeeld rijen uit een tabel verwijdert als onderdeel van de methode Execute , kan het aantal rijen worden geretourneerd dat is verwijderd als de waarde van de ExecutionValue eigenschap. Daarnaast biedt de TaskHost accommodatie de ExecValueVariable eigenschap. Met deze eigenschap kan de gebruiker de ExecutionValue geretourneerde van de taak toewijzen aan elke variabele die zichtbaar is voor de taak. De opgegeven variabele kan vervolgens worden gebruikt om prioriteitsbeperkingen tussen taken vast te stellen.

Voorbeeld van uitvoering

In het volgende codevoorbeeld ziet u een implementatie van de execute-methode en ziet u een overschreven ExecutionValue-eigenschap . De taak verwijdert het bestand dat is opgegeven door de eigenschap FileName van de taak. De taak plaatst een waarschuwing als het bestand niet bestaat of als de eigenschap FileName een lege tekenreeks is. De taak retourneert een Booleaanse waarde in de ExecutionValue eigenschap om aan te geven of het bestand is verwijderd.

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

Zie ook

Een aangepaste taak maken
Een aangepaste taak coderen
Een gebruikersinterface ontwikkelen voor een aangepaste taak

  • Last updated on