aspire-configuration

Name: aspire-configuration
Author: wshaddix

65stars10forks

How to install aspire-configuration?

wshaddix/dotnet-skills/aspire-configuration

$npx -y skills add wshaddix/dotnet-skills --skill aspire-configuration

Installs into the current project.

Summary

Configure Aspire AppHost to emit explicit app config via environment variables while keeping app code free of Aspire clients and service discovery. Use when wiring AppHost resources to application configuration, ensuring production configuration is transparent and portable outsid

Files · 1

View on GitHub

SKILL.md

1	# Aspire Configuration
2
3	## When to Use This Skill
4
5	Use this skill when:
6	- Wiring AppHost resources to application configuration in Aspire-based repos
7	- Ensuring production configuration is transparent and portable outside of Aspire
8	- Avoiding Aspire client/service-discovery packages inside application code
9	- Designing feature toggles for dev/test without changing app code paths
10
11	---
12
13	## Core Principles
14
15	1. AppHost owns Aspire infrastructure packages
16	- Aspire Hosting packages belong in AppHost only.
17	- App projects should not reference Aspire client/service-discovery packages.
18
19	2. Explicit configuration only
20	- AppHost must translate resource outputs into explicit config keys (env vars).
21	- App code binds to `IOptions<T>` or `Configuration` only.
22
23	3. Production parity and transparency
24	- Every value injected by AppHost must be representable in production as env vars
25	or config files without Aspire.
26	- Avoid opaque service discovery and implicit configuration.
27
28	---
29
30	## Configuration Flow
31
32	```
33	AppHost resource -> WithEnvironment(...) -> app config keys -> IOptions<T> in app
34	```
35
36	The AppHost is responsible for turning Aspire resources into explicit app settings.
37	The application never consumes Aspire clients or service discovery directly.
38
39	---
40
41	## AppHost Patterns (Explicit Mapping)
42
43	### Example: Database + Blob Storage
44
45	```csharp
46	// AppHost/Program.cs
47	var builder = DistributedApplication.CreateBuilder(args);
48
49	var postgres = builder.AddPostgres("postgres");
50	var db = postgres.AddDatabase("appdb");
51
52	var minio = builder.AddContainer("minio", "minio/minio")
53	.WithArgs("server", "/data")
54	.WithHttpEndpoint(targetPort: 9000, name: "http")
55	.WithHttpEndpoint(targetPort: 9001, name: "console")
56	.WithEnvironment("MINIO_ROOT_USER", "minioadmin")
57	.WithEnvironment("MINIO_ROOT_PASSWORD", "minioadmin");
58
59	var api = builder.AddProject<Projects.MyApp_Api>("api")
60	.WithReference(db, "Postgres")
61	.WithEnvironment("BlobStorage__Enabled", "true")
62	.WithEnvironment("BlobStorage__ServiceUrl", minio.GetEndpoint("http"))
63	.WithEnvironment("BlobStorage__AccessKey", "minioadmin")
64	.WithEnvironment("BlobStorage__SecretKey", "minioadmin")
65	.WithEnvironment("BlobStorage__Bucket", "attachments")
66	.WithEnvironment("BlobStorage__ForcePathStyle", "true");
67
68	builder.Build().Run();
69	```
70
71	Key points
72	- `WithReference(db, "Postgres")` sets `ConnectionStrings__Postgres` explicitly.
73	- Every external dependency is represented via explicit config keys.
74	- The API project only reads `Configuration` values.
75
76	---
77
78	## App Code Pattern (No Aspire Clients)
79
80	Application code binds to options and initializes SDKs directly. It never depends
81	on Aspire client packages or service discovery.
82
83	```csharp
84	// Api/Program.cs
85	builder.Services
86	.AddOptions<BlobStorageOptions>()
87	.BindConfiguration("BlobStorage")
88	.ValidateDataAnnotations()
89	.ValidateOnStart();
90
91	builder.Services.AddSingleton<IBlobStorageService>(sp =>
92	{
93	var options = sp.GetRequiredService<IOptions<BlobStorageOptions>>().Value;
94	return new S3BlobStorageService(options); // uses explicit options only
95	});
96	```
97
98	Do not add Aspire client packages (or `AddServiceDiscovery`) to the app.
99	Those are orchestration concerns and should stay in AppHost.
100
101	---
102
103	## Feature Toggles and Test Overrides
104
105	Keep toggles in config and drive them through AppHost and test fixtures. This
106	maintains parity between dev/test and production configuration.
107
108	```csharp
109	// AppHost: disable persistence in tests via config overrides
110	var config = builder.Configuration.GetSection("App")
111	.Get<AppHostConfiguration>() ?? new AppHostConfiguration();
112
113	if (!config.UseVolumes)
114	{
115	postgres.WithDataVolume(false);
116	}
117
118	api.WithEnvironment("BlobStorage__Enabled", config.EnableBlobStorage.ToString());
119	```
120
121	See `skills/aspire/integration-testing/SKILL.md` for patterns on passing
122	configuration overrides into `DistributedApplicationTestingBuilder`.
123
124	---
125
126	## Do / Don’t Checklist
127
128	Do
129	- Map every Aspire resource output to explicit configuration keys
130	- Use `IOptions<T>` with validation for all infrastructure settings
131	- Keep AppHost as the only place that references Aspire hosting packages
132	- Ensure any AppHost-injected value can be set in production env vars
133
134	Don’t
135	- Reference Aspire client/service-discovery packages in application projects
136	- Rely on opaque service discovery that cannot be mirrored in production
137	- Hide configuration behind Aspire-only abstractions
138
139	---
140
141	## Related Skills
142
143	- `skills/aspire/service-defaults/SKILL.md`
144	- `skills/aspire/integration-testing/SKILL

People who liked this also viewed

6 picks

Type

aspire-configuration

65stars10forks

View on GitHub

How to install aspire-configuration?

wshaddix/dotnet-skills/aspire-configuration

$npx -y skills add wshaddix/dotnet-skills --skill aspire-configuration

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Aspire Configuration
2
3	## When to Use This Skill
4
5	Use this skill when:
6	- Wiring AppHost resources to application configuration in Aspire-based repos
7	- Ensuring production configuration is transparent and portable outside of Aspire
8	- Avoiding Aspire client/service-discovery packages inside application code
9	- Designing feature toggles for dev/test without changing app code paths
10
11	---
12
13	## Core Principles
14
15	1. AppHost owns Aspire infrastructure packages
16	- Aspire Hosting packages belong in AppHost only.
17	- App projects should not reference Aspire client/service-discovery packages.
18
19	2. Explicit configuration only
20	- AppHost must translate resource outputs into explicit config keys (env vars).
21	- App code binds to `IOptions<T>` or `Configuration` only.
22
23	3. Production parity and transparency
24	- Every value injected by AppHost must be representable in production as env vars
25	or config files without Aspire.
26	- Avoid opaque service discovery and implicit configuration.
27
28	---
29
30	## Configuration Flow
31
32	```
33	AppHost resource -> WithEnvironment(...) -> app config keys -> IOptions<T> in app
34	```
35
36	The AppHost is responsible for turning Aspire resources into explicit app settings.
37	The application never consumes Aspire clients or service discovery directly.
38
39	---
40
41	## AppHost Patterns (Explicit Mapping)
42
43	### Example: Database + Blob Storage
44
45	```csharp
46	// AppHost/Program.cs
47	var builder = DistributedApplication.CreateBuilder(args);
48
49	var postgres = builder.AddPostgres("postgres");
50	var db = postgres.AddDatabase("appdb");
51
52	var minio = builder.AddContainer("minio", "minio/minio")
53	.WithArgs("server", "/data")
54	.WithHttpEndpoint(targetPort: 9000, name: "http")
55	.WithHttpEndpoint(targetPort: 9001, name: "console")
56	.WithEnvironment("MINIO_ROOT_USER", "minioadmin")
57	.WithEnvironment("MINIO_ROOT_PASSWORD", "minioadmin");
58
59	var api = builder.AddProject<Projects.MyApp_Api>("api")
60	.WithReference(db, "Postgres")
61	.WithEnvironment("BlobStorage__Enabled", "true")
62	.WithEnvironment("BlobStorage__ServiceUrl", minio.GetEndpoint("http"))
63	.WithEnvironment("BlobStorage__AccessKey", "minioadmin")
64	.WithEnvironment("BlobStorage__SecretKey", "minioadmin")
65	.WithEnvironment("BlobStorage__Bucket", "attachments")
66	.WithEnvironment("BlobStorage__ForcePathStyle", "true");
67
68	builder.Build().Run();
69	```
70
71	Key points
72	- `WithReference(db, "Postgres")` sets `ConnectionStrings__Postgres` explicitly.
73	- Every external dependency is represented via explicit config keys.
74	- The API project only reads `Configuration` values.
75
76	---
77
78	## App Code Pattern (No Aspire Clients)
79
80	Application code binds to options and initializes SDKs directly. It never depends
81	on Aspire client packages or service discovery.
82
83	```csharp
84	// Api/Program.cs
85	builder.Services
86	.AddOptions<BlobStorageOptions>()
87	.BindConfiguration("BlobStorage")
88	.ValidateDataAnnotations()
89	.ValidateOnStart();
90
91	builder.Services.AddSingleton<IBlobStorageService>(sp =>
92	{
93	var options = sp.GetRequiredService<IOptions<BlobStorageOptions>>().Value;
94	return new S3BlobStorageService(options); // uses explicit options only
95	});
96	```
97
98	Do not add Aspire client packages (or `AddServiceDiscovery`) to the app.
99	Those are orchestration concerns and should stay in AppHost.
100
101	---
102
103	## Feature Toggles and Test Overrides
104
105	Keep toggles in config and drive them through AppHost and test fixtures. This
106	maintains parity between dev/test and production configuration.
107
108	```csharp
109	// AppHost: disable persistence in tests via config overrides
110	var config = builder.Configuration.GetSection("App")
111	.Get<AppHostConfiguration>() ?? new AppHostConfiguration();
112
113	if (!config.UseVolumes)
114	{
115	postgres.WithDataVolume(false);
116	}
117
118	api.WithEnvironment("BlobStorage__Enabled", config.EnableBlobStorage.ToString());
119	```
120
121	See `skills/aspire/integration-testing/SKILL.md` for patterns on passing
122	configuration overrides into `DistributedApplicationTestingBuilder`.
123
124	---
125
126	## Do / Don’t Checklist
127
128	Do
129	- Map every Aspire resource output to explicit configuration keys
130	- Use `IOptions<T>` with validation for all infrastructure settings
131	- Keep AppHost as the only place that references Aspire hosting packages
132	- Ensure any AppHost-injected value can be set in production env vars
133
134	Don’t
135	- Reference Aspire client/service-discovery packages in application projects
136	- Rely on opaque service discovery that cannot be mirrored in production
137	- Hide configuration behind Aspire-only abstractions
138
139	---
140
141	## Related Skills
142
143	- `skills/aspire/service-defaults/SKILL.md`
144	- `skills/aspire/integration-testing/SKILL

People who liked this also viewed

6 picks

Type