Criar o manifesto do pacote

  • Artigo

Se você deseja enviar um pacote de software para o Repositório da Community do Gerenciador de Pacotes do Windows, comece criando um manifesto do pacote. O manifesto é um arquivo YAML que descreve o aplicativo a ser instalado.

Você pode usar o Criador de Manifestos do Gerenciador de Pacotes do Windows, o script YAMLCreate do PowerShell ou pode criar um manifesto manualmente seguindo as instruções abaixo.

Observação

Confira as Perguntas frequentes sobre manifestos abaixo para obter mais informações gerais de alto nível explicando manifestos, pacotes e versões.

Opções para criação de manifesto

Usando o Utilitário WinGetCreate

Você pode instalar o utilitário wingetcreate usando o comando a seguir.

winget install wingetcreate

Após a instalação, você pode executar wingetcreate new para criar um pacote e preencher os prompts. A última opção que WinGetCreate oferecerá é a de enviar o manifesto para o repositório de pacotes. Se você aceitar, enviará automaticamente sua PR (solicitação de pull) para o Repositório da Community do Gerenciador de Pacotes do Windows.

Usando YAMLCreate.ps1

Para ajudar a escrever arquivos de manifesto, fornecemos o script do PowerShell YAMLCreate.ps1, localizado na pasta Ferramentas no Repositório da Comunidade do Gerenciador de Pacotes do Windows. Você pode usar o script clonando o repositório no seu PC e executando o script diretamente da pasta Ferramentas. O script solicitará a URL para o instalador e solicitará que você preencha os metadados. Semelhante ao uso de WinGetCreate, esse script oferecerá a opção de enviar seu manifesto automaticamente.

Noções básicas sobre YAML

O formato YAML foi escolhido para manifestos do pacote devido à facilidade relativa de legibilidade por humanos à consistência com outras ferramentas de desenvolvimento da Microsoft. Se você não estiver familiarizado com a sintaxe do YAML, poderá aprender as noções básicas em Aprender sobre o YAML em Y minutos.

Observação

No momento, os manifestos do Gerenciador de Pacotes do Windows não dão suporte a todos os recursos do YAML. Os recursos do YAML sem suporte incluem âncoras, chaves complexas e conjuntos.

Convenções

Essas convenções são usadas neste artigo:

  • À esquerda de :, há uma palavra-chave literal usada em definições de manifesto.
  • À direita de :, há um tipo de dados. O tipo de dados pode ser um tipo primitivo como cadeia de caracteres ou uma referência a uma estrutura avançada definida em outro lugar neste artigo.
  • A notação [datatype] indica uma matriz do tipo de dados mencionado. Por exemplo, [ string ] é uma matriz de cadeias de caracteres.
  • A notação {datatype:datatype} indica um mapeamento de um tipo de dados para outro. Por exemplo, { string: string } é um mapeamento de cadeias de caracteres para cadeias de caracteres.

Conteúdo do manifesto

Um manifesto do pacote consiste em itens necessários e itens opcionais que podem ajudar a aprimorar a experiência do cliente com a instalação do seu software. Esta seção fornece um breve resumo do esquema de manifesto necessário e dos esquemas de manifesto completos com exemplos de cada um.

Cada campo no arquivo de manifesto deve ser escrito na formatação Pascal e não pode ser duplicado.

Para obter uma lista completa e descrições de itens em um manifesto, confira a especificação de manifesto no Repositório da comunidade do Gerenciador de Pacotes do Windows.

Esquema mínimo necessário

Conforme especificado no esquema JSON singleton, somente determinados campos são obrigatórios. O arquivo YAML mínimo com suporte seria semelhante ao exemplo abaixo. O formato singleton só é válido para pacotes que contenham um único instalador e uma única localidade. Se mais de um instalador ou uma localidade for fornecido, o esquema e o formato do arquivo YAML múltiplo deverão ser usados.

O esquema de particionamento foi adicionado para ajudar com a UX do GitHub. As pastas com milhares de filhos não são bem renderizadas no navegador.

PackageIdentifier:  # Publisher.package format.
PackageVersion:     # Version numbering format.
PackageLocale:      # BCP 47 format (e.g. en-US)
Publisher:          # The name of the publisher.
PackageName:        # The name of the application.
License:            # The license of the application.
ShortDescription:   # The description of the application.
Installers: 
 - Architecture:    # Enumeration of supported architectures.
   InstallerType:   # Enumeration of supported installer types (exe, msi, msix, inno, wix, nullsoft, appx).
   InstallerUrl:    # Path to download installation file.
   InstallerSha256: # SHA256 calculated from installer.
ManifestType:       # The manifest file type
ManifestVersion: 1.6.0

Vários arquivos de manifesto

Para fornecer a melhor experiência do usuário, os manifestos devem conter o máximo possível de metadados. Para separar as preocupações de validação de instaladores e fornecimento de metadados localizados, os manifestos devem ser divididos em vários arquivos. O número mínimo de arquivos YAML para esse tipo de manifesto é três. Outras localidades também devem ser fornecidas.

