Como criar um arquivo de Configuração do WinGet

2025-05-06

Para criar um arquivo de Configuração do WinGet:

Crie um arquivo YAML seguindo a convenção de nomenclatura de arquivo de Configuração do WinGet.
Familiarize-se com o formato de um arquivo de configuração do WinGet e vincule o esquema de arquivo atual.
Determine a lista de Declarações (pré-condições necessárias) e Recursos (a lista de instalações e configurações necessárias para configurar o ambiente de desenvolvimento da máquina para o estado desejado) a ser incluída no arquivo.
Identifique os módulos do PowerShell e os recursos de DSC (Configuração de Estado Desejado) necessários para realizar as tarefas de configuração desejadas.
Determine as diretivas e as configurações necessárias para cada recurso de configuração.
Determine as dependências de cada recurso.

Saiba mais sobre como usar o comando de configuração do WinGet.

Formato de arquivo

O Gerenciador de Pacotes do Windows usa manifestos (arquivos YAML) para localizar e instalar pacotes para usuários do Windows. Os arquivos de Configuração do WinGet usam o mesmo formato de estilo YAML, adicionando uma especificação de esquema JSON para ajudar a definir a estrutura e a validação do arquivo. Para auxiliar ainda mais na detecção de se o formato do arquivo de Configuração do WinGet é válido, recomendamos usar o Visual Studio Code com a extensão YAML do RedHat para dar suporte à sintaxe adequada, ajudar a detectar erros de formatação, fornecer suporte ao foco e preenchimento automático (quando vinculado ao arquivo de esquema JSON) e garantir a formatação válida.

Convenção de nomenclatura de arquivo

A convenção para nomear um arquivo de Configuração do WinGet está usando a extensão de arquivo ".winget" (como configuration.winget). Para projetos baseados em Git, a configuração padrão deve ser armazenada em um diretório ".config" em: ./config/configuration.winget. Em alguns casos, mais de um arquivo de configuração pode ser apropriado devido a diferentes carrinhos de ferramentas ou preferências do usuário. Esses arquivos de configuração adicionais também devem estar localizados no diretório ".config".

Seções de um arquivo de configuração do WinGet

Um arquivo de Configuração do WinGet é separado em duas seções primárias:

Asserções: as pré-condições necessárias para executar a configuração.
Recursos: a lista de software e ferramentas a serem instaladas, as configurações dessas instalações e as configurações do sistema operacional Windows.

Seção Asserções

A lista de declarações abrange as pré-condições (ou pré-requisitos) necessárias para que os recursos listados neste arquivo de Configuração do WinGet tenham êxito no computador que executa o arquivo. As declarações podem ser concluídas em paralelo e não exigem nenhuma ordem sequencial.

Uma asserção de exemplo:

versão do sistema operacional: uma versão mínima do sistema operacional* instalada na máquina. À medida que os recursos são adicionados ao longo do tempo ao sistema operacional, alguns são retroportados para versões anteriores e outros não. É sempre útil verificar se há uma versão mínima do sistema operacional para determinar se uma ferramenta ou recurso específico pode ter suporte necessário para a configuração. Por exemplo, o WinGet (Gerenciador de Pacotes do Windows) requer um mínimo de Windows 10, versão 1809 ou mais recente. As versões mais antigas do Windows não dão suporte ao WinGet. * É possível que os Recursos DSC do PowerShell alterem o estado do sistema, mas não seria apropriado chamar o Windows Update e modificar a versão do sistema operacional na configuração do projeto para um projeto de software livre.

Se uma declaração retornar "false" para indicar que o sistema não está no estado desejado, qualquer Recurso que identifique essa declaração como uma dependência usando o campo dependsOn será ignorado e não será executado. Nesse caso, mesmo que nenhuma alteração de configuração tenha sido aplicada ao ambiente do Windows, essa configuração seria considerada um resultado bem-sucedido.

Seção Recursos

