Cipta pakej untuk alat Package Deployer

Package Deployer membenarkan pentadbir menggunakan pakej pada tika Microsoft Dataverse. Package Deployer pakej boleh terdiri daripada mana-mana atau semua yang berikut:

• Satu atau lebih Dataverse fail penyelesaian.
• Fail rata atau fail data konfigurasi dieksport daripada alat Pemindahan Konfigurasi. Untuk maklumat lanjut tentang alat, lihat Alihkan data konfigurasi merentas tika dan organisasi dengan Configuration Migration Tool.
• Kod tersuai yang boleh dijalankan sebelum, semasa, atau selepas pakej dilaksanakan ke tika Dataverse.
• Kandungan HTML khusus untuk pakej yang boleh dipaparkan pada permulaan dan penghujung proses pelaksanaan. Kandungan ini boleh menjadi berguna untuk memberikan penerangan tentang penyelesaian dan fail yang digunakan di dalam pakej.

Nota

Terdapat satu lagi jenis pakej yang dipanggil pakej pasang masuk. Pakej jenis itu adalah untuk perhimpunan pasang masuk dan tidak mempunyai hubungan dengan pakej Package Deployer.

Prasyarat

• Pastikan anda bersedia dengan penyelesaian dan fail lain yang anda mahu masukkan ke dalam pakej.
• Visual Studio 2019 atau lebih baru, atau Visual Studio Kod.

Gambaran keseluruhan proses

Untuk membuat Package Deployer pakej, lakukan langkah berikut.

• Cipta projek Visual Studio atau MSBuild
• Tambah penyelesaian dan fail lain kepada projek
• Kemas kini fail HTML yang disediakan (pilihan)
• Tentukan nilai konfigurasi untuk pakej
• Takrif kod tersuai untuk pakej
• Bina dan gunakan pakej

Langkah-langkah ini diterangkan secara terperinci dalam artikel ini.

Cipta projek pakej

Langkah pertama ialah mencipta projek Visual Studio MSBuild untuk pakej tersebut. Untuk berbuat demikian, anda mesti mempunyai salah satu daripada dua sambungan alat tersedia yang dipasang dalam komputer pembangunan anda. Jika menggunakan Visual Studio Code, pasang Microsoft Power Platform CLI. Jika tidak, jika menggunakan Visual Studio 2019 atau lebih baru, pasang Power Platform alatan untuk Visual Studio.

Pilih tab yang sesuai di bawah untuk mengetahui cara untuk mencipta projek menggunakan sambungan alat yang diingini. Kedua-dua alat mengeluarkan projek dalam format yang sama.

Power Platform CLI

Jalankan arahan pac package init untuk mencipta pakej awal. Maklumat lanjut: pac package

pac package init help
pac package init --outputDirectory DeploymentPackage

Output CLI yang terhasil mengandungi folder dan fail yang ditunjukkan di bawah. Nama folder "DeploymentPackage" telah digunakan di sini sebagai contoh.

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

Dalam projek yang dibuat, cari fail konfigurasi ImportConfig.xml dalam folder PkgAssets dan fail PackageImportExtension.cs. Anda akan mengubah suai fail ini seperti yang diterangkan kemudian dalam artikel ini.

Power Platform Alat

Anda boleh mencipta Visual Studio projek menggunakan Templat Penyelesaian Power Platform dan kemudian menambah projek pakej menggunakan templat Projek Power Platform Penggunaan Pakej atau mencipta projek secara langsung menggunakan templat Projek Power Platform Penggunaan Pakej.

Nota

Jangan pilih templat Pakej Power Platform. Templat tersebut adalah untuk pakej pasang masuk.

Hasil projek dan penyelesaian Visual Studio mengandungi folder dan fail yang ditunjukkan di bawah. Nama "Deployment-package" telah digunakan di sini sebagai contoh. Kandungan folder Kandungan tidak ditunjukkan di sini untuk keringkasan.

C:.
│   Deployment-package.csproj
│   Deployment-package.sln
│   GettingStarted.html
│   PackageTemplate.cs
│
├───PkgFolder
│   │   ImportConfig.xml
│   │
│   └───Content

Dalam projek yang dibuat, cari fail konfigurasi ImportConfig.xml dalam folder PkgFolder dan fail PackageTemplate.cs. Anda akan mengubah suai fail ini seperti yang diterangkan kemudian dalam artikel ini.

Maklumat lanjut tentang penggunaan sambungan Power Platform Tools: Mula cepat: Cipta projek Power Platform Tools

Tambah fail pakej

