C# file-based apps

Цей контент ще не доступний вашою мовою.

This article is the reference for the Aspire C# file-based apps hosting integration. It enumerates the AppHost APIs — with examples for both AppHost.cs and apphost.ts — that you use to model C# file-based app resources in your AppHost project.

C# file-based applications let you run single .cs files without a .csproj project file. This feature, built on .NET 10 SDK’s file-based app support, integrates directly with Aspire’s orchestration. Use AddCSharpApp (or addCSharpApp in TypeScript) to add these lightweight apps to your AppHost alongside traditional projects, containers, and executables.

When to use file-based apps

Use file-based apps when you need to:

Prototype a service quickly without project scaffolding.
Run simple worker processes or background tasks.
Create lightweight APIs with minimal ceremony.
Experiment with Aspire integrations in a single file.

For production workloads or apps with multiple source files, use AddProject<T> (C#) or addProject (TypeScript) with a standard .csproj project instead.

Add C# app resource

Call AddCSharpApp with a resource name and the relative path to a .cs file. The path is resolved relative to the AppHost directory:

C#
TypeScript

#pragma warning disable ASPIRECSHARPAPPS001

var builder = DistributedApplication.CreateBuilder(args);

builder.AddCSharpApp("worker", "../worker/Program.cs");

builder.Build().Run();

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

await builder.addCSharpApp("worker", "../worker/Program.cs");

await builder.build().run();

You can also point to a .csproj file or a directory that contains one:

C#
TypeScript

#pragma warning disable ASPIRECSHARPAPPS001

var builder = DistributedApplication.CreateBuilder(args);

// Point to a .csproj file
builder.AddCSharpApp("api", "../api/Api.csproj");

// Point to a directory containing a .csproj file
builder.AddCSharpApp("frontend", "../frontend/");

builder.Build().Run();

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

// Point to a .csproj file
await builder.addCSharpApp("api", "../api/Api.csproj");

// Point to a directory containing a .csproj file
await builder.addCSharpApp("frontend", "../frontend/");

await builder.build().run();

For more information about AddProject, project references, and generated Projects types, see Project resources.

Add resource dependencies

File-based apps integrate fully with Aspire’s resource model. You can reference other resources and configure service discovery just like any other project resource:

C#
TypeScript

#pragma warning disable ASPIRECSHARPAPPS001

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");
var db = builder.AddPostgres("pg").AddDatabase("mydb");

builder.AddCSharpApp("worker", "../worker/Program.cs")
    .WithReference(cache)
    .WithReference(db)
    .WithExternalHttpEndpoints();

builder.Build().Run();

import { createBuilder } from './.modules/aspire.js';

const builder = await createBuilder();

const cache = await builder.addRedis("cache");
const pg = await builder.addPostgres("pg");
const db = await pg.addDatabase("mydb");

await builder.addCSharpApp("worker", "../worker/Program.cs")
    .withReference(cache)
    .withReference(db)
    .withExternalHttpEndpoints();

await builder.build().run();

The file-based app receives connection strings and service discovery information through environment variables, exactly like projects added with AddProject<T> (or addProject).

Configure options

The C# AddCSharpApp method accepts an optional Action<ProjectResourceOptions> callback to configure launch settings:

C#
TypeScript

#pragma warning disable ASPIRECSHARPAPPS001

var builder = DistributedApplication.CreateBuilder(args);

builder.AddCSharpApp("api", "../api/Api.cs", options =>
{
    options.LaunchProfileName = "https";
    options.ExcludeLaunchProfile = false;
    options.ExcludeKestrelEndpoints = false;
});

builder.Build().Run();

The available options are the same as those used with AddProject<T>:

Option	Description
`LaunchProfileName`	The name of the launch profile to use from launchSettings.json.
`ExcludeLaunchProfile`	When `true`, ignores launch profile settings.
`ExcludeKestrelEndpoints`	When `true`, doesn’t automatically add Kestrel endpoints.

File-based AppHost

You can also write the AppHost itself as a file-based C# app using the #:sdk directive:

#:sdk Aspire.AppHost.Sdk@13.1.0
#:package Aspire.Hosting.Redis@13.1.0

#pragma warning disable ASPIRECSHARPAPPS001

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

builder.AddCSharpApp("worker", "../worker/Program.cs")
    .WithReference(cache);

builder.Build().Run();

Use #:package directives to add NuGet package references directly in the source file instead of a .csproj.

Learn more about the Aspire SDK.

Limitations

Since this feature is experimental, be aware of the following limitations:

Experimental status — the API is marked with [Experimental("ASPIRECSHARPAPPS001")] and may change in future releases.
Single-file only — file-based apps are limited to a single .cs file per resource.
.NET 10 SDK required — file-based app execution requires the .NET 10 SDK or later.
No deployment support — file-based apps are designed for local development scenarios.

Suppress the diagnostic

To use AddCSharpApp in a C# AppHost, suppress the ASPIRECSHARPAPPS001 diagnostic using one of these methods:

In code with a pragma directive:

#pragma warning disable ASPIRECSHARPAPPS001
builder.AddCSharpApp("worker", "../worker/Program.cs");
#pragma warning restore ASPIRECSHARPAPPS001

In your project file with NoWarn:

<PropertyGroup>
    <NoWarn>$(NoWarn);ASPIRECSHARPAPPS001</NoWarn>
</PropertyGroup>

In an .editorconfig file:

[*.{cs,vb}]
dotnet_diagnostic.ASPIRECSHARPAPPS001.severity = none

Learn more about ASPIRECSHARPAPPS001.