Creare il manifesto del pacchetto

  • Articolo

Per inviare un pacchetto software al repository della community di Gestione pacchetti Windows, iniziare creando un manifesto del pacchetto. Il manifesto è un file YAML che descrive l'applicazione da installare.

È possibile usare Manifest Creator di Gestione pacchetti di Windows, lo script PowerShell YAMLCreate oppure creare un manifesto manualmente seguendo le istruzioni riportate di seguito.

Nota

Per informazioni generali più generali su manifesti, pacchetti e versioni, vedere le domande frequenti sul manifesto di seguito.

Opzioni per la creazione del manifesto

Uso dell'utilità WinGetCreate

È possibile installare l'utilità wingetcreate usando il comando seguente.

winget install wingetcreate

Dopo l'installazione, è possibile eseguire wingetcreate new per creare un nuovo pacchetto e compilare le richieste. L'ultima opzione nei prompt di WinGetCreate consiste nell'inviare il manifesto al repository dei pacchetti. Se si sceglie di sì, si invierà automaticamente la richiesta pull (PR) al repository della community di Gestione pacchetti di Windows.

Uso di YAMLCreate.ps1

Per facilitare la creazione di file manifesto, è stato fornito uno script powershell YAMLCreate.ps1 che si trova nella cartella Strumenti nel repository della community di Gestione pacchetti di Windows. È possibile usare lo script clonando il repository nel PC ed eseguendo lo script direttamente dalla cartella Strumenti. Lo script richiederà l'URL per il programma di installazione, quindi chiederà di compilare i metadati. Analogamente all'uso di WinGetCreate, questo script offrirà la possibilità di inviare automaticamente il manifesto.

Informazioni di base su YAML

Per i manifesti del pacchetto è stato scelto il formato YAML, in quanto garantisce una relativa facilità di leggibilità e la coerenza con altri strumenti di sviluppo Microsoft. Se non hai familiarità con la sintassi YAML, puoi apprendere le nozioni di base in Apprendere YAML in Y minuti.

Nota

I manifesti per Gestione pacchetti di Windows attualmente non supportano tutte le funzionalità YAML. Le funzionalità YAML non supportate includono ancoraggi, chiavi complesse e set.

Convenzioni

Convenzioni usate in questo articolo:

  • A sinistra di : è presente una parola chiave letterale usata nelle definizioni del manifesto.
  • A destra di : è presente un tipo di dati. Il tipo di dati può essere un tipo primitivo, ad esempio string, o un riferimento a una struttura avanzata definita altrove in questo articolo.
  • La notazione [datatype] indica una matrice del tipo di dati indicato. Ad esempio, [ string ] è una matrice di stringhe.
  • La notazione {datatype:datatype} indica un mapping di un tipo di dati a un altro. Ad esempio, { string: string } è un mapping di stringhe a stringhe.

Contenuto del manifesto

Un manifesto del pacchetto è composto da elementi necessari e facoltativi che consentono di migliorare l'esperienza del cliente per l'installazione del software. In questa sezione viene fornito un breve riepilogo dello schema del manifesto necessario e degli schemi di manifesto completi, con esempi per ognuno di essi.

Ogni campo nel file manifesto deve essere espresso in notazione Pascal e non può essere duplicato.

Per un elenco completo e le descrizioni degli elementi in un manifesto, vedere la specifica del manifesto nel repository della community di Gestione pacchetti Windows.

Schema minimo necessario

Come specificato nello schema JSON singleton, sono necessari solo determinati campi. Il file YAML minimo supportato sarà simile all'esempio seguente. Il formato singleton è valido solo per i pacchetti contenenti un singolo programma di installazione e una singola impostazione locale. Se sono disponibili più programmi di installazione o impostazioni locali, è necessario usare il formato e lo schema di file YAML multipli.

Lo schema di partizionamento è stato aggiunto per facilitare l'esperienza utente di GitHub. Le cartelle con migliaia di elementi figlio non eseguono il rendering corretto nel browser.

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

File manifesto multipli

Per offrire un'esperienza utente ottimale, i manifesti devono contenere il maggior numero possibile di metadati. Per separare i problemi relativi alla convalida dei programmi di installazione e per fornire di metadati localizzati, i manifesti devono essere suddivisi in più file. Il numero minimo di file YAML per questo tipo di manifesto è tre. È necessario specificare anche impostazioni locali aggiuntive.

L'esempio seguente mostra molti campi di metadati facoltativi e più impostazioni locali. Si noti che le impostazioni locali predefinite hanno più requisiti rispetto alle impostazioni locali aggiuntive. Nel comando show, tutti i campi obbligatori non forniti per impostazioni locali aggiuntive visualizzeranno i campi dalle impostazioni locali predefinite.

