Welcome

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

In this major release, the Ocelot team focused on preparing the codebase and its ecosystem for .NET 10, while also extracting several integrated extension packages from the mono-repo into their own dedicated repositories to speed up delivery and reduce release coupling. This release also introduces a built-in Quality of Service (QoS) circuit breaker that works out of the box, without requiring the Polly library.

The updated documentation 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.

Additionally, this release brings a significant enhancement to the Kubernetes (K8s) PollKube provider from the Ocelot.Discovery.KubeClient package.

What’s New?

• Quality of Service: A “Built-in Circuit Breaker” 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 “Built-in QoS” documentation for full details, including the AddQualityOfService<THandler>() extensibility point for overriding server error codes.

• Websockets: Overridable WebSocket buffer size and custom middleware injection was 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 OcelotPipelineConfiguration, allowing a fully custom WebSocket middleware to be injected into the pipeline.

• Websockets: SecurityOptions support for the WebSocket pipeline was added 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.

• Configuration: “Merge custom JSON properties across multiple configuration files” 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. This also applies to the DynamicRoutes collection. See the updated Configuration documentation, the “Extend with Custom Properties” section and the Configuration Sample app for details.

• Aggregation: “Correct mapping of RouteKeysConfig arrays in aggregates” fix, contributed in pull request 2328.

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

What’s Updated?

• Package extraction 2334: The Ocelot team, led by @raman-m, continued extracting integrated extension packages out of the mono-repo into their own dedicated repositories, each with an independent release cycle:

  • Ocelot.Cache.CacheManager — pull request 2360

  • Ocelot.Tracing.Butterfly — pull request 2361

  • Ocelot.Tracing.OpenTracing — pull request 2362

  • Ocelot.Discovery.Eureka (renamed from Ocelot.Provider.Eureka, see issue 2371) — pull request 2372

  • Ocelot.QualityOfService.Polly (renamed from Ocelot.Provider.Polly, see issue 2378) — pull request 2380

  • Ocelot.Discovery.Consul (renamed from Ocelot.Provider.Consul, see issue 2378) — pull request 2388

  • Ocelot.Discovery.KubeClient (renamed from Ocelot.Provider.Kubernetes, see issue 2378) — pull request 2404

  This keeps the Ocelot core repo lean, avoids delays caused by 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.

• Error Handling: Non-ASCII header exceptions mapped to 400 Bad Request per RFC 7230, in pull request 2379.

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

• Administration: “Hide Administration controllers from Swagger and OpenAPI” fix, contributed 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.

• DevOps: Extensive testing and tooling modernization was carried out by @raman-m and contributors ahead of .NET 10:

  • Solutions upgraded to the Visual Studio 2026 format.

  • Testing projects migrated from xUnit v2 to xUnit v3, and acceptance tests migrated to the Microsoft.Testing.Platform framework.

  • Ocelot.Testing was re-embedded into the mono-repo and later excluded from Cobertura coverage via coverlet.runsettings.

  • Codecov coverage reporting was installed for the repository.

  • All NuGet packages were bumped to their latest versions to support .NET SDK 10.0.302 (.NET Runtime 10.0.10).

Patches Included

• Routing: Issue 2346 patch, contributed 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.

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!