Referensi format kontrol sumber YAML solusi

Artikel ini adalah referensi untuk format kontrol sumber berbasis YAML yang digunakan saat Anda:

  • Terapkan solusi menggunakan integrasi Dataverse Git asli di Power Apps.
  • Ekstrak solusi menggunakan pac solution clone atau pac solution sync.
  • Jalankan SolutionPackager secara manual terhadap folder yang berisi file manifes YAML.

Format YAML berbeda dari tata letak XML klasik. Memahami struktur penting ketika Anda ingin mengemas kembali folder YAML secara manual ke dalam .zip file yang dapat diimpor Dataverse.

Important

Dukungan format kontrol sumber YAML di CLI pac memerlukan Microsoft. PowerApps.CLI versi 2.4.1 atau yang lebih baru. Unduh versi terbaru dari NuGet atau perbarui melalui pac install latest. SolutionPackager.exe, yang dikirim dengan paket NuGet, mendukung format YAML dari versi yang sama.

Gambaran umum struktur folder

Akar repositori format YAML berisi direktori tingkat atas berikut:

<repositoryRoot>/
├── solutions/
│   └── <SolutionUniqueName>/       (one subfolder per solution)
│       ├── solution.yml
│       ├── solutioncomponents.yml
│       ├── rootcomponents.yml
│       └── missingdependencies.yml
├── publishers/
│   └── <PublisherUniqueName>/      (one subfolder per publisher)
│       └── publisher.yml
├── entities/                        (entity components, if any)
│   └── <entity_schema_name>/
│       ├── attributes/
│       ├── formxml/
│       ├── savedqueries/
│       └── ...
├── workflows/                       (classic workflow definitions, if any)
├── modernflows/                     (Power Automate cloud flows, if any)
├── canvasapps/                      (canvas app .msapp files, if any)
│   └── <canvas_app_schema_name>/
│       └── <name>.msapp
├── environmentvariabledefinitions/  (environment variable definitions, if any)
├── connectors/                      (custom connectors, if any)
└── [other component folders]/

Direktori solutions/ dan publishers/ diperlukan. Semua folder komponen di akar bersifat opsional dan bergantung pada apa yang dikandung solusi.

Important

Semua file manifes YAML (solution.yml, publisher.yml, dan sebagainya) harus ditempatkan di bawah subdirektori masing-masing (solutions/<name>/, publishers/<name>/). Menempatkannya di akar repositori mencegah deteksi format dan menyebabkan alat SolutionPackager kembali ke format XML — menghasilkan kesalahan menyesatkan tentang hilangnya Customizations.xml. Informasi selengkapnya: Pemecahan masalah alat SolutionPackager

Format deteksi otomatis

SolutionPackager (dan pac solution pack) mendeteksi format secara otomatis sebagai berikut:

Keadaan Format terdeteksi Behavior
solutions/*/solution.yml ditemukan — satu solusi YAML Nama solusi yang disimpulkan dari nama subfolder
solutions/*/solution.yml ditemukan — beberapa solusi YAML /SolutionName argumen diperlukan untuk menentukan solusi mana yang akan dikemas
Tidak ada solutions/ subdirektori yang ada XML (warisan) Other\Solution.xml Mengharapkan danOther\Customizations.xml

File manifes

solution.yml

Terletak di solutions/<SolutionUniqueName>/solution.yml. Berisi metadata solusi tingkat atas — setara DENGAN solution.xml YAML dalam format XML.

Bidang utama mencakup nama unik solusi, versi, nama yang mudah diingat, deskripsi, dan referensi ke penerbit.

solutioncomponents.yml

Terletak di solutions/<SolutionUniqueName>/solutioncomponents.yml. Mencantumkan jalur relatif ke semua file komponen yang disertakan dalam solusi ini. SolutionPackager membaca file ini selama paket untuk menemukan sumber komponen.

Contoh kutipan:

