Bring Pinning to PowerShell Cmdlets by Trenly · Pull Request #6190 · microsoft/winget-cli

Kaleb Luedtke (Trenly) · 2026-04-29T17:55:52Z

Bring Pinning to PowerShell Cmdlets

I have signed the Contributor License Agreement.
I have updated the Release Notes.
This pull request is related to an issue.

Summary

This PR extends the WinGet pinning system with new metadata, a new CLI subcommand, expanded COM API surface, and PowerShell cmdlets for managing pins.

CLI Changes

winget pin add: Added --note argument to attach an optional freeform note to a pin. The timestamp when a pin is created is now recorded automatically.
winget pin list --details: New option that displays detailed information about pins for all packages or a specific package (query by ID, name, or keyword).

Pinning Index Schema (v1.1)

New schema version adds DateAdded and Note columns to the pin table to persist the new metadata.

COM API (`Microsoft.Management.Deployment`, contract v30)

PackageManager.GetAllPins() — retrieve all pins across all sources.
PackageManager.GetPins(CatalogPackage) — retrieve pins for a specific package.
PackageManager.PinPackage(CatalogPackage, PinPackageOptions) — add or update a pin.
PackageManager.UnpinPackage(CatalogPackage) — remove all pins for a package.
PackageManager.ResetAllPins(String sourceName) — reset all pins, optionally scoped to a source.
New PackagePin runtime class exposing PackageId, SourceId, Type, GatedVersion, DateAdded, Note, and IsForInstalledPackage.
New PinPackageOptions and PinPackageResult runtime classes.
New PackagePinType enum (PinnedByManifest, Pinning, Gating, Blocking).

PowerShell (`Microsoft.WinGet.Client`)

Add-WinGetPin — pin a package with a specified pin type, optional gated version, note, and force flag.
Get-WinGetPin — list pins, filterable by package/source.
Remove-WinGetPin — remove pins for a package.
Reset-WinGetPin — reset all pins, optionally scoped to a source.
Get-WinGetPackage — new IsPinned property on returned objects.

cc Demitrius Nelon (@denelon) for Naming

Microsoft Reviewers: Open in CodeFlow

Demitrius Nelon (denelon) · 2026-04-29T21:46:09Z

Were you able to figure out the PlatyPS MAML stuff for the PowerShell help?

Kaleb Luedtke (Trenly) · 2026-04-29T22:00:45Z

Were you able to figure out the PlatyPS MAML stuff for the PowerShell help?

Get-Help seems to work the same way for the new cmdlets as it does for the others. I might look at improving the PowerShell help separately in the future. This PR is already bigger than I'm sure John might like it to be, don't want to make anyone too frazzled

Copilot

Pull request overview

This PR expands WinGet’s pinning feature end-to-end (repository schema + CLI workflow + COM/WinRT API + PowerShell cmdlets), adding pin metadata (DateAdded, Note), a new winget pin show command, and PowerShell cmdlets to manage pins.

Changes:

Add DateAdded and Note support to the pinning index (schema v1.1) with migration from v1.0.
Extend the COM API surface for pin management (get/pin/unpin/reset) and expose PackagePin, PinPackageOptions, PinPackageResult.
Add PowerShell cmdlets (Get/Add/Remove/Reset-WinGetPin) and related PS output objects/help.

Reviewed changes

