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

Trenly · 2026-04-29T17:55:52Z

I have signed the Contributor License Agreement.
I have updated the Release Notes.
- I'd like to get the code itself reviewed before I generate 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 show: New subcommand that displays detailed information about pins for 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 v29)

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 @denelon for Naming

Microsoft Reviewers: Open in CodeFlow

denelon · 2026-04-29T21:46:09Z

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

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.

JohnMcPMS · 2026-04-30T16:15:40Z

            std::make_unique<PinRemoveCommand>(FullName()),
            std::make_unique<PinListCommand>(FullName()),
            std::make_unique<PinResetCommand>(FullName()),
+            std::make_unique<PinShowCommand>(FullName()),


I would prefer that we follow the model of package list and have --details on the existing list command. That also removes the need to create a whole new search mechanism and just makes the change in ReportPins.

Followup: Well it looks like it would need a whole new search mechanism to actually implement the arguments that it claims to support...

Yes, we would need a whole new search mechanism anyways. I do think that there is some overlap with winget list <query> --details, but to me it felt more akin to winget show <query>. The semantics of list vs show as a base command don't really apply to pins. Where show in the base command is for a remote package / manifest information, list is for installed applications.

I will think on this and probably end up refactoring to extend the behavior of list instead of adding show

JohnMcPMS · 2026-04-30T23:03:07Z

+                auto newPin = CreatePinFromOptions(pinKey, options);
+
+                auto existingPin = pinningData.GetPin(pinKey);
+                if (existingPin && !(*existingPin == newPin))


Shouldn't this only be comparing the pin type rather than the entire pin?

I don't think so. The CLI compares the version as well for gating pins so that updating a gating pin by overwriting it requires --force . e.g winget pin add Microsoft.WingetCreate --version 1.9 and then running winget pin add Microsoft.WingetCreate --version 1.10 would give an error that there is already a pin and it needs to be overriden.

This matches the behavior of the CLI

JohnMcPMS · 2026-04-30T23:38:48Z

+    /// <summary>
+    /// Must match the user-settable values of Microsoft.Management.Deployment.PackagePinType.
+    /// </summary>
+    public enum PSPackagePinType


Do we need the "pinned by the manifest" type?

I don't believe we do, since it isn't user-settable and the CLI doesn't expose it when listing pins as far as I can tell

It feels like a thing that we probably should expose everywhere, but that can be a separate change.

It is no longer needed since the interface surface is so small

* Updated .github/copilot-instructions.md

Copilot

Pull request overview

Copilot reviewed 78 out of 78 changed files in this pull request and generated 8 comments.

Copilot · 2026-05-01T15:10:20Z

+        bool hasName = context.Args.Contains(Execution::Args::Type::Name);
+        bool hasQuery = context.Args.Contains(Execution::Args::Type::Query);
+        bool exactMatch = context.Args.Contains(Execution::Args::Type::Exact);
+


winget pin show currently allows running with no query/id/name arguments, in which case it will match every pin and dump verbose details for all of them. This seems inconsistent with the intent of a "show" command (and the comment above suggests at least one filter is expected). Consider enforcing that at least one of --id/--name/--query is provided and terminating with an appropriate error message when none are specified.

Suggested change

if (!hasId && !hasName && !hasQuery)

{

context.Reporter.Error() << "The 'pin show' command requires at least one of --id, --name, or --query." << std::endl;

AICLI_TERMINATE_CONTEXT(APPINSTALLER_CLI_ERROR_INVALID_CL_ARGUMENTS);

}

JohnMcPMS

I would like to see the PinTable stuff be thought through more to re-use code in a way that allows the 1.0 code to stay largely untouched and 1.0 to leverage it without anything over.

JohnMcPMS · 2026-05-07T23:14:07Z

 - Parsing in `AppInstallerCommonCore/Manifest/`
 - Multi-file manifests: installer, locale, version, defaultLocale

+## SQLite Statement Builder


This should go into a path specific instructions file (with the appropriate target paths). It is a lot of lines that are only needed in a few cases.

JohnMcPMS · 2026-05-07T23:15:31Z

+| `Equals(optional<T>)` | `IS NULL` | **WHERE** / filter clauses |
+| `AssignValue(optional<T>)` | `= ?` (binds NULL) | **UPDATE SET** assignments |
+
+Using `Equals(optional)` in an UPDATE SET clause is a bug — SQLite does not accept `col = IS NULL`.


Suggested change

Using `Equals(optional)` in an UPDATE SET clause is a bug — SQLite does not accept `col = IS NULL`.

Using `Equals(optional)` in an UPDATE SET clause is a bug — SQLite does not accept `col IS NULL`.

JohnMcPMS · 2026-05-07T23:20:04Z

 #include <Microsoft/Schema/IPinningIndex.h>
 #include <Microsoft/Schema/Pinning_1_0/PinTable.h>
-#include <Microsoft/Schema/Pinning_1_1/PinTable.h>
+#include <Microsoft/Schema/Pinning_1_1/PinTable_1_1.h>


We can definitely leave the header as PinTable.h.