- Path: entities/account
- Path: entities/contact
- Path: canvasapps/myapp_<guid>
- Path: publishers/MyPublisher

rootcomponents.yml

Terletak di solutions/<SolutionUniqueName>/rootcomponents.yml. Mencantumkan komponen tingkat akar (biasanya tabel dan objek tingkat atas lainnya) yang termasuk dalam solusi ini.

Note

Jika komponen dideklarasikan di rootcomponents.yml tetapi file sumbernya tidak ada dari folder (misalnya, file aplikasi .msapp kanvas di bawah canvasapps/<name>/), SolutionPackager memancarkan peringatan dan menghilangkan komponen tersebut dari yang dikemas .zip. Operasi paket masih berhasil diselesaikan dengan kode keluar 0.

Keberhasilan paket tidak menjamin keberhasilan impor. Jika solutioncomponents.yml menghilangkan jalur dependensi yang diperlukan — seperti folder entitas induk atau definisi hubungan di bawah entityrelationships/ — paket solusi tanpa kesalahan tetapi gagal mengimpor dengan pesan seperti: "Atribut tidak memiliki definisi hubungan terkait." Selalu pastikan solutioncomponents.yml mencakup semua entitas dan hubungan dependen, bukan hanya entitas yang dimiliki solusi.

missingdependencies.yml

Terletak di solutions/<SolutionUniqueName>/missingdependencies.yml. Mencatat dependensi solusi apa pun yang tidak ada saat solusi terakhir diekspor. Digunakan untuk tujuan informasi dan untuk memvalidasi kelengkapan pada impor.

publisher.yml

Terletak di publishers/<PublisherUniqueName>/publisher.yml. Berisi definisi penerbit — nama unik, nama tampilan, awalan kustomisasi, dan awalan nilai opsi.

Struktur minimal yang diperlukan:

Publisher:
  UniqueName: mypublisher
  LocalizedNames:
    LocalizedName:
      '@description': My Publisher
      '@languagecode': '1033'
  Descriptions:
  EMailAddress:
    '@xsi:nil': 'true'
    '@xmlns:xsi': http://www.w3.org/2001/XMLSchema-instance
  SupportingWebsiteUrl:
    '@xsi:nil': 'true'
    '@xmlns:xsi': http://www.w3.org/2001/XMLSchema-instance
  CustomizationPrefix: myp
  CustomizationOptionValuePrefix: '12345'
  Addresses:

Dukungan jenis komponen

Tabel berikut ini mencantumkan bagaimana setiap jenis komponen ditangani dalam format YAML.

Jenis komponen Dalam format YAML Catatan
Entitas (tabel), atribut, formulir, tampilan ✓ File YAML Disimpan sebagai file YAML individual per subkomponen
Alur kerja (klasik) ✓ File YAML Di bawah workflows/
Alur modern (Power Automate aliran cloud) ✓ — Hanya format YAML Di bawah modernflows/; tidak didukung dalam format XML
Aplikasi kanvas ✓ — Hanya format YAML .msapp biner di bawah canvasapps/<name>/; tidak didukung dalam format XML
Definisi variabel lingkungan ✓ File XML File individual .xml di bawah environmentvariabledefinitions/
Nilai variabel lingkungan ✓ File JSON Disimpan sebagai environment_variable_values.json
Konektor kustom ✓ Di bawah connectors/
Rakitan plug-in ✓ Nama jenis yang sepenuhnya memenuhi syarat dipetakan ulang secara default (/remapPluginTypeNames)
Sumber daya web ✓ Di bawah webresources/
Peran keamanan ✓ Disimpan sebagai XML secara internal; difilter per solusi
Rangkaian opsi (global) ✓ Disimpan sebagai XML; difilter per solusi
Dashboards ✓ Disimpan sebagai XML; difilter per solusi
Peta situs ✓ Disimpan sebagai XML; difilter per solusi
Kustomisasi pita ✓ Disimpan sebagai XML; difilter per solusi
Hubungan entitas ✓ Di bawah entityrelationships/

