Ocelot Files

Upgrade to .NET 10 SDK (TFM net10.0, version 25.0) a.k.a. the .NET 10 release

Milestone: .NET 10 :point_left: Codenamed: .NET 10 Read the Docs: Ocelot 25.0 with PDF Target Framework Monikers: net8.0, net9.0, net10.0

:information_source: About

On November 11th, 2025, the .NET team announced the release of the .NET 10 framework:

• .NET Blog: Announcing .NET 10

This major release upgrades the Ocelot package TFMs to net10.0 in addition to the current net8.0 and net9.0. Thus, the current Ocelot supported frameworks are .NET 8 LTS, .NET 9 STS, and .NET 10 LTS.

Additionally, in this major release the Ocelot team focused on preparing the codebase and its ecosystem for the .NET 10 SDK (.NET 10 milestone), while also extracting several integrated extension packages from the v24.1 monorepo into their own dedicated repositories to speed up delivery and reduce release coupling. As a result of these DevOps activities, the Ocelot repository now hosts only two package projects — Ocelot (src folder) and Ocelot.Testing (github.com) (testing folder) — along with two solutions, Ocelot.slnx and Ocelot.Samples.slnx, which can be opened or built only if the .NET 10 SDK is installed. Since the extension packages now live in separate repositories, a new Release Radar status page has been introduced to track their progress.

This major version also includes the following feature updates:

• A built-in Quality of Service (QoS) circuit breaker (express edition) that works out of the box without requiring the Polly library.
• Significant enhancements to the WebSockets feature, including WebSockets middleware overriding and the addition of Security Options to the WebSockets pipeline.
• Improved Configuration experience that merges multiple ocelot.*.json files, keeping users' extended properties available during Ocelot app startup and at runtime via the standard IConfiguration service in the DI container.

Finally, because the repository has a new folder structure, the development team recommends recloning or even reforking the Ocelot repository for a successful upgrade to the new version in order to avoid potential build errors.

As a best practice, the release strategy has been aligned with .NET SDK monthly patches (usually available between the 10th and 15th of each month). The development team will therefore also aim to roll out monthly Ocelot patches that reference the new .NET SDK patched versions. Ocelot patches will follow the form of a beta or patched version major.minor.*, where * is the Ocelot patch number corresponding to the newly available .NET SDK patch.

Ideally, the Ocelot team expects accelerated releases with more frequent minor/patch versions, because DevOps is now prepared for the new release strategy and offers fast delivery.

For successful contributions, maintainers will announce an identity-verification procedure (details for first-time contributors will be published soon).

:new: What's New?

