Membangun, Menyebarkan, dan Menelusuri Kesalahan Objek Kustom

Artikel
05/23/2023

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

Setelah Anda menulis kode untuk objek kustom untuk Integration Services, Anda harus membangun assembly, menyebarkannya, dan mengintegrasikannya ke dalam SSIS Designer untuk membuatnya tersedia untuk digunakan dalam paket, dan menguji dan men-debugnya.

Langkah-langkah dalam Membangun, Menyebarkan, dan Men-debug Objek Kustom untuk Layanan Integrasi

Anda telah menulis fungsionalitas kustom untuk objek Anda. Sekarang Anda harus mengujinya dan membuatnya tersedia untuk pengguna. Langkah-langkahnya sangat mirip untuk semua jenis objek kustom yang dapat Anda buat untuk Layanan Integrasi.

Berikut adalah langkah-langkah untuk membangun, menyebarkan, dan mengujinya.

Tanda tangani assembly yang akan dihasilkan dengan nama yang kuat.
Bangun assembly.
Sebarkan assembly dengan memindahkan atau menyalinnya ke folder Integration Services yang sesuai.
Instal assembly di cache perakitan global (GAC).

Objek secara otomatis ditambahkan ke Kotak Alat.
Memecahkan masalah penyebaran, jika perlu.
Uji dan debug kode Anda.

Anda sekarang dapat menggunakan SSIS Designer di SQL Server Data Tools (SSDT) untuk membuat, memelihara, dan menjalankan paket yang menargetkan versi SQL Server yang berbeda. Untuk informasi selengkapnya tentang dampak peningkatan ini pada ekstensi kustom Anda, lihat Mendapatkan ekstensi kustom SSIS Anda agar didukung oleh dukungan multi-versi SSDT 2015 untuk SQL Server 2016

Menandatangani Assembly

Ketika assembly dimaksudkan untuk dibagikan, assembly harus diinstal di cache assembly global. Setelah assembly ditambahkan ke cache assembly global, assembly dapat digunakan oleh aplikasi seperti SQL Server Data Tools (SSDT). Persyaratan cache assembly global adalah bahwa assembly harus ditandatangani dengan nama yang kuat, yang menjamin bahwa assembly unik secara global. Rakitan bernama kuat memiliki nama yang sepenuhnya memenuhi syarat yang mencakup nama, budaya, kunci publik, dan nomor versi assembly. Runtime menggunakan informasi ini untuk menemukan assembly dan membedakannya dari rakitan lain dengan nama yang sama.

Untuk menandatangani rakitan dengan nama yang kuat, Anda harus terlebih dahulu memiliki atau membuat pasangan kunci publik/privat. Pasangan kunci kriptografi publik dan privat ini digunakan pada waktu build untuk membuat rakitan bernama yang kuat.

Untuk informasi selengkapnya tentang nama yang kuat dan pada langkah-langkah yang harus Anda ikutiuntuk menandatangani assembly, lihat topik berikut dalam dokumentasi SDK .NET Framework:

Rakitan Strong-Named
Membuat Pasangan Kunci
Menandatangani Assembly dengan Nama Yang Kuat

Anda dapat dengan mudah menandatangani assembly Anda dengan nama yang kuat di Visual Studio pada waktu build. Dalam kotak dialog Properti Proyek , pilih tab Penandatanganan . Pilih opsi untuk Menandatangani rakitan lalu berikan jalur file kunci (.snk).

Membangun Assembly

Setelah menandatangani proyek, Anda harus membangun atau membangun kembali proyek atau solusi dengan menggunakan perintah yang tersedia pada menu Build SQL Server Data Tools. Solusi Anda mungkin berisi proyek terpisah untuk antarmuka pengguna kustom, yang juga harus ditandatangani dengan nama yang kuat, dan dapat dibangun secara bersamaan.

Metode yang paling nyaman untuk melakukan dua langkah berikutnya dalam menyebarkan assembly dan menginstalnya di cache perakitan global-adalah dengan membuat skrip langkah-langkah ini sebagai peristiwa pasca-build di Visual Studio. Peristiwa build tersedia dari halaman Kompilasi Properti Proyek untuk proyek Visual Basic, dan dari halaman Peristiwa Build untuk proyek C#. Jalur lengkap diperlukan untuk utilitas prompt perintah seperti gacutil.exe. Tanda kutip diperlukan baik di sekitar jalur yang berisi spasi dan di sekitar makro seperti $(TargetPath) yang meluas ke jalur yang berisi spasi.