Selepas anda mencipta projek pakej, anda boleh mula menambah penyelesaian dan fail lain kepada projek tersebut.

Power Platform CLI

Apabila menggunakan CLI, anda boleh menambah pakej luaran, penyelesaian, dan rujukan kepada projek pakej anda menggunakan salah satu daripada sub perintah tambah. Masukkan pac package help untuk melihat senarai sub perintah. Mari tambah penyelesaian kepada pakej kami.

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

Power Platform Alat

1. Dalam anak tetingkap Peneroka Penyelesaian, tambah penyelesaian Dataverse dan fail di bawah folder PkgFolder. Fail HTML tergolong dalam folder Kandungan. Lebih lanjut tentang kandungan HTML ini kemudian.
2. Untuk setiap fail yang anda tambah, di bawah anak tetingkap Sifat, tetapkan nilai Salin ke Direktori Output kepada Sentiasa Salin. Penetapan nilai ini memastikan fail anda tersedia dalam pakej yang dijana.

Seterusnya, kemas kini fail tertentu bahasa HTML.

1. Dalam anak tetingkap Peneroka Penyelesaian, kembangkan PkgFolder>Kandungan>ms-my. Cari dua folder yang dipanggil EndHTML dan WelcomeHTML. Folder ini mengandungi fail HTML dan berkaitan yang mendayakan anda untuk memaparkan (kepada pengguna) maklumat pada penghujung dan permulaan proses pelaksanaan pakej. Edit fail dalam folder HTML fail ini untuk menambahkan maklumat untuk memaparkan pakej anda.

2. Anda juga boleh menambah fail HTML ke dalam pakej anda dalam bahasa lain supaya kandungan HTML dipaparkan dalam bahasa yang berasaskan tetapan setempat bagi komputer pengguna. Untuk berbuat demikian:

   1. Cipta salinan folder ms-my di bawah PkgFolder>Kandungan.
   2. Namakan semula folder yang disalin ke bahasa yang sesuai. Contohnya, untuk bahasa Sepanyol, namakannya semula ke es-ES.
   3. Ubah suai kandungan fail HTML untuk menambah kandungan Bahasa Sepanyol.

Konfigurasikan pakej

Takrifkan konfigurasi pakej dengan menambah maklumat tentang pakej anda dalam fail ImportConfig.xml tersedia dalam projek. Rujuk Rujukan ImportConfig untuk contoh dan penerangan tentang elemen dan atribut yang sah untuk digunakan.

Tambah kod tersuai

Anda boleh menambah kod tersuai yang dilaksanakan sebelum, semasa dan, selepas pakej diimport ke dalam persekitaran. Untuk berbuat demikian, ikut arahan ini.

1. Edit fail PackageTemplate.cs (atau PackageImportExtension.cs) dalam folder akar projek.