Tracciato: 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"

Nota

Se il programma di installazione è un file con estensione exe ed è stato compilato con Nullsoft o Inno, è possibile specificare tali valori. Quando si specifica Nullsoft o Inno, il client imposterà automaticamente i comportamenti di installazione silenziosa e installazione silenziosa con indicatore di stato per il programma di installazione.

Opzioni del programma di installazione

Spesso puoi scoprire quali Switches invisibili all'utente sono disponibili per un programma di installazione tramite il passaggio di -? al programma di installazione dalla riga di comando. Ecco alcune Switches invisibili all'utente comuni che possono essere usate per diversi tipi di programma di installazione.

Programma di installazione Comando Documentazione
MSI /q Opzioni della riga di comando di MSI
InstallShield /s Parametri della riga di comando di InstallShield
Inno Setup /SILENT or /VERYSILENT Documentazione di Inno Setup
Nullsoft /S Programmi di installazione/disinstallazione invisibili all'utente di Nullsoft

Suggerimenti e procedure consigliate

  • L'identificatore del pacchetto deve essere univoco. Non sono consentiti più invii con lo stesso identificatore del pacchetto. È consentita una sola richiesta pull per versione del pacchetto.
  • Evita di creare più cartelle dell'editore. Ad esempio, non è possibile creare "Contoso Ltd" se è già presente una cartella "Contoso".
  • Tutti gli strumenti devono supportare un'installazione invisibile all'utente. Se è presente un file eseguibile che non supporta un'installazione invisibile all'utente, in questo momento non possiamo fornire tale strumento.
  • Specificare il maggior numero possibile di campi. Maggiore sarà il numero di metadati forniti, migliore sarà l'esperienza utente. In alcuni casi, i campi potrebbero non essere ancora supportati dal client di Gestione pacchetti windows (winget.exe). Ad esempio, il campo AppMoniker è facoltativo. Tuttavia, se includi questo campo, i clienti visualizzeranno i risultati associati al valore Moniker durante l'esecuzione del comando search, ad esempio vscode per Visual Studio Code. Se è presente una sola app con il valore Moniker specificato, i clienti possono installare l'applicazione specificando il moniker anziché l'identificatore del pacchetto completo.
  • La lunghezza delle stringhe in questa specifica deve essere limitata a 100 caratteri prima di un'interruzione di riga.
  • Il PackageName deve corrispondere alla voce inserita in Aggiungi/Rimuvi programmi per facilitare la correlazione con i manifesti per supportare l'esportazionee l'aggiornamento.
  • Il Publisher deve corrispondere alla voce inserita in Aggiungi/Rimuvi programmi per facilitare la correlazione con i manifesti per supportare l'esportazionee l'aggiornamento.
  • I programmi di installazione dei pacchetti in formato MSI usano codici prodotto per identificare in modo univoco le applicazioni. Il codice prodotto per una determinata versione di un pacchetto deve essere incluso nel manifesto per garantire la migliore esperienza di aggiornamento.
  • Quando esiste più di un tipo di programma di installazione per la versione specificata del pacchetto, è possibile includere un'istanza di InstallerType in tutti gli Installers.

Domande frequenti sul manifesto

Che cos'è un manifesto?

I manifesti sono file YAML contenenti metadati usati da Gestione pacchetti di Windows per installare e aggiornare software nel sistema operativo Windows. Esistono migliaia di questi file partizionati nella directory manifesti nel repository winget-pkgs in GitHub. La struttura della directory di Gestione pacchetti di Windows deve essere partizionata in modo da non dover scorrere molto nel sito quando si cerca un manifesto.

Che cos'è un pacchetto?

Si pensi a un pacchetto come a un'applicazione o un programma software. Gestione pacchetti di Windows usa un "PackageIdentifier" per rappresentare un pacchetto univoco. Questi sono in genere sotto forma di Publisher.Package. In alcuni casi potrebbero essere visualizzati valori aggiuntivi separati da un secondo punto.

Che cos'è una versione?

Le versioni dei pacchetti sono associate a una versione specifica. In alcuni casi si vedrà un numero di versione semantica perfettamente formato e in altri casi potrebbe essere visualizzato qualcosa di diverso. Queste possono essere basate su dati o potrebbero avere altri caratteri con un significato specifico del pacchetto. La chiave YAML per una versione del pacchetto è "PackageVersion".

Per altre informazioni sulla struttura di directory e sulla creazione del primo manifesto, vedere Creazione di manifesti nel repository winget-pkgs in GitHub.