If you’re building microservices with .NET, you’ll eventually need a reliable API Gateway to route traffic, apply security, and centralize cross‑cutting concerns.
Microsoft’s YARP (Yet Another Reverse Proxy) is a powerful, production‑ready reverse proxy built specifically for ASP.NET Core.
In this article, we’ll walk through a complete working sample of a YARP API Gateway using .NET 10, including:
- Solution architecture
- Creating downstream services
- Configuring YARP routing & load balancing
- Adding transforms and health checks
- Running the full system locally
1. Architecture Overview
Our sample contains three projects:
- Gateway → YARP reverse proxy
- Orders API → downstream microservice
- Products API → downstream microservice
Client → YARP Gateway → MicroservicesThe gateway will:
- Route
/orders/*→ Orders API - Route
/products/*→ Products API - Provide centralized entry point for future auth, caching, logging, etc.
2. Create the Solution
Open terminal and run:
dotnet new sln -n YarpSample# Create gatewaydotnet new web -n gatewaycd gatewaydotnet add package Yarp.ReverseProxycd ..# Create microservicesdotnet new webapi -n orders-api --no-httpsdotnet new webapi -n products-api --no-https# Add to solutiondotnet sln add gateway orders-api products-api3. Build Downstream Services
Orders API
orders-api/Program.cs
var builder = WebApplication.CreateBuilder(args);builder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen();var app = builder.Build();app.UseSwagger();app.UseSwaggerUI();app.MapGet("/orders", () => new[]{ new { Id = 1, Item = "Laptop", Price = 1200 }, new { Id = 2, Item = "Mouse", Price = 25 }});app.Run("http://localhost:5001");Products API
products-api/Program.cs
var builder = WebApplication.CreateBuilder(args);builder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen();var app = builder.Build();app.UseSwagger();app.UseSwaggerUI();app.MapGet("/products", () => new[]{ new { Id = 1, Name = "Keyboard" }, new { Id = 2, Name = "Monitor" }});app.Run("http://localhost:5002");Run both services:
dotnet run --project orders-apidotnet run --project products-api4. Configure the YARP Gateway
Install package
cd gatewaydotnet add package Yarp.ReverseProxyappsettings.json
{ "ReverseProxy": { "Routes": { "orders-route": { "ClusterId": "orders-cluster", "Match": { "Path": "/orders/{**catch-all}" } }, "products-route": { "ClusterId": "products-cluster", "Match": { "Path": "/products/{**catch-all}" } } }, "Clusters": { "orders-cluster": { "LoadBalancingPolicy": "RoundRobin", "Destinations": { "orders-api": { "Address": "http://localhost:5001/" } } }, "products-cluster": { "LoadBalancingPolicy": "RoundRobin", "Destinations": { "products-api": { "Address": "http://localhost:5002/" } } } } }}Program.cs
using Yarp.ReverseProxy;var builder = WebApplication.CreateBuilder(args);builder.Services .AddReverseProxy() .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));var app = builder.Build();app.MapReverseProxy();app.Run("http://localhost:5000");5. Test the Gateway
Start the gateway:
dotnet run --project gatewayNow test endpoints:
- Orders → http://localhost:5000/orders
- Products → http://localhost:5000/products
Requests flow through YARP → downstream service → response to client.
6. Adding Transforms (Optional)
Example: add header before forwarding.
"Transforms": [ { "RequestHeader": "X-Gateway", "Set": "YARP" }]This enables:
- tracing
- auditing
- gateway identification
7. Health Checks & Resilience
YARP supports active and passive health checks.
Example cluster config:
"HealthCheck": { "Active": { "Enabled": true, "Interval": "00:00:10", "Timeout": "00:00:05", "Policy": "ConsecutiveFailures", "Path": "/health" }}This ensures traffic only routes to healthy services.
8. Why Use YARP Instead of Ocelot or Nginx?
Advantages of YARP:
- Built by Microsoft for ASP.NET Core
- Fully programmable in C#
- High performance & production ready
- Native integration with .NET middleware
Perfect for cloud‑native microservices.
9. Next Steps for Production
Consider adding:
- JWT authentication at gateway
- Rate limiting
- Distributed tracing (OpenTelemetry)
- Service discovery (Consul, Kubernetes)
- Caching layer
Conclusion
You now have a fully working YARP API Gateway on .NET 10 with:
- Multiple microservices
- Routing & load balancing
- Transforms and health checks
This setup is a strong foundation for scalable .NET microservices architecture.