DOCSEARCHbyAlgolia
Submit Docs

WingetCreate Documentation

repository·main·Indexed 20 days ago

https://github.com/microsoft/winget-create

An open-source tool for creating, updating, and submitting manifest files to the Windows Package Manager (winget-pkgs) community repository. Includes guides on CLI commands, CI/CD pipeline integration via standalone exe or msixbundle, building from source, and managing settings using the dsc command.

Tokens
17.9K
Snippets
66
Records
79
Agent score
68%

What's inside WingetCreate

  1. How the 'new' command workflow works

    main

    The new command follows a structured wizard flow to ensure manifest accuracy:

    1. Downloading the installer: The tool downloads the provided installer and attempts to extract metadata to pre-populate fields like PackageIdentifier.
    2. Auto-filling manifest fields: If the installer URL is a GitHub release, the tool can automatically populate several fields using a GitHub token (--token). Fields include:
      • License, ShortDescription, ReleaseDate, ReleaseNotesUrl, PackageUrl, PublisherUrl, PublisherSupportUrl, Tags, and Documentations (if a wiki exists).
    3. Reviewing and Editing: You will be prompted to accept or modify remaining required fields. You can use DEL and ARROW keys to edit. After all fields are filled, the tool displays a summary for review. If you need to change something, you can go back through the fields.
    4. Saving: Once you confirm the details, the manifest is saved to your specified --out directory.
    5. Submission: The tool offers to automatically submit a Pull Request (PR) to the microsoft/winget-pkgs repository. If you haven't provided a --token, you will be prompted to authenticate via a web page.

  2. Auto-fill manifest metadata from GitHub releases

    main

    If the installer URLs are hosted on a GitHub release, winget-create can automatically populate several manifest fields. To enable this, you must provide a valid GitHub personal access token using the --token (or -t) argument.

    Automatically filled fields include:

    • ReleaseDate: The publish date of the GitHub release.
    • ReleaseNotesUrl: The URL to the GitHub release notes.
    • PackageUrl: The URL to the GitHub repository.
    • PublisherUrl: The URL to the publisher's GitHub page.
    • PublisherSupportUrl: The URL to GitHub issues.
    • Tags: Tags from the GitHub repository.
    • Documentations: The URL to the repository wiki (if available).

  3. Override installer architecture, scope, and display version

    main

    If winget-create fails to detect the correct architecture or scope from the installer URL or binary, you can use a pipe-delimited string within the --urls argument to override these values.

    Note: Because the | character is a pipeline operator in most shells, you must wrap the URL string in quotes.

    Override Formats

    • Architecture: '<InstallerUrl>|<InstallerArchitecture>' (e.g., x64, x86)
    • Scope: '<InstallerUrl>|<InstallerArchitecture>|<InstallerScope>' (e.g., user, machine)
    • Display Version: '<InstallerUrl>|<DisplayVersion>' (use this if the marketing version differs from the installed version)
    • Arguments: '<InstallerUrl>|<Argument1>|<Argument2>...'
    # Override architecture
wingetcreate update <PackageIdentifier> --urls '<InstallerUrl1>|x64' --version <Version>

# Override architecture and scope
wingetcreate update <PackageIdentifier> --urls '<InstallerUrl1>|x64|user' '<InstallerUrl1>|x64|machine' --version <Version>

# Override display version
wingetcreate update <PackageIdentifier> --urls '<InstallerUrl1>|1.2.3' --version <Version>

  4. How to file issues and get help

    main

    To report bugs or request new features for winget-create, use the GitHub issues tracker. It is recommended to search existing issues before filing a new one to prevent duplicates.

    • Bugs: File a bug report using the provided template.
    • Feature Requests: File a feature request using the provided template.
    • General Help: Consult the official documentation site for usage guidance.
    • Contributing: If you wish to contribute code to the project, refer to the Contributor's Guide.

  6. Configure Winget-Create settings

    main

    You can configure Winget-Create by editing the settings.json file. To open this file in your default JSON editor, run the following command. If no editor is configured, Windows will prompt you to select one (Notepad is a recommended option).

    wingetcreate.exe settings

  7. Use WingetCreate in a CI/CD pipeline with the msixbundle

    main

    On Windows Server 2022 or later, you can use the msixbundle which supports App Execution Aliases.

    Prerequisite: You must install the C++ Runtime Desktop framework package before installing the msixbundle.

    Example PowerShell task for a pipeline:

    - powershell: |
        # Download and install C++ Runtime framework package.
        iwr https://aka.ms/Microsoft.VCLibs.x64.14.00.Desktop.appx -OutFile $(vcLibsBundleFile)
        Add-AppxPackage $(vcLibsBundleFile)

        # Download Winget-Create msixbundle, install, and execute update.
        iwr https://aka.ms/wingetcreate/latest/msixbundle -OutFile $(appxBundleFile)
        Add-AppxPackage $(appxBundleFile)
        wingetcreate update Microsoft.WingetCreate -u $(packageUrl) -v $(manifestVersion) -t $(GITHUB_PAT) --submit
    - powershell: |
        # Download and install C++ Runtime framework package.
        iwr https://aka.ms/Microsoft.VCLibs.x64.14.00.Desktop.appx -OutFile $(vcLibsBundleFile)
        Add-AppxPackage $(vcLibsBundleFile)

        # Download Winget-Create msixbundle, install, and execute update.
        iwr https://aka.ms/wingetcreate/latest/msixbundle -OutFile $(appxBundleFile)
        Add-AppxPackage $(appxBundleFile)
        wingetcreate update Microsoft.WingetCreate -u $(packageUrl) -v $(manifestVersion) -t $(GITHUB_PAT) --submit

  8. Add a new locale for a package using new-locale

    main

    The new-locale command provides an interactive workflow to create a new locale manifest for an existing package in the Windows Package Manager repository. It prompts the user for necessary locale fields and generates the manifest based on an existing package's data.

    To use this command, you must provide a <PackageIdentifier> and a GitHub Personal Access Token (--token).

    # Add a new locale for the latest version of a package
