-
Notifications
You must be signed in to change notification settings - Fork 65
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Doc updates for updated PowerShell module (#267)
- Loading branch information
Showing
17 changed files
with
1,579 additions
and
1,320 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,92 +1,70 @@ | ||
| # Welcome to the winget-cli-restsource repository | ||
|
|
||
| ## Building the client | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| * [Git Large File Storage (LFS)](https://git-lfs.github.com/) | ||
| * [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) | ||
| * The following workloads: | ||
| * .NET desktop development | ||
| * Azure development | ||
| * ASP<area>.NET and web development | ||
|
|
||
| Open `src\WinGet.RestSource.sln` in Visual Studio and build. We currently only build using the solution; command line methods of building a VS solution should work as well. | ||
|
|
||
| ## Running locally | ||
|
|
||
| The REST functions can be run locally, but to use winget with them, the functions must be run using HTTPS, this is pre-configured by the `launchSettings.json` file. | ||
|
|
||
| 1. In the `src\WinGet.RestSource.Functions` directory, run `generate_self_sign_cert.ps1` in PowerShell. | ||
| * This will generate a test pfx and install it into the Root store. | ||
| * It will automatically be used as the HTTPS cert during local execution, thanks to `launchSettings.json` | ||
| 2. Create a CosmosDB database instance in Azure, using either the above instructions, or [manually](https://docs.microsoft.com/azure/cosmos-db/sql/create-cosmosdb-resources-portal). | ||
| * Navigate to the Keys section of your CosmosDB instance in the Azure portal to find your connection information. | ||
| * If you've used the ARM templates as described above, your Database will be named `WinGet` and your Collection will be `Manifests` | ||
| 3. Copy `src\WinGet.RestSource.Functions\local.settings.template.json` to `local.settings.json` and populate required fields from the above Keys section. | ||
| 4. Run the `WinGet.RestSource.Functions` project locally in Visual Studio using F5. | ||
| 5. Add it as a source in winget with: `winget source add -n "winget-pkgs-restsource" -a https://localhost:7071/api/ -t "Microsoft.Rest"` | ||
|
|
||
| Your commands to winget will now use your locally running REST instance as the primary source. | ||
|
|
||
| ## Running Tests | ||
|
|
||
| Running tests are a great way to ensure that functionality is preserved across major changes. You can run these tests in Visual Studio Test Explorer. In Visual Studio, run the tests from the menu with Test > Run All Tests | ||
|
|
||
| ### Unit Testing Prerequisites | ||
|
|
||
| * Install the [Cosmos DB Emulator](https://docs.microsoft.com/azure/cosmos-db/local-emulator?tabs=ssl-netstd21) | ||
| * Copy the `WinGet.RestSource.UnitTest\Test.runsettings.template.json` template configuration to `Test.runsettings.json` | ||
| * The defaults should work for your local Cosmos DB emulator instance. You can change the configuration to point to a Cosmos DB instance in Azure instead. | ||
| * Alternatively, all of the test configuration properties can be set as environment variables. This is useful for overriding properties in an ADO build. | ||
|
|
||
| ### Integration Testing Prerequisites | ||
|
|
||
| * Install the [winget client](https://github.com/microsoft/winget-cli) locally. | ||
| * Copy the `WinGet.RestSource.IntegrationTest\Test.runsettings.template.json` template configuration to `Test.runsettings.json` | ||
| * Modify the `RestSourceUrl` property to point to a deployed rest source endpoint. You can use the below instructions to deploy a rest instance. | ||
| * If the local winget client doesn't already have the source added, the integration tests can add it. To do so, change the `AddRestSource` property to true. Visual Studio must be running as admin in this case. | ||
| * There is a test case that **modifies** the rest source. By default it's disabled, to run it the `RunWriteTests` setting must be set to true. The `FunctionsHostKey` setting must also be set since the add/update/delete endpoints all require function authorization. We recommend creating a new pipeline-specific host key for this purpose. | ||
|
|
||
| ## Automatically create a rest source | ||
|
|
||
| The `Microsoft.WinGet.Source` PowerShell module provides the [New-WinGetSource](/Tools/PowershellModule/doc/PowerShell/New-WinGetSource.md) 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 Parameter files with specified values, then create Azure resources with the generated ARM 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](/Tools/PowershellModule/doc/PowerShell/New-WinGetSource.md) in Docs. | ||
|
|
||
| | Required | Parameter | Description | | ||
| |----------|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | Yes | Name | A string of letters which will be prefixed to your newly created Azure resources. | | ||
| | Yes | ResourceGroup | The Resource Group that will be used to contain the Azure resources. | | ||
| | No | SubscriptionName | The name of the Azure Subscription that will be used to pay for the Azure resources. | | ||
| | No | Region | The Azure location where the Azure resources will be created. (Default: westus) | | ||
| | No | ParameterOutput | The folder location that contains new items will be created in. | | ||
| | No | RestSourcePath | Path to the compiled Rest API Zip file. (Default: .\RestAPI\CompiledFunctions.ps1) | | ||
| | No | ImplementationPerformance | specifies the performance of the resources to be created for the Windows Package Manager rest source. ["Demo", "Basic", "Enhanced"] | | ||
| | No | ShowConnectionInstructions | If specified, the instructions for connecting to the Windows Package Manager rest source. (Default: False) | | ||
|
|
||
| > [!Note] | ||
| > The PowerShell Module must be re-imported each time the PowerShell window is closed. | ||
| **How to:** | ||
|
|
||
| 1. From the Administrative PowerShell window run the following: | ||
| ```PowerShell | ||
| PS C:\> New-WinGetSource -Name "contoso" -ResourceGroup "WinGetPrivateSource" -Region "westus" -ImplementationPerformance "Demo" -ShowConnectionInstructions | ||
| ``` | ||
| 1. After the above has completed, copy and run the connection information provided for your newly created Windows Package Manager rest source to add it to your WinGet client. | ||
|
|
||
|
|
||
| ## Contributing | ||
|
|
||
| This project welcomes contributions and suggestions. Most contributions require you to agree to a | ||
| Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us | ||
| the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. | ||
|
|
||
| When you submit a pull request, a CLA bot will automatically determine whether you need to provide | ||
| a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions | ||
| provided by the bot. You will only need to do this once across all repos using our CLA. | ||
|
|
||
| This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). | ||
| For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or | ||
| contact [[email protected]](mailto:[email protected]) with any additional questions or comments. | ||
| # Welcome to the winget-cli-restsource repository | ||
|
|
||
| ## Create a Windows Package Manager REST source on Azure with PowerShell | ||
|
|
||
| The [Microsoft.WinGet.RestSource](https://www.powershellgallery.com/packages/Microsoft.WinGet.RestSource) PowerShell module is provided for creating and managing Windows Package Manager REST sources. | ||
|
|
||
| Please visit [Create a Windows Package Manager REST source](/Tools/PowershellModule/doc/WingetRestSource.md) for more details. | ||
|
|
||
| ## Building the client | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| * [Git Large File Storage (LFS)](https://git-lfs.github.com/) | ||
| * [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/) | ||
| * The following workloads: | ||
| * .NET desktop development | ||
| * Azure development | ||
| * ASP<area>.NET and web development | ||
|
|
||
| Open `src\WinGet.RestSource.sln` in Visual Studio and build. We currently only build using the solution; command line methods of building a VS solution should work as well. | ||
|
|
||
| ## Running locally | ||
|
|
||
| The REST functions can be run locally, but to use winget with them, the functions must be run using HTTPS. This is pre-configured by the `launchSettings.json` file. | ||
|
|
||
| 1. In the `src\WinGet.RestSource.Functions` directory, run `generate_self_sign_cert.ps1` in PowerShell. | ||
| * This will generate a test pfx and install it into the Root store. | ||
| * It will automatically be used as the HTTPS cert during local execution, thanks to `launchSettings.json` | ||
| 2. Create a CosmosDB database instance in Azure, using either the above instructions, or [manually](https://docs.microsoft.com/azure/cosmos-db/sql/create-cosmosdb-resources-portal). | ||
| * Navigate to the Keys section of your CosmosDB instance in the Azure portal to find your connection information. | ||
| * If you've used the ARM templates as described above, your Database will be named `WinGet` and your Collection will be `Manifests` | ||
| 3. Copy `src\WinGet.RestSource.Functions\local.settings.template.json` to `local.settings.json` and populate required fields from the above Keys section. | ||
| 4. In source codes, change HttpTrigger level to Anonymous for InformationGet, ManifestSearchPost and ManifestGet endpoints. | ||
| 5. Run the `WinGet.RestSource.Functions` project locally in Visual Studio using F5. | ||
| 6. Add it as a source in winget with: `winget source add -n "winget-pkgs-restsource" -a https://localhost:7071/api/ -t "Microsoft.Rest"` | ||
|
|
||
| Your commands to winget will now use your locally running REST instance as a user added source. | ||
|
|
||
| ## Running Tests | ||
|
|
||
| Running tests are a great way to ensure that functionality is preserved across major changes. You can run these tests in Visual Studio Test Explorer. In Visual Studio, run the tests from the menu with Test > Run All Tests | ||
|
|
||
| ### Unit Testing Prerequisites | ||
|
|
||
| * Install the [Cosmos DB Emulator](https://docs.microsoft.com/azure/cosmos-db/local-emulator?tabs=ssl-netstd21) | ||
| * Copy the `WinGet.RestSource.UnitTest\Test.runsettings.template.json` template configuration to `Test.runsettings.json` | ||
| * The defaults should work for your local Cosmos DB emulator instance. You can change the configuration to point to a Cosmos DB instance in Azure instead. | ||
| * Alternatively, all of the test configuration properties can be set as environment variables. This is useful for overriding properties in an ADO build. | ||
|
|
||
| ### Integration Testing Prerequisites | ||
|
|
||
| * Install the [winget client](https://github.com/microsoft/winget-cli) locally. | ||
| * Copy the `WinGet.RestSource.IntegrationTest\Test.runsettings.template.json` template configuration to `Test.runsettings.json` | ||
| * Modify the `RestSourceUrl` property to point to a deployed REST source endpoint. You can use the below instructions to deploy a REST instance. | ||
| * If the local winget client doesn't already have the source added, the integration tests can add it. To do so, change the `AddRestSource` property to true. Visual Studio must be running as admin in this case. | ||
| * There is a test case that **modifies** the REST source. This test is disabled by default. To run it the `RunWriteTests` setting must be set to true. The `FunctionsHostKey` setting must also be set since the add/update/delete endpoints all require function authorization. We recommend creating a new pipeline-specific host key for this purpose. | ||
|
|
||
| ## Contributing | ||
|
|
||
| This project welcomes contributions and suggestions. Most contributions require you to agree to a | ||
| Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us | ||
| the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. | ||
|
|
||
| When you submit a pull request, a CLA bot will automatically determine whether you need to provide | ||
| a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions | ||
| provided by the bot. You will only need to do this once across all repos using our CLA. | ||
|
|
||
| This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). | ||
| For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or | ||
| contact [[email protected]](mailto:[email protected]) with any additional questions or comments. |
217 changes: 110 additions & 107 deletions
217
Tools/PowershellModule/doc/PowerShell/Add-WinGetManifest.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,107 +1,110 @@ | ||
| --- | ||
| Module Name: Microsoft.WinGet.RestSource | ||
| online version: | ||
| schema: 2.0.0 | ||
| --- | ||
|
|
||
| # Add-WinGetManifest | ||
|
|
||
| ## SYNOPSIS | ||
| Submits a Manifest file(s) to the Azure REST source | ||
|
|
||
| ## SYNTAX | ||
|
|
||
| ``` | ||
| Add-WinGetManifest [-FunctionName] <String> [-Path] <String> [[-SubscriptionName] <String>] | ||
| [<CommonParameters>] | ||
| ``` | ||
|
|
||
| ## DESCRIPTION | ||
| By running this function with the required inputs, it will connect to the Azure Tenant that hosts the Windows Package Manager REST source, then collects the required URL for Manifest submission before retrieving the contents of the Manifest JSON to submit. | ||
|
|
||
| The following Azure Modules are used by this script: | ||
| Az.Resources | ||
| Az.Accounts | ||
| Az.Websites | ||
| Az.Functions | ||
|
|
||
| ## EXAMPLES | ||
|
|
||
| ### EXAMPLE 1 | ||
| ``` | ||
| Add-WinGetManifest -FunctionName "contosorestsource" -Path "C:\AppManifests\Microsoft.PowerToys\PowerToys.json" | ||
| ``` | ||
|
|
||
| Connects to Azure, then runs the Azure Function "contosorestsource" REST APIs to add the specified Manifest file (*.json) to the Windows Package Manager REST source | ||
|
|
||
| ### EXAMPLE 2 | ||
| ``` | ||
| Add-WinGetManifest -FunctionName "contosorestsource" -Path "C:\AppManifests\Microsoft.PowerToys\" | ||
| ``` | ||
|
|
||
| Connects to Azure, then runs the Azure Function "contosorestsource" REST APIs to adds the Manifest file(s) (*.json / *.yaml) found in the specified folder to the Windows Package Manager REST source | ||
|
|
||
| ### EXAMPLE 3 | ||
| ``` | ||
| Add-WinGetManifest -FunctionName "contosorestsource" -Path "C:\AppManifests\Microsoft.PowerToys\PowerToys.json" -SubscriptionName "Visual Studio Subscription" | ||
| ``` | ||
|
|
||
| Connects to Azure and the specified Subscription, then runs the Azure Function "contosorestsource" REST APIs to add the specified Manifest file (*.json) to the Windows Package Manager REST source | ||
|
|
||
| ## PARAMETERS | ||
|
|
||
| ### -FunctionName | ||
| Name of the Azure Function that hosts the REST source. | ||
|
|
||
| ```yaml | ||
| Type: String | ||
| Parameter Sets: (All) | ||
| Aliases: | ||
|
|
||
| Required: True | ||
| Position: 1 | ||
| Default value: None | ||
| Accept pipeline input: False | ||
| Accept wildcard characters: False | ||
| ``` | ||
| ### -Path | ||
| The Path to the JSON manifest file or folder hosting the JSON / YAML files that will be uploaded to the REST source. This path may contain a single JSON / YAML file, or a folder containing multiple JSON / YAML files. Does not support targetting a single folder of multiple different applications in *.yaml format. | ||
| ```yaml | ||
| Type: String | ||
| Parameter Sets: (All) | ||
| Aliases: | ||
|
|
||
| Required: True | ||
| Position: 2 | ||
| Default value: None | ||
| Accept pipeline input: False | ||
| Accept wildcard characters: False | ||
| ``` | ||
| ### -SubscriptionName | ||
| \[Optional\] The Subscription name contains the Windows Package Manager REST source | ||
| ```yaml | ||
| Type: String | ||
| Parameter Sets: (All) | ||
| Aliases: | ||
|
|
||
| Required: False | ||
| Position: 3 | ||
| Default value: None | ||
| Accept pipeline input: False | ||
| Accept wildcard characters: False | ||
| ``` | ||
| ### CommonParameters | ||
| This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). | ||
| ## INPUTS | ||
| ## OUTPUTS | ||
| ## NOTES | ||
| ## RELATED LINKS | ||
| --- | ||
| external help file: Microsoft.WinGet.RestSource-help.xml | ||
| Module Name: microsoft.WinGet.RestSource | ||
| online version: | ||
| schema: 2.0.0 | ||
| --- | ||
|
|
||
| # Add-WinGetManifest | ||
|
|
||
| ## SYNOPSIS | ||
| Submits a Manifest to the Windows Package Manager REST source. | ||
|
|
||
| ## SYNTAX | ||
|
|
||
| ``` | ||
| Add-WinGetManifest [-FunctionName] <String> [-Path] <String> [-SubscriptionName <String>] | ||
| [-ProgressAction <ActionPreference>] [<CommonParameters>] | ||
| ``` | ||
|
|
||
| ## DESCRIPTION | ||
| Submits a Manifest to the Windows Package Manager REST source. | ||
| Running this function will first connect to the Azure Tenant that hosts the Windows Package Manager REST source. | ||
| The function will then collect the required URL before retrieving the contents of the Manifest for submission. | ||
|
|
||
| ## EXAMPLES | ||
|
|
||
| ### EXAMPLE 1 | ||
| ``` | ||
| Add-WinGetManifest -FunctionName "contosorestsource" -Path "C:\AppManifests\Microsoft.PowerToys\PowerToys.json" | ||
| ``` | ||
|
|
||
| Connects to Azure, then runs the Azure Function "contosorestsource" REST APIs to add the specified Manifest (*.json) | ||
| to the Windows Package Manager REST source. | ||
|
|
||
| ### EXAMPLE 2 | ||
| ``` | ||
| Add-WinGetManifest -FunctionName "contosorestsource" -Path "C:\AppManifests\Microsoft.PowerToys\" | ||
| ``` | ||
|
|
||
| Connects to Azure, then runs the Azure Function "contosorestsource" REST APIs to adds the Manifest (*.json / *.yaml) | ||
| found in the specified folder to the Windows Package Manager REST source. | ||
|
|
||
| ### EXAMPLE 3 | ||
| ``` | ||
| Add-WinGetManifest -FunctionName "contosorestsource" -Path "C:\AppManifests\Microsoft.PowerToys\PowerToys.json" -SubscriptionName "Visual Studio Subscription" | ||
| ``` | ||
|
|
||
| Connects to Azure and the specified Subscription, then runs the Azure Function "contosorestsource" REST APIs to add the | ||
| specified Manifest (*.json) to the Windows Package Manager REST source. | ||
|
|
||
| ## PARAMETERS | ||
|
|
||
| ### -FunctionName | ||
| Name of the Azure Function that hosts the Windows Package Manager REST source. | ||
|
|
||
| ```yaml | ||
| Type: String | ||
| Parameter Sets: (All) | ||
| Aliases: | ||
|
|
||
| Required: True | ||
| Position: 1 | ||
| Default value: None | ||
| Accept pipeline input: False | ||
| Accept wildcard characters: False | ||
| ``` | ||
| ### -Path | ||
| Supports input from pipeline. | ||
| The path to the Manifest file or folder hosting either a JSON or YAML file(s) that will be uploaded to the REST source. | ||
| This path may contain a single Manifest file, or a folder containing multiple YAML files for a single Manifest. | ||
| Does not support targeting a single folder containing multiple different Manifests. | ||
| ```yaml | ||
| Type: String | ||
| Parameter Sets: (All) | ||
| Aliases: | ||
|
|
||
| Required: True | ||
| Position: 2 | ||
| Default value: None | ||
| Accept pipeline input: True (ByValue) | ||
| Accept wildcard characters: False | ||
| ``` | ||
| ### -SubscriptionName | ||
| \[Optional\] The name of the subscription containing the Windows Package Manager REST source. | ||
| ```yaml | ||
| Type: String | ||
| Parameter Sets: (All) | ||
| Aliases: | ||
|
|
||
| Required: False | ||
| Position: Named | ||
| Default value: None | ||
| Accept pipeline input: False | ||
| Accept wildcard characters: False | ||
| ``` | ||
| ### CommonParameters | ||
| This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). | ||
| ## INPUTS | ||
| ## OUTPUTS | ||
| ## NOTES | ||
| ## RELATED LINKS |
Oops, something went wrong.