Berikut adalah contoh baris perintah peristiwa pasca-build untuk penyedia log kustom:

"C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\bin\NETFX 4.0 Tools\gacutil.exe" -u $(TargetName)  
"C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\bin\NETFX 4.0 Tools\gacutil.exe" -i $(TargetFileName)  
copy $(TargetFileName) "C:\Program Files\Microsoft SQL Server\130\DTS\LogProviders "

Menyebarkan Assembly

Perancang SSIS menemukan objek kustom yang tersedia untuk digunakan dalam paket dengan menghitung file yang ditemukan dalam serangkaian folder yang dibuat saat SQL Server Integration Services diinstal. Ketika pengaturan penginstalan SQL Server default digunakan, kumpulan folder ini terletak di bawah C:\Program Files\Microsoft SQL Server\130\DTS. Namun jika Anda membuat program penyetelan untuk objek kustom, Anda harus memeriksa nilai kunci registri HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SQL Server\130\SSIS\Setup\DtsPath untuk memverifikasi lokasi folder ini.

Catatan

Untuk informasi tentang cara menyebarkan komponen kustom agar berfungsi dengan baik dengan dukungan multi-versi di SQL Server Data Tools, lihat Mendapatkan ekstensi kustom SSIS Anda agar didukung oleh dukungan multi-versi SSDT 2015 untuk SQL Server 2016.

Anda dapat meletakkan assembly di folder dengan dua cara:

Pindahkan atau salin rakitan yang dikompilasi ke folder yang sesuai setelah membuatnya. (Untuk kenyamanan, Anda dapat menyertakan perintah salin dalam Peristiwa Pasca-build.)
Buat rakitan langsung di folder yang sesuai.

Folder penyebaran berikut di bawah C:\Program Files\Microsoft SQL Server\130\DTS digunakan untuk berbagai jenis objek kustom:

Objek kustom	Folder penyebaran
Tugas	Tugas
Manajer sambungan	Koneksi
Penyedia log	LogProviders
Komponen aliran data	PipelineComponents

Catatan

Rakitan disalin ke folder ini untuk mendukung enumerasi tugas yang tersedia, manajer koneksi, dan sebagainya. Oleh karena itu Anda tidak perlu menyebarkan rakitan yang hanya berisi antarmuka pengguna kustom untuk objek kustom ke folder ini.

Menginstal Assembly di Singgahan Majelis Global

Untuk menginstal rakitan tugas ke dalam cache perakitan global (GAC), gunakan alat baris perintah gacutil.exe, atau seret rakitan ke %system%\assembly direktori. Untuk kenyamanan, Anda juga dapat menyertakan panggilan ke gacutil.exe dalam Peristiwa Pasca-build.

Perintah berikut menginstal komponen bernama MyTask.dll ke GAC dengan menggunakan gacutil.exe.

gacutil /iF MyTask.dll

Anda harus menutup dan membuka kembali SSIS Designer setelah menginstal versi baru objek kustom Anda. Jika Anda telah menginstal versi sebelumnya dari objek kustom Anda di cache perakitan global, Anda harus menghapusnya sebelum menginstal versi baru. Untuk menghapus instalasi assembly, jalankan gacutil.exe dan tentukan nama assembly dengan /u opsi .

Untuk informasi selengkapnya tentang cache assembly global, lihat Global Assembly Cache Tool (Gactutil.exe) di .NET Framework Tools.

Pemecahan Masalah Penyebaran

Jika objek kustom Anda muncul di Kotak Alat atau daftar objek yang tersedia, tetapi Anda tidak dapat menambahkannya ke paket, cobalah hal berikut:

