Kódování vlastní úlohy

platí pro:SQL Server SSIS Integration Runtime ve službě Azure Data Factory

Po vytvoření třídy, která dědí ze základní třídy Microsoft.SqlServer.Dts.Runtime.Task a použitý DtsTaskAttribute atribut na třídu, musíte přepsat implementaci vlastností a metod základní třídy, aby poskytovala vlastní funkce.

Konfigurace úlohy

Ověření úlohy

Při navrhování balíčku integrační služby můžete pomocí ověřování ověřit nastavení u jednotlivých úloh, abyste mohli zachytit nesprávná nebo nevhodná nastavení hned po jejich nastavení, a ne najít všechny chyby pouze za běhu. Účelem ověření je určit, jestli úloha obsahuje neplatná nastavení nebo připojení, která brání jeho úspěšnému spuštění. Tím se zajistí, že balíček obsahuje úlohy, které mají dobrou šanci na spuštění při prvním spuštění.

Ověřování můžete implementovat pomocí metody Validate ve vlastním kódu. Modul runtime ověří úlohu voláním metody Validate pro úlohu. Vývojář úloh zodpovídá za definování kritérií, která poskytují úspěšné nebo neúspěšné ověření úlohy, a informovat modul runtime o výsledku tohoto vyhodnocení.

Abstraktní základní třída úkolu

Abstraktní základní třída Microsoft.SqlServer.Dts.Runtime.Task poskytuje metodu Validate , kterou každá úloha přepíše, aby definovala svá ověřovací kritéria. Návrhář SSIS automaticky volá metodu Validate několikrát během návrhu balíčku a poskytuje uživateli vizuální upozornění, když dojde k upozorněním nebo chybám, které pomáhají identifikovat problémy s konfigurací úlohy. Úkoly poskytují výsledky ověření vrácením hodnoty z výčtu DTSExecResult a vyvoláním upozornění a chybových událostí. Tyto události obsahují informace, které se uživateli zobrazí v nástroji SSIS Designer.

Následují příklady ověření:

Správce připojení ověří konkrétní název souboru.
Správce připojení ověří, že typ vstupu je očekávaný typ, například soubor XML.
Úloha, která očekává, že vstup databáze ověří, že nemůže přijímat data z ne database připojení.
Úkol zaručuje, že žádná z jeho vlastností není v rozporu s jinými vlastnostmi nastavenými na stejný úkol.
Úloha zaručuje, že jsou k dispozici všechny požadované prostředky používané úlohou v době provádění.

Výkon je něco, co je potřeba zvážit při určování toho, co je ověřeno a co není. Vstupem k úkolu může být například připojení přes síť, která má malou šířku pásma nebo velký provoz. Ověření může trvat několik sekund, než se rozhodnete ověřit, že je prostředek dostupný. Jiné ověření může způsobit odezvu na server s vysokou poptávkou a ověřovací rutina může být pomalá. I když existuje mnoho vlastností a nastavení, která je možné ověřit, ne vše by mělo být ověřeno.

Kód v metodě Validate je volána TaskHost také před spuštěním úlohy a TaskHost zruší provádění v případě selhání ověření.

Důležité informace o uživatelském rozhraní během ověřování

Microsoft.SqlServer.Dts.Runtime.Task obsahuje IDTSComponentEvents rozhraní jako parametr metody Validate. Rozhraní IDTSComponentEvents obsahuje metody volané úlohou za účelem vyvolání událostí do modulu runtime. Metody FireWarning a FireError metody se volají, když během ověřování dojde k upozornění nebo chybovému stavu. Obě metody upozornění vyžadují stejné parametry, mezi které patří kód chyby, zdrojová komponenta, popis, soubor nápovědy a kontextové informace nápovědy. Návrhář SSIS používá tyto informace k zobrazení vizuálních upozornění na návrhové ploše. Vizuální upozornění poskytovaná návrhářem obsahují vykřičník, který se zobrazí vedle úkolu na ploše návrháře. Tento vizuální signál uživateli signalizuje, že úloha před spuštěním vyžaduje další konfiguraci.

Ikona vykřičníku zobrazuje také popis, který obsahuje chybovou zprávu. Chybová zpráva je poskytována úkolem v parametru popisu události. Chybové zprávy se také zobrazují v podokně Seznam úloh v nástrojích SQL Server Data Tools (SSDT), které uživateli poskytují centrální umístění pro zobrazení všech chyb ověření.

Příklad ověření

Následující příklad kódu ukazuje úkol s UserName vlastnost. Tato vlastnost byla zadána podle potřeby pro úspěšné ověření. Pokud vlastnost není nastavena, úloha publikuje chybu a vrátí Failure se z výčtu DTSExecResult . Metoda Validate je zabalena do bloku try/catch a selže ověření, pokud dojde k výjimce.

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

Zachování úkolu

Obvykle nemusíte pro úlohu implementovat vlastní trvalost. Vlastní trvalost je vyžadována pouze v případě, že vlastnosti objektu používají komplexní datové typy. Další informace naleznete v tématu Vývoj vlastních objektů pro integrační služby.

