Referencia do formato de control de versión YAML da solución

Este artigo é unha referencia para o formato de control de versións baseado en YAML usado cando ti:

Confirma solucións usando integración nativa Dataverse Git en Power Apps.
Extraer solucións usando pac solution clone ou pac solution sync.
Executa manualmente SolutionPackager nunha carpeta que conteña ficheiros de manifestos YAML.

O formato YAML difire do formato clásico XML. Entender a estrutura é importante cando queres empaquetar manualmente unha carpeta YAML nun .zip ficheiro que Dataverse poida importar.

Importante

O soporte para o formato de control de versións YAML na CLI pac require Microsoft. PowerApps.CLI versión 2.4.1 ou posterior. Descarga a última versión de NuGet ou actualízaa a través de pac install latest. SolutionPackager.exe, que vén co paquete NuGet, soporta o formato YAML da mesma versión.

Visión xeral da estrutura de carpetas

A raíz dun repositorio en formato YAML contén os seguintes directorios de nivel superior:

<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]/

Os solutions/ directorios e publishers/ son obrigatorios. Todas as carpetas de compoñentes na raíz son opcionais e dependen do que conteña a solución.

Importante

Todos os ficheiros de manifestos YAML (solution.yml, publisher.yml, e así sucesivamente) deben colocarse baixo os seus respectivos subdirectorios (solutions/<name>/, publishers/<name>/). Colocalos na raíz do repositorio evita a detección de formatos e fai que a ferramenta SolutionPackager volva ao formato XML, xerando un erro enganoso sobre a falta Customizations.xmlde . Máis información: Solución de problemas da ferramenta SolutionPackager

Detección automática de formato

SolutionPackager (e pac solution pack) detectan automaticamente o formato do seguinte xeito:

Condición	Formato detectado	Comportamento
`solutions/*/solution.yml` atopada — unha solución	YAML	Nome da solución inferido do nome da subcarpeta
`solutions/*/solution.yml` atopado — múltiples solucións	YAML	`/SolutionName` argumento necesario para especificar que solución empaquetar
Non hai `solutions/` subdirectorio	XML (legado)	Expectativas `Other\Solution.xml` e `Other\Customizations.xml`

Arquivos de manifesto

solution.yml

Situado en solutions/<SolutionUniqueName>/solution.yml. Contén metadatos de solución de nivel superior — o equivalente en YAML no solution.xml formato XML.

Os campos clave inclúen o nome único da solución, a versión, o nome amigo, a descrición e unha referencia ao editor.

solutioncomponents.yml

Situado en solutions/<SolutionUniqueName>/solutioncomponents.yml. Lista rutas relativas a todos os ficheiros de compoñentes incluídos nesta solución. SolutionPackager le este ficheiro durante o pack para localizar as fontes de compoñentes.

Exemplo de extracto:

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

rootcomponents.yml

Situado en solutions/<SolutionUniqueName>/rootcomponents.yml. Lista os compoñentes a nivel raíz (normalmente as táboas e outros obxectos de nivel superior) que pertencen a esta solución.

Nota

Se un compoñente está declarado en rootcomponents.yml pero os seus ficheiros fonte están ausentes na carpeta (por exemplo, un ficheiro de aplicación .msapp canvas baixo canvasapps/<name>/), SolutionPackager emite un aviso e omite ese compoñente do arquivo empaquetado .zip. A operación do paquete aínda se completa con éxito co código de saída 0.

O éxito do pack non garante o éxito das importacións. Se solutioncomponents.yml omite os camiños de dependencia necesarios — como cartafoles de entidades nais ou definicións de relación baixo entityrelationships/ — a solución empaqueta sen erro pero falla na importación cunha mensaxe como: "Os atributos carecen de definicións de relación asociadas." Sempre asegúrate solutioncomponents.yml de incluír todas as entidades e relacións dependentes, non só as que son propiedade da solución.

missingdependencies.yml

Situado en solutions/<SolutionUniqueName>/missingdependencies.yml. Rexistra calquera dependencia da solución que non estivese presente cando a solución foi exportada por última vez. Úsase con fins informativos e para validar a completitude na importación.

publisher.yml

Situado en publishers/<PublisherUniqueName>/publisher.yml. Contén a definición do editor — nome único, nome para mostrar, prefixo de personalización e prefixo de valor de opción.

Estrutura mínima requirida:

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:

Soporte de tipos de compoñentes

A seguinte táboa mostra como se xestiona cada tipo de compoñente no formato YAML.

