Buat paket untuk alat Package Deployer

Package Deployer memungkinkan administrator menyebarkan paket pada instans Microsoft Dataverse. Sebuah paket Package Deployer dapat berisi salah satu atau semua dari berikut ini:

  • 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.

Note

Ada jenis paket lain yang disebut paket plug-in. Paket semacam itu adalah untuk rangkaian 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 yang lebih baru, atau Visual Studio Code.

Gambaran umum proses

Untuk membuat paket Package Deployer, lakukan beberapa 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. Atau, jika menggunakan Visual Studio 2019 atau yang lebih baru, instal Power Platform Tools 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 dalam 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 instruksi ini.

  1. Edit file Packagetemplat.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 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()  
{
  // 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 cmdlet Import-CrmPackage untuk menentukan apakah harus melewatkan pemeriksaan keamanan sewaktu menjalankan alat Package Deployer untuk mengimpor paket. Informasi selengkapnya: Menerapkan 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, dan apakah akan secara otomatis mengaktifkan plug-in dan alur kerja.

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

      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. Ambil alih metode OverrideSolutionImportDecision untuk mengembalikan enum UserRequestedImportAction yang mengontrol apakah impor solusi akan dilewati, diperbarui, atau ditingkatkan (default).

      public override UserRequestedImportAction OverrideSolutionImportDecision(
  string solutionUniqueName, Version organizationVersion,
  Version packageSolutionVersion, Version inboundSolutionVersion,
  Version deployedSolutionVersion, ImportAction systemSelectedImportAction )
{
  return systemSelectedImportAction == 
      ImportAction.Import ? UserRequestedImportAction.ForceUpdate
      : base.OverrideSolutionImportDecision(solutionUniqueName, organizationVersion,
      packageSolutionVersion, inboundSolutionVersion, deployedSolutionVersion,
      systemSelectedImportAction);
}

    5. 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.

    6. Timpa bahasa yang dipilih saat ini untuk impor data konfigurasi menggunakan definisi metode timpa OverrideConfigurationDataFileLanguage. Jika ID lokal yang ditentukan (LCID) dari bahasa yang ditentukan tidak ditemukan dalam daftar bahasa yang tersedia dalam paket, file data default akan 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 = benar) bisa efektif di sini jika Anda yakin bahwa instans Dataverse target tidak berisi data apa pun.

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

    8. Ubah nama default folder paket Anda ke nama paket yang diinginkan. Untuk melakukannya, ganti nama folder PkgFolder (atau PkgAssets) di panel Penjelajah Solusi, lalu edit nilai pengembalian di bawah properti GetImportPackageDataFolderName.

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

    9. 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 penyebar paket Dynamics 365.

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

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

      Nilai yang dihasilkan ini adalah deskripsi paket yang akan muncul di sisi nama paket pada halaman pilihan paket di wizard Package Deployer.

    11. 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 Type 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 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.
    IsRoleAssociatedWithTeam(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 Property 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 suatu nilai.
    CrmSvc Property Pointer ke kelas CrmServiceClient yang memungkinkan paket untuk mengakses Dynamics 365 dari dalam paket. Gunakan penunjuk ini untuk menjalankan metode SDK dan tindakan lainnya dalam metode ditimpa.
    DataImportBypass Property Tentukan apakah Package Deployer Dynamics 365 melewatkan semua operasi impor data seperti mengimpor data sampel Dataverse, data file flat, dan data yang diekspor dari Configuration Migration Tool. Tentukan Benar atau Salah. Defaultnya adalah false.
    OverrideDataImportSafetyChecks Property Tentukan apakah Penyebar Paket Dynamics 365 melewati beberapa pemeriksaan keamanannya, yang membantu meningkatkan performa impor. Tentukan true atau false. Defaultnya adalah false.

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

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

Membangun dan menyebarkan

Bagian berikut menjelaskan cara membuat dan menyebarkan paket.

Build

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

Untuk membuat paket yang dibuat dengan CLI, Anda dapat memuat file .csproj ke Visual Studio, tetapi sebaliknya 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 terbuat dari file berikut di folder <Project>\Bin\Debug.

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

Note

Anda mungkin melihat folder .NET (misalnya, net472) yang berisi folder pdpublish. DLL Anda dan file proyek lainnya berada di folder pdpublish tersebut.

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

Deploy

Setelah membuat paket, Anda dapat menyebarkannya 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 paket Deploy menggunakan Penyebar Paket atau Windows PowerShell.

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

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

    Note

    Untuk menyebarkan paket ke lingkungan target menggunakan CLI, Anda harus terlebih dulu mengkonfigurasi profil autentikasi 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 tersebut ditandatangani.

Menyebarkan paket

Saat menyebarkan paket, administrator Dataverse harus:

  • Menekankan rakitan paket ditandatangani sehingga Anda dapat melacak rakitan kembali ke sumbernya.
  • Menguji paket pada instans praproduksi, sebaiknya gambar bayangan dari instans produksi, sebelum menjalankannya di instans produksi.
  • Mencadangkan instans produksi sebelum menyebarkan paket.

Baca juga

Alat Solution Packager

  • Last updated on