Copilot reviewed 59 out of 59 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/PowerShell/Microsoft.WinGet.Client/ModuleFiles/Microsoft.WinGet.Client.psd1	Exports new pin cmdlets from the module.
src/PowerShell/Microsoft.WinGet.Client.Engine/PSObjects/PSPinResult.cs	Adds PS wrapper for COM pin operation results.
src/PowerShell/Microsoft.WinGet.Client.Engine/PSObjects/PSPackagePin.cs	Adds PS wrapper for COM `PackagePin` objects.
src/PowerShell/Microsoft.WinGet.Client.Engine/PSObjects/PSInstalledCatalogPackage.cs	Adds `IsPinned` property on installed package output objects.
src/PowerShell/Microsoft.WinGet.Client.Engine/Helpers/PackageManagerWrapper.cs	Adds wrapper methods for new COM pin APIs.
src/PowerShell/Microsoft.WinGet.Client.Engine/Helpers/PSEnumHelpers.cs	Adds conversion helper for `PackagePinType`.
src/PowerShell/Microsoft.WinGet.Client.Engine/Helpers/ManagementDeploymentFactory.cs	Adds COM factory creation for `PinPackageOptions`.
src/PowerShell/Microsoft.WinGet.Client.Engine/Commands/ResetPinCommand.cs	Adds engine command to reset pins via COM.
src/PowerShell/Microsoft.WinGet.Client.Engine/Commands/PinPackageCommand.cs	Adds engine command to get/add/remove pins via COM.
src/PowerShell/Microsoft.WinGet.Client.Cmdlets/Common/Constants.cs	Adds parameter sets and noun constant for pin cmdlets.
src/PowerShell/Microsoft.WinGet.Client.Cmdlets/Cmdlets/ResetPinCmdlet.cs	Adds `Reset-WinGetPin` cmdlet.
src/PowerShell/Microsoft.WinGet.Client.Cmdlets/Cmdlets/RemovePinCmdlet.cs	Adds `Remove-WinGetPin` cmdlet (supports pipeline pin input).
src/PowerShell/Microsoft.WinGet.Client.Cmdlets/Cmdlets/PSObjects/PSPackagePinType.cs	Adds PowerShell-facing enum for pin types.
src/PowerShell/Microsoft.WinGet.Client.Cmdlets/Cmdlets/GetPinCmdlet.cs	Adds `Get-WinGetPin` cmdlet.
src/PowerShell/Microsoft.WinGet.Client.Cmdlets/Cmdlets/AddPinCmdlet.cs	Adds `Add-WinGetPin` cmdlet (type/gatedVersion/note/force).
src/PowerShell/Help/Microsoft.WinGet.Client/Reset-WinGetPin.md	Adds help documentation for reset pin cmdlet.
src/PowerShell/Help/Microsoft.WinGet.Client/Remove-WinGetPin.md	Adds help documentation for remove pin cmdlet.
src/PowerShell/Help/Microsoft.WinGet.Client/Microsoft.WinGet.Client.md	Adds module index entries for new cmdlets.
src/PowerShell/Help/Microsoft.WinGet.Client/Get-WinGetPin.md	Adds help documentation for get pin cmdlet.
src/PowerShell/Help/Microsoft.WinGet.Client/Add-WinGetPin.md	Adds help documentation for add pin cmdlet.
src/Microsoft.Management.Deployment/Public/ComClsids.h	Adds CLSIDs for `PinPackageOptions` activation.
src/Microsoft.Management.Deployment/PinPackageResult.h	Introduces WinRT result type for pin operations.
src/Microsoft.Management.Deployment/PinPackageResult.cpp	Implements WinRT result type for pin operations.
src/Microsoft.Management.Deployment/PinPackageOptions.h	Introduces WinRT options type for pin operations.
src/Microsoft.Management.Deployment/PinPackageOptions.cpp	Implements WinRT options type for pin operations.
src/Microsoft.Management.Deployment/PackagePin.h	Introduces WinRT `PackagePin` runtimeclass.
src/Microsoft.Management.Deployment/PackagePin.cpp	Implements WinRT `PackagePin` object creation from internal pins.
src/Microsoft.Management.Deployment/PackageManager.idl	Adds pinning APIs + types to the public WinRT contract.
src/Microsoft.Management.Deployment/PackageManager.h	Declares new `PackageManager` pinning methods.
src/Microsoft.Management.Deployment/PackageManager.cpp	Implements GetPins/GetAllPins/Pin/Unpin/Reset via pinning data store.
src/Microsoft.Management.Deployment/Microsoft.Management.Deployment.vcxproj	Adds new pin-related source/header files to project build.
src/Microsoft.Management.Deployment/Converters.h	Declares `GetPinOperationStatus` mapping.
src/Microsoft.Management.Deployment/Converters.cpp	Implements HRESULT→PinResultStatus mapping.
src/Microsoft.Management.Deployment/ComClsids.cpp	Enables in-proc→out-of-proc redirection for `PinPackageOptions`.
src/Microsoft.Management.Deployment.Projection/WinGetProjectionFactory.cs	Adds projection factory method for `PinPackageOptions`.
src/Microsoft.Management.Deployment.Projection/ClassesDefinition.cs	Registers `PinPackageOptions` class for projection activation.
src/AppInstallerRepositoryCore/Microsoft/Schema/Pinning_1_1/PinningIndexInterface_1_1.cpp	Adds v1.1 pinning schema interface + migration path.
src/AppInstallerRepositoryCore/Microsoft/Schema/Pinning_1_1/PinningIndexInterface.h	Declares v1.1 schema interface.
src/AppInstallerRepositoryCore/Microsoft/Schema/Pinning_1_1/PinTable.h	Declares v1.1 pin table with new columns.
src/AppInstallerRepositoryCore/Microsoft/Schema/Pinning_1_1/PinTable.cpp	Implements v1.1 pin table CRUD/migration including note/date.
src/AppInstallerRepositoryCore/Microsoft/Schema/Pinning_1_0/PinningIndexInterface_1_0.cpp	Implements `MigrateFrom` for v1.0 (not supported).
src/AppInstallerRepositoryCore/Microsoft/Schema/Pinning_1_0/PinningIndexInterface.h	Adds `MigrateFrom` to v1.0 interface declaration.
src/AppInstallerRepositoryCore/Microsoft/Schema/IPinningIndex.h	Adds `MigrateFrom` to schema interface abstraction.
src/AppInstallerRepositoryCore/Microsoft/PinningIndex.h	Adds helper to create schema interface for a specific version.
src/AppInstallerRepositoryCore/Microsoft/PinningIndex.cpp	Implements migration-on-open for pinning index and version dispatch.
src/AppInstallerRepositoryCore/AppInstallerRepositoryCore.vcxproj	Adds v1.1 pinning schema files to repository core build.
src/AppInstallerCommonCore/Public/winget/Pin.h	Adds `DateAdded` + `Note` fields to internal Pin model.
src/AppInstallerCLITests/PinningIndex.cpp	Adds unit tests for v1.1 schema and migration behavior.
src/AppInstallerCLITests/PinFlow.cpp	Adds workflow tests for note/date and new `pin show` behavior.
src/AppInstallerCLIPackage/Shared/Strings/en-us/winget.resw	Adds localized strings for `--note` and `pin show` output.
src/AppInstallerCLIPackage/Package.appxmanifest	Registers COM server class for `PinPackageOptions` (dev out-of-proc).
src/AppInstallerCLICore/Workflows/PinFlow.h	Declares new workflow step `ShowPinDetails`.
src/AppInstallerCLICore/Workflows/PinFlow.cpp	Sets date/note on add; implements `winget pin show` output filtering.
src/AppInstallerCLICore/Resources.h	Adds resource IDs for new pin strings.
src/AppInstallerCLICore/ExecutionArgs.h	Adds `PinNote` execution arg.
src/AppInstallerCLICore/Commands/PinCommand.h	Adds `PinShowCommand` declaration.
src/AppInstallerCLICore/Commands/PinCommand.cpp	Wires up `winget pin show` and adds `--note` to `pin add`.
src/AppInstallerCLICore/Argument.cpp	Adds CLI argument mapping for `--note`.
.github/actions/spelling/expect.txt	Adds expected spelling words introduced by new tests/log strings.

