Bagikan melalui

Buat paket untuk alat Package Deployer

  • Artikel

Package Deployer memungkinkan administrator untuk menyebarkan paket di instans Microsoft Dataverse. Paket Package Deployer dapat terdiri dari salah satu atau semua hal berikut:

  • Satu atau beberapa file solusi Dataverse.
  • File tetap atau file data konfigurasi yang diekspor dari Configuration Migration tool. Untuk informasi lebih lanjut tentang alat, lihat Pindahkan data konfigurasi di seluruh instans dan organisasi dengan Configuration Migration tool.
  • Kode kustom yang dapat berjalan sebelum, selama, atau setelah paket disebarkan ke instans Dataverse.
  • Konten HTML khusus paket yang dapat ditampilkan di awal dan akhir proses penyebaran. Konten ini dapat bermanfaat untuk memberikan keterangan solusi dan file yang disebarkan di paket.

Catatan

Ada jenis paket lain yang disebut paket plug-in. Paket semacam itu adalah untuk asembli dependen plug-in dan tidak memiliki relasi dengan paket Package Deployer.

Prasyarat

  • Pastikan Anda menyiapkan semua solusi dan file lainnya yang akan disertakan dalam paket.
  • Visual Studio 2019 atau lebih baru, atau Visual Studio Kode.

Ikhtisar proses

Untuk membuat Package Deployer paket, lakukan langkah-langkah berikut.

  • Membuat proyek Visual Studio atau MSBuild
  • Menambahkan solusi dan file lainnya ke proyek
  • Pembaruan file HTML yang diberikan (opsional)
  • Tentukan nilai konfigurasi untuk paket
  • Tentukan kode kustom untuk paket
  • Buat dan terapkan paket

Langkah-langkah ini dijelaskan secara rinci dalam artikel ini.

Buat proyek paket

Langkah pertama adalah membuat proyek Visual Studio atau MSBuild untuk paket. Untuk melakukannya, Anda harus memiliki salah satu dari dua ekstensi alat yang tersedia yang terinstal di komputer pengembangan. Jika menggunakan Visual Studio Code, instal Microsoft Power Platform CLI. Jika tidak, jika menggunakan Visual Studio 2019 atau yang lebih baru, instal Power Platform alat untuk Visual Studio.

Pilih tab yang sesuai di bawah ini untuk mengetahui cara membuat proyek menggunakan ekstensi alat yang diinginkan. Kedua alat output proyek dalam format yang serupa.

Jalankan perintah pac package init untuk membuat paket awal. Informasi lebih lanjut: paket pac

pac package init help
pac package init --outputDirectory DeploymentPackage

Output CLI yang dihasilkan berisi folder dan file yang ditampilkan di bawah. Nama folder "DeploymentPackage" digunakan di sini sebagai contoh.

C:.
└───DeploymentPackage
    │   DeploymentPackage.csproj
    │   PackageImportExtension.cs
    │
    └───PkgAssets
            ImportConfig.xml
            manifest.ppkg.json

Dalam proyek yang dibuat, temukan file konfigurasi ImportConfig.xml di folder PkgAssets dan file PackageImportExtension.cs. Anda akan memodifikasi file-file ini seperti yang dijelaskan nanti di artikel ini.

Tambah file paket

Setelah membuat proyek paket, Anda dapat mulai menambahkan solusi dan file lainnya ke proyek tersebut.

Bila menggunakan CLI, Anda dapat menambahkan paket eksternal, solusi, dan referensi ke proyek paket menggunakan salah satu subperintah add. Masukkan pac package help untuk melihat daftar subperintah. Tambahkan solusi ke paket kita.

> pac package add-solution help

Commands:
Usage: pac package add-solution --path [--import-order] [--skip-validation] [--publish-workflows-activate-plugins] [--overwrite-unmanaged-customizations] [--import-mode] [--missing-dependency-behavior] [--dependency-overrides]

> cd .\DeploymentPackage\
> pac package add-solution --path ..\TestSolution_1_0_0_1_managed.zip

The item was added successfully.

Konfigurasikan paket

