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 de soluções do Power Apps, os ficheiros escritos para o fornecedor Git 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

• SolutionPackager Ferramenta
• 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