This release supports .NET 8.0 and newer. See Getting Started.
Note that while this version also includes targets for .NET 6 and .NET 7, those runtimes are no longer supported.

The Yarp.ReverseProxy packages are available on NuGet.org.

Breaking changes

• More errors triggered by the client disconnecting are now logged under a Debug severity (#2765 by @MihaZupan).
  • ForwarderError.ResponseBodyCanceled and UpgradeResponseCanceled are no longer logged with a Warning severity.
  • This is a continuation of a change we've made in 2.2 where we've done the same with RequestCanceled, RequestBodyCanceled, and UpgradeRequestCanceled.
• Replacing the HttpRequestMessage.Content property in a request transform will throw an exception (#2722 by @MihaZupan).
  • While setting the property may have appeared to work during limited testing, it could lead to various issues as YARP internally relies on the property remaining unchanged. See the pull request for more context on this change.
• We now always enforce the HttpVersionPolicy during HTTP version negotiation (#2729 by @MihaZupan).
  • It was previously possible for YARP to initiate HTTP/1.1 connections for WebSocket and SPDY requests even if the specified HttpVersionPolicy disallowed it. This was breaking scenarios such as outgoing HTTP/2 WebSockets without TLS.
  • If the policy disallows the use of outbound HTTP/1.1, SPDY requests will not be proxied and will instead return a RequestCreation error.
  • This does not affect the default YARP configuration, which is Version=2.0, Policy=RequestVersionOrLower.

Major changes

• YARP has always logically been a part of .NET and we have now moved the repository from the microsoft to the dotnet organization.
  • The license has been updated to the .NET foundation, but remains MIT as before (#2738 by @adityamandaleeka).
  • As part of the repository move, we have moved the documentation to learn.microsoft.com.
• We've created a JSON schema for YARP configuration! Editing now comes with validation and autocompletions (#2758 by @MihaZupan).
  • The change is automatic when referencing the 2.3.0 version of the YARP package and editing the ReverseProxy section in appsettings.json.
    
    
  • If you encounter any issues with the schema, please let us know by opening an issue.
  • False positives can be safely ignored until we're able to update the schema. Runtime interpretation of the configuration remains unchanged and is unaffected by schema validation.
  • You can manually reference the latest version of the schema without changing the package by pointing Visual Studio at https://raw.githubusercontent.com/dotnet/yarp/refs/heads/main/src/ReverseProxy/ConfigurationSchema.json.
    
• We've started shipping a minimal YARP container image at mcr.microsoft.com (#2710 by @benjaminpetit).
  • More functionality will be added to the image over time.

Other changes

• We've added optional parameters to AddForwarded and AddXForwarded request transforms that allow you to opt-out of removing the other variant of the header (#2728 by @rkargMsft).

  ctx.AddForwarded(removeAllXForwardedHeaders: false);
  ctx.AddXForwarded(removeForwardedHeader: false);

• Improved HttpSysDelegator logging and retry logic (#2671 by @NGloreous).
• YARP can now be published with NativeAOT when targetting .NET 8.0 again (#2759 by @MihaZupan).
• We've added a workaround for an error in .NET builds from the Ubuntu package feed (#2673 by @MihaZupan).
  • See dotnet/aspnetcore#59166 for more information.

New Contributors

• @xtqqczze made their first contribution in #2748

For a full list of changes see here.

This release supports .NET 6.0 and .NET 8.0. See Getting Started.

The Yarp.ReverseProxy packages are available on NuGet.org.

Breaking changes

• There are no breaking changes between YARP 2.2.0-preview.1 and 2.2.0.
• See 2.2.0-preview.1 release notes for the list of breaking changes between YARP 2.1 and 2.2.

Other changes

• The Forwarded transform now prefers the IPv4 form for dual-mode sockets (#2509 by @rkargMsft).
  • E.g. 127.0.0.1 is used instead of ::ffff:127.0.0.1.
  • A similar change was already made for X-Forwarded-For in 2.2.0-preview.1 (#2400).
• Added a missing WebSocketCloseReason.ActivityTimeout enum value (#2571 by @MihaZupan).
• Added a TlsFrameHelper.ParsingStatus API (#2587 by @wfurt).
  • This information can be used to distinguish between Invalid and Incomplete frames.
• Removed one async state machine allocation when forwarding a request (#2586 by @MihaZupan).
• Several documentation improvements.

New Contributors

• @rkargMsft made their first contribution in #2509
• @nigma143 made their first contribution in #2535
• @mroberts91 made their first contribution in #2530
• @t0mll made their first contribution in #2547
• @fnuttens made their first contribution in #2558

For a full list of changes see here.

This release supports .NET 6.0 and .NET 8.0. See Getting Started.

The Yarp.ReverseProxy packages are available on NuGet.org.

Breaking changes

• HeaderMatchMode.NotExists now also matches headers with an empty value (#2412 by @qianyuansun).
  • This makes NotExists exactly the opposite of Exists. Previously, empty values would not match either mode.
• Errors triggered by the client disconnecting are now logged under a Debug severity (#2503 by @MihaZupan).
  • ForwarderError.RequestCanceled, RequestBodyCanceled, and UpgradeRequestCanceled are now logged under a new ILogger event with a Debug severity. Other errors continue to be logged under the existing event with a Warning severity.
  • How errors are mapped to different ForwarderErrors remains the same.

Other changes

• Added support for Kestrel Start/Stop events on IKestrelTelemetryConsumer (#2360 by @ajay-sainy).
• Added support for controlling OutputCachePolicy in the route configuration (#2328 by @witskeeper).
  • See the Output Caching documentation for more details.
• X-Forwarded-For now prefers the IPv4 form for dual-mode sockets (#2400 by @hacst).
  • E.g. 127.0.0.1 is used instead of ::ffff:127.0.0.1.
• Fixed a bug where active health checks would consider new destinations as Healthy instead of Unknown (#2415 by @robbieknuth).
  • Destinations now remain as Unknown until enough health probes have been sent.
• Added a new Query property to active health check configuration (#2421 by @robbieknuth).
  • Previously, only Path could have been specified, and ? would be escaped to %3F.
• Added support to HttpSysDelegator for detaching from and re-initializing queues (#2426 by @NGloreous).
• Fixed a race condition reliability bug in HttpSysDelegator (#2487 by @NGloreous).
• OperationCanceledExceptions thrown by response transforms as part of error handling are now ignored (#2452 by @MihaZupan).
• Fixed a bug where YARP validation of UseRequestTimeouts was too strict (#2501 by @MihaZupan).
• Reduced the performance overhead of updating the activity timeout timer (#2475 by @MihaZupan).
• Many documentation improvements.

New Contributors

• @larsbj1988 made their first contribution in #2293
• @Bambi-pa-hal-is made their first contribution in #2350
• @ajay-sainy made their first contribution in #2360
• @joegoldman2 made their first contribution in #2381
• @hacst made their first contribution in #2400
• @allantargino made their first contribution in #2411
• @robbieknuth made their first contribution in #2415
• @qianyuansun made their first contribution in #2412
• @jsedlak-microsoft made their first contribution in #2436
• @jamesmontemagno made their first contribution in #2433
• @eltociear made their first contribution in #2456

For a full list of changes see here.

This release supports .NET 6.0, 7.0, and 8.0. See Getting Started.

The Yarp.ReverseProxy packages are available on NuGet.org.

Breaking changes

• There are no breaking changes between YARP 2.1.0-preview.1 and 2.1.0.
• See 2.1.0-preview.1 release notes for the list of breaking changes between YARP 2.0 and 2.1.

Other changes

• Set IsPackable to true for the k8s project on non rtw builds by @benjaminpetit in #2286
• Conditionally copy Strict-Transport-Security by @Tratcher in #2306
• fix: typo in prometheus sample metrics by @asafdl in #2309
• Add NuGet feed to get daily builds of Yarp.Kubernetes.Controller package. by @benjaminpetit in #2312
• [main] Update dependencies from dotnet/arcade by @dotnet-maestro in #2318
• Update config-files.md by @YehudaKremer in #2319
• Make RequestTransformContext.DestinationPrefix read-write by @benjaminpetit in #2311
• failing tests for rate limiter policy validation when 'default' or 'disable' used by @jakebanks in #2283
• Update dependencies to rtw by @benjaminpetit in #2326
• chore: fix prometheus sample metric typos in description by @asafdl in #2308
• Timeout integration by @Tratcher in #2307
• Clarify websocket activity failure by @Tratcher in #2325
• Minimal APIs for docs and samples by @Tratcher in #2327

New Contributors

• @asafdl made their first contribution in #2309
• @YehudaKremer made their first contribution in #2319
• @jakebanks made their first contribution in #2283

Full Changelog: v2.1.0-preview.1...v2.1.0

This release supports .NET 6.0, 7.0, and 8.0. See Getting Started.

The Yarp.ReverseProxy packages are available on NuGet.org.

Breaking changes

• The default IAvailableDestinationsPolicy has been changed from HealthyAndUnknown to HealthyOrPanic by @Tratcher in #2171
  • This new default allows the proxy to serve at least some requests even if all destinations are unhealthy.
• We're now using the new TimeProvider type by @Tratcher in #2108
  • The old IClock interface was marked obsolete and is no longer used by YARP.

Other changes

• Update log level to warning for unsuccessful proxying by @kheardCB in #2044
• Fix an issue where destinations are compared against themselves by @felipeogarcia in #2065
• Workaround EventListener bug when consuming metrics by @MihaZupan in #2104
• Add .NET 8 TFM, clean up new warnings by @Tratcher in #2105
• Fix extended connect check condition by @benjaminpetit in #2119
• Adding distinct activity for distributed tracing to YARP by @samsp-msft in #2098
• Perf improvements by @MihaZupan in #2127
• Enable AOT Compatibility by @eerhardt in #2144
• Enable AOT compatibility for Yarp.Telemetry.Consumption by @eerhardt in #2146
• Added more direct routing APIs by @davidfowl in #2147
• Add [StringSyntax("Route")] to route patterns by @divyeshio in #2156
• Forwarder blame improvements by @Tratcher in #2167
• Add cluster destination address validation by @hahn-kev in #2184
• Overload constructors for ClusterState and DestinationState to enable unit testing by @antonybstack in #2198
• Changed streaming flag to empty string when logging no gRPC request by @marekott in #2200
• Add IDestinationResolver for resolving cluster destination addresses by @ReubenBond in #2210
• Request body exception status code granularity by @antonybstack in #2227
• Improve diagnostics for IDestinationResolver exceptions by @ReubenBond in #2241
• Improve route string syntax usage by @JamesNK in #2253
• 💡Feat: allow for simpler override of Response header encoding of Forwarded Requests by @ChintanRaval in #2254
• Update NotContains match mode for Header and QueryParameters to support missing/empty values by @evmurphy in #2258
• Add Request Header From Route by @daniel-steinmann in #2262
• Use SearchValues in RequestUtilities.EncodePath by @MihaZupan in #2267
• React to runtime EventSource changes by @MihaZupan in #2268
• Use frozen collections by @MihaZupan in #2272

New Contributors

• @kheardCB made their first contribution in #2044
• @obenarchid made their first contribution in #2053
• @catcherwong made their first contribution in #2043
• @felipeogarcia made their first contribution in #2065
• @jonathantower made their first contribution in #2112
• @kyler-swanson made their first contribution in #2114
• @kant2002 made their first contribution in #2122
• @eerhardt made their first contribution in #2144
• @foostackdev made their first contribution in #2152
• @antonybstack made their first contribution in #2157
• @divyeshio made their first contribution in #2156
• @MilenaHristova made their first contribution in #2189
• @hahn-kev made their first contribution in #2184
• @kzhen made their first contribution in #2180
• @marekott made their first contribution in #2200
• @ReubenBond made their first contribution in #2210
• @HappyCodeSloth made their first contribution in #2231
• @JamesNK made their first contribution in #2253
• @ChintanRaval made their first contribution in #2254
• @evmurphy made their first contribution in #2258
• @daniel-steinmann made their first contribution in #2262

Pull Requests: query
Full Changelog: v2.0.0...v2.1.0-preview.1

A security issue was identified in YARP 2.0.0. See Microsoft Security Advisory CVE-2023-33141.

The fix has been released and is available on NuGet.org.

A security issue was identified in YARP 1.1.1 and lower. See Microsoft Security Advisory CVE-2023-33141.

The fix has been released and is available on NuGet.org.

This release supports .NET 6.0 and .NET 7.0. See Getting Started.

The Yarp.ReverseProxy packages are available on NuGet.org.

Breaking changes

• Existing HttpTransformer overloads that don't accept a CancellationToken have been marked as obsolete (#2016).
  • If you have created a custom class that derives from HttpTransformer, you should update the implementation to override the overloads which accept the CancellationToken instead.
  • Existing implementations that only override the obsolete overloads will continue working for the time being, but these overloads may be removed in a future major release.
• See 2.0.0-RC.1 release notes for the rest of the breaking changes between YARP 1.1 and 2.0.

Other changes

• Added a new enum value ForwarderError.RequestCreation that is reported if a request transform throws an exception (#2016).
• Fixed a bug introduced in RC1 where custom response transform callbacks were not called on errors (when ProxyResponse is null) (#2016).
• Fixed a bug where a request cancellation triggered by the manual CancellationToken (parameter to IHttpForwarder.SendAsync) was reported as RequestTimedOut instead of RequestCanceled (#2016).

For a full list of changes see here.

This release supports .NET 6.0 and .NET 7.0. See Getting Started.

The Yarp.ReverseProxy packages are available on NuGet.org.

Breaking changes

• We dropped support for .NET Core 3.1 and .NET 5.0 as they are no longer supported.
  • YARP 2.0 targets .NET 6 and .NET 7.
• The default session affinity policy has been changed from Cookie to HashCookie (#1989).
  • This policy provides fewer security guarantees about the protection level of the key data - the destination ids. On the other hand, it allows for multiple YARP instances to share session affinity cookies without the need to configure ASP.NET Core Data Protection.
  • For more details, see the Session Affinity documentation.
• YARP now sets the SocketsHttpHandler.ConnectTimeout by default (#1991). You may observe different exceptions being reported by the proxy in failure scenarios when destination servers aren't responding. See #1678 for more context on this change.
• The name of the enum value TlsHandshakeType.KeyEpdate has been corrected to KeyUpdate (#1614).

Major changes

• Added support for WebSockets over HTTP/2 (#1978).
  • Protocol upgrades and downgrades are automatic. You can mix different protocol versions on both incoming and outgoing sides.
  • This feature is available on .NET 7.0 and newer only. To accept HTTP/2 WebSockets, you must use Kestrel.
  • See the YARP WebSockets documentation for more details.
• Request transforms can now short-circuit requests and avoid proxying (#1923).
  • If you set the status code on the response to something other than 200 OK, or if you start writing to the response body, forwarding will be skipped.
  • See the Request Transforms documentation for more details.

Other changes

• You can specify the RateLimiterPolicy on a route from the configuration (#1967). See the Rate Limiting documentation for more details.
• You can specify the MaxRequestBodySize on a route from the configuration (#1947).
• We exposed the InMemoryConfigProvider as a built-in API (#1732). You no longer have to copy the implementation from the samples :)
• Added an IConfigChangeListener interface you can implement to receive notifications when and if configuration has been applied (#1734).
• Added an IHttpForwarder.SendAsync overload that accepts a cancellation token (#1985).
• Added async APIs to ISessionAffinityPolicy (#1990).
• Added an overload of ReassignProxyRequest that also accepts a route (#1760).
• Added a HeaderMatchMode.NotExists mode to header routing (#1806).
• Added an AddMetricsConsumer helper method to make it easier to register a consumer with multiple IMetricsConsumers (#1899).
• We report a warning early if you define multiple routes with the same ID (#1831).
• We throw if you use a custom IForwarderHttpClientFactory and also call ConfigureHttpClient as the two are mutually exclusive (#1805).
• We no longer restore the Upgrade response header unless there is a matching entry in the Connection header (#1731).
• We remove the Content-Length: 0 header on responses that don't allow bodies (#1813).
• We no longer proxy the Strict-Transport-Security header (#1984).

For a full list of changes see here.

This release supports .NET Core 3.1, .NET 5.0, and .NET 6.0. See Getting Started.

The Yarp.ReverseProxy packages are available on NuGet.org.

Changes:

• A fix for issue #1770 which was causing WebSockets to close abortively rather than gracefully.