Feature Proposal: WithEnvFile for Aspire resources
- Dominant language
- C#
- Stars
- 6.3k
- Forks
- 991
- Avg merge
- 2d 15h
- Merged PRs (30d)
- 196
Description
## Background and Motivation
Enable Aspire resources to load environment variables from `.env` files and map them to Aspire parameters. This simplifies configuration and supports best practices for parameter management and secrets.
## Proposed API
```csharp
public static IResourceBuilder WithEnvFile(this IResourceBuilder builder)
where T : IResourceWithEnvironment;
public static IResourceBuilder WithEnvFile(
this IResourceBuilder builder,
Action> configure)
where T : IResourceWithEnvironment;
```
### EnvEntry Structure (Immutable)
```csharp
public sealed class EnvEntry
{
public string Key { get; }
public string? Value { get; }
public string? Comment { get; }
public EnvEntry(string key, string? value, string? comment)
{
Key = key;
Value = value;
Comment = comment;
}
}
```
## Mapping Rules
- By default, each `.env` entry is mapped to a non-secret parameter with the key and value.
- Comments from the `.env` file are available via the `Comment` property on `EnvEntry`.
- The second overload allows the user to customize:
- Whether a parameter is a secret (based on key name or custom logic)
- The parameter description or other metadata
- Skipping or modifying entries before mapping
- **Parameter Name Uniqueness:**
To ensure uniqueness for parameters originating from an `.env` file, the naming scheme should be `{resource}-env-{key}` (where `{resource}` is the logical name or ID of the resource and `{key}` is the environment variable key, lowercased). This avoids collisions across resources and makes the origin clear.
- Example: For resource `"ui"` and key `"API_KEY"`, the parameter name would be `"ui-env-api_key"`.
### Usage Example
```csharp
builder.AddNpmApp("ui", "../frontend")
.WithEnvFile();
builder.AddNpmApp("ui", "../frontend")
.WithEnvFile((entry, paramBuilder) =>
{
if (entry.Key.EndsWith("_SECRET"))
paramBuilder.Resource.Secret = true;
paramBuilder.WithDescription(entry.Comment ?? $"Imported from .env: {entry.Key}");
// Parameter name will automatically be "ui-env-{key.ToLowerInvariant()}"
});
```
## Risks & Considerations
- **File not found:** If `.env` is not found, nothing happens.
- **Duplicate keys:** If duplicate keys exist, only the last one is used.
- **Sensitive data:** Take care not to accidentally expose secrets.
- **Error handling:** Consider adding logging or errors for malformed lines.
- **Customization:** Users have full control via the callback to decide how each env entry is mapped.
- **Parameter Naming:** Uniqueness is guaranteed by the `{resource}-env-{key}` (lowercased) scheme.
- **Immutability:** `EnvEntry` is immutable for thread safety and reliability.
---
Contributor guide
Research direction
Start by reviewing Aspire's existing IResourceBuilder, IResourceWithEnvironment, and ParameterResource APIs against the proposed WithEnvFile overloads and EnvEntry shape. Define completion around parsing .env entries, applying the resource-qualified parameter names, supporting callback customization, and covering the stated missing-file, duplicate-key, malformed-line, comment, and secret-handling behaviors.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- cloud
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100