Como criar um arquivo de Configuração do WinGet

Artigo
09/28/2023

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 necessárias e configurações para colocar o ambiente de desenvolvimento do computador no estado desejado) a serem incluídos no arquivo.
Identifique os módulos do PowerShell e os recursos de DSC (Desired State Configuration) necessários para realizar as tarefas de configuração desejadas.
Determine as diretrizes 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 WinGet configure.

Formato de arquivo

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

Convenção de nomenclatura de arquivo

A convenção para nomear um arquivo de Configuração do WinGet é configuration.dsc.yaml. Para projetos baseados em Git, a configuração padrão deve ser armazenada em um diretório "configurations" em: ./configurations/configuration.dsc.yaml.

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

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

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

Seção Declaraçõ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 declaração de exemplo:

Versão do sistema operacional: uma versão mínima do sistema operacional* instalado no computador. À medida que os recursos são adicionados ao longo do tempo ao sistema operacional, alguns têm suporte retroativo para versões anteriores e outros não. É sempre útil considerar uma versão mínima do sistema operacional para determinar se uma ferramenta ou recurso específico necessário para a configuração é ou não compatível. Por exemplo, o WinGet (Gerenciador de Pacotes do Windows) requer no mínimo o 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 de DSC do PowerShell alterem o estado do sistema, mas não seria apropriado chamar Windows Update e modificar a versão do sistema operacional na configuração do projeto para um projeto de software livre.

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

Seção de recursos

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

A seguir um exemplo de arquivo de Configuração do WinGet configuration.dsc.yaml 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.Developer/DeveloperMode
      directives:
        description: Enable Developer Mode
        allowPrerelease: true
      settings:
        Ensure: Present
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      id: vsPackage
      directives:
        description: Install Visual Studio 2022 Community
        allowPrerelease: true
      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
      settings:
        productId: Microsoft.VisualStudio.Product.Community
        channelId: VisualStudio.17.Release
        vsConfigFile: '${WinGetConfigRoot}\..\.vsconfig'
        includeRecommended: true
  configurationVersion: 0.2.0

Os componentes desse arquivo consistem de:

Esquema: a primeira linha do arquivo de configuração deve conter o 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 encontrar a versão mais recente do esquema de Configuração do WinGet, acesse 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, que precisa 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 os pré-requisitos) necessários para essa configuração nesta seção.
Recurso: as seções de lista assertions e 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á chamado para aplicar o estado desejado: {ModuleName}/{DscResource}. Cada recurso deve incluir directives e settings. Opcionalmente, ele também pode incluir um valor de id. Ao aplicar uma configuração, o WinGet saberá instalar o módulo da Galeria do PowerShell e invocar o recurso DSC especificado.
Diretrizes: a seçã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" da Galeria do PowerShell.
Configurações: o valor settings de um recurso representa a coleção de 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 do Registro ou o estabelecimento de uma configuração de rede específica.
Dependências: o valor dependsOn de um recurso determina se qualquer outra declaração ou recurso precisa ser concluído antes de iniciar essa 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 de id poderá ser usado se outro recurso tiver uma dependência desse recurso sendo aplicada primeiro.

Organizar 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 por:

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 realizadas depois que o arquivo é executado – o que é instalado por primeiro, por 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 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 de README.md com qualquer arquivo de Configuração do WinGet publicado de software livre que inclua a abordagem organizacional da estrutura de arquivos.

Usando a variável ${WinGetConfigRoot}

Certos 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 comando winget configure está sendo executado e anexar 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 mostra 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 comando winget configure.

Onde encontrar módulos de recurso DSC do PowerShell

Confira a lista de Recursos de Desired State Configuration do PowerShell prontos para uso ("caixa de entrada") que recebem suporte da Microsoft, incluindo:

Ambiente: gerencie uma variável de ambiente para um computador ou processo.
MsiPackage: instale ou desinstale um pacote MSI.
Registro: gerencie uma chave ou valor do Registro.
Script: execute blocos de script do PowerShell.
Serviço: gerencie um serviço Windows.
WindowsFeature: instale ou desinstale uma função ou recurso do Windows.
WindowsProcess: inicie ou interrompa um processo do Windows.

Você também pode encontrar módulos de recurso DSC do PowerShell na Galeria do PowerShell. Essa galeria hospeda centenas de módulos do PowerShell que contêm recursos da DSC (Desired State Configuration) aprovados pelos usuários da comunidade. 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, pois qualquer script arbitrário pode ser incluído. Consulte Como garantir a confiabilidade de um arquivo de Configuração do WinGet para obter mais dicas sobre como criar um arquivo de configuração confiável do WinGet.