2. Dalam fail C#, anda boleh:

   1. Masukkan kod tersuai untuk dilaksanakan apabila pakej diawalkan dalam definisi kaedah ganti bagi InitializeCustomExtension.

      Kaedah ini boleh digunakan untuk membenarkan pengguna menggunakan parameter masa jalanan apabila menjalankan pakej. Sebagai pembangun, anda boleh menambah sokongan untuk mana-mana parameter masa jalanan pada pakej anda dengan menggunakan sifat RuntimeSettings selagi anda mempunyai kod untuk memprosesnya berasaskan pada input pengguna.

      Contohnya, kod sampel berikut mendayakan parameter masa jalanan dipanggil SkipChecks untuk pakej yang mempunyai dua kemungkinan nilai: benar atau palsu. Kod sampel memeriksa jika pengguna menentukan sebarang parameter masa jalanan apabila Package Deployer (sama ada menggunakan baris perintah atau PowerShell), dan kemudian memproses maklumat sewajarnya. Jika tiada parameter masa jalanan ditentukan oleh pengguna apabila menjalankan pakej, nilai sifat RuntimeSettings akan menjadi nol.

      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");  
      }  
      

      Kod ini membenarkan pentadbir menggunakan baris perintah atau cmdlet Import-CrmPackage bagi menentukan sama ada melangkau semakan keselamatan apabila menjalankan alat Package Deployer untuk mengimport pakej. Maklumat lanjut: Laksanakan pakej menggunakan Package Deployer dan Windows PowerShell

   2. Masukkan kod tersuai untuk melaksanakan sebelum penyelesaian diimport dalam definisi kaedah ganti PreSolutionImport bagi menentukan sama ada mengekalkan atau menulis ganti penyesuaian semasa mengemas kini penyelesaian yang ditentukan dalam tika Dataverse sasaran dan sama ada untuk memasang masuk diaktifkan dan aliran kerja.

   3. Gunakan takrifan kaedah ganti untuk RunSolutionUpgradeMigrationStep melaksanakan transformasi data atau naik taraf antara dua versi penyelesaian Kaedah ini dipanggil hanya jika penyelesaian yang anda import sudah hadir dalam tika sasaran Dataverse .

      Fungsi ini menjangkakan parameter berikut:

      Parameter	Penerangan
      solutionName	Nama penyelesaian
      oldVersion	Nombor versi penyelesaian lama
      newVersion	Nombor versi penyelesaian baharu
      oldSolutionId	GUID penyelesaian lama.
      newSolutionId	GUID penyelesaian baharu.

   4. Masukkan kod tersuai untuk dilaksanakan sebelum import penyelesaian selesai dalam definisi kaedah ganti bagi BeforeImportStage. Data sampel dan beberapa fail rata untuk penyelesaian yang ditentukan dalam fail ImportConfig.xml diimport sebelum import penyelesaian selesai.

   5. Ganti bahasa yang dipilih pada masa ini untuk import data konfigurasi menggunakan definisi OverrideConfigurationDataFileLanguage kaedah ganti. Jika ID tempatan (LCID) yang ditentukan bagi bahasa yang ditentukan tidak ditemui dalam senarai bahasa yang tersedia dalam pakej, fail data lalai diimport.

      Anda menentukan bahasa tersedia untuk data konfigurasi dalam nod <cmtdatafiles> dalam fail ImportConfig.xml. Fail import data konfigurasi lalai ditentukan dalam atribut crmmigdataimportfile dalam fail ImportConfig.xml.

      Melangkau semakan data (OverrideDataImportSafetyChecks = benar) boleh berkesan di sini jika anda pasti bahawa tika sasaran Dataverse tidak mengandungi sebarang data.

   6. Masukkan kod tersuai untuk dilaksanakan selepas import selesai dalam definisi ganti kaedah AfterPrimaryImport>. Baki fail rata yang tidak diimport sebelum ini, sebelum import penyelesaian bermula, diimport sekarang.

   7. Ubah nama lalai folder pakej anda kepada nama pakej yang anda mahukan. Untuk berbuat demikian, namakan semula folder PkgFolder (atau PkgAssets) dalam anak tetingkap Peneroka Penyelesaian, dan kemudian edit nilai yang dikembalikan di bawah sifat 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 pakej dengan mengedit nilai yang dikembalikan di bawah sifat GetNameOfImport.

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

      Nilai yang dikembalikan ini ialah nama pakej anda yang muncul pada halaman pemilihan pakej dalam bestari Dynamics 365 Package Deployer .

   9. Ubah description pakej dengan mengedit nilai yang dikembalikan di bawah sifat GetImportPackageDescriptionText.

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

      Nilai yang dikembalikan ini ialah perihalan pakej yang muncul bersama nama pakej pada halaman pemilihan pakej dalam Package Deployer wizard.

   10. Ubah nama panjang pakej dengan mengedit nilai yang dikembalikan di bawah sifat GetLongNameOfImport.

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

       Nama panjang pakej dipaparkan pada halaman seterusnya selepas anda telah memilih pakej untuk dipasang.