A lista de recursos abrange todos os softwares, ferramentas, pacotes etc. que precisam ser instalados e as configurações para seu sistema operacional Windows ou aplicativos instalados. Cada recurso precisará receber um nome, uma descrição da diretiva a ser executada e o módulo do PowerShell que será responsável por executar essa diretiva, bem como quaisquer configurações ou dependências associadas.

Exemplo de arquivo de configuração do WinGet

Aqui está um exemplo de arquivo de configuração do WinGet configuration.winget formatado:

# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2
properties:
  assertions:
    - resource: Microsoft.Windows.Developer/OsVersion
      directives:
        description: Verify min OS version requirement
        allowPrerelease: true
      settings:
        MinVersion: '10.0.22000'
  resources:
    - resource: Microsoft.Windows.Settings/WindowsSettings
      directives:
        description: Enable Developer Mode
        allowPrerelease: true
        securityContext: elevated
      settings:
        DeveloperMode: true
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      id: vsPackage
      directives:
        description: Install Visual Studio 2022 Community
        securityContext: elevated
      settings:
        id: Microsoft.VisualStudio.2022.Community
        source: winget
    - resource: Microsoft.VisualStudio.DSC/VSComponents
      dependsOn:
        - vsPackage
      directives:
        description: Install required VS workloads from vsconfig file
        allowPrerelease: true
        securityContext: elevated
      settings:
        productId: Microsoft.VisualStudio.Product.Community
        channelId: VisualStudio.17.Release
        vsConfigFile: '${WinGetConfigRoot}\..\.vsconfig'
        includeRecommended: true
  configurationVersion: 0.2.0

Os componentes deste arquivo consistem em:

Esquema: a primeira linha no arquivo de configuração deve conter o seguinte comentário: # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/<most recent schema version #> para estabelecer o esquema DSC que está sendo seguido pelo arquivo. Para localizar a versão mais recente do esquema de Configuração do WinGet, vá para https://aka.ms/configuration-dsc-schema/. O número de esquema mais recente no momento deste exemplo é 0.2, portanto, o esquema foi inserido como: # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2.
Propriedades: o nó raiz de um arquivo de configuração é properties o qual deve conter uma versão de configuração (configurationVersion: 0.2.0 neste exemplo). Essa versão deve ser atualizada de acordo com as atualizações do arquivo de configuração. O nó de propriedades deve conter um nó assertions e um nó resources.
Declarações: liste as pré-condições (ou pré-requisitos) necessários para essa configuração nesta seção.
Resources: Ambas as seções assertions e resources lista consistem em nós resource individuais para representar a tarefa configurada. O resource nome do módulo do PowerShell deve ser fornecido seguido pelo nome do recurso DSC do módulo que será invocado para aplicar o estado desejado: {ModuleName}/{DscResource}. Cada recurso deve incluir directives e settings. Opcionalmente, ele também pode incluir um id valor. Ao aplicar uma configuração, o WinGet saberá instalar o módulo do da Galeria do PowerShell e invocar o recurso de DSC especificado.
Diretivas: a directives seção fornece informações sobre o módulo e o recurso. Esta seção deve incluir um description valor para descrever a tarefa de configuração que está sendo realizada pelo módulo. O valor permite que você escolha se a configuração será permitida ou não () para usar módulos "Pré-lançamento" doda Galeria PowerShell. Alguns recursos de DSC podem precisar ser executados com privilégios de administrador. O securityContext: elevated campo na seção diretivas de um recurso indica esse requisito. Quando definido como elevated, o WinGet solicitará uma aprovação UAC no início da configuração. Em seguida, o WinGet iniciará dois processos: um que executa recursos com privilégios elevados e outro que executa recursos com privilégios do usuário atual.
Configurações: o valor settings de um recurso representa a coleção dos pares nome-valor que estão sendo passados para o Recurso DSC do PowerShell. As configurações podem representar qualquer coisa, desde se o Modo de Desenvolvedor está habilitado, até a aplicação de uma chave de reg ou o estabelecimento de uma configuração de rede específica.
Dependências: O valor do recurso dependsOn determina se qualquer outra afirmação ou recurso deve ser concluído antes do início desta tarefa. Se a dependência falhar, esse recurso também falhará automaticamente.
ID: um identificador exclusivo para a instância de recurso específica. O valor id pode ser usado se outro recurso tiver uma dependência de este ser aplicado primeiro.

