dotnet/yarp: a reverse proxy toolkit you configure in C# instead of in a config file

The problem YARP solves: proxy behaviour that has to change while the process is running

Most reverse proxies are configured by editing a file and reloading. That works until the routing table is derived from something the proxy cannot see, such as a service registry, a tenant database, or a per-customer feature flag. At that point the config file becomes a generated artifact, and the team ends up writing a sidecar that renders templates and signals the proxy to reload. YARP takes the position that the routing table belongs in the application process.

The README describes the origin directly: internal teams at Microsoft were each building a reverse proxy for their own service or asking for APIs to build one, so the work was consolidated into a common solution. The stated differentiator is customizability, with configuration managed programmatically from the user's own backend configuration management system rather than only from files. YARP is not a product you run; it is a library and project template you compose into an ASP.NET application, so the proxy inherits the host's dependency injection, logging and middleware pipeline.

How YARP works: ASP.NET middleware, a route table, and a forwarding pipeline

YARP is built on ASP.NET and .NET infrastructure. A YARP application is an ASP.NET app with proxy middleware inserted into the request pipeline. Requests arrive, the middleware matches them against a route table, selects a cluster, and forwards the request to a destination inside that cluster. The response comes back through the same pipeline, which is where transforms apply.

The configuration model has two halves. Routes describe how incoming requests are matched, and clusters describe the set of destinations a matched request can be sent to. That split is what makes runtime reconfiguration practical: a service discovery integration only needs to rewrite clusters, leaving route matching untouched. The README notes that YARP supports configuration files but expects many users to manage configuration programmatically through a configuration API, which is the in-process path.

Customization points are spread across the pipeline rather than concentrated in one plugin interface. The samples directory shows the range: ReverseProxy.ConfigFilter.Sample, ReverseProxy.Transforms.Sample, ReverseProxy.Auth.Sample, ReverseProxy.Code.Sample, ReverseProxy.Direct.Sample, ReverseProxy.HttpSysDelegation.Sample, ReverseProxy.LetsEncrypt.Sample and ReverseProxy.Metrics.Sample. Each one is a different extension seam. If you want to know whether YARP can express your routing rule, that directory is a better answer than the README.

Installing YARP and proxying your first backend

YARP ships as NuGet packages, and the README points to the Getting Started documentation on Microsoft Learn and to preview builds on the releases page. The README does not inline a package install command, so the first step is to follow the Getting Started doc rather than copy a command from here.

Building YARP from source is a separate exercise, and this part the README does document. It says `build.cmd` on Windows or `build.sh` on Linux and macOS downloads the .NET SDK and builds the solution.

./build.sh

For local development the README describes a two-step setup: run the restore script to fetch the SDK into a `.dotnet` directory inside the repository, then dot-source the activate script to put that SDK on `PATH`.

./restore.sh
. ./activate.sh

The README is explicit that the leading `. ` is required in PowerShell (`. .\activate.ps1`) and that CMD has no supported activate script, so on CMD you must add the in-repo `.dotnet` directory to `PATH` yourself and confirm `where dotnet` points inside the repository. To undo the change, run the `deactivate` function. Testing is a separate switch: the README gives `build.cmd/sh -test` to build and run all tests, and for a single test it gives `dotnet build /t:Test /p:XunitMethodName={FullyQualifiedNamespace}.{ClassName}.{MethodName}`.

What you should see after the restore and activate steps is that `dotnet` resolves to the copy inside the repository rather than a machine-wide install, which is what makes the build reproducible across the team. The repository also ships a `startvs.cmd` script for launching Visual Studio against that same local SDK. For the application-level configuration model, the README defers entirely to the Getting Started docs, and the samples directory is the place to look for a working host: samples/BasicYarpSample, samples/ReverseProxy.Config.Sample and samples/ReverseProxy.Code.Sample cover the config file and programmatic paths respectively.

Where YARP is the wrong tool

The README is candid that YARP is a toolkit, not a finished proxy. That has consequences. There is no standalone binary to download and configure; adopting YARP means owning an ASP.NET application, its deployment, its upgrade cadence and its capacity planning. A team that wants a proxy an operator can tune without a .NET build pipeline is not the audience.

Customizability cuts the other way too. Features that nginx ships as directives, such as caching behaviour or a particular load-balancing policy, may exist in YARP as an extension point rather than a built-in. The samples directory is evidence of this: authentication, transforms, metrics and Let's Encrypt each get their own sample, which suggests each is a thing you assemble rather than a thing you switch on. Budget engineering time accordingly.

Release cadence is the other constraint to check. The most recent release listed is v2.3.0 from 2025-02-27, following v2.2.0 in September 2024 and a v2.2.0 preview in May 2024. The repository itself was last pushed on 2026-09-21 and is not archived, but the release history is what determines which package version you can pin. The README points to docs/roadmap.md for the support policy, which is where the supported .NET versions are defined rather than in the README.

YARP versus nginx: in-process code against a declarative config file

The comparison people search for is YARP against nginx, and the difference is not performance, it is where the routing decision lives. nginx reads a configuration file and applies it; changing behaviour means editing that file and reloading. YARP builds the route table inside the application, so a change can come from any code path the application can reach, including a database query or a service registry watch.

That makes YARP a better fit when routing is a function of application state. It makes nginx a better fit when routing is a function of deployment topology that changes rarely and is managed by people who do not work in the application's language. There is a middle ground: run nginx at the edge for TLS termination and static routing, and use YARP inside the application for the dynamic layer. Nothing in the README forbids that arrangement, and the samples include a KubernetesIngress.Sample and a StaticSite sample, which suggests the project expects to sit in a larger topology rather than replace every hop.

Maintenance, packaging and the MIT licence

YARP is licensed under MIT, and the repository carries LICENSE.txt along with THIRD-PARTY-NOTICES.TXT. MIT is permissive: you can use the library in a closed product, and the practical obligation is preserving the copyright and licence notice. That is a summary of the licence identifier, not legal advice; read LICENSE.txt and the third-party notices before shipping, particularly because a proxy aggregates dependencies.

The upgrade cost is the cost of an ASP.NET dependency. YARP targets .NET, the repository carries a TFMs.props file and a global.json pinning an SDK, and the README directs readers to docs/roadmap.md for the support policy. In practice that means a YARP upgrade is coupled to a .NET version decision, not an isolated package bump. The README also documents a daily build channel in docs/DailyBuilds.md for people who want to track unreleased changes, which is useful for testing a fix but not a version to pin in production.

Security reports go to the Microsoft Security Response Center at [email protected] rather than to public issues, and the README states you should receive a response within 24 hours. If your organisation routes vulnerability reports through its own process, that address is the one to record.

Editorial conclusion

Adopt YARP if your routing, auth or backend discovery logic already lives in C# and you need to change it without a restart; the samples directory and the Getting Started doc are the fastest way to judge that. Do not adopt it if you want a standalone proxy binary with a config file you can hand to an ops team that does not read .NET, or if you need a feature the toolkit does not ship and you are not prepared to write it. Before committing, verify that the v2.3.0 packages restore on your target framework, and check the support policy in docs/roadmap.md to confirm your .NET version is still in scope.

Frequently asked questions

Official sources

1. dotnet/yarp on GitHub
2. License: MIT
3. Project website
4. README
5. Releases