Tentukan konfigurasi paket dengan menambahkan informasi tentang paket di file importconfig.xml yang tersedia di proyek. Lihat Referensi ImportConfig untuk contoh dan deskripsi elemen dan atribut yang valid untuk digunakan.

Tambahkan Kode kustom

Anda dapat menambahkan kode kustom yang dieksekusi sebelum, selama, dan setelah paket diimpor ke lingkungan. Untuk melakukannya, ikuti petunjuk berikut.

  1. Edit file PackageTemplate.cs (atau PackageImportExtension.cs) dalam folder root proyek.

  2. Di file C#, Anda dapat:

    1. Masukkan kode kustom untuk mengeksekusi saat paket diinisialisasi dalam definisi metode timpa InitializeCustomExtension.

      Metode ini dapat digunakan untuk memungkinkan pengguna menggunakan parameter runtime saat menjalankan sebuah paket. Sebagai pengembang, Anda dapat menambahkan dukungan untuk parameter runtime apa pun ke paket dengan menggunakan properti RuntimeSettings selama Anda memiliki kode untuk memprosesnya berdasarkan input pengguna.

      Contohnya, kode contoh berikut memungkinkan parameter runtime yang disebut SkipChecks untuk paket yang memiliki dua nilai yang mungkin: True atau false. Kode sampel memeriksa apakah pengguna telah menentukan parameter runtime apa pun saat menjalankan Package Deployer (baik menggunakan baris perintah atau PowerShell), lalu memproses informasi tersebut. Jika tidak ada parameter runtime yang ditentukan oleh pengguna saat menjalankan paket, nilai properti RuntimeSettings akan null.

      public override void InitializeCustomExtension()  
{  
// Do nothing.  

// Validate the state of the runtime settings object.  
if (RuntimeSettings != null)  
{  
PackageLog.Log(string.Format("Runtime Settings populated.  Count = {0}", RuntimeSettings.Count));  
foreach (var setting in RuntimeSettings)  
{  
PackageLog.Log(string.Format("Key={0} | Value={1}", setting.Key, setting.Value.ToString()));  
}  

// Check to see if skip checks is present.  
if ( RuntimeSettings.ContainsKey("SkipChecks") )  
{  
bool bSkipChecks = false;  
if (bool.TryParse((string)RuntimeSettings["SkipChecks"], out bSkipChecks))  
OverrideDataImportSafetyChecks = bSkipChecks;  
}  
}  
else  
PackageLog.Log("Runtime Settings not populated");  
}

      Kode ini memungkinkan administrator menggunakan baris perintah atau impor-CrmPackage cmdlet untuk menentukan apakah akan melewati pemeriksaan keamanan saat menjalankan alat Package Deployer untuk mengimpor paket. Informasi lebih lanjut: Menyebarkan paket menggunakan Package Deployer dan Windows PowerShell

    2. Masukkan kode kustom untuk dieksekusi sebelum solusi diimpor dalam definisi metode timpa PreSolutionImport untuk menentukan apakah akan mempertahankan atau menimpa penyesuaian saat memperbarui solusi yang ditentukan dalam instans Dataverse target, dan apakah akan mengaktifkan plug-in dan alur kerja secara otomatis.

    3. Gunakan definisi metode penggantian untuk RunSolutionUpgradeMigrationStep melakukan transformasi data atau peningkatan antara dua versi solusi Metode ini dipanggil hanya jika solusi yang Anda impor sudah ada di instans target Dataverse .

      Fungsi ini memperkirakan parameter berikut:

      Parameter Deskripsi
      solutionName Nama solusi
      oldVersion Nomor versi solusi lama
      newVersion Nomor versi solusi baru
      oldSolutionId GUID solusi lama.
      newSolutionId GUID solusi baru.

    4. Masukkan kode kustom untuk mengeksekusi sebelum impor solusi selesai dalam definisi timpa metode BeforeImportStage. Data sampel dan beberapa file flat untuk solusi yang ditentukan dalam file ImportConfig.xml diimpor sebelum impor solusi selesai.

    5. Ganti bahasa yang saat ini dipilih untuk impor data konfigurasi menggunakan definisi OverrideConfigurationDataFileLanguage metode pengganti. Jika ID lokal (LCID) yang ditentukan dari bahasa yang ditentukan tidak ditemukan dalam daftar bahasa yang tersedia dalam paket, file data default diimpor.

      Anda menentukan bahasa yang tersedia untuk data konfigurasi di node <cmtdatafiles> dalam file ImportConfig.xml. File impor data konfigurasi default ditentukan di atribut crmmigdataimportfile dalam file ImportConfig.xml.

      Melewatkan pemeriksaan data (OverrideDataImportSafetyChecks = true) dapat efektif di sini jika Anda yakin bahwa instans target Dataverse tidak berisi data apa pun.

    6. Masukkan kode kustom untuk mengeksekusi setelah impor selesai dalam definisi timpa metode AfterPrimaryImport>. File datar yang tersisa yang tidak diimpor sebelumnya, sebelum impor solusi dimulai, diimpor sekarang.

    7. Ubah nama default folder paket Anda ke nama paket yang diinginkan. Untuk melakukannya, ganti nama PkgFolder (atau folder PkgAssets) di panel penelusur solusi, lalu Edit nilai kembali dalam properti GetImportPackageDataFolderName.

      public override string GetImportPackageDataFolderName  
{  
get  
{  
// WARNING this value directly correlates to the folder name in the Solution Explorer where the ImportConfig.xml and sub content is located.  
// Changing this name requires that you also change the correlating name in the Solution Explorer  
return "PkgFolder";  
}  
}

    8. Ubah nama paket dengan mengedit nilai kembali dalam properti GetNameOfImport.

      public override string GetNameOfImport(bool plural)  
{  
return "Package Short Name";  
}

      Nilai yang dikembalikan ini adalah nama paket Anda yang muncul di halaman pemilihan paket di wizard Dynamics 365 Package Deployer .

    9. Ubah deskripsi paket dengan mengedit nilai kembali dalam properti GetImportPackageDescriptionText.

      