Organizando a seção Recursos

Há várias abordagens a serem consideradas ao determinar como organizar a seção Recursos do arquivo de Configuração do WinGet. Você pode organizar sua lista de arquivos:

Ordem de execução: organizando sua lista de recursos de acordo com a ordem lógica na qual eles devem ser executados. Essa abordagem pode ajudar o usuário a entender e acompanhar as etapas de automação que estão sendo executadas depois que o arquivo é executado – o que é instalado primeiro, segundo, qual configuração é atualizada em terceiro, etc.
Possibilidade de falha: organizar sua lista de recursos de acordo com a probabilidade de uma possível falha pode ajudar os usuários a detectar problemas no início do processo de configuração e ajudá-los a entender por que as etapas restantes podem falhar, permitindo que eles identifiquem e façam as alterações necessárias antes que muito tempo seja investido.
Agrupar tipos de recursos semelhantes: organizar sua lista de recursos agrupando tipos de recursos semelhantes é uma abordagem comum nas metodologias de engenharia de software e pode ser a mais familiar para você ou para outros desenvolvedores que utilizam seu arquivo de configuração.

É recomendável incluir um arquivo README.md com qualquer arquivo de Configuração do WinGet publicado em Software Livre que inclua a abordagem organizacional da estrutura de arquivos.

Usando a variável ${WinGetConfigRoot}

Determinados recursos DSC podem receber um parâmetro que especifica o caminho de um arquivo. Em vez de especificar o caminho completo, você pode usar a variável ${WinGetConfigRoot} para definir o diretório de trabalho em que o winget configure comando está sendo executado e acrescentar o caminho relativo para apontar para esse arquivo. Isso é útil para generalizar um arquivo de configuração para que ele seja independente do computador. O recurso Microsoft.VisualStudio.DSC/VSComponents no exemplo acima demonstra essa funcionalidade utilizando o ${WinGetConfigRoot} para apontar para um arquivo .vsconfig no diretório raiz de um projeto. Isso também significa que o usuário deve garantir que o arquivo de destino exista no caminho relativo com base no diretório de trabalho atual antes de executar o winget configure comando.

Onde encontrar módulos de recursos DSC do PowerShell

Confira a lista de recursos prontos para uso ("caixa de entrada") recursos de configuração de estado desejados do PowerShell compatíveis com a Microsoft, incluindo:

Ambiente: gerenciar uma variável de ambiente para um computador ou processo.
MsiPackage: instalar ou desinstalar um pacote MSI.
Registro: gerenciar uma chave ou valor do registro.
Script: executar blocos de script do PowerShell.
Serviço: Gerenciar um serviço do Windows.
WindowsFeature: instalar ou desinstalar uma função ou recurso do Windows.
WindowsProcess: Inicie ou pare um processo do Windows.

Você também pode encontrar módulos de Recursos DSC na Galeria do PowerShell . Esta galeria hospeda centenas de módulos do PowerShell que contêm recursos de DSC (Desired State Configuration) enviados pela comunidade de usuários. Você pode filtrar os resultados da pesquisa aplicando o filtro "Recurso DSC" em "Categorias". Esse repositório não é verificado pela Microsoft e contém recursos de uma variedade de autores e editores. Os módulos do PowerShell sempre devem ser revisados quanto à segurança e à credibilidade antes de serem usados como qualquer script arbitrário pode ser incluído. Veja como verificar a confiabilidade de um arquivo de Configuração do WinGet para obter mais dicas sobre como criar um arquivo de Configuração do WinGet confiável.