aspire-configuration

Name: aspire-configuration
Author: Aaronontheweb

340installs98forks

How to install aspire-configuration?

aaronontheweb/dotnet-skills/aspire-configuration

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

Installs into the current project.

Summary

Configure Aspire AppHost to emit explicit app config via environment variables; keep app code free of Aspire clients and service discovery.

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.md`
145	- `skills/akka/aspire-configuration/SKILL.md`
146
147	---
148
149	## Resources
150
151	- Aspire AppHost environment configuration: https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/app-host
152	- Configura

People who liked this also viewed

6 picks

Type

hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026262k37k
request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026165k181k
analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026161k507
explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026161k507
ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026160k181k
scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026149k181k

aspire-configuration

340installs98forks

View on GitHub

How to install aspire-configuration?

aaronontheweb/dotnet-skills/aspire-configuration

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

Installs into the current project.

Summary

Configure Aspire AppHost to emit explicit app config via environment variables; keep app code free of Aspire clients and service discovery.

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.md`
145	- `skills/akka/aspire-configuration/SKILL.md`
146
147	---
148
149	## Resources
150
151	- Aspire AppHost environment configuration: https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/app-host
152	- Configura

People who liked this also viewed

6 picks

Type