Lihat di cache perakitan global untuk beberapa versi komponen Anda. Jika ada beberapa versi komponen dalam cache perakitan global, perancang mungkin tidak dapat memuat komponen Anda. Hapus semua instans assembly dari cache assembly global, dan tambahkan kembali assembly.
Pastikan bahwa hanya satu instans rakitan yang ada di folder penyebaran.
Refresh Kotak Alat.
Lampirkan Visual Studio ke devenv.exe dan atur titik henti untuk menelusuri kode inisialisasi Anda untuk memastikan bahwa tidak ada pengecualian yang terjadi.

Menguji dan Men-debug Kode Anda

Pendekatan paling sederhana untuk men-debug metode run-time objek kustom adalah memulai dtexec.exe dari Visual Studio setelah membangun objek kustom Anda dan menjalankan paket yang menggunakan komponen.

Jika Anda ingin men-debug metode waktu desain komponen, seperti metode Validasi , buka paket yang menggunakan komponen dalam instans kedua Visual Studio, dan lampirkan ke proses devenv.exe .

Jika Anda juga ingin men-debug metode run-time komponen saat paket terbuka dan berjalan di perancang SSIS, Anda harus memaksa jeda dalam eksekusi paket sehingga Anda juga dapat melampirkan ke proses DtsDebugHost.exe .

Untuk men-debug metode run-time objek dengan melampirkan ke dtexec.exe

Tanda tangani dan bangun proyek Anda dalam konfigurasi Debug, sebarkan, dan instal di cache perakitan global seperti yang dijelaskan dalam topik ini.
Pada tab DebugProperti Proyek, pilih Mulai program eksternal sebagai Tindakan Mulai, dan temukan dtexec.exe, yang diinstal secara default di C:\Program Files\Microsoft SQL Server\130\DTS\Binn.
Dalam kotak teks Opsi baris perintah , di bawah Opsi Mulai, masukkan argumen baris perintah yang diperlukan untuk menjalankan paket yang menggunakan komponen Anda. Seringkali argumen baris perintah akan terdiri dari sakelar /F[ILE] diikuti dengan jalur dan nama file file .dtsx. Untuk informasi selengkapnya, lihat Utilitas dtexec.
Atur titik henti dalam kode sumber jika sesuai dalam metode run-time komponen Anda.
Jalankan proyek Anda.

Untuk men-debug metode waktu desain objek kustom dengan melampirkan ke SQL Server Data Tools

Tanda tangani dan bangun proyek Anda dalam konfigurasi Debug, sebarkan, dan instal di cache perakitan global seperti yang dijelaskan dalam topik ini.
Atur titik henti dalam kode sumber jika sesuai dalam metode waktu desain objek kustom Anda.
Buka instans kedua Visual Studio dan muat proyek Integration Services yang berisi paket yang menggunakan objek kustom.
Dari instans pertama Visual Studio, lampirkan ke instans kedua devenv.exe tempat paket dimuat dengan memilih Lampirkan ke Proses dari menu Debug instans pertama.
Jalankan paket dari instans kedua Visual Studio.

Untuk men-debug metode run-time objek kustom dengan melampirkan ke SQL Server Data Tools

Setelah Anda menyelesaikan langkah-langkah yang tercantum dalam prosedur sebelumnya, paksa jeda dalam eksekusi paket Anda sehingga Anda dapat melampirkan ke DtsDebugHost.exe. Anda dapat memaksa jeda ini dengan menambahkan titik henti ke peristiwa OnPreExecute , atau dengan menambahkan tugas Skrip ke proyek Anda dan memasukkan skrip yang menampilkan kotak pesan modal.
Jalankan paket. Saat jeda terjadi, beralihlah ke instans Visual Studio tempat proyek kode Anda terbuka, dan pilih Lampirkan ke Proses dari menu Debug . Pastikan untuk melampirkan ke instans DtsDebugHost.exe yang tercantum sebagai Terkelola, x86 di kolom Jenis , bukan ke instans yang tercantum sebagai x86 saja.
Kembali ke paket yang dijeda dan lanjutkan melewati titik henti, atau klik OK untuk menutup kotak pesan yang dimunculkan oleh tugas Skrip, dan lanjutkan eksekusi dan penelusuran kesalahan paket.

Lihat juga

Mengembangkan Objek Kustom untuk SSIS
Objek Kustom yang Bertahan
Alat Pemecahan Masalah untuk Pengembangan Paket

Bagikan melalui