Erstellen des Paketmanifests

  • Artikel

Wenn Sie ein Softwarepaket an das Windows-Paket-Manager-Communityrepository übermitteln möchten, erstellen Sie zunächst ein Paketmanifest. Das Manifest ist eine YAML-Datei mit einer Beschreibung der zu installierenden Anwendung.

Sie können entweder den Windows-Paket-Manager-Manifestersteller oder das PowerShell-Skript YAMLCreate verwenden oder aber ein Manifest gemäß den folgenden Anweisungen manuell erstellen.

Hinweis

Weitere allgemeine Informationen zur Erläuterung von Manifesten, Paketen und Versionen finden Sie unten in den aufgeführten häufig gestellten Fragen zu Manifesten.

Optionen für die Manifesterstellung

Verwenden des WinGetCreate-Hilfsprogramms

Sie können das Hilfsprogramm wingetcreate mithilfe des folgenden Befehls installieren.

winget install wingetcreate

Nach der Installation können Sie wingetcreate new ausführen, um ein neues Paket zu erstellen und die Eingabeaufforderungen auszufüllen. Der letzte Schritt in den WinGetCreate-Eingabeaufforderungen besteht darin, das Manifest an das Paketrepository zu übermitteln. Wenn Sie „Ja“ auswählen, übermitteln Sie Ihren Pull Request (PR) automatisch an das Windows-Paket-Manager-Communityrepository.

Verwenden von „YAMLCreate.ps1“

Zur Unterstützung beim Erstellen von Manifestdateien stellen wir ein PowerShell-Skript „YAMLCreate.ps1“ im Ordner „Extras“ im Windows-Paket-Manager-Communityrepository bereit. Sie können das Skript verwenden, indem Sie das Repository auf Ihrem PC klonen und das Skript direkt aus dem Ordner Extras ausführen. Das Skript fordert Sie zur Eingabe der URL zum Installationsprogramm und dann zum Eintragen von Metadaten auf. Ähnlich wie bei der Verwendung von WinGetCreate bietet dieses Skript die Möglichkeit, Ihr Manifest automatisch zu übermitteln.

YAML-Grundlagen

Das YAML-Format wurde aus Gründen der relativ guten Lesbarkeit und der Konsistenz mit anderen Microsoft-Entwicklungstools für Paketmanifeste ausgewählt. Wenn Sie mit der YAML-Syntax nicht vertraut sind, können Sie sich die Grundlagen unter Learn YAML in Y Minutes (Erlernen von YAML in Y Minuten) aneignen.

Hinweis

Manifeste für den Windows-Paket-Manager unterstützen zurzeit nicht alle YAML-Features. Zu den nicht unterstützten YAML-Features zählen Anker, komplexe Schlüssel und Sätze.

Konventionen

In diesem Artikel werden die folgenden Konventionen verwendet:

  • Links von : steht ein Literalschlüsselwort, das in Manifestdefinitionen verwendet wird.
  • Rechts von : steht ein Datentyp. Der Datentyp kann ein primitiver Typ wie string oder ein Verweis auf eine umfangreiche Struktur sein, die an anderer Stelle in diesem Artikel definiert ist.
  • Die Schreibweise [Datentyp] gibt ein Array des erwähnten Datentyps an. Beispielsweise steht [ string ] für ein Zeichenfolgenarray.
  • Die Schreibweise {Datentyp:Datentyp} gibt die Zuordnung des einen Datentyps zum anderen an. Beispielsweise ist { string: string } eine Zuordnung von Zeichenfolgen zu Zeichenfolgen.

Inhalt des Manifests

Ein Paketmanifest besteht aus erforderlichen und optionalen Elementen, die zu einer höheren Benutzerfreundlichkeit der Softwareinstallation beitragen können. Dieser Abschnitt enthält kurze Zusammenfassungen des erforderlichen Manifestschemas sowie vollständige Manifestschemas und Beispiele für beides.

Jedes Feld in der Manifestdatei muss die Pascal-Schreibweise verwenden und darf nicht doppelt vorkommen.

Eine vollständige Liste und Beschreibungen der Elemente in einem Manifest finden Sie in der Manifestspezifikation im Repository der Windows-Paket-Manager-Community.

Mindestens erforderliches Schema

Wie im Singleton-JSON-Schema angegeben, sind nur bestimmte Felder erforderlich. Die minimal unterstützte YAML-Datei würde wie im folgenden Beispiel aussehen. Das Singleton-Format ist nur für Pakete gültig, die ein einzelnes Installationsprogramm und ein einzelnes Gebietsschema enthalten. Wenn mehrere Installationsprogramme oder Gebietsschemas bereitgestellt werden, müssen Dateiformat und Schema von YAML verwendet werden.

Das Partitionierungsschema wurde hinzugefügt, um GitHub-Benutzeroberflächen zu unterstützen. Ordner mit Tausenden von untergeordneten Elementen werden im Browser nicht gut gerendert.

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

Mehrere Manifestdateien

Um eine optimale Benutzererfahrung zu bieten, sollten Manifeste so viele Metadaten wie möglich enthalten. Um die Belange der Validierung von Installationsprogrammen und der Bereitstellung lokalisierter Metadaten zu trennen, sollten Manifeste in mehrere Dateien aufgeteilt werden. Die Mindestanzahl von YAML-Dateien für diese Art von Manifest beträgt drei. Es sollten auch zusätzliche Gebietsschemas bereitgestellt werden.

