Support single file cs apphost

[davidfowl]

The .NET 10 SDK supports single file C# programs. This would allow us to run aspire applications as a single cs file instead of using a project. We have lots of configuration options spread across appsettings and the launch profile that need to go somewhere.

Proposal work to make this experience nice:

• We need to support this via aspire run. It's unclear how this will interact with scanning.
• We need to find a home for these settings.
• We need single file apphost templates.
• We need a way to add a single file as project as an aspire resource (see AddCSharpApp below) (with debug support?)

Current POC: ()

#:package Aspire.Hosting.AppHost@9.3.0
// This is because the current version does not support NuGet based MSBuild SDKs
#:package Aspire.Hosting.Orchestration.win-x64@9.3.0
#:package Aspire.Dashboard.Sdk.win-x64@9.3.0

#region config
Environment.SetEnvironmentVariable("ASPIRE_ALLOW_UNSECURED_TRANSPORT", "true");
Environment.SetEnvironmentVariable("ASPNETCORE_URLS", "http://localhost:5003");
Environment.SetEnvironmentVariable("ASPNETCORE_ENVIRONMENT", "Development");
Environment.SetEnvironmentVariable("ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL", "http://localhost:4317");
Environment.SetEnvironmentVariable("ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL", "http://localhost:5001");

Environment.SetEnvironmentVariable("Logging__LogLevel__Default", "Information");
Environment.SetEnvironmentVariable("Logging__LogLevel__Aspire.Hosting.Dcp", "Warning");
Environment.SetEnvironmentVariable("Logging__LogLevel__Microsoft.AspNetCore", "Warning");
#endregion

var builder = DistributedApplication.CreateBuilder(args);

builder.AddCSharpApp("api", "api.cs")
       .WithHttpEndpoint(targetPort: 5000);

builder.Build().Run();

#region csharpfile
public static class CSFileExtensions
{
    public static IResourceBuilder<CsharpFileApp> AddCSharpApp(this IDistributedApplicationBuilder builder, string name, string filePath)
    {
        return builder.AddResource(new CsharpFileApp(name, Environment.CurrentDirectory))
            .WithArgs("run", filePath);
    }
}

public class CsharpFileApp(string name, string workingDirectory) : ExecutableResource(name, "dotnet", workingDirectory)
{

}
#endregion

[davidfowl]

cc @mitchdenny @maddymontaquila

[DamianEdwards]

