Mengodekan Tugas Kustom

Artikel
05/23/2023

Berlaku untuk: Integration Runtime SSIS SQL Server di Azure Data Factory

Setelah Anda membuat kelas yang mewarisi dari kelas dasar Microsoft.SqlServer.Dts.Runtime.Task , dan menerapkan DtsTaskAttribute atribut ke kelas , Anda harus mengambil alih implementasi properti dan metode kelas dasar untuk menyediakan fungsionalitas kustom Anda.

Mengonfigurasi Tugas

Memvalidasi Tugas

Saat merancang paket Layanan Integrasi, Anda dapat menggunakan validasi untuk memverifikasi pengaturan pada setiap tugas, sehingga Anda dapat menangkap pengaturan yang salah atau tidak pantas segera setelah diatur, alih-alih menemukan semua kesalahan pada run-time saja. Tujuan validasi adalah untuk menentukan apakah tugas berisi pengaturan atau koneksi yang tidak valid yang akan mencegahnya berjalan dengan sukses. Ini memastikan bahwa paket berisi tugas yang memiliki peluang baik untuk berjalan pada eksekusi pertama mereka.

Anda dapat menerapkan validasi dengan menggunakan metode Validasi dalam kode kustom. Mesin run-time memvalidasi tugas dengan memanggil metode Validasi pada tugas. Pengembang tugas bertanggung jawab untuk menentukan kriteria yang memberi Anda validasi tugas yang berhasil atau gagal, dan untuk memberi tahu mesin run-time hasil evaluasi ini.

Kelas Dasar Abstrak Tugas

Kelas dasar abstrak Microsoft.SqlServer.Dts.Runtime.Task menyediakan metode Validasi yang diambil alih setiap tugas untuk menentukan kriteria validasinya. Perancang SSIS secara otomatis memanggil metode Validasi beberapa kali selama desain paket, dan memberikan iseng visual kepada pengguna ketika peringatan atau kesalahan terjadi untuk membantu mengidentifikasi masalah dengan konfigurasi tugas. Tugas memberikan hasil validasi dengan mengembalikan nilai dari DTSExecResult enumerasi, dan dengan menaikkan peristiwa peringatan dan kesalahan. Peristiwa ini berisi informasi yang ditampilkan kepada pengguna di SSIS Designer.

Beberapa contoh untuk validasi berikut:

Manajer koneksi memvalidasi nama file tertentu.
Manajer koneksi memvalidasi bahwa jenis input adalah jenis yang diharapkan, seperti file XML.
Tugas yang mengharapkan input database memverifikasi bahwa ia tidak dapat menerima data dari koneksi non-database.
Tugas menjamin bahwa tidak ada propertinya yang bertentangan dengan properti lain yang ditetapkan pada tugas yang sama.
Tugas menjamin bahwa semua sumber daya yang diperlukan yang digunakan oleh tugas pada waktu eksekusi tersedia.

Performa adalah sesuatu yang perlu dipertimbangkan dalam menentukan apa yang divalidasi dan apa yang tidak. Misalnya, input ke tugas mungkin merupakan koneksi melalui jaringan yang memiliki bandwidth rendah atau lalu lintas berat. Validasi mungkin membutuhkan waktu beberapa detik untuk diproses jika Anda memutuskan untuk memvalidasi bahwa sumber daya tersedia. Validasi lain dapat menyebabkan perjalanan pulang pergi ke server yang diminati tinggi, dan rutinitas validasi mungkin lambat. Meskipun ada banyak properti dan pengaturan yang dapat divalidasi, tidak semuanya harus divalidasi.

Kode dalam metode Validasi juga dipanggil oleh TaskHost sebelum tugas dijalankan, dan TaskHost membatalkan eksekusi jika validasi gagal.

Pertimbangan Antarmuka Pengguna selama Validasi

Microsoft.SqlServer.Dts.Runtime.Task menyertakan IDTSComponentEvents antarmuka sebagai parameter untuk metode Validasi. Antarmuka IDTSComponentEvents berisi metode yang dipanggil oleh tugas untuk menaikkan peristiwa ke mesin run-time. Metode FireWarning dan FireError dipanggil ketika kondisi peringatan atau kesalahan terjadi selama validasi. Kedua metode peringatan memerlukan parameter yang sama, yang mencakup kode kesalahan, komponen sumber, deskripsi, file Bantuan, dan informasi konteks Bantuan. Perancang SSIS menggunakan informasi ini untuk menampilkan iseng visual pada permukaan desain. Iseng visual yang disediakan oleh perancang menyertakan ikon seru yang muncul di samping tugas di permukaan perancang. Isyarat visual ini memberi sinyal kepada pengguna bahwa tugas memerlukan konfigurasi tambahan sebelum eksekusi dapat dilanjutkan.

Ikon tanda seru juga menampilkan TipsAlat yang berisi pesan kesalahan. Pesan kesalahan disediakan oleh tugas dalam parameter deskripsi peristiwa. Pesan kesalahan juga ditampilkan di panel Daftar Tugas SQL Server Data Tools (SSDT), memberi pengguna lokasi terpusat untuk melihat semua kesalahan validasi.

Contoh Validasi

Contoh kode berikut menunjukkan tugas dengan properti UserName . Properti ini telah ditentukan sebagaimana diperlukan agar validasi berhasil. Jika properti tidak diatur, tugas memposting kesalahan, dan kembali Failure dari DTSExecResult enumerasi. Metode Validasi dibungkus dalam blok coba/tangkap, dan gagal validasi jika terjadi pengecualian.

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

