DotnetProjectHostingExtensions Methods

AddDotnetProject(IDistributedApplicationBuilder, string, string)extensionIResourceBuilder<DotnetProjectResource>

Adds a C# project or file-based app to the application model.

public static class DotnetProjectHostingExtensions
{
    public static IResourceBuilder<DotnetProjectResource> AddDotnetProject(
        this IDistributedApplicationBuilder builder,
        string name,
        string path)
    {
        // ...
    }
}

DotnetProjectHostingExtensions.cs#L243-L247

Parameters

builderIDistributedApplicationBuilderThe Hosting.IDistributedApplicationBuilder.

namestringThe name of the resource. This name will be used for service discovery when referenced in a dependency.

pathstringThe path to the file-based app file, project file, or project directory.

Returns

IResourceBuilder<DotnetProjectResource>A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

This overload of the DotnetProjectHostingExtensions.AddDotnetProject method adds a C# project or file-based app to the application model using a path to the file-based app .cs file, project file (.csproj), or project directory. If the path is not an absolute path then it will be computed relative to the AppHost directory.

Add a file-based app to the app model via a file path.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddDotnetProject("inventoryservice", @"..\InventoryService.cs");

builder.Build().Run();

AddDotnetProject(IDistributedApplicationBuilder, string, string, Action<ProjectResourceOptions>)extensionIResourceBuilder<DotnetProjectResource>

Adds a C# project or file-based app to the application model.

public static class DotnetProjectHostingExtensions
{
    public static IResourceBuilder<DotnetProjectResource> AddDotnetProject(
        this IDistributedApplicationBuilder builder,
        string name,
        string path,
        Action<ProjectResourceOptions> configure)
    {
        // ...
    }
}

DotnetProjectHostingExtensions.cs#L293-L458

Parameters

builderIDistributedApplicationBuilderThe Hosting.IDistributedApplicationBuilder.

namestringThe name of the resource. This name will be used for service discovery when referenced in a dependency.

pathstringThe path to the file-based app file, project file, or project directory.

configureAction<ProjectResourceOptions>An optional action to configure the C# app resource options.

Returns

IResourceBuilder<DotnetProjectResource>A reference to the ApplicationModel.IResourceBuilder`1.

Remarks

This overload of the DotnetProjectHostingExtensions.AddDotnetProject method adds a C# project or file-based app to the application model using a path to the file-based app .cs file, project file (.csproj), or project directory. If the path is not an absolute path then it will be computed relative to the AppHost directory.

Add a file-based app to the app model via a file path.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddDotnetProject(
    "inventoryservice",
    @"..\InventoryService.cs",
    o => o.LaunchProfileName = "https");

builder.Build().Run();

WithBuildEnvironment(IResourceBuilder<DotnetProjectResource>, string, string)extensionIResourceBuilder<DotnetProjectResource>

Adds an environment variable to the build process for a .NET project.

public static class DotnetProjectHostingExtensions
{
    public static IResourceBuilder<DotnetProjectResource> WithBuildEnvironment(
        this IResourceBuilder<DotnetProjectResource> builder,
        string name,
        string value)
    {
        // ...
    }
}

DotnetProjectHostingExtensions.cs#L73-L77

Parameters

builderIResourceBuilder<DotnetProjectResource>The .NET project resource builder.

namestringThe name of the environment variable.

valuestringThe value of the environment variable.

Returns

IResourceBuilder<DotnetProjectResource>A reference to the ApplicationModel.IResourceBuilder`1 for chaining additional configuration.

Exceptions

ArgumentNullException Thrown when builder, name, or value is null.

ArgumentException Thrown when name is empty.

DistributedApplicationException Thrown when builder represents a file-based C# app.

Remarks

This method supports project files ( .csproj) only. File-based C# apps ( .cs) do not support build-only environment variables.

The variable is available while Aspire builds the project but is not added to the environment of the launched project. Use WithEnvironment separately when the same variable is also needed at runtime.

