ProjectResourceBuilderExtensions Methods
IDistributedApplicationBuilder to add and configure project resources. AddCSharpApp(IDistributedApplicationBuilder, string, string) Section titled AddCSharpApp(IDistributedApplicationBuilder, string, string)extensionIResourceBuilder<ProjectResource> public static class ProjectResourceBuilderExtensions{ public static IResourceBuilder<ProjectResource> AddCSharpApp( this IDistributedApplicationBuilder builder, string name, string path) { // ... }}Parameters
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<ProjectResource> A reference to the ApplicationModel.IResourceBuilder`1 .Remarks
This overload of the Project 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.
var builder = DistributedApplication.CreateBuilder(args);
builder.AddCSharpApp("inventoryservice", @"..\InventoryService.cs");
builder.Build().Run();AddCSharpApp(IDistributedApplicationBuilder, string, string, Action<ProjectResourceOptions>) Section titled AddCSharpApp(IDistributedApplicationBuilder, string, string, Action<ProjectResourceOptions>)extensionIResourceBuilder<CSharpAppResource> public static class ProjectResourceBuilderExtensions{ public static IResourceBuilder<CSharpAppResource> AddCSharpApp( this IDistributedApplicationBuilder builder, string name, string path, Action<ProjectResourceOptions> configure) { // ... }}Parameters
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<CSharpAppResource> A reference to the ApplicationModel.IResourceBuilder`1 .Remarks
This overload of the Project 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.
var builder = DistributedApplication.CreateBuilder(args);
builder.AddCSharpApp( "inventoryservice", @"..\InventoryService.cs", o => o.LaunchProfileName = "https");
builder.Build().Run();AddProject(IDistributedApplicationBuilder, string) Section titled AddProject(IDistributedApplicationBuilder, string)extensionIResourceBuilder<ProjectResource> public static class ProjectResourceBuilderExtensions{ public static IResourceBuilder<ProjectResource> AddProject<TProject>( this IDistributedApplicationBuilder builder, string name) { // ... }}Parameters
namestringThe 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 Project method takes a T type parameter. The T type parameter is constrained to types that implement the I interface.
Classes that implement the I interface are generated when a .NET project is added as a reference to the AppHost project. The generated class contains a property that returns the path to the referenced project file. Using this path Aspire parses the launch 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 <Project that references the project can have a Aspire 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 Endpoint.
var builder = DistributedApplication.CreateBuilder(args);
builder.AddProject<Projects.InventoryService>("inventoryservice");
builder.Build().Run();AddProject(IDistributedApplicationBuilder, string, string) Section titled AddProject(IDistributedApplicationBuilder, string, string)extensionIResourceBuilder<ProjectResource> public static class ProjectResourceBuilderExtensions{ public static IResourceBuilder<ProjectResource> AddProject( this IDistributedApplicationBuilder builder, string name, string projectPath) { // ... }}Parameters
namestringThe name of the resource. This name will be used for service discovery when referenced in a dependency.projectPath stringThe path to the project file.Returns
IResourceBuilder<ProjectResource> A reference to the ApplicationModel.IResourceBuilder`1 .Remarks
This overload of the Project 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 AppHost directory.
var builder = DistributedApplication.CreateBuilder(args);
builder.AddProject( "inventoryservice", @"..\InventoryService\InventoryService.csproj");
builder.Build().Run();AddProject(IDistributedApplicationBuilder, string, string?) Section titled AddProject(IDistributedApplicationBuilder, string, string?)extensionIResourceBuilder<ProjectResource> public static class ProjectResourceBuilderExtensions{ public static IResourceBuilder<ProjectResource> AddProject<TProject>( this IDistributedApplicationBuilder builder, string name, string? launchProfileName) { // ... }}Parameters
namestringThe 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 Project method takes a T type parameter. The T type parameter is constrained to types that implement the I interface.
Classes that implement the I interface are generated when a .NET project is added as a reference to the AppHost project. The generated class contains a property that returns the path to the referenced project file. Using this path Aspire parses the launch 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 <Project that references the project can have a Aspire attribute added to override the name.
var builder = DistributedApplication.CreateBuilder(args);
builder.AddProject<Projects.InventoryService>( "inventoryservice", launchProfileName: "otherLaunchProfile");
builder.Build().Run();AddProject(IDistributedApplicationBuilder, string, string, string?) Section titled AddProject(IDistributedApplicationBuilder, string, string, string?)extensionIResourceBuilder<ProjectResource> public static class ProjectResourceBuilderExtensions{ public static IResourceBuilder<ProjectResource> AddProject( this IDistributedApplicationBuilder builder, string name, string projectPath, string? launchProfileName) { // ... }}Parameters
namestringThe name of the resource. This name will be used for service discovery when referenced in a dependency.projectPath stringThe 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 Project 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 AppHost directory.
var builder = DistributedApplication.CreateBuilder(args);
builder.AddProject( "inventoryservice", @"..\InventoryService\InventoryService.csproj", launchProfileName: "otherLaunchProfile");
builder.Build().Run();AddProject(IDistributedApplicationBuilder, string, Action<ProjectResourceOptions>) Section titled AddProject(IDistributedApplicationBuilder, string, Action<ProjectResourceOptions>)extensionIResourceBuilder<ProjectResource> public static class ProjectResourceBuilderExtensions{ public static IResourceBuilder<ProjectResource> AddProject<TProject>( this IDistributedApplicationBuilder builder, string name, Action<ProjectResourceOptions> configure) { // ... }}Parameters
namestringThe name of the resource. This name will be used for service discovery when referenced in a dependency.configureAction<ProjectResourceOptions> A callback to configure the project resource options.Returns
IResourceBuilder<ProjectResource> A reference to the ApplicationModel.IResourceBuilder`1 .Remarks
This overload of the Project method takes a T type parameter. The T type parameter is constrained to types that implement the I interface.
Classes that implement the I interface are generated when a .NET project is added as a reference to the AppHost project. The generated class contains a property that returns the path to the referenced project file. Using this path Aspire parses the launch 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 <Project that references the project can have a Aspire attribute added to override the name.
var builder = DistributedApplication.CreateBuilder(args);
builder.AddProject<Projects.InventoryService>( "inventoryservice", options => { options.LaunchProfileName = "otherLaunchProfile"; });
builder.Build().Run();AddProject(IDistributedApplicationBuilder, string, string, Action<ProjectResourceOptions>) Section titled AddProject(IDistributedApplicationBuilder, string, string, Action<ProjectResourceOptions>)extensionIResourceBuilder<ProjectResource> public static class ProjectResourceBuilderExtensions{ public static IResourceBuilder<ProjectResource> AddProject( this IDistributedApplicationBuilder builder, string name, string projectPath, Action<ProjectResourceOptions> configure) { // ... }}Parameters
namestringThe name of the resource. This name will be used for service discovery when referenced in a dependency.projectPath stringThe path to the project file or directory.configureAction<ProjectResourceOptions> A callback to configure the project resource options.Returns
IResourceBuilder<ProjectResource> A reference to the ApplicationModel.IResourceBuilder`1 .Remarks
This overload of the Project 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 AppHost directory.
var builder = DistributedApplication.CreateBuilder(args);
builder.AddProject( "inventoryservice", @"..\InventoryService\InventoryService.csproj", options => { options.LaunchProfileName = "otherLaunchProfile"; });
builder.Build().Run();DisableForwardedHeaders(IResourceBuilder<ProjectResource>) Section titled DisableForwardedHeaders(IResourceBuilder<ProjectResource>)extensionIResourceBuilder<ProjectResource> public static class ProjectResourceBuilderExtensions{ public static IResourceBuilder<ProjectResource> DisableForwardedHeaders( this IResourceBuilder<ProjectResource> builder) { // ... }}Parameters
builderIResourceBuilder<ProjectResource> The project resource builder.Returns
IResourceBuilder<ProjectResource> A reference to the ApplicationModel.IResourceBuilder`1 .Remarks
By default 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_ variable is injected into the project and set to true. If the Project extension is used this environment variable will not be set.
var builder = DistributedApplication.CreateBuilder(args);
builder.AddProject<Projects.InventoryService>("inventoryservice") .DisableForwardedHeaders();PublishAsDockerFile(IResourceBuilder<T>, Action<IResourceBuilder<ContainerResource>>) Section titled PublishAsDockerFile(IResourceBuilder<T>, Action<IResourceBuilder<ContainerResource>>)extensionIProjectResource 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) { // ... }}Parameters
builderIconfigureAction<IResourceBuilder<ContainerResource>> optionalOptional action to configure the container resourceReturns
IResourceBuilder<T> A reference to the ApplicationModel.IResourceBuilder`1 .Remarks
configure action. WithEndpointsInEnvironment(IResourceBuilder<ProjectResource>, Func<EndpointAnnotation, bool>) Section titled WithEndpointsInEnvironment(IResourceBuilder<ProjectResource>, Func<EndpointAnnotation, bool>)extensionIResourceBuilder<ProjectResource> public static class ProjectResourceBuilderExtensions{ public static IResourceBuilder<ProjectResource> WithEndpointsInEnvironment( this IResourceBuilder<ProjectResource> builder, Func<EndpointAnnotation, bool> filter) { // ... }}Parameters
builderIResourceBuilder<ProjectResource> The project resource builder.filterFunc<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 .WithProjectDefaults(IResourceBuilder<TProjectResource>, ProjectResourceOptions) Section titled WithProjectDefaults(IResourceBuilder<TProjectResource>, ProjectResourceOptions)extensionIResourceBuilder<TProjectResource> public static class ProjectResourceBuilderExtensions{ public static IResourceBuilder<TProjectResource> WithProjectDefaults<TProjectResource>( this IResourceBuilder<TProjectResource> builder, ProjectResourceOptions options) { // ... }}Parameters
builderIResourceBuilder<TProjectResource> The resource builder.optionsProjectReturns
IResourceBuilder<TProjectResource> The resource builder.Exceptions
InvalidOperationExceptionThe resource does not carry exactly one IProjectMetadata annotation, project metadata changes after defaults are applied, or defaults were already applied.Remarks
This is the wiring shared by every .NET-launched resource: OpenTelemetry exporter configuration, launch profile selection and materialization, endpoints derived from launch profile and Kestrel configuration, ASPNETCORE_ / HTTP_ / HTTPS_ and Kestrel_ environment overrides, and (in run mode) the hidden rebuilder resource behind the Rebuild command.
For TLS-enabled endpoints, an available HTTPS certificate is mapped to Kestrel's default certificate unless the resource environment already contains Kestrel_, Kestrel_, or Kestrel_. These names are matched case-insensitively. The presence of any of them preserves the existing certificate configuration, including its password. Settings supplied by earlier HTTPS certificate callbacks participate in this check.
A password alone does not suppress the default PFX configuration. It is replaced by the selected certificate's password, or removed when that certificate has no password. Certificate settings loaded separately by the resource application, such as from appsettings., are not checked.
The resource must carry I. It is intended for language integration packages that add their own .NET resource type, such as Aspire.; use Project for ordinary projects.
The project metadata annotation must not be added, removed, or replaced after this method returns. Aspire validates this before the distributed application starts or publishes.
WithReplicas(IResourceBuilder<ProjectResource>, int) Section titled WithReplicas(IResourceBuilder<ProjectResource>, int)extensionIResourceBuilder<ProjectResource> public static class ProjectResourceBuilderExtensions{ public static IResourceBuilder<ProjectResource> WithReplicas( this IResourceBuilder<ProjectResource> builder, int replicas) { // ... }}Parameters
builderIResourceBuilder<ProjectResource> The project resource builder.replicasintThe 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 AppHost to start multiple instances of the application based on the specified number of replicas. By default the AppHost automatically starts a reverse proxy for each process. When Project 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);
Aspire