JohnMcPMS · 2026-05-07T23:21:25Z

 {
    Builder::StatementBuilder update;
-    update.Update(s_tableName).Set().Column(s_firstColumn).Equals(firstVal).Column(s_secondColumn).Equals(secondVal);
+    update.Update(s_tableName).Set().Column(s_firstColumn).AssignValue(firstVal).Column(s_secondColumn).AssignValue(secondVal);


New test that provides an empty optional?

JohnMcPMS · 2026-05-07T23:27:37Z

        bool ResetAllPins(SQLite::Connection& connection, std::string_view sourceId) override;
+
+    protected:
+        virtual SQLite::rowid_t IAddPin(SQLite::Connection& connection, const Pinning::Pin& pin);


The proper mechanism would be:

V1_1::AddPin(pin) { savepoint_1_1; pin_row = V1_0::AddPin(pin); modify_new_pin_with_new_fields(pin_row, pin); savepoint_1_1.commit(); }

This is certainly inefficient, but it ensures the proper separation of schema concerns. So a bug fix in 1_0 doesn't have to be duplicated across the range.

JohnMcPMS · 2026-05-07T23:34:39Z

+
+    protected:
+        // Creates the table with named indices.
+        static void Create(SQLite::Connection& connection);


Why is this protected?

JohnMcPMS · 2026-05-08T17:34:04Z

+    }
+
+    using namespace std::string_view_literals;
+    static constexpr std::string_view s_PinTable_Table_Name = "pin"sv;


These here and 1.0 should be moved to under the PinTable type so that they are not defined multiple times.

JohnMcPMS · 2026-05-08T17:37:35Z

-                m_interface = CreateIPinningIndexForVersion(m_version);
-            }
+
+            m_interface = std::move(latestInterface);


Should be inside the above if block (is a functional no-op when they are already the same except for a tiny bit of move overhead).

JohnMcPMS · 2026-05-08T17:54:49Z

        /// </summary>
        protected override void ProcessRecord()
        {
+            if (this.Blocking && !string.IsNullOrEmpty(this.GatedVersion))


Can we do this through parameter sets? Not sure if it is more complicated or by how much, but it would better integrate with PS (at least I assume that once it has decided which set you are using on the shell it won't offer tab-suggestions from the other sets).

JohnMcPMS · 2026-05-08T18:10:37Z

+                return;
+            }
+
+            // Fetch all pins in a single COM call and build a lookup set to avoid


This feels like it is shifting the cost up front; a cost that doesn't need to be paid when the caller doesn't examine the IsPinned property. This isn't a single COM call either, ever PackageId property retrieval is also one. I think it would be better to just cache the IsPinned state from the previous change lazily rather than forcibly populating it.

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

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

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

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

Copilot AI reviewed Apr 30, 2026

View reviewed changes

JohnMcPMS reviewed Apr 30, 2026

View reviewed changes

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

Trenly added 7 commits April 30, 2026 23:17

Remove version comment

243798b

It is no longer needed since the interface surface is so small

Update filters so 1.1 schema is visible

4b7b8ef

Create the correct interface and migrate only if newer

e93e3d1

Use correct version info

ae87ff1

Move invariants outside try catch

917db77

Add TryRemovePin for simplicity

34a727c

Refactor to use -Blocking and -GatedVersion

01aad8e

This comment has been minimized.

Sign in to view

Trenly added 10 commits May 1, 2026 08:43

Spelling

ad9932f

Add Pester Tests

a96e43e

Tests should now be part of default creation test

fde7382

Further abstract the interface

d5f682c

Update test name

8f819c1

Add comment

91f532a

Appease our AI overlords with an update to their tomes

595abca

* Updated .github/copilot-instructions.md

Unify on AssignValue to avoid future confusion

7e83a83

Ensure pin writes always record the last updated time

615ddca

Use original symbol for creation

1f8932d

Trenly requested a review from Copilot May 1, 2026 15:03

Copilot started reviewing on behalf of Trenly May 1, 2026 15:04 View session

Add missing System namepace

df55096

Copilot AI reviewed May 1, 2026

View reviewed changes

Trenly added 6 commits May 1, 2026 10:12

Restore conditional setting of date

6d085dd

Ensure ShouldProcess is always respected

ea9f0d8

Fix minor issue in copilot instructions

d207c77

Validate provided pin types

349a0a1

Cache all pins and only fall back to get if set is empty

840e5ae

Change file name to remove override

65f8373

JohnMcPMS reviewed May 8, 2026

View reviewed changes

+        if (!hasId && !hasName && !hasQuery)
+        {
+            context.Reporter.Error() << "The 'pin show' command requires at least one of --id, --name, or --query." << std::endl;
+            AICLI_TERMINATE_CONTEXT(APPINSTALLER_CLI_ERROR_INVALID_CL_ARGUMENTS);
+        }

	Using `Equals(optional)` in an UPDATE SET clause is a bug — SQLite does not accept `col = IS NULL`.
	Using `Equals(optional)` in an UPDATE SET clause is a bug — SQLite does not accept `col IS NULL`.

Conversation

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 v29)

PowerShell (Microsoft.WinGet.Client)

Microsoft Reviewers: Open in CodeFlow

Uh oh!

denelon commented Apr 29, 2026

Uh oh!

Trenly commented Apr 29, 2026

Uh oh!

Copilot AI 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI May 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JohnMcPMS left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Trenly commented Apr 29, 2026 •

edited

Loading

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

PowerShell (`Microsoft.WinGet.Client`)