Copilot

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

Copilot

Pull request overview

Copilot reviewed 80 out of 80 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (6)

src/PowerShell/Microsoft.WinGet.Client.Cmdlets/Cmdlets/RemovePinCmdlet.cs:1

Remove-WinGetPin's PinSet parameter set ignores the piped PSPackagePin.SourceId and IsForInstalledPackage, and only uses PackageId to re-resolve a CatalogPackage. This can (a) throw VagueCriteriaException if the same Id exists in multiple sources, and (b) fail entirely for installed-package pins where PackageId is a ProductCode/PFN rather than an available package Id. Fix by using the pin object to disambiguate resolution: when SourceId is present, scope the search to that source; when IsForInstalledPackage is true, resolve via the installed package identity path (or change the engine command to unpin by pin key rather than re-searching). Add a test that pipes a pin from Get-WinGetPin where the package exists in multiple sources and/or covers installed-pin removal.
src/PowerShell/Microsoft.WinGet.Client.Engine/Helpers/PSEnumHelpers.cs:1
The default branch throws InvalidOperationException() without a message, which makes user-facing failures (and debugging) opaque when an invalid pin type string flows in. Prefer an exception with a clear message (e.g., ArgumentOutOfRangeException/InvalidOperationException including the invalid value and accepted values).
src/PowerShell/tests/Microsoft.WinGet.Client.Tests.ps1:1
RemoveTestSource is executed both in the new Describe's AfterAll and again in the file-level AfterAll. If RemoveTestSource is not idempotent, this can make the test suite flaky (second removal fails) and also makes cleanup ordering harder to reason about. Consider removing the nested RemoveTestSource or restructuring so the test source is added/removed in only one place for this file.
src/PowerShell/tests/Microsoft.WinGet.Client.Tests.ps1:1
RemoveTestSource is executed both in the new Describe's AfterAll and again in the file-level AfterAll. If RemoveTestSource is not idempotent, this can make the test suite flaky (second removal fails) and also makes cleanup ordering harder to reason about. Consider removing the nested RemoveTestSource or restructuring so the test source is added/removed in only one place for this file.
src/PowerShell/Microsoft.WinGet.Client.Engine/Commands/PinPackageCommand.cs:1
This uses async/await and Task.FromResult(...) around a synchronous operation, which creates unnecessary async state machines and makes the flow harder to read. If GetPackageAndExecuteAsync expects a Task<T>, return Task.FromResult(PackageManagerWrapper.Instance.PinPackage(...)) directly (non-async lambda), or if it supports sync delegates, call the sync operation directly.
src/Microsoft.Management.Deployment/PackageManager.cpp:1
GetPins() performs one DB lookup per derived PinKey (pinningData.GetPin(pinKey)), which can become a multi-query pattern for packages with many available versions and/or multiple installed identities. Consider fetching all pins once (GetAllPins) and filtering in-memory by key (e.g., build a hash set of requested keys) or adding a bulk-get API in PinningData/index layer to reduce DB round-trips.