Configuring a build environment causes Aspire to build this project separately from traversal groups.

When publishing a container, do not use this API to set MSBuild properties that control the output artifact's identity, destination, format, or target platform. Aspire rejects those properties because downstream publishing steps use the values configured with WithContainerBuildOptions.

Do not use this API for secrets. Aspire must carry the value in IDE launch metadata and process environments, and the value can appear in build diagnostics. Protected temporary MSBuild response files preserve global-property semantics without exposing values in process command lines, but they are not a general-purpose secret transport.

Examples

Configure an environment variable that selects a custom build output:

builder.AddDotnetProject("worker", "../Worker/Worker.csproj")
    .WithBuildEnvironment("BUILD_FLAVOR", "custom");

WithBuildEnvironment(IResourceBuilder<DotnetProjectResource>, Action<EnvironmentCallbackContext>)extensionIResourceBuilder<DotnetProjectResource>

Adds a callback that configures build-only environment variables for a .NET project.

public static class DotnetProjectHostingExtensions
{
    public static IResourceBuilder<DotnetProjectResource> WithBuildEnvironment(
        this IResourceBuilder<DotnetProjectResource> builder,
        Action<EnvironmentCallbackContext> callback)
    {
        // ...
    }
}

DotnetProjectHostingExtensions.cs

Parameters

builderIResourceBuilder<DotnetProjectResource>The .NET project resource builder.

callbackAction<EnvironmentCallbackContext>The callback that configures the build environment.

Returns

IResourceBuilder<DotnetProjectResource>A reference to the ApplicationModel.IResourceBuilder`1 for chaining additional configuration.

Exceptions

ArgumentNullException Thrown when builder or callback is null.

DistributedApplicationException Thrown when builder represents a file-based C# app.

Remarks

This method supports project files ( .csproj) only. File-based C# apps ( .cs) do not support build-only environment variables.

When publishing a container, do not use this API to set MSBuild properties that control the output artifact's identity, destination, format, or target platform. Aspire rejects those properties because downstream publishing steps use the values configured with WithContainerBuildOptions.

Values configured by this callback are not added to the environment of the launched project. Do not use this API for secrets because Aspire carries the values in IDE launch metadata, process environments, and protected temporary MSBuild response files, and the values can appear in build diagnostics.

WithBuildEnvironment(IResourceBuilder<DotnetProjectResource>, Func<EnvironmentCallbackContext, Task>)extensionIResourceBuilder<DotnetProjectResource>

Adds an asynchronous callback that configures build-only environment variables for a .NET project.

public static class DotnetProjectHostingExtensions
{
    public static IResourceBuilder<DotnetProjectResource> WithBuildEnvironment(
        this IResourceBuilder<DotnetProjectResource> builder,
        Func<EnvironmentCallbackContext, Task> callback)
    {
        // ...
    }
}

DotnetProjectHostingExtensions.cs

Parameters

builderIResourceBuilder<DotnetProjectResource>The .NET project resource builder.

callbackFunc<EnvironmentCallbackContext, Task>The callback that configures the build environment.

Returns

IResourceBuilder<DotnetProjectResource>A reference to the ApplicationModel.IResourceBuilder`1 for chaining additional configuration.

Exceptions

ArgumentNullException Thrown when builder or callback is null.

DistributedApplicationException Thrown when builder represents a file-based C# app.

Remarks

This method supports project files ( .csproj) only. File-based C# apps ( .cs) do not support build-only environment variables.

When publishing a container, do not use this API to set MSBuild properties that control the output artifact's identity, destination, format, or target platform. Aspire rejects those properties because downstream publishing steps use the values configured with WithContainerBuildOptions.

Values configured by this callback are not added to the environment of the launched project. Do not use this API for secrets because Aspire carries the values in IDE launch metadata, process environments, and protected temporary MSBuild response files, and the values can appear in build diagnostics.