Spuštění úlohy

Tato část popisuje, jak používat metodu Execute , která je zděděna a přepsána úkoly. Tato část také vysvětluje různé způsoby poskytování informací o výsledcích provádění úkolů.

Execute – metoda

Úlohy obsažené v balíčku se spustí, když prostředí Integration Services Runtime volá metodu Execute . Úlohy implementují v této metodě základní obchodní logiku a funkce a poskytují výsledky provádění publikováním zpráv, vrácením hodnoty z výčtu DTSExecResult a přepsáním vlastnosti getExecutionValue vlastnost.

Základní třída Microsoft.SqlServer.Dts.Runtime.Task poskytuje výchozí implementaci Execute metody. Vlastní úlohy tuto metodu přepíšou, aby definovaly jejich funkce za běhu. Objekt TaskHost zabalí úlohu, izoluje ji od modulu runtime a dalších objektů v balíčku. Z důvodu této izolace úloha neví o svém umístění v balíčku, pokud jde o jeho pořadí provádění, a spustí se pouze v případě, že je volána modulem runtime. Tato architektura zabraňuje problémům, ke kterým může dojít při úpravě balíčku během provádění úloh. Úloha je poskytována přístup k ostatním objektům v balíčku pouze prostřednictvím objektů zadaných v Execute metodě jako parametry. Tyto parametry umožňují úkolům vyvolat události, zapisovat položky do protokolu událostí, přistupovat ke kolekci proměnných a vypsat připojení ke zdrojům dat v transakcích a přitom zachovat izolaci, která je nezbytná k zajištění stability a spolehlivosti balíčku.

Následující tabulka uvádí parametry zadané pro úlohu v Execute metodě.

Parametr	Popis
Connections	Obsahuje kolekci ConnectionManager objektů dostupných pro úlohu.
VariableDispenser	Obsahuje proměnné, které jsou pro úkol k dispozici. Úkoly používají proměnné prostřednictvím variableDispenser; úkoly nepoužívají proměnné přímo. Proměnná dávkovač uzamkne a odemkne proměnné a zabrání zablokování nebo přepsání.
IDTSComponentEvents	Obsahuje metody volané úlohou pro vyvolání událostí do modulu runtime.
IDTSLogging	Obsahuje metody a vlastnosti používané úlohou k zápisu položek do protokolu událostí.
Objekt	Obsahuje objekt transakce, který kontejner je součástí, pokud existuje. Tato hodnota se předává jako parametr AcquireConnection metodě objektu ConnectionManager .

Poskytnutí zpětné vazby k provádění

Úlohy zabalí kód do bloků try/catch , aby se zabránilo vyvolání výjimek do modulu runtime. Tím se zajistí, že se balíček dokončí a neočekávaně se nezastaví. Modul runtime však poskytuje další mechanismy pro zpracování chybových podmínek, ke kterým může dojít během provádění úlohy. Patří mezi ně publikování chyb a upozornění zpráv, vrácení hodnoty ze DTSExecResult struktury, publikování zpráv, vrácení DTSExecResult hodnoty a zveřejnění informací o výsledcích provádění úkolů prostřednictvím ExecutionValue vlastnosti.

Rozhraní IDTSComponentEvents obsahuje metody FireWarning a FireError metody, které může úloha volat k publikování chybových a upozorňujících zpráv modulu za běhu. Obě metody vyžadují parametry, jako je kód chyby, zdrojová komponenta, popis, soubor nápovědy a kontextové informace nápovědy. V závislosti na konfiguraci úlohy modul runtime na tyto zprávy reaguje vyvoláním událostí a zarážek nebo zápisem informací do protokolu událostí.

Poskytuje TaskHost také ExecutionValue vlastnost, kterou lze použít k poskytnutí dalších informací o výsledcích provádění. Pokud například úkol odstraní řádky z tabulky jako součást metody Execute , může vrátit počet řádků odstraněných jako hodnota ExecutionValue vlastnosti. Kromě toho TaskHost poskytuje ExecValueVariable vlastnost. Tato vlastnost umožňuje uživateli namapovat vrácenou ExecutionValue úlohu na libovolnou proměnnou viditelnou pro úkol. Zadaná proměnná se pak dá použít k vytvoření omezení priority mezi úkoly.

Příklad spuštění

Následující příklad kódu ukazuje implementaci Execute metoda a ukazuje přepsán ExecutionValue vlastnost. Úloha odstraní soubor určený vlastností fileName úkolu. Úkol publikuje upozornění, pokud soubor neexistuje, nebo pokud je vlastnost fileName prázdný řetězec. Úloha vrátí logickou hodnotu ve ExecutionValue vlastnosti, která určuje, zda byl soubor odstraněn.

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

Viz také

Vytvoření vlastní úlohy
Kódování vlastní úlohy
Vývoj uživatelského rozhraní pro vlastní úlohu

Last updated on 2025-05-26

Sdílet prostřednictvím