ProjectResourceBuilderExtensions Methods

Docs / Reference / Search C# APIs / Aspire.Hosting / ProjectResourceBuilderExtensions / Methods

Methods

Docs Reference Search C# APIs Aspire.Hosting ProjectResourceBuilderExtensions Methods

Class Methods 12 members

Provides extension methods for IDistributedApplicationBuilder to add and configure project resources.

Experimental — ASPIRECSHARPAPPS001

AddCSharpApp(IDistributedApplicationBuilder, string, string) extension IResourceBuilder<ProjectResource>

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

public static class ProjectResourceBuilderExtensions
{
    public static IResourceBuilder<ProjectResource> AddCSharpApp(
        this IDistributedApplicationBuilder builder,
        string name,
        string path)
    {
        // ...
    }
}

ProjectResourceBuilderExtensions.cs#L320-L324

Parameters

builder IDistributedApplicationBuilder The IDistributedApplicationBuilder.

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

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

Returns

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

Remarks

This overload of the ProjectResourceBuilderExtensions.AddCSharpApp 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 app host directory.

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

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

Experimental — ASPIRECSHARPAPPS001

AddCSharpApp(IDistributedApplicationBuilder, string, string, Action<ProjectResourceOptions>) extension IResourceBuilder<CSharpAppResource>

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

public static class ProjectResourceBuilderExtensions
{
    public static IResourceBuilder<CSharpAppResource> AddCSharpApp(
        this IDistributedApplicationBuilder builder,
        string name,
        string path,
        Action<ProjectResourceOptions> configure)
    {
        // ...
    }
}

ProjectResourceBuilderExtensions.cs#L355-L400

Parameters

builder IDistributedApplicationBuilder The IDistributedApplicationBuilder.

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

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

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

Returns

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

Remarks

This overload of the ProjectResourceBuilderExtensions.AddCSharpApp 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 app host directory.

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

var builder = DistributedApplication.CreateBuilder(args);

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

builder.Build().Run();

AddProject(IDistributedApplicationBuilder, string) extension IResourceBuilder<ProjectResource>

Adds a .NET project to the application model.

public static class ProjectResourceBuilderExtensions
{
    public static IResourceBuilder<ProjectResource> AddProject<TProject>(
        this IDistributedApplicationBuilder builder,
        string name)
    {
        // ...
    }
}

ProjectResourceBuilderExtensions.cs#L68-L71

Parameters

builder IDistributedApplicationBuilder The IDistributedApplicationBuilder.

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

Returns

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

Remarks

This overload of the ProjectResourceBuilderExtensions.AddProject method takes a TProject type parameter. The TProject type parameter is constrained to types that implement the IProjectMetadata interface.

Classes that implement the IProjectMetadata interface are generated when a .NET project is added as a reference to the app host project. The generated class contains a property that returns the path to the referenced project file. Using this path .NET Aspire parses the launchSettings.json file to determine which launch profile to use when running the project, and what endpoint configuration to automatically generate.

The name of the automatically generated project metadata type is a normalized version of the project name. Periods, dashes, and spaces in project names are converted to underscores. This normalization may lead to naming conflicts. If a conflict occurs the <ProjectReference /> that references the project can have a AspireProjectMetadataTypeName="..." attribute added to override the name.

Note that endpoints coming from the Kestrel configuration are automatically added to the project. The Kestrel Url and Protocols are used to build the equivalent EndpointAnnotation.

Example of adding a project to the application model.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject<Projects.InventoryService>("inventoryservice");

builder.Build().Run();

AddProject(IDistributedApplicationBuilder, string, string) extension IResourceBuilder<ProjectResource>

Adds a .NET project to the application model.

public static class ProjectResourceBuilderExtensions
{
    public static IResourceBuilder<ProjectResource> AddProject(
        this IDistributedApplicationBuilder builder,
        string name,
        string projectPath)
    {
        // ...
    }
}

ProjectResourceBuilderExtensions.cs#L101-L105

Parameters

builder IDistributedApplicationBuilder The IDistributedApplicationBuilder.

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

projectPath string The path to the project file.

Returns

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

Remarks

This overload of the ProjectResourceBuilderExtensions.AddProject method adds a project to the application model using a path to the project file. This allows for projects to be referenced that may not be part of the same solution. If the project path is not an absolute path then it will be computed relative to the app host directory.

Add a project to the app model via a project path.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject(
    "inventoryservice",
    @"..\InventoryService\InventoryService.csproj");

builder.Build().Run();

AddProject(IDistributedApplicationBuilder, string, string?) extension IResourceBuilder<ProjectResource>

Adds a .NET project to the application model. By default, this will exist in a Projects namespace. e.g. Projects.MyProject. If the project is not in a Projects namespace, make sure a project reference is added from the AppHost project to the target project.

