ShellInterop.JumpList
0.2.0-preview.1
dotnet add package ShellInterop.JumpList --version 0.2.0-preview.1
NuGet\Install-Package ShellInterop.JumpList -Version 0.2.0-preview.1
<PackageReference Include="ShellInterop.JumpList" Version="0.2.0-preview.1" />
<PackageVersion Include="ShellInterop.JumpList" Version="0.2.0-preview.1" />
<PackageReference Include="ShellInterop.JumpList" />
paket add ShellInterop.JumpList --version 0.2.0-preview.1
#r "nuget: ShellInterop.JumpList, 0.2.0-preview.1"
#:package ShellInterop.JumpList@0.2.0-preview.1
#addin nuget:?package=ShellInterop.JumpList&version=0.2.0-preview.1&prerelease
#tool nuget:?package=ShellInterop.JumpList&version=0.2.0-preview.1&prerelease
ShellInterop.JumpList
Windows-only Jump List Tasks publisher targeting net10.0-windows; depends on ShellInterop.Core >= 0.2.0-preview.1 (a NuGet dependency, restored transitively). This is a pre-release (0.2.0-preview.1), released together with ShellInterop.Core 0.2.0-preview.1. Publishing the package is not a legal clearance, and is separate from distributing an application that uses it. Earlier internal Core builds numbered 0.1.0-preview.1 included the JumpList types and were never published on NuGet.org. Add a reference to this package and rebuild when migrating from that earlier Core code. The namespace remains ShellInterop.Core.JumpLists, but binary compatibility is not guaranteed.
Supports Tasks, one or more custom categories (JumpListDefinition.FromEntriesWithCategories, Categories; Category is the single-category view) with removed-destination protection (Fake-tested; real Shell: SHELL-JL-05 single category, SHELL-JL-07 multiple categories, conditional PASS), apply/delete results and safe publisher shutdown. Separators are supported; Recent/Frequent are not implemented. Split-assembly real Shell regression passed without separators (SHELL-SPLIT-02); separators inside TasksFallback are real-Shell confirmed (SHELL-JL-07). MIT license; see LICENSE and the repository's rights-review notes.
Packing the JumpList project with the old 0.1.0-preview.1 version remains blocked by a guard (the old Core lacks the split internals); the current 0.2.0-preview.1 of both projects packs. For local tests of other versions, pass the same -p:Version=... to both projects and do not publish it.
Use JumpListDefinition.FromEntries(appId, [JumpListEntry.ForTask(taskA), JumpListEntry.Separator(), JumpListEntry.ForTask(taskB)]) for mixed ordered entries. The existing task-only constructor remains valid. Entries is authoritative and Tasks excludes separators; the local 100-task cap and RequestedTaskCount exclude separators. Entry-based error indices count all entries. Windows ignores leading/trailing separators and suppresses adjacent duplicates; the library preserves the supplied sequence. BeginList minimum slots exclude separators and headers only up to four, and additional ones can reduce displayed destinations. Real Shell: separators inside TasksFallback were confirmed with this library (SHELL-JL-07); a standalone test application using this library's public API also confirmed separator display (SHELL-JL-02). Other layouts are not verified.
Custom category and removed-destination tracking (SHELL-JL-04)
Real Shell status. The behaviour below is covered by Fake tests; real-Shell checks cover a single category (SHELL-JL-05) and multiple categories with removed-destination tracking and the privacy-setting E_ACCESSDENIED fallback (SHELL-JL-07, conditional PASS). SHELL-JL-08 (conditional PASS) added real-Shell checks of removed destinations after Explorer restart and a later-category E_ACCESSDENIED induced by changing the privacy setting mid-transaction. Not verified: a naturally occurring later-category E_ACCESSDENIED, empty-Tasks clearing, OS restart, other Windows builds. Fake-test results are not real-Shell results.
Registration success does not mean the Shell displays every destination: it limits the displayed count, and the JumpListItems_Maximum registry value changes that count. Put important destinations in the first categories; see the repository README ("Displayed destination count") for the observed behavior and its limits.
CommitList discards the Shell's removed-destinations list, even for a Tasks-only Apply. To avoid silently losing a user's "remove from this list", use JumpListDefinition.FromEntries(appId, entries, category, tracking):
JumpRemovedDestinationTracking(opt-in, independent of the category):ExcludedDestinationKeysandMatchOnly(identities recognised but not displayed, e.g. hidden groups or previously registered items). With tracking on, the removed list is read on every Apply, with or without a category.JumpCategoryDefinition:Name,Destinations(JumpDestinationDefinition: stableKey+ link) and optionalTasksFallback. A category without tracking is a validation error (Tracking.Required); once a category has ever been used, Tasks-only Applies must keep passing tracking (with an empty category orMatchOnly), otherwise removals are consumed unnoticed.- Matching uses only Arguments (Ordinal) and path (OrdinalIgnoreCase), never display names or order. Arguments and Keys must be unique across destinations and
MatchOnly. A link whose Arguments match but whose path differs isAmbiguous(Apply stops) unless the definition setsPathPolicy = AllowArgumentsOnly, i.e. the caller asserts the Arguments are a stable identifier unique to its app. The library hard-codes no argument format. - Classification in
RemovedDestinations:Matched,Foreign/ForeignItem(reported, do not block),Unreadable/Ambiguous(block). A readable link that matches nothing isForeign, so register former items inMatchOnlyif they must be protected.
Flow ("detect → abort → caller persists → apply again"):
- If a
Matchedremoval is not inExcludedDestinationKeys, the library callsAbortListand returnsRemovedDestinationsPending. Nothing is committed (ShellState = Unchanged,Succeeded = false,Error = null). Pending is not Success. - Persisting the keys is the caller's responsibility (the library stores nothing). Save every
Matchedkey withAlreadyExcluded == false, and only then add them toExcludedDestinationKeys. Never pass unsaved keys. - Apply again after saving. Excluded destinations are never appended again.
RemovedDestinationUnidentifiable: an element was unreadable or ambiguous (or the list could not be read); aborted, nothing committed, the removed list is kept.
AppendCategory: only E_ACCESSDENIED (privacy setting/policy) is tolerated. With no TasksFallback the category is omitted (CategorySkipped); with one, the caller's explicit static entries are added to Tasks (TasksFallback). Destinations are never converted automatically, keyed fallback entries (JumpListEntry.ForKeyedTask) are dropped while excluded, duplicates of ordinary tasks are rejected, and separators are trimmed/merged inside the block (one separator is inserted after ordinary tasks). Do not put history-derived items in the fallback; the Windows privacy setting is never changed. Any other failing HRESULT aborts (CategoryAppendFailed). Each Apply tries AppendCategory again.
Result fields: EffectiveDisplayMode (set on success only: TasksOnly, CategoryAndTasks, CategoryEmpty, TasksFallback, CategorySkipped), FallbackReason, RemovedDestinations. They describe COM results, not what Explorer shows.
JumpListEntry is an API input model, not a persistence format; persist application data separately and reconstruct entries with the factories.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0-windows7.0 is compatible. |
-
net10.0-windows7.0
- ShellInterop.Core (>= 0.2.0-preview.1)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.2.0-preview.1 | 58 | 11/14/2026 |