Das folgende Beispiel zeigt viele optionale Metadatenfelder und mehrere Gebietsschemas. Beachten Sie, dass für das Standardgebietsschema mehr Anforderungen als für zusätzliche Gebietsschemas gelten. Im show-Befehl werden für alle erforderlichen Felder, die für zusätzliche Gebietsschemas nicht angegeben werden, die Werte aus den Feldern des Standardgebietsschemas angezeigt.

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

Hinweis

Wenn Ihr Installationsprogramm eine EXE-Datei ist und mit Nullsoft oder Inno erstellt wurde, können Sie stattdessen diese Werte angeben. Wird Nullsoft oder Inno angegeben, legt der Client automatisch die Werte „Silent“ (Unbeaufsichtigt) und „Silent with Progress“ (Unbeaufsichtigt mit Statusanzeige) für das Installationsverhalten des Installationsprogramms fest.

Installer-Switches

Sie können oft herausfinden, welche automatischen Switches für ein Installationsprogramm verfügbar sind, indem Sie ein -? über die Befehlszeile an das Installationsprogramm übergeben. Hier sehen Sie einige gebräuchliche automatische Switches, die für verschiedene Installertypen verwendet werden können.

Installer Befehl Dokumentation
MSI /q Befehlszeilenoptionen für MSI
InstallShield /s InstallShield-Befehlszeilenparameter
Inno Setup /SILENT or /VERYSILENT Inno Setup-Dokumentation
Nullsoft /S Nullsoft-Installer für die Installation/Deinstallation im Hintergrund

Tipps und bewährte Methoden

  • Der Paketbezeichner muss eindeutig sein. Mehrere Übermittlungen mit dem gleichen Paketbezeichner sind nicht zulässig. Pro Paketversion ist nur ein Pull Request zulässig.
  • Vermeiden Sie das Erstellen mehrerer Ordner für den Herausgeber. Erstellen Sie z. B. keinen Ordner „Contoso Ltd.“, wenn der Ordner „Contoso“ bereits vorhanden ist.
  • Alle Tools müssen eine unbeaufsichtigte Installation unterstützen. Wenn Sie über eine ausführbare Datei verfügen, die keine unbeaufsichtigte Installation unterstützt, können wir dieses Tool derzeit nicht bereitstellen.
  • Geben Sie so viele Felder wie möglich an. Je mehr Metadaten Sie bereitstellen, desto besser ist die Benutzerfreundlichkeit. In einigen Fällen werden die Felder möglicherweise vom Windows-Paket-Manager-Client (winget.exe) noch nicht unterstützt. Beispielsweise ist das Feld AppMoniker optional. Wenn Sie dieses Feld jedoch einschließen, werden Kunden Ergebnisse angezeigt, die dem Moniker-Wert zugeordnet sind, wenn Sie den Befehl search ausführen (z. B. vscode für Visual Studio Code). Wenn nur eine App mit dem angegebenen Moniker-Wert vorhanden ist, können Kunden die Anwendung installieren, indem Sie anstelle des vollqualifizierten Paketbezeichners den Moniker angeben.
  • Die Länge von Zeichenfolgen in dieser Spezifikation vor einem Zeilenumbruch sollte auf 100 Zeichen beschränkt werden.
  • PackageName sollte mit dem Eintrag unter Software übereinstimmen, um die Korrelation mit Manifesten zu erleichtern, die Exporte und Upgrades unterstützen.
  • Publisher sollte mit dem Eintrag unter Software übereinstimmen, um die Korrelation mit Manifesten zu erleichtern, die Exporte und Upgrades unterstützen.
  • Paketinstallationsprogramme im MSI-Format verwenden Produktcodes, um Anwendungen eindeutig zu identifizieren. Der Produktcode für eine bestimmte Version eines Pakets sollte im Manifest enthalten sein, um eine optimale Erfahrung beim Upgrade zu gewährleisten.
  • Wenn für die angegebene Version des Pakets mehr als ein Typ von Installationsprogramm vorhanden ist, kann eine Instanz von InstallerType unter jedem der Installers platziert werden.

Häufig gestellte Fragen zu Manifesten

Was ist ein Manifest?

Manifeste sind YAML-Dateien mit Metadaten, die vom Windows-Paket-Manager zur Installation und Aktualisierung von Software auf dem Windows-Betriebssystem verwendet werden. Es gibt Tausende dieser Dateien, die unter dem Manifestverzeichnis im winget-pkgs-Repository auf GitHub partitioniert sind. Die Verzeichnisstruktur des Windows-Paket-Managers musste partitioniert werden, damit Sie bei der Suche nach einem Manifest nicht so viel in der Website scrollen müssen.

Was ist ein Paket?

Stellen Sie sich ein Paket als eine Anwendung oder ein Softwareprogramm vor. Der Windows-Paket-Manager verwendet ein „PackageIdentifier“-Objekt zur eindeutigen Darstellung eines Pakets. Dies liegt im Allgemeinen in Form von Publisher.Package vor. Manchmal werden möglicherweise zusätzliche Werte angezeigt, getrennt durch einen zweiten Punkt.

Was ist eine Version?

Paketversionen sind einem bestimmten Release zugeordnet. In einigen Fällen wird eine perfekt gebildete semantische Versionsnummer angezeigt, in anderen Fällen wird möglicherweise etwas anderes angezeigt. Dies kann datumsgesteuert sein, oder es gibt möglicherweise andere Zeichen mit einer bestimmten paketspezifischen Bedeutung. Der YAML-Schlüssel für eine Paketversion lautet „PackageVersion“.

Weitere Informationen zum Verständnis der Verzeichnisstruktur und zum Erstellen Ihres ersten Manifests finden Sie unter Authoring Manifests (Erstellen von Manifests) im winget-pkgs-Repository auf GitHub.