• :star: Quality of Service: A "Built-in Circuit Breaker" feature implementation was added by @ocelot-ot in pull request [#2385] — no Polly required. :star:

Ocelot's QoS schema no longer strictly depends on the external Ocelot.QualityOfService.Polly (www.nuget.org) package to provide circuit breaking and timeout enforcement. A lightweight, thread-safe circuit breaker (Closed → Open → HalfOpen → Closed) ships in the Ocelot core package, supporting both count-based and FailureRatio-based modes. The two implementations are mutually exclusive: the last of AddQualityOfService() or AddPolly() registered on the OcelotBuilder wins. See the built-in QoS documentation for full details, including the AddQualityOfService<THandler>() extensibility point for overriding server error codes.

• WebSockets: The "Overridable WebSocket buffer size" feature and custom middleware injection were added by @erannevo in pull request [#2387].

The previously hard-coded DefaultWebSocketBufferSize is now a protected virtual property that can be overridden by subclassing. The Middleware Injection feature was extended with a WebSocketsProxyMiddleware override on the OcelotPipelineConfiguration class, allowing a fully custom WebSocket middleware to be injected into the pipeline. Refer to the "Sample" section to understand how to utilize the new feature.

• WebSockets: The "SecurityOptions support for the WebSocket pipeline" feature was added by @CurtisRobertOliver in pull request [#2406].

Previously, IP allow/block-list Routing "Security Options" were not enforced for WebSocket upgrade requests (a.k.a. the CONNECT HTTP method), allowing them to bypass IP security. WebSocket upgrade requests are now intercepted by the same IPSecurityPolicy used for regular HTTP requests, and denied upgrades now correctly return 403 Forbidden.

• :star: Configuration: The "Extend configuration with Custom Properties" feature was implemented by @jlukawska in pull request [#1183]. :star:

Ocelot's configuration builder now merges custom (non-schema) JSON properties defined across multiple ocelot.*.json files using Newtonsoft's JToken merge functionality, instead of the last-loaded file silently overwriting properties from previous files in the Routes collection. This also applies to the DynamicRoutes collection and the GlobalConfiguration section. See the updated Configuration documentation, especially the "Extend configuration with Custom Properties" section, and the Configuration Sample app for details.

• :airplane: Aggregation: A new "Manual/custom aggregators for Complex Aggregation" feature has been published (originally developed by @TomPallister in pull requests [#248], [#310]). :airplane:

While working on bug [#2248] in pull request [#2328] by @NandanDevHub, the development team uncovered an undocumented feature in the Multiplexer namespace and decided to publish this pilot feature in the "Aggregate Manually?" documentation. The feature is based on the IResponseAggregator interface, whose correct application is currently unclear. The Ocelot team will test it further in upcoming releases, develop best practices, create a sample app, and inform the community. For this reason we warn that the feature is still in pilot status. :airplane:

:up: What's Updated?

• Extension packages extraction [#2334]: The Ocelot team continued extracting integrated extension packages out of the monorepo into their own dedicated repositories, each with an independent release cycle:

• Ocelot.Cache.CacheManager (github.com) in pull request [#2360]

• Ocelot.Tracing.Butterfly (github.com) in pull request [#2361]
• Ocelot.Tracing.OpenTracing (github.com) in pull request [#2362]
• Ocelot.Discovery.Eureka (github.com) (renamed from Ocelot.Provider.Eureka, see issue [#2371]) in pull request [#2372]
• Ocelot.QualityOfService.Polly (github.com) (renamed from Ocelot.Provider.Polly, see issue [#2378]) in pull request [#2380]
• Ocelot.Discovery.Consul (github.com) (renamed from Ocelot.Provider.Consul, see issue [#2378]) in pull request [#2388]
• Ocelot.Discovery.KubeClient (github.com) (renamed from Ocelot.Provider.Kubernetes, see issue [#2378]) in pull request [#2404]

This keeps the Ocelot core repository lean, avoids delays caused by the integrated packages' own release schedules, and lets each provider evolve independently. Consult the Caching, Tracing, Service Discovery, and Kubernetes chapters for package-specific upgrade notes. Please note that some of the packages are deprecated! To watch the status of each package and its repository, go to the Release Radar status page.

• Kubernetes: The "PollKube provider" was redesigned by @raman-m in pull request [#2358].

The PollKube discovery provider was redesigned to utilize PeriodicTimer (introduced in .NET 6). The provider is based on an "active polling" strategy that requires stable behavior and careful management of timing events in multi-threaded scenarios. The new PeriodicTimer is designed for thread safety, and its callbacks replace the old Timer callbacks, which work fine in a synchronous flow. Please note that the PollKube discovery provider is now part of the Ocelot.Discovery.KubeClient (github.com) package.

• DevOps: Extensive testing and tooling modernization was carried out by contributors ahead of .NET 10 milestone:

• Solutions upgraded to the Visual Studio 2026 Solution File Format a.k.a. .NET 10 CLI solution file format (.sln → .slnx), by @raman-m in pull request [#2354].

• Testing projects migrated from xUnit v2 to xUnit v3 (by @methran1304 in [#2356]), and acceptance tests migrated to the Microsoft.Testing.Platform framework (by @raman-m in [#2392]).
• Ocelot.Testing (github.com) was re-embedded into the monorepo (by @ocelot-ot in [#2364]) and later excluded from Cobertura coverage via coverlet.runsettings (by @ocelot-ot in [#2365]).
• Codecov coverage reporting was installed for the repository, by @raman-m in pull request [#2359].
• NuGet packages were continuously bumped to their latest versions to support .NET SDK 10.0.* (.NET Runtime 10.0.*), by @raman-m and @ocelot-ot in pull requests [#2367], [#2389], [#2402], and [#2409].

The updated documentation also highlights the deprecation of certain packages through multiple notes and warnings. With the Obsolete attributes in place, C# developers will notice several warnings in the build logs during compilation.

:package: Patches

• Routing: Issue [#2346] was patched by @bhargav-polara in pull request [#2351].

This fixes a bug where downstream URL query parameter names could be corrupted if they contained a placeholder with a non-empty value. The DownstreamUrlCreatorMiddleware query-string merging algorithm was refactored to take full advantage of ASP.NET Core's QueryHelpers.

• Error Handling: Issue [#2376] was patched by @Majdi-Zlitni in pull request [#2379].

Requests containing non-ASCII characters in HTTP header values previously surfaced as an unhandled HttpRequestException and an HTTP 502 Bad Gateway response. Ocelot now catches this HttpRequestException and maps it to a 400 Bad Request response, in line with RFC 7230 "Field Parsing" rules.

• :fire: WebSockets: Critical issue [#2403] was patched by @CurtisRobertOliver in pull request [#2406]. :fire:

Previously, IP allow/block-list Routing "Security Options" were not enforced for WebSocket upgrade requests, allowing them to bypass IP security. WebSocket upgrade requests are now intercepted by the same IPSecurityPolicy used for regular HTTP requests, and denied upgrades now correctly return 403 Forbidden.

This critical security issue was detected by security scanners on GitHub after the bug was reported. :see_no_evil: Many thanks to George Chen (@geo-chen) for reporting this critical bug.

• Aggregation: Issue [#2248] was patched by @NandanDevHub in pull request [#2328].

Complex Aggregation routes configured with the RouteKeysConfig array now correctly map route keys to the corresponding aggregator context, fixing a bug where keys could be mismatched or dropped during multiplexing.

• Administration: Issue [#989] was patched by @mmustafasenoglu in pull request [#2412].

The {adminPath}/configuration and {adminPath}/outputcache/{region} endpoints are now decorated with [ApiExplorerSettings(IgnoreApi = true)] so that they no longer appear in Swagger/OpenAPI documentation generated for the downstream API surface.

Honoring :medal_sports: Top 5 Contributors :clap:

1^st :1st_place_medal: goes to Ocelot Robot for delivering 3 features 2^nd :2nd_place_medal: goes to jlukawska for delivering 1 feature in 32 files changed 3^rd :3rd_place_medal: goes to Eran Nevo for delivering 1 feature in 21 files changed 4^th :orange_heart: goes to Majdi Zlitni for delivering 1 feature in 17 files changed 5^th :yellow_heart: goes to CurtisRobertOliver for delivering 1 feature in 15 files changed

Starring :star: Release Influencers :bowtie:

:star::star::star::star::star::star::star::star::star::star::star::star::star::star::star::star::star::star::star::star::star::star::star::star: Raman Maksimchuk :star::star::star: Ocelot Robo :star::star::star: Ocelot Robot :star: ocelotgateway :star: jlukawska :star: Eran Nevo :star: Majdi Zlitni :star: CurtisRobertOliver :star: Methran G. :star: Nandan Parmar :star: bhargav-polara :star: mmustafasenoglu :star: Miňo Martiniak

Features in Release 25.0.0

Logbook

- _{78c983d8 by **Raman Maksimchuk** on Wednesday, July 29 at 13:38 →} Release v25.0 | Upgrade to net10.0 TFM | .NET 10 release (#2415) - _{1a2d8290 by **Ocelot Robot** on Thursday, July 23 at 21:51 →} Update docs for Ocelot v25 based on 25.0.0-beta.4 tag (#2413) - _{bc8d4f24 by **Raman Maksimchuk** on Wednesday, July 22 at 23:06 →} Pre-Release Ocelot v25 beta 4 and Ocelot.Testing v25 beta 10 (#2411) - _{bef1ad9b by **mmustafasenoglu** on Wednesday, July 22 at 17:10 →} [#989] Hide Administration controllers from Swagger and OpenAPI (#2412) - _{5f084f17 by **Ocelot Robot** on Friday, July 17 at 18:55 →} Add Release Radar .md doc with dynamic package badges (#2408) - _{9fb9d9b7 by **Ocelot Robot** on Thursday, July 16 at 18:04 →} Ref SDK 10.0.302 (Runtime 10.0.10) to release Ocelot v25 beta 4 and Ocelot.Testing v25 beta 10+ (#2409) - _{7b38a950 by **jlukawska** on Saturday, July 11 at 19:22 →} [#651] Merge custom JSON properties across multiple ocelot.X.json configuration files using Newtonsoft's JToken merge functionality (#1183) - _{c5ee5101 by **Miňo Martiniak** on Friday, July 03 at 14:22 →} Add info about `MMLib.SwaggerForOcelot` package to the Introduction "Not Supported" chapter (#1429) - _{2634264f by **Nandan Parmar** on Wednesday, July 01 at 04:14 →} [#2248] Ensure correct mapping of RouteKeysConfig arrays in aggregates (#2328) - _{6ceb308b by **Raman Maksimchuk** on Monday, June 29 at 15:30 →} Normalize line endings with .gitattributes - _{f156fd40 by **CurtisRobertOliver** on Saturday, June 27 at 11:56 →} [#2403] Add `SecurityOptions` support to the WebSocket pipeline (#2406) - _{6062d5a5 by **Raman Maksimchuk** on Wednesday, June 24 at 17:05 →} Follow-up [#2405] Update unit test coverage paths in workflows and cache dependency paths for "Setup .NET" steps - _{f6552b73 by **Raman Maksimchuk** on Monday, June 22 at 20:35 →} [#2378] Shorten file paths for the new folder structure (#2405) - _{a69a4235 by **Raman Maksimchuk** on Friday, June 19 at 22:44 →} [#2378] Deprecate Ocelot.Provider.Kubernetes project in favor of a dedicated repository (#2404) - _{053287a8 by **Ocelot Robot** on Saturday, June 13 at 13:17 →} Ref SDK 10.0.301 (Runtime 10.0.9) to release Ocelot v25 beta 4 and Ocelot.Testing v25 beta 10+ (#2402) - _{6353f8ba by **Ocelot Robot** on Thursday, June 11 at 19:14 →} Harden the Kube provider, repository FileConfigurationPoller, and infrastructure InMemoryBus, and stabilize their tests (#2399) - _{0bd72fd3 by **Raman Maksimchuk** on Saturday, June 06 at 19:01 →} Release Ocelot.Discovery.Consul v25.0.0-beta.3 and update Service Discovery feat docs (Consul Provider section) - _{c20325bc by **Ocelot Robot** on Monday, June 01 at 20:33 →} Harden `FileConfigurationPoller` against timer reentrancy and callback thread leaks, and stabilize `TimeoutDelegatingHandler` timeout test (#2394) - _{e4022a7d by **Raman Maksimchuk** on Saturday, May 30 at 13:05 →} Pre-Release Ocelot v25 beta 3 and Ocelot.Testing v25 beta 8 - _{fe00b04e by **Eran Nevo** on Thursday, May 28 at 21:25 →} [#2386] Overridable WebSocket buffer size via virtual property and custom middleware injection (#2387) - _{e324bba0 by **Raman Maksimchuk** on Sunday, May 24 at 17:53 →} Migrate to Microsoft.Testing.Platform framework & xUnit v3 for acceptance testing (#2392) - _{a5efd3cc by **Raman Maksimchuk** on Thursday, May 21 at 18:56 →} Ref SDK 10.0.300 (Runtime 10.0.8) to release Ocelot v25 beta 3 and Ocelot.Testing v25 beta 8+ (#2389) - _{5db7db87 by **Raman Maksimchuk** on Saturday, May 09 at 16:24 →} [#2378] Deprecate Ocelot.Provider.Consul project in favor of a dedicated repository (#2388) - _{fe672ec0 by **Ocelot Robo** on Tuesday, April 28 at 20:19 →} [#2384] Built-in Circuit Breaker for Quality of Service (express edition, no Polly required) (#2385) - _{c3720c55 by **Raman Maksimchuk** on Monday, April 20 at 17:21 →} [#2378] Deprecate Ocelot.Provider.Polly project in favor of a dedicated repository (#2380) - _{1724c495 by **Raman Maksimchuk** on Saturday, April 18 at 18:11 →} Follow up [#2379] Review InvalidHeaderValueTests (#2382) - _{e881c975 by **Majdi Zlitni** on Thursday, April 16 at 19:58 →} [#2375] [#2376] Map non-ASCII header `HttpRequestException` to 400 Bad Request according to RFC 7230 (#2379) - _{5eeb9ccc by **Raman Maksimchuk** on Tuesday, March 24 at 20:47 →} [#2334] [#2371] Deprecate Ocelot.Provider.Eureka project in favor of a dedicated repository (#2372) - _{9acc2719 by **Raman Maksimchuk** on Friday, March 20 at 15:55 →} Pre-Release 25.0 aka Beta 2 (#2369) - _{086c7b15 by **Ocelot Robo** on Tuesday, March 17 at 22:48 →} Bump all NuGet packages to the latest versions for .NET SDK 10.0.201 (aka .NET Runtime 10.0.5) (#2367) - _{02aaa769 by **Ocelot Robo** on Friday, March 13 at 20:26 →} Follow-up [#2363] [#2364]: Exclude Ocelot.Testing from Cobertura coverage via coverlet.runsettings (#2365) - _{e4e73af4 by **Raman Maksimchuk** on Friday, March 13 at 14:22 →} Follow-up [#2364]: Improve Ocelot.Testing experience by refactoring and removing the direct reference to v25.0.0-beta.3 - _{daa6ffeb by **ocelotgateway** on Thursday, March 12 at 17:00 →} [#2363] Embed Ocelot.Testing back into the Ocelot mono-repo (#2364) - _{d38a0018 by **Raman Maksimchuk** on Saturday, March 07 at 21:18 →} [#2334] Deprecate Ocelot.Tracing.OpenTracing project in favor of a dedicated repository (#2362) - _{f972f896 by **Raman Maksimchuk** on Friday, March 06 at 15:19 →} [#2334] Deprecate Ocelot.Tracing.Butterfly project in favor of a dedicated repository (#2361) - _{8921fb2f by **Raman Maksimchuk** on Tuesday, March 03 at 14:58 →} [#2334] Deprecate Ocelot.Cache.CacheManager project in favor of a dedicated repository (#2360) - _{bc196e9e by **Raman Maksimchuk** on Thursday, February 26 at 17:34 →} Install Codecov coverage app (#2359) - _{12b9204b by **Raman Maksimchuk** on Wednesday, February 25 at 17:27 →} Release 25.0 Beta 1 | +semver: major - _{9134d613 by **Raman Maksimchuk** on Wednesday, February 25 at 14:07 →} [#2354] Follow-up: Redesign PollKube discovery using PeriodicTimer (#2358) - _{fccf792f by **Methran G.** on Tuesday, February 17 at 09:54 →} [#2341] Testing projects xUnit v2 to v3 migration (#2356) - _{070593c0 by **Raman Maksimchuk** on Monday, February 09 at 16:20 →} Follow up [#2354]: Bump Ocelot.Testing to 25.0.0-beta.1 * Warning ASPDEPR008: 'IWebHostBuilder.Build()' is obsolete: 'IWebHost is obsolete. Use IHost instead. For more information, visit https://aka.ms/aspnet/deprecate/008 - _{b8cc478b by **Raman Maksimchuk** on Thursday, January 29 at 10:38 →} [#2344] Upgrade solutions to Visual Studio 2026 format (#2354) - _{55095d8e by **bhargav-polara** on Wednesday, January 21 at 21:56 →} [#2346] Fix problem with downstream URLs where query parameter names get messed up if they contain a placeholder that has a non-empty value (#2351)