Referência do formato de controle do código-fonte YAML da solução

Este artigo é uma referência para o formato de controle do código-fonte baseado em YAML usado quando você:

Confirme soluções usando a integração do Git do Dataverse no Power Apps.
Extrair soluções usando pac solution clone ou pac solution sync.
Execute manualmente o SolutionPackager em uma pasta que contém arquivos de manifesto YAML.

O formato YAML difere do layout XML clássico. Entender a estrutura é importante quando você deseja empacotar manualmente uma pasta YAML de volta em um .zip arquivo que o Dataverse pode importar.

Importante

O suporte ao formato de controle do código-fonte YAML na CLI do pac requer Microsoft. PowerApps.CLI versão 2.4.1 ou posterior. Baixe a versão mais recente do NuGet ou atualize por pac install latest. SolutionPackager.exe, que é fornecido com o pacote NuGet, dá suporte ao formato YAML da mesma versão.

Visão geral da estrutura de pastas

Uma raiz do repositório de formato YAML contém os seguintes diretórios de nível 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/ diretórios e os diretórios publishers/ são necessários. Todas as pastas de componente na raiz são opcionais e dependem do que a solução contém.

Importante

Todos os arquivos de manifesto YAML (solution.ymlpublisher.ymle assim por diante) devem ser colocados sob seus respectivos subdiretórios (solutions/<name>/, publishers/<name>/). Colocá-los na raiz do repositório impede a detecção de formato e faz com que a ferramenta SolutionPackager retorne ao formato XML, produzindo um erro enganoso sobre uma falta Customizations.xml. Mais informações: Solução de problemas da ferramenta SolutionPackager

Formatar detecção automática

SolutionPackager (e pac solution pack) detecta automaticamente o formato da seguinte maneira:

Condição	Formato detectado	Comportamento
`solutions/*/solution.yml` encontrado – uma solução	YAML	Nome da solução inferido do nome da subpasta
`solutions/*/solution.yml` encontrado – várias soluções	YAML	`/SolutionName` argumento necessário para especificar qual solução empacotar
Nenhum `solutions/` subdiretório presente	XML (herdado)	`Other\Solution.xml` Espera e`Other\Customizations.xml`

Ficheiros de manifesto

solution.yml

Localizado em solutions/<SolutionUniqueName>/solution.yml. Contém metadados de solução de nível superior – o equivalente solution.xml YAML no formato XML.

Os campos de chave incluem o nome exclusivo da solução, a versão, o nome amigável, a descrição e uma referência ao editor.

solutioncomponents.yml

Localizado em solutions/<SolutionUniqueName>/solutioncomponents.yml. Lista caminhos relativos para todos os arquivos de componente incluídos nesta solução. SolutionPackager lê esse arquivo durante o pacote para localizar fontes de componente.

Trecho de exemplo:

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

rootcomponents.yml

Localizado em solutions/<SolutionUniqueName>/rootcomponents.yml. Lista os componentes de nível raiz (normalmente tabelas e outros objetos de nível superior) que pertencem a essa solução.

Observação

Se um componente for declarado, rootcomponents.yml mas seus arquivos de origem estiverem ausentes da pasta (por exemplo, um arquivo de aplicativo .msapp de tela em canvasapps/<name>/), SolutionPackager emitirá um aviso e omitirá esse componente do pacote .zip. A operação do pacote ainda é concluída com êxito com o código de saída 0.

O sucesso do pacote não garante o sucesso da importação. Se solutioncomponents.yml omitir caminhos de dependência necessários , como pastas de entidade pai ou definições de relação em – entityrelationships/ a solução empacota sem erro, mas falha ao importar com uma mensagem como: "Atributos estão faltando definições de relação associadas". Sempre certifique-se de incluir solutioncomponents.yml todas as entidades e relações dependentes, não apenas as de propriedade da solução.

missingdependencies.yml

Localizado em solutions/<SolutionUniqueName>/missingdependencies.yml. Registra as dependências de solução que não estavam presentes quando a solução foi exportada pela última vez. Usado para fins informativos e para validar a integridade na importação.

publisher.yml

Localizado em publishers/<PublisherUniqueName>/publisher.yml. Contém a definição do editor — nome exclusivo, nome de exibição, prefixo de personalização e prefixo de valor de opção.

Estrutura mínima necessária:

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:

Suporte ao tipo de componente

A tabela a seguir lista como cada tipo de componente é tratado no formato YAML.