O exemplo abaixo mostra muitos campos de metadados opcionais e várias localidades. Observe que a localidade padrão tem mais requisitos do que as localidades adicionais. No comando show, todos os campos obrigatórios que não são fornecidos para localidades adicionais exibirão campos da localidade padrão.

Caminho: manifests / m / Microsoft / WindowsTerminal / 1.6.10571.0 / Microsoft.WindowsTerminal.yaml

PackageIdentifier: "Microsoft.WindowsTerminal"
PackageVersion: "1.6.10571.0"
DefaultLocale: "en-US"
ManifestType: "version"
ManifestVersion: "1.6.0"

Observação

Se o instalador for um .exe e tiver sido criado usando o Nullsoft ou o Inno, será possível especificar esses valores. Quando o Nullsoft ou o Inno forem especificados, o cliente definirá automaticamente os comportamentos de instalação silenciosa e silenciosa com progresso para o instalador.

Opções do instalador

Muitas vezes, você pode descobrir quais Switches silenciosas estão disponíveis para um instalador passando um -? para o instalador da linha de comando. Aqui estão algumas Switches silenciosas comuns que podem ser usadas para diferentes tipos de instalador.

Instalador Comando Documentação
MSI /q Opções de linha de comando do MSI
InstallShield /s Parâmetros da linha de comando do InstallShield
Configuração do Inno /SILENT or /VERYSILENT Documentação de configuração do Inno
Nullsoft /S Instaladores/desinstaladores silenciosos do Nullsoft

Dicas e melhores práticas

  • O identificador do pacote precisa ser exclusivo. Não é possível ter vários envios com o mesmo identificador de pacote. Somente uma solicitação de pull por versão do pacote é permitida.
  • Evite criar várias pastas do editor. Por exemplo, não crie "Contoso Ltd." se já houver uma pasta "Contoso".
  • Todas as ferramentas precisam dar suporte a uma instalação silenciosa. Se você tiver um executável que não dá suporte a uma instalação silenciosa, não poderemos fornecer essa ferramenta no momento.
  • Forneça o máximo de campos possível. Quanto mais metadados você fornecer, melhor será a experiência do usuário. Em alguns casos, os campos talvez ainda não tenham suporte do cliente do Gerenciador de Pacotes do Windows (winget.exe). Por exemplo, o campo AppMoniker é opcional. No entanto, se você incluir esse campo, os clientes verão os resultados associados ao valor Moniker ao executarem o comando search (por exemplo, vscode para Visual Studio Code). Se houver apenas um aplicativo com o valor Moniker especificado, os clientes poderão instalar seu aplicativo especificando o moniker em vez do identificador do pacote totalmente qualificado.
  • O comprimento das cadeias de caracteres nesta especificação deve ser limitado a 100 caracteres antes de um quebra de linha.
  • O PackageName deve corresponder à entrada feita em Adicionar ou remover programas para ajudar a correlação com manifestos a dar suporte à exportação e ao upgrade.
  • O Publisher deve corresponder à entrada feita em Adicionar ou remover programas para ajudar a correlação com manifestos a dar suporte à exportação e ao upgrade.
  • Os instaladores de pacote no formato MSI usam códigos de produto para identificar exclusivamente os aplicativos. O código do produto para uma determinada versão de um pacote deve ser incluído no manifesto para ajudar a garantir a melhor experiência de upgrade.
  • Quando houver mais de um tipo de instalador para a versão do pacote especificada, uma instância de InstallerType poderá ser colocada em cada um dos Installers.

Perguntas frequentes sobre manifesto

O que é um manifesto?

Os manifestos são arquivos YAML que contêm metadados usados pelo Gerenciador de Pacotes do Windows para instalar e atualizar o software no sistema operacional Windows. Há milhares desses arquivos particionados no diretório de manifestos no repositório winget-pkgs no GitHub. A estrutura de diretório do Gerenciador de Pacotes do Windows teve de ser particionada para que você não precise rolar tanto no site ao procurar um manifesto.

O que é um pacote?

Pense em um pacote como um aplicativo ou um programa de software. O Gerenciador de Pacotes do Windows usa um "PackageIdentifier" para representar um pacote exclusivo. Eles geralmente estão na forma de Publisher.Package. Às vezes, você pode ver valores adicionais separados por um segundo ponto.

O que é uma versão?

As versões do pacote estão associadas a uma versão específica. Em alguns casos, você verá um número de versão semântica perfeitamente formado e, em outros casos, poderá ver algo diferente. Elas podem ser controladas por data ou podem ter outros caracteres com algum significado específico do pacote. A chave YAML para uma versão do pacote é "PackageVersion".

Para obter mais informações sobre como entender a estrutura do diretório e criar seu primeiro manifesto, confira Manifestos de criação no repositório winget-pkgs no GitHub.