public override string GetImportPackageDescriptionText  
{  
get { return "Package Description"; }  
}

      Nilai yang dikembalikan ini adalah deskripsi paket yang muncul di samping nama paket pada halaman pemilihan paket di Package Deployer wizard.

    10. Ubah nama panjang paket dengan mengedit nilai kembali dalam properti GetLongNameOfImport.

      
public override string GetLongNameOfImport  
{  
get { return "Package Long Name"; }  
}

      Nama panjang paket akan muncul di halaman berikutnya setelah Anda memilih paket yang akan diinstal.

  3. Selain itu, fungsi dan variabel berikut tersedia untuk paket:

    Nama Jenis Deskripsi
    CreateProgressItem(String) Function Digunakan untuk membuat item progres baru di antarmuka pengguna (UI).
    RaiseUpdateEvent(String, ProgressPanelItemStatus) Function Digunakan untuk memperbarui progres yang dibuat oleh panggilan ke CreateProgressItem(String).

    ProgressPanelItemStatus adalah enum dengan nilai-nilai berikut:

    Bekerja = 0
    Selesai = 1
    Gagal = 2
    Peringatan = 3
    Tidak diketahui = 4
    RaiseFailEvent(String, Exception) Function Digunakan untuk menggagalkan dalam impor status saat ini dengan pesan pengecualian.
    IsRoleAssoicatedWithTeam(Guid, Guid) Function Digunakan untuk menentukan apakah peran dikaitkan dengan tim tertentu.
    IsWorkflowActive(Guid) Function Digunakan untuk menentukan apakah alur kerja tertentu aktif.
    PackageLog Penunjuk kelas Penunjuk ke antarmuka log yang diinisialisasi untuk paket. Antarmuka ini digunakan oleh paket untuk mencatat pesan dan pengecualian ke file log paket.
    RootControlDispatcher Properti Antarmuka operator yang digunakan untuk memungkinkan kontrol Anda menyajikan antarmukanya sendiri selama penyebaran paket. Gunakan antarmuka ini untuk membungkus setiap perintah atau elemen UI. Penting untuk memeriksa variabel ini untuk nilai null sebelum menggunakannya karena mungkin tidak diatur ke nilai.
    CrmSvc Properti Penunjuk ke kelas CrmServiceClient yang memungkinkan paket ke alamat Dynamics 365 dari dalam paket. Gunakan penunjuk ini untuk menjalankan metode SDK dan tindakan lainnya dalam metode ditimpa.
    DataImportBypass Properti Tentukan apakah Package Deployer Dynamics 365 melompati semua operasi impor data seperti mengimpor data sampel Dataverse, data file datar, dan data yang diekspor dari Configuration Migration tool. Tentukan Benar atau Salah. Default-nya adalah false.
    OverrideDataImportSafetyChecks Properti Tentukan apakah Dynamics 365 Package Deployer melewati beberapa pemeriksaan keamanannya, yang membantu meningkatkan performa impor. Tetapkan true atau false. Default-nya adalah false.

    Anda harus mengatur properti ini ke hanya true jika instans target Dataverse tidak berisi data apa pun.

  4. Simpan proyek Anda. Langkah selanjutnya adalah membangun paket.

