Skip to content

Commit 43edf49

Browse files
yao-msftyao-msft
authored
Doc updates for updated PowerShell module (#267)
1 parent 2af954b commit 43edf49

17 files changed

+1579
-1320
lines changed

‎README.md‎

Lines changed: 70 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,70 @@
1-
# Welcome to the winget-cli-restsource repository
2-
3-
## Building the client
4-
5-
### Prerequisites
6-
7-
* [Git Large File Storage (LFS)](https://git-lfs.github.com/)
8-
* [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/)
9-
* The following workloads:
10-
* .NET desktop development
11-
* Azure development
12-
* ASP<area>.NET and web development
13-
14-
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.
15-
16-
## Running locally
17-
18-
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.
19-
20-
1. In the `src\WinGet.RestSource.Functions` directory, run `generate_self_sign_cert.ps1` in PowerShell.
21-
* This will generate a test pfx and install it into the Root store.
22-
* It will automatically be used as the HTTPS cert during local execution, thanks to `launchSettings.json`
23-
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).
24-
* Navigate to the Keys section of your CosmosDB instance in the Azure portal to find your connection information.
25-
* If you've used the ARM templates as described above, your Database will be named `WinGet` and your Collection will be `Manifests`
26-
3. Copy `src\WinGet.RestSource.Functions\local.settings.template.json` to `local.settings.json` and populate required fields from the above Keys section.
27-
4. Run the `WinGet.RestSource.Functions` project locally in Visual Studio using F5.
28-
5. Add it as a source in winget with: `winget source add -n "winget-pkgs-restsource" -a https://localhost:7071/api/ -t "Microsoft.Rest"`
29-
30-
Your commands to winget will now use your locally running REST instance as the primary source.
31-
32-
## Running Tests
33-
34-
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
35-
36-
### Unit Testing Prerequisites
37-
38-
* Install the [Cosmos DB Emulator](https://docs.microsoft.com/azure/cosmos-db/local-emulator?tabs=ssl-netstd21)
39-
* Copy the `WinGet.RestSource.UnitTest\Test.runsettings.template.json` template configuration to `Test.runsettings.json`
40-
* 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.
41-
* Alternatively, all of the test configuration properties can be set as environment variables. This is useful for overriding properties in an ADO build.
42-
43-
### Integration Testing Prerequisites
44-
45-
* Install the [winget client](https://github.com/microsoft/winget-cli) locally.
46-
* Copy the `WinGet.RestSource.IntegrationTest\Test.runsettings.template.json` template configuration to `Test.runsettings.json`
47-
* Modify the `RestSourceUrl` property to point to a deployed rest source endpoint. You can use the below instructions to deploy a rest instance.
48-
* 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.
49-
* 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.
50-
51-
## Automatically create a rest source
52-
53-
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.
54-
55-
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.
56-
57-
| Required | Parameter | Description |
58-
|----------|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
59-
| Yes | Name | A string of letters which will be prefixed to your newly created Azure resources. |
60-
| Yes | ResourceGroup | The Resource Group that will be used to contain the Azure resources. |
61-
| No | SubscriptionName | The name of the Azure Subscription that will be used to pay for the Azure resources. |
62-
| No | Region | The Azure location where the Azure resources will be created. (Default: westus) |
63-
| No | ParameterOutput | The folder location that contains new items will be created in. |
64-
| No | RestSourcePath | Path to the compiled Rest API Zip file. (Default: .\RestAPI\CompiledFunctions.ps1) |
65-
| No | ImplementationPerformance | specifies the performance of the resources to be created for the Windows Package Manager rest source. ["Demo", "Basic", "Enhanced"] |
66-
| No | ShowConnectionInstructions | If specified, the instructions for connecting to the Windows Package Manager rest source. (Default: False) |
67-
68-
> [!Note]
69-
> The PowerShell Module must be re-imported each time the PowerShell window is closed.
70-
71-
**How to:**
72-
73-
1. From the Administrative PowerShell window run the following:
74-
```PowerShell
75-
PS C:\> New-WinGetSource -Name "contoso" -ResourceGroup "WinGetPrivateSource" -Region "westus" -ImplementationPerformance "Demo" -ShowConnectionInstructions
76-
```
77-
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.
78-
79-
80-
## Contributing
81-
82-
This project welcomes contributions and suggestions. Most contributions require you to agree to a
83-
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
84-
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
85-
86-
When you submit a pull request, a CLA bot will automatically determine whether you need to provide
87-
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
88-
provided by the bot. You will only need to do this once across all repos using our CLA.
89-
90-
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
91-
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
92-
contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
1+
# Welcome to the winget-cli-restsource repository
2+
3+
## Create a Windows Package Manager REST source on Azure with PowerShell
4+
5+
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.
6+
7+
Please visit [Create a Windows Package Manager REST source](/Tools/PowershellModule/doc/WingetRestSource.md) for more details.
8+
9+
## Building the client
10+
11+
### Prerequisites
12+
13+
* [Git Large File Storage (LFS)](https://git-lfs.github.com/)
14+
* [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/)
15+
* The following workloads:
16+
* .NET desktop development
17+
* Azure development
18+
* ASP<area>.NET and web development
19+
20+
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.
21+
22+
## Running locally
23+
24+
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.
25+
26+
1. In the `src\WinGet.RestSource.Functions` directory, run `generate_self_sign_cert.ps1` in PowerShell.
27+
* This will generate a test pfx and install it into the Root store.
28+
* It will automatically be used as the HTTPS cert during local execution, thanks to `launchSettings.json`
29+
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).
30+
* Navigate to the Keys section of your CosmosDB instance in the Azure portal to find your connection information.
31+
* If you've used the ARM templates as described above, your Database will be named `WinGet` and your Collection will be `Manifests`
32+
3. Copy `src\WinGet.RestSource.Functions\local.settings.template.json` to `local.settings.json` and populate required fields from the above Keys section.
33+
4. In source codes, change HttpTrigger level to Anonymous for InformationGet, ManifestSearchPost and ManifestGet endpoints.
34+
5. Run the `WinGet.RestSource.Functions` project locally in Visual Studio using F5.
35+
6. Add it as a source in winget with: `winget source add -n "winget-pkgs-restsource" -a https://localhost:7071/api/ -t "Microsoft.Rest"`
36+
37+
Your commands to winget will now use your locally running REST instance as a user added source.
38+
39+
## Running Tests
40+
41+
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
42+
43+
### Unit Testing Prerequisites
44+
45+
* Install the [Cosmos DB Emulator](https://docs.microsoft.com/azure/cosmos-db/local-emulator?tabs=ssl-netstd21)
46+
* Copy the `WinGet.RestSource.UnitTest\Test.runsettings.template.json` template configuration to `Test.runsettings.json`
47+
* 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.
48+
* Alternatively, all of the test configuration properties can be set as environment variables. This is useful for overriding properties in an ADO build.
49+
50+
### Integration Testing Prerequisites
51+
52+
* Install the [winget client](https://github.com/microsoft/winget-cli) locally.
53+
* Copy the `WinGet.RestSource.IntegrationTest\Test.runsettings.template.json` template configuration to `Test.runsettings.json`
54+
* Modify the `RestSourceUrl` property to point to a deployed REST source endpoint. You can use the below instructions to deploy a REST instance.
55+
* 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.
56+
* 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.
57+
58+
## Contributing
59+
60+
This project welcomes contributions and suggestions. Most contributions require you to agree to a
61+
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
62+
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
63+
64+
When you submit a pull request, a CLA bot will automatically determine whether you need to provide
65+
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
66+
provided by the bot. You will only need to do this once across all repos using our CLA.
67+
68+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
69+
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
70+
contact [[email protected]](mailto:[email protected]) with any additional questions or comments.

‎Tools/PowershellModule/doc/PowerShell/Add-WinGetManifest.md‎

Lines changed: 110 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -1,107 +1,110 @@
1-
---
2-
Module Name: Microsoft.WinGet.RestSource
3-
online version:
4-
schema: 2.0.0
5-
---
6-
7-
# Add-WinGetManifest
8-
9-
## SYNOPSIS
10-
Submits a Manifest file(s) to the Azure REST source
11-
12-
## SYNTAX
13-
14-
```
15-
Add-WinGetManifest [-FunctionName] <String> [-Path] <String> [[-SubscriptionName] <String>]
16-
[<CommonParameters>]
17-
```
18-
19-
## DESCRIPTION
20-
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.
21-
22-
The following Azure Modules are used by this script:
23-
Az.Resources
24-
Az.Accounts
25-
Az.Websites
26-
Az.Functions
27-
28-
## EXAMPLES
29-
30-
### EXAMPLE 1
31-
```
32-
Add-WinGetManifest -FunctionName "contosorestsource" -Path "C:\AppManifests\Microsoft.PowerToys\PowerToys.json"
33-
```
34-
35-
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
36-
37-
### EXAMPLE 2
38-
```
39-
Add-WinGetManifest -FunctionName "contosorestsource" -Path "C:\AppManifests\Microsoft.PowerToys\"
40-
```
41-
42-
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
43-
44-
### EXAMPLE 3
45-
```
46-
Add-WinGetManifest -FunctionName "contosorestsource" -Path "C:\AppManifests\Microsoft.PowerToys\PowerToys.json" -SubscriptionName "Visual Studio Subscription"
47-
```
48-
49-
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
50-
51-
## PARAMETERS
52-
53-
### -FunctionName
54-
Name of the Azure Function that hosts the REST source.
55-
56-
```yaml
57-
Type: String
58-
Parameter Sets: (All)
59-
Aliases:
60-
61-
Required: True
62-
Position: 1
63-
Default value: None
64-
Accept pipeline input: False
65-
Accept wildcard characters: False
66-
```
67-
68-
### -Path
69-
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.
70-
71-
```yaml
72-
Type: String
73-
Parameter Sets: (All)
74-
Aliases:
75-
76-
Required: True
77-
Position: 2
78-
Default value: None
79-
Accept pipeline input: False
80-
Accept wildcard characters: False
81-
```
82-
83-
### -SubscriptionName
84-
\[Optional\] The Subscription name contains the Windows Package Manager REST source
85-
86-
```yaml
87-
Type: String
88-
Parameter Sets: (All)
89-
Aliases:
90-
91-
Required: False
92-
Position: 3
93-
Default value: None
94-
Accept pipeline input: False
95-
Accept wildcard characters: False
96-
```
97-
98-
### CommonParameters
99-
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).
100-
101-
## INPUTS
102-
103-
## OUTPUTS
104-
105-
## NOTES
106-
107-
## RELATED LINKS
1+
---
2+
external help file: Microsoft.WinGet.RestSource-help.xml
3+
Module Name: microsoft.WinGet.RestSource
4+
online version:
5+
schema: 2.0.0
6+
---
7+
8+
# Add-WinGetManifest
9+
10+
## SYNOPSIS
11+
Submits a Manifest to the Windows Package Manager REST source.
12+
13+
## SYNTAX
14+
15+
```
16+
Add-WinGetManifest [-FunctionName] <String> [-Path] <String> [-SubscriptionName <String>]
17+
[-ProgressAction <ActionPreference>] [<CommonParameters>]
18+
```
19+
20+
## DESCRIPTION
21+
Submits a Manifest to the Windows Package Manager REST source.
22+
Running this function will first connect to the Azure Tenant that hosts the Windows Package Manager REST source.
23+
The function will then collect the required URL before retrieving the contents of the Manifest for submission.
24+
25+
## EXAMPLES
26+
27+
### EXAMPLE 1
28+
```
29+
Add-WinGetManifest -FunctionName "contosorestsource" -Path "C:\AppManifests\Microsoft.PowerToys\PowerToys.json"
30+
```
31+
32+
Connects to Azure, then runs the Azure Function "contosorestsource" REST APIs to add the specified Manifest (*.json)
33+
to the Windows Package Manager REST source.
34+
35+
### EXAMPLE 2
36+
```
37+
Add-WinGetManifest -FunctionName "contosorestsource" -Path "C:\AppManifests\Microsoft.PowerToys\"
38+
```
39+
40+
Connects to Azure, then runs the Azure Function "contosorestsource" REST APIs to adds the Manifest (*.json / *.yaml)
41+
found in the specified folder to the Windows Package Manager REST source.
42+
43+
### EXAMPLE 3
44+
```
45+
Add-WinGetManifest -FunctionName "contosorestsource" -Path "C:\AppManifests\Microsoft.PowerToys\PowerToys.json" -SubscriptionName "Visual Studio Subscription"
46+
```
47+
48+
Connects to Azure and the specified Subscription, then runs the Azure Function "contosorestsource" REST APIs to add the
49+
specified Manifest (*.json) to the Windows Package Manager REST source.
50+
51+
## PARAMETERS
52+
53+
### -FunctionName
54+
Name of the Azure Function that hosts the Windows Package Manager REST source.
55+
56+
```yaml
57+
Type: String
58+
Parameter Sets: (All)
59+
Aliases:
60+
61+
Required: True
62+
Position: 1
63+
Default value: None
64+
Accept pipeline input: False
65+
Accept wildcard characters: False
66+
```
67+
68+
### -Path
69+
Supports input from pipeline.
70+
The path to the Manifest file or folder hosting either a JSON or YAML file(s) that will be uploaded to the REST source.
71+
This path may contain a single Manifest file, or a folder containing multiple YAML files for a single Manifest.
72+
Does not support targeting a single folder containing multiple different Manifests.
73+
74+
```yaml
75+
Type: String
76+
Parameter Sets: (All)
77+
Aliases:
78+
79+
Required: True
80+
Position: 2
81+
Default value: None
82+
Accept pipeline input: True (ByValue)
83+
Accept wildcard characters: False
84+
```
85+
86+
### -SubscriptionName
87+
\[Optional\] The name of the subscription containing the Windows Package Manager REST source.
88+
89+
```yaml
90+
Type: String
91+
Parameter Sets: (All)
92+
Aliases:
93+
94+
Required: False
95+
Position: Named
96+
Default value: None
97+
Accept pipeline input: False
98+
Accept wildcard characters: False
99+
```
100+
101+
### CommonParameters
102+
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).
103+
104+
## INPUTS
105+
106+
## OUTPUTS
107+
108+
## NOTES
109+
110+
## RELATED LINKS

0 commit comments

Comments
 (0)