Other issues is Aspire defaults for the dashboard URLs (there aren't any), and lack of launch profiles in single-file apps (without a separate file). The launch profile is where the environment is set to "Development" today, which is required to trigger ASP.NET Core to load the developer certificate in order to host an HTTPS endpoint. I attempted to add back Aspire defaults for URLs but without the dev cert you're stuck in HTTP land which also requires the AllowUnsecureTransport setting to be opted-in to via, you guessed it, a launch profile. 😕

[maddymontaquila]

aspire add will have to know how to add single file type package references too

[DamianEdwards]

aspire add will have to know how to add single file type package references too

Assuming it just shells to dotnet package add, it will "just work" for file-based apps once dotnet/sdk#49635 is merged

[DamianEdwards]

We're going to look at adding support for "implicit launch profiles" to the dotnet run app.cs experience, such that an SDK or package can provide a default launch profile in the case one isn't present. Then there'd be a command to drop it on disk for customization. This will let the Aspire SDK provide a default launch profile with the necessary configuration to let a single-file AppHost run with HTTPS, etc.

[jomaxso]

I have been experimenting with the current AppHost.cs setup over the past few days and would like to share some insights.

This is what I played with:

#!/usr/bin/env dotnet

#:sdk Microsoft.NET.Sdk
#:sdk Aspire.AppHost.Sdk@9.3.1

#:property PublishAot=false

#:package Aspire.Hosting.AppHost@9.3.1
#:package Aspire.Hosting.PostgreSQL@9.*

#:project Api/Api.csproj

var builder = DistributedApplication.CreateBuilder(args);

// Required settings
builder.Configuration["ASPNETCORE_ENVIRONMENT"] ??= "Development";
builder.Configuration["ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL"] ??= "http://localhost:4317";
builder.Configuration["ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL"] ??= "http://localhost:5001";

// Optional settings to improve local development experience
builder.Configuration["ASPIRE_ALLOW_UNSECURED_TRANSPORT"] ??= "true";
builder.Configuration["ASPNETCORE_URLS"] ??= "http://localhost:5003";

builder.Configuration["Logging:LogLevel:Default"] ??= "Information";
builder.Configuration["Logging:LogLevel:Aspire.Hosting.Dcp"] ??= "Warning";
builder.Configuration["Logging:LogLevel:Microsoft.AspNetCore"] ??= "Warning";

var postgres = builder.AddPostgres("postgres")
                      .WithLifetime(ContainerLifetime.Persistent);

var postgresdb = postgres.AddDatabase("db");

var migration = builder.AddCSharpScript("api-db-migration", "Api.Db.Migration.cs")
                       .WithParentRelationship(postgres)
                       .WithReference(postgresdb)
                       .WaitFor(postgresdb);

var api = builder.AddProject<Projects.Api>("api")
                 .WithReference(postgresdb)
                 .WaitFor(postgresdb);

builder.Build().Run();

public static class CSFileExtensions
{
    public static IResourceBuilder<CsharpFileResource> AddCSharpScript(this IDistributedApplicationBuilder builder, string name, string filePath)
    {
        return builder.AddResource(new CsharpFileResource(name, Environment.CurrentDirectory))
                      .WithArgs("run", filePath)
                      .WithEnvironment("OTEL_EXPORTER_OTLP_ENDPOINT", builder.Configuration["ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL"])
                      .WithEnvironment("OTEL_SERVICE_NAME", name);
    }
}

public class CsharpFileResource(string name, string workingDirectory) : ExecutableResource(name, "dotnet", workingDirectory);

Findings

1. Currently, when running dotnet run AppHost.cs or dotnet AppHost.cs, the project is compiled with AOT, which leads to errors in AppHost. Therefore, you must explicitly set #:property PublishAot=false. This could be implied by the Aspire.AppHost.Sdk to avoid confusion for developers who may not be aware of this requirement.
2. The following configuration logic could ideally be provided as defaults by the DistributedApplicationBuilder itself. This would streamline local development and reduce boilerplate, allowing developers to focus on application-specific settings rather than repeatedly specifying common environment and logging options:

    // Required settings
    builder.Configuration["ASPNETCORE_ENVIRONMENT"] ??= "Development";
    builder.Configuration["ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL"] ??= "http://localhost:4317";
    builder.Configuration["ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL"] ??= "http://localhost:5001";
   
    // Optional settings to improve local development experience
    builder.Configuration["ASPIRE_ALLOW_UNSECURED_TRANSPORT"] ??= "true";
    builder.Configuration["ASPNETCORE_URLS"] ??= "http://localhost:5003";
   
    builder.Configuration["Logging:LogLevel:Default"] ??= "Information";
    builder.Configuration["Logging:LogLevel:Aspire.Hosting.Dcp"] ??= "Warning";
    builder.Configuration["Logging:LogLevel:Microsoft.AspNetCore"] ??= "Warning";

3. When using #:sdk Aspire.AppHost.Sdk@9.3.1, you must also explicitly specify #:sdk Microsoft.NET.Sdk because Aspire.AppHost.Sdk does not implicitly include the .NET SDK. This can be confusing, as one might expect the AppHost SDK to bring all required dependencies automatically. In general, it would be beneficial if the AppHost SDK could automatically include the necessary .NET SDK and other common dependencies like Aspire.Hosting.AppHost to reduce the need for manual configuration in the project file.

Conclusion

With the introduction of a dedicated Aspire SDK alias such as Microsoft.NET.Sdk.Aspire, similar to established SDKs like Microsoft.NET.Sdk.Web or Microsoft.NET.Sdk.Worker, the setup process could be greatly simplified. This would enable developers to focus on building application features rather than managing environment configuration, resulting in a more streamlined and developer-friendly experience.

One open question remains: Would the release cycle of Aspire, with such an integration, then be directly tied to the .NET version, similar to the other SDKs?

A more streamlined configuration could look like this:

#!/usr/bin/env dotnet

#:sdk Microsoft.NET.Sdk.Aspire // Could this be versioned like `Microsoft.NET.Sdk.Aspire@9.3.1`?

#:package Aspire.Hosting.PostgreSQL@9.*
#:project Api/Api.csproj

var builder = DistributedApplication.CreateBuilder(args);

var postgres = builder.AddPostgres("postgres")
                      .WithLifetime(ContainerLifetime.Persistent);

var postgresdb = postgres.AddDatabase("db");

var migration = builder.AddCSharpScript("api-db-migration", "Api.Db.Migration.cs")
                       .WithParentRelationship(postgres)
                       .WithReference(postgresdb)
                       .WaitFor(postgresdb);

var api = builder.AddProject<Projects.Api>("api")
                 .WithReference(postgresdb)
                 .WaitFor(postgresdb);

builder.Build().Run();

[DamianEdwards]

@jomaxso thanks for your feedback.

1. Yep that's something we've talked about doing and I think it makes sense.
2. That default would be unsecured which is something we won't do (by default). We're looking to introduce support for "implicit launch profiles" so that the SDK can provide a default launch profile in the case the app doesn't have one and all these settings would be taken care of there.
3. We chose to keep the Aspire SDK separate and make the project compose it as necessary but it's possible we could update it to auto-import the NET SDK if it detects it hasn't been already. (@joperezr for his thoughts)

[jomaxso]

Since #:sdk Aspire.AppHost.Sdk needs to be referenced with a specific version, would it make sense to also include Aspire.Hosting.AppHost in the SDK?

[DamianEdwards]

Since #:sdk Aspire.AppHost.Sdk needs to be referenced with a specific version, would it make sense to also include Aspire.Hosting.AppHost in the SDK?

Our goal was to have the SDK not version every release, so we specifically kept the versions separate, but we haven't gotten there yet for various reasons.