Bangun dan sebar

Bagian berikut menjelaskan cara membuat dan menyebarkan paket.

Buat

Membuat paket Anda dijelaskan di bawah ini tergantung pada alat yang Anda gunakan.

Untuk membangun paket yang dibuat dengan CLI, Anda dapat memuat file .csproj ke dalam Visual Studio, tetapi sebagai gantinya kita akan menggunakan perintah dotnet dan MSBuild. Contoh di bawah ini mengasumsikan direktori kerja berisi file *.csproj.

> dotnet publish

DeploymentPackage -> C:\Users\peter\Downloads\DeploymentPackage\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

Anda dapat melihat rincian paket yang telah dibuat secara opsional.

> pac package show --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

Paket Anda dibuat dari file berikut di dalam folder <Project>\Bin\Debug.

  • <Folder PackageName> : Nama folder sama dengan yang Anda ubah untuk nama folder paket Anda di langkah 2.g bagian Tambahkan kode kustom ini . Folder ini berisi semua solusi, data konfigurasi, file datar, dan isi untuk paket Anda.

Catatan

Anda dapat melihat folder .NET (contoh: net472) yang berisi folder publikasi pdpublish. DLL Anda dan file proyek lainnya berada di folder pdpublish tersebut.

  • <PackageName.DLL>: Rakitan berisi kode kustom untuk paket Anda. Secara default, nama unit sama dengan nama proyek Anda.

Sebarkan

Setelah membuat paket, Anda dapat menerapkannya pada instans Dataverse dengan menggunakan alat Package Deployer Windows PowerShell, atau perintah CLI.

  • Untuk menyebarkan menggunakan alat Package Deployer, unduh alat terlebih dahulu seperti dijelaskan dalam alat pengembangan Dataverse. Selanjutnya, ikuti informasi terperinci tentang penyebaran paket dalam artikel Menyebarkan paket menggunakan Package Deployer atau Windows PowerShell.

  • Untuk menyebarkan menggunakan CLI, gunakan perintah pac package deploy.

    > pac package deploy --package .\bin\Debug\DeploymentPackage.1.0.0.pdpkg.zip

    Catatan

    Untuk menyebarkan paket ke lingkungan target menggunakan CLI, Anda harus terlebih dulu mengkonfigurasi profil otentikasi dan memilih organisasi. Informasi selengkapnya: pac auth create, pac org select

Praktik terbaik

Tercantum di bawah ini adalah beberapa tips praktik terbaik yang dapat diikuti saat bekerja dengan paket Package Deployer.

Membuat paket

Saat membuat paket, pengembang harus:

  • Pastikan rakitan paket ditandatangani.

Menyebarkan paket

Saat menyebarkan paket, administrator Dataverse harus:

  • Bersikeras pada rakitan paket yang ditandatangani sehingga Anda dapat melacak rakitan kembali ke sumbernya.
  • Uji paket pada instans praproduksi, sebaiknya gambar cermin dari instans produksi, sebelum menjalankannya pada instans produksi.
  • Cadangkan instans produksi sebelum menyebarkan paket.

Lihat juga

Alat Pengemas Solusi