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

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

Breaking changes

This release contains a number of API breaking changes that aim to make YARP easier and more consistent to use.

• Core types are renamed to better indicate their responsibilities
  • ClusterConfig => ClusterModel
  • Cluster => ClusterConfig
  • ClusterInfo => ClusterState
  • RouteConfig => RouteModel
  • ProxyRoute => RouteConfig
  • RouteInfo => RouteState
  • DestinationConfig => DestinationModel
  • Destination => DestinationConfig
  • DestinationInfo => DestinationState
• Cluster sub option types are also renamed
  • HealthCheckOptions => HealthCheckConfig
  • ActiveHealthCheckOptions => ActiveHealthCheckConfig
  • PassiveHealthCheckOptions => PassiveHealthCheckConfig
  • ProxyHttpClientOptions => ProxyHttpClientConfig
  • WebProxyOptions => WebProxyConfig
  • RequestProxyOptions => ForwarderRequestConfig
  • SessionAffinityOptions => SessionAffinityConfig
• Client certificate configuration is removed from HttpClientConfig #994
  • Added configure client certificate sample Details
• QueryParameterTransform can set an empty value "" to a parameter. #978
• RequestHeaderEncoding is set as a string in configuration #995
• Session affinity API changed
  • Renamed ISessionAffinityProvider => ISessionAffinityPolicy
  • Renamed AffinitizeRequest => AffinitizeResponse
  • Renamed SessionAffinityConfig.Mode => SessionAffinityConfig.Provider
  • Renamed AffinityFailurePolicies => FailurePolicies
  • New mandatory setting SessionAffinityConfig.AffinityKeyName are used by both of cookie and custom header affinity provider to set the cookie name or the custom header name respectively
  • New strongly-typed section SessionAffinityCookieConfig is added to configure the cookie affinity provider
  • SessionAffinityConfig.Settings collection is removed
• Projects structure is refactored by flattening hierarchy and regrouping files, changing several namespaces #1035
• Renamed IHttpProxy => IHttpForwarder. In this context, "Forwarder" term is now used instead of "Proxy", thus in all related type the "Proxy" in the name are replaced with "Forwarder" (e.g. IProxyHttpClientFactory => IForwarderHttpClientFactory, IProxyErrorFeature => IForwarderErrorFeature, AddHttpProxy => AddHttpForwarder)
• Changed the return type of IHttpForwarder.SendAsync it now returns ValueTask<ForwarderError>
• Renamed load balancing policy LoadBalancingPolicies.First => LoadBalancingPolicies.FirstAlphabetical
• Renamed IActiveHealthCheckMonitor.InitialDestinationsProbed => InitialProbeCompleted
• X-Forwarded-* and Forwarded header transforms changed. Details
  • New transform actions supported: Set, Remove, Off
  • Prefix config setting renamed to HeaderPrefix
  • Separate action configuration for each of X-Forwarded-* headers. Example:

  {
      "X-Forwarded": "Set",
      "For": "Remove",
      "Proto": "Append",
      "Prefix": "Off",
      "HeaderPrefix": "X-Forwarded-"
  }
  

  • Default action for X-Forwarded-* and Forwarded transforms is Set
• RequestHeader, ResponseHeader, and ResponseTrailer transforms no longer use "Set": "" (empty) to remove a header. See the new *Remove transforms below.

Other major changes and features

• Cluster's available destination list is now updated by IClusterDestinationsUpdater service based on destinations health status. Two update policies HealthyAndUnknown and HealthyOrPanic are added which can be configure on a cluster like this:

"cluster1": {
  "AvailableDestinationsPolicy": "HealthyOrPanic",
  "HealthCheck": {
    "Passive": {
      "Enabled": "true"
    }
    //...
}

• New transforms added: RequestHeaderRemove, ResponseHeaderRemove, ResponseTrailerRemove. Details
• Connection specific headers are removed from request and responses #1008, #1050
• User-Agent is for active health check requests #1013
• README.md added for the samples folder
• Documentation for proxying gRPC traffic is added