wingetcreate.exe new-locale <PackageIdentifier> --token <GitHubPersonalAccessToken>

# Add a new locale for a specific version of a package
wingetcreate.exe new-locale <PackageIdentifier> --token <GitHubPersonalAccessToken> --version <Version>

# Create a new locale and save the generated manifests to a specified directory
wingetcreate.exe new-locale <PackageIdentifier> --out <OutputDirectory> --token <GitHubPersonalAccessToken> --version <Version>

  9. Build the WingetCreate client from source

    main

    To build the project locally, ensure you have the following prerequisites:

    • Visual Studio 2022 with .NET Desktop Development and Universal Windows Platform Development workloads.
    • Windows 11 SDK (10.0.26100.0).
    • Git LFS.

    Configuration Options:

    1. Using the configuration file: Clone the repo and run winget configure .config/configuration.winget from the root, or import the .vsconfig file via the Visual Studio Installer.
    2. Manual setup: Install the workloads and SDKs manually via Visual Studio.

    Build Process: Open winget-create\src\WingetCreateCLI.sln in Visual Studio and build the solution.

  10. Use WingetCreate in a CI/CD pipeline with the standalone exe

    main

    To use the standalone executable in a pipeline (e.g., Azure DevOps or GitHub Actions), follow these requirements:

    1. Install .NET Runtime 6.0: The executable requires the .NET 6.0 runtime.
    2. Install Microsoft Visual C++ Redistributable: This is a mandatory dependency to avoid DllNotFoundException.
    3. Secure your GitHub PAT: Do not hardcode your Personal Access Token. Use secret pipeline variables.

    Example workflow to download and update a manifest:

    Invoke-WebRequest https://aka.ms/wingetcreate/latest -OutFile wingetcreate.exe
.\wingetcreate.exe update <packageId> -u $(packageUrls) -v $(manifestVersion) -t $(GITHUB_PAT)
    Invoke-WebRequest https://aka.ms/wingetcreate/latest -OutFile wingetcreate.exe
.\wingetcreate.exe update <packageId> -u $(packageUrls) -v $(manifestVersion) -t $(GITHUB_PAT)

  11. Use the update command to update manifests

    main

    The update command updates an existing manifest by modifying the URL, hash, and version. It supports two modes:

    1. Interactive mode (--interactive): Provides a guided experience with user prompts.
    2. Autonomous mode: Designed for CI/CD pipelines to automate manifest updates.

    Important: When providing installer URLs via --urls, the number of URLs must exactly match the number of existing installer nodes in the manifest to ensure deterministic updates. If they do not match, the command will fail.

    wingetcreate.exe update <id> [-u <urls>] [-v <version>] [-s] [-t <token>] [-o <output directory>] [-p <pull request title>] [-r] [<replace version>] [-d <display version>] [--release-date <release date> ] [--release-notes-url <release notes url>] [--format <format>] [--interactive] [--help]

  12. Use the 'new' command to generate a manifest

    main

    The new command initiates the wizard-driven process of generating a Windows Package Manager manifest file. This is used when you want to submit software to the Microsoft Community Package Manifest Repository on GitHub.

    Providing Installer URLs

    You can provide URLs in two ways:

    1. Command Line Arguments: Pass one or more URLs separated by spaces.
    2. Interactive Prompt: If no URLs are provided, the tool will prompt you. When prompted, separate multiple URLs with a comma.

    Command Arguments

    ArgumentDescription
    -o, --outThe output directory where the newly created manifests will be saved locally
    --allow-unsecure-downloadsAllow unsecure downloads (HTTP) for this operation
    -f, --formatOutput format of the manifest. Default is yaml
    -t, --tokenGitHub personal access token used for direct submission. ⚠️ Note: Using this may result in the token being logged. See https://aka.ms/winget-create-token for alternatives.
    -n, --no-openIf set, the tool will not automatically open the Pull Request in your browser upon submission. Default is false
    -?, --helpDisplays help for the new command
    # Single URL
wingetcreate.exe new https://microsoft.com/foo.exe

# Multiple URLs via command line
wingetcreate.exe new https://microsoft.com/foo.exe https://microsoft.com/bar.msix

# Specifying output directory and format
wingetcreate.exe new https://microsoft.com/foo.exe -o ./my-manifests -f yaml