Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
SolutionPackager adalah alat yang dapat menguraikan file solusi terkompresi Microsoft Dataverse ke dalam beberapa file XML dan file lainnya. Anda kemudian dapat dengan mudah mengelola file-file ini dengan menggunakan sistem kontrol sumber. Bagian berikut ini menunjukkan cara menjalankan alat dan cara menggunakan alat dengan solusi terkelola dan tidak terkelola.
Important
Alat SolutionPackager bukan lagi cara yang direkomendasikan untuk membongkar dan mengemas solusi. Kemampuan alat SolutionPackager dimasukkan ke dalam Power Platform CLI. Perintah pac solution ini memiliki banyak kata kerja termasuk unpack, pack, clone, dan sync yang menggabungkan kemampuan mendasar yang sama dari alat SolutionPackager.
Lokasi menemukan alat SolutionPackager
Alat SolutionPackager didistribusikan sebagai bagian dari paket NuGet Microsoft.CrmSdk.CoreTools. Untuk menginstal program, ikuti langkah-langkah berikut.
- Unduh paket NuGet.
- Ganti nama ekstensi nama file paket dari .nupkg menjadi .zip.
- Ekstrak isi file kompresi (zip).
Temukan SolutionPackager.exe yang dapat dieksekusi di folder <extracted-folder-name>/contents/bin/coretools. Jalankan program dari folder coretools atau tambahkan folder itu ke PATH Anda.
Argumen baris perintah SolutionPackager
SolutionPackager adalah alat baris perintah yang dapat dijalankan dengan parameter yang diidentifikasi dalam tabel berikut.
| Argumen | Deskripsi |
|---|---|
| /action: {Extract|Pack} | Dibutuhkan. Tindakan untuk dilakukan. Tindakan ini dapat berupa mengekstrak file Solution.zip ke folder, atau untuk mengemas folder ke dalam file .zip. |
| /zipfile: <jalur file> | Dibutuhkan. Jalur dan nama file Solution.zip. Saat mengekstrak, file harus ada dan dapat dibaca. Saat mengemas, file akan diganti. |
| /folder: <jalur folder> | Dibutuhkan. Jalur ke folder. Saat mengekstrak, folder ini dibuat dan diisi dengan file komponen. Saat mengemas, folder ini harus sudah ada dan berisi file komponen yang diekstrak sebelumnya. |
| /packagetype: {Tidak Dikelola|Terkelola|Keduanya} | Optional. Jenis paket untuk diproses. Nilai default adalah Tidak terkelola. Argumen ini mungkin dihilangkan dalam banyak kesempatan karena jenis paket dapat dibaca dari dalam file .zip atau file komponen. Saat mengekstrak dan keduanya ditentukan, file .zip solusi yang terkelola dan tidak terkelola harus ada dan diproses menjadi satu folder. Saat mengemas dan Keduanya ditentukan, file .zip solusi yang terkelola dan tidak terkelola dihasilkan dari satu folder. Untuk informasi lebih lanjut, lihat bagian tentang cara menangani solusi terkelola dan tidak terkelola nanti di artikel ini. |
| /allowWrite:{Yes|No} | Optional. Nilai default adalah Ya. Argumen ini hanya digunakan selama ekstraksi. Bila/allowWrite:No ditentukan, alat melakukan semua operasi namun dicegah untuk menulis atau menghapus file apa pun. Operasi ekstrak dapat dinilai dengan aman tanpa menimpa atau menghapus file yang ada. |
| /allowDelete:{Yes|No|Prompt} | Optional. Nilai default adalah Prompt. Argumen ini hanya digunakan selama ekstraksi. Bila/allowDelete: Ya ditentukan, file apa pun yang ada di folder yang ditentukan oleh parameter /folder yang tidak diharapkan akan dihapus secara otomatis. Bila/allowDelete:No ditentukan, tidak ada penghapusan yang terjadi. Bila/allowDelete:Prompt ditentukan, pengguna akan diminta melalui konsol untuk membolehkan atau menolak semua operasi penghapusan. Jika /allowWrite:No ditentukan, tidak ada penghapusan akan terjadi meskipun /allowDelete:Yes juga ditentukan. |
| /clobber | Optional. Argumen ini hanya digunakan selama ekstraksi. Bila/clobber ditentukan, file yang memiliki rangkaian atribut baca-saja akan ditimpa atau dihapus. Bila tidak ditentukan, file dengan atribut baca-saja tidak akan ditimpa atau dihapus. |
| /errorlevel: {Off|Error|Warning|Info|Verbose} | Optional. Nilai default adalah Info. Argumen ini menunjukkan tingkat pencatatan informasi ke output. |
| /map: <jalur file> | Optional. Jalur dan nama file .xml yang berisi perintah pemetaan file. Bila digunakan selama ekstraksi, file yang biasanya dibaca dari dalam folder yang ditentukan oleh parameter /folder dibaca dari lokasi alternatif sebagaimana ditentukan dalam file pemetaan. Selama operasi paket, file yang cocok dengan arahan tidak ditulis. |
| /nologo | Optional. Menekan spanduk saat runtime. |
| /log: <jalur file> | Optional. Jalur dan nama ke file log. Jika file sudah ada, informasi Logging baru ditambahkan ke file. |
| @ <file path> | Optional. Jalur dan nama ke file yang berisi argumen baris perintah untuk alat. |
| /sourceLoc: <string> | Optional. Argumen ini menghasilkan file sumber daya template, dan hanya berlaku saat ekstraksi. Nilai yang mungkin adalah auto atau kode LCID/ISO untuk bahasa yang ingin diekspor. Bila argumen ini digunakan, sumber string dari lokal yang diberikan diekstrak sebagai file Neutral .resx. Jika auto atau hanya bentuk panjang atau pendek peralihan ditentukan, lokal dasar atau solusi digunakan. Anda dapat menggunakan formulir singkat perintah: /src. |
| /localize | Optional. Ekstrak atau gabungkan semua sumber daya string ke dalam file .resx. Anda dapat menggunakan formulir singkat perintah: /loc. Pilihan lokalisasi mendukung komponen bersama untuk file .resx. Informasi lebih lanjut: menggunakan Sumber daya web RESX |
| /NamaSolusi: <name> | Optional. Nama unik solusi untuk mengemas atau mengekstrak ketika folder sumber berisi beberapa solusi di bawah solutions/*/solution.yml. Diperlukan ketika lebih dari satu solusi terdeteksi. Hanya berlaku untuk format kontrol sumber YAML. Anda dapat menggunakan bentuk pendek perintah: /sn. |
| /remapPluginTypeNames | Optional. Jika ditentukan, nama jenis plug-in yang sepenuhnya memenuhi syarat dipetakan ulang berdasarkan rakitan yang disertakan dalam solusi. Diaktifkan secara default dalam format kontrol sumber YAML. Anda dapat menggunakan bentuk pendek perintah: /fp. |
Format file kontrol sumber
SolutionPackager mendukung dua tata letak folder saat mengekstrak dan mengemas solusi.
Format XML (warisan)
Format asli. Metadata solusi disimpan di Other\Solution.xml dan Other\Customizations.xml, dan semua file komponen diekstrak ke dalam hierarki folder datar bersama-sama file-file tersebut. Format ini adalah format default saat mengekstrak file .zip tanpa konfigurasi lebih lanjut.
Format kontrol sumber YAML
Diperkenalkan bersama integrasi Dataverse Git, format ini menyimpan metadata solusi sebagai file YAML yang didistribusikan di seluruh hierarki folder terstruktur. Ini adalah format yang ditulis saat Anda menerapkan solusi menggunakan integrasi Git asli di Power Apps.
Keuntungan daripada format XML
- Menghasilkan perbedaan per komponen yang lebih bersih dan lebih mudah dibaca dalam kontrol sumber
- Mendukung beberapa solusi dalam satu folder repositori
- File aplikasi kanvas
.msappdan alur kerja modern hanya didukung dalam format ini - Pemetaan ulang nama jenis plug-in diaktifkan secara default
Struktur folder yang diperlukan
<rootFolder>/
├── solutions/
│ └── <SolutionUniqueName>/
│ ├── solution.yml (solution metadata)
│ ├── solutioncomponents.yml (paths to all component files)
│ ├── rootcomponents.yml (root-level components)
│ └── missingdependencies.yml (dependency info)
├── publishers/
│ └── <PublisherUniqueName>/
│ └── publisher.yml (publisher definition)
├── entities/ (entity components, if present)
├── workflows/ (classic workflows, if present)
├── modernflows/ (Power Automate cloud flows, if present)
├── canvasapps/ (canvas app .msapp files, if present)
└── [other component folders]/
Important
Format YAML terdeteksi otomatis oleh keberadaan subfolder solutions/ yang berisi *solution.yml file.
Jika file manifes YAML Anda (solution.yml, solutioncomponents.yml, dan sebagainya) ditempatkan di akar folder daripada di bawah solutions/<SolutionUniqueName>/, alat tidak mendeteksi format YAML. Alat ini beralih kembali ke jalur XML dan melaporkan kesalahan yang menyesatkan terkait hilangnya Customizations.xml. Lihat Pemecahan masalah untuk informasi tentang cara memperbaiki masalah ini.
Informasi selengkapnya: Referensi format kontrol sumber YAML solusi
Memformat aturan deteksi otomatis
| Keadaan | Format yang digunakan |
|---|---|
solutions/*/solution.yml ditemukan — tepat satu solusi |
Format YAML, tempat nama solusi disimpulkan dari folder |
solutions/*/solution.yml ditemukan — beberapa solusi |
Format YAML, di mana argumen /SolutionName diperlukan |
Tidak ada solutions/ subdirektori yang ada |
Format XML (warisan) |
Mengemas folder dengan format YAML
Perintah berikut mengemas folder format YAML.
SolutionPackager.exe /action:Pack /zipfile:MySolution.zip /folder:C:\repos\myrepo
Melakukan pengemasan dari direktori multi-solusi
Perintah berikut mengemas solusi tertentu dalam folder multi-solusi.
SolutionPackager.exe /action:Pack /zipfile:SolutionA.zip /folder:C:\repos\myrepo /SolutionName:SolutionA
Gunakan argumen perintah /map
Diskusi berikut merinci penggunaan argumen /map untuk alat SolutionPackager.
File yang dibuat dalam sistem pembuatan otomatis, seperti file .xap Silverlight dan assembly plug-in, biasanya tidak dimasukkan ke kontrol sumber. Sumber daya web mungkin sudah ada di kontrol sumber di lokasi yang tidak kompatibel secara langsung dengan alat SolutionPackager. Dengan menyertakan parameter /map, alat SolutionPackager dapat diarahkan untuk membaca dan mengemas file tersebut dari lokasi alternatif dan tidak di dalam folder ekstrak seperti yang biasanya dilakukan. Parameter /map harus menentukan nama dan jalur ke file XML yang berisi arahan pemetaan. Arahan tersebut menginstruksikan SolutionPackager untuk mencocokkan file berdasarkan nama dan jalurnya, dan menunjukkan lokasi alternatif untuk menemukan file yang cocok. Informasi berikut berlaku untuk semua arahan yang sama.
Beberapa arahan dapat didaftarkan termasuk arahan akan mencocokkan file yang sama. Arahan yang tercantum di awal dalam file lebih diutamakan daripada arahan yang tercantum nanti.
Jika file dicocokkan dengan arahan apa pun, maka file tersebut harus ditemukan di setidaknya satu lokasi alternatif. Jika tidak ada alternatif yang cocok ditemukan, SolutionPackager mengeluarkan kesalahan.
Jalur folder dan file mungkin mutlak atau relatif. Jalur relatif selalu dievaluasi dari folder yang ditentukan oleh parameter /folder.
Variabel lingkungan dapat ditentukan dengan menggunakan sintaks %variabel%.
Wildcard folder "**" dapat digunakan yang berarti "di setiap subfolder". Ini hanya dapat digunakan sebagai bagian akhir dari jalur, misalnya: "c:\folderA\**".
Karakter pengganti nama file hanya dapat digunakan dalam format "*.ext" atau "*.*". Tidak ada pola lain yang didukung.
Tiga jenis pemetaan arahan dijelaskan di sini, bersama dengan contoh yang menunjukkan cara menggunakannya.
Pemetaan folder
Informasi berikut ini menyediakan informasi rinci tentang pemetaan folder.
Xml Format
<Folder map="folderA" to="folderB" />
Description
Jalur file yang cocok dengan "folderA" dialihkan ke "folderB".
Hierarki subfolder di bawah masing-masing harus sama persis.
Wildcard folder tidak didukung.
Tidak ada nama file yang dapat ditentukan.
Examples
<Folder map="folderA" to="folderB" /> <Folder map="folderA\folderB" to="..\..\folderC\" /> <Folder map="WebResources\subFolder" to="%base%\WebResources" />
Pemetaan File ke file
Informasi berikut ini menyediakan detail lebih lanjut rinci tentang pemetaan file ke file.
Xml Format
<FileToFile map="path\filename.ext" to="path\filename.ext" />
Description
File yang cocok dengan parameter map dibaca dari nama dan jalur yang ditentukan dalam parameter to.
Untuk parameter map:
Nama file harus ditentukan. Jalur ini opsional. Jika tidak ada jalur yang ditentukan, file dari folder mungkin dicocokkan.
Wildcard nama file tidak didukung.
Wildcard folder didukung.
Untuk parameter
to:Nama file dan jalur harus ditentukan.
Nama file mungkin berbeda dari nama dalam parameter
map.Wildcard nama file tidak didukung.
Wildcard folder didukung.
Examples
<FileToFile map="assembly.dll" to="c:\path\folder\assembly.dll" />
<FileToFile map="PluginAssemblies\**\this.dll" to="..\..\Plugins\**\that.dll" />
<FileToFile map="Webresrouces\ardvark.jpg" to="%SRCBASE%\CrmPackage\WebResources\JPG format\aardvark.jpg" />
<FileToFile
map="pluginpackages\cr886_PluginPackageTest\package\cr886_PluginPackageTest.nupkg"
to="myplg\bin\Debug\myplg.1.0.0.nupkg" />
Dalam contoh paket NuGet di atas, cr886_PluginPackageTest.nupkg tidak ditimpa jika file sudah ada di lokasi yang ditentukan.
Pemetaan file ke jalur
Berikut menyediakan informasi rinci tentang pemetaan file ke jalur.
Xml Format
<FileToPath map="path\filename.ext" to="path" />
Description
File yang cocok dengan parameter map dibaca dari jalur yang ditentukan dalam parameter to.
Untuk parameter map:
Nama file harus ditentukan. Jalur ini opsional. Jika tidak ada jalur yang ditentukan, file dari folder mungkin dicocokkan.
Wildcard nama file didukung.
Wildcard folder didukung.
Untuk parameter to:
Jalur harus ditentukan.
Wildcard folder didukung.
Nama file tidak boleh ditentukan.
Examples
<FileToPath map="assembly.dll" to="c:\path\folder" />
<FileToPath map="PluginAssemblies\**\this.dll" to="..\..\Plugins\bin\**" />
<FileToPath map="*.jpg" to="%SRCBASE%\CrmPackage\WebResources\JPG format\" />
<FileToPath map="*.*" to="..\..\%ARCH%\%TYPE%\drop" />
Contoh pemetaan
Sampel kode XML berikut menunjukkan file pemetaan lengkap yang mengaktifkan alat SolutionPackager untuk membaca sumber daya web dan dua assembly yang dihasilkan secara default dari proyek toolkit pengembang bernama CRMDevTookitSample.
<?xml version="1.0" encoding="utf-8"?>
<Mapping>
<!-- Match specific named files to an alternate folder -->
<FileToFile map="CRMDevTookitSamplePlugins.dll" to="..\..\Plugins\bin\**\CRMDevTookitSample.plugins.dll" />
<FileToFile map="CRMDevTookitSampleWorkflow.dll" to="..\..\Workflow\bin\**\CRMDevTookitSample.Workflow.dll" />
<!-- Match any file in and under WebResources to an alternate set of subfolders -->
<FileToPath map="WebResources\*.*" to="..\..\CrmPackage\WebResources\**" />
<FileToPath map="WebResources\**\*.*" to="..\..\CrmPackage\WebResources\**" />
</Mapping>
Solusi terkelola dan tidak terkelola
File solusi terkompresi Dataverse (.zip) dapat diekspor dalam salah satu dari dua jenis seperti yang ditunjukkan di sini.
Solusi terkelola
Solusi lengkap siap diimpor ke organisasi. Setelah diimpor, komponen tidak dapat ditambahkan atau dihapus, meskipun secara opsional dapat mengizinkan penyesuaian lebih lanjut. Ini direkomendasikan bila pengembangan solusi selesai.
Solusi tidak terkelola
Solusi terbuka tanpa batasan pada apa yang dapat ditambahkan, dihapus, atau dimodifikasi. Ini disarankan selama pengembangan solusi.
Format file solusi terkompresi akan berbeda berdasarkan jenisnya, baik terkelola maupun tidak terkelola. SolutionPackager dapat memproses file solusi terkompresi dari kedua jenis. Namun, alat ini tidak dapat mengonversi satu jenis ke jenis lainnya. Satu-satunya cara untuk mengkonversi file solusi ke jenis yang berbeda, misalnya dari tidak terkelola ke terkelola, adalah dengan mengimpor file .zip solusi tidak terkelola solution ke server Dataverse dan kemudian mengekspor solusi sebagai solusi terkelola.
SolutionPackager dapat memproses file yang tidak dikelola dan solusi terkelola .zip sebagai bundel yang digabungkan melalui parameter /PackageType:Both. Untuk melakukan operasi ini, Anda perlu mengekspor solusi dua kali sebagai masing-masing jenis, dengan menamai file .zip sebagai berikut.
File .zip yang tidak dikelola: AnyName.zip
File .zip yang dikelola: AnyName_managed.zip
Alat akan mengasumsikan adanya file zip terkelola di folder yang sama dengan file yang tidak dikelola dan mengekstrak kedua file ke dalam satu folder yang mempertahankan perbedaan di mana komponen terkelola dan tidak terkelola ada.
Setelah solusi diekstrak sebagai tidak terkelola dan dikelola, dimungkinkan dari satu folder itu untuk mengemas keduanya, atau masing-masing jenis secara individual menggunakan parameter /PackageType untuk menentukan jenis yang akan dibuat. Saat menentukan kedua file, dua file .zip akan diproduksi menggunakan konvensi penamaan seperti di atas. Jika parameter /PackageType hilang saat pengemasan dari folder tak terkelola dan terkelola ganda, maka default adalah untuk menghasilkan file .zip tunggal yang tidak dikelola.
Troubleshooting
Pesan ditampilkan saat menggunakan Visual Studio untuk mengedit file sumber daya
Jika Anda menggunakan Visual Studio untuk mengedit file sumber daya yang dibuat oleh pengemas solusi, Anda mungkin menerima pesan saat mengemas ulang yang mirip dengan ini: "Failed to determine version id of the resource file <filename>.resx the resource file must be exported from the solutionpackager.exe tool in order to be used as part of the pack process." Ini terjadi karena Visual Studio mengganti tag metadata file sumber daya dengan tag data.
Workaround
Buka file sumber daya di editor teks favorit Anda, lalu temukan dan perbarui Tag berikut:
<data name="Source LCID" xml:space="preserve"> <data name="Source file" xml:space="preserve"> <data name="Source package type" xml:space="preserve"> <data name="SolutionPackager Version" mimetype="application/x-microsoft.net.object.binary.base64">Ubah nama node dari
<data>ke<metadata>.Misalnya, string ini:
<data name="Source LCID" xml:space="preserve"> <value>1033</value> </data>Berubah ke:
<metadata name="Source LCID" xml:space="preserve"> <value>1033</value> </metadata>Hal ini memungkinkan solution Packager untuk membaca dan mengimpor file sumber daya. Masalah ini baru diamati saat menggunakan editor sumber daya Visual Studio.
Kesalahan: "Tidak dapat menemukan file yang diperlukan ...\Other\Customizations.xml" dengan folder YAML
Kesalahan ini muncul ketika Anda menjalankan SolutionPackager (atau pac solution pack) terhadap folder yang berisi file YAML seperti solution.yml, tetapi file-file tersebut ditempatkan di akar folder daripada di dalam subfolder yang diperlukan solutions/<SolutionUniqueName>/ .
Menyebabkan: Alat ini mendeteksi format kontrol sumber YAML dengan mencari subfolder yang solutions/ berisi *solution.yml file. Ketika direktori itu tidak ada, alat secara diam-diam kembali ke format XML (warisan) dan mengharapkan Other\Customizations.xml. Pesan kesalahan yang dihasilkan mengacu pada file XML dan tidak menyebutkan YAML, yang menyesatkan.
Memperbaiki: Tata ulang folder sehingga file manifes YAML berada di bawah jalur yang benar:
<rootFolder>/
solutions/<YourSolutionUniqueName>/ ← move solution.yml here
solution.yml
solutioncomponents.yml
rootcomponents.yml
missingdependencies.yml
publishers/<YourPublisherUniqueName>/
publisher.yml
Jika Anda mendapatkan folder dari penerapan integrasi Git atau pac solution clone, struktur folder harus sudah benar. Folder yang hanya berisi file YAML tingkat atas tanpa solutions/ subdirektori mewakili ekstrak yang tidak lengkap dan tidak dapat dikemas secara langsung.
Peringatan: komponen yang dideklarasikan dalam rootcomponents.yml tidak memiliki file sumber
Peringatan ini muncul ketika komponen, seperti aplikasi kanvas, tercantum di rootcomponents.yml tetapi tidak ada file sumber yang sesuai di folder komponen yang diharapkan (misalnya, canvasapps/<schema-name>/).
Efek: Alat ini masih berhasil (kode keluar 0) dan menghasilkan file yang valid .zip , tetapi komponen yang dinyatakan dihilangkan dari solusi yang dikemas.
Menyebabkan: Folder diproduksi oleh ekstrak parsial, atau file sumber komponen tidak disertakan dalam repositori. Misalnya, hanya file manifes solusi yang dikomit dan bukan aplikasi kanvas itu sendiri.
Memperbaiki: Pastikan semua komponen yang dinyatakan memiliki rootcomponents.yml file sumber yang sesuai yang ada di folder. Untuk aplikasi kanvas, .msapp file harus ada di bawah canvasapps/<schema-name>/. Jika ada file yang hilang, ekspor kembali solusi lengkap dari Dataverse dan bongkar lagi, atau gunakan pac solution clone untuk mendapatkan ekstrak lengkap.