ShellInterop.JumpList 0.2.0-preview.1

This is a prerelease version of ShellInterop.JumpList.
dotnet add package ShellInterop.JumpList --version 0.2.0-preview.1
                    
NuGet\Install-Package ShellInterop.JumpList -Version 0.2.0-preview.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="ShellInterop.JumpList" Version="0.2.0-preview.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="ShellInterop.JumpList" Version="0.2.0-preview.1" />
                    
Directory.Packages.props
<PackageReference Include="ShellInterop.JumpList" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add ShellInterop.JumpList --version 0.2.0-preview.1
                    
#r "nuget: ShellInterop.JumpList, 0.2.0-preview.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package ShellInterop.JumpList@0.2.0-preview.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=ShellInterop.JumpList&version=0.2.0-preview.1&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=ShellInterop.JumpList&version=0.2.0-preview.1&prerelease
                    
Install as a Cake Tool

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): ExcludedDestinationKeys and MatchOnly (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: stable Key + link) and optional TasksFallback. 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 or MatchOnly), 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 is Ambiguous (Apply stops) unless the definition sets PathPolicy = 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 is Foreign, so register former items in MatchOnly if they must be protected.

Flow ("detect → abort → caller persists → apply again"):

  1. If a Matched removal is not in ExcludedDestinationKeys, the library calls AbortList and returns RemovedDestinationsPending. Nothing is committed (ShellState = Unchanged, Succeeded = false, Error = null). Pending is not Success.
  2. Persisting the keys is the caller's responsibility (the library stores nothing). Save every Matched key with AlreadyExcluded == false, and only then add them to ExcludedDestinationKeys. Never pass unsaved keys.
  3. Apply again after saving. Excluded destinations are never appended again.
  4. 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 Compatible and additional computed target framework versions.
.NET net10.0-windows7.0 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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