- Remove detailed IDL interface definitions (too implementation-level for a spec; keep high-level description of needed COM surface) - Use PinType property instead of IsBlocking for future expandability (supports checking gating pins too) - Add PR microsoft#6190 (Configuration module improvements) to Resources Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

JohnMcPMS

Just a note for the future, please build things in layers 🥲 :

CLI
COM
PowerShell

That will help with faster reviews and iteration when we can focus on each part.

JohnMcPMS · 2026-06-22T17:49:56Z

+ addDateAdded.Execute(connection);
+
+ StatementBuilder addNote;
+ addNote.AlterTable(s_PinTable_Table_Name).Add(s_PinTable_Note_Column, Type::Text);


Can't you add multiple columns at once?

I'm not seeing any examples in the codebase where that's done today - perhaps I'm just missing it?

Kaleb Luedtke (Trenly) · 2026-06-22T18:35:43Z

CLI
COM
PowerShell
That will help with faster reviews and iteration when we can focus on each part.

Apprecate the advice and will do for the future (And thank you for your patience with me and my new friend 🤖 )

* Don't fake a name search

JohnMcPMS · 2026-08-05T23:42:30Z

Looking good (sorry about the slow feedback). I'm wondering if we should find some other method to record changes than a single file that commonly produces conflicts.

Kaleb Luedtke (Trenly) · 2026-08-05T23:53:14Z

Looking good (sorry about the slow feedback). I'm wondering if we should find some other method to record changes than a single file that commonly produces conflicts.

Thats what I've been wondering. . .

JohnMcPMS · 2026-08-06T00:03:32Z

/azp run

azure-pipelines · 2026-08-06T00:03:43Z

Azure Pipelines: Successfully started running 1 pipeline(s).

Kaleb Luedtke (Trenly) added 8 commits April 29, 2026 08:58

Add note, date created, and show subcommand
32b17d4

Add tests
697ca1d

Add pinning to COM APIs
b6502ef

Add IsPinned propery for Get-WingetPackage
ae483b0

Add pinning to PowerShell Cmdlets
fac4ec4

Spelling
7ce3b27

Inherit from 1.0 Interface
35322e7

Contract 29 is not released yet
236e667