Tipo de componente	No formato YAML	Observações
Entidades (tabelas), atributos, formulários, exibições	✓ Arquivos YAML	Armazenados como arquivos YAML individuais por subcomponente
Fluxos de trabalho (clássico)	✓ Arquivos YAML	Em `workflows/`
Fluxos modernos (fluxos de nuvem Power Automate)	✓ — somente formato YAML	Em `modernflows/`; sem suporte no formato XML
Aplicativos Canvas	✓ — somente formato YAML	`.msapp` binário em `canvasapps/<name>/`; sem suporte no formato XML
Definições de variável de ambiente	✓ Arquivos XML	Arquivos individuais `.xml` em `environmentvariabledefinitions/`
Valores de variável de ambiente	✓ Arquivo JSON	Armazenado como `environment_variable_values.json`
Conectores personalizados	✓	Em `connectors/`
Assemblies de plug-in	✓	Nomes de tipo totalmente qualificados remapeados por padrão (`/remapPluginTypeNames`)
Recursos da Web	✓	Em `webresources/`
Funções de segurança	✓	Armazenado como XML internamente; filtrado por solução
Conjuntos de opções (global)	✓	Armazenado como XML; filtrado por solução
Dashboards	✓	Armazenado como XML; filtrado por solução
Mapas do site	✓	Armazenado como XML; filtrado por solução
Personalizações da faixa de opções	✓	Armazenado como XML; filtrado por solução
Relações de entidade	✓	Em `entityrelationships/`

Observação

Os componentes armazenados como XML internamente são convertidos automaticamente entre XML e YAML durante operações de pacote e desempacotamento. Você pode criar como arquivos YAML; a ferramenta manipula a conversão.

Repositórios de várias soluções

Uma única raiz de repositório pode conter várias soluções. Todas as soluções compartilham as mesmas pastas de componente; solutioncomponents.yml em cada solução controla quais caminhos de componente pertencem a essa solução.

Estrutura de exemplo com duas soluções:

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

Empacotando uma solução específica de uma pasta de várias soluções

Usando SolutionPackager.exe:

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

Usando pac solution pack (somente pastas de solução única – para várias soluções, use SolutionPackager.exe diretamente com /SolutionName):

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

Observação

Ao usar a integração nativa do Dataverse Git com a associação de ambiente, todas as soluções no ambiente compartilham uma única raiz de repositório usando o layout de várias soluções. Ao usar a associação de solução, cada solução pode ser associada a uma pasta separada.

Trabalhando com pastas de formato YAML

Empacotar uma pasta YAML em um 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 uma pasta YAML completa do Dataverse

A maneira recomendada de obter uma pasta YAML completa e empacotável é usar pac solution clone:

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

Isso extrai a solução para o formato YAML, incluindo todos os arquivos de origem do componente. Como alternativa, use a integração nativa do Git para confirmar de Power Apps – os arquivos confirmados estão no formato YAML e totalmente empacotáveis.

Verificar a pasta antes de empacotar

Verifique se a solutions/<name>/ pasta existe e se todos os caminhos são solutioncomponents.yml resolvidos para arquivos reais. Quaisquer caminhos ausentes resultam em avisos durante o pacote e esses componentes são omitidos.

Relação com a integração do Git do Dataverse

O formato de controle do código-fonte YAML é o formato canônico usado pela integração do Dataverse Git. Quando os criadores confirmam soluções de Power Apps, os arquivos gravados em Azure DevOps usam esse formato. Os desenvolvedores de primeiro código podem trabalhar com o mesmo repositório usando as ferramentas da CLI descritas aqui.

Para obter informações sobre como conectar ambientes ao Git, consulte a configuração de integração do Dataverse Git.

Comentários

Esta página foi útil?

Last updated on 2026-04-10

Compartilhar via

Referência do formato de controle do código-fonte YAML da solução

Visão geral da estrutura de pastas

Formatar detecção automática

Ficheiros de manifesto

solution.yml

solutioncomponents.yml

rootcomponents.yml

missingdependencies.yml

publisher.yml

Suporte ao tipo de componente

Repositórios de várias soluções

Empacotando uma solução específica de uma pasta de várias soluções

Trabalhando com pastas de formato YAML

Empacotar uma pasta YAML em um arquivo .zip

Obter uma pasta YAML completa do Dataverse

Verificar a pasta antes de empacotar

Relação com a integração do Git do Dataverse

Conteúdo relacionado

Comentários

Recursos adicionais