Nextended.Aspire 10.1.34

Nextended.Aspire

Conditional AppHost builder extensions — WithReferenceIf / WaitForIf / WithExplicitStartIf, strongly typed environment variables from config objects, HTTPS dev-cert wiring, Docker guards, GitHub-source resources and npm app discovery.

📖 Documentation: English · Deutsch

Installation

dotnet add package Nextended.Aspire

Add it to your AppHost project. The other Nextended.Aspire.Hosting.* packages build on it.

The idea

An AppHost accumulates conditionals. A resource only exists in local development, a reference is only wired when a feature flag is on, a queue is only awaited in CI. Written straight, that turns Program.cs into a staircase of if blocks with a duplicated builder chain in each branch.

Every extension here is the conditional form of an existing Aspire call: it applies the step when the condition holds and returns the builder untouched when it does not, so the chain stays one chain.

Feature map

Quick start

One chain instead of a staircase

var builder = DistributedApplication.CreateBuilder(args);

var isLocal = builder.Environment.IsDevelopment();
var cache   = isLocal ? builder.AddRedis("cache") : null;

var api = builder.AddProject<Projects.Api>("api")
    // Null dependency? The call is a no-op — no if, no duplicated chain.
    .WithReferenceIf(cache)
    .WithReferenceIf("legacy", legacyUri)          // skipped when legacyUri is null
    .WaitForIf(isLocal, database)
    .WithExplicitStartIf(!isLocal);                // in production, start it manually

WithReferenceIf(dependency) overloads accept a nullable builder, so "the resource may not exist at all" is expressible without a null check at the call site.

Configuration objects instead of environment-variable strings

record SmtpOptions(string Host, int Port, bool UseTls);

api.WithEnvironments(new SmtpOptions("localhost", 1025, false));

The object is flattened with __ separators and prefixed with the type name, producing SmtpOptions__Host, SmtpOptions__Port, SmtpOptions__UseTls — exactly the shape IConfiguration binding expects, so the consuming service reads it back with Configuration.GetSection("SmtpOptions").Get<SmtpOptions>(). Nested objects keep flattening, so a whole options tree travels in one call.

Pass your own prefix when the section name differs, or use WithEnvironmentsIf to skip the whole block when the options object is null:

api.WithEnvironments(smtpOptions, "Mail")     // Mail__Host, Mail__Port, …
   .WithEnvironmentsIf(featureOptions);       // no-op when featureOptions is null

There is also a refactor-safe single-value form that derives the variable name from the expression:

api.WithEnvironment<Projects.Api, SmtpOptions>(o => o.Host, "smtp.internal");

Project names you do not have to repeat

// Resource name and launch profile are derived from the project type,
// PascalCase split into a dash-separated, Aspire-legal resource name.
var api = builder.AddWithAutoNaming<Projects.My_Api_Service>();

Do not fail with a container error when Docker simply is not running

// Check up front and start the daemon rather than failing on the first container pull.
builder.Build()
    .EnsureDockerRunningIfLocalDebug()
    .Run();

IsDockerInstalled() and IsDockerRunning() are available for your own branching, and StartDocker() launches the daemon on Windows.

HTTPS dev certificate inside a container

var app = builder.AddContainer("frontend", "my/frontend")
    .RunWithHttpsDevCertificate();

The ASP.NET Core dev certificate is exported and mounted, so a containerised resource can serve HTTPS in local development without a manual certificate dance.

Resources straight from a Git repository

var tool = builder.AddGithubRepository("docs", "https://github.com/fgilde/Nextended");

EnsureGitCheckout clones or updates the working copy first, so the resource has its sources before it builds.

Every npm app in a folder

// One NodeAppResource per package.json found beneath the path.
var frontends = builder.AddAllNpmAppsInPath("../frontends");

The Aspire hosting integrations

Ready-made resources built on this package, each with a runnable AppHost sample:

Supported frameworks

• net8.0
• net9.0
• net10.0

Dependencies

• Nextended.Core
• Aspire.Hosting.AppHost

The Nextended family

The other 17 packages in the suite:

Core libraries

