Skip to content

Commit 979bc9d

Browse files
github-actions[bot]Copilotdavidfowl
authored
[release/9.4] Update YARP README to reflect current implementation and API patterns (#10709)
* Initial plan * Update YARP README with comprehensive documentation and examples Co-authored-by: davidfowl <[email protected]> * Final touches: add using directive and complete YARP README update Co-authored-by: davidfowl <[email protected]> * Remove file-based configuration API references from YARP README Co-authored-by: davidfowl <[email protected]> * Apply suggestions from code review * Update src/Aspire.Hosting.Yarp/README.md * Update src/Aspire.Hosting.Yarp/README.md * Add YARP integration documentation link Co-authored-by: davidfowl <[email protected]> * Update src/Aspire.Hosting.Yarp/README.md * Apply suggestions from code review --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: davidfowl <[email protected]> Co-authored-by: David Fowler <[email protected]>
1 parent 4ebda28 commit 979bc9d

File tree

1 file changed

+140
-65
lines changed

1 file changed

+140
-65
lines changed

‎src/Aspire.Hosting.Yarp/README.md

Lines changed: 140 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Aspire.Hosting.Yarp library
22

3-
Provides extension methods and resource definitions for a .NET Aspire AppHost to configure a YARP instance.
3+
Provides extension methods and resource definitions for a .NET Aspire AppHost to configure a YARP reverse proxy instance.
44

55
## Getting started
66

@@ -12,80 +12,155 @@ In your AppHost project, install the .NET Aspire YARP Hosting library with [NuGe
1212
dotnet add package Aspire.Hosting.Yarp
1313
```
1414

15-
## Usage example
15+
## Usage examples
1616

17-
Then, in the _Program.cs_ file of `AppHost`, add a YARP resource and provide the configuration file using the following methods:
17+
### Programmatic configuration
18+
19+
The modern approach uses programmatic configuration with the `WithConfiguration` method:
20+
21+
```csharp
22+
var builder = DistributedApplication.CreateBuilder(args);
23+
24+
var backendService = builder.AddProject<Projects.Backend>("backend");
25+
var frontendService = builder.AddProject<Projects.Frontend>("frontend");
26+
27+
var gateway = builder.AddYarp("gateway")
28+
.WithConfiguration(yarp =>
29+
{
30+
// Add a catch-all route for the frontend
31+
yarp.AddRoute(frontendService);
32+
33+
// Add a route with path prefix for the backend API
34+
yarp.AddRoute("/api/{**catch-all}", backendService)
35+
.WithTransformPathRemovePrefix("/api");
36+
});
37+
38+
var app = builder.Build();
39+
await app.RunAsync();
40+
```
41+
42+
### Configuration with external services
43+
44+
You can also route to external services:
45+
46+
```csharp
47+
var externalApi = builder.AddExternalService("external-api", "https://api.example.com");
48+
49+
var gateway = builder.AddYarp("gateway")
50+
.WithConfiguration(yarp =>
51+
{
52+
yarp.AddRoute("/external/{**catch-all}", externalApi)
53+
.WithTransformPathRemovePrefix("/external");
54+
});
55+
```
56+
## Configuration API
57+
58+
### Core methods
59+
60+
| Method | Description |
61+
|--------|-------------|
62+
| `AddYarp(string name)` | Adds a YARP container resource to the application |
63+
| `WithConfiguration(Action<IYarpConfigurationBuilder>)` | Configures YARP programmatically |
64+
| `WithHostPort(int? port)` | Sets a specific host port instead of random assignment |
65+
66+
### Route configuration
67+
68+
The `IYarpConfigurationBuilder` provides methods to configure routes and clusters:
69+
70+
```csharp
71+
// Add routes with different targets
72+
yarp.AddRoute(resource); // Catch-all route
73+
yarp.AddRoute("/path/{**catch-all}", resource); // Specific path route
74+
yarp.AddRoute("/path/{**catch-all}", endpoint); // Route to specific endpoint
75+
yarp.AddRoute("/path/{**catch-all}", externalService); // Route to external service
76+
77+
// Add clusters directly
78+
var cluster = yarp.AddCluster(resource);
79+
var route = yarp.AddRoute("/path/{**catch-all}", cluster);
80+
```
81+
82+
### Route matching options
83+
84+
Routes can be configured with various matching criteria:
85+
86+
```csharp
87+
yarp.AddRoute("/api/{**catch-all}", backendService)
88+
.WithMatchMethods("GET", "POST") // HTTP methods
89+
.WithMatchHeaders(new RouteHeader("Content-Type", "application/json")) // Headers
90+
.WithMatchHosts("api.example.com") // Host header
91+
.WithOrder(1); // Route priority
92+
```
93+
94+
## Transform extensions
95+
96+
YARP provides various transform extensions to modify requests and responses:
97+
98+
### Path transforms
99+
100+
```csharp
101+
route.WithTransformPathSet("/new/path") // Set path
102+
.WithTransformPathPrefix("/prefix") // Add prefix
103+
.WithTransformPathRemovePrefix("/api") // Remove prefix
104+
.WithTransformPathRouteValues("/users/{id}/posts"); // Use route values
105+
```
106+
107+
### Request header transforms
108+
109+
```csharp
110+
route.WithTransformRequestHeader("X-Forwarded-For", "value") // Add/set header
111+
.WithTransformRequestHeaderRouteValue("X-User-Id", "id") // From route value
112+
.WithTransformUseOriginalHostHeader(true) // Preserve host
113+
.WithTransformCopyRequestHeaders(false); // Copy headers
114+
```
115+
116+
### Response transforms
18117

19118
```csharp
20-
var catalogService = builder.AddProject<Projects.CatalogService>("catalogservice")
21-
[...];
22-
var basketService = builder.AddProject<Projects.BasketService>("basketservice")
23-
[...];
24-
25-
builder.AddYarp("apigateway")
26-
.WithConfigFile("yarp.json")
27-
.WithReference(basketService)
28-
.WithReference(catalogService);
119+
route.WithTransformResponseHeader("X-Powered-By", "Aspire") // Add response header
120+
.WithTransformResponseHeaderRemove("Server") // Remove header
121+
.WithTransformCopyResponseHeaders(true); // Copy headers
29122
```
30123

31-
The `yarp.json` configuration file can use the referenced service like this:
32-
33-
```json
34-
{
35-
"Logging": {
36-
"LogLevel": {
37-
"Default": "Information",
38-
"Microsoft.AspNetCore": "Information"
39-
}
40-
},
41-
"AllowedHosts": "*",
42-
"ReverseProxy": {
43-
"Routes": {
44-
"catalog": {
45-
"ClusterId": "catalog",
46-
"Match": {
47-
"Path": "/catalog/{**catch-all}"
48-
},
49-
"Transforms": [
50-
{ "PathRemovePrefix": "/catalog" }
51-
]
52-
},
53-
"basket": {
54-
"ClusterId": "basket",
55-
"Match": {
56-
"Path": "/basket/{**catch-all}"
57-
},
58-
"Transforms": [
59-
{ "PathRemovePrefix": "/basket" }
60-
]
61-
}
62-
},
63-
"Clusters": {
64-
"catalog": {
65-
"Destinations": {
66-
"catalog": {
67-
"Address": "http://catalogservice",
68-
}
69-
}
70-
},
71-
"basket": {
72-
"Destinations": {
73-
"basket": {
74-
"Address": "http://basketservice",
75-
}
76-
}
77-
}
78-
}
79-
}
80-
}
124+
### Query parameter transforms
81125

126+
```csharp
127+
route.WithTransformQueryValue("version", "1.0") // Add query param
128+
.WithTransformQueryRouteValue("userId", "id") // From route value
129+
.WithTransformQueryRemoveKey("debug"); // Remove query param
130+
```
131+
132+
## Advanced configuration
133+
134+
### Custom port configuration
135+
136+
```csharp
137+
var gateway = builder.AddYarp("gateway")
138+
.WithHostPort(8080) // Use specific port
139+
.WithConfiguration(yarp => { /* config */ });
140+
```
141+
142+
### Multiple routes to the same service
143+
144+
```csharp
145+
builder.AddYarp("gateway")
146+
.WithConfiguration(yarp =>
147+
{
148+
// Different routes to the same backend
149+
yarp.AddRoute("/api/v1/{**catch-all}", backendService)
150+
.WithTransformPathRemovePrefix("/api/v1");
151+
152+
yarp.AddRoute("/api/v2/{**catch-all}", backendService)
153+
.WithTransformPathRemovePrefix("/api/v2")
154+
.WithTransformPathPrefix("/v2");
155+
});
82156
```
83157

84158
## Additional documentation
85159

86-
* https://learn.microsoft.com/dotnet/aspire/caching/stackexchange-redis-component
87-
* https://learn.microsoft.com/dotnet/aspire/caching/stackexchange-redis-output-caching-component
88-
* https://learn.microsoft.com/dotnet/aspire/caching/stackexchange-redis-distributed-caching-component
160+
* [YARP documentation](https://microsoft.github.io/reverse-proxy/)
161+
* [.NET Aspire documentation](https://learn.microsoft.com/dotnet/aspire/)
162+
* [YARP integration in .NET Aspire](https://learn.microsoft.com/dotnet/aspire/proxies/yarp-integration)
163+
* [Service Discovery in .NET Aspire](https://learn.microsoft.com/dotnet/aspire/service-discovery/overview)
89164

90165
## Feedback & contributing
91166

0 commit comments

Comments
 (0)