Kaleb Luedtke (Trenly) marked this pull request as ready for review April 29, 2026 20:22

Kaleb Luedtke (Trenly) requested a review from a team as a code owner April 29, 2026 20:22

JohnMcPMS requested a review from Copilot April 30, 2026 15:44

Copilotstarted reviewing on behalf of JohnMcPMS April 30, 2026 15:48 View session

CopilotAI reviewed Apr 30, 2026
View reviewed changes

JohnMcPMS reviewed Apr 30, 2026
View reviewed changes

Kaleb Luedtke (Trenly) added 14 commits April 30, 2026 20:48

Adddress comments about resource strings
1c89957

Update comment to indicate the appropriate contract version
fa617a6

Make methods public
7f33f56

Adjust how new schema is created
3c7d4a6

Reduce duplicated code through inheritance
99a8760

Use statement builder, savepoints, and tuples for ownership
e336194

Use a time point instead of strings
0cb653b

Guard against non-existent source
29d6203

Cache IsPinned
184cc7a

Merge default pin add behavior into single test
952e56e

Ensure table is not created in a partial state
e823b75

Add an alternate function for optional parms
195846f

Move to PackageCatalogReference
0468b34

Move functionality to converters
4bfde99

Kaleb Luedtke (Trenly) requested a review from Copilot June 15, 2026 19:35

CopilotAI reviewed Jun 15, 2026

Kaleb Luedtke (Trenly) added 3 commits June 15, 2026 14:40

Update release notes
41e10af

Revert instructions edit
f05bcc8

Run renormalize
fdcd860

Kaleb Luedtke (Trenly) requested a review from Copilot June 15, 2026 19:42

Fix release notes
19406e9

CopilotAI reviewed Jun 15, 2026
View reviewed changes

Comment threaddoc/ReleaseNotes.md

Kaleb Luedtke (Trenly) requested a review from JohnMcPMS June 15, 2026 19:46

Kaleb Luedtke (Trenly) mentioned this pull request Jun 17, 2026
Specification: PowerShell Module Full Parity #6290
Draft
8 tasks

JohnMcPMS reviewed Jun 22, 2026
View reviewed changes

Kaleb Luedtke (Trenly) added 10 commits June 23, 2026 12:04

Merge remote-tracking branch 'upstream/master' into PinPlus
987bae2

Update comments to clearly indicate relation to previous log messages
aeb8fae

Update test to ensure empty notes column is hidden
80cf29a

Make public
fcaeace

Filter the list that creates row data
a923669
* Don't fake a name search

Show all columns and remove --details
77b4b7d

Ensure atomicity of get/remove operation in Pin Database
59af822

Make migration faliures non-fatal
2173a38

Update table implementation
5c43088

Merge remote tracking branch upstream/master
0c80e10

Kaleb Luedtke (Trenly) requested a review from JohnMcPMS July 28, 2026 00:17

Merge branch 'master' into PinPlus
fa8121b

Resolve stylecop issue and add xmldoc comment for function
2a51bb3

Uh oh!

Conversation

Kaleb Luedtke (Trenly) commented Apr 29, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

CLI Changes

Pinning Index Schema (v1.1)

COM API (Microsoft.Management.Deployment, contract v30)

PowerShell (Microsoft.WinGet.Client)

Microsoft Reviewers: Open in CodeFlow

Uh oh!

Demitrius Nelon (denelon) commented Apr 29, 2026

Uh oh!

Kaleb Luedtke (Trenly) commented Apr 29, 2026

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

JohnMcPMS left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JohnMcPMSJun 22, 2026

Choose a reason for hiding this comment

Uh oh!

Kaleb Luedtke (Trenly)Jun 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Kaleb Luedtke (Trenly) commented Jun 22, 2026

Uh oh!

JohnMcPMS commented Aug 5, 2026

Uh oh!

Kaleb Luedtke (Trenly) commented Aug 5, 2026

Uh oh!

JohnMcPMS commented Aug 6, 2026

Uh oh!

azure-pipelinesBot commented Aug 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Kaleb Luedtke (Trenly) commented Apr 29, 2026•
edited
Loading

COM API (`Microsoft.Management.Deployment`, contract v30)

PowerShell (`Microsoft.WinGet.Client`)