Ocelot

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

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

ℹ️ 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 (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).

🆕 What's New?

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

   Ocelot's QoS schema no longer strictly depends on the external Ocelot.QualityOfService.Polly 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.

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

   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.

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

   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. ✈️

🆙 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 in pull request #2360
• Ocelot.Tracing.Butterfly in pull request #2361
• Ocelot.Tracing.OpenTracing in pull request #2362
• Ocelot.Discovery.Eureka (renamed from Ocelot.Provider.Eureka, see issue #2371) in pull request #2372
• Ocelot.QualityOfService.Polly (renamed from Ocelot.Provider.Polly, see issue #2378) in pull request #2380
• Ocelot.Discovery.Consul (renamed from Ocelot.Provider.Consul, see issue #2378) in pull request #2388
• Ocelot.Discovery.KubeClient (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 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 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.

📦 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.

WebSockets: Critical issue #2403 was patched by @CurtisRobertOliver in pull request #2406. 🔥

   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. 🙈
   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 🏅 Top 5 Contributors 👏

1^st 🥇 goes to Ocelot Robot for delivering 3 features
2^nd🥈 goes to Jolanta Łukawska for delivering 1 feature in 32 files changed
3^rd 🥉 goes to Eran Nevo for delivering 1 feature in 21 files changed
4^th 🧡 goes to Majdi Zlitni for delivering 1 feature in 17 files changed
5^th 💛 goes to Curtis Oliver for delivering 1 feature in 15 files changed

Starring ⭐ Release Influencers

⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐ Raman Maksimchuk
⭐⭐⭐⭐⭐⭐⭐ Ocelot Robot, @ocelot-ot
⭐ Jolanta Łukawska, @jlukawska
⭐ Eran Nevo, @erannevo
⭐ Majdi Zlitni, @Majdi-Zlitni
⭐ Curtis Oliver, @CurtisRobertOliver
⭐ Methran G., @methran1304
⭐ Nandan Parmar, @NandanDevHub
⭐ Bhargav Polara, @bhargav-polara
⭐ Mustafa Şenoğlu, @mmustafasenoglu
⭐ Miňo Martiniak, @Burgyn

Features in Release 25.0

Logbook

• _{78c983d by Raman Maksimchuk on Wednesday, July 29 at 13:38 →}
  Release v25.0 | Upgrade to net10.0 TFM | .NET 10 release (#2415)
• _{1a2d829 by Ocelot Robot on Thursday, July 23 at 21:51 →}
  Update docs for Ocelot v25 based on 25.0.0-beta.4 tag (#2413)
• _{bc8d4f2 by Raman Maksimchuk on Wednesday, July 22 at 23:06 →}
  Pre-Release Ocelot v25 beta 4 and Ocelot.Testing v25 beta 10 (#2411)
• _{bef1ad9 by mmustafasenoglu on Wednesday, July 22 at 17:10 →}
  #989 Hide Administration controllers from Swagger and OpenAPI (#2412)
• _{5f084f1 by Ocelot Robot on Friday, July 17 at 18:55 →}
  Add Release Radar .md doc with dynamic package badges (#2408)
• _{9fb9d9b 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)
• _{7b38a95 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)
• _{c5ee510 by Miňo Martiniak on Friday, July 3 at 14:22 →}
  Add info about MMLib.SwaggerForOcelot package to the Introduction "Not Supported" chapter (#1429)
• _{2634264 by Nandan Parmar on Wednesday, July 1 at 04:14 →}
  #2248 Ensure correct mapping of RouteKeysConfig arrays in aggregates (#2328)
• _{6ceb308 by Raman Maksimchuk on Monday, June 29 at 15:30 →}
  Normalize line endings with .gitattributes
• _{f156fd4 by CurtisRobertOliver on Saturday, June 27 at 11:56 →}
  #2403 Add SecurityOptions support to the WebSocket pipeline (#2406)
• _{6062d5a 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
• _{f6552b7 by Raman Maksimchuk on Monday, June 22 at 20:35 →}
  #2378 Shorten file paths for the new folder structure (#2405)
• _{a69a423 by Raman Maksimchuk on Friday, June 19 at 22:44 →}
  #2378 Deprecate Ocelot.Provider.Kubernetes project in favor of a dedicated repository (#2404)
• _{053287a 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)
• _{6353f8b by Ocelot Robot on Thursday, June 11 at 19:14 →}
  Harden the Kube provider, repository FileConfigurationPoller, and infrastructure InMemoryBus, and stabilize their tests (#2399)
• _{0bd72fd by Raman Maksimchuk on Saturday, June 6 at 19:01 →}
  Release Ocelot.Discovery.Consul v25.0.0-beta.3 and update Service Discovery feat docs (Consul Provider section)
• _{c20325b by Ocelot Robot on Monday, June 1 at 20:33 →}
  Harden FileConfigurationPoller against timer reentrancy and callback thread leaks, and stabilize TimeoutDelegatingHandler timeout test (#2394)
• _{e4022a7 by Raman Maksimchuk on Saturday, May 30 at 13:05 →}
  Pre-Release Ocelot v25 beta 3 and Ocelot.Testing v25 beta 8
• _{fe00b04 by Eran Nevo on Thursday, May 28 at 21:25 →}
  #2386 Overridable WebSocket buffer size via virtual property and custom middleware injection (#2387)
• _{e324bba by Raman Maksimchuk on Sunday, May 24 at 17:53 →}
  Migrate to Microsoft.Testing.Platform framework & xUnit v3 for acceptance testing (#2392)
• _{a5efd3c 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)
• _{5db7db8 by Raman Maksimchuk on Saturday, May 9 at 16:24 →}
  #2378 Deprecate Ocelot.Provider.Consul project in favor of a dedicated repository (#2388)
• _{fe672ec 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)
• _{c3720c5 by Raman Maksimchuk on Monday, April 20 at 17:21 →}
  #2378 Deprecate Ocelot.Provider.Polly project in favor of a dedicated repository (#2380)
• _{1724c49 by Raman Maksimchuk on Saturday, April 18 at 18:11 →}
  Follow up #2379 Review InvalidHeaderValueTests (#2382)
• _{e881c97 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)
• _{5eeb9cc by Raman Maksimchuk on Tuesday, March 24 at 20:47 →}
  #2334 #2371 Deprecate Ocelot.Provider.Eureka project in favor of a dedicated repository (#2372)
• _{9acc271 by Raman Maksimchuk on Friday, March 20 at 15:55 →}
  Pre-Release 25.0 aka Beta 2 (#2369)
• _{086c7b1 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)
• _{02aaa76 by Ocelot Robo on Friday, March 13 at 20:26 →}
  Follow-up #2363 #2364: Exclude Ocelot.Testing from Cobertura coverage via coverlet.runsettings (#2365)
• _{e4e73af 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
• _{daa6ffe by ocelotgateway on Thursday, March 12 at 17:00 →}
  #2363 Embed Ocelot.Testing back into the Ocelot mono-repo (#2364)
• _{d38a001 by Raman Maksimchuk on Saturday, March 7 at 21:18 →}
  #2334 Deprecate Ocelot.Tracing.OpenTracing project in favor of a dedicated repository (#2362)

Note truncated.

Summer-Autumn 2025 (version 24.1) a.k.a. the Globality release

Milestone: Summer'25 👈
Codenamed: Globality
Read the Docs: Ocelot 24.1 with PDF

ℹ️ About

In this minor release, the Ocelot team put the spotlight on the Configuration feature as part of their semi-annual 2025 effort, with a particular focus on the Global Configuration Schema. This release enhances support for global configurations across both routing modes: the classic static Routing and the service discovery-based Dynamic Routing.

The updated documentation highlights the deprecation of certain options through multiple notes and warnings. This deprecation process will be completed in the upcoming .NET 10 release. With the [Obsolete] attributes in place, C# developers will notice several warnings in the build logs during compilation.

On top of that, this release brings a great enhancement to the Kubernetes provider, also known as the Ocelot.Provider.Kubernetes package.

🆕 What's New?

Configuration: The "Dynamic routing global configuration" feature has been redesigned by @raman-m and contributors.

This update brings changes to the Dynamic Route Schema and Global Configuration Schema, while the Route Schema stays the same apart from deprecation updates. All work was coordinated under issue #585, which addressed the challenges of configuring Ocelot's most popular features globally before version 24.1, when dynamic routing gained global configuration partial support, but static routing mostly lacked it. A key outcome of #585 is the ability to override global configuration options within the DynamicRoutes collection. This ongoing issue will continue to require attention, as adapting static route global configurations for dynamic routing is complex and, in some cases, impossible. This will be a challenge for future Ocelot releases and the community.

Kubernetes: The "Kubernetes provider based on watch requests" feature by @kick2nick in PR #2174. ⭐

The Ocelot.Provider.Kubernetes package now features a new WatchKube provider for Kubernetes service discovery. This provider is a great fit for high-load environments where the older Kube and PollKube providers struggle to handle heavy traffic, often leading to increased log errors, HTTP 500 issues, and potential Ocelot instance failures. WatchKube is the next step in the evolution of these providers, leveraging the reactive capabilities of the KubeClient API. For guidance on choosing the right provider for your Kubernetes setup, check out the "Comparing providers" section in the documentation.

Configuration: The "Routing default timeout" feature by @hogwartsdeveloper in PR #2073.

In the past, the Timeout setting in the Route Schema didn't actually stop requests, defaulting instead to a fixed 90 seconds. Custom timeouts were handled using the Quality of Service Timeout strategy, and this only applied if Polly and the Ocelot.Provider.Polly package were used. Now, the Timeout option (in seconds) can be set at the route, global, and QoS levels. The Global Configuration Schema and Dynamic Route Schema also include the new Timeout setting, making it possible to configure default timeouts for dynamic routing as well.

Quality of Service: The "FailureRatio and SamplingDuration parameters of Polly V8 circuit-breaker" feature by @RaynaldM in PR #2081.

Starting with version 24.1, two new parameters in QoSOptions, FailureRatio and SamplingDuration, let you fine-tune the behavior of the Circuit Breaker strategy. Both can be configured globally, even with dynamic routing.
Please note that DurationOfBreak, ExceptionsAllowedBeforeBreaking, and TimeoutValue are now deprecated in 24.1, so check the QoSOptions Schema documentation for details.

🆙 What's Updated?

Configuration: Several File-model options have been deprecated by @raman-m.

The updated docs now highlight these deprecated options with multiple notes and warnings. The v24.1 deprecation process will wrap up in the upcoming .NET 10 release. Due to the Obsolete attributes, C# developers will notice several build warnings during compilation.

Testing: The Ocelot.Testing project was deprecated by @raman-m in PR #2295.

The project was removed from the main repo and moved to its own Ocelot.Testing repository. This change allows the Ocelot.Testing package to be shared independently for extension package delivery. The Ocelot team also plans to deprecate more projects and move them to separate repos because: a) despite the fact that a monorepo enables faster builds and quicker delivery; b) but the release process can be delayed by missing versions of integrated libraries in extension packages. The goal is for the Ocelot repo to only contain essential projects, avoiding delays caused by integrated package release schedules. Legacy or abandoned integrated packages should be deprecated and maintained in their own repos with independent release cycles.

Headers Transformation: Added global configuration by @marklonquist in PR #1659.

The Global Configuration Schema now includes new DownstreamHeaderTransform and UpstreamHeaderTransform options. These work only with static routes, meaning the Routes collection (see Route Schema). They aren't supported for dynamic routes because they're not part of the Dynamic Route Schema, and Ocelot Core doesn't read global configuration of this feature in dynamic routing mode. This is noted in the Roadmap documentation.

Authentication: Added global configuration by @jlukawska in PR #2114.

The Global Configuration Schema now includes a new AuthenticationOptions property for setting up static routes globally. This also introduces the AllowAnonymous boolean option within AuthenticationOptions to control static route authentication. Later, PR #2336 extended global authentication support to dynamic routes.
Note: The AuthenticationProviderKey option is deprecated in version 24.1—see the AuthenticationOptions Schema documentation for details.

Rate Limiting: Re-designed global configuration by @MiladRv and @raman-m in PR #2294.

The Global Configuration Schema now includes a new RateLimitOptions property for both static and dynamic routes. Previously, global configuration was available through RateLimitOptions in dynamic routing mode, while route overriding used the now-deprecated RateLimitRule from the Dynamic Route Schema.
This marks the second major overhaul of the Rate Limiting feature since the first update in PR #1592. A new Wait option has been added, replacing the deprecated PeriodTimespan, to enhance the Fixed Window algorithm. The full list of deprecated options can be found in the Deprecated Options documentation.

Load Balancer: Added global configuration by @raman-m in PR #2324.

The Global Configuration Schema now includes a new LoadBalancerOptions property for both static and dynamic routes. Previously, global configuration was available through LoadBalancerOptions in dynamic routing mode without dynamic route overrides. Starting with version 24.1, the Dynamic Route Schema also supports LoadBalancerOptions for overriding, and global configuration for static routes is now supported as well.

Caching: Added global configuration by @raman-m in PR #2331.

The Global Configuration Schema now includes a new CacheOptions property for both static and dynamic routes. Global configuration has been available for static routes since version 23.3, but starting with version 24.1, the Dynamic Route Schema also supports CacheOptions for overriding.
Note that the FileCacheOptions property in the Route Schema (static routes) is deprecated in version 24.1. For more details, see the caching Configuration documentation.

Http Handler: Added global configuration by @raman-m in PR #2332.

The Global Configuration Schema now includes a new HttpHandlerOptions property for both static and dynamic routes. Previously, global configuration was available through HttpHandlerOptions in dynamic routing mode without dynamic route overriding. Starting with version 24.1, the Dynamic Route Schema also supports HttpHandlerOptions for overriding, and global configuration is now available for static routes as well.

Authentication: Added global configuration by @raman-m in PR #2336.

The Global Configuration Schema now includes a new AuthenticationOptions property for both static and dynamic routes. Starting with version 24.1, the Dynamic Route Schema also supports AuthenticationOptions to override global settings.
Note that the AuthenticationProviderKey option is deprecated in version 24.1, so check the AuthenticationOptions Schema documentation for details.

Quality of Service: Added global configuration by @raman-m in PR #2339.

The Global Configuration Schema now includes a new QoSOptions property for both static and dynamic routes. Previously, global configuration was available through QoSOptions in dynamic routing mode without the option for dynamic route overrides. Starting with version 24.1, the Dynamic Route Schema supports QoSOptions for overriding, and global configuration support is now available for static routes as well.
Note that the DurationOfBreak, ExceptionsAllowedBeforeBreaking, and TimeoutValue options are deprecated in version 24.1. For details, see the QoSOptions Schema documentation.

DevOps: Stabilized tests and reviewed GH-Actions workflows by @raman-m in PRs #2342 and #2345.

These efforts kept the CI/CD builds in GitHub Actions stable, targeting the beta release of version 24.1. The CI/CD environment was set up and tested GH-Actions workflows in advance for the beta release, which is the goal of PR #2347.

📦 Patches

Websockets: Issue #930 patch by @hogwartsdeveloper in PR #2091.

This update removes the troublesome System.Net.WebSockets.WebSocketException from logs, preventing Ocelot from running into 500 status disasters. The issue stemmed from client-side or network events that Ocelot's WebSocketsProxyMiddleware couldn't anticipate on the server side. The patch now checks for incorrect connection statuses, attempting to close the connection and end server-side tasks gracefully without errors.

Kubernetes: Issue #2304 patch by @raman-m in PR #2335.

This update fixes the PollKube provider to address a bug with the first cold request, where the winning thread got an empty collection before the initial callback was triggered. The solution is to call the integrated discovery provider for the first cold request when the queue is empty.

Authorization: Issue #913 patch by @mehyaa in PR #1478.

Starting with version 24.1, Ocelot now supports RFC 8693 (OAuth 2.0 Token Exchange) for the scope claim in the ScopesAuthorizer service, also referred to as the IScopesAuthorizer service in the DI container.

Honoring 🏅 aka Top Contributors 👏

1^st 🥇 goes to Zhannur Akhmetkhanov for delivering 2 features
2^nd 🥈 goes to Milad Rivandi for delivering 1 feature in 136 files changed
3^rd 🥉 goes to Jolanta Łukawska for delivering 1 feature in 39 files changed

Starring ⭐ aka Release Influencers

⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐ Raman Maksimchuk, @raman-m
⭐⭐ Zhannur Akhmetkhanov, @hogwartsdeveloper
⭐ Milad Rivandi, @MiladRv
⭐ Jolanta Łukawska, @jlukawska
⭐ Nikolay Kuksov, @kick2nick
⭐ Mehmet Yasin Akar, @mehyaa
⭐ Harris Zhang, @harris2012
⭐ Mark Bøg Lønquist, @marklonquist
⭐ Raynald Messié, @RaynaldM

Features in Release 24.1

Logbook

• _{6be80d8 by Raman Maksimchuk on Wednesday, December 24 at 10:05 →}
  #2343 Release 24.1 Beta.1 (#2348)
• _{2f317b7 by Raman Maksimchuk on Tuesday, December 23 at 17:22 →}
  #2343 Release 24.1 Beta | +semver: minor (#2347)
• _{fede41d by Raman Maksimchuk on Friday, December 19 at 17:19 →}
  #2343 Pre-release 24.1 | +semver: patch (#2345)
• _{fff9cf7 by Raman Maksimchuk on Tuesday, December 9 at 21:20 →}
  Follow-up on #2335 and #2339: Stabilize flaky tests in the CI/CD environment (#2342)
• _{adc34ec by Mehmet Yasin AKAR on Sunday, December 7 at 21:16 →}
  #913 Support RFC 8693 (OAuth 2.0 Token Exchange) for the "scope" claim in ScopesAuthorizer (#1478)
• _{35dbc9d by Raman Maksimchuk on Thursday, December 4 at 17:25 →}
  #585 #2338 Quality of Service global configuration (#2339)
• _{4730613 by Raman Maksimchuk on Monday, November 24 at 9:48 →}
  #585 #2316 Authentication global configuration (#2336)
• _{1fdf6c2 by Raman Maksimchuk on Tuesday, November 11 at 13:45 →}
  #2304 Utilize ConcurrentQueue{T} for managing service versions during polling by the PollKube discovery provider (#2335)
• _{9127387 by Raman Maksimchuk on Sunday, November 9 at 22:36 →}
  #585 #2320 Http handler global configuration (#2332)
• _{e3ad51c by Raman Maksimchuk on Monday, October 27 at 18:09 →}
  #585 #2330 Caching global configuration (#2331)
• _{f758ba7 by Raman Maksimchuk on Thursday, October 23 at 00:36 →}
  #585 #2319 Load Balancer global configuration (#2324)
• _{3c6f648 by Raman Maksimchuk on Thursday, September 25 at 18:04 →}
  #1440 #2318 Remove the GH Actions step /usr/lib/dotnet since the old DevOps lifehack is no longer necessary
• _{e6b2023 by Raman Maksimchuk on Thursday, September 25 at 17:37 →}
  #1440 Update license file (#2318)
• _{d5e6d9a by Milad Rivandi on Tuesday, September 23 at 10:55 →}
  #585 #1229 #1598 #1915 Rate limiting global configuration (#2294)
• _{265f9b4 by jlukawska on Sunday, August 10 at 21:00 →}
  #842 #1414 Introduce AllowAnonymous authentication option with global AuthenticationOptions configuration (#2114)
• _{c7b9c91 by Harris Zhang on Tuesday, August 5 at 18:13 →}
  Use the appropriate class name as a type parameter to create a named logger through the factory in the ConfigurationMiddleware constructor (#2306)
• _{c29d821 by Mark Bøg Lønquist on Saturday, July 26 at 15:38 →}
  #1658 Add global configuration for Headers Transformation (#1659)
• _{c721273 by Raynald Messié on Saturday, July 19 at 18:21 →}
  #2080 Add new FailureRatio and SamplingDuration V8 parameters to fine-tune Polly's circuit-breaker strategy via route-level and global QoS options (#2081)
• _{7c583bf by Zhannur Akhmetkhanov on Friday, July 4 at 21:10 →}
  #1314 #1869 #2072 Default timeout for all levels, including route, global, and QoS (#2073)
• _{8143d56 by Nikolay on Monday, June 16 at 16:16 →}
  #2168 A brand-new WatchKube provider for Kubernetes service discovery (#2174)
• _{ed8ba5b by Raman Maksimchuk on Thursday, June 12 at 22:45 →}
  Follow up #2091 Update the Develop & Release workflows to include two actions: adding DNS records and installing certificates
• _{e527f27 by Zhannur Akhmetkhanov on Friday, June 13 at 1:01 →}
  #930 Try to close WebSocket destination when state is Open or CloseReceived (#2091)
• _{0b794b3 by Raman Maksimchuk on Tuesday, May 27 at 13:33 →}
  Publish Administration docs of the new Ocelot.Administration.IdentityServer4 package
• _{cae58d5 by Raman Maksimchuk on Friday, May 23 at 12:52 →}
  Deprecate the Ocelot.Testing project in favor of its NuGet package (#2295)
• _{e78fe42 by Raman Maksimchuk on Tuesday, April 22 at 19:56 →}
  Rewrite the README and roll back the status badge targets to develop

What's Changed

• Deprecate the Ocelot.Testing project in favor of its NuGet package by @raman-m in #2295
• #930 Try to close WebSocket destination when state is Open or CloseReceived by @hogwartsdeveloper in #2091
• #2168 A brand-new WatchKube provider for Kubernetes service discovery by @kick2nick in #2174
• #1314 #1869 #2072 Default timeout for all levels, including route, global, and QoS by @hogwartsdeveloper in #2073
• #2080 Add new FailureRatio and SamplingDuration V8 parameters to fine-tune Polly's circuit-breaker strategy via route-level and global QoS options by @RaynaldM in #2081
• #1658 Add global configuration for Headers Transformation by @marklonquist in #1659
• Use the appropriate class name as a type parameter to create a named logger through the factory in the ConfigurationMiddleware constructor by @harris2012 in

Note truncated.

Upgrade to .NET 9 with supported TFMs (net8.0;net9.0)

Upgrade to .NET 9 with supported TFMs (net8.0;net9.0)

🔥 Hot fixing issue #2246 (version 23.4.3) a.k.a. v23.4.2 patch 📦

Milestone: Nov-December'24
Hot fixed versions: 23.4.0 — 23.4.2
Read the Docs: Ocelot 23.4 with PDF

ℹ️ About

🔥 Hot fixed issue: #2246
❤️ A sincere and heartfelt "Thank You" to Donny Tian, @donnytian for reporting the bug.

⚠️ Warning

1. Consider this patch as the last one supporting .NET 6 and 7 frameworks. For more details, refer to the previous version notes.
2. No further patches for this minor version are expected. The next major release will be .NET 9, version 24.0.

❗ Breaking Changes

Upgrading from 23.4.0-23.4.2 to 23.4.3 introduces no breaking changes. However, some internal interfaces have been updated, which should not introduce IBC for 99.99% of projects. For further information, refer to the source code.

What's Changed

• #2246 Review Core cache and redesign Regex caching by @raman-m in #2251
• Release 23.4.3 | Hot fixing #2246 | November'24 release | +semver: patch by @raman-m in #2252

Full Changelog: 23.4.2...23.4.3

📦 End of .NET 6, 7 Support (version 23.4.2)

Milestone: Nov-December'24
Hot fixed version: 23.4.1
Read the Docs: Ocelot 23.4 with PDF

This is the last patched version for .NET 6 and 7 frameworks. The upcoming major release, version 24.0, will target .NET 9 alongside the LTS .NET 8. Projects targeting .NET 6 or 7 should update to this version while considering an upgrade to .NET 8 or 9 in the future.

ℹ️ About

• All package versions have been updated to latest versions targeting the net6.0 and net7.0 frameworks, along with the LTS net8.0.
• Dependabot alerts concerning reported vulnerabilities related to IdentityServer4 have not yet been addressed; these will be resolved in the next major release (refer to Warnings further information).

❗ Warning

1. Releasing a patched 23.4.* is possible.
2. In the next major version, the Ocelot team will remove references to the IdentityServer4 package from testing projects due to its "Public Archive" status; the version, 4.1.2, was released on July 7, 2021.
3. The main Ocelot package is not integrated with IdentityServer4, allowing Ocelot users to utilize any authentication provider, as Ocelot's Authentication feature is provider-agnostic.
4. Our plans to utilize the ASP.NET Core Identity framework in testing projects due to industry standards, instead the IdentityServer4 library.
5. Following the release of .NET 9, the team will begin the deprecation of the Ocelot extension-packages: Ocelot.Cache.CacheManager, Ocelot.Tracing.Butterfly, and Ocelot.Tracing.OpenTracing.

What's Changed

• Review Dependabot alerts for net6.0 and net7.0 target frameworks and bump all packages by @raman-m in #2220
• Release 23.4.2 | End of .NET 6, 7 Support | November'24 release | +semver: patch by @raman-m in #2221

Full Changelog: 23.4.1...23.4.2

📦 Routing patch (version 23.4.1) for v23.4.0

Milestone: Nov-December'24
Read the Docs: Ocelot 23.4 with PDF
Hot fixed version: 23.4.0

❤️ A heartfelt "Thank You" to Guillaume Gnaegi (@ggnaegi)
🔥 Hot fixed issues: #2165, #2209, #2212

What's Changed

• #2165 Global configuration SecurityOptions by @Fabman08 in #2170
• #2209 Placeholders matching must work if RouteIsCaseSensitive = false by @ggnaegi in #2210
• File-scoped namespaces everywhere by @raman-m in #2211
• #2212 Incorrect calculation of placeholders, only the last placeholder should be allowed to match several segments by @ggnaegi in #2213
• Release 23.4.1 | Routing patch | November'24 release | +semver: patch by @raman-m in #2215

Full Changelog: 23.4.0...23.4.1

🔀 Routing Update (version 23.4) a.k.a. the McDonald's release

Milestone: Nov-December'24 👈
Codenamed: McDonald's
Read the Docs: Ocelot 23.4 with PDF

ℹ️ About

This minor release significantly upgrades the Routing feature by supporting embedded placeholders within path segments (between slashes). Additionally, the team has focused on enhancing the performance of Regex objects.

🆕 What's new?

• Routing: Introducing the new "Embedded Placeholders" feature by @ggnaegi.
  As of November 2024, Ocelot was unable to process multiple placeholders embedded between two forward slashes. It was also challenging to differentiate the placeholder from other elements within the slashes. For example, /{url}-2/ for /y-2/ would yield {url} = y-2. We are excited to introduce an enhanced method for evaluating placeholders that allows for the resolution of placeholders within complex URLs.
  For additional information, refer to PR #2200.

🆙 What's updated?

Features: Routing, Core, Rate Limiting, Middleware Injection

• Routing: The new feature is "Embedded Placeholders" by @ggnaegi.
• Core: All Regex logic has been refactored by @EngRajabi.
  The Ocelot Core now boasts improved performance of Regex objects, striving to adhere to the Best Practices for Regular Expressions in .NET. It is estimated that each request could save from 1 to over 10 microseconds in processing time (though no benchmarks have been developed to measure this).
• Rate Limiting: The persistent issue with Rate Limiting headers has been resolved by @jlukawska.
  The problem was the absence of unofficial X-Rate-Limit-* headers (found in the RateLimitingHeaders class) in the RateLimitingMiddleware's response. For more details, see PR #1307.
  Note that these unofficial headers have not yet been documented, so they may be subject to change since Ocelot's RateLimiting headers do not align with industry standards.
• Middleware Injection: The OcelotPipelineConfiguration.ClaimsToHeadersMiddleware property has been introduced by @kesskalli.
  This new property enables the overriding of the ClaimsToHeadersMiddleware. For additional information, refer to PR #1403.

Documentation for v23.4.0

• Routing: Introducing a new section on Embedded Placeholders
• Middleware Injection: Documentation now includes the ClaimsToHeadersMiddleware feature

Honoring 🏅 aka Top Contributors 👏

1^st 🥇 goes to Mohsen Rajabi for delivering 1 feature in 12 files changed
2^nd 🥈 goes to Jolanta Łukawska for delivering 1 feature in 8 files changed
3^rd 🥉 goes to Karim Esskalli for delivering 1 feature in 6 files changed

Starring ⭐ aka Release Influencers

⭐ Mohsen Rajabi, @EngRajabi
⭐ Jolanta Łukawska, @jlukawska
⭐ Raman Maksimchuk, @raman-m
⭐ Karim Esskalli, @kesskalli
⭐ Guillaume Gnaegi, @ggnaegi

Features in Release 23.4

Logbook

• _{41fc9bd by Raman Maksimchuk on Monday, November 18 at 23:40 →}
  Release 23.4 | Routing Update | MGGA release | +semver: minor (#2206)
• _{27d3df2 by Guillaume Gnaegi on Sunday, November 17 at 15:24 →}
  #2199 Adding support of placeholder matching between slashes👍 (#2200)
• _{d76fc95 by Mohsen Rajabi on Saturday, November 16 at 21:39 →}
  Best practices for regular expressions versus Regex performance review (#1348)
• _{da9d6fa by jlukawska on Saturday, November 9 at 18:09 →}
  #1305 Populate RateLimiting headers in the original HttpContext response accessed via IHttpContextAccessor (#1307)
• _{d310508 by kesskalli on Tuesday, November 5 at 19:09 →}
  Override the ClaimsToHeadersMiddleware by the OcelotPipelineConfiguration settings (#1403)

What's Changed

• Override the ClaimsToHeadersMiddleware by the OcelotPipelineConfiguration settings by @kesskalli in #1403
• #1305 Populate RateLimiting headers in the original HttpContext response accessed via IHttpContextAccessor by @jlukawska in #1307
• Best practices for regular expressions versus Regex performance review by @EngRajabi in #1348
• #2199 Adding support of placeholder matching between slashes👍 by @ggnaegi in #2200
• Release 23.4 | Routing Update | MGGA release | +semver: minor by @raman-m in #2206

New Contributors

• @kesskalli made their first contribution in #1403

Full Changelog: 23.3.6...23.4.0

d2a79ac

This commit was created on GitHub.com and signed with GitHub’s verified signature .

GPG key ID: B5690EEEBB952194

Verified Learn about vigilant mode .

February 2024 (version 23.2 ) a.k.a. the Lunar Eclipse release

Milestone: February'24 👈 Codenamed: Lunar Eclipse Read the Docs: Ocelot 23.2 with PDF

What's new?

• Configuration : A brand new Merging files to memory feature by @ebjornset as a part of the Merging Configuration Files one. The AddOcelot method merges the ocelot.*.json files into a single ocelot.json file as the primary configuration file, which is written back to disk and then added to the IConfigurationBuilder for the well-known IConfiguration . You can now call another AddOcelot method that adds the merged JSON directly from memory to the IConfigurationBuilder , using AddJsonStream instead. See more details in Configuration Overview of Dependency Injection .

• Service Fabric : Published old undocumented " Placeholders in Service Name " feature of Service Fabric service discovery provider . This feature by @FelixBoers is available starting from version 13.0.0 .

• Quality of Service : A brand new Polly v8 pipelines Extensibility feature by @RaynaldM

Focus On

Updates of the features : Configuration, Dependency Injection and QoS

• Configuration : New Merging files to memory feature by @ebjornset

• Dependency Injection : Added new overloaded AddOcelot methods by @ebjornset

• Quality of Service : Support of new Polly v8 syntax and new Extensibility feature by @RaynaldM Ocelot extra packages

• Ocelot.Provider.Polly : Support of new Polly v8 syntax. Polly 8.0+ versions introduced the concept of resilience pipelines . All AddPolly extensions have been automatically migrated from v7 to v8 . Please note that older v7 extensions are marked with the [Obsolete] attribute and renamed using the V7 suffix. And the old v7 implementation has been moved to the v7 namespace . See more details in Polly v7 vs v8 section of Quality of Service chapter. Stabilization aka bug fixing

• 683 by PR 1927 New rules have been added to Ocelot's configuration validation logic to find duplicate placeholders in path templates. See more in the FileConfigurationFluentValidator class. Thanks to @AlyHKafoury !

• 1518 hotfix by PR 1986 Using the default IServiceCollection DI extensions to register Ocelot services resulted in the ServiceCollection provider being forced to be created by calling BuildServiceProvider() . This resulted in problems with dependency injection libraries, or worse, causing the Ocelot app to crash! See more in the ServiceCollectionExtensions class. Thanks to @ArwynFr !

• See all bugs of the February'24 milestone