Como criar um arquivo de configuração do WinGet

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

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

Saiba mais sobre como usar o comando WinGet configure.

Formato de ficheiro

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 ajudar ainda mais a detetar se o formato do seu arquivo de configuração do WinGet é válido, recomendamos usar o Visual Studio Code com a extensão YAML da RedHat para oferecer suporte à sintaxe adequada, ajudar a detetar erros de formatação, fornecer suporte a foco e preenchimento automático (quando vinculado ao arquivo de esquema JSON) e garantir uma formatação válida.

Convenção de nomenclatura de arquivos

A convenção para nomear um arquivo de configuração do WinGet é usar 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, dadas as diferentes cadeias 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 principais:

Asserções: As pré-condições necessárias para executar a configuração.
Recursos: A lista de software e ferramentas a instalar, as definições de configuração para essas instalações e as definições de configurações para o sistema operacional Windows.

Secção Asserções

A lista de asserções abrange as pré-condições (ou pré-requisitos) necessários para que os recursos listados neste arquivo de configuração do WinGet sejam bem-sucedidos na máquina que executa o arquivo. As asserções podem ser completadas em paralelo e não requerem qualquer ordem sequencial.

Um exemplo de afirmação:

versão do SO: Uma versão mínima do sistema operativo* instalado na máquina. À medida que os recursos são adicionados ao sistema operativo ao longo do tempo, alguns são adaptados retroativamente para suportar versões anteriores, enquanto 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 ser suportado que é necessário para a configuração. Por exemplo, WinGet (Gerenciador de Pacotes do Windows) requer um mínimo de Windows 10, versão 1809 ou mais recente. Quaisquer versões mais antigas do Windows não suportam 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 código aberto.

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

Secção Recursos

A lista de Recursos abrange todos os softwares, ferramentas, pacotes, etc. que precisam ser instalados e as configurações para o 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

O seguinte é um exemplo de arquivo de configuração WinGet no formato configuration.winget.

# 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:

Schema: A primeira linha do ficheiro 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á a ser seguido pelo ficheiro. Para encontrar 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 que deve conter uma versão de configuração (configurationVersion: 0.2.0 neste exemplo). Esta versão deve ser atualizada de acordo com as atualizações do arquivo de configuração. O nó de propriedades deve conter um assertions nó e um resources nó.
Asserções: Liste as pré-condições (ou pré-requisitos) necessários para esta configuração nesta seção.
Recursos: Tanto a seção assertions quanto a lista resources consistem em nós individuais resource para representar a tarefa de configuração. O resource deve receber o nome do módulo PowerShell seguido do 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, também pode incluir um id valor. Ao aplicar uma configuração, o WinGet saberá instalar o módulo a partir do Galeria do PowerShell e invocar ode recursos DSC especificado.
Diretivas: A secção directives fornece informações sobre o módulo e o recurso. Esta seção deve incluir um valor description para descrever a tarefa de configuração que está sendo realizada pelo módulo. O valor allowPrerelease permite que você escolha se a configuração terá ou não permissão (true) para usar módulos de "Pré-lançamento" do PowerShell Gallery. Alguns recursos do DSC podem precisar ser executados com privilégios de administrador. O securityContext: elevated campo sob a seção de diretivas de um recurso indica esse requisito. Quando definido como elevated, o WinGet solicitará uma aprovação do UAC no início da configuração. 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 de pares nome-valor que são 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 reg ou o estabelecimento de uma configuração de rede específica.
Dependências: O valor dependsOn de um recurso determina se alguma outra asserção ou recurso precisa ser concluído antes de iniciar esta tarefa. Se a dependência falhar, este recurso também falhará automaticamente.
ID: Um identificador exclusivo para a instância de recurso específica. O id valor pode ser usado se outro recurso tiver uma dependência desse recurso que está sendo aplicado primeiro.

Organizando a seção Recursos

Há várias abordagens a serem consideradas ao determinar como organizar a seção Recursos do seu arquivo de configuração do WinGet. Pode organizar a sua lista de ficheiros da seguinte forma:

Ordem de execução: Organizar a sua lista de recursos de acordo com a ordem lógica em que 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 lugar, etc.
Possibilidade de falha: Organizar sua lista de recursos de acordo com a probabilidade de uma falha potencial pode ajudar os usuários a detetar problemas no início do processo de configuração e ajudá-los a entender por que as etapas restantes podem falhar, permitindo-lhes identificar e fazer 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 em metodologias de engenharia de software e pode ser a mais familiar para você ou para outros desenvolvedores que utilizam seu arquivo de configuração.

Recomendamos incluir um arquivo README.md com qualquer arquivo de configuração WinGet publicado em código aberto que inclua a abordagem organizacional da estrutura do arquivo.

Usando a variável ${WinGetConfigRoot}

Certos recursos DSC podem ter 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 onde o comando winget configure 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 da máquina. O recurso Microsoft.VisualStudio.DSC/VSComponents no exemplo acima demonstra esta funcionalidade ao utilizar 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 existe no caminho relativo com base no diretório de trabalho atual antes de executar o comando winget configure.

Onde encontrar módulos de recursos DSC do PowerShell

Confira a lista de recursos de configuração de estado desejado prontos para uso ("caixa de entrada") PowerShell que são suportados pela Microsoft, incluindo:

Ambiente: Gerencie uma variável de ambiente para uma máquina ou processo.
MsiPackage: Instale ou desinstale um pacote MSI.
do Registro: Gerir uma chave ou um valor de registro.
Script: Execute blocos de script do PowerShell.
Service: Gerenciar um serviço do Windows.
WindowsFeature: Instale ou desinstale uma função ou recurso do Windows.
WindowsProcess: Inicie ou pare um processo do Windows.

Você também pode encontrar os módulos de Recursos DSC do PowerShell no Galeria do PowerShell. Esta galeria hospeda centenas de módulos do PowerShell contendo recursos de configuração de estado desejado (DSC) enviados pela comunidade de usuários. Você pode filtrar os resultados da pesquisa aplicando o filtro "Recurso DSC" em "Categorias". Este repositório não está verificado pela Microsoft e contém recursos de uma variedade de autores e editores. Os módulos do PowerShell devem sempre ser revisados quanto à segurança e credibilidade antes de serem usados, pois qualquer script arbitrário pode ser incluído. Consulte 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.

Feedback

Esta página foi útil?

Last updated on 2025-05-03