public static class ProjectResourceBuilderExtensions
{
    public static IResourceBuilder<ProjectResource> AddProject<TProject>(
        this IDistributedApplicationBuilder builder,
        string name,
        string? launchProfileName)
    {
        // ...
    }
}

ProjectResourceBuilderExtensions.cs#L148-L155

Parameters

builder IDistributedApplicationBuilder The IDistributedApplicationBuilder.

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

launchProfileName string? The launch profile to use. If null then no launch profile will be used.

Returns

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

Remarks

This overload of the ProjectResourceBuilderExtensions.AddProject method takes a TProject type parameter. The TProject type parameter is constrained to types that implement the IProjectMetadata interface.

Classes that implement the IProjectMetadata interface are generated when a .NET project is added as a reference to the app host project. The generated class contains a property that returns the path to the referenced project file. Using this path .NET Aspire parses the launchSettings.json file to determine which launch profile to use when running the project, and what endpoint configuration to automatically generate.

The name of the automatically generated project metadata type is a normalized version of the project name. Periods, dashes, and spaces in project names are converted to underscores. This normalization may lead to naming conflicts. If a conflict occurs the <ProjectReference /> that references the project can have a AspireProjectMetadataTypeName="..." attribute added to override the name.

Example of adding a project to the application model.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject<Projects.InventoryService>(
    "inventoryservice",
    launchProfileName: "otherLaunchProfile");

builder.Build().Run();

AddProject(IDistributedApplicationBuilder, string, string, string?) extension IResourceBuilder<ProjectResource>

Adds a .NET project to the application model.

public static class ProjectResourceBuilderExtensions
{
    public static IResourceBuilder<ProjectResource> AddProject(
        this IDistributedApplicationBuilder builder,
        string name,
        string projectPath,
        string? launchProfileName)
    {
        // ...
    }
}

ProjectResourceBuilderExtensions.cs#L186-L194

Parameters

builder IDistributedApplicationBuilder The IDistributedApplicationBuilder.

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

projectPath string The path to the project file.

launchProfileName string? The launch profile to use. If null then no launch profile will be used.

Returns

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

Remarks

This overload of the ProjectResourceBuilderExtensions.AddProject method adds a project to the application model using a path to the project file. This allows for projects to be referenced that may not be part of the same solution. If the project path is not an absolute path then it will be computed relative to the app host directory.

Add a project to the app model via a project path.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject(
    "inventoryservice",
    @"..\InventoryService\InventoryService.csproj",
    launchProfileName: "otherLaunchProfile");

builder.Build().Run();

AddProject(IDistributedApplicationBuilder, string, Action<ProjectResourceOptions>) extension IResourceBuilder<ProjectResource>

Adds a .NET project to the application model.

public static class ProjectResourceBuilderExtensions
{
    public static IResourceBuilder<ProjectResource> AddProject<TProject>(
        this IDistributedApplicationBuilder builder,
        string name,
        Action<ProjectResourceOptions> configure)
    {
        // ...
    }
}

ProjectResourceBuilderExtensions.cs#L235-L245

Parameters

builder IDistributedApplicationBuilder The IDistributedApplicationBuilder.

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

configure Action<ProjectResourceOptions> A callback to configure the project resource options.

Returns

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

Remarks

This overload of the ProjectResourceBuilderExtensions.AddProject method takes a TProject type parameter. The TProject type parameter is constrained to types that implement the IProjectMetadata interface.

Classes that implement the IProjectMetadata interface are generated when a .NET project is added as a reference to the app host project. The generated class contains a property that returns the path to the referenced project file. Using this path .NET Aspire parses the launchSettings.json file to determine which launch profile to use when running the project, and what endpoint configuration to automatically generate.

The name of the automatically generated project metadata type is a normalized version of the project name. Periods, dashes, and spaces in project names are converted to underscores. This normalization may lead to naming conflicts. If a conflict occurs the <ProjectReference /> that references the project can have a AspireProjectMetadataTypeName="..." attribute added to override the name.

Example of adding a project to the application model.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject<Projects.InventoryService>(
    "inventoryservice",
    options => { options.LaunchProfileName = "otherLaunchProfile"; });

builder.Build().Run();

AddProject(IDistributedApplicationBuilder, string, string, Action<ProjectResourceOptions>) extension IResourceBuilder<ProjectResource>

Adds a .NET project to the application model.

public static class ProjectResourceBuilderExtensions
{
    public static IResourceBuilder<ProjectResource> AddProject(
        this IDistributedApplicationBuilder builder,
        string name,
        string projectPath,
        Action<ProjectResourceOptions> configure)
    {
        // ...
    }
}

ProjectResourceBuilderExtensions.cs#L275-L290

Parameters