• Nextended.Core — Foundation library — extension methods, custom types (Money, Date, BaseId, SuperType), class mapping, deep clone, encryption, hashing and the code-generation attributes.
• Nextended.Cache — Expression-based caching — automatic cache keys from method expressions, CacheProvider with condition-based invalidation, thread-safe AddOrGetExisting.

Data access

• Nextended.EF — Entity Framework Core extensions — graph loading (LoadGraphAsync, IncludeAll, MultiInclude), declarative include definitions, paging, dynamic sorting and bulk operations.

ASP.NET Core & web

• Nextended.Web — ASP.NET Core utilities — zero-config OData (AddODataAuto), composable IQueryable OData appliers, strongly typed controller URLs, streaming download helpers and a background executor that can replay a captured request.
• Nextended.ResponseFilters — Fluent, provider-agnostic pipeline that redacts, masks, rounds, truncates, hashes, prunes and restructures response DTOs before serialization — per request, per user, per permission.
• Nextended.ResponseFilters.AspNetCore — ASP.NET Core adapter for Nextended.ResponseFilters — registers the pipeline as a global IAsyncResultFilter and replays structural edits against the serialized JSON tree.

UI libraries

• Nextended.Blazor — Blazor helpers — IBrowserFile extensions (bytes, data URLs, downloads), a hierarchical model for browsing inside uploaded zip/tar/rar archives, MIME-type detection and component-parameter reflection.
• Nextended.UI — WPF and Windows desktop helpers — a global input-binding manager with hold/sequence matching, DirectInput and XInput gamepad readers, key-bind capture controls, converters, behaviours, markup extensions and runtime-defined PropertyGrid types.

Code generation & tooling

• Nextended.Imaging — Image processing — aspect-preserving resize, crop, colour replacement, brightness-based foreground picking, thumbnail generation, byte/data-URL conversion and MIME detection from magic bytes.
• Nextended.CodeGen — Roslyn source generator — DTOs and interfaces from your entities, strongly typed classes from JSON/XML, lookup tables from Excel, and documentation from source files.

.NET Aspire hosting

• Nextended.Aspire — Conditional AppHost builder extensions — WithReferenceIf / WaitForIf / WithExplicitStartIf, strongly typed environment variables from config objects, HTTPS dev-cert wiring, Docker guards, GitHub-source resources and npm app discovery. (this package)
• Nextended.Aspire.Hosting.Supabase — The complete Supabase stack — Postgres, Auth (GoTrue), REST, Realtime, Storage, Studio, Kong and Edge Functions — as one composable Aspire resource.
• Nextended.Aspire.Hosting.N8n — The n8n workflow-automation platform as an Aspire resource, with Postgres persistence, workflow import and a typed client for triggering workflows from .NET.
• Nextended.Aspire.Hosting.Grafana — Grafana, Prometheus, Loki, Tempo, Promtail, cAdvisor, postgres_exporter and the OpenTelemetry Collector as composable resources with auto-provisioned datasources.
• Nextended.Aspire.Hosting.WebDataStudio — WebDataStudio — a browser database studio for PostgreSQL, MySQL, SQL Server, SQLite, Oracle, DuckDB, ClickHouse, MongoDB and Redis — wired to the databases of your stack, with accounts and roles, an optional SQL assistant, and an MCP endpoint for AI agents.
• Nextended.Aspire.Hosting.AspireUI — AspireUI — the visual AppHost builder — as a resource inside your own Aspire stack, with an optional pre-seeded admin user and a starter stack built from your project paths.
• Nextended.Aspire.Hosting.LocalAI — Self-hosted, OpenAI-compatible multimodal AI — image generation, text-to-speech, speech-to-text and video — with gallery model management, GPU support and Open WebUI.
• Nextended.Aspire.Hosting.Php — Run PHP endpoints inside your Aspire stack — a docroot folder or a single router script served by PHP's built-in web server, with php.ini settings as fluent options.

Links

• 📦 NuGet package
• 📖 Documentation — English
• 📖 Dokumentation — Deutsch
• 🏠 Documentation portal
• 🧑‍💻 Source code
• 🐛 Report an issue

License

GPL-3.0-or-later — see LICENSE.