Note

Komponen yang disimpan sebagai XML secara internal secara otomatis dikonversi antara XML dan YAML selama operasi paket dan bongkar. Anda dapat menulisnya sebagai file YAML; alat ini menangani konversi.

Repositori multi-solusi

Akar repositori tunggal dapat berisi beberapa solusi. Semua solusi berbagi folder komponen yang sama; solutioncomponents.yml di setiap solusi mengontrol jalur komponen mana yang termasuk dalam solusi tersebut.

Contoh struktur dengan dua solusi:

<repositoryRoot>/
├── solutions/
│   ├── SolutionA/
│   │   ├── solution.yml
│   │   ├── solutioncomponents.yml    ← references entities/account, entities/contact
│   │   ├── rootcomponents.yml
│   │   └── missingdependencies.yml
│   └── SolutionB/
│       ├── solution.yml
│       ├── solutioncomponents.yml    ← references entities/lead, workflows/myflow
│       ├── rootcomponents.yml
│       └── missingdependencies.yml
├── publishers/
│   └── SharedPublisher/
│       └── publisher.yml
├── entities/
│   ├── account/
│   ├── contact/
│   └── lead/
└── workflows/
    └── myflow/

Mengemas solusi tertentu dari folder multi-solusi

Menggunakan SolutionPackager.exe:

SolutionPackager.exe /action:Pack /zipfile:SolutionA.zip /folder:C:\repos\myrepo /SolutionName:SolutionA

Menggunakan pac solution pack (folder solusi tunggal saja — untuk multi-solusi, gunakan SolutionPackager.exe langsung dengan /SolutionName):

pac solution pack --zipfile SolutionA.zip --folder C:\repos\myrepo

Note

Saat menggunakan integrasi Dataverse Git asli dengan pengikatan lingkungan, semua solusi di lingkungan berbagi akar repositori tunggal menggunakan tata letak multi-solusi. Saat menggunakan pengikatan solusi, setiap solusi dapat terikat ke folder terpisah.

Bekerja dengan folder format YAML

Mengemas folder YAML ke dalam file .zip

# Using pac CLI (single solution in folder)
pac solution pack --zipfile C:\output\MySolution.zip --folder C:\repos\myrepo

# Using SolutionPackager.exe directly (also works for multi-solution with /SolutionName)
SolutionPackager.exe /action:Pack /zipfile:C:\output\MySolution.zip /folder:C:\repos\myrepo

Mendapatkan folder YAML lengkap dari Dataverse

Cara yang disarankan untuk mendapatkan folder YAML yang lengkap dan dapat dikemas adalah dengan menggunakan pac solution clone:

pac solution clone --name MySolutionUniqueName --outputDirectory C:\repos\myrepo

Ini mengekstrak solusi ke dalam format YAML, termasuk semua file sumber komponen. Atau, gunakan integrasi Git asli untuk berkomitmen dari Power Apps - file yang diterapkan dalam format YAML dan sepenuhnya dapat dikemas.

Verifikasi folder sebelum mengemas

Periksa apakah solutions/<name>/ folder ada dan bahwa semua jalur dalam solutioncomponents.yml mengatasi file aktual. Setiap jalur yang hilang mengakibatkan peringatan selama paket dan komponen tersebut dihilangkan.

Hubungan dengan integrasi Dataverse Git

Format kontrol sumber YAML adalah format kanonis yang digunakan oleh integrasi Dataverse Git. Ketika pembuat menerapkan solusi dari Power Apps, file yang ditulis ke Azure DevOps menggunakan format ini. Pengembang code-first dapat bekerja dengan repositori yang sama menggunakan alat CLI yang dijelaskan di sini.

Untuk informasi tentang menghubungkan lingkungan ke Git, lihat Penyiapan integrasi Dataverse Git.

Konten terkait

  • Last updated on