Mempertahankan Tugas

Biasanya Anda tidak perlu menerapkan persistensi kustom untuk tugas. Persistensi kustom hanya diperlukan saat properti objek menggunakan jenis data yang kompleks. Untuk informasi selengkapnya, lihat Mengembangkan Objek Kustom untuk Layanan Integrasi.

Menjalankan Tugas

Bagian ini menjelaskan cara menggunakan metode Execute yang diwariskan dan ditimpa oleh tugas. Bagian ini juga menjelaskan berbagai cara memberikan informasi tentang hasil eksekusi tugas.

Metode Eksekusi

Tugas yang terkandung dalam paket berjalan saat runtime Layanan Integrasi memanggil metode Jalankan . Tugas mengimplementasikan logika dan fungsionalitas bisnis inti mereka dalam metode ini, dan memberikan hasil eksekusi dengan memposting pesan, mengembalikan nilai dari DTSExecResult enumerasi, dan mengambil alih properti dapatkan dari properti ExecutionValue .

Kelas dasar Microsoft.SqlServer.Dts.Runtime.Task menyediakan implementasi Execute default metode . Tugas kustom mengambil alih metode ini untuk menentukan fungsi run-time mereka. Objek TaskHost membungkus tugas, mengisolasinya dari mesin run-time dan objek lain dalam paket. Karena isolasi ini, tugas tidak menyadari lokasinya dalam paket sehubungan dengan urutan eksekusinya, dan hanya berjalan ketika dipanggil oleh runtime. Arsitektur ini mencegah masalah yang dapat terjadi ketika tugas memodifikasi paket selama eksekusi. Tugas ini disediakan akses ke objek lain dalam paket hanya melalui objek yang disediakan untuk itu sebagai parameter dalam Execute metode . Parameter ini memungkinkan tugas menaikkan peristiwa, menulis entri ke log peristiwa, mengakses pengumpulan variabel, dan mendaftarkan koneksi ke sumber data dalam transaksi, sambil tetap mempertahankan isolasi yang diperlukan untuk menjamin stabilitas dan keandalan paket.

Tabel berikut mencantumkan parameter yang disediakan untuk tugas dalam Execute metode .

Parameter	Deskripsi
Connections	Berisi kumpulan ConnectionManager objek yang tersedia untuk tugas.
VariableDispenser	Berisi variabel yang tersedia untuk tugas. Tugas menggunakan variabel melalui VariableDispenser; tugas tidak menggunakan variabel secara langsung. Variabel dispenser mengunci dan membuka kunci variabel, dan mencegah kebuntuan atau penimpaan.
IDTSComponentEvents	Berisi metode yang dipanggil oleh tugas untuk menaikkan peristiwa ke mesin run-time.
IDTSLogging	Berisi metode dan properti yang digunakan oleh tugas untuk menulis entri ke log peristiwa.
Object	Berisi objek transaksi yang merupakan bagian dari kontainer, jika ada. Nilai ini diteruskan sebagai parameter ke AcquireConnection metode ConnectionManager objek .

Memberikan Umpan Balik Eksekusi

Tugas membungkus kode mereka dalam blok try/catch untuk mencegah pengecualian dinaikkan ke mesin run-time. Ini memastikan bahwa paket menyelesaikan eksekusi dan tidak berhenti secara tak terduga. Namun, mesin run-time menyediakan mekanisme lain untuk menangani kondisi kesalahan yang dapat terjadi selama pelaksanaan tugas. Ini termasuk memposting pesan kesalahan dan peringatan, mengembalikan nilai dari DTSExecResult struktur, memposting pesan, mengembalikan DTSExecResult nilai, dan mengungkapkan informasi tentang hasil eksekusi tugas melalui ExecutionValue properti .

Antarmuka IDTSComponentEvents berisi FireWarning metode dan FireError , yang dapat dipanggil oleh tugas untuk memposting pesan kesalahan dan peringatan ke mesin run-time. Kedua metode memerlukan parameter seperti kode kesalahan, komponen sumber, deskripsi, file Bantuan, dan informasi konteks bantuan. Bergantung pada konfigurasi tugas, runtime merespons pesan ini dengan menaikkan peristiwa dan titik henti, atau dengan menulis informasi ke log peristiwa.

juga TaskHost menyediakan ExecutionValue properti yang dapat digunakan untuk memberikan informasi tambahan tentang hasil eksekusi. Misalnya, jika tugas menghapus baris dari tabel sebagai bagian dari metode Jalankan , tugas mungkin mengembalikan jumlah baris yang dihapus sebagai nilai ExecutionValue properti . Selain itu, menyediakan TaskHost ExecValueVariable properti . Properti ini memungkinkan pengguna memetakan yang ExecutionValue dikembalikan dari tugas ke variabel apa pun yang terlihat oleh tugas. Variabel yang ditentukan kemudian dapat digunakan untuk menetapkan batasan prioritas antar tugas.

Contoh Eksekusi

Contoh kode berikut menunjukkan implementasi metode Execute , dan menunjukkan properti ExecutionValue yang ditimpa. Tugas menghapus file yang ditentukan oleh properti fileName tugas. Tugas memposting peringatan jika file tidak ada, atau jika properti fileName adalah string kosong. Tugas mengembalikan nilai Boolean di ExecutionValue properti untuk menunjukkan apakah file telah dihapus.

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

Lihat juga

Membuat Tugas Kustom
Mengodekan Tugas Kustom
Mengembangkan Antarmuka Pengguna untuk Tugas Kustom

Bagikan melalui