Tipo de compoñente	En formato YAML	Notas
Entidades (táboas), atributos, formas, vistas	✓ Ficheiros YAML	Almacénanse como ficheiros YAML individuais por subcompoñente
Fluxos de traballo (clásico)	✓ Ficheiros YAML	Baixo `workflows/`
Fluxos modernos (fluxos na nube de Power Automate)	✓ — só formato YAML	Baixo `modernflows/`; non soportado en formato XML
Aplicacións de lenzo	✓ — só formato YAML	`.msapp` binario baixo `canvasapps/<name>/`; non soportado en formato XML
Definicións de variables de ambiente	✓ Ficheiros XML	Ficheiros individuais `.xml` baixo `environmentvariabledefinitions/`
Valores das variables de ambiente	✓ Ficheiro JSON	Almacenado como `environment_variable_values.json`
Conectores personalizados	✓	Baixo `connectors/`
Conxuntos enchufables	✓	Nomes de tipo totalmente cualificados reasignados por defecto (`/remapPluginTypeNames`)
Recursos web	✓	Baixo `webresources/`
Roles de seguranza	✓	Almacenado internamente como XML; filtrado por solución
Conxuntos de opcións (globais)	✓	Almacenado en XML; filtrado por solución
Paneis	✓	Almacenado en XML; filtrado por solución
Mapas do sitio	✓	Almacenado en XML; filtrado por solución
Personalizacións da cinta	✓	Almacenado en XML; filtrado por solución
Relacións entre entidades	✓	Baixo `entityrelationships/`

Nota

Os compoñentes almacenados internamente como XML convértense automaticamente entre XML e YAML durante as operacións de empaquetado e desempacado. Podes crealos como ficheiros YAML; A ferramenta encárgase da conversión.

Repositorios multi-solución

Unha única raíz de repositorio pode conter múltiples solucións. Todas as solucións comparten os mesmos cartafoles de compoñentes; solutioncomponents.yml en cada solución controla que camiños de compoñentes pertencen a esa solución.

Exemplo de estrutura con dúas solucións:

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

Empaquetar unha solución específica dunha carpeta multi-solución

Usando SolutionPackager.exe:

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

Usando pac solution pack (só cartafoles de solución única — para multisolución, usa SolutionPackager.exe directamente con /SolutionName):

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

Nota

Ao usar integración nativa de Dataverse Git con enlace de entorno, todas as solucións do entorno comparten unha única raíz de repositorio usando o deseño multi-solución. Ao usar a unión de solucións, cada solución pode vincularse a unha carpeta separada.

Traballando con cartafoles en formato YAML

Empaqueta unha carpeta YAML nun arquivo .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

Obter unha carpeta YAML completa de Dataverse

A forma recomendada de obter unha carpeta YAML completa e empaquetable é usar pac solution clone:

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

Isto extrae a solución ao formato YAML, incluíndo todos os ficheiros fonte dos compoñentes. Alternativamente, usa integración nativa con Git para facer commit desde Power Apps — os ficheiros comprometidos están en formato YAML e son totalmente empaquetables.

Verifica a carpeta antes de empaquetar

Comproba que a solutions/<name>/ carpeta exista e que todos os camiños se solutioncomponents.yml resolvan a ficheiros reais. Calquera camiño que falte provoca avisos durante o empaquetado e eses compoñentes son omitidos.

Relación coa integración Git de Dataverse

O formato de control de versións YAML é o formato canónico usado pola integración Git de Dataverse. Cando os creadores commiten solucións de Power Apps, os ficheiros escritos en Azure DevOps usan este formato. Os desenvolvedores de código primeiro poden traballar co mesmo repositorio usando as ferramentas CLI descritas aquí.

Para información sobre como conectar ambientes a Git, véxase configuración de integración Dataverse con Git.

Comentarios

Resultoulle útil esta páxina?

Last updated on 2026-04-10

Referencia do formato de control de versión YAML da solución

Visión xeral da estrutura de carpetas

Detección automática de formato

Arquivos de manifesto

solution.yml

solutioncomponents.yml

rootcomponents.yml

missingdependencies.yml

publisher.yml

Soporte de tipos de compoñentes

Repositorios multi-solución

Empaquetar unha solución específica dunha carpeta multi-solución

Traballando con cartafoles en formato YAML

Empaqueta unha carpeta YAML nun arquivo .zip

Obter unha carpeta YAML completa de Dataverse

Verifica a carpeta antes de empaquetar

Relación coa integración Git de Dataverse

Contido relacionado

Comentarios

Recursos adicionais