Ocelot v25.0

Welcome to the Ocelot 25.0 documentation!

It is recommended to read all Release Notes if you have deployed the Ocelot app in a production environment and are planning to upgrade to major, minor or patched versions.

Release Notes

Release Tag: 25.0.0

Release Codename: .NET 10

Release Date: July 29, 2026

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 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 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 QoSOptions 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 Quality of Service 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 Websockets documentation 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 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 chapter, especially the “Extend 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, the development team uncovered an undocumented feature in the Ocelot.Multiplexer namespace and decided to publish this pilot feature in the “Aggregate Manually?” documentation. The feature is based on the IResponseAggregator interface. The Ocelot team will test it further in upcoming releases, develop best practices, create a sample app, and inform the community. For this reason 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 (K8s) 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 (K8s) : 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:

  • 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 Included

• 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 (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.

  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.

Contributing

Pull requests, issues, and commentary are welcome at the Ocelot GitHub repository. For ideas and questions, please post them in the Ocelot Discussions space.

Our Development Process is a part of successful Release Process. If you are a new contributor, it is crucial to read Development Process attentively to grasp our methods for efficient and swift feature delivery. We, as a team, advocate adhering to Best Practices throughout the development phase.

We extend our best wishes for your successful contributions to the Ocelot product!