Referência do formato de controlo de versões YAML da solução

Este artigo é uma referência para o formato de controlo de versões baseado em YAML usado quando se segue:

• Soluções de commit usando integração nativa Dataverse Git em Power Apps.
• Extrair soluções usando pac solution clone ou pac solution sync.
• Execute manualmente o SolutionPackager numa pasta que contenha ficheiros de manifestos YAML.

O formato YAML difere do layout clássico XML. Compreender a estrutura é importante quando se quer empacotar manualmente uma pasta YAML num .zip ficheiro que o Dataverse possa importar.

Visão geral da estrutura da pasta

A raiz de um repositório em formato YAML contém os seguintes diretórios de topo:

<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 publishers/ são obrigatórios. Todas as pastas componentes na raiz são opcionais e dependem do que a solução contém.

Deteção automática de formato

O SolutionPackager (e pac solution pack) detetam automaticamente o formato da seguinte forma:

Ficheiros de manifesto

solution.yml

Localizado em solutions/<SolutionUniqueName>/solution.yml. Contém metadados de solução de topo — o equivalente YAML a solution.xml no formato XML.

Os campos-chave incluem o nome único da solução, versão, nome amigo, descrição e uma referência ao editor.

solutioncomponents.yml

Localizado em solutions/<SolutionUniqueName>/solutioncomponents.yml. Lista caminhos relativos a todos os ficheiros de componentes incluídos nesta solução. O SolutionPackager lê este ficheiro durante o pack para localizar as fontes dos componentes.

Excerto 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 ao nível raiz (tipicamente tabelas e outros objetos de topo) que pertencem a esta solução.

missingdependencies.yml

Localizado em solutions/<SolutionUniqueName>/missingdependencies.yml. Regista quaisquer dependências da solução que não estivessem presentes quando a solução foi exportada pela última vez. Usado para fins informativos e para validar a completude na importação.

publisher.yml

Localizado em publishers/<PublisherUniqueName>/publisher.yml. Contém a definição do editor — nome único, nome de visualizaçã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 a tipos de componentes

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

Repositórios multi-solução

A raiz de um único repositório pode conter múltiplas soluções. Todas as soluções partilham as mesmas pastas de componentes; solutioncomponents.yml em cada solução controla quais os caminhos dos componentes que pertencem a essa solução.

Exemplo de estrutura 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/

Empacotamento de uma solução específica a partir de uma pasta multi-solução

Usando SolutionPackager.exe:

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

Usando pac solution pack (apenas pastas de solução única — para multisolução, use SolutionPackager.exe diretamente com /SolutionName):

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

A trabalhar com pastas em formato YAML

Empacota uma pasta YAML num ficheiro .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

Obtenha uma pasta YAML completa do Dataverse

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

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

Isto extrai a solução para o formato YAML, incluindo todos os ficheiros fonte dos componentes. Alternativamente, use integração nativa com Git para fazer commit a partir do Power Apps — os ficheiros comprometidos estão em formato YAML e são totalmente empacotáveis.

Verifique a pasta antes de empacotar

Verifica se a solutions/<name>/ pasta existe e se todos os caminhos resolvem solutioncomponents.yml para ficheiros reais. Quaisquer caminhos em falta resultam em avisos durante a embalagem e esses componentes são omitidos.

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

O formato de controlo de versões YAML é o formato canónico utilizado pela integração Dataverse Git. Quando os criadores fazem commit das soluções do Power Apps, os ficheiros escritos no Azure DevOps utilizam este formato. Os programadores de código em primeiro lugar podem trabalhar com o mesmo repositório usando as ferramentas de CLI descritas aqui.

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

Conteúdo relacionado

• Ferramenta SolutionPackager
• Controlo de versões com ficheiros de solução
• Pacote de Soluções PAC
• Solução PAC desembalar
• Visão geral da integração Dataverse Git