builder IDistributedApplicationBuilder The IDistributedApplicationBuilder.

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

projectPath string The path to the project file or directory.

configure Action<ProjectResourceOptions> A callback to configure the project resource options.

Returns

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

Remarks

This overload of the ProjectResourceBuilderExtensions.AddProject method adds a project to the application model using a path to the project file or directory. This allows for projects to be referenced that may not be part of the same solution. If the project path is not an absolute path then it will be computed relative to the app host directory.

Add a project to the app model via a project path.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject(
    "inventoryservice",
    @"..\InventoryService\InventoryService.csproj",
    options => { options.LaunchProfileName = "otherLaunchProfile"; });

builder.Build().Run();

DisableForwardedHeaders(IResourceBuilder<ProjectResource>) extension IResourceBuilder<ProjectResource>

Configures the project to disable forwarded headers when being published.

public static class ProjectResourceBuilderExtensions
{
    public static IResourceBuilder<ProjectResource> DisableForwardedHeaders(
        this IResourceBuilder<ProjectResource> builder)
    {
        // ...
    }
}

ProjectResourceBuilderExtensions.cs#L770-L773

Parameters

builder IResourceBuilder<ProjectResource> The project resource builder.

Returns

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

Remarks

By default .NET Aspire assumes that .NET applications which expose endpoints should be configured to use forwarded headers. This is because most typical cloud native deployment scenarios involve a reverse proxy which translates an external endpoint hostname to an internal address.

To enable forwarded headers the ASPNETCORE_FORWARDEDHEADERS_ENABLED variable is injected into the project and set to true. If the ProjectResourceBuilderExtensions.DisableForwardedHeaders extension is used this environment variable will not be set.

Disable forwarded headers for a project.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject<Projects.InventoryService>("inventoryservice")
       .DisableForwardedHeaders();

PublishAsDockerFile(IResourceBuilder<T>, Action<IResourceBuilder<ContainerResource>>) extension IResourceBuilder<T>

Adds support for containerizing this ProjectResource during deployment. The resulting container image is built, and when the optional configure action is provided, it is used to configure the container resource.

public static class ProjectResourceBuilderExtensions
{
    public static IResourceBuilder<T> PublishAsDockerFile<T>(
        this IResourceBuilder<T> builder,
        Action<IResourceBuilder<ContainerResource>>? configure = null)
    {
        // ...
    }
}

ProjectResourceBuilderExtensions.cs#L811-L858

Parameters

builder IResourceBuilder<T> Resource builder

configure Action<IResourceBuilder<ContainerResource>> optional Optional action to configure the container resource

Returns

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

Remarks

When the executable resource is converted to a container resource, the arguments to the executable are not used. This is because arguments to the project often contain physical paths that are not valid in the container. The container can be set up with the correct arguments using the configure action.

WithEndpointsInEnvironment(IResourceBuilder<ProjectResource>, Func<EndpointAnnotation, bool>) extension IResourceBuilder<ProjectResource>

Set a filter that determines if environment variables are injected for a given endpoint. By default, all endpoints are included (if this method is not called).

public static class ProjectResourceBuilderExtensions
{
    public static IResourceBuilder<ProjectResource> WithEndpointsInEnvironment(
        this IResourceBuilder<ProjectResource> builder,
        Func<EndpointAnnotation, bool> filter)
    {
        // ...
    }
}

ProjectResourceBuilderExtensions.cs#L786-L791

Parameters

builder IResourceBuilder<ProjectResource> The project resource builder.

filter Func<EndpointAnnotation, bool> The filter callback that returns true if and only if the endpoint should be included.

Returns

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

WithReplicas(IResourceBuilder<ProjectResource>, int) extension IResourceBuilder<ProjectResource>

Configures how many replicas of the project should be created for the project.

public static class ProjectResourceBuilderExtensions
{
    public static IResourceBuilder<ProjectResource> WithReplicas(
        this IResourceBuilder<ProjectResource> builder,
        int replicas)
    {
        // ...
    }
}

ProjectResourceBuilderExtensions.cs#L736-L739

Parameters

builder IResourceBuilder<ProjectResource> The project resource builder.

replicas int The number of replicas.

Returns

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

Remarks

When this method is applied to a project resource it will configure the app host to start multiple instances of the application based on the specified number of replicas. By default the app host automatically starts a reverse proxy for each process. When ProjectResourceBuilderExtensions.WithReplicas is used the reverse proxy will load balance traffic between the replicas.

This capability can be useful when debugging scale out scenarios to ensure state is appropriately managed within a cluster of instances.

Start multiple instances of the same service.

var builder = DistributedApplication.CreateBuilder(args);

builder.AddProject<Projects.InventoryService>("inventoryservice")
       .WithReplicas(3);