This section provides guidance on how to create a REST source for the Windows Package Manager. ISVs or Publishers may host and manage a REST source if they would like full control of the packages available in a source. An independently hosted source may choose to expose the read endpoints publicly, restrict access to specific IP address via the addition of a traffic shaping module or restrict access by Microsoft Entra Id authentication. The basic setups configured by the cmdlets and examples result in a source that is publicly readable but requires an authorization key to manage.
Windows Package Manager offers a comprehensive package manager solution including a command line tool and a set of services for installing applications. For more general package submission information, see submit packages to Windows Package Manager.
To simplify the management and interaction with the Windows Package Manager REST source, the Microsoft.WinGet.RestSource PowerShell module has been made available. This PowerShell module provides cmdlets that enable you to Add, Find, Remove and Get package manifests from your Windows Package Manager REST source, as well as stand up a new Windows Package Manager REST source in Azure.
The following steps are for managing a Windows Package Manager REST source with PowerShell:
- Download and install the
Microsoft.WinGet.RestSourcePowerShell Module. - Automate the creation of a Windows Package Manager REST source.
- Publish Package Manifests to the Windows Package Manager REST source.
- Find Package Manifests from Windows Package Manager REST source.
- Retrieve published Package Manifests from the Windows Package Manager REST source.
- Remove published Package Manifests from the Windows Package Manager REST source.
The Microsoft.WinGet.RestSource PowerShell module requires PowerShell Core version 7.4 or later.
Before getting started with the Windows Package Manager REST source with PowerShell, here are a few recommended steps you should complete before using the PowerShell module to ensure you can successfully stand up a new Windows Package Manager REST source in Azure.
- Open PowerShell as an Administrator
- Set the PowerShell execution policies
PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
- Install the Azure Az module
PS C:\> Install-Module -Name Az -AllowClobber
- Connect to Azure with an authenticated account
PS C:\> Connect-AzAccount
- Select the required subscription using Set-AzContext
PS C:\> Set-AzContext -Subscription [Paste the Azure Subscription here]
- Install the PowerShell module from PowerShell Gallery
PS C:\> Install-PSResource -Name Microsoft.WinGet.RestSource -Prerelease
The following steps will get PowerShell from Github Releases for use with the Windows Package Manager REST source.
- Open an Edge Browser.
- Navigate to https://github.com/microsoft/winget-cli-restsource/releases.
- Download the latest release of the Microsoft.WinGet.RestSource PowerShell module. (WinGet.RestSource-Winget.PowerShell.Source.zip)
- Open a File Explorer window, and navigate to where you downloaded the Microsoft.WinGet.RestSource PowerShell module.
- Right-click on WinGet.RestSource-Winget.PowerShell.Source.zip, and select Extract all from the drop-down menu.
- In the new window, select the Extract button.
- After the extraction has completed, navigate to '\WinGet.RestSource-Winget.Powershell.Source'.
- Open an Administrative PowerShell window.
- Ensure the downloaded
Microsoft.WinGet.RestSourcefiles are not blockedPS C:\> Get-ChildItem -Path [Paste the path to the root folder of Microsoft.WinGet.RestSource] -Recurse | Unblock-File
- In combination, press [Ctrl]+[Shift]+Right-click on the
Microsoft.WinGet.RestSource.psd1file. Select Copy Path from the drop-down menu. - Run the following command from the Administrative PowerShell window:
PS C:\> Import-Module [Paste the path to the Microsoft.WinGet.RestSource.psd1 file]
Note
If PowerShell module is extracted from zip file downloaded from Github releases page, the PowerShell module must be re-imported each time the PowerShell window is closed.
To prevent having to re-install this PowerShell module each time, install from PowerShell Gallery or review the instructions in the Installing a PowerShell module on Microsoft Docs
The Microsoft.WinGet.RestSource PowerShell module provides the New-WinGetSource cmdlet to simplify the creation of a Windows Package Manager REST source. This PowerShell cmdlet will initiate a connection to Azure if not currently connected. Validating that the connection is established with a specific Subscription (if specified). Generate the ARM Template Parameter files with specified values, then create Azure resources with the generated ARM Template Parameter files and the provided ARM Template files.
The New-WinGetSource PowerShell cmdlet makes use of the following input parameters. For more information on how to use this cmdlet, use the Get-Help New-WinGetSource -Full or visit the New-WinGetSource PowerShell Article in Docs.
| Required | Parameter | Description |
|---|---|---|
| Yes | Name | A string of letters as the base name for your newly created Azure resources. |
| No | ResourceGroup | The Resource Group that will be used to contain the Azure resources. (Default: WinGetRestSource) |
| No | SubscriptionName | The name of the Azure Subscription that will be used to pay for the Azure resources. (Default: current subscription) |
| No | Region | The Azure location where the Azure resources will be created. (Default: westus) |
| No | TemplateFolderPath | The folder location where ARM templates can be found. (Default: Templates provided by the Powershell module) |
| No | ParameterOutputPath | The folder location where the ARM template parameter files will be created. (Default: Current Directory\Parameters) |
| No | RestSourcePath | Path to the compiled REST API Zip file. (Default: Zip file provided by the Powershell module) |
| No | PublisherName | The Windows Package Manager REST source publisher name. (Default: Signed in user email Or WinGetRestSource@DomainName) |
| No | PublisherEmail | The Windows Package Manager REST source publisher email. (Default: Signed in user email Or WinGetRestSource@DomainName) |
| No | ImplementationPerformance | Specifies the performance of the Azure resources for the Windows Package Manager REST source. ["Developer", "Basic", "Enhanced"] |
| No | RestSourceAuthentication | The Windows Package Manager REST source authentication type. ["None", "MicrosoftEntraId"] (Default: None) |
| No | CreateNewMicrosoftEntraIdAppRegistration | If specified, a new Microsoft Entra Id app registration will be created. (Default: False) |
| No | MicrosoftEntraIdResource | Microsoft Entra Id authentication resource. (Default: None) |
| No | MicrosoftEntraIdResourceScope | Microsoft Entra Id authentication resource scope. (Default: None) |
| No | ShowConnectionInstructions | If specified, the instructions for connecting to the new Windows Package Manager REST source will be provided. (Default: False) |
| No | MaxRetryCount | Max ARM templates deployment retry count upon failure. (Default: 5) |
To create a new Windows Package Manager REST source, open the Administrative PowerShell Window and run the following:
- From an Administrative PowerShell window run the following:
For public access WIndows Package Manager REST source
Or for Microsoft Entra Id protected WIndows Package Manager REST source
PS C:\> New-WinGetSource -Name "contosorestsource" -ResourceGroup "WinGet" -Region "westus" -ImplementationPerformance "Basic" -ShowConnectionInstructions -InformationAction Continue -Verbose
PS C:\> New-WinGetSource -Name "contosorestsource" -ResourceGroup "WinGet" -Region "westus" -ImplementationPerformance "Basic" -RestSourceAuthentication "MicrosoftEntraId" -CreateNewMicrosoftEntraIdAppRegistration -ShowConnectionInstructions -InformationAction Continue -Verbose
- After the above command has completed, copy and run the connection information provided for your newly created Windows Package Manager REST source to add to your winget client.
Note
This is a long running process which can take up to 1 hour depending on network, Azure service load, etc.
After the creation of your Windows Package Manager REST source has completed, you'll need to add Package Manifests for your users to install from. Using the Microsoft.WinGet.RestSource PowerShell module, the Add-WinGetManifest cmdlet will add new Package Manifests to your Windows Package Manager REST source.
The Add-WinGetManifest PowerShell cmdlet supports targeting a specific *.json file, or a folder containing *.yaml files for a single package manifest. For more information on how to use this cmdlet, use the command: Get-Help Add-WinGetManifest -Full or visit the Add-WinGetManifest article in the PowerShell docs.
To add an Package Manifest, open the Administrative PowerShell Window and run the following:
PS C:\> Add-WinGetManifest -FunctionName "contoso" -Path "C:\WinGet\Manifests\Windows.PowerToys\1.0.0"The Microsoft.WinGet.RestSource PowerShell module provides the Find-WinGetManifest cmdlet that will find Package Manifests from the specified Windows Package Manager REST source.
The Find-WinGetManifest PowerShell cmdlet supports targeting an existing Windows Package Manager REST source. For more information on how to use this cmdlet, use the Get-Help Find-WinGetManifest -Full or visit the Find-WinGetManifest article in the PowerShell docs.
To find package manifests, open the Administrative PowerShell Window and run the following:
PS C:\> Find-WinGetManifest -FunctionName "contoso" -Query "PowerToys"To find all package manifests, open the Administrative PowerShell Window and run the following:
PS C:\> Find-WinGetManifest -FunctionName "contoso" -Query ""The Microsoft.WinGet.RestSource PowerShell module provides the Get-WinGetManifest cmdlet that will use ManifestGET against a specified Windows Package Manager REST source to fetch all packages or a specific package by Package Identifier.
Alternatively, the Get-WinGetManifest PowerShell cmdlet supports targeting a specific *.json file or *.yaml files in a folder as well as targeting an existing Windows Package Manager REST source. For more information on how to use this cmdlet, use the Get-Help Get-WinGetManifest -Full or visit the Get-WinGetManifest article in the PowerShell docs.
To get a Package Manifest from Windows Package Manager REST source, open the Administrative PowerShell Window and run the following:
PS C:\> Get-WinGetManifest -FunctionName "contoso" -PackageIdentifier "Windows.PowerToys"The Microsoft.WinGet.RestSource PowerShell module provides the Remove-WinGetManifest cmdlet that will remove a specific Package Manifest from the specified Windows Package Manager REST source.
The Remove-WinGetManifest PowerShell cmdlet supports targeting an existing Windows Package Manager REST source for a specific Package Identifier. For more information on how to use this cmdlet, use the Get-Help Remove-WinGetManifest -Full or visit the Remove-WinGetManifest article in the PowerShell docs.
To remove all versions of a package, open the Administrative PowerShell Window and run the following:
PS C:\> Remove-WinGetManifest -FunctionName "contoso" -PackageIdentifier "Windows.PowerToys"To remove a specific version of a package, open the Administrative PowerShell Window and run the following:
PS C:\> Remove-WinGetManifest -FunctionName "contoso" -PackageIdentifier "Windows.PowerToys" -PackageVersion "1.0.0"