3. Selain itu, fungsi dan pemboleh ubah berikut tersedia untuk pakej:

   Nama	Jenis	Penerangan
   CreateProgressItem(String)	Function	Digunakan untuk mencipta item dalam antara muka pengguna (UI).
   RaiseUpdateEvent(String, ProgressPanelItemStatus)	Function	Digunakan untuk kemas kini kemajuan dicipta oleh panggilan ke CreateProgressItem(String). ProgressPanelItemStatus ialah enum dengan nilai berikut: Bekerja = 0 Selesai = 1 Gagal = 2 Amaran = 3 Tidak diketahui = 4
   RaiseFailEvent(String, Exception)	Function	Digunakan untuk menggagalkan status import semasa dengan message pengecualian.
   IsRoleAssoicatedWithTeam(Guid, Guid)	Function	Digunakan untuk menentukan jika peranan berkaitan dengan pasukan tertentu.
   IsWorkflowActive(Guid)	Function	Digunakan untuk menentukan jika aliran kerja yang ditentukan adalah aktif.
   PackageLog	Penuding Kelas	Penuding untuk memulakan antara muka pengelogan bagi pakej. Antara muka ini digunakan oleh pakej untuk log message dan pengecualian ke fail log pakej.
   RootControlDispatcher	Sifat	Antara muka penghantar yang digunakan untuk membenarkan kawalan anda memaparkan UI sendiri semasa pelaksanaan pakej. Gunakan antara muka ini untuk memperkemaskan mana-mana elemen atau perintah . Adalah penting untuk menyemak pembolehubah ini untuk nilai nol sebelum menggunakannya kerana ia mungkin tidak ditetapkan kepada nilai.
   CrmSvc	Sifat	Penuding kepada kelas CrmServiceClient yang membenarkan pakej untuk menangani Dynamics 365 daripada dalam pakej. Gunakan penuding ini untuk melaksanakan kaedah SDK dan tindakan lain dalam kaedah diganti.
   DataImportBypass	Sifat	Tentukan sama ada Dynamics 365 Package Deployer melangkau semua operasi import data seperti mengimport data sampel Dataverse, data fail rata dan data yang dieksport daripada Configuration Migration Tool. Tentukan benar atau palsu. Lalai ialah false.
   OverrideDataImportSafetyChecks	Sifat	Tentukan sama ada Dynamics 365 Package Deployer memintas beberapa semakan keselamatannya, yang membantu dalam meningkatkan prestasi import. Tentukan true atau false. Lalai ialah false. Anda harus menetapkan sifat ini kepada hanya true jika tika sasaran Dataverse tidak mengandungi sebarang data.

4. Simpan projek anda. Langkah seterusnya ialah untuk membina pakej.

Bina dan gunakan

Bahagian berikut menerangkan cara membina dan menggunakan pakej.

Bina

Membina pakej anda diterangkan di bawah bergantung pada alat yang anda gunakan.

Power Platform CLI

Untuk membina pakej yang dibuat dengan CLI, anda boleh memuatkan fail .csproj ke dalam Visual Studio, tetapi sebaliknya kami akan menggunakan arahan dotnet dan MSBuild. Contoh di bawah menganggap direktori kerja mengandungi fail *.csproj.

> dotnet publish

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

Anda boleh lihat secara pilihan pada butiran pakej terbina.

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

Power Platform Alat

Untuk membina pakej, tekan F5 dalam atau Visual Studio pilih Bina penyelesaian binaan>.

Pakej anda dibuat daripada fail berikut di bawah folder <Project>\Bin\Debug.

• <Folder PackageName> : Nama folder adalah sama dengan nama folder yang anda tukar untuk nama folder pakej anda dalam langkah 2.g bahagian ini Tambah kod tersuai. Folder ini mengandungi semua penyelesaian, data konfigurasi, fail rata, dan kandungan untuk pakej anda.

Nota

Anda mungkin nampak folder .NET (cth, net472) mengandungi folder pdpublish. Fail DLL dan projek lain anda ada dalam folder pdpublish.

• <PackageName>.dll: Perhimpunan mengandungi kod tersuai untuk pakej anda. Secara lalai, nama pemasangan sama seperti nama projek anda.

Laksana

Selepas anda mencipta pakej, anda boleh melaksanakannya pada tika Dataverse dengan menggunakan alat Package Deployer, Windows PowerShell, atau perintah CLI.

• Untuk menggunakan alat ini Package Deployer, pertama sekali muat turun alat seperti yang diterangkan dalam alat pembangunan Dataverse. Seterusnya, ikut maklumat terperinci tentang penggunaan pakej dalam artikel Kerahkan pakej menggunakan Package Deployer atau Windows PowerShell.

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

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

  Nota

  Untuk menggunakan pakej kepada persekitaran sasaran menggunakan CLI, anda mesti menyediakan profil pengesahan terlebih dahulu dan memilih organisasi. Maklumat lanjut: pac auth create, pac org select

Amalan terbaik

Berikut adalah beberapa petua amalan terbaik untuk diikut apabila bekerja dengan pakej Package Deployer.

Mencipta pakej

Apabila mencipta pakej, pembangun mesti:

• Pastikan perhimpunan pakej ditandatangani.

Menggunakan pakej

Semasa menggunakan pakej, pentadbir Dataverse mestilah:

• Tegaskan perhimpunan pakej yang ditandatangani supaya anda boleh menjejaki perhimpunan kembali ke sumbernya.
• Uji pakej pada tika prapengeluaran, sebaik-baiknya imej cermin tika tika pengeluaran, sebelum menjalankannya pada tika tika pengeluaran.
• Sandarkan tika pengeluaran sebelum menggunakan pakej.

Lihat juga

Alat Pembungkus Penyelesaian