diff --git a/docs/app-host/configuration.md b/docs/app-host/configuration.md index 9bf94c2172..d160a7fbb6 100644 --- a/docs/app-host/configuration.md +++ b/docs/app-host/configuration.md @@ -1,21 +1,21 @@ --- -title: .NET Aspire app host configuration -description: Learn about the .NET Aspire app host configuration options. +title: .NET Aspire AppHost configuration +description: Learn about the .NET Aspire AppHost configuration options. ms.date: 04/15/2025 ms.topic: reference --- -# App host configuration +# AppHost configuration -The app host project configures and starts your distributed application (). When a `DistributedApplication` runs it reads configuration from the app host. Configuration is loaded from environment variables that are set on the app host and . +The AppHost project configures and starts your distributed application (). When a `DistributedApplication` runs it reads configuration from the AppHost. Configuration is loaded from environment variables that are set on the AppHost and . Configuration includes: - Settings for hosting the resource service, such as the address and authentication options. - Settings used to start the [.NET Aspire dashboard](../fundamentals/dashboard/overview.md), such the dashboard's frontend and OpenTelemetry Protocol (OTLP) addresses. -- Internal settings that .NET Aspire uses to run the app host. These are set internally but can be accessed by integrations that extend .NET Aspire. +- Internal settings that .NET Aspire uses to run the AppHost. These are set internally but can be accessed by integrations that extend .NET Aspire. -App host configuration is provided by the app host launch profile. The app host has a launch settings file call _launchSettings.json_ which has a list of launch profiles. Each launch profile is a collection of related options which defines how you would like `dotnet` to start your application. +AppHost configuration is provided by the AppHost launch profile. The AppHost has a launch settings file call _launchSettings.json_ which has a list of launch profiles. Each launch profile is a collection of related options which defines how you would like `dotnet` to start your application. ```json { @@ -40,35 +40,35 @@ App host configuration is provided by the app host launch profile. The app host The preceding launch settings file: - Has one launch profile named `https`. -- Configures an .NET Aspire app host project: +- Configures an .NET Aspire AppHost project: - The `applicationUrl` property configures the dashboard launch address (`ASPNETCORE_URLS`). - - Environment variables such as `ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL` and `ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL` are set on the app host. + - Environment variables such as `ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL` and `ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL` are set on the AppHost. For more information, see [.NET Aspire and launch profiles](../fundamentals/launch-profiles.md). > [!NOTE] -> Configuration described on this page is for .NET Aspire app host project. To configure the standalone dashboard, see [dashboard configuration](../fundamentals/dashboard/configuration.md). +> Configuration described on this page is for .NET Aspire AppHost project. To configure the standalone dashboard, see [dashboard configuration](../fundamentals/dashboard/configuration.md). ## Common configuration | Option | Default value | Description | |--|--|--| -| `ASPIRE_ALLOW_UNSECURED_TRANSPORT` | `false` | Allows communication with the app host without https. `ASPNETCORE_URLS` (dashboard address) and `ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL` (app host resource service address) must be secured with HTTPS unless true. | +| `ASPIRE_ALLOW_UNSECURED_TRANSPORT` | `false` | Allows communication with the AppHost without https. `ASPNETCORE_URLS` (dashboard address) and `ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL` (AppHost resource service address) must be secured with HTTPS unless true. | | `ASPIRE_CONTAINER_RUNTIME` | `docker` | Allows the user of alternative container runtimes for resources backed by containers. Possible values are `docker` (default) or `podman`. See [Setup and tooling overview for more details](../fundamentals/setup-tooling.md). | | `ASPIRE_VERSION_CHECK_DISABLED` | `false` | When set to `true`, .NET Aspire doesn't check for newer versions on startup. | ## Resource service -A resource service is hosted by the app host. The resource service is used by the dashboard to fetch information about resources which are being orchestrated by .NET Aspire. +A resource service is hosted by the AppHost. The resource service is used by the dashboard to fetch information about resources which are being orchestrated by .NET Aspire. | Option | Default value | Description | |--|--|--| -| `ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL` | `null` | Configures the address of the resource service hosted by the app host. Automatically generated with _launchSettings.json_ to have a random port on localhost. For example, `https://localhost:17037`. | -| `ASPIRE_DASHBOARD_RESOURCESERVICE_APIKEY` | Automatically generated 128-bit entropy token. | The API key used to authenticate requests made to the app host's resource service. The API key is required if the app host is in run mode, the dashboard isn't disabled, and the dashboard isn't configured to allow anonymous access with `ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS`. | +| `ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL` | `null` | Configures the address of the resource service hosted by the AppHost. Automatically generated with _launchSettings.json_ to have a random port on localhost. For example, `https://localhost:17037`. | +| `ASPIRE_DASHBOARD_RESOURCESERVICE_APIKEY` | Automatically generated 128-bit entropy token. | The API key used to authenticate requests made to the AppHost's resource service. The API key is required if the AppHost is in run mode, the dashboard isn't disabled, and the dashboard isn't configured to allow anonymous access with `ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS`. | ## Dashboard -By default, the dashboard is automatically started by the app host. The dashboard supports [its own set of configuration](../fundamentals/dashboard/configuration.md), and some settings can be configured from the app host. +By default, the dashboard is automatically started by the AppHost. The dashboard supports [its own set of configuration](../fundamentals/dashboard/configuration.md), and some settings can be configured from the AppHost. | Option | Default value | Description | |--|--|--| @@ -77,20 +77,20 @@ By default, the dashboard is automatically started by the app host. The dashboar | `ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL` | `http://localhost:18889` if no gRPC endpoint is configured. | Configures the dashboard OTLP gRPC address. Used by the dashboard to receive telemetry over OTLP. Set on resources as the `OTEL_EXPORTER_OTLP_ENDPOINT` env var. The `OTEL_EXPORTER_OTLP_PROTOCOL` env var is `grpc`. Automatically generated with _launchSettings.json_ to have a random port on localhost. | | `ASPIRE_DASHBOARD_OTLP_HTTP_ENDPOINT_URL` | `null` | Configures the dashboard OTLP HTTP address. Used by the dashboard to receive telemetry over OTLP. If only `ASPIRE_DASHBOARD_OTLP_HTTP_ENDPOINT_URL` is configured then it is set on resources as the `OTEL_EXPORTER_OTLP_ENDPOINT` env var. The `OTEL_EXPORTER_OTLP_PROTOCOL` env var is `http/protobuf`. | | `ASPIRE_DASHBOARD_CORS_ALLOWED_ORIGINS` | `null` | Overrides the CORS allowed origins configured in the dashboard. This setting replaces the default behavior of calculating allowed origins based on resource endpoints. | -| `ASPIRE_DASHBOARD_FRONTEND_BROWSERTOKEN` | Automatically generated 128-bit entropy token. | Configures the frontend browser token. This is the value that must be entered to access the dashboard when the auth mode is BrowserToken. If no browser token is specified then a new token is generated each time the app host is launched. | +| `ASPIRE_DASHBOARD_FRONTEND_BROWSERTOKEN` | Automatically generated 128-bit entropy token. | Configures the frontend browser token. This is the value that must be entered to access the dashboard when the auth mode is BrowserToken. If no browser token is specified then a new token is generated each time the AppHost is launched. | | `ASPIRE_DASHBOARD_TELEMETRY_OPTOUT` | `false` | Configures the dashboard to never send [usage telemetry](../fundamentals/dashboard/microsoft-collected-dashboard-telemetry.md). | -| `ASPIRE_DASHBOARD_AI_DISABLED` | `false` | [GitHub Copilot in the dashboard](../fundamentals/dashboard/copilot.md) is available when the app host is launched by a supported IDE. When set to `true` Copilot is disabled in the dashboard and no Copilot UI is visible. | +| `ASPIRE_DASHBOARD_AI_DISABLED` | `false` | [GitHub Copilot in the dashboard](../fundamentals/dashboard/copilot.md) is available when the AppHost is launched by a supported IDE. When set to `true` Copilot is disabled in the dashboard and no Copilot UI is visible. | ## Internal -Internal settings are used by the app host and integrations. Internal settings aren't designed to be configured directly. +Internal settings are used by the AppHost and integrations. Internal settings aren't designed to be configured directly. | Option | Default value | Description | |--|--|--| -| `AppHost:Directory` | The content root if there's no project. | Directory of the project where the app host is located. Accessible from the . | -| `AppHost:Path` | The directory combined with the application name. | The path to the app host. It combines the directory with the application name. | -| `AppHost:Sha256` | It is created from the app host name when the app host is in publish mode. Otherwise it is created from the app host path. | Hex encoded hash for the current application. The hash is based on the location of the app on the current machine so it is stable between launches of the app host. | -| `AppHost:OtlpApiKey` | Automatically generated 128-bit entropy token. | The API key used to authenticate requests sent to the dashboard OTLP service. The value is present if needed: the app host is in run mode, the dashboard isn't disabled, and the dashboard isn't configured to allow anonymous access with `ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS`. | -| `AppHost:BrowserToken` | Automatically generated 128-bit entropy token. | The browser token used to authenticate browsing to the dashboard when it is launched by the app host. The browser token can be set by `ASPIRE_DASHBOARD_FRONTEND_BROWSERTOKEN`. The value is present if needed: the app host is in run mode, the dashboard isn't disabled, and the dashboard isn't configured to allow anonymous access with `ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS`. | -| `AppHost:ResourceService:AuthMode` | `ApiKey`. If `ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS` is true then the value is `Unsecured`. | The authentication mode used to access the resource service. The value is present if needed: the app host is in run mode and the dashboard isn't disabled. | -| `AppHost:ResourceService:ApiKey` | Automatically generated 128-bit entropy token. | The API key used to authenticate requests made to the app host's resource service. The API key can be set by `ASPIRE_DASHBOARD_RESOURCESERVICE_APIKEY`. The value is present if needed: the app host is in run mode, the dashboard isn't disabled, and the dashboard isn't configured to allow anonymous access with `ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS`. | +| `AppHost:Directory` | The content root if there's no project. | Directory of the project where the AppHost is located. Accessible from the . | +| `AppHost:Path` | The directory combined with the application name. | The path to the AppHost. It combines the directory with the application name. | +| `AppHost:Sha256` | It is created from the AppHost name when the AppHost is in publish mode. Otherwise it is created from the AppHost path. | Hex encoded hash for the current application. The hash is based on the location of the app on the current machine so it is stable between launches of the AppHost. | +| `AppHost:OtlpApiKey` | Automatically generated 128-bit entropy token. | The API key used to authenticate requests sent to the dashboard OTLP service. The value is present if needed: the AppHost is in run mode, the dashboard isn't disabled, and the dashboard isn't configured to allow anonymous access with `ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS`. | +| `AppHost:BrowserToken` | Automatically generated 128-bit entropy token. | The browser token used to authenticate browsing to the dashboard when it is launched by the AppHost. The browser token can be set by `ASPIRE_DASHBOARD_FRONTEND_BROWSERTOKEN`. The value is present if needed: the AppHost is in run mode, the dashboard isn't disabled, and the dashboard isn't configured to allow anonymous access with `ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS`. | +| `AppHost:ResourceService:AuthMode` | `ApiKey`. If `ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS` is true then the value is `Unsecured`. | The authentication mode used to access the resource service. The value is present if needed: the AppHost is in run mode and the dashboard isn't disabled. | +| `AppHost:ResourceService:ApiKey` | Automatically generated 128-bit entropy token. | The API key used to authenticate requests made to the AppHost's resource service. The API key can be set by `ASPIRE_DASHBOARD_RESOURCESERVICE_APIKEY`. The value is present if needed: the AppHost is in run mode, the dashboard isn't disabled, and the dashboard isn't configured to allow anonymous access with `ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS`. | diff --git a/docs/app-host/eventing.md b/docs/app-host/eventing.md index 8d5f39a0fc..92a6abe968 100644 --- a/docs/app-host/eventing.md +++ b/docs/app-host/eventing.md @@ -1,45 +1,45 @@ --- title: Eventing in .NET Aspire description: Learn how to use the .NET eventing features with .NET Aspire. -ms.date: 07/10/2025 +ms.date: 08/07/2025 ms.custom: sfi-ropc-nochange --- # Eventing in .NET Aspire -In .NET Aspire, eventing allows you to publish and subscribe to events during various [app host life cycles](xref:dotnet/aspire/app-host#app-host-life-cycles). Eventing is more flexible than life cycle events. Both let you run arbitrary code during event callbacks, but eventing offers finer control of event timing, publishing, and provides supports for custom events. +In .NET Aspire, eventing allows you to publish and subscribe to events during various [AppHost life cycles](xref:dotnet/aspire/app-host#apphost-life-cycles). Eventing is more flexible than life cycle events. Both let you run arbitrary code during event callbacks, but eventing offers finer control of event timing, publishing, and provides supports for custom events. -The eventing mechanisms in .NET Aspire are part of the [📦 Aspire.Hosting](https://www.nuget.org/packages/Aspire.Hosting) NuGet package. This package provides a set of interfaces and classes in the namespace that you use to publish and subscribe to events in your .NET Aspire app host project. Eventing is scoped to the app host itself and the resources within. +The eventing mechanisms in .NET Aspire are part of the [📦 Aspire.Hosting](https://www.nuget.org/packages/Aspire.Hosting) NuGet package. This package provides a set of interfaces and classes in the namespace that you use to publish and subscribe to events in your .NET Aspire AppHost project. Eventing is scoped to the AppHost itself and the resources within. In this article, you learn how to use the eventing features in .NET Aspire. -## App host eventing +## AppHost eventing -The following events are available in the app host and occur in the following order: +The following events are available in the AppHost and occur in the following order: -1. : This event is raised before the app host starts. +1. : This event is raised before the AppHost starts. 1. : This event is raised per resource after its endpoints are allocated. -1. : This event is raised after the app host created resources. +1. : This event is raised after the AppHost created resources. -All of the preceding events are analogous to the [app host life cycles](xref:dotnet/aspire/app-host#app-host-life-cycles). That is, an implementation of the could handle these events just the same. With the eventing API, however, you can run arbitrary code when these events are raised and event define custom events—any event that implements the interface. +All of the preceding events are analogous to the [AppHost life cycles](xref:dotnet/aspire/app-host#apphost-life-cycles). That is, an implementation of the could handle these events just the same. With the eventing API, however, you can run arbitrary code when these events are raised and event define custom events—any event that implements the interface. -### Subscribe to app host events +### Subscribe to AppHost events -To subscribe to the built-in app host events, use the eventing API. After you have a distributed application builder instance, walk up to the property and call the API. Consider the following sample app host _AppHost.cs_ file: +To subscribe to the built-in AppHost events, use the eventing API. After you have a distributed application builder instance, walk up to the property and call the API. Consider the following sample AppHost _AppHost.cs_ file: :::code source="snippets/AspireApp/AspireApp.AppHost/AppHost.cs"::: -The preceding code is based on the starter template with the addition of the calls to the `Subscribe` API. The `Subscribe` API returns a instance that you can use to unsubscribe from the event. It's common to discard the returned subscriptions, as you don't usually need to unsubscribe from events as the entire app is torn down when the app host is shut down. +The preceding code is based on the starter template with the addition of the calls to the `Subscribe` API. The `Subscribe` API returns a instance that you can use to unsubscribe from the event. It's common to discard the returned subscriptions, as you don't usually need to unsubscribe from events as the entire app is torn down when the AppHost is shut down. -When the app host is run, by the time the .NET Aspire dashboard is displayed, you should see the following log output in the console: +When the AppHost is run, by the time the .NET Aspire dashboard is displayed, you should see the following log output in the console: :::code language="Plaintext" source="snippets/AspireApp/AspireApp.AppHost/Console.txt" highlight="2,10,12,14,16,22"::: -The log output confirms that event handlers are executed in the order of the app host life cycle events. The subscription order doesn't affect execution order. The `BeforeStartEvent` is triggered first, followed by each resource's `ResourceEndpointsAllocatedEvent`, and finally `AfterResourcesCreatedEvent`. +The log output confirms that event handlers are executed in the order of the AppHost life cycle events. The subscription order doesn't affect execution order. The `BeforeStartEvent` is triggered first, followed by each resource's `ResourceEndpointsAllocatedEvent`, and finally `AfterResourcesCreatedEvent`. ## Resource eventing -In addition to the app host events, you can also subscribe to resource events. Resource events are raised specific to an individual resource. Resource events are defined as implementations of the interface. The following resource events are available in the listed order: +In addition to the AppHost events, you can also subscribe to resource events. Resource events are raised specific to an individual resource. Resource events are defined as implementations of the interface. The following resource events are available in the listed order: 1. : Raised by orchestrators to signal to resources that they should initialize themselves. 1. : Raised when the orchestrator allocates endpoints for a resource. @@ -61,7 +61,7 @@ The preceding code subscribes to the `InitializeResourceEvent`, `ResourceReadyEv - `OnBeforeResourceStarted`: Subscribes to the event. - `OnResourceReady`: Subscribes to the event. -When the app host is run, by the time the .NET Aspire dashboard is displayed, you should see the following log output in the console: +When the AppHost is run, by the time the .NET Aspire dashboard is displayed, you should see the following log output in the console: :::code language="Plaintext" source="snippets/AspireApp/AspireApp.ResourceAppHost/Console.txt" highlight="8,10,12,14,20"::: @@ -70,7 +70,7 @@ When the app host is run, by the time the .NET Aspire dashboard is displayed, yo ## Publish events -When subscribing to any of the built-in events, you don't need to publish the event yourself as the app host orchestrator manages to publish built-in events on your behalf. However, you can publish custom events with the eventing API. To publish an event, you have to first define an event as an implementation of either the or interface. You need to determine which interface to implement based on whether the event is a global app host event or a resource-specific event. +When subscribing to any of the built-in events, you don't need to publish the event yourself as the AppHost orchestrator manages to publish built-in events on your behalf. However, you can publish custom events with the eventing API. To publish an event, you have to first define an event as an implementation of either the or interface. You need to determine which interface to implement based on whether the event is a global AppHost event or a resource-specific event. Then, you can subscribe and publish the event by calling the either of the following APIs: @@ -88,11 +88,11 @@ When events are dispatched, you can control how the events are dispatched to sub The default behavior is `EventDispatchBehavior.BlockingSequential`. To override this behavior, when calling a publishing API such as , provide the desired behavior as an argument. -## App Host life cycle events +## AppHost life cycle events Eventing offers the most flexibility. However, this section explains the alternative: life cycle events. -The .NET Aspire app host exposes several life cycles that you can hook into by implementing the interface. The following lifecycle methods are available: +The .NET Aspire AppHost exposes several life cycles that you can hook into by implementing the interface. The following lifecycle methods are available: | Order | Method | Description | |--|--|--| @@ -102,21 +102,21 @@ The .NET Aspire app host exposes several life cycles that you can hook into by i ### Register a life cycle hook -To register a life cycle hook, implement the interface and register the hook with the app host using the API: +To register a life cycle hook, implement the interface and register the hook with the AppHost using the API: :::code source="../fundamentals/snippets/lifecycles/AspireApp/AspireApp.AppHost/AppHost.cs"::: The preceding code: - Implements the interface as a `LifecycleLogger`. -- Registers the life cycle hook with the app host using the API. +- Registers the life cycle hook with the AppHost using the API. - Logs a message for all the events. -When this app host is run, the life cycle hook is executed for each event. The following output is generated: +When this AppHost is run, the life cycle hook is executed for each event. The following output is generated: :::code language="Plaintext" source="../fundamentals/snippets/lifecycles/AspireApp/AspireApp.AppHost/Console.txt" highlight="2,10,16"::: -The preferred way to hook into the app host life cycle is to use the eventing API. For more information, see [App host eventing](#app-host-eventing). +The preferred way to hook into the AppHost life cycle is to use the eventing API. For more information, see [AppHost eventing](#apphost-eventing). ## See also diff --git a/docs/app-host/persistent-containers.md b/docs/app-host/persistent-containers.md index 25b9d9f706..9772993e29 100644 --- a/docs/app-host/persistent-containers.md +++ b/docs/app-host/persistent-containers.md @@ -1,14 +1,14 @@ --- title: Persistent container lifetimes in .NET Aspire -description: Learn how to configure containers to persist and be re-used between .NET Aspire app host runs. +description: Learn how to configure containers to persist and be re-used between .NET Aspire AppHost runs. ms.date: 07/15/2025 --- # Persistent container lifetimes in .NET Aspire -In .NET Aspire, containers follow a typical lifecycle where they're created when the app host starts and destroyed when it stops. However, you can specify that you want to use **persistent containers**, which deviate from this standard lifecycle. Persistent containers are created and started by the .NET Aspire orchestrator but aren't destroyed when the app host stops, allowing them to persist between runs. +In .NET Aspire, containers follow a typical lifecycle where they're created when the AppHost starts and destroyed when it stops. However, you can specify that you want to use **persistent containers**, which deviate from this standard lifecycle. Persistent containers are created and started by the .NET Aspire orchestrator but aren't destroyed when the AppHost stops, allowing them to persist between runs. -This feature is particularly beneficial for containers that have long startup times, such as databases, as it eliminates the need to wait for these services to initialize on every app host restart. +This feature is particularly beneficial for containers that have long startup times, such as databases, as it eliminates the need to wait for these services to initialize on every AppHost restart. ## Configure a persistent container @@ -28,7 +28,7 @@ builder.AddProject("inventory") builder.Build().Run(); ``` -In the preceding example, the PostgreSQL container is configured to persist between app host runs, while the `inventory` project references the database as normal. +In the preceding example, the PostgreSQL container is configured to persist between AppHost runs, while the `inventory` project references the database as normal. ## Dashboard visualization @@ -36,26 +36,26 @@ The .NET Aspire dashboard shows persistent containers with a distinctive pin ico :::image type="content" source="../whats-new/media/persistent-container.png" lightbox="../whats-new/media/persistent-container.png" alt-text="Screenshot of the .NET Aspire dashboard showing a persistent container with a pin icon."::: -After the app host stops, persistent containers continue running and can be seen in your container runtime (such as Docker Desktop): +After the AppHost stops, persistent containers continue running and can be seen in your container runtime (such as Docker Desktop): -:::image type="content" source="../whats-new/media/persistent-container-docker-desktop.png" lightbox="../whats-new/media/persistent-container-docker-desktop.png" alt-text="Screenshot of Docker Desktop showing a persistent RabbitMQ container still running after the app host stopped."::: +:::image type="content" source="../whats-new/media/persistent-container-docker-desktop.png" lightbox="../whats-new/media/persistent-container-docker-desktop.png" alt-text="Screenshot of Docker Desktop showing a persistent RabbitMQ container still running after the AppHost stopped."::: ## Configuration change detection -Persistent containers are automatically recreated when the app host detects meaningful configuration changes. .NET Aspire tracks a hash of the configuration used to create each container and compares it to the current configuration on subsequent runs. If the configuration differs, the container is recreated with the new settings. +Persistent containers are automatically recreated when the AppHost detects meaningful configuration changes. .NET Aspire tracks a hash of the configuration used to create each container and compares it to the current configuration on subsequent runs. If the configuration differs, the container is recreated with the new settings. -This mechanism ensures that persistent containers stay synchronized with your app host configuration without requiring manual intervention. +This mechanism ensures that persistent containers stay synchronized with your AppHost configuration without requiring manual intervention. ## Container naming and uniqueness By default, persistent containers use a naming pattern that combines: -- The service name you specify in your app host. -- A postfix based on a hash of the app host project path. +- The service name you specify in your AppHost. +- A postfix based on a hash of the AppHost project path. -This naming scheme ensures that persistent containers are unique to each app host project, preventing conflicts when multiple .NET Aspire projects use the same service names. +This naming scheme ensures that persistent containers are unique to each AppHost project, preventing conflicts when multiple .NET Aspire projects use the same service names. -For example, if you have a service named `"postgres"` in an app host project located at `/path/to/MyApp.AppHost`, the container name might be `postgres-abc123def` where `abc123def` is derived from the project path hash. +For example, if you have a service named `"postgres"` in an AppHost project located at `/path/to/MyApp.AppHost`, the container name might be `postgres-abc123def` where `abc123def` is derived from the project path hash. ### Custom container names @@ -71,12 +71,12 @@ var postgres = builder.AddPostgres("postgres") builder.Build().Run(); ``` -When you specify a custom container name, .NET Aspire first checks if a container with that name already exists. If a container with that name exists and was previously created by .NET Aspire, it follows the normal persistent container behavior and can be automatically recreated if the configuration changes. If a container with that name exists but wasn't created by .NET Aspire, it won't be managed or recreated by the app host. If no container with the custom name exists, .NET Aspire creates a new one. +When you specify a custom container name, .NET Aspire first checks if a container with that name already exists. If a container with that name exists and was previously created by .NET Aspire, it follows the normal persistent container behavior and can be automatically recreated if the configuration changes. If a container with that name exists but wasn't created by .NET Aspire, it won't be managed or recreated by the AppHost. If no container with the custom name exists, .NET Aspire creates a new one. ## Manual cleanup > [!IMPORTANT] -> Persistent containers aren't automatically removed when you stop the app host. To delete these containers, you must manually stop and remove them using your container runtime. +> Persistent containers aren't automatically removed when you stop the AppHost. To delete these containers, you must manually stop and remove them using your container runtime. You can clean up persistent containers using Docker CLI commands: @@ -97,10 +97,10 @@ Persistent containers are ideal for: - **Database services**: PostgreSQL, SQL Server, MySQL, and other databases that take time to initialize and load data. - **Message brokers**: RabbitMQ, Redis, and similar services that benefit from maintaining state between runs. - **Development data**: Containers with test data or configurations that you want to preserve during development iterations. -- **Shared services**: Services that multiple app hosts or development team members can share. +- **Shared services**: Services that multiple AppHosts or development team members can share. ## See also - [Orchestrate resources in .NET Aspire](../fundamentals/orchestrate-resources.md) -- [.NET Aspire app host overview](../fundamentals/app-host-overview.md) +- [.NET Aspire AppHost overview](../fundamentals/app-host-overview.md) - [What's new in .NET Aspire 9.0](../whats-new/dotnet-aspire-9.md#persistent-containers) diff --git a/docs/app-host/withdockerfile.md b/docs/app-host/withdockerfile.md index 5339ad33fd..dbfd122ece 100644 --- a/docs/app-host/withdockerfile.md +++ b/docs/app-host/withdockerfile.md @@ -6,7 +6,7 @@ ms.date: 07/23/2024 # Add Dockerfiles to your .NET app model -With .NET Aspire it's possible to specify a _Dockerfile_ to build when the [app host](../fundamentals/app-host-overview.md) is started using either the or extension methods. +With .NET Aspire it's possible to specify a _Dockerfile_ to build when the [AppHost](../fundamentals/app-host-overview.md) is started using either the or extension methods. These two methods serve different purposes: @@ -43,11 +43,11 @@ var container = builder.AddDockerfile( "mycontainer", "relative/context/path"); ``` -Unless the context path argument is a rooted path the context path is interpreted as being relative to the app host projects directory (where the AppHost `*.csproj` folder is located). +Unless the context path argument is a rooted path the context path is interpreted as being relative to the AppHost projects directory (where the AppHost `*.csproj` folder is located). By default the name of the _Dockerfile_ which is used is `Dockerfile` and is expected to be within the context path directory. It's possible to explicitly specify the _Dockerfile_ name either as an absolute path or a relative path to the context path. -This is useful if you wish to modify the specific _Dockerfile_ being used when running locally or when the app host is deploying. +This is useful if you wish to modify the specific _Dockerfile_ being used when running locally or when the AppHost is deploying. ```csharp var builder = DistributedApplication.CreateBuilder(args); diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index b813b952d8..d1414dff6b 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -39,7 +39,7 @@ Most importantly, the translation process itself is highly extensible. You can d .NET Aspire operates in two primary modes, each tailored to streamline your specific needs—detailed in the following section. Both modes use a robust set of familiar APIs and a rich ecosystem of [integrations](../fundamentals/integrations-overview.md). Each integration simplifies working with a common service, framework, or platform, such as Redis, PostgreSQL, Azure services, or Orleans, for example. These integrations work together like puzzle pieces, enabling you to define resources, express dependencies, and configure behavior effortlessly—whether you're running locally or deploying to production. -Why is modality important when it comes to the app host's execution context? This is because it allows you to define your app model once and with the appropriate APIs, specify how resources operate in each mode. Consider the following collection of resources: +Why is modality important when it comes to the AppHost's execution context? This is because it allows you to define your app model once and with the appropriate APIs, specify how resources operate in each mode. Consider the following collection of resources: - Database: PostgreSQL - Cache: Redis @@ -47,11 +47,11 @@ Why is modality important when it comes to the app host's execution context? Thi - Backend: ASP.NET Core minimal API - Frontend: React app -Depending on the mode, the app host might treat these resources differently. For example, in run mode, the app host might use a local PostgreSQL database and Redis cache—using containers, while in publish mode, it might generate deployment artifacts for Azure PostgreSQL and Redis Cache. +Depending on the mode, the AppHost might treat these resources differently. For example, in run mode, the AppHost might use a local PostgreSQL database and Redis cache—using containers, while in publish mode, it might generate deployment artifacts for Azure PostgreSQL and Redis Cache. #### Run mode -The default mode is run mode, which is ideal for local development and testing. In this mode, the .NET Aspire app host orchestrates your application model, including processes, containers, and cloud emulators, to facilitate fast and iterative development. Resources behave like real runtime entities with lifecycles that mirror production. With a simple F5, the app host launches everything in your [app model](xref:Aspire.Hosting.ApplicationModel.DistributedApplicationModel)—storage, databases, caches, messaging, jobs, APIs, frontends—all fully configured and ready to debug locally. Let's considering the app model from the previous section—where app host would orchestrate the following resources locally: +The default mode is run mode, which is ideal for local development and testing. In this mode, the .NET Aspire AppHost orchestrates your application model, including processes, containers, and cloud emulators, to facilitate fast and iterative development. Resources behave like real runtime entities with lifecycles that mirror production. With a simple F5, the AppHost launches everything in your [app model](xref:Aspire.Hosting.ApplicationModel.DistributedApplicationModel)—storage, databases, caches, messaging, jobs, APIs, frontends—all fully configured and ready to debug locally. Let's considering the app model from the previous section—where AppHost would orchestrate the following resources locally:
@@ -369,7 +369,7 @@ builder.Services.AddAuthentication() For production deployments, consider using connection strings instead of the hosting integration: ```csharp -// In Program.cs of your app host +// In Program.cs of your AppHost builder.AddConnectionString("keycloak", "https://your-keycloak-server.com"); ``` diff --git a/docs/azure/azure-app-configuration-integration.md b/docs/azure/azure-app-configuration-integration.md index 85cc1251c3..28b25a88ea 100644 --- a/docs/azure/azure-app-configuration-integration.md +++ b/docs/azure/azure-app-configuration-integration.md @@ -8,11 +8,11 @@ ms.date: 07/22/2025 [!INCLUDE [includes-hosting-and-client](../includes/includes-hosting-and-client.md)] -[Azure App Configuration](/azure/azure-app-configuration/overview) provides a service to centrally manage application settings and feature flags. Modern programs, especially programs running in a cloud, generally have many components that are distributed in nature. Spreading configuration settings across these components can lead to hard-to-troubleshoot errors during an application deployment. The .NET Aspire Azure App Configuration integration enables you to connect to existing App Configuration instances or create new instances all from your app host. +[Azure App Configuration](/azure/azure-app-configuration/overview) provides a service to centrally manage application settings and feature flags. Modern programs, especially programs running in a cloud, generally have many components that are distributed in nature. Spreading configuration settings across these components can lead to hard-to-troubleshoot errors during an application deployment. The .NET Aspire Azure App Configuration integration enables you to connect to existing App Configuration instances or create new instances all from your AppHost. ## Hosting integration -The .NET Aspire Azure App Configuration hosting integration models the App Configuration resource as the type. To access this type and APIs fro expressing the resource, add the [📦 Aspire.Hosting.Azure.AppConfiguration](https://www.nuget.org/packages/Aspire.Hosting.Azure.AppConfiguration) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +The .NET Aspire Azure App Configuration hosting integration models the App Configuration resource as the type. To access this type and APIs fro expressing the resource, add the [📦 Aspire.Hosting.Azure.AppConfiguration](https://www.nuget.org/packages/Aspire.Hosting.Azure.AppConfiguration) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -33,7 +33,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add Azure App Configuration resource -In your app host project, call to add and return an Azure App Configuration resource builder. +In your AppHost project, call to add and return an Azure App Configuration resource builder. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -45,7 +45,7 @@ var appConfig = builder.AddAzureAppConfiguration("config"); builder.Build().Run(); ``` -When you add an to the app host, it exposes other useful APIs. +When you add an to the AppHost, it exposes other useful APIs. > [!IMPORTANT] > When you call , it implicitly calls —which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see [Local provisioning: Configuration](local-provisioning.md#configuration). @@ -101,7 +101,7 @@ For more information, see [Use existing Azure resources](integrations-overview.m ### Connect to an existing Azure App Configuration store -An alternative approach to using the `*AsExisting` APIs enables the addition of a connection string instead, where the app host uses configuration to resolve the connection information. To add a connection to an existing Azure App Configuration store, call the method: +An alternative approach to using the `*AsExisting` APIs enables the addition of a connection string instead, where the AppHost uses configuration to resolve the connection information. To add a connection to an existing Azure App Configuration store, call the method: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -116,7 +116,7 @@ builder.AddProject("web") [!INCLUDE [connection-strings-alert](../includes/connection-strings-alert.md)] -The connection string is configured in the app host's configuration, typically under [User Secrets](/aspnet/core/security/app-secrets), under the `ConnectionStrings` section. The app host injects this connection string as an environment variable into all dependent resources, for example: +The connection string is configured in the AppHost's configuration, typically under [User Secrets](/aspnet/core/security/app-secrets), under the `ConnectionStrings` section. The AppHost injects this connection string as an environment variable into all dependent resources, for example: ```json { @@ -154,7 +154,7 @@ builder.AddAzureAppConfiguration(connectionName: "config"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the App Configuration resource in the app host project. In other words, when you call `AddAzureAppConfiguration` in the app host and provide a name of `config` that same name should be used when calling `AddAzureAppConfiguration` in the client-consuming project. For more information, see [Add Azure App Configuration resource](#add-azure-app-configuration-resource). +> The `connectionName` parameter must match the name used when adding the App Configuration resource in the AppHost project. In other words, when you call `AddAzureAppConfiguration` in the AppHost and provide a name of `config` that same name should be used when calling `AddAzureAppConfiguration` in the client-consuming project. For more information, see [Add Azure App Configuration resource](#add-azure-app-configuration-resource). You can then retrieve the instance using dependency injection. For example, to retrieve the client from an example service: diff --git a/docs/azure/configure-aca-environments.md b/docs/azure/configure-aca-environments.md index 848ca349e8..15e5f64c5c 100644 --- a/docs/azure/configure-aca-environments.md +++ b/docs/azure/configure-aca-environments.md @@ -15,7 +15,7 @@ It's easy to [publish resources as Azure Container Apps (ACA)](integrations-over These APIs automatically create a default ACA environment when you publish your app. While this default setup works well for most scenarios, you might need to customize the ACA environment to meet specific requirements. To achieve this, use the `AddAzureContainerAppEnvironment` method. -The [.NET Aspire app host](../fundamentals/app-host-overview.md) simplifies infrastructure provisioning by generating code to create Azure resources for your applications. This approach enables you to model and configure deployment-related aspects directly in C#, reducing the need to rely on tools like Bicep. These aspects include configuring ACA environments, which provide a serverless platform for running containerized applications. +The [.NET Aspire AppHost](../fundamentals/app-host-overview.md) simplifies infrastructure provisioning by generating code to create Azure resources for your applications. This approach enables you to model and configure deployment-related aspects directly in C#, reducing the need to rely on tools like Bicep. These aspects include configuring ACA environments, which provide a serverless platform for running containerized applications. By using the APIs (explained in [Customize Azure resources](customize-azure-resources.md)), you can configure and customize ACA environments along with related resources, such as container registries and file share volumes. Any available deployment setting can be configured. For more information on the available settings, see [Microsoft.App managedEnvironments](/azure/templates/microsoft.app/managedenvironments). @@ -23,8 +23,6 @@ This article guides you through the process of tailoring ACA environments for yo ## Add an ACA environment - - The `AzureContainerAppEnvironmentResource` type models an ACA environment resource. When you call the `AddAzureContainerAppEnvironment` method, it creates an instance of this type (wrapped in the ). :::code language="csharp" source="snippets/aca/AspireAca.AppHost/AspireApp.AppHost/Program.cs"::: @@ -47,9 +45,7 @@ Using the `acaEnv` variable, you can chain a call to the - -By default, `AddAzureContainerAppEnvironment` uses a different Azure resource naming scheme than the [Azure Developer CLI (`azd`)](/azure/developer/azure-developer-cli/). If you're upgrading an existing deployment that previously used `azd`, you might see duplicate Azure resources. To avoid this issue, call the `WithAzdResourceNaming` method to revert to the naming convention used by `azd`: +By default, uses a different Azure resource naming scheme than the [Azure Developer CLI (`azd`)](/azure/developer/azure-developer-cli/). If you're upgrading an existing deployment that previously used `azd`, you might see duplicate Azure resources. To avoid this issue, call the method to revert to the naming convention used by `azd`: ```csharp var builder = DistributionApplicationBuilder.Create(args); diff --git a/docs/azure/customize-azure-resources.md b/docs/azure/customize-azure-resources.md index 0db64b27a2..8e179852a3 100644 --- a/docs/azure/customize-azure-resources.md +++ b/docs/azure/customize-azure-resources.md @@ -13,7 +13,7 @@ The Azure SDK for .NET provides the [📦 Azure.Provisioning](https://www.nuget. -While it's possible to provision Azure resources manually, .NET Aspire simplifies the process by providing a set of APIs to express Azure resources. These APIs are available as extension methods in .NET Aspire Azure hosting libraries, extending the interface. When you add Azure resources to your app host, they add the appropriate provisioning functionality implicitly. In other words, you don't need to call any provisioning APIs directly. +While it's possible to provision Azure resources manually, .NET Aspire simplifies the process by providing a set of APIs to express Azure resources. These APIs are available as extension methods in .NET Aspire Azure hosting libraries, extending the interface. When you add Azure resources to your AppHost, they add the appropriate provisioning functionality implicitly. In other words, you don't need to call any provisioning APIs directly. Since .NET Aspire models Azure resources within Azure hosting integrations, the Azure SDK is used to provision these resources. Bicep files are generated that define the Azure resources you need. The generated Bicep files are output alongside the manifest file when you publish your app. @@ -21,7 +21,7 @@ There are several ways to influence the generated Bicep files: - [Azure.Provisioning customization](#azureprovisioning-customization): - [Configure infrastructure](#configure-infrastructure): Customize Azure resource infrastructure. - - [Add Azure infrastructure](#add-azure-infrastructure): Manually add Azure infrastructure to your app host. + - [Add Azure infrastructure](#add-azure-infrastructure): Manually add Azure infrastructure to your AppHost. - [Use custom Bicep templates](#use-custom-bicep-templates): - [Reference Bicep files](#reference-bicep-files): Add a reference to a Bicep file on disk. - [Reference Bicep inline](#reference-bicep-inline): Add an inline Bicep template. @@ -32,7 +32,7 @@ To avoid conflating terms and to help disambiguate "provisioning," it's importan - **_Local provisioning:_** - By default, when you call any of the Azure hosting integration APIs to add Azure resources, the API is called implicitly. This API registers services in the dependency injection (DI) container that are used to provision Azure resources when the app host starts. This concept is known as _local provisioning_. For more information, see [Local Azure provisioning](local-provisioning.md). + By default, when you call any of the Azure hosting integration APIs to add Azure resources, the API is called implicitly. This API registers services in the dependency injection (DI) container that are used to provision Azure resources when the AppHost starts. This concept is known as _local provisioning_. For more information, see [Local Azure provisioning](local-provisioning.md). - **_`Azure.Provisioning`:_** @@ -64,9 +64,9 @@ This exemplifies flowing an [external parameter](../fundamentals/external-parame ### Add Azure infrastructure -Not all Azure services are exposed as .NET Aspire integrations. While they might be at a later time, you can still provision services that are available in `Azure.Provisioning.*` libraries. Imagine a scenario where you have worker service that's responsible for managing an Azure Container Registry. Now imagine that an app host project takes a dependency on the [📦 Azure.Provisioning.ContainerRegistry](https://www.nuget.org/packages/Azure.Provisioning.ContainerRegistry) NuGet package. +Not all Azure services are exposed as .NET Aspire integrations. While they might be at a later time, you can still provision services that are available in `Azure.Provisioning.*` libraries. Imagine a scenario where you have worker service that's responsible for managing an Azure Container Registry. Now imagine that an AppHost project takes a dependency on the [📦 Azure.Provisioning.ContainerRegistry](https://www.nuget.org/packages/Azure.Provisioning.ContainerRegistry) NuGet package. -You can use the `AddAzureInfrastructure` API to add the Azure Container Registry infrastructure to your app host: +You can use the `AddAzureInfrastructure` API to add the Azure Container Registry infrastructure to your AppHost: :::code language="csharp" source="../snippets/azure/AppHost/Program.AddAzureInfra.cs" id="add"::: @@ -81,7 +81,7 @@ The preceding code: - Adds a project named `worker` to the builder. - Chains a call to to set the `ACR_REGISTRY_NAME` environment variable in the project to the value of the `registryName` output. -The functionality demonstrates how to add Azure infrastructure to your app host project, even if the Azure service isn't directly exposed as a .NET Aspire integration. It further shows how to flow the output of the Azure Container Registry into the environment of a dependent project. +The functionality demonstrates how to add Azure infrastructure to your AppHost project, even if the Azure service isn't directly exposed as a .NET Aspire integration. It further shows how to flow the output of the Azure Container Registry into the environment of a dependent project. Consider the resulting Bicep file: @@ -152,7 +152,7 @@ To add a reference to the Bicep file on disk, call the being added to the application's resources collection with the `"storage"` name, and the API returns an `IResourceBuilder` instance that can be used to further customize the resource. +The preceding code adds a reference to a Bicep file located at `../infra/storage.bicep`. The file paths should be relative to the _AppHost_ project. This reference results in an being added to the application's resources collection with the `"storage"` name, and the API returns an `IResourceBuilder` instance that can be used to further customize the resource. ### Reference Bicep inline diff --git a/docs/azure/includes/azure-configuration.md b/docs/azure/includes/azure-configuration.md index 26eb75ee55..9e950525f0 100644 --- a/docs/azure/includes/azure-configuration.md +++ b/docs/azure/includes/azure-configuration.md @@ -3,4 +3,4 @@ ms.topic: include --- > [!IMPORTANT] -> When you call `RunAsExisting`, `PublishAsExisting`, or `AsExisting` methods to work with resources that are already present in your Azure subscription, you must add certain configuration values to your App Host to ensure that .NET Aspire can locate them. The necessary configuration values include **SubscriptionId**, **AllowResourceGroupCreation**, **ResourceGroup**, and **Location**. If you don't set them, "Missing configuration" errors appear in the .NET Aspire dashboard. For more information about how to set them, see [Configuration](../local-provisioning.md#configuration). +> When you call `RunAsExisting`, `PublishAsExisting`, or `AsExisting` methods to work with resources that are already present in your Azure subscription, you must add certain configuration values to your AppHost to ensure that .NET Aspire can locate them. The necessary configuration values include **SubscriptionId**, **AllowResourceGroupCreation**, **ResourceGroup**, and **Location**. If you don't set them, "Missing configuration" errors appear in the .NET Aspire dashboard. For more information about how to set them, see [Configuration](../local-provisioning.md#configuration). diff --git a/docs/azure/integrations-overview.md b/docs/azure/integrations-overview.md index 05d0274de7..3c7447794f 100644 --- a/docs/azure/integrations-overview.md +++ b/docs/azure/integrations-overview.md @@ -11,11 +11,11 @@ uid: dotnet/aspire/integrations/azure-overview ## Add Azure resources -All .NET Aspire Azure hosting integrations expose Azure resources and by convention are added using `AddAzure*` APIs. When you add these resources to your .NET Aspire app host, they represent an Azure service. The `AddAzure*` API returns an where `T` is the type of Azure resource. These `IResourceBuilder` (builder) interfaces provide a fluent API that allows you to configure the underlying Azure resource within the [app model](xref:dotnet/aspire/app-host#terminology). There are APIs for adding new Azure resources, marking resources as existing, and configuring how the resources behave in various execution contexts. +All .NET Aspire Azure hosting integrations expose Azure resources and by convention are added using `AddAzure*` APIs. When you add these resources to your .NET Aspire AppHost, they represent an Azure service. The `AddAzure*` API returns an where `T` is the type of Azure resource. These `IResourceBuilder` (builder) interfaces provide a fluent API that allows you to configure the underlying Azure resource within the [app model](xref:dotnet/aspire/app-host#terminology). There are APIs for adding new Azure resources, marking resources as existing, and configuring how the resources behave in various execution contexts. ### Typical developer experience -When your .NET Aspire app host contains Azure resources, and you run it locally (typical developer F5 or `dotnet run` experience), the [Azure resources are provisioned](local-provisioning.md) in your Azure subscription. This allows you as the developer to debug against them locally in the context of your app host. +When your .NET Aspire AppHost contains Azure resources, and you run it locally (typical developer F5 or `dotnet run` experience), the [Azure resources are provisioned](local-provisioning.md) in your Azure subscription. This allows you as the developer to debug against them locally in the context of your AppHost. .NET Aspire aims to minimize costs by defaulting to _Basic_ or _Standard_ [Stock Keeping Unit (SKU)](/partner-center/developer/product-resources#sku) for its Azure integrations. While these sensible defaults are provided, you can [customize the Azure resources](customize-azure-resources.md#azureprovisioning-customization) to suit your needs. Additionally, some integrations support [emulators](#local-emulators) or [containers](#local-containers), which are useful for local development, testing, and debugging. By default, when you run your app locally, the Azure resources use the actual Azure service. However, you can configure them to use local emulators or containers, avoiding costs associated with the actual Azure service during local development. @@ -74,13 +74,13 @@ The same is true for SQL and PostgreSQL services: | [AddAzureSqlServer("sql").RunAsContainer()](xref:Aspire.Hosting.AzureSqlExtensions.RunAsContainer*) | Local SQL Server container | Azure SQL Server | | [AddSqlServer("sql")](xref:Aspire.Hosting.SqlServerBuilderExtensions.AddSqlServer*) | Local SQL Server container | Azure Container App with SQL Server image | -For more information on the difference between run and publish modes, see [.NET Aspire app host: Execution context](xref:dotnet/aspire/app-host#execution-context). +For more information on the difference between run and publish modes, see [.NET Aspire AppHost: Execution context](xref:dotnet/aspire/app-host#execution-context). ### APIs for expressing Azure resources in different modes -The distributed application builder, part of the [app host](../fundamentals/app-host-overview.md), uses the builder pattern to `AddAzure*` resources to the [_app model_](../fundamentals/app-host-overview.md#terminology). Developers can configure these resources and define their behavior in different execution contexts. Azure hosting integrations provide APIs to specify how these resources should be "published" and "run." +The distributed application builder, part of the [AppHost](../fundamentals/app-host-overview.md), uses the builder pattern to `AddAzure*` resources to the [_app model_](../fundamentals/app-host-overview.md#terminology). Developers can configure these resources and define their behavior in different execution contexts. Azure hosting integrations provide APIs to specify how these resources should be "published" and "run." -When the app host executes, the [_execution context_](../fundamentals/app-host-overview.md#execution-context) is used to determine whether the app host is in or mode. The naming conventions for these APIs indicate the intended action for the resource. +When the AppHost executes, the [_execution context_](../fundamentals/app-host-overview.md#execution-context) is used to determine whether the AppHost is in or mode. The naming conventions for these APIs indicate the intended action for the resource. The following table summarizes the naming conventions used to express Azure resources: @@ -164,7 +164,7 @@ The preceding code: - Calls the `PublishAsExisting` method on the `serviceBus` resource builder, passing the `existingServiceBusName` parameter—alternatively, you can use the `string` parameter overload. - Adds a queue named `queue` to the `serviceBus` resource. -After the app host is executed in publish mode, the generated manifest file will include the `existingResourceName` parameter, which can be used to reference the existing Azure resource. Consider the following generated partial snippet of the manifest file: +After the AppHost is executed in publish mode, the generated manifest file will include the `existingResourceName` parameter, which can be used to reference the existing Azure resource. Consider the following generated partial snippet of the manifest file: ```json "messaging": { @@ -252,7 +252,7 @@ The preceding code: ## Add existing Azure resources with connection strings -.NET Aspire provides the ability to [connect to existing resources](../fundamentals/app-host-overview.md#reference-existing-resources), including Azure resources. Expressing connection strings is useful when you have existing Azure resources that you want to use in your .NET Aspire app. The API is used with the app host's [execution context](../fundamentals/app-host-overview.md#execution-context) to conditionally add a connection string to the app model. +.NET Aspire provides the ability to [connect to existing resources](../fundamentals/app-host-overview.md#reference-existing-resources), including Azure resources. Expressing connection strings is useful when you have existing Azure resources that you want to use in your .NET Aspire app. The API is used with the AppHost's [execution context](../fundamentals/app-host-overview.md#execution-context) to conditionally add a connection string to the app model. [!INCLUDE [connection-strings-alert](../includes/connection-strings-alert.md)] @@ -279,7 +279,7 @@ The preceding code: - Adds a project named `api` to the builder. - The `api` project references the `storage` resource regardless of the mode. -The consuming API project uses the connection string information with no knowledge of how the app host configured it. In "publish" mode, the code adds a new Azure Storage resource—which would be reflected in the [deployment manifest](../deployment/manifest-format.md) accordingly. When in "run" mode the connection string corresponds to a configuration value visible to the app host. It's assumed that all role assignments for the target resource are configured. This means, you'd likely configure an environment variable or a user secret to store the connection string. The configuration is resolved from the `ConnectionStrings__storage` (or `ConnectionStrings:storage`) configuration key. These configuration values can be viewed when the app runs. For more information, see [Resource details](../fundamentals/dashboard/explore.md#resource-details). +The consuming API project uses the connection string information with no knowledge of how the AppHost configured it. In "publish" mode, the code adds a new Azure Storage resource—which would be reflected in the [deployment manifest](../deployment/manifest-format.md) accordingly. When in "run" mode the connection string corresponds to a configuration value visible to the AppHost. It's assumed that all role assignments for the target resource are configured. This means, you'd likely configure an environment variable or a user secret to store the connection string. The configuration is resolved from the `ConnectionStrings__storage` (or `ConnectionStrings:storage`) configuration key. These configuration values can be viewed when the app runs. For more information, see [Resource details](../fundamentals/dashboard/explore.md#resource-details). Unlike existing resources modeled with [the first-class `AsExisting` API](#use-existing-azure-resources), existing resource modeled as connection strings can't be enhanced with additional role assignments or infrastructure customizations. @@ -297,7 +297,7 @@ To publish these resources, use the following APIs: - - -These APIs configure the resource to be published as an Azure Container App and implicitly call to add the necessary infrastructure and Bicep files to your app host. As an example, consider the following code: +These APIs configure the resource to be published as an Azure Container App and implicitly call to add the necessary infrastructure and Bicep files to your AppHost. As an example, consider the following code: ```csharp var builder = DistributedApplication.CreateBuilder(); diff --git a/docs/azure/role-assignments.md b/docs/azure/role-assignments.md index 292e08e20e..a329eb6e8c 100644 --- a/docs/azure/role-assignments.md +++ b/docs/azure/role-assignments.md @@ -1,7 +1,7 @@ --- title: Manage Azure role assignments description: Learn how to override Azure role assignments on .NET Aspire resources. -ms.date: 03/31/2025 +ms.date: 08/07/2025 --- # Manage Azure role assignments @@ -32,9 +32,7 @@ These role assignments allow the API project to read and write data to the Azure ## Override default role assignments - - -To override the default role assignment, use the `WithRoleAssignments` API and assign built-in roles as shown in the following example: +To override the default role assignment, use the [WithRoleAssignments APIs](/dotnet/api/?preserve-view=true&view=dotnet-aspire-9.0&term=WithRoleAssignments) and assign built-in roles as shown in the following example: ```csharp var builder = DistributedApplication.CreateBuilder(args); diff --git a/docs/azureai/azureai-foundry-integration.md b/docs/azureai/azureai-foundry-integration.md index 9b67c7cdde..961bd36b4f 100644 --- a/docs/azureai/azureai-foundry-integration.md +++ b/docs/azureai/azureai-foundry-integration.md @@ -1,7 +1,7 @@ --- title: ".NET Aspire Azure AI Foundry integration (Preview)" description: "Learn how to integrate Azure AI Foundry with .NET Aspire applications, including hosting and client integration." -ms.date: 07/22/2025 +ms.date: 08/07/2025 ai-usage: ai-assisted titleSuffix: '' --- @@ -35,7 +35,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add an Azure AI Foundry resource -To add an `AzureAIFoundryResource` to your app host project, call the `AddAzureAIFoundry` method: +To add an `AzureAIFoundryResource` to your AppHost project, call the `AddAzureAIFoundry` method: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -48,18 +48,14 @@ builder.AddProject() // After adding all resources, run the app... ``` -The preceding code adds an Azure AI Foundry resource named `foundry` to the app host project. The method passes the connection information to the `ExampleProject` project. - - +The preceding code adds an Azure AI Foundry resource named `foundry` to the AppHost project. The method passes the connection information to the `ExampleProject` project. > [!IMPORTANT] -> When you call `AddAzureAIFoundry`, it implicitly calls —which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see [Local provisioning: Configuration](/dotnet/aspire/azure/local-provisioning#configuration). +> When you call , it implicitly calls —which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see [Local provisioning: Configuration](/dotnet/aspire/azure/local-provisioning#configuration). ### Add an Azure AI Foundry deployment resource - - -To add an Azure AI Foundry deployment resource, call the `AddDeployment` method: +To add an Azure AI Foundry deployment resource, call the method: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -78,16 +74,14 @@ builder.AddProject() The preceding code: - Adds an Azure AI Foundry resource named `foundry`. -- Adds an Azure AI Foundry deployment resource named `chat` with a model name of `Phi-4`. The model name must correspond to an [available model](/azure/ai-foundry/how-to/deploy-models-open) in the Azure AI Foundry service. +- Adds an Azure AI Foundry deployment resource named `chat` with a model name of `Phi-4`. The model name must correspond to an [available model](/azure/ai-foundry/foundry-models/concepts/models) in the Azure AI Foundry service. > [!NOTE] > The `format` parameter of the `AddDeployment(...)` method can be found in the Azure AI Foundry portal in the details page of the model, right after the `Quick facts` text. ### Configure deployment properties - - -You can customize deployment properties using the `WithProperties` method: +You can customize deployment properties using the method: ```csharp var chat = foundry.AddDeployment("chat", "Phi-4", "1", "Microsoft") @@ -151,7 +145,7 @@ builder.AddProject() For more information on treating Azure AI Foundry resources as existing resources, see [Use existing Azure resources](/dotnet/aspire/azure/integrations-overview#use-existing-azure-resources). > [!NOTE] -> Alternatively, instead of representing an Azure AI Foundry resource, you can add a connection string to the app host. This approach is weakly typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](/dotnet/aspire/azure/integrations-overview#add-existing-azure-resources-with-connection-strings). +> Alternatively, instead of representing an Azure AI Foundry resource, you can add a connection string to the AppHost. This approach is weakly typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](/dotnet/aspire/azure/integrations-overview#add-existing-azure-resources-with-connection-strings). ### Use Foundry Local for development @@ -174,15 +168,11 @@ builder.AddProject() When the AppHost starts up, the local foundry service is also started. This requires the local machine to have [Foundry Local](/azure/ai-foundry/foundry-local/get-started) installed and running. - - -The `RunAsFoundryLocal()` method configures the resource to run as an emulator. It downloads and loads the specified models locally. The method provides health checks for the local service and automatically manages the Foundry Local lifecycle. +The method configures the resource to run as an emulator. It downloads and loads the specified models locally. The method provides health checks for the local service and automatically manages the Foundry Local lifecycle. ### Assign roles to resources - - -You can assign specific roles to resources that need to access the Azure AI Foundry service. Use the `WithRoleAssignments` method: +You can assign specific roles to resources that need to access the Azure AI Foundry service. Use the method: ```csharp var foundry = builder.AddAzureAIFoundry("foundry"); @@ -222,7 +212,7 @@ builder.AddAzureChatCompletionsClient(connectionName: "chat"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Azure AI Foundry deployment resource in the app host project. For more information, see Add an Azure AI Foundry deployment resource. +> The `connectionName` parameter must match the name used when adding the Azure AI Foundry deployment resource in the AppHost project. For more information, see Add an Azure AI Foundry deployment resource. After adding the `ChatCompletionsClient`, you can retrieve the client instance using dependency injection: @@ -240,7 +230,7 @@ For more information, see: ### Add Azure AI Foundry client with registered `IChatClient` -If you're interested in using the [IChatClient](/dotnet/api/microsoft.extensions.ai.ichatclient) interface, with the Azure AI Foundry client, simply chain the [AddChatClient](/dotnet/api/microsoft.extensions.hosting.aspirechatcompletionsclientbuilderchatclientextensions.addchatclient) API to the `AddAzureChatCompletionsClient` method: +If you're interested in using the [IChatClient](/dotnet/api/microsoft.extensions.ai.ichatclient) interface, with the Azure AI Foundry client, simply chain the API to the `AddAzureChatCompletionsClient` method: ```csharp builder.AddAzureChatCompletionsClient(connectionName: "chat") @@ -347,7 +337,7 @@ The .NET Aspire Azure AI Foundry integration emits tracing activities using Open ## See also -- [Azure AI Foundry](https://azure.microsoft.com/products/ai-services/ai-foundry/) +- [Azure AI Foundry](https://ai.azure.com/?cid=learnDocs) - [.NET Aspire integrations overview](/dotnet/aspire/fundamentals/integrations-overview) - [.NET Aspire Azure integrations overview](/dotnet/aspire/azure/integrations-overview) - [.NET Aspire GitHub repo](https://github.com/dotnet/aspire) diff --git a/docs/azureai/azureai-inference-integration.md b/docs/azureai/azureai-inference-integration.md index dd17ab472b..5506202a9e 100644 --- a/docs/azureai/azureai-inference-integration.md +++ b/docs/azureai/azureai-inference-integration.md @@ -13,11 +13,11 @@ The .NET Aspire Azure AI Inference integration provides a seamless way to deploy ## Hosting integration -Although the Azure AI Inference library doesn't currently offer direct hosting integration, you can still integrate it into your app host project. Simply add a connection string to establish a reference to an existing Azure AI Foundry resource. +Although the Azure AI Inference library doesn't currently offer direct hosting integration, you can still integrate it into your AppHost project. Simply add a connection string to establish a reference to an existing Azure AI Foundry resource. ### Connect to an existing Azure AI Foundry service -If you already have an [Azure AI Foundry](https://ai.azure.com/) service, you can easily connect to it by adding a connection string to your app host. This approach uses a simple, string-based configuration. To establish the connection, use the method: +If you already have an [Azure AI Foundry](https://ai.azure.com/) service, you can easily connect to it by adding a connection string to your AppHost. This approach uses a simple, string-based configuration. To establish the connection, use the method: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -32,7 +32,7 @@ builder.AddProject() [!INCLUDE [connection-strings-alert](../includes/connection-strings-alert.md)] -The connection string is configured in the app host's configuration, typically under User Secrets, under the `ConnectionStrings` section: +The connection string is configured in the AppHost's configuration, typically under User Secrets, under the `ConnectionStrings` section: ```json { @@ -74,7 +74,7 @@ builder.AddChatCompletionsClient(connectionName: "ai-foundry"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Azure AI Inference resource in the app host project. For more information, see [Connect to an existing Azure AI Foundry service](#connect-to-an-existing-azure-ai-foundry-service). +> The `connectionName` parameter must match the name used when adding the Azure AI Inference resource in the AppHost project. For more information, see [Connect to an existing Azure AI Foundry service](#connect-to-an-existing-azure-ai-foundry-service). After adding the `ChatCompletionsClient`, you can retrieve the client instance using dependency injection: diff --git a/docs/azureai/azureai-openai-integration.md b/docs/azureai/azureai-openai-integration.md index d5a33d723e..d4d7b035be 100644 --- a/docs/azureai/azureai-openai-integration.md +++ b/docs/azureai/azureai-openai-integration.md @@ -13,7 +13,7 @@ ms.custom: sfi-ropc-nochange ## Hosting integration -The .NET Aspire [Azure OpenAI](/azure/ai-services/openai/) hosting integration models Azure OpenAI resources as . To access these types and APIs for expressing them within your [app host](xref:dotnet/aspire/app-host) project, install the [📦 Aspire.Hosting.Azure.CognitiveServices](https://www.nuget.org/packages/Aspire.Hosting.Azure.CognitiveServices) NuGet package: +The .NET Aspire [Azure OpenAI](/azure/ai-services/openai/) hosting integration models Azure OpenAI resources as . To access these types and APIs for expressing them within your [AppHost](xref:dotnet/aspire/app-host) project, install the [📦 Aspire.Hosting.Azure.CognitiveServices](https://www.nuget.org/packages/Aspire.Hosting.Azure.CognitiveServices) NuGet package: ### [.NET CLI](#tab/dotnet-cli) @@ -34,7 +34,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add an Azure OpenAI resource -To add an to your app host project, call the method: +To add an to your AppHost project, call the method: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -47,7 +47,7 @@ builder.AddProject() // After adding all resources, run the app... ``` -The preceding code adds an Azure OpenAI resource named `openai` to the app host project. The method passes the connection information to the `ExampleProject` project. +The preceding code adds an Azure OpenAI resource named `openai` to the AppHost project. The method passes the connection information to the `ExampleProject` project. > [!IMPORTANT] > When you call , it implicitly calls —which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see [Local provisioning: Configuration](../azure/local-provisioning.md#configuration). @@ -129,7 +129,7 @@ builder.AddProject() For more information on treating Azure OpenAI resources as existing resources, see [Use existing Azure resources](../azure/integrations-overview.md#use-existing-azure-resources). > [!NOTE] -> Alternatively, instead of representing an Azure OpenAI resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). +> Alternatively, instead of representing an Azure OpenAI resource, you can add a connection string to the AppHost. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). ## Client integration @@ -159,7 +159,7 @@ builder.AddAzureOpenAIClient(connectionName: "openai"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Azure OpenAI resource in the app host project. For more information, see [Add an Azure OpenAI resource](#add-an-azure-openai-resource). +> The `connectionName` parameter must match the name used when adding the Azure OpenAI resource in the AppHost project. For more information, see [Add an Azure OpenAI resource](#add-an-azure-openai-resource). After adding the `OpenAIClient`, you can retrieve the client instance using dependency injection: diff --git a/docs/azureai/azureai-search-document-integration.md b/docs/azureai/azureai-search-document-integration.md index cf97c6602a..084b072427 100644 --- a/docs/azureai/azureai-search-document-integration.md +++ b/docs/azureai/azureai-search-document-integration.md @@ -13,7 +13,7 @@ The .NET Aspire Azure AI Search Documents integration enables you to connect to ## Hosting integration -The .NET Aspire Azure AI Search hosting integration models the Azure AI Search resource as the type. To access this type and APIs for expressing them within your [app host](xref:dotnet/aspire/app-host) project, install the [📦 Aspire.Hosting.Azure.Search](https://www.nuget.org/packages/Aspire.Hosting.Azure.Search) NuGet package: +The .NET Aspire Azure AI Search hosting integration models the Azure AI Search resource as the type. To access this type and APIs for expressing them within your [AppHost](xref:dotnet/aspire/app-host) project, install the [📦 Aspire.Hosting.Azure.Search](https://www.nuget.org/packages/Aspire.Hosting.Azure.Search) NuGet package: ### [.NET CLI](#tab/dotnet-cli) @@ -34,7 +34,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add an Azure AI Search resource -To add an to your app host project, call the method providing a name: +To add an to your AppHost project, call the method providing a name: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -47,7 +47,7 @@ builder.AddProject() // After adding all resources, run the app... ``` -The preceding code adds an Azure AI Search resource named `search` to the app host project. The method passes the connection information to the `ExampleProject` project. +The preceding code adds an Azure AI Search resource named `search` to the AppHost project. The method passes the connection information to the `ExampleProject` project. > [!IMPORTANT] > When you call , it implicitly calls —which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see Local provisioning: Configuration @@ -107,7 +107,7 @@ builder.AddProject() For more information on treating Azure AI Search resources as existing resources, see [Use existing Azure resources](../azure/integrations-overview.md#use-existing-azure-resources). > [!NOTE] -> Alternatively, instead of representing an Azure AI Search resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). +> Alternatively, instead of representing an Azure AI Search resource, you can add a connection string to the AppHost. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). ### Hosting integration health checks @@ -141,7 +141,7 @@ builder.AddAzureSearchClient(connectionName: "search"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Azure AI Search resource in the app host project. For more information, see [Add an Azure AI Search resource](#add-an-azure-ai-search-resource). +> The `connectionName` parameter must match the name used when adding the Azure AI Search resource in the AppHost project. For more information, see [Add an Azure AI Search resource](#add-an-azure-ai-search-resource). After adding the `SearchIndexClient`, you can retrieve the client instance using dependency injection. For example, to retrieve the client instance from an example service: diff --git a/docs/caching/azure-cache-for-redis-distributed-caching-integration.md b/docs/caching/azure-cache-for-redis-distributed-caching-integration.md index 58f4c2a89b..21fb203062 100644 --- a/docs/caching/azure-cache-for-redis-distributed-caching-integration.md +++ b/docs/caching/azure-cache-for-redis-distributed-caching-integration.md @@ -31,7 +31,7 @@ builder.AddRedisDistributedCache(connectionName: "cache"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Azure Cache for Redis resource in the app host project. For more information, see [Add Azure Cache for Redis resource](#add-azure-cache-for-redis-resource). +> The `connectionName` parameter must match the name used when adding the Azure Cache for Redis resource in the AppHost project. For more information, see [Add Azure Cache for Redis resource](#add-azure-cache-for-redis-resource). You can then retrieve the `IDistributedCache` instance using dependency injection. For example, to retrieve the cache from a service: diff --git a/docs/caching/azure-cache-for-redis-integration.md b/docs/caching/azure-cache-for-redis-integration.md index 4323505b1f..51d8b36634 100644 --- a/docs/caching/azure-cache-for-redis-integration.md +++ b/docs/caching/azure-cache-for-redis-integration.md @@ -31,7 +31,7 @@ builder.AddRedisClient(connectionName: "cache"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Azure Cache for Redis resource in the app host project. For more information, see [Add Azure Cache for Redis resource](#add-azure-cache-for-redis-resource). +> The `connectionName` parameter must match the name used when adding the Azure Cache for Redis resource in the AppHost project. For more information, see [Add Azure Cache for Redis resource](#add-azure-cache-for-redis-resource). You can then retrieve the `IConnectionMultiplexer` instance using dependency injection. For example, to retrieve the connection from an example service: diff --git a/docs/caching/azure-cache-for-redis-output-caching-integration.md b/docs/caching/azure-cache-for-redis-output-caching-integration.md index 0fa8000491..6595638710 100644 --- a/docs/caching/azure-cache-for-redis-output-caching-integration.md +++ b/docs/caching/azure-cache-for-redis-output-caching-integration.md @@ -31,7 +31,7 @@ builder.AddRedisOutputCache(connectionName: "cache"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Azure Cache for Redis resource in the app host project. For more information, see [Add Azure Cache for Redis resource](#add-azure-cache-for-redis-resource). +> The `connectionName` parameter must match the name used when adding the Azure Cache for Redis resource in the AppHost project. For more information, see [Add Azure Cache for Redis resource](#add-azure-cache-for-redis-resource). Add the middleware to the request processing pipeline by calling : diff --git a/docs/caching/caching-integrations.md b/docs/caching/caching-integrations.md index 7391febcae..78ac47a753 100644 --- a/docs/caching/caching-integrations.md +++ b/docs/caching/caching-integrations.md @@ -42,7 +42,7 @@ Visual Studio creates a new .NET Aspire solution that consists of the following - **AspireRedis.AppHost** - An orchestrator project designed to connect and configure the different projects and services of your app. - **AspireRedis.ServiceDefaults** - A .NET Aspire shared project to manage configurations that are reused across the projects in your solution related to [resilience](/dotnet/core/resilience/http-resilience), [service discovery](../service-discovery/overview.md), and [telemetry](../telemetry.md). -## Configure the App Host project +## Configure the AppHost project 1. Add the [📦 Aspire.Hosting.Redis](https://www.nuget.org/packages/Aspire.Hosting.Redis) NuGet package to the `AspireRedis.AppHost` project: diff --git a/docs/caching/includes/azure-redis-app-host.md b/docs/caching/includes/azure-redis-app-host.md index cb6570a760..398c0f5470 100644 --- a/docs/caching/includes/azure-redis-app-host.md +++ b/docs/caching/includes/azure-redis-app-host.md @@ -2,7 +2,7 @@ ms.topic: include --- -The .NET Aspire Azure Cache for Redis hosting integration models an Azure Redis resource as the type. To access this type and APIs for expressing them as resources in your [app host](xref:dotnet/aspire/app-host) project, add the [📦 Aspire.Hosting.Azure.Redis](https://www.nuget.org/packages/Aspire.Hosting.Azure.Redis) NuGet package: +The .NET Aspire Azure Cache for Redis hosting integration models an Azure Redis resource as the type. To access this type and APIs for expressing them as resources in your [AppHost](xref:dotnet/aspire/app-host) project, add the [📦 Aspire.Hosting.Azure.Redis](https://www.nuget.org/packages/Aspire.Hosting.Azure.Redis) NuGet package: ### [.NET CLI](#tab/dotnet-cli) @@ -23,7 +23,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add Azure Cache for Redis resource -In your app host project, call on the `builder` instance to add an Azure Cache for Redis resource, as shown in the following example: +In your AppHost project, call on the `builder` instance to add an Azure Cache for Redis resource, as shown in the following example: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -97,7 +97,7 @@ builder.AddProject() For more information on treating Azure Cache for Redis resources as existing resources, see [Use existing Azure resources](../../azure/integrations-overview.md#use-existing-azure-resources). > [!NOTE] -> Alternatively, instead of representing an Azure Cache for Redis resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). +> Alternatively, instead of representing an Azure Cache for Redis resource, you can add a connection string to the AppHost. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). ### Run Azure Cache for Redis resource as a container diff --git a/docs/caching/includes/azure-redis-distributed-client.md b/docs/caching/includes/azure-redis-distributed-client.md index 024016a277..1a194e80de 100644 --- a/docs/caching/includes/azure-redis-distributed-client.md +++ b/docs/caching/includes/azure-redis-distributed-client.md @@ -5,7 +5,7 @@ ms.custom: sfi-ropc-nochange ### Add Azure Cache for Redis authenticated distributed client -By default, when you call in your app host project, the Redis hosting integration configures [📦 Microsoft.Azure.StackExchangeRedis](https://www.nuget.org/packages/Microsoft.Azure.StackExchangeRedis) NuGet package to enable authentication: +By default, when you call in your AppHost project, the Redis hosting integration configures [📦 Microsoft.Azure.StackExchangeRedis](https://www.nuget.org/packages/Microsoft.Azure.StackExchangeRedis) NuGet package to enable authentication: ### [.NET CLI](#tab/dotnet-cli) diff --git a/docs/caching/includes/garnet-app-host.md b/docs/caching/includes/garnet-app-host.md index d57389953c..097358f2f9 100644 --- a/docs/caching/includes/garnet-app-host.md +++ b/docs/caching/includes/garnet-app-host.md @@ -3,7 +3,7 @@ ms.topic: include ms.custom: sfi-ropc-nochange --- -The Garnet hosting integration models a Garnet resource as the type. To access this type and APIs that allow you to add it to your [📦 Aspire.Hosting.Garnet](https://www.nuget.org/packages/Aspire.Hosting.Garnet) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +The Garnet hosting integration models a Garnet resource as the type. To access this type and APIs that allow you to add it to your [📦 Aspire.Hosting.Garnet](https://www.nuget.org/packages/Aspire.Hosting.Garnet) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -24,7 +24,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add Garnet resource -In your app host project, call on the `builder` instance to add a Garnet resource: +In your AppHost project, call on the `builder` instance to add a Garnet resource: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -37,7 +37,7 @@ builder.AddProject() // After adding all resources, run the app... ``` -When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `ghcr.io/microsoft/garnet` image, it creates a new Garnet instance on your local machine. A reference to your Garnet resource (the `cache` variable) is added to the `ExampleProject`. +When .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `ghcr.io/microsoft/garnet` image, it creates a new Garnet instance on your local machine. A reference to your Garnet resource (the `cache` variable) is added to the `ExampleProject`. The method configures a connection in the `ExampleProject` named `"cache"`. For more information, see [Container resource lifecycle](../../fundamentals/orchestrate-resources.md#container-resource-lifecycle). diff --git a/docs/caching/includes/redis-app-host.md b/docs/caching/includes/redis-app-host.md index f222aa9a0d..9f543ec31a 100644 --- a/docs/caching/includes/redis-app-host.md +++ b/docs/caching/includes/redis-app-host.md @@ -3,7 +3,7 @@ ms.topic: include ms.custom: sfi-ropc-nochange --- -The Redis hosting integration models a Redis resource as the type. To access this type and APIs for expressing them as resources in your [app host](xref:dotnet/aspire/app-host) project, add the [📦 Aspire.Hosting.Redis](https://www.nuget.org/packages/Aspire.Hosting.Redis) NuGet package: +The Redis hosting integration models a Redis resource as the type. To access this type and APIs for expressing them as resources in your [AppHost](xref:dotnet/aspire/app-host) project, add the [📦 Aspire.Hosting.Redis](https://www.nuget.org/packages/Aspire.Hosting.Redis) NuGet package: ### [.NET CLI](#tab/dotnet-cli) @@ -24,7 +24,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add Redis resource -In your app host project, call on the `builder` instance to add a Redis resource: +In your AppHost project, call on the `builder` instance to add a Redis resource: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -37,7 +37,7 @@ builder.AddProject() // After adding all resources, run the app... ``` -When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `docker.io/Redis/Redis` image, it creates a new Redis instance on your local machine. A reference to your Redis resource (the `cache` variable) is added to the `ExampleProject`. +When .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `docker.io/Redis/Redis` image, it creates a new Redis instance on your local machine. A reference to your Redis resource (the `cache` variable) is added to the `ExampleProject`. The method configures a connection in the `ExampleProject` named `"cache"`. For more information, see [Container resource lifecycle](../../fundamentals/orchestrate-resources.md#container-resource-lifecycle). @@ -60,7 +60,7 @@ builder.AddProject() // After adding all resources, run the app... ``` -Redis Insights is a free graphical interface for analyzing Redis data across all operating systems and Redis deployments with the help of our AI assistant, Redis Copilot. .NET Aspire adds another container image [`docker.io/redis/redisinsight`](https://hub.docker.com/r/redis/redisinsight) to the app host that runs the commander app. +Redis Insights is a free graphical interface for analyzing Redis data across all operating systems and Redis deployments with the help of our AI assistant, Redis Copilot. .NET Aspire adds another container image [`docker.io/redis/redisinsight`](https://hub.docker.com/r/redis/redisinsight) to the AppHost that runs the commander app. > [!NOTE] > To configure the host port for the `RedisInsightResource` chain a call to the `WithHostPort` API and provide the desired port number. @@ -81,7 +81,7 @@ builder.AddProject() // After adding all resources, run the app... ``` -Redis Commander is a Node.js web application used to view, edit, and manage a Redis Database. .NET Aspire adds another container image [`docker.io/rediscommander/redis-commander`](https://hub.docker.com/r/rediscommander/redis-commander) to the app host that runs the commander app. +Redis Commander is a Node.js web application used to view, edit, and manage a Redis Database. .NET Aspire adds another container image [`docker.io/rediscommander/redis-commander`](https://hub.docker.com/r/rediscommander/redis-commander) to the AppHost that runs the commander app. > [!TIP] > To configure the host port for the chain a call to the API and provide the desired port number. diff --git a/docs/caching/includes/valkey-app-host.md b/docs/caching/includes/valkey-app-host.md index 12a9927dea..c551092779 100644 --- a/docs/caching/includes/valkey-app-host.md +++ b/docs/caching/includes/valkey-app-host.md @@ -3,7 +3,7 @@ ms.topic: include ms.custom: sfi-ropc-nochange --- -The Valkey hosting integration models a Valkey resource as the type. To access this type and APIs that allow you to add it to your [📦 Aspire.Hosting.Valkey](https://www.nuget.org/packages/Aspire.Hosting.Valkey) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +The Valkey hosting integration models a Valkey resource as the type. To access this type and APIs that allow you to add it to your [📦 Aspire.Hosting.Valkey](https://www.nuget.org/packages/Aspire.Hosting.Valkey) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -24,7 +24,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add Valkey resource -In your app host project, call on the `builder` instance to add a Valkey resource: +In your AppHost project, call on the `builder` instance to add a Valkey resource: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -37,7 +37,7 @@ builder.AddProject() // After adding all resources, run the app... ``` -When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `docker.io/valkey/valkey` image, it creates a new Valkey instance on your local machine. A reference to your Valkey resource (the `cache` variable) is added to the `ExampleProject`. +When .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `docker.io/valkey/valkey` image, it creates a new Valkey instance on your local machine. A reference to your Valkey resource (the `cache` variable) is added to the `ExampleProject`. The method configures a connection in the `ExampleProject` named `"cache"`. For more information, see [Container resource lifecycle](../../fundamentals/orchestrate-resources.md#container-resource-lifecycle). diff --git a/docs/caching/stackexchange-redis-distributed-caching-integration.md b/docs/caching/stackexchange-redis-distributed-caching-integration.md index 458d88611c..94d8f4158c 100644 --- a/docs/caching/stackexchange-redis-distributed-caching-integration.md +++ b/docs/caching/stackexchange-redis-distributed-caching-integration.md @@ -65,19 +65,19 @@ builder.AddRedisDistributedCache(connectionName: "cache"); :::zone pivot="redis" > [!TIP] -> The `connectionName` parameter must match the name used when adding the Redis resource in the app host project. For more information, see [Add Redis resource](#add-redis-resource). +> The `connectionName` parameter must match the name used when adding the Redis resource in the AppHost project. For more information, see [Add Redis resource](#add-redis-resource). :::zone-end :::zone pivot="garnet" > [!TIP] -> The `connectionName` parameter must match the name used when adding the Garnet resource in the app host project. For more information, see [Add Garnet resource](#add-garnet-resource). +> The `connectionName` parameter must match the name used when adding the Garnet resource in the AppHost project. For more information, see [Add Garnet resource](#add-garnet-resource). :::zone-end :::zone pivot="valkey" > [!TIP] -> The `connectionName` parameter must match the name used when adding the Valkey resource in the app host project. For more information, see [Add Valkey resource](#add-valkey-resource). +> The `connectionName` parameter must match the name used when adding the Valkey resource in the AppHost project. For more information, see [Add Valkey resource](#add-valkey-resource). :::zone-end diff --git a/docs/caching/stackexchange-redis-integration.md b/docs/caching/stackexchange-redis-integration.md index 9a53207e90..ab034e5321 100644 --- a/docs/caching/stackexchange-redis-integration.md +++ b/docs/caching/stackexchange-redis-integration.md @@ -146,19 +146,19 @@ builder.AddRedisClient(connectionName: "cache"); :::zone pivot="redis" > [!TIP] -> The `connectionName` parameter must match the name used when adding the Redis resource in the app host project. For more information, see [Add Redis resource](#add-redis-resource). +> The `connectionName` parameter must match the name used when adding the Redis resource in the AppHost project. For more information, see [Add Redis resource](#add-redis-resource). :::zone-end :::zone pivot="garnet" > [!TIP] -> The `connectionName` parameter must match the name used when adding the Garnet resource in the app host project. For more information, see [Add Garnet resource](#add-garnet-resource). +> The `connectionName` parameter must match the name used when adding the Garnet resource in the AppHost project. For more information, see [Add Garnet resource](#add-garnet-resource). :::zone-end :::zone pivot="valkey" > [!TIP] -> The `connectionName` parameter must match the name used when adding the Valkey resource in the app host project. For more information, see [Add Valkey resource](#add-valkey-resource). +> The `connectionName` parameter must match the name used when adding the Valkey resource in the AppHost project. For more information, see [Add Valkey resource](#add-valkey-resource). :::zone-end diff --git a/docs/caching/stackexchange-redis-output-caching-integration.md b/docs/caching/stackexchange-redis-output-caching-integration.md index eaf748867b..8b0c9e4c57 100644 --- a/docs/caching/stackexchange-redis-output-caching-integration.md +++ b/docs/caching/stackexchange-redis-output-caching-integration.md @@ -65,19 +65,19 @@ builder.AddRedisOutputCache(connectionName: "cache"); :::zone pivot="redis" > [!TIP] -> The `connectionName` parameter must match the name used when adding the Redis resource in the app host project. For more information, see [Add Redis resource](#add-redis-resource). +> The `connectionName` parameter must match the name used when adding the Redis resource in the AppHost project. For more information, see [Add Redis resource](#add-redis-resource). :::zone-end :::zone pivot="garnet" > [!TIP] -> The `connectionName` parameter must match the name used when adding the Garnet resource in the app host project. For more information, see [Add Garnet resource](#add-garnet-resource). +> The `connectionName` parameter must match the name used when adding the Garnet resource in the AppHost project. For more information, see [Add Garnet resource](#add-garnet-resource). :::zone-end :::zone pivot="valkey" > [!TIP] -> The `connectionName` parameter must match the name used when adding the Valkey resource in the app host project. For more information, see [Add Valkey resource](#add-valkey-resource). +> The `connectionName` parameter must match the name used when adding the Valkey resource in the AppHost project. For more information, see [Add Valkey resource](#add-valkey-resource). :::zone-end diff --git a/docs/cli-reference/aspire-deploy.md b/docs/cli-reference/aspire-deploy.md index 361807fde6..53699cf0ea 100644 --- a/docs/cli-reference/aspire-deploy.md +++ b/docs/cli-reference/aspire-deploy.md @@ -1,6 +1,6 @@ --- title: aspire deploy command -description: Learn about the aspire deploy command and its usage. This command first runs publishing mode, then invokes resource deployments declared by the app host. +description: Learn about the aspire deploy command and its usage. This command first runs publishing mode, then invokes resource deployments declared by the AppHost. ms.date: 07/24/2025 --- # aspire deploy command (Preview) @@ -49,7 +49,7 @@ The following options are available: - **`--`** - Delimits arguments to `aspire publish` from arguments for the app host. All arguments after this delimiter are passed to the apphost. + Delimits arguments to `aspire publish` from arguments for the AppHost. All arguments after this delimiter are passed to the apphost. - [!INCLUDE [option-project](includes/option-project.md)] diff --git a/docs/cli-reference/aspire-new.md b/docs/cli-reference/aspire-new.md index 7d793a6dc6..662b58aa6d 100644 --- a/docs/cli-reference/aspire-new.md +++ b/docs/cli-reference/aspire-new.md @@ -56,7 +56,7 @@ Each command represents a template. Pass the `--help` parameter to the template | Command | Template | |--------------------------|------------------------------| | `aspire` | Aspire Empty App | -| `aspire-apphost` | Aspire App Host | +| `aspire-apphost` | Aspire AppHost | | `aspire-mstest` | Aspire Test Project (MSTest) | | `aspire-nunit` | Aspire Test Project (NUnit) | | `aspire-servicedefaults` | Aspire Service Defaults | diff --git a/docs/cli-reference/aspire-publish.md b/docs/cli-reference/aspire-publish.md index a0b4a60b99..c842b4cb29 100644 --- a/docs/cli-reference/aspire-publish.md +++ b/docs/cli-reference/aspire-publish.md @@ -9,7 +9,7 @@ ms.date: 07/11/2025 ## Name -`aspire publish` - Generates deployment artifacts for an Aspire app host project. +`aspire publish` - Generates deployment artifacts for an Aspire AppHost project. [!INCLUDE [mode-preview](includes/mode-preview.md)] diff --git a/docs/cli-reference/aspire-run.md b/docs/cli-reference/aspire-run.md index 122db63fb0..c57e794ac9 100644 --- a/docs/cli-reference/aspire-run.md +++ b/docs/cli-reference/aspire-run.md @@ -1,6 +1,6 @@ --- title: aspire run command -description: Learn about the aspire run command and its usage. This command runs an Aspire app host. +description: Learn about the aspire run command and its usage. This command runs an Aspire AppHost. ms.date: 07/11/2025 --- # aspire run command @@ -19,7 +19,7 @@ aspire run [options] [[--] ...] ## Description -The `aspire run` command runs the AppHost project in development mode, which configures the Aspire environment, builds and starts resources defined by the app host, launches the web dashboard, and prints a list of endpoints. +The `aspire run` command runs the AppHost project in development mode, which configures the Aspire environment, builds and starts resources defined by the AppHost, launches the web dashboard, and prints a list of endpoints. [!INCLUDE [project-search-logic-description](includes/project-search-logic-description.md)] @@ -45,7 +45,7 @@ The following options are available: - **`--`** - Delimits arguments to `aspire run` from arguments for the app host being run. All arguments after this delimiter are passed to the app host run. + Delimits arguments to `aspire run` from arguments for the AppHost being run. All arguments after this delimiter are passed to the AppHost run. - [!INCLUDE [option-project](includes/option-project.md)] diff --git a/docs/cli/overview.md b/docs/cli/overview.md index 5dbf09f4e7..0a845a3cb9 100644 --- a/docs/cli/overview.md +++ b/docs/cli/overview.md @@ -1,6 +1,6 @@ --- title: .NET Aspire CLI Overview and Commands -description: Learn about the Aspire CLI commands for creating projects, running an app host, and adding integrations. Get started with command-line tools to build and manage distributed applications efficiently. +description: Learn about the Aspire CLI commands for creating projects, running an AppHost, and adding integrations. Get started with command-line tools to build and manage distributed applications efficiently. ms.date: 06/26/2025 ms.topic: overview ms.custom: @@ -33,7 +33,7 @@ While command line parameters can be used to automate the creation of an Aspire [_Command reference: `aspire run`_](../cli-reference/aspire-run.md) -The `aspire run` command runs the AppHost project in development mode, which configures the Aspire environment, builds and starts resources defined by the app host, launches the web dashboard, and prints a list of endpoints. +The `aspire run` command runs the AppHost project in development mode, which configures the Aspire environment, builds and starts resources defined by the AppHost, launches the web dashboard, and prints a list of endpoints. When `aspire run` starts, it searches the current directory for an AppHost project. If a project isn't found, the sub directories are searched until one is found. If no AppHost project is found, Aspire stops. Once a project is found, Aspire CLI takes the following steps: diff --git a/docs/community-toolkit/dapr.md b/docs/community-toolkit/dapr.md index 343dbdf061..91d89e211c 100644 --- a/docs/community-toolkit/dapr.md +++ b/docs/community-toolkit/dapr.md @@ -1,6 +1,6 @@ --- title: NET Aspire Dapr integration -description: Learn how to use the .NET Aspire Dapr integration, which can configure and orchestrate Dapr from a .NET Aspire app host project. +description: Learn how to use the .NET Aspire Dapr integration, which can configure and orchestrate Dapr from a .NET Aspire AppHost project. ms.date: 05/12/2025 uid: frameworks/dapr --- @@ -51,7 +51,7 @@ This integration requires Dapr version 1.13 or later. To install Dapr, see [Inst ## Hosting integration -In your .NET Aspire solution, to integrate Dapr and access its types and APIs, add the [📦 CommunityToolkit.Aspire.Hosting.Dapr](https://www.nuget.org/packages/CommunityToolkit.Aspire.Hosting.Dapr) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +In your .NET Aspire solution, to integrate Dapr and access its types and APIs, add the [📦 CommunityToolkit.Aspire.Hosting.Dapr](https://www.nuget.org/packages/CommunityToolkit.Aspire.Hosting.Dapr) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -84,9 +84,9 @@ The `WithDaprSidecar` method offers overloads to configure your Dapr sidecar opt :::code language="csharp" source="snippets/Dapr/Dapr.AppHost/Program.cs" range="9-20" highlight="1-7,12"::: -### Complete Dapr app host example +### Complete Dapr AppHost example -Putting everything together, consider the following example of a .NET Aspire app host project that includes: +Putting everything together, consider the following example of a .NET Aspire AppHost project that includes: - A backend API service that declares a Dapr sidecar with defaults. - A web frontend project that declares a Dapr sidecar with specific options, such as explict ports. diff --git a/docs/community-toolkit/hosting-bun.md b/docs/community-toolkit/hosting-bun.md index 69fe471bcc..1ddd3651d4 100644 --- a/docs/community-toolkit/hosting-bun.md +++ b/docs/community-toolkit/hosting-bun.md @@ -11,11 +11,11 @@ ms.date: 11/15/2024 [!INCLUDE [banner](includes/banner.md)] -[Bun](https://bun.sh) is a modern, fast, and lightweight framework for building web applications with TypeScript. The .NET Aspire Bun hosting integration allows you to host Bun applications in your .NET Aspire app host project, and provide it to other resources in your application. +[Bun](https://bun.sh) is a modern, fast, and lightweight framework for building web applications with TypeScript. The .NET Aspire Bun hosting integration allows you to host Bun applications in your .NET Aspire AppHost project, and provide it to other resources in your application. ## Hosting integration -The Bun hosting integration models a Bun application as the `Aspire.Hosting.ApplicationModel.BunAppResource` type. To access this type and APIs that allow you to add it to your app host project, install the [📦 CommunityToolkit.Aspire.Hosting.Bun](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Bun) NuGet package in the app host project. +The Bun hosting integration models a Bun application as the `Aspire.Hosting.ApplicationModel.BunAppResource` type. To access this type and APIs that allow you to add it to your AppHost project, install the [📦 CommunityToolkit.Aspire.Hosting.Bun](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Bun) NuGet package in the AppHost project. This integration expects that the Bun executable has already been installed on the host machine, and that it's available in the system path. @@ -38,7 +38,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ## Add a Bun resource -In your app host project, call the `Aspire.Hosting.BunAppExtensions.AddBunApp` on the `builder` instance to add a Bun application resource as shown in the following example: +In your AppHost project, call the `Aspire.Hosting.BunAppExtensions.AddBunApp` on the `builder` instance to add a Bun application resource as shown in the following example: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -52,14 +52,14 @@ var exampleProject = builder.AddProject() // After adding all resources, run the app... ``` -By default the working directory of the application will be a sibling folder to the app host matching the name provided to the resource, and the entrypoint will be _:::no-loc text="index.ts"::_. Both of these can be customized by passing additional parameters to the `AddBunApp` method. +By default the working directory of the application will be a sibling folder to the AppHost matching the name provided to the resource, and the entrypoint will be _:::no-loc text="index.ts"::_. Both of these can be customized by passing additional parameters to the `AddBunApp` method. ```csharp var api = builder.AddBunApp("api", "../api-service", "start") .WithHttpEndpoint(env: "PORT"); ``` -The Bun application can be added as a reference to other resources in the app host project. +The Bun application can be added as a reference to other resources in the AppHost project. ### Ensuring packages are installed diff --git a/docs/community-toolkit/hosting-data-api-builder.md b/docs/community-toolkit/hosting-data-api-builder.md index 19b93d48e0..18cba74d02 100644 --- a/docs/community-toolkit/hosting-data-api-builder.md +++ b/docs/community-toolkit/hosting-data-api-builder.md @@ -16,7 +16,7 @@ In this article, you learn how to use the .NET Aspire Data API Builder hosting i ## Hosting integration -To get started with the .NET Aspire Azure Data API Builder hosting integration, install the [📦 CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +To get started with the .NET Aspire Azure Data API Builder hosting integration, install the [📦 CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Azure.DataApiBuilder) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -37,7 +37,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ## Usage - In the app host project, register and consume the Data API Builder integration using the `AddDataAPIBuilder` extension method to add the Data API Builder container to the application builder. + In the AppHost project, register and consume the Data API Builder integration using the `AddDataAPIBuilder` extension method to add the Data API Builder container to the application builder. ```csharp var builder = DistributedApplication.CreateBuilder(); @@ -51,7 +51,7 @@ builder.AddProject() // After adding all resources, run the app... ``` -When the .NET Aspire adds a container image to the app host, as shown in the preceding example with the `mcr.microsoft.com/azure-databases/data-api-builder` image, it creates a new Data API Builder instance on your local machin. A reference to the DAB resource (the `dab` variable) is added to the `ExampleProject` project. +When the .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `mcr.microsoft.com/azure-databases/data-api-builder` image, it creates a new Data API Builder instance on your local machin. A reference to the DAB resource (the `dab` variable) is added to the `ExampleProject` project. ### Configuration diff --git a/docs/community-toolkit/hosting-eventstore.md b/docs/community-toolkit/hosting-eventstore.md index 6b585ca26e..1599f79451 100644 --- a/docs/community-toolkit/hosting-eventstore.md +++ b/docs/community-toolkit/hosting-eventstore.md @@ -1,7 +1,7 @@ --- title: .NET Aspire Community Toolkit EventStore integration description: Learn how to use the .NET Aspire EventStore hosting and client integration to run the EventStore container and accessing it via the EventStore client. -ms.date: 11/21/2024 +ms.date: 08/07/2025 ms.custom: sfi-ropc-nochange --- @@ -15,7 +15,7 @@ In this article, you learn how to use the .NET Aspire EventStore hosting integra ## Hosting integration -To run the EventStore container, install the [📦 CommunityToolkit.Aspire.Hosting.EventStore][hosting-nuget-link] NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +To run the EventStore container, install the [📦 CommunityToolkit.Aspire.Hosting.EventStore][hosting-nuget-link] NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -36,7 +36,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add EventStore resource -In the app host project, register and consume the EventStore integration using the `AddEventStore` extension method to add the EventStore container to the application builder. +In the AppHost project, register and consume the EventStore integration using the `AddEventStore` extension method to add the EventStore container to the application builder. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -49,7 +49,7 @@ builder.AddProject() // After adding all resources, run the app... ``` -When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `docker.io/eventstore/eventstore` image, it creates a new EventStore instance on your local machine. A reference to your EventStore resource (the `eventstore` variable) is added to the `ExampleProject`. +When .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `docker.io/eventstore/eventstore` image, it creates a new EventStore instance on your local machine. A reference to your EventStore resource (the `eventstore` variable) is added to the `ExampleProject`. For more information, see [Container resource lifecycle](../fundamentals/orchestrate-resources.md#container-resource-lifecycle). @@ -163,7 +163,7 @@ builder.AddEventStoreClient(connectionName: "eventstore"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the EventStore resource in the app host project. For more information, see [Add EventStore resource](#add-eventstore-resource). +> The `connectionName` parameter must match the name used when adding the EventStore resource in the AppHost project. For more information, see [Add EventStore resource](#add-eventstore-resource). You can then retrieve the `EventStoreClient` instance using dependency injection. For example, to retrieve the connection from an example service: @@ -255,10 +255,5 @@ The .NET Aspire EventStore integration uses the configured client to perform a ` - [EventStore Client](https://github.com/EventStore/EventStore-Client-Dotnet) - [.NET Aspire Community Toolkit GitHub repo](https://github.com/CommunityToolkit/Aspire) - -[hosting-nuget-link]: https://github.com/CommunityToolkit/Aspire/tree/main/src/CommunityToolkit.Aspire.Hosting.EventStore -[client-nuget-link]: https://github.com/CommunityToolkit/Aspire/tree/main/src/CommunityToolkit.Aspire.EventStore +[hosting-nuget-link]: https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.EventStore +[client-nuget-link]: https://nuget.org/packages/CommunityToolkit.Aspire.EventStore diff --git a/docs/community-toolkit/hosting-golang.md b/docs/community-toolkit/hosting-golang.md index 15238189be..cc65103bfb 100644 --- a/docs/community-toolkit/hosting-golang.md +++ b/docs/community-toolkit/hosting-golang.md @@ -36,7 +36,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ## Example usage -In the _:::no-loc text="Program.cs":::_ file of your app host project, call the `AddGolangApp` method to add a Go application to the builder. +In the _:::no-loc text="Program.cs":::_ file of your AppHost project, call the `AddGolangApp` method to add a Go application to the builder. ```csharp var golang = builder.AddGolangApp("golang", "../gin-api") diff --git a/docs/community-toolkit/hosting-java.md b/docs/community-toolkit/hosting-java.md index 58796784fc..b0a0e43dc6 100644 --- a/docs/community-toolkit/hosting-java.md +++ b/docs/community-toolkit/hosting-java.md @@ -84,7 +84,7 @@ The following sections detail various example usage scenarios, from hosting a co ### [Container hosting](#tab/container-hosting) -In the _:::no-loc text="Program.cs":::_ file of your app host project, call the `AddSpringApp` method to define the containerized Spring app. The `JavaAppContainerResourceOptions` allows you to specify the container image and OpenTelemetry agent configuration. +In the _:::no-loc text="Program.cs":::_ file of your AppHost project, call the `AddSpringApp` method to define the containerized Spring app. The `JavaAppContainerResourceOptions` allows you to specify the container image and OpenTelemetry agent configuration. ```csharp var containerapp = builder.AddSpringApp( diff --git a/docs/community-toolkit/hosting-meilisearch.md b/docs/community-toolkit/hosting-meilisearch.md index 33f0d65fe7..0109a0c896 100644 --- a/docs/community-toolkit/hosting-meilisearch.md +++ b/docs/community-toolkit/hosting-meilisearch.md @@ -15,7 +15,7 @@ In this article, you learn how to use the .NET Aspire Meilisearch hosting integr ## Hosting integration -To run the Meilisearch container, install the [📦 CommunityToolkit.Aspire.Hosting.Meilisearch](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Meilisearch) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +To run the Meilisearch container, install the [📦 CommunityToolkit.Aspire.Hosting.Meilisearch](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Meilisearch) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -36,7 +36,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add Meilisearch resource -In the app host project, register and consume the Meilisearch integration using the `AddMeilisearch` extension method to add the Meilisearch container to the application builder. +In the AppHost project, register and consume the Meilisearch integration using the `AddMeilisearch` extension method to add the Meilisearch container to the application builder. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -49,7 +49,7 @@ builder.AddProject() // After adding all resources, run the app... ``` -When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `docker.io/getmeili/meilisearch` image, it creates a new Meilisearch instance on your local machine. A reference to your Meilisearch resource (the `meilisearch` variable) is added to the `ExampleProject`. The Meilisearch resource includes a randomly generated `master key` using the method when a master key wasn't provided. +When .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `docker.io/getmeili/meilisearch` image, it creates a new Meilisearch instance on your local machine. A reference to your Meilisearch resource (the `meilisearch` variable) is added to the `ExampleProject`. The Meilisearch resource includes a randomly generated `master key` using the method when a master key wasn't provided. For more information, see [Container resource lifecycle](../fundamentals/orchestrate-resources.md#container-resource-lifecycle). @@ -138,7 +138,7 @@ builder.AddMeilisearchClient(connectionName: "meilisearch"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Meilisearch resource in the app host project. For more information, see [Add Meilisearch resource](#add-meilisearch-resource). +> The `connectionName` parameter must match the name used when adding the Meilisearch resource in the AppHost project. For more information, see [Add Meilisearch resource](#add-meilisearch-resource). You can then retrieve the `MeilisearchClient` instance using dependency injection. For example, to retrieve the connection from an example service: diff --git a/docs/community-toolkit/hosting-mongodb-extensions.md b/docs/community-toolkit/hosting-mongodb-extensions.md index 465f4bf9dc..9d8a0e2952 100644 --- a/docs/community-toolkit/hosting-mongodb-extensions.md +++ b/docs/community-toolkit/hosting-mongodb-extensions.md @@ -46,4 +46,4 @@ var MongoDB = builder.AddMongoDB("MongoDB") .WithDbGate(); ``` -This will add a new resource to the app host which will be available from the .NET Aspire dashboard. +This will add a new resource to the AppHost which will be available from the .NET Aspire dashboard. diff --git a/docs/community-toolkit/hosting-mysql-extensions.md b/docs/community-toolkit/hosting-mysql-extensions.md index 6ad7deeef3..9a065c3939 100644 --- a/docs/community-toolkit/hosting-mysql-extensions.md +++ b/docs/community-toolkit/hosting-mysql-extensions.md @@ -55,4 +55,4 @@ var mysql = builder.AddMySql("mysql") .WithAdminer(); ``` -This will add a new resource to the app host which will be available from the .NET Aspire dashboard. +This will add a new resource to the AppHost which will be available from the .NET Aspire dashboard. diff --git a/docs/community-toolkit/hosting-postgresql-extensions.md b/docs/community-toolkit/hosting-postgresql-extensions.md index 02a345ce0a..bb7c8c6bad 100644 --- a/docs/community-toolkit/hosting-postgresql-extensions.md +++ b/docs/community-toolkit/hosting-postgresql-extensions.md @@ -54,4 +54,4 @@ var postgresServer = builder.AddPostgreSQL("PostgreSQL") .WithAdminer(); ``` -This will add a new resource to the app host which will be available from the .NET Aspire dashboard. +This will add a new resource to the AppHost which will be available from the .NET Aspire dashboard. diff --git a/docs/community-toolkit/hosting-python-extensions.md b/docs/community-toolkit/hosting-python-extensions.md index 37c3e6cc74..82af8a4429 100644 --- a/docs/community-toolkit/hosting-python-extensions.md +++ b/docs/community-toolkit/hosting-python-extensions.md @@ -44,7 +44,7 @@ The `PORT` environment variable is used to determine the port the Uvicorn applic # [Uvicorn](#tab/uvicorn) -In the _:::no-loc text="Program.cs":::_ file of your app host project, call the `AddUvicornApp` method to add a Uvicorn application to the builder. +In the _:::no-loc text="Program.cs":::_ file of your AppHost project, call the `AddUvicornApp` method to add a Uvicorn application to the builder. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -63,7 +63,7 @@ The Uvicorn application can be added as a reference to other resources in the Ap # [uv](#tab/uv) -In the _:::no-loc text="Program.cs":::_ file of your app host project, call the `AddUvApp` method to add a uv application to the builder. +In the _:::no-loc text="Program.cs":::_ file of your AppHost project, call the `AddUvApp` method to add a uv application to the builder. ```csharp var builder = DistributedApplication.CreateBuilder(args); diff --git a/docs/community-toolkit/hosting-redis-extensions.md b/docs/community-toolkit/hosting-redis-extensions.md index 840fce4a8e..5887834b27 100644 --- a/docs/community-toolkit/hosting-redis-extensions.md +++ b/docs/community-toolkit/hosting-redis-extensions.md @@ -46,4 +46,4 @@ var redis = builder.AddRedis("Redis") .WithDbGate(); ``` -This will add a new resource to the app host which will be available from the .NET Aspire dashboard. +This will add a new resource to the AppHost which will be available from the .NET Aspire dashboard. diff --git a/docs/community-toolkit/hosting-rust.md b/docs/community-toolkit/hosting-rust.md index 9ddfc3078a..8645bf96df 100644 --- a/docs/community-toolkit/hosting-rust.md +++ b/docs/community-toolkit/hosting-rust.md @@ -12,11 +12,11 @@ ms.date: 11/15/2024 [!INCLUDE [banner](includes/banner.md)] [Rust](https://www.rust-lang.org/) is a general-purpose programming language emphasizing performance, type safety, and concurrency. It enforces memory safety, meaning that all references point to valid memory. -The .NET Aspire Rust hosting integration allows you to host Rust applications in your .NET Aspire app host project, and provide it to other resources in your application. +The .NET Aspire Rust hosting integration allows you to host Rust applications in your .NET Aspire AppHost project, and provide it to other resources in your application. ## Hosting integration -The Rust hosting integration models a Rust application as the `Aspire.Hosting.ApplicationModel.RustAppExecutableResource` type. To access this type and APIs that allow you to add it to your app host project, install the [📦 CommunityToolkit.Aspire.Hosting.Rust](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Rust) NuGet package in the app host project. +The Rust hosting integration models a Rust application as the `Aspire.Hosting.ApplicationModel.RustAppExecutableResource` type. To access this type and APIs that allow you to add it to your AppHost project, install the [📦 CommunityToolkit.Aspire.Hosting.Rust](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Rust) NuGet package in the AppHost project. This integration expects that the Rust programming language has already been installed on the host machine and the Rust package manager [`cargo`](https://doc.rust-lang.org/cargo/getting-started/installation.html) is available in the system path. @@ -39,7 +39,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ## Add a Rust resource -In the _:::no-loc text="Program.cs":::_ file of your app host project, call the `Aspire.Hosting.RustAppHostingExtension.AddRustApp` on the `builder` instance to add a Rust application resource as shown in the following example: +In the _:::no-loc text="Program.cs":::_ file of your AppHost project, call the `Aspire.Hosting.RustAppHostingExtension.AddRustApp` on the `builder` instance to add a Rust application resource as shown in the following example: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -61,7 +61,7 @@ var rust = builder.AddRustApp("rust-app", workingDirectory: "../rust-service", a .WithHttpEndpoint(env: "PORT"); ``` -The Rust application can be added as a reference to other resources in the app host project. +The Rust application can be added as a reference to other resources in the AppHost project. ## See also diff --git a/docs/community-toolkit/hosting-sql-database-projects.md b/docs/community-toolkit/hosting-sql-database-projects.md index 11e03bf524..1135590355 100644 --- a/docs/community-toolkit/hosting-sql-database-projects.md +++ b/docs/community-toolkit/hosting-sql-database-projects.md @@ -19,7 +19,7 @@ This integration requires a SQL Database Project based on either [MSBuild.Sdk.Sq ## Hosting integration -To get started with the .NET Aspire SQL Database Projects hosting integration, install the [📦 CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects) NuGet package in the app host project. +To get started with the .NET Aspire SQL Database Projects hosting integration, install the [📦 CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.SqlDatabaseProjects) NuGet package in the AppHost project. ### [.NET CLI](#tab/dotnet-cli) @@ -40,7 +40,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ## Example usage -Add a reference to the [📦 MSBuild.Sdk.SqlProj](https://www.nuget.org/packages/MSBuild.Sdk.SqlProj) or [📦 Microsoft.Build.Sql](https://www.nuget.org/packages/Microsoft.Build.Sql) project you want to publish in your .NET Aspire app host project: +Add a reference to the [📦 MSBuild.Sdk.SqlProj](https://www.nuget.org/packages/MSBuild.Sdk.SqlProj) or [📦 Microsoft.Build.Sql](https://www.nuget.org/packages/Microsoft.Build.Sql) project you want to publish in your .NET Aspire AppHost project: ```dotnetcli dotnet add reference ../MySqlProj/MySqlProj.csproj @@ -61,11 +61,11 @@ builder.AddSqlProject("mysqlproj") .WithReference(sql); ``` -Now when you run your .NET Aspire app host project you see the SQL Database Project being published to the specified SQL Server. +Now when you run your .NET Aspire AppHost project you see the SQL Database Project being published to the specified SQL Server. ## NuGet Package support -Starting with version 9.2.0, you can deploy databases from referenced NuGet packages, such as those produced by [📦 MSBuild.Sdk.SqlProj](https://www.nuget.org/packages/MSBuild.Sdk.SqlProj) or [📦 Microsoft.Build.Sql](https://www.nuget.org/packages/Microsoft.Build.Sql). To deploy, add the NuGet package to your Aspire app host project, for example: +Starting with version 9.2.0, you can deploy databases from referenced NuGet packages, such as those produced by [📦 MSBuild.Sdk.SqlProj](https://www.nuget.org/packages/MSBuild.Sdk.SqlProj) or [📦 Microsoft.Build.Sql](https://www.nuget.org/packages/Microsoft.Build.Sql). To deploy, add the NuGet package to your Aspire AppHost project, for example: ```dotnetcli dotnet add package ErikEJ.Dacpac.Chinook @@ -91,7 +91,7 @@ builder.AddSqlPackage("chinook") ``` > [!NOTE] -> By default, the _.dacpac_ is expected to be located under `tools/.dacpac`. In the preceding example, the _tools/ErikEJ.Dacpac.Chinook.dacpac_ path is expected. If for whatever reason the _.dacpac_ is under a different path within the package you can use `WithDacpac("relative/path/to/some.dacpac")` API to specify a path relative to the root of app host project directory. +> By default, the _.dacpac_ is expected to be located under `tools/.dacpac`. In the preceding example, the _tools/ErikEJ.Dacpac.Chinook.dacpac_ path is expected. If for whatever reason the _.dacpac_ is under a different path within the package you can use `WithDacpac("relative/path/to/some.dacpac")` API to specify a path relative to the root of AppHost project directory. ### Local .dacpac file support @@ -149,7 +149,7 @@ The preceding code: ### Redeploy support -If you make changes to your SQL Database project while the app host is running, you can use the `Redeploy` custom action on the .NET Aspire dashboard to redeploy your updates without having to restart the app host. +If you make changes to your SQL Database project while the AppHost is running, you can use the `Redeploy` custom action on the .NET Aspire dashboard to redeploy your updates without having to restart the AppHost. ## See also diff --git a/docs/community-toolkit/hosting-sqlserver-extensions.md b/docs/community-toolkit/hosting-sqlserver-extensions.md index 249b5ec745..18581a83b1 100644 --- a/docs/community-toolkit/hosting-sqlserver-extensions.md +++ b/docs/community-toolkit/hosting-sqlserver-extensions.md @@ -54,4 +54,4 @@ var sqlserver = builder.AddSqlServer("sqlserver") .WithAdminer(); ``` -This will add a new resource to the app host which will be available from the .NET Aspire dashboard. +This will add a new resource to the AppHost which will be available from the .NET Aspire dashboard. diff --git a/docs/community-toolkit/includes/sqlite-hosting.md b/docs/community-toolkit/includes/sqlite-hosting.md index 7c2648952c..76be2383af 100644 --- a/docs/community-toolkit/includes/sqlite-hosting.md +++ b/docs/community-toolkit/includes/sqlite-hosting.md @@ -2,7 +2,7 @@ ms.topic: include --- -The SQLite hosting integration models a SQLite database as the `SQLiteResource` type and will create the database file in the specified location. To access these types and APIs that allow you to add the [📦 CommunityToolkit.Aspire.Hosting.SQLite](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.SQLite) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +The SQLite hosting integration models a SQLite database as the `SQLiteResource` type and will create the database file in the specified location. To access these types and APIs that allow you to add the [📦 CommunityToolkit.Aspire.Hosting.SQLite](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.SQLite) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -23,7 +23,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add SQLite resource -In the app host project, register and consume the SQLite integration using the `AddSQLite` extension method to add the SQLite database to the application builder. +In the AppHost project, register and consume the SQLite integration using the `AddSQLite` extension method to add the SQLite database to the application builder. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -34,7 +34,7 @@ var exampleProject = builder.AddProject() .WithReference(sqlite); ``` -When .NET Aspire adds a SQLite database to the app host, as shown in the preceding example, it creates a new SQLite database file in the users temp directory. +When .NET Aspire adds a SQLite database to the AppHost, as shown in the preceding example, it creates a new SQLite database file in the users temp directory. Alternatively, if you want to specify a custom location for the SQLite database file, provide the relevant arguments to the `AddSqlite` method. @@ -51,7 +51,7 @@ var sqlite = builder.AddSQLite("my-database") .WithSqliteWeb(); ``` -This code adds a container based on `ghcr.io/coleifer/sqlite-web` to the app host, which provides a web interface to interact with the SQLite database it is connected to. Each SQLiteWeb instance is connected to a single SQLite database, meaning that if you add multiple SQLiteWeb instances, there will be multiple SQLiteWeb containers. +This code adds a container based on `ghcr.io/coleifer/sqlite-web` to the AppHost, which provides a web interface to interact with the SQLite database it is connected to. Each SQLiteWeb instance is connected to a single SQLite database, meaning that if you add multiple SQLiteWeb instances, there will be multiple SQLiteWeb containers. ### Adding SQLite extensions diff --git a/docs/community-toolkit/ollama.md b/docs/community-toolkit/ollama.md index 6a28b93329..6508a35cb2 100644 --- a/docs/community-toolkit/ollama.md +++ b/docs/community-toolkit/ollama.md @@ -15,7 +15,7 @@ ms.custom: sfi-ropc-nochange ## Hosting integration -The Ollama hosting integration models an Ollama server as the `OllamaResource` type, and provides the ability to add models to the server using the `AddModel` extension method, which represents the model as an `OllamaModelResource` type. To access these types and APIs that allow you to add the [📦 CommunityToolkit.Aspire.Hosting.Ollama](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Ollama) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +The Ollama hosting integration models an Ollama server as the `OllamaResource` type, and provides the ability to add models to the server using the `AddModel` extension method, which represents the model as an `OllamaModelResource` type. To access these types and APIs that allow you to add the [📦 CommunityToolkit.Aspire.Hosting.Ollama](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.Ollama) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -36,7 +36,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add Ollama resource -In the app host project, register and consume the Ollama integration using the `AddOllama` extension method to add the Ollama container to the application builder. You can then add models to the container, which downloads and run when the container starts, using the `AddModel` extension method. +In the AppHost project, register and consume the Ollama integration using the `AddOllama` extension method to add the Ollama container to the application builder. You can then add models to the container, which downloads and run when the container starts, using the `AddModel` extension method. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -55,7 +55,7 @@ Alternatively, if you want to use a model from the [Hugging Face](https://huggin var llama = ollama.AddHuggingFaceModel("llama", "bartowski/Llama-3.2-1B-Instruct-GGUF:IQ4_XS"); ``` -When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `docker.io/ollama/ollama` image, it creates a new Ollama instance on your local machine. For more information, see [Container resource lifecycle](../fundamentals/orchestrate-resources.md#container-resource-lifecycle). +When .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `docker.io/ollama/ollama` image, it creates a new Ollama instance on your local machine. For more information, see [Container resource lifecycle](../fundamentals/orchestrate-resources.md#container-resource-lifecycle). ### Download the LLM @@ -136,7 +136,7 @@ dotnet add package CommunityToolkit.Aspire.OllamaSharp ### Add Ollama client API -In the _:::no-loc text="Program.cs":::_ file of your client-consuming project, call the `AddOllamaClientApi` extension to register an `IOllamaClientApi` for use via the dependency injection container. If the resource provided in the app host, and referenced in the client-consuming project, is an `OllamaModelResource`, then the `AddOllamaClientApi` method will register the model as the default model for the `IOllamaClientApi`. +In the _:::no-loc text="Program.cs":::_ file of your client-consuming project, call the `AddOllamaClientApi` extension to register an `IOllamaClientApi` for use via the dependency injection container. If the resource provided in the AppHost, and referenced in the client-consuming project, is an `OllamaModelResource`, then the `AddOllamaClientApi` method will register the model as the default model for the `IOllamaClientApi`. ```csharp builder.AddOllamaClientApi("llama3"); diff --git a/docs/community-toolkit/ravendb.md b/docs/community-toolkit/ravendb.md index 879c29c207..3b0b434d46 100644 --- a/docs/community-toolkit/ravendb.md +++ b/docs/community-toolkit/ravendb.md @@ -15,7 +15,7 @@ ms.date: 5/27/2025 ## Hosting integration -The RavenDB hosting integration models the server as the `RavenDBServerResource` type and the database as the `RavenDBDatabaseResource` type. To access these types and APIs, add the [📦 CommunityToolkit.Aspire.Hosting.RavenDB](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.RavenDB) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +The RavenDB hosting integration models the server as the `RavenDBServerResource` type and the database as the `RavenDBDatabaseResource` type. To access these types and APIs, add the [📦 CommunityToolkit.Aspire.Hosting.RavenDB](https://nuget.org/packages/CommunityToolkit.Aspire.Hosting.RavenDB) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -36,7 +36,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add RavenDB server resource and database resource -To set up RavenDB in your app host project, call one of the `AddRavenDB` extension methods on the `builder` instance to add a RavenDB server resource, then call `AddDatabase` on the server resource to add a database. Here’s an example: +To set up RavenDB in your AppHost project, call one of the `AddRavenDB` extension methods on the `builder` instance to add a RavenDB server resource, then call `AddDatabase` on the server resource to add a database. Here’s an example: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -54,7 +54,7 @@ builder.AddProject() > [!IMPORTANT] > A valid RavenDB license is required. If you don’t have one yet, you can request a free Community license [here](https://ravendb.net/license/request/community). -When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `docker.io/ravendb/ravendb` image, it creates a new RavenDB instance on your local machine. A reference to your RavenDB database resource (the `ravendb` variable) is added to the `ExampleProject`. +When .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `docker.io/ravendb/ravendb` image, it creates a new RavenDB instance on your local machine. A reference to your RavenDB database resource (the `ravendb` variable) is added to the `ExampleProject`. For more information, see [Container resource lifecycle](../fundamentals/orchestrate-resources.md#container-resource-lifecycle). @@ -126,7 +126,7 @@ The hosting integration relies on the [📦 AspNetCore.HealthChecks.RavenDB](htt ## Client integration -To get started with the .NET Aspire RavenDB client integration, install the [📦 CommunityToolkit.Aspire.RavenDB.Client](https://nuget.org/packages/CommunityToolkit.Aspire.RavenDB.Client) NuGet package in the client-consuming project, that is, the project for the application that uses the RavenDB client. The RavenDB client integration registers an [IDocumentStore](https://ravendb.net/docs/article-page/6.2/csharp/client-api/what-is-a-document-store) instance, which serves as the entry point for interacting with the RavenDB server resource or an existing RavenDB instance. If your app host includes RavenDB database resources, the associated [IDocumentSession](https://ravendb.net/docs/article-page/6.2/csharp/client-api/session/what-is-a-session-and-how-does-it-work) and [IAsyncDocumentSession](https://ravendb.net/docs/article-page/6.2/csharp/client-api/session/what-is-a-session-and-how-does-it-work) instances are also registered for dependency injection. +To get started with the .NET Aspire RavenDB client integration, install the [📦 CommunityToolkit.Aspire.RavenDB.Client](https://nuget.org/packages/CommunityToolkit.Aspire.RavenDB.Client) NuGet package in the client-consuming project, that is, the project for the application that uses the RavenDB client. The RavenDB client integration registers an [IDocumentStore](https://ravendb.net/docs/article-page/6.2/csharp/client-api/what-is-a-document-store) instance, which serves as the entry point for interacting with the RavenDB server resource or an existing RavenDB instance. If your AppHost includes RavenDB database resources, the associated [IDocumentSession](https://ravendb.net/docs/article-page/6.2/csharp/client-api/session/what-is-a-session-and-how-does-it-work) and [IAsyncDocumentSession](https://ravendb.net/docs/article-page/6.2/csharp/client-api/session/what-is-a-session-and-how-does-it-work) instances are also registered for dependency injection. ### [.NET CLI](#tab/dotnet-cli) @@ -152,7 +152,7 @@ builder.AddRavenDBClient(connectionName: "ravendb"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the RavenDB server resource (or the database resource, if provided) in the app host project. In other words, when you call `AddDatabase` and provide a name of `ravendb`, that same name should be used when calling `AddRavenDBClient`. For more information, see [Add RavenDB server resource and database resource](#add-ravendb-server-resource-and-database-resource). +> The `connectionName` parameter must match the name used when adding the RavenDB server resource (or the database resource, if provided) in the AppHost project. In other words, when you call `AddDatabase` and provide a name of `ravendb`, that same name should be used when calling `AddRavenDBClient`. For more information, see [Add RavenDB server resource and database resource](#add-ravendb-server-resource-and-database-resource). You can then retrieve the `IDocumentStore` instance using dependency injection. For example, to retrieve the client from an example service: diff --git a/docs/community-toolkit/sqlite-entity-framework-integration.md b/docs/community-toolkit/sqlite-entity-framework-integration.md index 6709620b36..d6c9835e35 100644 --- a/docs/community-toolkit/sqlite-entity-framework-integration.md +++ b/docs/community-toolkit/sqlite-entity-framework-integration.md @@ -43,7 +43,7 @@ builder.AddSqliteDbContext(connectionName: "sqlite"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the SQLite resource in the app host project. For more information, see [Add SQLite resource](#add-sqlite-resource). +> The `connectionName` parameter must match the name used when adding the SQLite resource in the AppHost project. For more information, see [Add SQLite resource](#add-sqlite-resource). After adding `YourDbContext` to the builder, you can get the `YourDbContext` instance using dependency injection. For example, to retrieve your data source object from an example service define it as a constructor parameter and ensure the `ExampleService` class is registered with the dependency injection container: @@ -68,7 +68,7 @@ builder.Services.AddDbContext(options => ``` > [!NOTE] -> The connection string name that you pass to the method must match the name used when adding the SQLite resource in the app host project. For more information, see [Add SQLite resource](#add-sqlite-resource). +> The connection string name that you pass to the method must match the name used when adding the SQLite resource in the AppHost project. For more information, see [Add SQLite resource](#add-sqlite-resource). ### Configuration diff --git a/docs/community-toolkit/sqlite.md b/docs/community-toolkit/sqlite.md index 0dd3b0de38..8ae4f456bb 100644 --- a/docs/community-toolkit/sqlite.md +++ b/docs/community-toolkit/sqlite.md @@ -43,7 +43,7 @@ builder.AddSqliteConnection(connectionName: "sqlite"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the SQLite resource in the app host project. For more information, see [Add SQLite resource](#add-sqlite-resource). +> The `connectionName` parameter must match the name used when adding the SQLite resource in the AppHost project. For more information, see [Add SQLite resource](#add-sqlite-resource). After adding `SqliteConnection` to the builder, you can get the `SqliteConnection` instance using dependency injection. For example, to retrieve your connection object from an example service define it as a constructor parameter and ensure the `ExampleService` class is registered with the dependency injection container: diff --git a/docs/compatibility/9.0/addpython.md b/docs/compatibility/9.0/addpython.md index 993c3873e4..09dfc266c7 100644 --- a/docs/compatibility/9.0/addpython.md +++ b/docs/compatibility/9.0/addpython.md @@ -7,7 +7,7 @@ ai-usage: ai-assisted # Python resources and APIs changed -When adding Python resources to your .NET Aspire app host, use the `AddPythonApp` method instead of the `AddPythonProject` method. The `AddPythonProject` method is now obsolete. Additionally, the `PythonProjectResource` class is now obsolete. Use the `PythonAppResource` class instead. +When adding Python resources to your .NET Aspire AppHost, use the `AddPythonApp` method instead of the `AddPythonProject` method. The `AddPythonProject` method is now obsolete. Additionally, the `PythonProjectResource` class is now obsolete. Use the `PythonAppResource` class instead. ## Version introduced @@ -15,11 +15,11 @@ When adding Python resources to your .NET Aspire app host, use the `AddPythonApp ## Previous behavior -The `AddPythonProject` method added a new `PythonProjectResource` to the app host. +The `AddPythonProject` method added a new `PythonProjectResource` to the AppHost. ## New behavior -The `AddPythonApp` method adds a new `PythonAppResource` to the app host. +The `AddPythonApp` method adds a new `PythonAppResource` to the AppHost. ## Type of breaking change @@ -27,7 +27,7 @@ This change is a [source compatibility](../categories.md#source-compatibility). ## Reason for change -This changes removes the concept of a Python project from the app host and instead uses the concept of a Python app. Project is an overloaded term that's reserved for .NET projects. The new term `PythonAppResource` is more accurate. +This changes removes the concept of a Python project from the AppHost and instead uses the concept of a Python app. Project is an overloaded term that's reserved for .NET projects. The new term `PythonAppResource` is more accurate. ## Recommended action diff --git a/docs/compatibility/9.0/make-unnamed-volumes-unique.md b/docs/compatibility/9.0/make-unnamed-volumes-unique.md index 1ce1a13f78..36449cb22a 100644 --- a/docs/compatibility/9.0/make-unnamed-volumes-unique.md +++ b/docs/compatibility/9.0/make-unnamed-volumes-unique.md @@ -7,7 +7,7 @@ ai-usage: ai-assisted # Make unnamed volume names more unique -This change updates the naming scheme for unnamed volumes to use the first 10 characters of the SHA256 of the app host's physical path as the volume name prefix. This ensures more unique volume names. +This change updates the naming scheme for unnamed volumes to use the first 10 characters of the SHA256 of the AppHost's physical path as the volume name prefix. This ensures more unique volume names. ## Version introduced @@ -19,7 +19,7 @@ Previously, unnamed volumes did not follow a specific scheme for uniqueness, whi ## New behavior -The new behavior uses the first 10 characters of the SHA256 of the app host's physical path as the volume name prefix, ensuring more unique volume names. +The new behavior uses the first 10 characters of the SHA256 of the AppHost's physical path as the volume name prefix, ensuring more unique volume names. ## Type of breaking change diff --git a/docs/compatibility/9.0/unnamed-volumes.md b/docs/compatibility/9.0/unnamed-volumes.md index 92f55093ad..da27c9e8f2 100644 --- a/docs/compatibility/9.0/unnamed-volumes.md +++ b/docs/compatibility/9.0/unnamed-volumes.md @@ -7,7 +7,7 @@ ai-usage: ai-assisted # Updates to implicitly named volumes to avoid collisions -The `WithDataVolume` methods create container volumes with names implicitly based on the App Host project name and resource name. This can lead to collisions when multiple App Host projects share the same name. +The `WithDataVolume` methods create container volumes with names implicitly based on the AppHost project name and resource name. This can lead to collisions when multiple AppHost projects share the same name. ## Version introduced @@ -15,11 +15,11 @@ The `WithDataVolume` methods create container volumes with names implicitly base ## Previous behavior -The implicit volume name is based on the App Host project name and resource name. For example, if the App Host project is named "TestShop.AppHost" and the resource is named "postgres", the implicit volume name will be "TestShop.AppHost-postgres-data". +The implicit volume name is based on the AppHost project name and resource name. For example, if the AppHost project is named "TestShop.AppHost" and the resource is named "postgres", the implicit volume name will be "TestShop.AppHost-postgres-data". ## New behavior -The implicit volume naming logic now includes a hash of the App Host project path or another deterministic, stable value derived from the App Host project. This prevents collisions of implicit volume names across different solutions. +The implicit volume naming logic now includes a hash of the AppHost project path or another deterministic, stable value derived from the AppHost project. This prevents collisions of implicit volume names across different solutions. ## Type of breaking change diff --git a/docs/compatibility/9.1/container-image-name-and-tag-updates.md b/docs/compatibility/9.1/container-image-name-and-tag-updates.md index fafc1efec7..20dd39cadb 100644 --- a/docs/compatibility/9.1/container-image-name-and-tag-updates.md +++ b/docs/compatibility/9.1/container-image-name-and-tag-updates.md @@ -26,7 +26,7 @@ In .NET Aspire 9.0: In .NET Aspire 9.1: - The default container image name used is now simply the resource name lowercased. -- The default container tag used is now a hash derived from the app host directory combined with a timestamp of when the method was called. +- The default container tag used is now a hash derived from the AppHost directory combined with a timestamp of when the method was called. ## Type of breaking change diff --git a/docs/compatibility/9.2/withauthentication-changes.md b/docs/compatibility/9.2/withauthentication-changes.md index ffd9e332d4..dde7b42c45 100644 --- a/docs/compatibility/9.2/withauthentication-changes.md +++ b/docs/compatibility/9.2/withauthentication-changes.md @@ -34,7 +34,7 @@ This is a [behavioral change](../categories.md#behavioral-change). ## Reason for change -This change moves resource management to the app host, making it easier to customize and manage resources. It allows sharing a key vault across multiple resources or using an existing key vault to manage connection strings and secrets. +This change moves resource management to the AppHost, making it easier to customize and manage resources. It allows sharing a key vault across multiple resources or using an existing key vault to manage connection strings and secrets. ## Recommended action diff --git a/docs/compatibility/9.3/remove-publisher-apis.md b/docs/compatibility/9.3/remove-publisher-apis.md index 81e3ed46e4..4f1eade8d5 100644 --- a/docs/compatibility/9.3/remove-publisher-apis.md +++ b/docs/compatibility/9.3/remove-publisher-apis.md @@ -1,7 +1,7 @@ --- title: "Breaking change - Removal of DockerComposePublisher, KubernetesPublisher, and AzurePublisher" description: "Learn about the breaking change in .NET Aspire 9.3 where publisher APIs were removed in favor of new resource types." -ms.date: 5/12/2025 +ms.date: 08/07/2025 ai-usage: ai-assisted ms.custom: https://github.com/dotnet/docs-aspire/issues/3373 --- @@ -34,11 +34,9 @@ Multiple publishers could be added, and the `aspire publish` CLI command allowed In .NET Aspire 9.3, the publishers are now replaced with new resource types: - - -- `DockerComposeEnvironmentResource` -- `KubernetesEnvironmentResource` -- `AzureEnvironmentResource` (Automatically added when you use any Azure resource) +- +- +- (Automatically added when you use any Azure resource) These resources include a `PublisherCallbackAnnotation` that defines their publishing behavior. The default publisher now automatically processes all resources with this annotation to generate assets. The `aspire publish` command no longer requires selecting a publisher; it uses the default publisher to handle all annotated resources. diff --git a/docs/database/azure-cosmos-db-entity-framework-integration.md b/docs/database/azure-cosmos-db-entity-framework-integration.md index 5e68770928..8b425df522 100644 --- a/docs/database/azure-cosmos-db-entity-framework-integration.md +++ b/docs/database/azure-cosmos-db-entity-framework-integration.md @@ -56,7 +56,7 @@ builder.AddCosmosDbContext("cosmosdb"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Cosmos DB resource in the app host project. In other words, when you call `AddAzureCosmosDB` and provide a name of `cosmosdb` that same name should be used when calling `AddCosmosDbContext`. For more information, see [Add Azure Cosmos DB resource](#add-azure-cosmos-db-resource). +> The `connectionName` parameter must match the name used when adding the Cosmos DB resource in the AppHost project. In other words, when you call `AddAzureCosmosDB` and provide a name of `cosmosdb` that same name should be used when calling `AddCosmosDbContext`. For more information, see [Add Azure Cosmos DB resource](#add-azure-cosmos-db-resource). You can then retrieve the instance using dependency injection. For example, to retrieve the client from a service: diff --git a/docs/database/azure-cosmos-db-integration.md b/docs/database/azure-cosmos-db-integration.md index 5e9169822e..e079b1d001 100644 --- a/docs/database/azure-cosmos-db-integration.md +++ b/docs/database/azure-cosmos-db-integration.md @@ -1,7 +1,7 @@ --- title: .NET Aspire Azure Cosmos DB integration description: Learn how to install and configure the .NET Aspire Azure Cosmos DB integration to connect to existing Cosmos DB instances or create new instances from .NET with the Azure Cosmos DB emulator. -ms.date: 05/15/2025 +ms.date: 08/07/2025 uid: dotnet/aspire/azure-cosmos-db-integration ms.custom: sfi-ropc-nochange --- @@ -52,7 +52,7 @@ builder.AddAzureCosmosClient(connectionName: "cosmos-db"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Cosmos DB resource in the app host project. In other words, when you call `AddAzureCosmosDB` and provide a name of `cosmos-db` that same name should be used when calling `AddAzureCosmosClient`. For more information, see [Add Azure Cosmos DB resource](#add-azure-cosmos-db-resource). +> The `connectionName` parameter must match the name used when adding the Cosmos DB resource in the AppHost project. In other words, when you call `AddAzureCosmosDB` and provide a name of `cosmos-db` that same name should be used when calling `AddAzureCosmosClient`. For more information, see [Add Azure Cosmos DB resource](#add-azure-cosmos-db-resource). You can then retrieve the instance using dependency injection. For example, to retrieve the client from an example service: @@ -92,17 +92,13 @@ For more information on keyed services, see [.NET dependency injection: Keyed se ### Add Azure Cosmos DB database - - -In the app host, the database resource (`AzureCosmosDBDatabaseResource`) can be added as a child resource to the parent . In your client-consuming project, you can deep-link to the database resource by name, registering a instance for use with dependency injection. For example, consider the following code that calls `AddAzureCosmosDatabase` on an instance: +In the AppHost, the database resource () can be added as a child resource to the parent . In your client-consuming project, you can deep-link to the database resource by name, registering a instance for use with dependency injection. For example, consider the following code that calls on an instance: ```csharp builder.AddAzureCosmosDatabase(connectionName: "customers"); ``` - - -The `AddAzureCosmosDatabase` API returns a `CosmosDatabaseBuilder` instance that you can use to attach multiple containers under the same database connection. All child containers share the same and database connection and `CosmosClient` instance. This strategy is useful when associating the same with multiple containers. +The `AddAzureCosmosDatabase` API returns a instance that you can use to attach multiple containers under the same database connection. All child containers share the same and database connection and `CosmosClient` instance. This strategy is useful when associating the same with multiple containers. After calling `AddAzureCosmosDatabase`, you can then retrieve the `Database` instance using dependency injection. For example, to retrieve the database from a delegate in a call consider the following code: @@ -115,9 +111,7 @@ app.MapGet("/api/customers", async (Database database) => ### Add keyed Azure Cosmos DB database - - -There's also an `AddKeyedAzureCosmosDatabase` API that returns a `CosmosDatabaseBuilder` instance that you can use to attach multiple containers under the same database connection. method that allows you to register multiple databases with different connection names. For example, consider the following code that calls `AddKeyedAzureCosmosDatabase` on an instance: +There's also an API that returns a `CosmosDatabaseBuilder` instance that you can use to attach multiple containers under the same database connection. method that allows you to register multiple databases with different connection names. For example, consider the following code that calls `AddKeyedAzureCosmosDatabase` on an instance: ```csharp var builder = WebApplication.CreateBuilder(args); @@ -147,9 +141,7 @@ The preceding example code demonstrates how to register two databases, `details` ### Add Azure Cosmos DB container - - -When you add a Cosmos DB resource in the app host project, you can also add an Azure Cosmos DB container resource as well. The container resource is considered a child resource to the parent `AzureCosmosDBDatabaseResource`. In your client-consuming project, you can deep-link to the container resource by name, registering a instance for use with dependency injection. For example, consider the following code that calls `AddAzureCosmosContainer` on an instance: +When you add a Cosmos DB resource in the AppHost project, you can also add an Azure Cosmos DB container resource as well. The container resource is considered a child resource to the parent `AzureCosmosDBDatabaseResource`. In your client-consuming project, you can deep-link to the container resource by name, registering a instance for use with dependency injection. For example, consider the following code that calls on an instance: ```csharp builder.AddAzureCosmosContainer(connectionName: "details"); @@ -168,9 +160,7 @@ app.MapGet("/api/orders/{id:guid}", async ( ### Add keyed Azure Cosmos DB container - - -There's also an `AddKeyedAzureCosmosContainer` method that allows you to register multiple containers with different connection names. For example, consider the following code that calls `AddKeyedAzureCosmosContainer` on an instance: +There's also an method that allows you to register multiple containers with different connection names. For example, consider the following code that calls `AddKeyedAzureCosmosContainer` on an instance: ```csharp var builder = WebApplication.CreateBuilder(args); diff --git a/docs/database/azure-sql-entity-framework-integration.md b/docs/database/azure-sql-entity-framework-integration.md index d51ef3311b..68117f02db 100644 --- a/docs/database/azure-sql-entity-framework-integration.md +++ b/docs/database/azure-sql-entity-framework-integration.md @@ -9,7 +9,7 @@ uid: database/azure-sql-entity-framework-integration [!INCLUDE [includes-hosting-and-client](../includes/includes-hosting-and-client.md)] -[Azure SQL](https://azure.microsoft.com/products/azure-sql) is a family of relational database management systems that run in the Azure cloud. The database systems are Platform-as-a-Service (PaaS) products that enable database administrators to implement highly scalable and available databases without maintaining complex infrastructures themselves. The .NET Aspire Azure SQL Server Hosting integration provides methods to create a new Azure Database server and databases from code in your .NET Aspire app host project. In a consuming project, you can use the .NET Aspire SQL Server Entity Framework Core client integration as you would for any other SQL Server instance. +[Azure SQL](https://azure.microsoft.com/products/azure-sql) is a family of relational database management systems that run in the Azure cloud. The database systems are Platform-as-a-Service (PaaS) products that enable database administrators to implement highly scalable and available databases without maintaining complex infrastructures themselves. The .NET Aspire Azure SQL Server Hosting integration provides methods to create a new Azure Database server and databases from code in your .NET Aspire AppHost project. In a consuming project, you can use the .NET Aspire SQL Server Entity Framework Core client integration as you would for any other SQL Server instance. ## Hosting integration diff --git a/docs/database/azure-sql-integration.md b/docs/database/azure-sql-integration.md index 7b7e0a41f0..87b23ed0d7 100644 --- a/docs/database/azure-sql-integration.md +++ b/docs/database/azure-sql-integration.md @@ -9,7 +9,7 @@ uid: database/azure-sql-integration [!INCLUDE [includes-hosting-and-client](../includes/includes-hosting-and-client.md)] -[Azure SQL](https://azure.microsoft.com/products/azure-sql) is a family of relational database management systems that run in the Azure cloud. The database systems are Platform-as-a-Service (PaaS) products that enable database administrators to implement highly scalable and available databases without maintaining complex infrastructures themselves. The .NET Aspire Azure SQL Server Hosting integration provides methods to create a new Azure Database server and databases from code in your .NET Aspire app host project. In a consuming project, you can use the .NET Aspire SQL Server client integration as you would for any other SQL Server instance. +[Azure SQL](https://azure.microsoft.com/products/azure-sql) is a family of relational database management systems that run in the Azure cloud. The database systems are Platform-as-a-Service (PaaS) products that enable database administrators to implement highly scalable and available databases without maintaining complex infrastructures themselves. The .NET Aspire Azure SQL Server Hosting integration provides methods to create a new Azure Database server and databases from code in your .NET Aspire AppHost project. In a consuming project, you can use the .NET Aspire SQL Server client integration as you would for any other SQL Server instance. ## Hosting integration diff --git a/docs/database/connect-to-existing-database.md b/docs/database/connect-to-existing-database.md index b31442af25..16dcc2d1a4 100644 --- a/docs/database/connect-to-existing-database.md +++ b/docs/database/connect-to-existing-database.md @@ -16,7 +16,7 @@ In this tutorial, you create a .NET Aspire solution with an API that connects to > [!div class="checklist"] > > - Create an API microservice that interacts with a database. -> - Configure the .NET Aspire App Host project with a connection string for the existing database. +> - Configure the .NET Aspire AppHost project with a connection string for the existing database. > - Pass the connection string to the API and use it to connect to the database. [!INCLUDE [aspire-prereqs](../includes/aspire-prereqs.md)] @@ -170,13 +170,13 @@ You'll use the Scalar UI to test the _AspireExistingDB.ApiService_ project. Let' } ``` -## Configure a connection string in the App Host project +## Configure a connection string in the AppHost project :::zone pivot="sql-server-ef" Usually, when you create a cloud-native solution with .NET Aspire, you call the method to initiate a container that runs the SQL Server instance. You pass that resource to other projects in your solution that need access to the database. -In this case, however, you want to work with an existing database outside of any container. There are three differences in the App Host project: +In this case, however, you want to work with an existing database outside of any container. There are three differences in the AppHost project: - You don't need to install the `Aspire.Hosting.SqlServer` hosting integration. - You add a connection string in a configuration file, such as **appsetting.json**. @@ -220,7 +220,7 @@ Let's implement that configuration: Usually, when you create a cloud-native solution with .NET Aspire, you call the method to initiate a container that runs the PostgreSQL instance. You pass that resource to other projects in your solution that need access to the database. -In this case, however, you want to work with an existing database outside of any container. There are three differences in the App Host project: +In this case, however, you want to work with an existing database outside of any container. There are three differences in the AppHost project: - You don't need to install the `Aspire.Hosting.PostgreSQL` hosting integration. - You add a connection string in a configuration file, such as **appsetting.json**. @@ -264,7 +264,7 @@ Let's implement that configuration: Usually, when you create a cloud-native solution with .NET Aspire, you call the method to initiate a container that runs the Oracle Database instance. You pass that resource to other projects in your solution that need access to the database. -In this case, however, you want to work with an existing database outside of any container. There are three differences in the App Host project: +In this case, however, you want to work with an existing database outside of any container. There are three differences in the AppHost project: - You don't need to install the `Aspire.Hosting.Oracle` hosting integration. - You add a connection string in a configuration file, such as **appsetting.json**. @@ -308,7 +308,7 @@ Let's implement that configuration: Usually, when you create a cloud-native solution with .NET Aspire, you call the method to initiate a container that runs the MySQL instance. You pass that resource to other projects in your solution that need access to the database. -In this case, however, you want to work with an existing database outside of any container. There are three differences in the App Host project: +In this case, however, you want to work with an existing database outside of any container. There are three differences in the AppHost project: - You don't need to install the `Aspire.Hosting.MySQL` hosting integration. - You add a connection string in a configuration file, such as **appsetting.json**. @@ -368,7 +368,7 @@ Let's implement that configuration: ## Use the database in the API project -Returning to the _AspireExistingDB.ApiService_ project, you must obtain the connection string resource from the App Host, and then use it to create the database: +Returning to the _AspireExistingDB.ApiService_ project, you must obtain the connection string resource from the AppHost, and then use it to create the database: 1. In Visual Studio, in the _AspireExistingDB.ApiService_ project, open the _Program.cs_ file. 1. Locate the following line of code: diff --git a/docs/database/ef-core-migrations.md b/docs/database/ef-core-migrations.md index 6a8b54a2bf..875e122d44 100644 --- a/docs/database/ef-core-migrations.md +++ b/docs/database/ef-core-migrations.md @@ -26,7 +26,7 @@ git clone https://github.com/MicrosoftDocs/aspire-docs-samples/ The sample app is in the *SupportTicketApi* folder. Open the solution in Visual Studio or VS Code and take a moment to review the sample app and make sure it runs before proceeding. The sample app is a rudimentary support ticket API, and it contains the following projects: - **SupportTicketApi.Api**: The ASP.NET Core project that hosts the API. -- **SupportTicketApi.AppHost**: Contains the .NET Aspire app host and configuration. +- **SupportTicketApi.AppHost**: Contains the .NET Aspire AppHost and configuration. - **SupportTicketApi.Data**: Contains the EF Core contexts and models. - **SupportTicketApi.ServiceDefaults**: Contains the default service configurations. @@ -115,7 +115,7 @@ If you get an error like "No database provider has been configured for this DbCo **Solution**: Temporarily add a connection string to your project's `appsettings.json` file: 1. In your API project (where the DbContext is registered), open or create an `appsettings.json` file. -1. Add a connection string with the same name used in your .NET Aspire app host: +1. Add a connection string with the same name used in your .NET Aspire AppHost: ```json { @@ -129,7 +129,7 @@ If you get an error like "No database provider has been configured for this DbCo 1. Remove the connection string from `appsettings.json` when you're done, as .NET Aspire will provide it at runtime. > [!TIP] -> The connection string name must match what you use in your app host. For example, if you use `builder.AddProject().WithReference(sqlServer.AddDatabase("ticketdb"))`, then use "ticketdb" as the connection string name. +> The connection string name must match what you use in your AppHost. For example, if you use `builder.AddProject().WithReference(sqlServer.AddDatabase("ticketdb"))`, then use "ticketdb" as the connection string name. ### Multiple databases in one solution @@ -213,14 +213,14 @@ To create a service that applies the migrations: ## Add the migration service to the orchestrator -The migration service is created, but it needs to be added to the .NET Aspire app host so that it runs when the app starts. +The migration service is created, but it needs to be added to the .NET Aspire AppHost so that it runs when the app starts. 1. In the *:::no-loc text="SupportTicketApi.AppHost":::* project, open the *:::no-loc text="Program.cs":::* file. 1. Add the following highlighted code: :::code source="~/aspire-docs-samples-solution/SupportTicketApi/SupportTicketApi.AppHost/Program.cs" highlight="7-9, 13-14" ::: - This code enlists the *:::no-loc text="SupportTicketApi.MigrationService":::* project as a service in the .NET Aspire app host. It also ensures that the API resource doesn't run until the migrations are complete. + This code enlists the *:::no-loc text="SupportTicketApi.MigrationService":::* project as a service in the .NET Aspire AppHost. It also ensures that the API resource doesn't run until the migrations are complete. > [!NOTE] > In the preceding code, the call to adds a representation of a SQL Server database to the .NET Aspire application model with a connection string. It *doesn't* create a database in the SQL Server container. To ensure that the database is created, the sample project calls the EF Core method from the support ticket API's *:::no-loc text="Program.cs":::* file. @@ -253,7 +253,7 @@ Create a dedicated migration service for each database. This approach provides b ``` 1. Configure each migration service to handle its specific database context. -1. Add both migration services to your app host: +1. Add both migration services to your AppHost: ```csharp var firstDb = sqlServer.AddDatabase("firstdb"); diff --git a/docs/database/entity-framework-core-integration-overview.md b/docs/database/entity-framework-core-integration-overview.md index fd7c2be312..6e39e15eff 100644 --- a/docs/database/entity-framework-core-integration-overview.md +++ b/docs/database/entity-framework-core-integration-overview.md @@ -86,17 +86,17 @@ using (var db = new TicketContext()) If you want to use EF Core in any of your microservices, .NET Aspire can help by: -- Managing the database container, or a connection to an existing database, centrally in the App Host project and passing its reference to any project that uses it. +- Managing the database container, or a connection to an existing database, centrally in the AppHost project and passing its reference to any project that uses it. > [!IMPORTANT] - > In .NET Aspire, EF Core is implemented by client integrations, not hosting integrations. The centralized management of the database in the App Host doesn't involve EF Core, which runs in consuming microservice projects instead. For more information, see [Cosmos DB Hosting integration](/dotnet/aspire/database/azure-cosmos-db-entity-framework-integration#hosting-integration), [MySQL Pomelo Hosting integration](/dotnet/aspire/database/mysql-entity-framework-integration#hosting-integration), [Oracle Hosting integration](/dotnet/aspire/database/oracle-entity-framework-integration#hosting-integration), [PostgreSQL Hosting integration](/dotnet/aspire/database/postgresql-entity-framework-integration#hosting-integration), or [SQL Server Hosting integration](/dotnet/aspire/database/sql-server-entity-framework-integration#hosting-integration). + > In .NET Aspire, EF Core is implemented by client integrations, not hosting integrations. The centralized management of the database in the AppHost doesn't involve EF Core, which runs in consuming microservice projects instead. For more information, see [Cosmos DB Hosting integration](/dotnet/aspire/database/azure-cosmos-db-entity-framework-integration#hosting-integration), [MySQL Pomelo Hosting integration](/dotnet/aspire/database/mysql-entity-framework-integration#hosting-integration), [Oracle Hosting integration](/dotnet/aspire/database/oracle-entity-framework-integration#hosting-integration), [PostgreSQL Hosting integration](/dotnet/aspire/database/postgresql-entity-framework-integration#hosting-integration), or [SQL Server Hosting integration](/dotnet/aspire/database/sql-server-entity-framework-integration#hosting-integration). - Providing EF Core-aware integrations that make it easy to create contexts in microservice projects. There are EF Core integrations for SQL Server, MySQL, PostgreSQL, Oracle, Cosmos DB, and other popular database systems. To use EF Core in your microservice, you must: - Define the EF Core model with entity classes and context classes. -- Create an instance of the data context, using the reference passed from the App Host, and add it to the Dependency Injection (DI) container. +- Create an instance of the data context, using the reference passed from the AppHost, and add it to the Dependency Injection (DI) container. - When you want to interact with the database, obtain the context from DI and use it to execute LINQ queries against the database as normal for any EF Core code. :::image type="content" source="media/ef-core-aspire-architecture-thumb.png" lightbox="media/ef-core-aspire-architecture-large.png" alt-text="A diagram showing how .NET Aspire utilizes EF Core to interact with a database.." ::: @@ -112,7 +112,7 @@ The .NET Aspire EF Core client integrations each include extension methods named These .NET Aspire add context methods: - Check that a context of the same type isn't already registered in the dependency injection (DI) container. -- Use the connection name you pass to the method to get the connection string from the application builder. This connection name must match the name used when adding the corresponding resource to the app host project. +- Use the connection name you pass to the method to get the connection string from the application builder. This connection name must match the name used when adding the corresponding resource to the AppHost project. - Apply the `DbContext` options, if you passed them. - Add the specified `DbContext` to the DI container with context pooling enabled. - Apply the recommended defaults, unless you've disabled them through the .NET Aspire EF Core settings: diff --git a/docs/database/includes/azure-postgresql-client.md b/docs/database/includes/azure-postgresql-client.md index 4d07d753f1..51a4b46079 100644 --- a/docs/database/includes/azure-postgresql-client.md +++ b/docs/database/includes/azure-postgresql-client.md @@ -20,16 +20,14 @@ dotnet add package Aspire.Azure.Npgsql --- - - -The PostgreSQL connection can be consumed using the client integration by calling the `AddAzureNpgsqlDataSource`: +The PostgreSQL connection can be consumed using the client integration by calling the : ```csharp builder.AddAzureNpgsqlDataSource(connectionName: "postgresdb"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the PostgreSQL server resource in the app host project. +> The `connectionName` parameter must match the name used when adding the PostgreSQL server resource in the AppHost project. The preceding code snippet demonstrates how to use the `AddAzureNpgsqlDataSource` method to register an `NpgsqlDataSource` instance that uses Azure authentication ([Microsoft Entra ID](/azure/postgresql/flexible-server/concepts-azure-ad-authentication)). This `"postgresdb"` connection name corresponds to a connection string configuration value. @@ -46,9 +44,7 @@ For more information on dependency injection, see [.NET dependency injection](/d ### Add keyed Azure Npgsql client - - -There might be situations where you want to register multiple `NpgsqlDataSource` instances with different connection names. To register keyed Npgsql clients, call the `AddKeyedAzureNpgsqlDataSource` method: +There might be situations where you want to register multiple `NpgsqlDataSource` instances with different connection names. To register keyed Npgsql clients, call the method: ```csharp builder.AddKeyedAzureNpgsqlDataSource(name: "sales_db"); @@ -97,9 +93,7 @@ For more information on how to configure the connection string, see the [Npgsql ##### Use configuration providers - - -The .NET Aspire Azure Npgsql integration supports . It loads the `AzureNpgsqlSettings` from configuration using the `Aspire:Azure:Npgsql` key. For example, consider the following _appsettings.json_ file that configures some of the available options: +The .NET Aspire Azure Npgsql integration supports . It loads the from configuration using the `Aspire:Azure:Npgsql` key. For example, consider the following _appsettings.json_ file that configures some of the available options: ```json { @@ -122,9 +116,7 @@ builder.AddAzureNpgsqlDataSource( settings => settings.DisableHealthChecks = true); ``` - - -Use the `AzureNpgsqlSettings.Credential` property to establish a connection. If no credential is configured, the is used. When the connection string contains a username and password, the credential is ignored. +Use the property to establish a connection. If no credential is configured, the is used. When the connection string contains a username and password, the credential is ignored. [!INCLUDE [client-integration-health-checks](../../includes/client-integration-health-checks.md)] diff --git a/docs/database/includes/azure-postgresql-ef-client.md b/docs/database/includes/azure-postgresql-ef-client.md index c488a7d6c6..9cab0a1366 100644 --- a/docs/database/includes/azure-postgresql-ef-client.md +++ b/docs/database/includes/azure-postgresql-ef-client.md @@ -20,18 +20,16 @@ dotnet add package Aspire.Azure.Npgsql.EntityFrameworkCore.PostgreSQL --- - - -The PostgreSQL connection can be consumed using the client integration by calling the `AddAzureNpgsqlDataSource`: +The PostgreSQL connection can be consumed using the client integration by calling the `AddAzureNpgsqlDbContext`: ```csharp builder.AddAzureNpgsqlDbContext(connectionName: "postgresdb"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the PostgreSQL server resource in the app host project. +> The `connectionName` parameter must match the name used when adding the PostgreSQL server resource in the AppHost project. -The preceding code snippet demonstrates how to use the `AddAzureNpgsqlDbContext` method to register an `YourDbContext` (that's [pooled for performance](/ef/core/performance/advanced-performance-topics)) instance that uses Azure authentication ([Microsoft Entra ID](/azure/postgresql/flexible-server/concepts-azure-ad-authentication)). This `"postgresdb"` connection name corresponds to a connection string configuration value. +The preceding code snippet demonstrates how to use the method to register an `YourDbContext` (that's [pooled for performance](/ef/core/performance/advanced-performance-topics)) instance that uses Azure authentication ([Microsoft Entra ID](/azure/postgresql/flexible-server/concepts-azure-ad-authentication)). This `"postgresdb"` connection name corresponds to a connection string configuration value. After adding `YourDbContext` to the builder, you can get the `YourDbContext` instance using dependency injection. For example, to retrieve your data source object from an example service define it as a constructor parameter and ensure the `ExampleService` class is registered with the dependency injection container: @@ -55,7 +53,7 @@ builder.Services.AddDbContext(options => ``` > [!NOTE] -> The connection string name that you pass to the method must match the name used when adding the PostgreSQL server resource in the app host project. For more information, see [Add PostgreSQL server resource](#add-postgresql-server-resource). +> The connection string name that you pass to the method must match the name used when adding the PostgreSQL server resource in the AppHost project. For more information, see [Add PostgreSQL server resource](#add-postgresql-server-resource). You have more flexibility when you create the database context in this way, for example: @@ -74,11 +72,9 @@ builder.EnrichAzureNpgsqlDbContext( }); ``` -The `settings` parameter is an instance of the `AzureNpgsqlEntityFrameworkCorePostgreSQLSettings` class. - - +The `settings` parameter is an instance of the class. -You might also need to configure specific options of Npgsql, or register a in other ways. In this case, you do so by calling the `EnrichAzureNpgsqlDbContext` extension method, as shown in the following example: +You might also need to configure specific options of Npgsql, or register a in other ways. In this case, you do so by calling the extension method, as shown in the following example: ```csharp var connectionString = builder.Configuration.GetConnectionString("postgresdb"); @@ -118,9 +114,7 @@ For more information on how to configure the connection string, see the [Npgsql ##### Use configuration providers - - -The .NET Aspire Azure PostgreSQL EntityFrameworkCore Npgsql integration supports . It loads the `AzureNpgsqlEntityFrameworkCorePostgreSQLSettings` from configuration using the `Aspire:Npgsql:EntityFrameworkCore:PostgreSQL` key. For example, consider the following _appsettings.json_ file that configures some of the available options: +The .NET Aspire Azure PostgreSQL EntityFrameworkCore Npgsql integration supports . It loads the from configuration using the `Aspire:Npgsql:EntityFrameworkCore:PostgreSQL` key. For example, consider the following _appsettings.json_ file that configures some of the available options: ```json { @@ -154,9 +148,7 @@ builder.EnrichAzureNpgsqlDbContext( settings => settings.DisableHealthChecks = true); ``` - - -Use the `AzureNpgsqlEntityFrameworkCorePostgreSQLSettings.Credential` property to establish a connection. If no credential is configured, the is used. +Use the property to establish a connection. If no credential is configured, the is used. When the connection string contains a username and password, the credential is ignored. diff --git a/docs/database/includes/azure-sql-hosting.md b/docs/database/includes/azure-sql-hosting.md index 9cdb2ce294..8f5822c06e 100644 --- a/docs/database/includes/azure-sql-hosting.md +++ b/docs/database/includes/azure-sql-hosting.md @@ -2,7 +2,7 @@ ms.topic: include --- -The Azure SQL hosting integration models the Azure SQL server as the type and the database as the type. To access these types and APIs, add the [📦 Aspire.Hosting.Azure.Sql](https://www.nuget.org/packages/Aspire.Hosting.Azure.Sql) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +The Azure SQL hosting integration models the Azure SQL server as the type and the database as the type. To access these types and APIs, add the [📦 Aspire.Hosting.Azure.Sql](https://www.nuget.org/packages/Aspire.Hosting.Azure.Sql) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -25,7 +25,7 @@ The Azure SQL hosting integration takes a dependency on the [📦 Aspire.Hosting ### Add Azure SQL server resource and database resource -In your app host project, call to add and return an Azure SQL server resource builder. Chain a call to the returned resource builder to , to add an Azure SQL database resource: +In your AppHost project, call to add and return an Azure SQL server resource builder. Chain a call to the returned resource builder to , to add an Azure SQL database resource: ```csharp var azureSql = builder.AddAzureSqlServer("azuresql") @@ -68,7 +68,7 @@ builder.AddProject() For more information on treating Azure SQL Database resources as existing resources, see [Use existing Azure resources](../../azure/integrations-overview.md#use-existing-azure-resources). > [!NOTE] -> Alternatively, instead of representing an Azure SQL Database resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). +> Alternatively, instead of representing an Azure SQL Database resource, you can add a connection string to the AppHost. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). ### Run Azure SQL server resource as a container diff --git a/docs/database/includes/cosmos-app-host.md b/docs/database/includes/cosmos-app-host.md index 4e46064275..a3d5f13da4 100644 --- a/docs/database/includes/cosmos-app-host.md +++ b/docs/database/includes/cosmos-app-host.md @@ -9,7 +9,7 @@ The .NET Aspire [Azure Cosmos DB](https://azure.microsoft.com/services/cosmos-db - : Represents an Azure Cosmos DB database resource. - : Represents an Azure Cosmos DB emulator resource. -To access these types and APIs for expressing them, add the [📦 Aspire.Hosting.Azure.CosmosDB](https://www.nuget.org/packages/Aspire.Hosting.Azure.CosmosDB) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +To access these types and APIs for expressing them, add the [📦 Aspire.Hosting.Azure.CosmosDB](https://www.nuget.org/packages/Aspire.Hosting.Azure.CosmosDB) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -30,7 +30,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add Azure Cosmos DB resource -In your app host project, call to add and return an Azure Cosmos DB resource builder. +In your AppHost project, call to add and return an Azure Cosmos DB resource builder. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -40,7 +40,7 @@ var cosmos = builder.AddAzureCosmosDB("cosmos-db"); // After adding all resources, run the app... ``` -When you add an to the app host, it exposes other useful APIs to add databases and containers. In other words, you must add an `AzureCosmosDBResource` before adding any of the other Cosmos DB resources. +When you add an to the AppHost, it exposes other useful APIs to add databases and containers. In other words, you must add an `AzureCosmosDBResource` before adding any of the other Cosmos DB resources. > [!IMPORTANT] > When you call , it implicitly calls —which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see [Local provisioning: Configuration](../../azure/local-provisioning.md#configuration). @@ -98,7 +98,7 @@ builder.AddProject("web") For more information on treating Azure Cosmos DB resources as existing resources, see [Use existing Azure resources](../../azure/integrations-overview.md#use-existing-azure-resources). > [!NOTE] -> Alternatively, instead of representing an Azure Cosmos DB resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). +> Alternatively, instead of representing an Azure Cosmos DB resource, you can add a connection string to the AppHost. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). ### Add Azure Cosmos DB database and container resources @@ -163,7 +163,7 @@ The following diagram illustrates the parent child relationship between the Azur :::image type="content" source="media/cosmos-resource-relationships-thumb.png" alt-text="A diagram depicting Azure Cosmos DB resource parent child relationships." lightbox="media/cosmos-resource-relationships.png"::: -When your app host code expresses parent-child relationships, the client can deep-link to these resources by name. For example, the `customers` database can be referenced by name in the client project, registering a instance that connects to the `customers` database. The same applies to named containers, for example, the `details` container can be referenced by name in the client project, registering a instance that connects to the `details` container. +When your AppHost code expresses parent-child relationships, the client can deep-link to these resources by name. For example, the `customers` database can be referenced by name in the client project, registering a instance that connects to the `customers` database. The same applies to named containers, for example, the `details` container can be referenced by name in the client project, registering a instance that connects to the `details` container. ### Add Azure Cosmos DB emulator resource @@ -178,7 +178,7 @@ var cosmos = builder.AddAzureCosmosDB("cosmos-db") // After adding all resources, run the app... ``` -When you call `RunAsEmulator`, it configures your Cosmos DB resources to run locally using an emulator. The emulator in this case is the [Azure Cosmos DB Emulator](/azure/cosmos-db/local-emulator). The Azure Cosmos DB Emulator provides a free local environment for testing your Azure Cosmos DB apps and it's a perfect companion to the .NET Aspire Azure hosting integration. The emulator isn't installed, instead, it's accessible to .NET Aspire as a container. When you add a container to the app host, as shown in the preceding example with the `mcr.microsoft.com/cosmosdb/emulator` image, it creates and starts the container when the app host starts. For more information, see [Container resource lifecycle](../../fundamentals/orchestrate-resources.md#container-resource-lifecycle). +When you call `RunAsEmulator`, it configures your Cosmos DB resources to run locally using an emulator. The emulator in this case is the [Azure Cosmos DB Emulator](/azure/cosmos-db/local-emulator). The Azure Cosmos DB Emulator provides a free local environment for testing your Azure Cosmos DB apps and it's a perfect companion to the .NET Aspire Azure hosting integration. The emulator isn't installed, instead, it's accessible to .NET Aspire as a container. When you add a container to the AppHost, as shown in the preceding example with the `mcr.microsoft.com/cosmosdb/emulator` image, it creates and starts the container when the AppHost starts. For more information, see [Container resource lifecycle](../../fundamentals/orchestrate-resources.md#container-resource-lifecycle). #### Configure Cosmos DB emulator container diff --git a/docs/database/includes/mysql-app-host.md b/docs/database/includes/mysql-app-host.md index cfab233ab5..a6f8d8debf 100644 --- a/docs/database/includes/mysql-app-host.md +++ b/docs/database/includes/mysql-app-host.md @@ -3,7 +3,7 @@ ms.topic: include ms.custom: sfi-ropc-nochange --- -The MySQL hosting integration models the server as the type and the database as the type. To access these types and APIs, add the [📦 Aspire.Hosting.MySql](https://www.nuget.org/packages/Aspire.Hosting.MySql) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +The MySQL hosting integration models the server as the type and the database as the type. To access these types and APIs, add the [📦 Aspire.Hosting.MySql](https://www.nuget.org/packages/Aspire.Hosting.MySql) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -24,7 +24,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add MySQL server resource and database resource -In your app host project, call to add and return a MySQL resource builder. Chain a call to the returned resource builder to , to add a MySQL database resource. +In your AppHost project, call to add and return a MySQL resource builder. Chain a call to the returned resource builder to , to add a MySQL database resource. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -44,9 +44,9 @@ var myService = builder.AddProject() > [!NOTE] > The SQL Server container is slow to start, so it's best to use a _persistent_ lifetime to avoid unnecessary restarts. For more information, see [Container resource lifetime](../../fundamentals/orchestrate-resources.md#container-resource-lifetime). -When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `mysql` image, it creates a new MySQL instance on your local machine. A reference to your MySQL resource builder (the `mysql` variable) is used to add a database. The database is named `mysqldb` and then added to the `ExampleProject`. The MySQL resource includes default credentials with a `username` of `root` and a random `password` generated using the method. +When .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `mysql` image, it creates a new MySQL instance on your local machine. A reference to your MySQL resource builder (the `mysql` variable) is used to add a database. The database is named `mysqldb` and then added to the `ExampleProject`. The MySQL resource includes default credentials with a `username` of `root` and a random `password` generated using the method. -When the app host runs, the password is stored in the app host's secret store. It's added to the `Parameters` section, for example: +When the AppHost runs, the password is stored in the AppHost's secret store. It's added to the `Parameters` section, for example: ```json { diff --git a/docs/database/includes/postgresql-app-host.md b/docs/database/includes/postgresql-app-host.md index c470e7e595..d7c3b088e3 100644 --- a/docs/database/includes/postgresql-app-host.md +++ b/docs/database/includes/postgresql-app-host.md @@ -10,7 +10,7 @@ The PostgreSQL hosting integration models various PostgreSQL resources as the fo - - -To access these types and APIs for expressing them as resources in your [app host](xref:dotnet/aspire/app-host) project, install the [📦 Aspire.Hosting.PostgreSQL](https://www.nuget.org/packages/Aspire.Hosting.PostgreSQL) NuGet package: +To access these types and APIs for expressing them as resources in your [AppHost](xref:dotnet/aspire/app-host) project, install the [📦 Aspire.Hosting.PostgreSQL](https://www.nuget.org/packages/Aspire.Hosting.PostgreSQL) NuGet package: ### [.NET CLI](#tab/dotnet-cli) @@ -31,7 +31,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add PostgreSQL server resource -In your app host project, call on the `builder` instance to add a PostgreSQL server resource then call on the `postgres` instance to add a database resource as shown in the following example: +In your AppHost project, call on the `builder` instance to add a PostgreSQL server resource then call on the `postgres` instance to add a database resource as shown in the following example: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -45,9 +45,9 @@ var exampleProject = builder.AddProject() // After adding all resources, run the app... ``` -When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `docker.io/library/postgres` image, it creates a new PostgreSQL server instance on your local machine. A reference to your PostgreSQL server and database instance (the `postgresdb` variable) are used to add a dependency to the `ExampleProject`. +When .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `docker.io/library/postgres` image, it creates a new PostgreSQL server instance on your local machine. A reference to your PostgreSQL server and database instance (the `postgresdb` variable) are used to add a dependency to the `ExampleProject`. -When adding a database resource to the app model, the database is created if it doesn't already exist. The creation of the database relies on the [app host eventing APIs](../../app-host/eventing.md), specifically . In other words, when the `postgres` resource is _ready_, the event is raised and the database resource is created. +When adding a database resource to the app model, the database is created if it doesn't already exist. The creation of the database relies on the [AppHost eventing APIs](../../app-host/eventing.md), specifically . In other words, when the `postgres` resource is _ready_, the event is raised and the database resource is created. The PostgreSQL server resource includes default credentials with a `username` of `"postgres"` and randomly generated `password` using the method. @@ -64,13 +64,7 @@ By default, when you add a " ``` - - -To alter the default script, chain a call to the `WithCreationScript` method on the database resource builder: +To alter the default script, chain a call to the method on the database resource builder: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -202,7 +196,7 @@ The data volume is used to persist the PostgreSQL server data outside the lifecy > [!IMPORTANT] > Some database integrations, including the .NET Aspire PostgreSQL integration, can't successfully use data volumes after deployment to Azure Container Apps (ACA). This is because ACA uses Server Message Block (SMB) to connect containers to data volumes, and some systems can't use this connection. In the Aspire Dashboard, a database affected by this issue has a status of **Activating** or **Activation Failed** but is never listed as **Running**. > -> You can resolve the problem by using the managed service **Azure Database for PostgreSQL** to host the deployed database instead of a container in ACA, which is the recommended approach regardless of this issue. The following App Host code shows how to deploy a database to Azure Database for PostgreSQL, but run it as a container, with a data volume, during development: +> You can resolve the problem by using the managed service **Azure Database for PostgreSQL** to host the deployed database instead of a container in ACA, which is the recommended approach regardless of this issue. The following AppHost code shows how to deploy a database to Azure Database for PostgreSQL, but run it as a container, with a data volume, during development: > :::code language="csharp" source="../snippets/postgres-data-volume-deploy/AppHost.cs"::: ### Add PostgreSQL server resource with data bind mount diff --git a/docs/database/includes/postgresql-client.md b/docs/database/includes/postgresql-client.md index d7ca9e2cd5..11d46882af 100644 --- a/docs/database/includes/postgresql-client.md +++ b/docs/database/includes/postgresql-client.md @@ -27,7 +27,7 @@ builder.AddNpgsqlDataSource(connectionName: "postgresdb"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the PostgreSQL server resource in the app host project. For more information, see [Add PostgreSQL server resource](#add-postgresql-server-resource). +> The `connectionName` parameter must match the name used when adding the PostgreSQL server resource in the AppHost project. For more information, see [Add PostgreSQL server resource](#add-postgresql-server-resource). After adding `NpgsqlDataSource` to the builder, you can get the `NpgsqlDataSource` instance using dependency injection. For example, to retrieve your data source object from an example service define it as a constructor parameter and ensure the `ExampleService` class is registered with the dependency injection container: diff --git a/docs/database/includes/postgresql-ef-client.md b/docs/database/includes/postgresql-ef-client.md index 7733931d69..d82506266d 100644 --- a/docs/database/includes/postgresql-ef-client.md +++ b/docs/database/includes/postgresql-ef-client.md @@ -28,7 +28,7 @@ builder.AddNpgsqlDbContext(connectionName: "postgresdb"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the PostgreSQL server resource in the app host project. For more information, see [Add PostgreSQL server resource](#add-postgresql-server-resource). +> The `connectionName` parameter must match the name used when adding the PostgreSQL server resource in the AppHost project. For more information, see [Add PostgreSQL server resource](#add-postgresql-server-resource). After adding `YourDbContext` to the builder, you can get the `YourDbContext` instance using dependency injection. For example, to retrieve your data source object from an example service define it as a constructor parameter and ensure the `ExampleService` class is registered with the dependency injection container: @@ -52,7 +52,7 @@ builder.Services.AddDbContext(options => ``` > [!NOTE] -> The connection string name that you pass to the method must match the name used when adding the PostgreSQL server resource in the app host project. For more information, see [Add PostgreSQL server resource](#add-postgresql-server-resource). +> The connection string name that you pass to the method must match the name used when adding the PostgreSQL server resource in the AppHost project. For more information, see [Add PostgreSQL server resource](#add-postgresql-server-resource). You have more flexibility when you create the database context in this way, for example: diff --git a/docs/database/includes/postgresql-flexible-server.md b/docs/database/includes/postgresql-flexible-server.md index 4dff5b6003..d884ab5935 100644 --- a/docs/database/includes/postgresql-flexible-server.md +++ b/docs/database/includes/postgresql-flexible-server.md @@ -9,7 +9,7 @@ The .NET Aspire Azure PostgreSQL hosting integration models a PostgreSQL flexibl - - -To access these types and APIs for expressing them as resources in your [app host](xref:dotnet/aspire/app-host) project, install the [📦 Aspire.Hosting.Azure.PostgreSQL](https://www.nuget.org/packages/Aspire.Hosting.Azure.PostgreSQL) NuGet package: +To access these types and APIs for expressing them as resources in your [AppHost](xref:dotnet/aspire/app-host) project, install the [📦 Aspire.Hosting.Azure.PostgreSQL](https://www.nuget.org/packages/Aspire.Hosting.Azure.PostgreSQL) NuGet package: ### [.NET CLI](#tab/dotnet-cli) @@ -36,7 +36,7 @@ The Azure PostgreSQL hosting integration takes a dependency on the [📦 Aspire. -After you've installed the .NET Aspire Azure PostgreSQL hosting integration, call the extension method in your app host project: +After you've installed the .NET Aspire Azure PostgreSQL hosting integration, call the extension method in your AppHost project: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -110,7 +110,7 @@ builder.AddProject() For more information on treating Azure PostgreSQL flexible server resources as existing resources, see [Use existing Azure resources](../../azure/integrations-overview.md#use-existing-azure-resources). > [!NOTE] -> Alternatively, instead of representing an Azure PostgreSQL flexible server resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). +> Alternatively, instead of representing an Azure PostgreSQL flexible server resource, you can add a connection string to the AppHost. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). ### Run Azure PostgreSQL resource as a container @@ -154,4 +154,4 @@ var exampleProject = builder.AddProject() .WithReference(postgresdb); ``` -The preceding code configures the Azure PostgreSQL server to use password authentication. The `username` and `password` parameters are added to the app host as parameters, and the `WithPasswordAuthentication` method is called to configure the Azure PostgreSQL server to use password authentication. For more information, see [External parameters](../../fundamentals/external-parameters.md). +The preceding code configures the Azure PostgreSQL server to use password authentication. The `username` and `password` parameters are added to the AppHost as parameters, and the `WithPasswordAuthentication` method is called to configure the Azure PostgreSQL server to use password authentication. For more information, see [External parameters](../../fundamentals/external-parameters.md). diff --git a/docs/database/includes/sql-app-host.md b/docs/database/includes/sql-app-host.md index 6422332074..20d5b72f66 100644 --- a/docs/database/includes/sql-app-host.md +++ b/docs/database/includes/sql-app-host.md @@ -3,7 +3,7 @@ ms.topic: include ms.custom: sfi-ropc-nochange --- -The SQL Server hosting integration models the server as the type and the database as the type. To access these types and APIs, add the [📦 Aspire.Hosting.SqlServer](https://www.nuget.org/packages/Aspire.Hosting.SqlServer) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +The SQL Server hosting integration models the server as the type and the database as the type. To access these types and APIs, add the [📦 Aspire.Hosting.SqlServer](https://www.nuget.org/packages/Aspire.Hosting.SqlServer) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -24,20 +24,20 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add SQL Server resource and database resource -In your app host project, call to add and return a SQL Server resource builder. Chain a call to the returned resource builder to , to add SQL Server database resource. +In your AppHost project, call to add and return a SQL Server resource builder. Chain a call to the returned resource builder to , to add SQL Server database resource. :::code language="csharp" source="../snippets/sql-server-integration/AspireApp.AppHost/AppHost.cs"::: > [!NOTE] > The SQL Server container is slow to start, so it's best to use a _persistent_ lifetime to avoid unnecessary restarts. For more information, see [Container resource lifetime](../../fundamentals/orchestrate-resources.md#container-resource-lifetime). -When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `mcr.microsoft.com/mssql/server` image, it creates a new SQL Server instance on your local machine. A reference to your SQL Server resource builder (the `sql` variable) is used to add a database. The database is named `database` and then added to the `ExampleProject`. +When .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `mcr.microsoft.com/mssql/server` image, it creates a new SQL Server instance on your local machine. A reference to your SQL Server resource builder (the `sql` variable) is used to add a database. The database is named `database` and then added to the `ExampleProject`. -When adding a database resource to the app model, the database is created if it doesn't already exist. The creation of the database relies on the [app host eventing APIs](../../app-host/eventing.md), specifically . In other words, when the `sql` resource is _ready_, the event is raised and the database resource is created. +When adding a database resource to the app model, the database is created if it doesn't already exist. The creation of the database relies on the [AppHost eventing APIs](../../app-host/eventing.md), specifically . In other words, when the `sql` resource is _ready_, the event is raised and the database resource is created. The SQL Server resource includes default credentials with a `username` of `sa` and a random `password` generated using the method. -When the app host runs, the password is stored in the app host's secret store. It's added to the `Parameters` section, for example: +When the AppHost runs, the password is stored in the AppHost's secret store. It's added to the `Parameters` section, for example: ```json { @@ -106,7 +106,7 @@ For more information on providing parameters, see [External parameters](../../fu ### Connect to database resources -When the .NET Aspire app host runs, the server's database resources can be accessed from external tools, such as [SQL Server Management Studio (SSMS)](/sql/ssms/download-sql-server-management-studio-ssms) or [MSSQL for Visual Studio Code](/sql/tools/visual-studio-code-extensions/mssql/mssql-extension-visual-studio-code). The connection string for the database resource is available in the dependent resources environment variables and is accessed using the [.NET Aspire dashboard: Resource details](../../fundamentals/dashboard/explore.md#resource-details) pane. The environment variable is named `ConnectionStrings__{name}` where `{name}` is the name of the database resource, in this example it's `database`. Use the connection string to connect to the database resource from external tools. Imagine that you have a database named `todos` with a single `dbo.Todos` table. +When the .NET Aspire AppHost runs, the server's database resources can be accessed from external tools, such as [SQL Server Management Studio (SSMS)](/sql/ssms/download-sql-server-management-studio-ssms) or [MSSQL for Visual Studio Code](/sql/tools/visual-studio-code-extensions/mssql/mssql-extension-visual-studio-code). The connection string for the database resource is available in the dependent resources environment variables and is accessed using the [.NET Aspire dashboard: Resource details](../../fundamentals/dashboard/explore.md#resource-details) pane. The environment variable is named `ConnectionStrings__{name}` where `{name}` is the name of the database resource, in this example it's `database`. Use the connection string to connect to the database resource from external tools. Imagine that you have a database named `todos` with a single `dbo.Todos` table. #### [SQL Server Management Studio](#tab/ssms) diff --git a/docs/database/includes/sql-server-client.md b/docs/database/includes/sql-server-client.md index 5d34fbb74d..55d5d4f7cd 100644 --- a/docs/database/includes/sql-server-client.md +++ b/docs/database/includes/sql-server-client.md @@ -28,7 +28,7 @@ builder.AddSqlServerClient(connectionName: "database"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the SQL Server database resource in the app host project. In other words, when you call `AddDatabase` and provide a name of `database` that same name should be used when calling `AddSqlServerClient`. For more information, see [Add SQL Server resource and database resource](../sql-server-integration.md#add-sql-server-resource-and-database-resource). +> The `connectionName` parameter must match the name used when adding the SQL Server database resource in the AppHost project. In other words, when you call `AddDatabase` and provide a name of `database` that same name should be used when calling `AddSqlServerClient`. For more information, see [Add SQL Server resource and database resource](../sql-server-integration.md#add-sql-server-resource-and-database-resource). You can then retrieve the instance using dependency injection. For example, to retrieve the connection from an example service: diff --git a/docs/database/includes/sql-server-ef-client.md b/docs/database/includes/sql-server-ef-client.md index 49d0b522d5..ca23b78314 100644 --- a/docs/database/includes/sql-server-ef-client.md +++ b/docs/database/includes/sql-server-ef-client.md @@ -30,7 +30,7 @@ builder.AddSqlServerDbContext(connectionName: "database"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the SQL Server database resource in the app host project. In other words, when you call `AddDatabase` and provide a name of `database` that same name should be used when calling `AddSqlServerDbContext`. For more information, see [Add SQL Server resource and database resource](../sql-server-integration.md#add-sql-server-resource-and-database-resource). +> The `connectionName` parameter must match the name used when adding the SQL Server database resource in the AppHost project. In other words, when you call `AddDatabase` and provide a name of `database` that same name should be used when calling `AddSqlServerDbContext`. For more information, see [Add SQL Server resource and database resource](../sql-server-integration.md#add-sql-server-resource-and-database-resource). To retrieve `ExampleDbContext` object from a service: @@ -54,7 +54,7 @@ builder.Services.AddDbContext(options => ``` > [!NOTE] -> The connection string name that you pass to the method must match the name used when adding the SQL server resource in the app host project. For more information, see [Add SQL Server resource and database resource](../sql-server-integration.md#add-sql-server-resource-and-database-resource). +> The connection string name that you pass to the method must match the name used when adding the SQL server resource in the AppHost project. For more information, see [Add SQL Server resource and database resource](../sql-server-integration.md#add-sql-server-resource-and-database-resource). You have more flexibility when you create the database context in this way, for example: diff --git a/docs/database/milvus-integration.md b/docs/database/milvus-integration.md index c838201c94..9e72752417 100644 --- a/docs/database/milvus-integration.md +++ b/docs/database/milvus-integration.md @@ -18,7 +18,7 @@ In this article, you learn how to use the .NET Aspire Milvus database integratio ## Hosting integration -The Milvus database hosting integration models the server as the type and the database as the type. To access these types and APIs, add the [📦 Aspire.Hosting.Milvus](https://www.nuget.org/packages/Aspire.Hosting.Milvus) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +The Milvus database hosting integration models the server as the type and the database as the type. To access these types and APIs, add the [📦 Aspire.Hosting.Milvus](https://www.nuget.org/packages/Aspire.Hosting.Milvus) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -39,7 +39,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add Milvus server and database resources -In your app host project, call to add and return a Milvus resource builder. Chain a call to the returned resource builder to , to add a Milvus database resource. +In your AppHost project, call to add and return a Milvus resource builder. Chain a call to the returned resource builder to , to add a Milvus database resource. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -59,7 +59,7 @@ builder.AddProject() > [!NOTE] > The Milvus container can be slow to start, so it's best to use a _persistent_ lifetime to avoid unnecessary restarts. For more information, see [Container resource lifetime](../fundamentals/orchestrate-resources.md#container-resource-lifetime). -When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `milvusdb/milvus` image, it creates a new Milvus instance on your local machine. A reference to your Milvus resource builder (the `milvus` variable) is used to add a database. The database is named `milvusdb` and then added to the `ExampleProject`. +When .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `milvusdb/milvus` image, it creates a new Milvus instance on your local machine. A reference to your Milvus resource builder (the `milvus` variable) is used to add a database. The database is named `milvusdb` and then added to the `ExampleProject`. The method configures a connection in the `ExampleProject` named `milvusdb`. @@ -187,7 +187,7 @@ builder.AddMilvusClient("milvusdb"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Milvus database resource in the app host project. In other words, when you call `AddDatabase` and provide a name of `milvusdb` that same name should be used when calling `AddMilvusClient`. For more information, see [Add a Milvus server resource and database resource](#add-milvus-server-and-database-resources). +> The `connectionName` parameter must match the name used when adding the Milvus database resource in the AppHost project. In other words, when you call `AddDatabase` and provide a name of `milvusdb` that same name should be used when calling `AddMilvusClient`. For more information, see [Add a Milvus server resource and database resource](#add-milvus-server-and-database-resources). You can then retrieve the `MilvusClient` instance using dependency injection. For example, to retrieve the connection from an example service: diff --git a/docs/database/mongodb-integration.md b/docs/database/mongodb-integration.md index 28f8bb6058..c67aa0d7ba 100644 --- a/docs/database/mongodb-integration.md +++ b/docs/database/mongodb-integration.md @@ -14,7 +14,7 @@ ms.custom: sfi-ropc-nochange ## Hosting integration -The MongoDB server hosting integration models the server as the type and the database as the type. To access these types and APIs, add the [📦 Aspire.Hosting.MongoDB](https://www.nuget.org/packages/Aspire.Hosting.MongoDB) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +The MongoDB server hosting integration models the server as the type and the database as the type. To access these types and APIs, add the [📦 Aspire.Hosting.MongoDB](https://www.nuget.org/packages/Aspire.Hosting.MongoDB) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -35,7 +35,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add MongoDB server resource and database resource -In your app host project, call to add and return a MongoDB server resource builder. Chain a call to the returned resource builder to , to add a MongoDB database resource. +In your AppHost project, call to add and return a MongoDB server resource builder. Chain a call to the returned resource builder to , to add a MongoDB database resource. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -55,12 +55,12 @@ builder.AddProject() > [!NOTE] > The MongoDB container can be slow to start, so it's best to use a _persistent_ lifetime to avoid unnecessary restarts. For more information, see [Container resource lifetime](../fundamentals/orchestrate-resources.md#container-resource-lifetime). -When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `docker.io/library/mongo` image, it creates a new MongoDB instance on your local machine. A reference to your MongoDB server resource builder (the `mongo` variable) is used to add a database. The database is named `mongodb` and then added to the `ExampleProject`. The MongoDB server resource includes default credentials: +When .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `docker.io/library/mongo` image, it creates a new MongoDB instance on your local machine. A reference to your MongoDB server resource builder (the `mongo` variable) is used to add a database. The database is named `mongodb` and then added to the `ExampleProject`. The MongoDB server resource includes default credentials: - `MONGO_INITDB_ROOT_USERNAME`: A value of `admin`. - `MONGO_INITDB_ROOT_PASSWORD`: Random `password` generated using the method. -When the app host runs, the password is stored in the app host's secret store. It's added to the `Parameters` section, for example: +When the AppHost runs, the password is stored in the AppHost's secret store. It's added to the `Parameters` section, for example: ```json { @@ -70,7 +70,7 @@ When the app host runs, the password is stored in the app host's secret store. I The name of the parameter is `mongo-password`, but really it's just formatting the resource name with a `-password` suffix. For more information, see [Safe storage of app secrets in development in ASP.NET Core](/aspnet/core/security/app-secrets) and [Add MongoDB server resource with parameters](#add-mongodb-server-resource-with-parameters). -The method configures a connection in the `ExampleProject` named `mongodb` and the instructs the app host to not start the dependant service until the `mongodb` resource is ready. +The method configures a connection in the `ExampleProject` named `mongodb` and the instructs the AppHost to not start the dependant service until the `mongodb` resource is ready. > [!TIP] > If you'd rather connect to an existing MongoDB server, call instead. For more information, see [Reference existing resources](../fundamentals/app-host-overview.md#reference-existing-resources). @@ -210,7 +210,7 @@ The hosting integration relies on the [📦 AspNetCore.HealthChecks.MongoDb](htt ## Client integration -To get started with the .NET Aspire MongoDB client integration, install the [📦 Aspire.MongoDB.Driver](https://www.nuget.org/packages/Aspire.MongoDB.Driver) NuGet package in the client-consuming project, that is, the project for the application that uses the MongoDB client. The MongoDB client integration registers a [IMongoClient](https://mongodb.github.io/mongo-csharp-driver/3.0.0/api/MongoDB.Driver/MongoDB.Driver.IMongoClient.html) instance that you can use to interact with the MongoDB server resource. If your app host adds MongoDB database resources, the [IMongoDatabase](https://mongodb.github.io/mongo-csharp-driver/3.0.0/api/MongoDB.Driver/MongoDB.Driver.IMongoDatabase.html) instance is also registered. +To get started with the .NET Aspire MongoDB client integration, install the [📦 Aspire.MongoDB.Driver](https://www.nuget.org/packages/Aspire.MongoDB.Driver) NuGet package in the client-consuming project, that is, the project for the application that uses the MongoDB client. The MongoDB client integration registers a [IMongoClient](https://mongodb.github.io/mongo-csharp-driver/3.0.0/api/MongoDB.Driver/MongoDB.Driver.IMongoClient.html) instance that you can use to interact with the MongoDB server resource. If your AppHost adds MongoDB database resources, the [IMongoDatabase](https://mongodb.github.io/mongo-csharp-driver/3.0.0/api/MongoDB.Driver/MongoDB.Driver.IMongoDatabase.html) instance is also registered. ### [.NET CLI](#tab/dotnet-cli) @@ -239,7 +239,7 @@ builder.AddMongoDBClient(connectionName: "mongodb"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the MongoDB server resource (or the database resource when provided) in the app host project. In other words, when you call `AddDatabase` and provide a name of `mongodb` that same name should be used when calling `AddMongoDBClient`. For more information, see [Add MongoDB server resource and database resource](#add-mongodb-server-resource-and-database-resource). +> The `connectionName` parameter must match the name used when adding the MongoDB server resource (or the database resource when provided) in the AppHost project. In other words, when you call `AddDatabase` and provide a name of `mongodb` that same name should be used when calling `AddMongoDBClient`. For more information, see [Add MongoDB server resource and database resource](#add-mongodb-server-resource-and-database-resource). You can then retrieve the `IMongoClient` instance using dependency injection. For example, to retrieve the client from an example service: @@ -250,7 +250,7 @@ public class ExampleService(IMongoClient client) } ``` -The `IMongoClient` is used to interact with the MongoDB server resource. It can be used to create databases that aren't already known to the app host project. When you define a MongoDB database resource in your app host, you could instead require that the dependency injection container provides an `IMongoDatabase` instance. For more information on dependency injection, see [.NET dependency injection](/dotnet/core/extensions/dependency-injection). +The `IMongoClient` is used to interact with the MongoDB server resource. It can be used to create databases that aren't already known to the AppHost project. When you define a MongoDB database resource in your AppHost, you could instead require that the dependency injection container provides an `IMongoDatabase` instance. For more information on dependency injection, see [.NET dependency injection](/dotnet/core/extensions/dependency-injection). ### Add keyed MongoDB client diff --git a/docs/database/mysql-entity-framework-integration.md b/docs/database/mysql-entity-framework-integration.md index 81e3c9a557..b1950f3bb7 100644 --- a/docs/database/mysql-entity-framework-integration.md +++ b/docs/database/mysql-entity-framework-integration.md @@ -45,7 +45,7 @@ builder.AddMySqlDbContext(connectionName: "mysqldb"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the SQL Server database resource in the app host project. In other words, when you call `AddDatabase` and provide a name of `mysqldb` that same name should be used when calling `AddMySqlDbContext`. For more information, see [Add MySQL server resource and database resource](#add-mysql-server-resource-and-database-resource). +> The `connectionName` parameter must match the name used when adding the SQL Server database resource in the AppHost project. In other words, when you call `AddDatabase` and provide a name of `mysqldb` that same name should be used when calling `AddMySqlDbContext`. For more information, see [Add MySQL server resource and database resource](#add-mysql-server-resource-and-database-resource). To retrieve `ExampleDbContext` object from a service: @@ -69,7 +69,7 @@ builder.Services.AddDbContext(options => ``` > [!NOTE] -> The connection string name that you pass to the method must match the name used when adding the MySQL resource in the app host project. For more information, see [Add MySQL server resource and database resource](#add-mysql-server-resource-and-database-resource). +> The connection string name that you pass to the method must match the name used when adding the MySQL resource in the AppHost project. For more information, see [Add MySQL server resource and database resource](#add-mysql-server-resource-and-database-resource). You have more flexibility when you create the database context in this way, for example: diff --git a/docs/database/mysql-integration.md b/docs/database/mysql-integration.md index 00cc137bf7..a74d0f78be 100644 --- a/docs/database/mysql-integration.md +++ b/docs/database/mysql-integration.md @@ -46,7 +46,7 @@ builder.AddMySqlDataSource(connectionName: "mysqldb"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the MySQL database resource in the app host project. In other words, when you call `AddDatabase` and provide a name of `mysqldb` that same name should be used when calling `AddMySqlDataSource`. For more information, see [Add MySQL server resource and database resource](#add-mysql-server-resource-and-database-resource). +> The `connectionName` parameter must match the name used when adding the MySQL database resource in the AppHost project. In other words, when you call `AddDatabase` and provide a name of `mysqldb` that same name should be used when calling `AddMySqlDataSource`. For more information, see [Add MySQL server resource and database resource](#add-mysql-server-resource-and-database-resource). You can then retrieve the `MySqlConnector.MySqlDataSource` instance using dependency injection. For example, to retrieve the data source from an example service: diff --git a/docs/database/oracle-entity-framework-integration.md b/docs/database/oracle-entity-framework-integration.md index a88219f258..1d0327a49c 100644 --- a/docs/database/oracle-entity-framework-integration.md +++ b/docs/database/oracle-entity-framework-integration.md @@ -14,7 +14,7 @@ ms.custom: sfi-ropc-nochange ## Hosting integration -The .NET Aspire Oracle hosting integration models the server as the type and the database as the type. To access these types and APIs, add the [📦 Aspire.Hosting.Oracle](https://www.nuget.org/packages/Aspire.Hosting.Oracle) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +The .NET Aspire Oracle hosting integration models the server as the type and the database as the type. To access these types and APIs, add the [📦 Aspire.Hosting.Oracle](https://www.nuget.org/packages/Aspire.Hosting.Oracle) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -35,7 +35,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add Oracle server and database resources -In your app host project, call to add and return an Oracle server resource builder. Chain a call to the returned resource builder to , to add an Oracle database to the server resource: +In your AppHost project, call to add and return an Oracle server resource builder. Chain a call to the returned resource builder to , to add an Oracle database to the server resource: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -55,7 +55,7 @@ builder.AddProject() > [!NOTE] > The Oracle database container can be slow to start, so it's best to use a _persistent_ lifetime to avoid unnecessary restarts. For more information, see [Container resource lifetime](../fundamentals/orchestrate-resources.md#container-resource-lifetime). -When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `container-registry.oracle.com/database/free` image, it creates a new Oracle server on your local machine. A reference to your Oracle resource builder (the `oracle` variable) is used to add a database. The database is named `oracledb` and then added to the `ExampleProject`. The Oracle resource includes a random `password` generated using the method. +When .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `container-registry.oracle.com/database/free` image, it creates a new Oracle server on your local machine. A reference to your Oracle resource builder (the `oracle` variable) is used to add a database. The database is named `oracledb` and then added to the `ExampleProject`. The Oracle resource includes a random `password` generated using the method. The method configures a connection in the `ExampleProject` named `"oracledb"`. For more information, see [Container resource lifecycle](../fundamentals/orchestrate-resources.md#container-resource-lifecycle). @@ -173,7 +173,7 @@ builder.AddOracleDatabaseDbContext(connectionName: "oracledb") ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Oracle database resource in the app host project. In other words, when you call `AddDatabase` and provide a name of `oracledb` that same name should be used when calling `AddOracleDatabaseDbContext`. For more information, see [Add Oracle server and database resources](#add-oracle-server-and-database-resources). +> The `connectionName` parameter must match the name used when adding the Oracle database resource in the AppHost project. In other words, when you call `AddDatabase` and provide a name of `oracledb` that same name should be used when calling `AddOracleDatabaseDbContext`. For more information, see [Add Oracle server and database resources](#add-oracle-server-and-database-resources). You can then retrieve the instance using dependency injection. For example, to retrieve the connection from an example service: @@ -197,7 +197,7 @@ builder.Services.AddDbContext(options => ``` > [!NOTE] -> The connection string name that you pass to the method must match the name used when adding the Oracle resource in the app host project. For more information, see [Add Oracle server and database resources](#add-oracle-server-and-database-resources). +> The connection string name that you pass to the method must match the name used when adding the Oracle resource in the AppHost project. For more information, see [Add Oracle server and database resources](#add-oracle-server-and-database-resources). You have more flexibility when you create the database context in this way, for example: diff --git a/docs/database/qdrant-integration.md b/docs/database/qdrant-integration.md index 4665f2f0c9..2504ba5ebe 100644 --- a/docs/database/qdrant-integration.md +++ b/docs/database/qdrant-integration.md @@ -18,7 +18,7 @@ In this article, you learn how to use the .NET Aspire Qdrant integration. The .N ## Hosting integration -The Qdrant hosting integration models the server as the type. To access this type and APIs, add the [📦 Aspire.Hosting.Qdrant](https://www.nuget.org/packages/Aspire.Hosting.Qdrant) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +The Qdrant hosting integration models the server as the type. To access this type and APIs, add the [📦 Aspire.Hosting.Qdrant](https://www.nuget.org/packages/Aspire.Hosting.Qdrant) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -39,7 +39,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add Qdrant resource -In your app host project, call to add and return a Qdrant resource builder. +In your AppHost project, call to add and return a Qdrant resource builder. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -57,7 +57,7 @@ builder.AddProject() > [!NOTE] > The Qdrant container can be slow to start, so it's best to use a _persistent_ lifetime to avoid unnecessary restarts. For more information, see [Container resource lifetime](../fundamentals/orchestrate-resources.md#container-resource-lifetime). -When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `qdrant/qdrant` image, it creates a new Qdrant instance on your local machine. The resource is named `qdrant` and then added to the `ExampleProject`. +When .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `qdrant/qdrant` image, it creates a new Qdrant instance on your local machine. The resource is named `qdrant` and then added to the `ExampleProject`. The method configures a connection in the `ExampleProject` named `qdrant`. @@ -168,7 +168,7 @@ builder.AddQdrantClient("qdrant"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Qdrant resource in the app host project. In other words, when you call `AddQdrant` and provide a name of `qdrant` that same name should be used when calling `AddQdrantClient`. For more information, see [Add Qdrant resource](#add-qdrant-resource). +> The `connectionName` parameter must match the name used when adding the Qdrant resource in the AppHost project. In other words, when you call `AddQdrant` and provide a name of `qdrant` that same name should be used when calling `AddQdrantClient`. For more information, see [Add Qdrant resource](#add-qdrant-resource). You can then retrieve the `QdrantClient` instance using dependency injection. For example, to retrieve the connection from an example service: diff --git a/docs/database/seed-database-data.md b/docs/database/seed-database-data.md index ad5a59622b..535f6171c4 100644 --- a/docs/database/seed-database-data.md +++ b/docs/database/seed-database-data.md @@ -46,13 +46,13 @@ The following code is an example T-SQL script that creates and populates an addr :::code source="~/aspire-samples/samples/DatabaseContainers/DatabaseContainers.ApiService/data/sqlserver/init.sql" ::: -You must ensure that this script is copied to the app host's output directory, so that .NET Aspire can execute it. Add the following XML to your *.csproj* file: +You must ensure that this script is copied to the AppHost's output directory, so that .NET Aspire can execute it. Add the following XML to your *.csproj* file: :::code language="xml" source="~/aspire-samples/samples/DatabaseContainers/DatabaseContainers.AppHost/DatabaseContainers.AppHost.csproj" range="13-17" ::: Adjust the `Include` parameter to match the path to your SQL script in the project. -Next, in the app host's *AppHost.cs* (or *Program.cs*) file, create the database and run the creation script: +Next, in the AppHost's *AppHost.cs* (or *Program.cs*) file, create the database and run the creation script: :::code source="~/aspire-samples/samples/DatabaseContainers/DatabaseContainers.AppHost/AppHost.cs" range="40-49" ::: @@ -71,7 +71,7 @@ The following code is an example PostgreSQL script that creates and populates a :::code source="~/aspire-samples/samples/DatabaseContainers/DatabaseContainers.ApiService/data/postgres/init.sql" ::: -In the app host's *AppHost.cs* (or *Program.cs*) file, create the database and mount the folder that contains the SQL script as a bind mount: +In the AppHost's *AppHost.cs* (or *Program.cs*) file, create the database and mount the folder that contains the SQL script as a bind mount: :::code source="~/aspire-samples/samples/DatabaseContainers/DatabaseContainers.AppHost/AppHost.cs" range="3-19" ::: @@ -79,7 +79,7 @@ In the app host's *AppHost.cs* (or *Program.cs*) file, create the database and m Starting with .NET Aspire 9.3, you can use the method to ensure a MySQL script is run when the database is created. Add SQL code to this script that creates and populates the database, the necessary tables, and other database objects. -In the following App Host code, the script is created as a string and passed to the `WithCreationScript` method: +In the following AppHost code, the script is created as a string and passed to the `WithCreationScript` method: :::code source="snippets/mysql-seed-data/AppHost.cs" ::: diff --git a/docs/deployment/azure/application-insights.md b/docs/deployment/azure/application-insights.md index 920e93758d..88f5098f37 100644 --- a/docs/deployment/azure/application-insights.md +++ b/docs/deployment/azure/application-insights.md @@ -12,21 +12,21 @@ ms.custom: Azure Application Insights, a feature of Azure Monitor, excels in Application Performance Management (APM) for live web applications. .NET Aspire projects are designed to use OpenTelemetry for application telemetry. OpenTelemetry supports an extension model to support sending data to different APMs. .NET Aspire uses OTLP by default for telemetry export, which is used by the dashboard during development. Azure Monitor doesn't (yet) support OTLP, so the applications need to be modified to use the Azure Monitor exporter, and configured with the connection string. -To use Application insights, you specify its configuration in the app host project *and* use the [Azure Monitor distro in the service defaults project](#use-the-azure-monitor-distro). +To use Application insights, you specify its configuration in the AppHost project *and* use the [Azure Monitor distro in the service defaults project](#use-the-azure-monitor-distro). ## Choosing how Application Insights is provisioned -.NET Aspire has the capability to provision cloud resources as part of cloud deployment, including Application Insights. In your .NET Aspire project, you can decide if you want .NET Aspire to provision an Application Insights resource when deploying to Azure. You can also select to use an existing Application Insights resource by providing its connection string. The connection information is managed by the resource configuration in the app host project. +.NET Aspire has the capability to provision cloud resources as part of cloud deployment, including Application Insights. In your .NET Aspire project, you can decide if you want .NET Aspire to provision an Application Insights resource when deploying to Azure. You can also select to use an existing Application Insights resource by providing its connection string. The connection information is managed by the resource configuration in the AppHost project. ### Provisioning Application insights during Azure deployment With this option, an instance of Application Insights will be created for you when the application is deployed using the Azure Developer CLI (`azd`). -To use automatic provisioning, you specify a dependency in the app host project, and reference it in each project/resource that needs to send telemetry to Application Insights. The steps include: +To use automatic provisioning, you specify a dependency in the AppHost project, and reference it in each project/resource that needs to send telemetry to Application Insights. The steps include: -- Add a Nuget package reference to [Aspire.Hosting.Azure.ApplicationInsights](https://nuget.org/packages/Aspire.Hosting.Azure.ApplicationInsights) in the app host project. +- Add a Nuget package reference to [Aspire.Hosting.Azure.ApplicationInsights](https://nuget.org/packages/Aspire.Hosting.Azure.ApplicationInsights) in the AppHost project. -- Update the app host code to use the Application Insights resource, and reference it from each project: +- Update the AppHost code to use the Application Insights resource, and reference it from each project: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -53,7 +53,7 @@ Application Insights uses a connection string to tell the OpenTelemetry exporter :::image type="content" loc-scope="azure" source="../media/app-insights-connection-string.png" lightbox="../media/app-insights-connection-string.png" alt-text="Connection string placement in the Azure Application Insights portal UI."::: -If you wish to use an instance of Application Insights that you have provisioned manually, then you should use the `AddConnectionString` API in the app host project to tell the projects/containers where to send the telemetry data. The Azure Monitor distro expects the environment variable to be `APPLICATIONINSIGHTS_CONNECTION_STRING`, so that needs to be explicitly set when defining the connection string. +If you wish to use an instance of Application Insights that you have provisioned manually, then you should use the `AddConnectionString` API in the AppHost project to tell the projects/containers where to send the telemetry data. The Azure Monitor distro expects the environment variable to be `APPLICATIONINSIGHTS_CONNECTION_STRING`, so that needs to be explicitly set when defining the connection string. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -74,7 +74,7 @@ builder.Build().Run(); #### Resource usage during development -When running the .NET Aspire project locally, the preceding code reads the connection string from configuration. As this is a secret, you should store the value in [app secrets](/aspnet/core/security/app-secrets). Right click on the app host project and choose **Manage Secrets** from the context menu to open the secrets file for the app host project. In the file add the key and your specific connection string, the example below is for illustration purposes. +When running the .NET Aspire project locally, the preceding code reads the connection string from configuration. As this is a secret, you should store the value in [app secrets](/aspnet/core/security/app-secrets). Right click on the AppHost project and choose **Manage Secrets** from the context menu to open the secrets file for the AppHost project. In the file add the key and your specific connection string, the example below is for illustration purposes. ```json { @@ -85,7 +85,7 @@ When running the .NET Aspire project locally, the preceding code reads the conne ``` > [!NOTE] -> The `name` specified in the app host code needs to match a key inside the `ConnectionStrings` section in the settings file. +> The `name` specified in the AppHost code needs to match a key inside the `ConnectionStrings` section in the settings file. #### Resource usage during deployment @@ -150,4 +150,4 @@ private static IHostApplicationBuilder AddOpenTelemetryExporters( } ``` -It's possible to further customize the Azure Monitor exporter, including customizing the resource name and changing the sampling. For more information, see [Customize the Azure Monitor exporter](/azure/azure-monitor/app/opentelemetry-configuration?tabs=aspnetcore). Using the parameterless version of `UseAzureMonitor()`, will pickup the connection string from the `APPLICATIONINSIGHTS_CONNECTION_STRING` environment variable, we configured via the app host project. +It's possible to further customize the Azure Monitor exporter, including customizing the resource name and changing the sampling. For more information, see [Customize the Azure Monitor exporter](/azure/azure-monitor/app/opentelemetry-configuration?tabs=aspnetcore). Using the parameterless version of `UseAzureMonitor()`, will pickup the connection string from the `APPLICATIONINSIGHTS_CONNECTION_STRING` environment variable, we configured via the AppHost project. diff --git a/docs/deployment/azure/customize-deployments.md b/docs/deployment/azure/customize-deployments.md index af3a3eaa76..6451c650a1 100644 --- a/docs/deployment/azure/customize-deployments.md +++ b/docs/deployment/azure/customize-deployments.md @@ -28,7 +28,7 @@ Infrastructure generation in `azd` transforms your .NET Aspire app model into co When you run `azd infra gen`, the CLI: -1. Analyzes your .NET Aspire app host project. +1. Analyzes your .NET Aspire AppHost project. 1. Identifies all resources and their dependencies. 1. Generates corresponding Azure resource definitions in Bicep. 1. Creates supporting configuration files for deployment. @@ -41,7 +41,7 @@ Call the generate infrastructure command on your .NET Aspire solution: azd infra gen ``` -This command creates an `infra` folder in your app host project directory with the following structure: +This command creates an `infra` folder in your AppHost project directory with the following structure: ```Directory └───📂 infra diff --git a/docs/deployment/manifest-format.md b/docs/deployment/manifest-format.md index 80be3bbc1a..f4f58334da 100644 --- a/docs/deployment/manifest-format.md +++ b/docs/deployment/manifest-format.md @@ -147,7 +147,7 @@ This dependency is known because the environment variables for the _webfrontend_ }, ``` -The `apiservice` resource is referenced by `webfrontend` using the call `WithReference(apiservice)` in the app host _:::no-loc text="Program.cs":::_ file and `redis` is referenced using the call `WithReference(cache)`: +The `apiservice` resource is referenced by `webfrontend` using the call `WithReference(apiservice)` in the AppHost _:::no-loc text="Program.cs":::_ file and `redis` is referenced using the call `WithReference(cache)`: ```csharp var builder = DistributedApplication.CreateBuilder(args); diff --git a/docs/deployment/overview.md b/docs/deployment/overview.md index 606b50a3b7..091de9d285 100644 --- a/docs/deployment/overview.md +++ b/docs/deployment/overview.md @@ -13,7 +13,7 @@ ms.date: 07/17/2025 To enable deployment tools from Microsoft and other cloud providers to understand the structure of .NET Aspire projects, specialized targets of the [AppHost project](../fundamentals/app-host-overview.md) can be executed to generate a manifest file describing the projects/services used by the app and the properties necessary for deployment, such as environment variables. -For more information on the schema of the manifest and how to run app host project targets, see [.NET Aspire manifest format for deployment tool builders](manifest-format.md). +For more information on the schema of the manifest and how to run AppHost project targets, see [.NET Aspire manifest format for deployment tool builders](manifest-format.md). ## Deploy to Azure @@ -33,10 +33,10 @@ Kubernetes is a popular container orchestration platform that can run .NET Aspir ### The Aspir8 project -**Aspir8**, an open-source project, handles the generation of deployment YAML based on the .NET Aspire app host manifest. The project outputs a .NET global tool that can be used to perform a series of tasks, resulting in the generation of Kubernetes manifests: +**Aspir8**, an open-source project, handles the generation of deployment YAML based on the .NET Aspire AppHost manifest. The project outputs a .NET global tool that can be used to perform a series of tasks, resulting in the generation of Kubernetes manifests: - `aspirate init`: Initializes the **Aspir8** project in the current directory. -- `aspirate generate`: Generates Kubernetes manifests based on the .NET Aspire app host manifest. +- `aspirate generate`: Generates Kubernetes manifests based on the .NET Aspire AppHost manifest. - `aspirate apply`: Applies the generated Kubernetes manifests to the Kubernetes cluster. - `aspirate destroy`: Deletes the resources created by the `apply` command. diff --git a/docs/diagnostics/aspire002.md b/docs/diagnostics/aspire002.md index 0da393032b..3d1217cbff 100644 --- a/docs/diagnostics/aspire002.md +++ b/docs/diagnostics/aspire002.md @@ -14,8 +14,8 @@ helpviewer_keywords: > 'Project' is an Aspire AppHost project but necessary dependencies aren't present. Are you missing an Aspire.Hosting.AppHost PackageReference? -This diagnostic warning is reported when your project is missing reference to the .NET Aspire App Host. +This diagnostic warning is reported when your project is missing reference to the .NET Aspire AppHost. ## To correct this warning -Add reference to the [📦 Aspire.Hosting.AppHost](https://www.nuget.org/packages/Aspire.Hosting.AppHost) NuGet package. For more information about the app host, see [.NET Aspire orchestration overview](../fundamentals/app-host-overview.md). +Add reference to the [📦 Aspire.Hosting.AppHost](https://www.nuget.org/packages/Aspire.Hosting.AppHost) NuGet package. For more information about the AppHost, see [.NET Aspire orchestration overview](../fundamentals/app-host-overview.md). diff --git a/docs/diagnostics/aspire004.md b/docs/diagnostics/aspire004.md index 93550a436d..d01dd5c0c9 100644 --- a/docs/diagnostics/aspire004.md +++ b/docs/diagnostics/aspire004.md @@ -14,11 +14,11 @@ helpviewer_keywords: > 'Project' is referenced by an Aspire Host project, but it is not an executable. Did you mean to set IsAspireProjectResource="false"? -The project being referenced byt the .NET Aspire App Host isn't an executable, but is being treated like one for the purposes of orchestration. +The project being referenced byt the .NET Aspire AppHost isn't an executable, but is being treated like one for the purposes of orchestration. ## To correct this warning -Either change the build type of the project to an executable, or add the `IsAspireProjectResource="false"` setting to the project reference in your .NET Aspire App Host project file, as demonstrated in the following snippet: +Either change the build type of the project to an executable, or add the `IsAspireProjectResource="false"` setting to the project reference in your .NET Aspire AppHost project file, as demonstrated in the following snippet: ```xml diff --git a/docs/diagnostics/aspire007.md b/docs/diagnostics/aspire007.md index 0ebca4266e..778002e2f3 100644 --- a/docs/diagnostics/aspire007.md +++ b/docs/diagnostics/aspire007.md @@ -14,7 +14,7 @@ helpviewer_keywords: > 'Project' requires a reference to "Aspire.AppHost.Sdk" with version "9.0.0" or greater to work correctly. Please add the following line after the Project declaration ``. -The .NET Aspire App Host package references require .NET Aspire SDK version 9.0.0 or greater. The SDK reference is either being omitted or is using a version older than 9.0.0. +The .NET Aspire AppHost package references require .NET Aspire SDK version 9.0.0 or greater. The SDK reference is either being omitted or is using a version older than 9.0.0. ## To correct this error diff --git a/docs/diagnostics/aspireacadomains001.md b/docs/diagnostics/aspireacadomains001.md index 82f4e953c5..13968af079 100644 --- a/docs/diagnostics/aspireacadomains001.md +++ b/docs/diagnostics/aspireacadomains001.md @@ -20,7 +20,7 @@ helpviewer_keywords: - `Aspire.Hosting.AzureContainerAppContainerExtensions.PublishAsAzureContainerApp` - `Aspire.Hosting.AzureContainerAppExecutableExtensions.PublishAsAzureContainerApp` -When you use one of these methods, the Azure Developer CLI (`azd`) can no longer preserve custom domains. Instead use the `Aspire.Hosting.ContainerAppExtensions.ConfigureCustomDomain` method to configure a custom domain within the .NET Aspire app host. +When you use one of these methods, the Azure Developer CLI (`azd`) can no longer preserve custom domains. Instead use the `Aspire.Hosting.ContainerAppExtensions.ConfigureCustomDomain` method to configure a custom domain within the .NET Aspire AppHost. However, `app.ConfigureCustomDomain` is an experimental API and you must suppress it to use it. diff --git a/docs/diagnostics/aspirehostingpython001.md b/docs/diagnostics/aspirehostingpython001.md index c372d07402..2833b09903 100644 --- a/docs/diagnostics/aspirehostingpython001.md +++ b/docs/diagnostics/aspirehostingpython001.md @@ -14,7 +14,7 @@ helpviewer_keywords: > `AddPythonApp` is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. -.NET Aspire provides a way to add Python executables or applications to the .NET Aspire app host with the `AddPythonApp` extension. Since the shape of this API is expected to change in the future, it's experimental. +.NET Aspire provides a way to add Python executables or applications to the .NET Aspire AppHost with the `AddPythonApp` extension. Since the shape of this API is expected to change in the future, it's experimental. ## Example diff --git a/docs/extensibility/custom-hosting-integration.md b/docs/extensibility/custom-hosting-integration.md index 0b0ec8df8e..db5d14aa3b 100644 --- a/docs/extensibility/custom-hosting-integration.md +++ b/docs/extensibility/custom-hosting-integration.md @@ -59,7 +59,7 @@ dir Once the project is created, you should see a listing containing the following: -- `MailDevResource.AppHost`: The [app host](../fundamentals/app-host-overview.md) used to test out the custom resource. +- `MailDevResource.AppHost`: The [AppHost](../fundamentals/app-host-overview.md) used to test out the custom resource. - `MailDevResource.ServiceDefaults`: The [service defaults](../fundamentals/service-defaults.md) project for use in service-related projects. - `MailDevResource.sln`: The solution file referencing both projects. @@ -139,7 +139,7 @@ spire Host project, but it is not an executable. Did you mean to set IsAspirePro source.AppHost.csproj] ``` -This is because .NET Aspire treats project references in the app host as if they're service projects. To tell .NET Aspire that the project reference should be treated as a nonservice project modify the _:::no-loc text="MailDevResource.AppHost\MailDevResource.AppHost.csproj":::_ files reference to the `MailDev.Hosting` project to be the following: +This is because .NET Aspire treats project references in the AppHost as if they're service projects. To tell .NET Aspire that the project reference should be treated as a nonservice project modify the _:::no-loc text="MailDevResource.AppHost\MailDevResource.AppHost.csproj":::_ files reference to the `MailDev.Hosting` project to be the following: ```xml @@ -151,11 +151,11 @@ This is because .NET Aspire treats project references in the app host as if they ``` -Now when you launch the app host, there's no warning displayed to the console. +Now when you launch the AppHost, there's no warning displayed to the console. ## Define the resource types -The _MailDev.Hosting_ class library contains the resource type and extension methods for adding the resource to the app host. You should first think about the experience that you want to give developers when using your custom resource. In the case of this custom resource, you would want developers to be able to write code like the following: +The _MailDev.Hosting_ class library contains the resource type and extension methods for adding the resource to the AppHost. You should first think about the experience that you want to give developers when using your custom resource. In the case of this custom resource, you would want developers to be able to write code like the following: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -184,7 +184,7 @@ Add the following code to a new file named _MailDevResourceBuilderExtensions.cs_ :::code language="csharp" source="snippets/MailDevResource/MailDev.Hosting/MailDevResourceBuilderExtensions.cs"::: -## Validate custom integration inside the app host +## Validate custom integration inside the AppHost Now that the basic structure for the custom resource is complete it's time to test it in a real AppHost project. Open the _:::no-loc text="Program.cs":::_ file in the _:::no-loc text="MailDevResource.AppHost":::_ project and update it with the following code: @@ -196,7 +196,7 @@ var maildev = builder.AddMailDev("maildev"); builder.Build().Run(); ``` -After updating the _:::no-loc text="Program.cs":::_ file, launch the app host project and open the dashboard: +After updating the _:::no-loc text="Program.cs":::_ file, launch the AppHost project and open the dashboard: ```dotnetcli dotnet run --project ./MailDevResource.AppHost/MailDevResource.AppHost.csproj @@ -212,7 +212,7 @@ _The MailDev web app should look similar to the following:_ :::image type="content" source="media/maildev-web-ui.png" lightbox="media/maildev-web-ui.png" alt-text="MailDev web-based user interface running as a container managed by .NET Aspire."::: -## Add a .NET service project to the app host for testing +## Add a .NET service project to the AppHost for testing Once .NET Aspire can successfully launch the MailDev integration, it's time to consume the connection information for MailDev within a .NET project. In .NET Aspire it's common for there to be a _hosting package_ and one or more _component packages_. For example consider: @@ -255,7 +255,7 @@ After the project has been added and references have been updated, open the _::: :::code source="snippets/MailDevResource/MailDevResource.AppHost/Program.cs"::: -After updating the _:::no-loc text="Program.cs":::_ file, launch the app host again. Then verify that the Newsletter Service started and that the environment variable `ConnectionStrings__maildev` was added to the process. From the **Resources** page, find the `newsletterservice` row, and select the **View** link on the **Details** column: +After updating the _:::no-loc text="Program.cs":::_ file, launch the AppHost again. Then verify that the Newsletter Service started and that the environment variable `ConnectionStrings__maildev` was added to the process. From the **Resources** page, find the `newsletterservice` row, and select the **View** link on the **Details** column: :::image type="content" source="media/maildev-envvar.png" lightbox="media/maildev-envvar.png" alt-text="Environment variables for Newsletter Service in .NET Aspire Dashboard."::: @@ -277,7 +277,7 @@ To test the client, add two simple `subscribe` and `unsubscribe` POST methods to > [!TIP] > Remember to reference the `System.Net.Mail` and `Microsoft.AspNetCore.Mvc` namespaces in _:::no-loc text="Program.cs":::_ if your code editor doesn't automatically add them. -Once the _:::no-loc text="Program.cs":::_ file is updated, launch the app host and use your browser, or `curl` to hit the following URLs (alternatively if you're using Visual Studio you can use `.http` files): +Once the _:::no-loc text="Program.cs":::_ file is updated, launch the AppHost and use your browser, or `curl` to hit the following URLs (alternatively if you're using Visual Studio you can use `.http` files): ```http POST /subscribe?email=test@test.com HTTP/1.1 @@ -326,7 +326,7 @@ curl -H @{ ContentType = "application/json" } -Method POST https://localhost:725 --- > [!TIP] -> Make sure that you replace the `https://localhost:7251` with the correct localhost port (the URL of the app host that you are running). +> Make sure that you replace the `https://localhost:7251` with the correct localhost port (the URL of the AppHost that you are running). If those API calls return a successful response (HTTP 200, Ok) then you should be able to select on the `maildev` resource the dashboard and the :::no-loc text="MailDev UI"::: will show the emails that have been sent to the SMTP endpoint. @@ -385,7 +385,7 @@ Here's how the flow of execution works: The interface is designed to solve the problem of sharing connection information between resources at deployment. The solution for this particular problem is described in the [.NET Aspire inner-loop networking overview](../fundamentals/networking-overview.md). Similarly to local development, many of the values are necessary to configure the app, yet they can't be determined until the app is being deployed via a tool, such as `azd` (Azure Developer CLI). -To solve this problem [.NET Aspire produces a manifest file](../deployment/manifest-format.md) which `azd` and other deployment tools interpret. Rather than specifying concrete values for connection information between resources an expression syntax is used which deployment tools evaluate. Generally the manifest file isn't visible to developers but it's possible to generate one for manual inspection. The command below can be used on the app host to produce a manifest. +To solve this problem [.NET Aspire produces a manifest file](../deployment/manifest-format.md) which `azd` and other deployment tools interpret. Rather than specifying concrete values for connection information between resources an expression syntax is used which deployment tools evaluate. Generally the manifest file isn't visible to developers but it's possible to generate one for manual inspection. The command below can be used on the AppHost to produce a manifest. ```dotnetcli dotnet run --project MailDevResource.AppHost/MailDevResource.AppHost.csproj -- --publisher manifest --output-path aspire-manifest.json diff --git a/docs/extensibility/interaction-service.md b/docs/extensibility/interaction-service.md index 9dc048a395..8ddf820b76 100644 --- a/docs/extensibility/interaction-service.md +++ b/docs/extensibility/interaction-service.md @@ -8,7 +8,7 @@ ms.date: 07/21/2025 The interaction service (`Aspire.Hosting.IInteractionService`) allows you to prompt users for input, request confirmation, and display messages. The interaction service works in two different contexts: -- **Aspire dashboard**: When running `aspire run` or launching the app host directly, interactions appear as dialogs and notifications in the dashboard UI. +- **Aspire dashboard**: When running `aspire run` or launching the AppHost directly, interactions appear as dialogs and notifications in the dashboard UI. - **Aspire CLI**: When running `aspire publish` or `aspire deploy`, interactions are prompted through the command-line interface. This is useful for scenarios where you need to gather information from the user or provide feedback on the status of operations, regardless of how the application is being launched or deployed. @@ -36,7 +36,7 @@ if (interactionService.IsAvailable) The interaction service has several methods that you use to interact with users or display messages. The behavior of these methods depends on the execution context: -- **Dashboard context** (`aspire run` or direct app host launch): Interactions appear as modal dialogs, notifications, and form inputs in the [Aspire dashboard web interface](../fundamentals/dashboard/overview.md). +- **Dashboard context** (`aspire run` or direct AppHost launch): Interactions appear as modal dialogs, notifications, and form inputs in the [Aspire dashboard web interface](../fundamentals/dashboard/overview.md). - **CLI context** (`aspire publish` or `aspire deploy`): Interactions are prompted through the command-line interface with text-based prompts and responses. The following sections describe how to use these APIs effectively in both contexts: @@ -333,7 +333,7 @@ The interaction service behaves differently depending on how your Aspire solutio ### Dashboard context -When you run your application using `aspire run` or by directly launching the app host project, interactions appear in the Aspire dashboard web interface: +When you run your application using `aspire run` or by directly launching the AppHost project, interactions appear in the Aspire dashboard web interface: - **Modal dialogs**: Message boxes and input prompts appear as overlay dialogs that require user interaction. - **Notification messages**: Informational messages appear as dismissible banners at the top of the dashboard. diff --git a/docs/extensibility/secure-communication-between-integrations.md b/docs/extensibility/secure-communication-between-integrations.md index 4b368895b2..1ef067fd88 100644 --- a/docs/extensibility/secure-communication-between-integrations.md +++ b/docs/extensibility/secure-communication-between-integrations.md @@ -22,7 +22,7 @@ Since this article continues from previous content, you should have already crea The resulting solution from these previous articles contains the following projects: - _MailDev.Hosting_: Contains the custom resource type for the MailDev container. -- _MailDevResource.AppHost_: The [app host](../fundamentals/app-host-overview.md) that uses the custom resource and defines it as a dependency for a Newsletter service. +- _MailDevResource.AppHost_: The [AppHost](../fundamentals/app-host-overview.md) that uses the custom resource and defines it as a dependency for a Newsletter service. - _MailDevResource.NewsletterService_: An ASP.NET Core Web API project that sends emails using the MailDev container. - _MailDevResource.ServiceDefaults_: Contains the [default service configurations](../fundamentals/service-defaults.md) intended for sharing. - _MailKit.Client_: Contains the custom client integration that exposes the MailKit `SmtpClient` through a factory. @@ -41,9 +41,9 @@ These updates add a `UsernameParameter` and `PasswordParameter` property. These The preceding code updates the `AddMailDev` extension method to include the `userName` and `password` parameters. The `WithEnvironment` method is updated to include the `UserEnvVarName` and `PasswordEnvVarName` environment variables. These environment variables are used to set the MailDev username and password. -## Update the app host +## Update the AppHost -Now that the resource is updated to include the username and password parameters, you need to update the app host to include these parameters. Update the _:::no-loc text="Program.cs":::_ file in the `MailDevResource.AppHost` project with the following C# code: +Now that the resource is updated to include the username and password parameters, you need to update the AppHost to include these parameters. Update the _:::no-loc text="Program.cs":::_ file in the `MailDevResource.AppHost` project with the following C# code: :::code source="snippets/MailDevResourceWithCredentials/MailDevResource.AppHost/Program.cs" highlight="3-4,6-9"::: @@ -77,7 +77,7 @@ When the factory determines that credentials have been configured, it authentica ## Run the sample -Now that you've updated the resource, corresponding integration projects, and the app host, you're ready to run the sample app. To run the sample from your IDE, select F5 or use `dotnet run` from the root directory of the solution to start the application—you should see the [.NET Aspire dashboard](../fundamentals/dashboard/overview.md). Navigate to the `maildev` container resource and view the details. You should see the username and password parameters in the resource details, under the **Environment Variables** section: +Now that you've updated the resource, corresponding integration projects, and the AppHost, you're ready to run the sample app. To run the sample from your IDE, select F5 or use `dotnet run` from the root directory of the solution to start the application—you should see the [.NET Aspire dashboard](../fundamentals/dashboard/overview.md). Navigate to the `maildev` container resource and view the details. You should see the username and password parameters in the resource details, under the **Environment Variables** section: :::image type="content" source="media/maildev-details.png" lightbox="media/maildev-details.png" alt-text=".NET Aspire Dashboard: MailDev container resource details."::: diff --git a/docs/frameworks/orleans.md b/docs/frameworks/orleans.md index 7921e0f685..4914ecce9d 100644 --- a/docs/frameworks/orleans.md +++ b/docs/frameworks/orleans.md @@ -1,6 +1,6 @@ --- title: .NET Aspire Orleans integration -description: Learn how to use the .NET Aspire Orleans hosting integration, which can configure and orchestrate Orleans from a .NET Aspire app host project. +description: Learn how to use the .NET Aspire Orleans hosting integration, which can configure and orchestrate Orleans from a .NET Aspire AppHost project. ms.date: 11/05/2024 uid: frameworks/orleans --- @@ -9,14 +9,14 @@ uid: frameworks/orleans [Orleans](https://github.com/dotnet/orleans) has built-in support for .NET Aspire. .NET Aspire's application model lets you describe the services, databases, and other resources and infrastructure in your app and how they relate to each other. Orleans provides a straightforward way to build distributed applications that are elastically scalable and fault-tolerant. You can use .NET Aspire to configure and orchestrate Orleans and its dependencies, such as by providing Orleans with cluster membership and storage. -Orleans is represented as a resource in .NET Aspire. Unlike other integrations, the Orleans integration doesn't create a container and doesn't require a separate client integration package. Instead you complete the Orleans configuration in the .NET Aspire app host project. +Orleans is represented as a resource in .NET Aspire. Unlike other integrations, the Orleans integration doesn't create a container and doesn't require a separate client integration package. Instead you complete the Orleans configuration in the .NET Aspire AppHost project. > [!NOTE] > This integration requires Orleans version 8.1.0 or later. ## Hosting integration -The Orleans hosting integration models an Orleans service as the type. To access this type and APIs, add the [📦 Aspire.Hosting.Orleans](https://www.nuget.org/packages/Aspire.Hosting.Orleans) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +The Orleans hosting integration models an Orleans service as the type. To access this type and APIs, add the [📦 Aspire.Hosting.Orleans](https://www.nuget.org/packages/Aspire.Hosting.Orleans) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -37,7 +37,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add an Orleans resource -In your app host project, call to add and return an Orleans service resource builder. The name provided to the Orleans resource is for diagnostic purposes. For most applications, a value of `"default"` suffices. +In your AppHost project, call to add and return an Orleans service resource builder. The name provided to the Orleans resource is for diagnostic purposes. For most applications, a value of `"default"` suffices. :::code language="csharp" source="snippets/Orleans/OrleansAppHost/Program.cs" range="12"::: @@ -47,7 +47,7 @@ In an Orleans app, the fundamental building block is a **grain**. Grains can hav Orleans hosts register themselves in a database and use that database to find each other and form a cluster. They store which servers are members of which silos in a database table. You can use either relational or NoSQL databases to store this information. In a .NET Aspire application, a popular choice to store this table is **Azure Table Storage**. -To configure Orleans with clustering and grain storage in Azure, install the [📦 Aspire.Hosting.Azure.Storage](https://www.nuget.org/packages/Aspire.Hosting.Azure.Storage) NuGet package in the app host project: +To configure Orleans with clustering and grain storage in Azure, install the [📦 Aspire.Hosting.Azure.Storage](https://www.nuget.org/packages/Aspire.Hosting.Azure.Storage) NuGet package in the AppHost project: ### [.NET CLI](#tab/dotnet-cli) @@ -64,19 +64,19 @@ dotnet add package Aspire.Hosting.Azure.Storage --- -In your app host project, after you call , configure the Orleans resource with clustering and grain storage using the and methods respectively: +In your AppHost project, after you call , configure the Orleans resource with clustering and grain storage using the and methods respectively: :::code language="csharp" source="snippets/Orleans/OrleansAppHost/Program.cs" range="3-14" highlight="4-5,11-12"::: The preceding code tells Orleans that any service referencing it must also reference the `clusteringTable` resource. -### Add an Orleans server project in the app host +### Add an Orleans server project in the AppHost Now you can add a new project, enrolled in .NET Aspire orchestration, to your solution as an Orleans server. It will take part in the Orleans cluster as a silo with constituent grains. Reference the Orleans resource from your server project using `WithReference(orleans)`. When you reference the Orleans resource from your service, those resources are also referenced: :::code language="csharp" source="snippets/Orleans/OrleansAppHost/Program.cs" range="16-22"::: -### Add an Orleans client project in the app host +### Add an Orleans client project in the AppHost Orleans clients communicate with grains hosted on Orleans servers. In a .NET Aspire app, for example, you might have a front-end Web site that calls grains in an Orleans cluster. Reference the Orleans resource from your Orleans client using `WithReference(orleans.AsClient())`. @@ -84,7 +84,7 @@ Orleans clients communicate with grains hosted on Orleans servers. In a .NET Asp ## Create the Orleans server project -Now that the app host project is completed, you can implement the Orleans server project. Let's start by adding the necessary NuGet packages: +Now that the AppHost project is completed, you can implement the Orleans server project. Let's start by adding the necessary NuGet packages: ### [.NET CLI](#tab/dotnet-cli) diff --git a/docs/fundamentals/annotations-overview.md b/docs/fundamentals/annotations-overview.md index 3c00f5482f..28f59e3f2c 100644 --- a/docs/fundamentals/annotations-overview.md +++ b/docs/fundamentals/annotations-overview.md @@ -142,7 +142,7 @@ Start by creating a class that implements `IResourceAnnotation`. Focus on captur ### 2. Create extension methods -Create fluent extension methods that follow .NET Aspire's builder pattern. These methods should make it easy for app host authors to configure your annotation: +Create fluent extension methods that follow .NET Aspire's builder pattern. These methods should make it easy for AppHost authors to configure your annotation: :::code source="snippets/annotations-overview/Program.cs" id="ServiceMetricsExtensions"::: @@ -155,7 +155,7 @@ The extension methods serve as the primary API surface for your annotation. They ### 3. Use the custom annotation -Once defined, annotations integrate seamlessly into the app host model: +Once defined, annotations integrate seamlessly into the AppHost model: ```csharp var builder = DistributedApplication.CreateBuilder(args); diff --git a/docs/fundamentals/app-host-overview.md b/docs/fundamentals/app-host-overview.md index 7b01fad669..350b424394 100644 --- a/docs/fundamentals/app-host-overview.md +++ b/docs/fundamentals/app-host-overview.md @@ -1,7 +1,7 @@ --- title: .NET Aspire orchestration overview description: Learn the fundamental concepts of .NET Aspire orchestration and explore the various APIs for adding resources and expressing dependencies. -ms.date: 04/23/2025 +ms.date: 08/07/2025 ms.topic: overview uid: dotnet/aspire/app-host ms.custom: @@ -18,9 +18,9 @@ ms.custom: Before continuing, consider some common terminology used in .NET Aspire: - **App model**: A collection of resources that make up your distributed application (), defined within the namespace. For a more formal definition, see [Define the app model](#define-the-app-model). -- **App host/Orchestrator project**: The .NET project that orchestrates the _app model_, named with the _*.AppHost_ suffix (by convention). +- **AppHost/Orchestrator project**: The .NET project that orchestrates the _app model_, named with the _*.AppHost_ suffix (by convention). - **Resource**: A [resource](#built-in-resource-types) is a dependent part of an application, such as a .NET project, container, executable, database, cache, or cloud service. It represents any part of the application that can be managed or referenced. -- **Integration**: An integration is a NuGet package for either the _app host_ that models a _resource_ or a package that configures a client for use in a consuming app. For more information, see [.NET Aspire integrations overview](integrations-overview.md). +- **Integration**: An integration is a NuGet package for either the _AppHost_ that models a _resource_ or a package that configures a client for use in a consuming app. For more information, see [.NET Aspire integrations overview](integrations-overview.md). - **Reference**: A reference defines a connection between resources, expressed as a dependency using the API. For more information, see [Reference resources](#reference-resources) or [Reference existing resources](#reference-existing-resources). > [!NOTE] @@ -32,7 +32,7 @@ Before continuing, consider some common terminology used in .NET Aspire: The app model is more than just a list of resources—it represents the complete topology of your application. This includes the relationships between resources, their dependencies, and their configurations. Resources can include projects, executables, containers, external services, and cloud resources that your application relies on. -In your [.NET Aspire app host project](#app-host-project), your `Program` file defines your app model: +In your [.NET Aspire AppHost project](#apphost-project), your `Program` file defines your app model: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -44,9 +44,9 @@ builder.Build().Run(); When you call , you get an instance of , which is used to configure your app model. This builder provides methods to add resources, define dependencies, and set up the overall structure of your application. After you've added resources, call `Build` to create the app model. The [templates](../fundamentals/aspire-sdk-templates.md) include code that chains a call to —which returns an instance, and then calls . -## App host project +## AppHost project -The app host project handles running all of the projects that are part of the .NET Aspire project. In other words, it's responsible for orchestrating all apps within the app model. The project itself is a .NET executable project that references the [📦 Aspire.Hosting.AppHost](https://www.nuget.org/packages/Aspire.Hosting.AppHost) NuGet package, and uses the [.NET Aspire SDK](dotnet-aspire-sdk.md): +The AppHost project handles running all of the projects that are part of the .NET Aspire project. In other words, it's responsible for orchestrating all apps within the app model. The project itself is a .NET executable project that references the [📦 Aspire.Hosting.AppHost](https://www.nuget.org/packages/Aspire.Hosting.AppHost) NuGet package, and uses the [.NET Aspire SDK](dotnet-aspire-sdk.md): ```xml @@ -68,7 +68,7 @@ The app host project handles running all of the projects that are part of the .N ``` -The following code describes an app host `Program` with two project references and a Redis cache: +The following code describes an AppHost `Program` with two project references and a Redis cache: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -100,7 +100,7 @@ The preceding code: The example code uses the [.NET Aspire Redis hosting integration](../caching/stackexchange-redis-integration.md#hosting-integration). -To help visualize the relationship between the app host project and the resources it describes, consider the following diagram: +To help visualize the relationship between the AppHost project and the resources it describes, consider the following diagram: :::image type="content" source="../media/app-host-resource-diagram.png" lightbox="../media/app-host-resource-diagram.png" alt-text="The relationship between the projects in the .NET Aspire Starter Application template."::: @@ -117,7 +117,7 @@ Each resource must be uniquely named. This diagram shows each resource and the r | | | An executable file, such as a [Node.js app](../get-started/build-aspire-apps-with-nodejs.md). | | | | A parameter resource that can be used to [express external parameters](external-parameters.md). | -Project resources represent .NET projects that are part of the app model. When you add a project reference to the app host project, the .NET Aspire SDK generates a type in the `Projects` namespace for each referenced project. For more information, see [.NET Aspire SDK: Project references](dotnet-aspire-sdk.md#project-references). +Project resources represent .NET projects that are part of the app model. When you add a project reference to the AppHost project, the .NET Aspire SDK generates a type in the `Projects` namespace for each referenced project. For more information, see [.NET Aspire SDK: Project references](dotnet-aspire-sdk.md#project-references). To add a project to the app model, use the method: @@ -142,7 +142,7 @@ The preceding code adds three replicas of the "apiservice" project resource to t ## Reference resources -A reference represents a dependency between resources. For example, you can probably imagine a scenario where a web frontend depends on a Redis cache. Consider the following example app host `Program` C# code: +A reference represents a dependency between resources. For example, you can probably imagine a scenario where a web frontend depends on a Redis cache. Consider the following example AppHost `Program` C# code: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -210,7 +210,7 @@ The `port` parameter is the port that the container is listening on. For more in In the preceding section, the method is used to express dependencies between resources. When service endpoints result in environment variables being injected into the dependent resource, the format might not be obvious. This section provides details on this format. -When one resource depends on another resource, the app host injects environment variables into the dependent resource. These environment variables configure the dependent resource to connect to the resource it depends on. The format of the environment variables is specific to .NET Aspire and expresses service endpoints in a way that is compatible with [Service Discovery](../service-discovery/overview.md). +When one resource depends on another resource, the AppHost injects environment variables into the dependent resource. These environment variables configure the dependent resource to connect to the resource it depends on. The format of the environment variables is specific to .NET Aspire and expresses service endpoints in a way that is compatible with [Service Discovery](../service-discovery/overview.md). Service endpoint environment variable names are prefixed with `services__` (double underscore), then the service name, the endpoint name, and finally the index. The index supports multiple endpoints for a single service, starting with `0` for the first endpoint and incrementing for each endpoint. @@ -230,13 +230,13 @@ In the preceding example, the `apiservice` service has a named endpoint called ` ## Reference existing resources -Some situations warrant that you reference an existing resource, perhaps one that is deployed to a cloud provider. For example, you might want to reference an Azure database. In this case, you'd rely on the [Execution context](#execution-context) to dynamically determine whether the app host is running in "run" mode or "publish" mode. If you're running locally and want to rely on a cloud resource, you can use the `IsRunMode` property to conditionally add the reference. You might choose to instead create the resource in publish mode. Some [hosting integrations](integrations-overview.md#hosting-integrations) support providing a connection string directly, which can be used to reference an existing resource. +Some situations warrant that you reference an existing resource, perhaps one that is deployed to a cloud provider. For example, you might want to reference an Azure database. In this case, you'd rely on the [Execution context](#execution-context) to dynamically determine whether the AppHost is running in "run" mode or "publish" mode. If you're running locally and want to rely on a cloud resource, you can use the `IsRunMode` property to conditionally add the reference. You might choose to instead create the resource in publish mode. Some [hosting integrations](integrations-overview.md#hosting-integrations) support providing a connection string directly, which can be used to reference an existing resource. -Likewise, there might be use cases where you want to integrate .NET Aspire into an existing solution. One common approach is to add the .NET Aspire app host project to an existing solution. Within your app host, you express dependencies by adding project references to the app host and [building out the app model](#define-the-app-model). For example, one project might depend on another. These dependencies are expressed using the method. For more information, see [Add .NET Aspire to an existing .NET app](../get-started/add-aspire-existing-app.md). +Likewise, there might be use cases where you want to integrate .NET Aspire into an existing solution. One common approach is to add the .NET Aspire AppHost project to an existing solution. Within your AppHost, you express dependencies by adding project references to the AppHost and [building out the app model](#define-the-app-model). For example, one project might depend on another. These dependencies are expressed using the method. For more information, see [Add .NET Aspire to an existing .NET app](../get-started/add-aspire-existing-app.md). ## Execution context -The exposes an execution context (), which provides information about the current execution of the app host. This context can be used to evaluate whether or not the app host is executing as "run" mode, or as part of a publish operation. Consider the following properties: +The exposes an execution context (), which provides information about the current execution of the AppHost. This context can be used to evaluate whether or not the AppHost is executing as "run" mode, or as part of a publish operation. Consider the following properties: - : Returns `true` if the current operation is running. - : Returns `true` if the current operation is publishing. @@ -278,8 +278,8 @@ builder.Build().Run(); In the preceding code: -- If the app host is in "run" mode, a Redis container resource is added. -- If the app host is in "publish" mode, a connection string is added. +- If the AppHost is in "run" mode, a Redis container resource is added. +- If the AppHost is in "publish" mode, a connection string is added. This logic can easily be inverted to connect to an existing Redis resource when you're running locally, and create a new Redis resource when you're publishing. diff --git a/docs/fundamentals/aspire-sdk-templates.md b/docs/fundamentals/aspire-sdk-templates.md index bdbd07139c..68b9f80b04 100644 --- a/docs/fundamentals/aspire-sdk-templates.md +++ b/docs/fundamentals/aspire-sdk-templates.md @@ -43,7 +43,7 @@ The following .NET Aspire project templates are available: -- **.NET Aspire App Host**: A standalone **.AppHost** project that can be used to orchestrate and manage the different projects and services of your app. +- **.NET Aspire AppHost**: A standalone **.AppHost** project that can be used to orchestrate and manage the different projects and services of your app. @@ -94,7 +94,7 @@ Select the desired location, enter a name, and select **Create**. To create a .NET Aspire solution or project using the .NET CLI, use the [dotnet new](/dotnet/core/tools/dotnet-new) command and specify which template you would like to create. Consider the following examples: -To create a basic [.NET Aspire app host](app-host-overview.md) project targeting the latest .NET version: +To create a basic [.NET Aspire AppHost](app-host-overview.md) project targeting the latest .NET version: ```dotnetcli dotnet new aspire-apphost @@ -107,7 +107,7 @@ dotnet new aspire-starter ``` > [!TIP] -> .NET Aspire templates default to using the latest .NET version, even when using an earlier version of the .NET CLI. To manually specify the .NET version, use the `--framework ` option, e.g. to create a basic [.NET Aspire app host](app-host-overview.md) project targeting .NET 8: +> .NET Aspire templates default to using the latest .NET version, even when using an earlier version of the .NET CLI. To manually specify the .NET version, use the `--framework ` option, e.g. to create a basic [.NET Aspire AppHost](app-host-overview.md) project targeting .NET 8: > > ```dotnetcli > dotnet new aspire-apphost --framework net8.0 diff --git a/docs/fundamentals/build-container-images.md b/docs/fundamentals/build-container-images.md index 1b0f74e904..2764c8294f 100644 --- a/docs/fundamentals/build-container-images.md +++ b/docs/fundamentals/build-container-images.md @@ -1,7 +1,7 @@ --- title: Build container images description: Learn how to build container images from your .NET Aspire resources. -ms.date: 07/25/2025 +ms.date: 08/07/2025 ai-usage: ai-assisted --- @@ -13,10 +13,8 @@ ai-usage: ai-assisted During publishing and deployment, the container image builder is available to create images for resources that need them. Aspire uses this builder when a resource requires a container image, such as when publishing with Docker Compose. The process involves two main components: - - -- `IResourceContainerImageBuilder`: The service that turns resource definitions into runnable container images. -- `PublishingActivityProgressReporter`: The API that provides structured progress reporting during long-running operations. +- : The service that turns resource definitions into runnable container images. +- : The API that provides structured progress reporting during long-running operations. These APIs give you fine-grained control over the image building process and provide real-time feedback to users during lengthy build operations. @@ -45,9 +43,7 @@ The `IResourceContainerImageBuilder` is the core service in the - -The `ContainerBuildOptions` class provides strongly typed configuration for container builds. This class allows you to specify: +The class provides strongly typed configuration for container builds. This class allows you to specify: - **Image format**: Docker or Open Container Initiative (OCI) format. - **Target platform**: Linux x64, Windows, ARM64, etc. diff --git a/docs/fundamentals/custom-resource-commands.md b/docs/fundamentals/custom-resource-commands.md index 58e079cbf4..3efc7ffdc9 100644 --- a/docs/fundamentals/custom-resource-commands.md +++ b/docs/fundamentals/custom-resource-commands.md @@ -1,7 +1,7 @@ --- -title: Custom resource commands in .NET Aspire +title: Custom resource commands description: Learn how to create custom resource commands in .NET Aspire. -ms.date: 11/07/2024 +ms.date: 08/07/2025 ms.topic: how-to ms.custom: sfi-ropc-nochange --- @@ -15,13 +15,13 @@ Each resource in the .NET Aspire [app model](app-host-overview.md#define-the-app ## Add custom commands to a resource -Start by creating a new .NET Aspire Starter App from the [available templates](aspire-sdk-templates.md). To create the solution from this template, follow the [Quickstart: Build your first .NET Aspire solution](../get-started/build-your-first-aspire-app.md). After creating this solution, add a new class named _RedisResourceBuilderExtensions.cs_ to the [app host project](app-host-overview.md#app-host-project). Replace the contents of the file with the following code: +Start by creating a new .NET Aspire Starter App from the [available templates](aspire-sdk-templates.md). To create the solution from this template, follow the [Quickstart: Build your first .NET Aspire solution](../get-started/build-your-first-aspire-app.md). After creating this solution, add a new class named _RedisResourceBuilderExtensions.cs_ to the [AppHost project](app-host-overview.md#apphost-project). Replace the contents of the file with the following code: :::code source="snippets/custom-commands/AspireApp/AspireApp.AppHost/RedisResourceBuilderExtensions.cs"::: The preceding code: -- Shares the namespace so that it's visible to the app host project. +- Shares the namespace so that it's visible to the AppHost project. - Is a `static class` so that it can contain extension methods. - It defines a single extension method named `WithClearCommand`, extending the `IResourceBuilder` interface. - The `WithClearCommand` method registers a command named `clear-cache` that clears the cache of the Redis resource. @@ -109,7 +109,7 @@ The preceding code: ## Test the custom command -To test the custom command, update your app host project's _Program.cs_ file to include the following code: +To test the custom command, update your AppHost project's _Program.cs_ file to include the following code: :::code source="snippets/custom-commands/AspireApp/AspireApp.AppHost/Program.cs" highlight="4"::: diff --git a/docs/fundamentals/custom-resource-urls.md b/docs/fundamentals/custom-resource-urls.md index 9c57819031..3257048089 100644 --- a/docs/fundamentals/custom-resource-urls.md +++ b/docs/fundamentals/custom-resource-urls.md @@ -79,4 +79,4 @@ URL customization callbacks run during the application model lifecycle, specific ## See also - [.NET Aspire dashboard overview](dashboard/overview.md) -- [.NET Aspire app host](app-host-overview.md) +- [.NET Aspire AppHost](app-host-overview.md) diff --git a/docs/fundamentals/dashboard/automation/aspire-dashboard/Aspire.Dashboard.ScreenCapture/README.md b/docs/fundamentals/dashboard/automation/aspire-dashboard/Aspire.Dashboard.ScreenCapture/README.md index df5907f3fc..f2742dbb2a 100644 --- a/docs/fundamentals/dashboard/automation/aspire-dashboard/Aspire.Dashboard.ScreenCapture/README.md +++ b/docs/fundamentals/dashboard/automation/aspire-dashboard/Aspire.Dashboard.ScreenCapture/README.md @@ -9,7 +9,7 @@ ms.date: 04/10/2025 This solution contains the following projects: - **Aspire.Dashboard.ScreenCapture**: This project contains the screen capture tests for the .NET Aspire Dashboard. It uses Playwright to automate the browser and capture images of the dashboard. -- **AspireSample.AppHost**: This project contains the .NET Aspire app host, which orchestrates the an API and Web frontend. +- **AspireSample.AppHost**: This project contains the .NET Aspire AppHost, which orchestrates the an API and Web frontend. - **AspireSample.ApiService**: This is an ASP.NET Core Minimal API service that provides a REST API for weather forecasts. - **AspireSample.Web**: This is a Blazor app that provides a web frontend. - **AspireSample.ServiceDefaults**: This project contains the default service settings for the API and Web apps. diff --git a/docs/fundamentals/dashboard/configuration.md b/docs/fundamentals/dashboard/configuration.md index 920d7f4a1b..410eb2c611 100644 --- a/docs/fundamentals/dashboard/configuration.md +++ b/docs/fundamentals/dashboard/configuration.md @@ -9,7 +9,7 @@ ms.topic: reference The dashboard is configured when it starts up. Configuration includes frontend and OpenTelemetry Protocol (OTLP) addresses, the resource service endpoint, authentication, telemetry limits, and more. -When the dashboard is launched with the .NET Aspire app host project, it's automatically configured to display the app's resources and telemetry. Configuration is provided when launching the dashboard in [standalone mode](overview.md#standalone-mode). +When the dashboard is launched with the .NET Aspire AppHost project, it's automatically configured to display the app's resources and telemetry. Configuration is provided when launching the dashboard in [standalone mode](overview.md#standalone-mode). There are many ways to provide configuration: @@ -63,15 +63,15 @@ Alternatively, these same values could be configured using a JSON configuration > For more information, see [dashboard security](security-considerations.md). > [!NOTE] -> Configuration described on this page is for the standalone dashboard. To configure an .NET Aspire app host project, see [App host configuration](../../app-host/configuration.md). +> Configuration described on this page is for the standalone dashboard. To configure an .NET Aspire AppHost project, see [AppHost configuration](../../app-host/configuration.md). ## Common configuration | Option | Default value | Description | |--|--|--| -| `ASPNETCORE_URLS` | `http://localhost:18888` | One or more HTTP endpoints through which the dashboard frontend is served. The frontend endpoint is used to view the dashboard in a browser. When the dashboard is launched by the .NET Aspire app host this address is secured with HTTPS. Securing the dashboard with HTTPS is recommended. | -| `ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL` | `http://localhost:18889` | The [OTLP/gRPC](https://opentelemetry.io/docs/specs/otlp/#otlpgrpc) endpoint. This endpoint hosts an OTLP service and receives telemetry using gRPC. When the dashboard is launched by the .NET Aspire app host this address is secured with HTTPS. Securing the dashboard with HTTPS is recommended. | -| `ASPIRE_DASHBOARD_OTLP_HTTP_ENDPOINT_URL` | `http://localhost:18890` | The [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp) endpoint. This endpoint hosts an OTLP service and receives telemetry using Protobuf over HTTP. When the dashboard is launched by the .NET Aspire app host the OTLP/HTTP endpoint isn't configured by default. To configure an OTLP/HTTP endpoint with the app host, set an `ASPIRE_DASHBOARD_OTLP_HTTP_ENDPOINT_URL` env var value in _launchSettings.json_. Securing the dashboard with HTTPS is recommended. | +| `ASPNETCORE_URLS` | `http://localhost:18888` | One or more HTTP endpoints through which the dashboard frontend is served. The frontend endpoint is used to view the dashboard in a browser. When the dashboard is launched by the .NET Aspire AppHost this address is secured with HTTPS. Securing the dashboard with HTTPS is recommended. | +| `ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL` | `http://localhost:18889` | The [OTLP/gRPC](https://opentelemetry.io/docs/specs/otlp/#otlpgrpc) endpoint. This endpoint hosts an OTLP service and receives telemetry using gRPC. When the dashboard is launched by the .NET Aspire AppHost this address is secured with HTTPS. Securing the dashboard with HTTPS is recommended. | +| `ASPIRE_DASHBOARD_OTLP_HTTP_ENDPOINT_URL` | `http://localhost:18890` | The [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp) endpoint. This endpoint hosts an OTLP service and receives telemetry using Protobuf over HTTP. When the dashboard is launched by the .NET Aspire AppHost the OTLP/HTTP endpoint isn't configured by default. To configure an OTLP/HTTP endpoint with the AppHost, set an `ASPIRE_DASHBOARD_OTLP_HTTP_ENDPOINT_URL` env var value in _launchSettings.json_. Securing the dashboard with HTTPS is recommended. | | `ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS` | `false` | Configures the dashboard to not use authentication and accepts anonymous access. This setting is a shortcut to configuring `Dashboard:Frontend:AuthMode` and `Dashboard:Otlp:AuthMode` to `Unsecured`. | | `ASPIRE_DASHBOARD_CONFIG_FILE_PATH` | `null` | The path for a JSON configuration file. If the dashboard is being run in a Docker container, then this is the path to the configuration file in a mounted volume. This value is optional. | | `ASPIRE_DASHBOARD_FILE_CONFIG_DIRECTORY` | `null` | The directory where the dashboard looks for key-per-file configuration. This value is optional. | diff --git a/docs/fundamentals/dashboard/copilot.md b/docs/fundamentals/dashboard/copilot.md index 08e4d8838e..848fb973b4 100644 --- a/docs/fundamentals/dashboard/copilot.md +++ b/docs/fundamentals/dashboard/copilot.md @@ -39,7 +39,7 @@ To get started, launch your .NET Aspire solution as usual in your IDE. 2. Ensure you're logged into the IDE with a GitHub account: - For Visual Studio, see [Add your GitHub accounts to your Visual Studio keychain](https://aka.ms/dotnet/aspire/copilot-vs-login). - For VS Code and C# Dev Kit, see [Set up GitHub Copilot in VS Code](https://aka.ms/dotnet/aspire/copilot-vscode-login). -3. Run the .NET Aspire app host. +3. Run the .NET Aspire AppHost. A GitHub Copilot button appears in the top-right corner of the dashboard. Selecting the button opens the Copilot UI. @@ -93,7 +93,7 @@ AI models have limits on how much data they can process at once. The .NET Aspire GitHub Copilot only accesses data when you explicitly interact with it. For example, submitting a chat query or selecting **Ask GitHub Copilot** from a context menu. -If you prefer to disable the feature entirely, set the `ASPIRE_DASHBOARD_AI_DISABLED` environment variable to `true` in your app host's _launchSettings.json_ file. This hides all Copilot UI elements in the dashboard. +If you prefer to disable the feature entirely, set the `ASPIRE_DASHBOARD_AI_DISABLED` environment variable to `true` in your AppHost's _launchSettings.json_ file. This hides all Copilot UI elements in the dashboard. :::code language="json" source="snippets/DisableAI/AspireApp/AspireApp.AppHost/Properties/launchSettings.json" highlight="14"::: diff --git a/docs/fundamentals/dashboard/enable-browser-telemetry.md b/docs/fundamentals/dashboard/enable-browser-telemetry.md index 4f28bdd778..6a61486f71 100644 --- a/docs/fundamentals/dashboard/enable-browser-telemetry.md +++ b/docs/fundamentals/dashboard/enable-browser-telemetry.md @@ -26,11 +26,11 @@ To configure the gPRC or HTTP endpoints, specify the following environment varia - `ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL`: The gRPC endpoint to which the dashboard connects for its data. - `ASPIRE_DASHBOARD_OTLP_HTTP_ENDPOINT_URL`: The HTTP endpoint to which the dashboard connects for its data. -Configuration of the HTTP OTLP endpoint depends on whether the dashboard is started by the app host or is run standalone. +Configuration of the HTTP OTLP endpoint depends on whether the dashboard is started by the AppHost or is run standalone. -#### Configure OTLP HTTP with app host +#### Configure OTLP HTTP with AppHost -If the dashboard and your app are started by the app host, the dashboard OTLP endpoints are configured in the app host's _launchSettings.json_ file. +If the dashboard and your app are started by the AppHost, the dashboard OTLP endpoints are configured in the AppHost's _launchSettings.json_ file. Consider the following example JSON file: @@ -72,7 +72,7 @@ The preceding command runs the dashboard container and maps gRPC OTLP to port `4 By default, browser apps are restricted from making cross domain API calls. This impacts sending telemetry to the dashboard because the dashboard and the browser app are always on different domains. Configuring CORS in the .NET Aspire dashboard removes the restriction. -If the dashboard and your app are started by the app host, no CORS configuration is required. .NET Aspire automatically configures the dashboard to allow all resource origins. +If the dashboard and your app are started by the AppHost, no CORS configuration is required. .NET Aspire automatically configures the dashboard to allow all resource origins. If the dashboard is used standlone then CORS must be configured manually. The domain used to view the browser app must be configured as an allowed origin by specifing the `DASHBOARD__OTLP__CORS__ALLOWEDORIGINS` environment variable when the dashboard container is started: @@ -112,7 +112,7 @@ For more information, see [.NET Aspire dashboard configuration: OTLP CORS](confi Dashboard OTLP endpoints can be secured with API key authentication. When enabled, HTTP OTLP requests to the dashboard must include the API key as the `x-otlp-api-key` header. By default a new API key is generated each time the dashboard is run. -API key authentication is automatically enabled when the dashboard is run from the app host. Dashboard authentication can be disabled by setting `ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS` to `true` in the app host's _launchSettings.json_ file. +API key authentication is automatically enabled when the dashboard is run from the AppHost. Dashboard authentication can be disabled by setting `ASPIRE_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS` to `true` in the AppHost's _launchSettings.json_ file. OTLP endpoints are unsecured by default in the standalone dashboard. @@ -126,9 +126,9 @@ OTLP exporters must be included in the browser app and configured with the SDK. When OTLP is added to the SDK, OTLP options must be specified. OTLP options includes: -- `url`: The address that HTTP OTLP requests are made to. The address should be the dashboard HTTP OTLP endpoint and the path to the OTLP HTTP API. For example, `https://localhost:4318/v1/traces` for the trace OTLP exporter. If the browser app is launched by the app host then the HTTP OTLP endpoint is available from the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable. +- `url`: The address that HTTP OTLP requests are made to. The address should be the dashboard HTTP OTLP endpoint and the path to the OTLP HTTP API. For example, `https://localhost:4318/v1/traces` for the trace OTLP exporter. If the browser app is launched by the AppHost then the HTTP OTLP endpoint is available from the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable. -- `headers`: The headers sent with requests. If OTLP endpoint API key authentication is enabled the `x-otlp-api-key` header must be sent with OTLP requests. If the browser app is launched by the app host then the API key is available from the `OTEL_EXPORTER_OTLP_HEADERS` environment variable. +- `headers`: The headers sent with requests. If OTLP endpoint API key authentication is enabled the `x-otlp-api-key` header must be sent with OTLP requests. If the browser app is launched by the AppHost then the API key is available from the `OTEL_EXPORTER_OTLP_HEADERS` environment variable. ### Browser metadata @@ -154,7 +154,7 @@ The following JavaScript code demonstrates the initialization of the OpenTelemet :::code language="javascript" source="snippets/BrowserTelemetry/BrowserTelemetry.Web/Scripts/index.js"::: -The preceding JavaScript code defines an `initializeTelemetry` function that expects the OTLP endpoint URL, the headers, and the resource attributes. These parameters are provided by the consuming browser app that pulls them from the environment variables set by the app host. Consider the following Razor code: +The preceding JavaScript code defines an `initializeTelemetry` function that expects the OTLP endpoint URL, the headers, and the resource attributes. These parameters are provided by the consuming browser app that pulls them from the environment variables set by the AppHost. Consider the following Razor code: :::code language="razor" source="snippets/BrowserTelemetry/BrowserTelemetry.Web/Pages/Shared/_Layout.cshtml" highlight="31-38"::: diff --git a/docs/fundamentals/dashboard/explore.md b/docs/fundamentals/dashboard/explore.md index c903aa1b5d..ce6013015e 100644 --- a/docs/fundamentals/dashboard/explore.md +++ b/docs/fundamentals/dashboard/explore.md @@ -22,11 +22,11 @@ The .NET Aspire dashboard also includes **GitHub Copilot**, your AI debugging as ## Dashboard authentication -When you run a .NET Aspire app host, the orchestrator starts up all the app's dependent resources and then opens a browser window to the dashboard. The .NET Aspire dashboard requires token-based authentication for its users because it displays environment variables and other sensitive information. +When you run a .NET Aspire AppHost, the orchestrator starts up all the app's dependent resources and then opens a browser window to the dashboard. The .NET Aspire dashboard requires token-based authentication for its users because it displays environment variables and other sensitive information. When the dashboard is launched from Visual Studio or Visual Studio Code (with the [C# Dev Kit extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit)), the browser is automatically logged in, and the dashboard opens directly. This is the typical developer F5 experience, and the authentication login flow is automated by the .NET Aspire tooling. -However, if you start the app host from the command line, you're presented with the login page. The console window displays a URL that you can select on to open the dashboard in your browser. +However, if you start the AppHost from the command line, you're presented with the login page. The console window displays a URL that you can select on to open the dashboard in your browser. :::image type="content" source="media/explore/dotnet-run-login-url.png" lightbox="media/explore/dotnet-run-login-url.png" alt-text=".NET CLI run command output, showing the login URL with token query string."::: diff --git a/docs/fundamentals/dashboard/security-considerations.md b/docs/fundamentals/dashboard/security-considerations.md index 9e602e2465..00955decbb 100644 --- a/docs/fundamentals/dashboard/security-considerations.md +++ b/docs/fundamentals/dashboard/security-considerations.md @@ -17,7 +17,7 @@ The dashboard can be run in different scenarios, such as being automatically sta ### .NET Aspire tooling -The dashboard is automatically started when an .NET Aspire app host is run. The dashboard is secure by default when run from .NET Aspire tooling: +The dashboard is automatically started when an .NET Aspire AppHost is run. The dashboard is secure by default when run from .NET Aspire tooling: - Transport is secured with HTTPS. Using HTTPS is configured by default in _launchSettings.json_. The launch profile includes `https` addresses in `applicationUrl` and `ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL` values. - Browser frontend authenticated with a browser token. @@ -28,7 +28,7 @@ HTTPS in the dashboard uses the ASP.NET Core development certificate. The certif - [Trust the ASP.NET Core HTTPS development certificate on Windows and macOS](/aspnet/core/security/enforcing-ssl#trust-the-aspnet-core-https-development-certificate-on-windows-and-macos) - [Trust HTTPS certificate on Linux](/aspnet/core/security/enforcing-ssl#trust-https-certificate-on-linux) -There are scenarios where you might want to allow an unsecured transport. The dashboard can run without HTTPS from the .NET Aspire app host by configuring the `ASPIRE_ALLOW_UNSECURED_TRANSPORT` setting to `true`. For more information, see [Allow unsecured transport in .NET Aspire](../../troubleshooting/allow-unsecure-transport.md). +There are scenarios where you might want to allow an unsecured transport. The dashboard can run without HTTPS from the .NET Aspire AppHost by configuring the `ASPIRE_ALLOW_UNSECURED_TRANSPORT` setting to `true`. For more information, see [Allow unsecured transport in .NET Aspire](../../troubleshooting/allow-unsecure-transport.md). ### Standalone mode diff --git a/docs/fundamentals/dashboard/standalone-for-nodejs.md b/docs/fundamentals/dashboard/standalone-for-nodejs.md index 770bf627b5..5611780fb0 100644 --- a/docs/fundamentals/dashboard/standalone-for-nodejs.md +++ b/docs/fundamentals/dashboard/standalone-for-nodejs.md @@ -194,6 +194,6 @@ You can enhance your application with custom spans, logs, and metrics: ## Next steps -You have successfully used the .NET Aspire dashboard with a Node.js application. To learn more about the .NET Aspire dashboard, see the [Aspire dashboard overview](overview.md) and how to orchestrate a Node.js application with the [.NET Aspire app host](../../get-started/build-aspire-apps-with-nodejs.md). +You have successfully used the .NET Aspire dashboard with a Node.js application. To learn more about the .NET Aspire dashboard, see the [Aspire dashboard overview](overview.md) and how to orchestrate a Node.js application with the [.NET Aspire AppHost](../../get-started/build-aspire-apps-with-nodejs.md). To learn more about OpenTelemetry instrumentation for Node.js applications, see the [OpenTelemetry JavaScript documentation](https://opentelemetry.io/docs/languages/js/). diff --git a/docs/fundamentals/dashboard/standalone-for-python.md b/docs/fundamentals/dashboard/standalone-for-python.md index 36556ef56d..9b63e01673 100644 --- a/docs/fundamentals/dashboard/standalone-for-python.md +++ b/docs/fundamentals/dashboard/standalone-for-python.md @@ -235,4 +235,4 @@ Navigate around the Python application, and you'll see structured logs in the As ## Next steps -You have successfully used the .NET Aspire dashboard with a Python application. To learn more about the .NET Aspire dashboard, see the [Aspire dashboard overview](overview.md) and how to orchestrate a Python application with the [.NET Aspire app host](../../get-started/build-aspire-apps-with-python.md). +You have successfully used the .NET Aspire dashboard with a Python application. To learn more about the .NET Aspire dashboard, see the [Aspire dashboard overview](overview.md) and how to orchestrate a Python application with the [.NET Aspire AppHost](../../get-started/build-aspire-apps-with-python.md). diff --git a/docs/fundamentals/dotnet-aspire-sdk.md b/docs/fundamentals/dotnet-aspire-sdk.md index 82d9d7f31b..7dd3c8547e 100644 --- a/docs/fundamentals/dotnet-aspire-sdk.md +++ b/docs/fundamentals/dotnet-aspire-sdk.md @@ -1,13 +1,13 @@ --- title: .NET Aspire SDK description: Learn -ms.date: 03/19/2025 +ms.date: 08/07/2025 uid: dotnet/aspire/sdk --- # .NET Aspire SDK -The .NET Aspire SDK is intended for [_*.AppHost_ projects](app-host-overview.md#app-host-project), which serve as the .NET Aspire orchestrator. These projects are designated by their usage of the `Aspire.AppHost.Sdk` in the project file. The SDK provides a set of features that simplify the development of .NET Aspire apps. +The .NET Aspire SDK is intended for [_*.AppHost_ projects](app-host-overview.md#apphost-project), which serve as the .NET Aspire orchestrator. These projects are designated by their usage of the `Aspire.AppHost.Sdk` in the project file. The SDK provides a set of features that simplify the development of .NET Aspire apps. ## Overview @@ -40,10 +40,10 @@ The .NET Aspire SDK provides several key features. ### Project references -Each `ProjectReference` in the [.NET Aspire app host][app-host] project isn't treated as standard project references. Instead, they enable the _app host_ to execute these projects as part of its orchestration. Each project reference triggers a generator to create a `class` that represents the project as an . This metadata is used to populate the named projects in the generated `Projects` namespace. When you call the API, the `Projects` namespace is used to reference the project—passing the generated class as a generic-type parameter. +Each `ProjectReference` in the [.NET Aspire AppHost][app-host] project isn't treated as standard project references. Instead, they enable the _AppHost_ to execute these projects as part of its orchestration. Each project reference triggers a generator to create a `class` that represents the project as an . This metadata is used to populate the named projects in the generated `Projects` namespace. When you call the API, the `Projects` namespace is used to reference the project—passing the generated class as a generic-type parameter. > [!TIP] -> If you need to reference a project in the traditional way within the app host, set the `IsAspireProjectResource` attribute on the `ProjectReference` element to `false`, as shown in the following example: +> If you need to reference a project in the traditional way within the AppHost, set the `IsAspireProjectResource` attribute on the `ProjectReference` element to `false`, as shown in the following example: > > ```xml > @@ -53,8 +53,8 @@ Each `ProjectReference` in the [.NET Aspire app host][app-host] project isn't tr ### Orchestrator dependencies -The .NET Aspire SDK dynamically adds references to the [.NET Aspire dashboard](dashboard/overview.md) and other app host dependencies, such as the developer control plane (DCP) packages. These dependencies are specific to the platform that the app host is built on. +The .NET Aspire SDK dynamically adds references to the [.NET Aspire dashboard](dashboard/overview.md) and other AppHost dependencies, such as the developer control plane (DCP) packages. These dependencies are specific to the platform that the AppHost is built on. -When the app host project runs, the orchestrator relies on these dependencies to provide the necessary functionality to the app host. For more information, see [.NET Aspire orchestration overview][app-host]. +When the AppHost project runs, the orchestrator relies on these dependencies to provide the necessary functionality to the AppHost. For more information, see [.NET Aspire orchestration overview][app-host]. [app-host]: xref:dotnet/aspire/app-host diff --git a/docs/fundamentals/external-parameters.md b/docs/fundamentals/external-parameters.md index 0c15eaa3c2..ba15e4e2d5 100644 --- a/docs/fundamentals/external-parameters.md +++ b/docs/fundamentals/external-parameters.md @@ -12,9 +12,9 @@ Environments provide context for the application to run in. Parameters express t ## Parameter values -Parameter values are read from the `Parameters` section of the app host's configuration and are used to provide values to the app while running locally. When you run or publish the app, if the value isn't configured you're prompted to provide it. +Parameter values are read from the `Parameters` section of the AppHost's configuration and are used to provide values to the app while running locally. When you run or publish the app, if the value isn't configured you're prompted to provide it. -Consider the following example app host _:::no-loc text="Program.cs":::_ file: +Consider the following example AppHost _:::no-loc text="Program.cs":::_ file: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -26,13 +26,13 @@ builder.AddProject("api") .WithEnvironment("ENVIRONMENT_VARIABLE_NAME", parameter); ``` -The preceding code adds a parameter named `example-parameter-name` to the app host. The parameter is then passed to the `Projects.ApiService` project as an environment variable named `ENVIRONMENT_VARIABLE_NAME`. +The preceding code adds a parameter named `example-parameter-name` to the AppHost. The parameter is then passed to the `Projects.ApiService` project as an environment variable named `ENVIRONMENT_VARIABLE_NAME`. ### Configure parameter values -Adding parameters to the builder is only one aspect of the configuration. You must also provide the value for the parameter. The value can be provided in the app host configuration file, set as a user secret, or configured in any [other standard configuration](/dotnet/core/extensions/configuration). When parameter values aren't found, they're prompted for when you run or publish the app. +Adding parameters to the builder is only one aspect of the configuration. You must also provide the value for the parameter. The value can be provided in the AppHost configuration file, set as a user secret, or configured in any [other standard configuration](/dotnet/core/extensions/configuration). When parameter values aren't found, they're prompted for when you run or publish the app. -Consider the following app host configuration file _:::no-loc text="appsettings.json":::_: +Consider the following AppHost configuration file _:::no-loc text="appsettings.json":::_: ```json { @@ -42,7 +42,7 @@ Consider the following app host configuration file _:::no-loc text="appsettings. } ``` -The preceding JSON configures a parameter in the `Parameters` section of the app host configuration. In other words, that app host is able to find the parameter as it's configured. For example, you could walk up to the and access the value using the `Parameters:example-parameter-name` key: +The preceding JSON configures a parameter in the `Parameters` section of the AppHost configuration. In other words, that AppHost is able to find the parameter as it's configured. For example, you could walk up to the and access the value using the `Parameters:example-parameter-name` key: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -52,7 +52,7 @@ var value = builder.Configuration[key]; // value = "local-value" ``` > [!IMPORTANT] -> However, you don't need to access this configuration value yourself in the app host. Instead, the is used to pass the parameter value to dependent resources. Most often as an environment variable. +> However, you don't need to access this configuration value yourself in the AppHost. Instead, the is used to pass the parameter value to dependent resources. Most often as an environment variable. ### Prompt for parameter values in the dashboard @@ -101,9 +101,9 @@ The code renders this control in the dashboard: ## Secret values -Parameters can be used to model secrets. When a parameter is marked as a secret, it serves as a hint to the manifest that the value should be treated as a secret. When you publish the app, the value is prompted for and stored in a secure location. When you run the app locally, the value is read from the `Parameters` section of the app host configuration. +Parameters can be used to model secrets. When a parameter is marked as a secret, it serves as a hint to the manifest that the value should be treated as a secret. When you publish the app, the value is prompted for and stored in a secure location. When you run the app locally, the value is read from the `Parameters` section of the AppHost configuration. -Consider the following example app host _:::no-loc text="Program.cs":::_ file: +Consider the following example AppHost _:::no-loc text="Program.cs":::_ file: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -117,7 +117,7 @@ builder.AddProject("api") builder.Build().Run(); ``` -Now consider the following app host configuration file _:::no-loc text="appsettings.json":::_: +Now consider the following AppHost configuration file _:::no-loc text="appsettings.json":::_: ```json { @@ -148,11 +148,11 @@ The manifest representation is as follows: ## Connection string values -Parameters can be used to model connection strings. When you publish the app, the value is prompted for and stored in a secure location. When you run the app locally, the value is read from the `ConnectionStrings` section of the app host configuration. +Parameters can be used to model connection strings. When you publish the app, the value is prompted for and stored in a secure location. When you run the app locally, the value is read from the `ConnectionStrings` section of the AppHost configuration. [!INCLUDE [connection-strings-alert](../includes/connection-strings-alert.md)] -Consider the following example app host _:::no-loc text="Program.cs":::_ file: +Consider the following example AppHost _:::no-loc text="Program.cs":::_ file: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -169,7 +169,7 @@ builder.Build().Run(); > [!NOTE] > Using with a connection string will implicitly wait for the resource that the connection string connects to. -Now consider the following app host configuration file _:::no-loc text="appsettings.json":::_: +Now consider the following AppHost configuration file _:::no-loc text="appsettings.json":::_: ```json { @@ -208,7 +208,7 @@ The following steps are performed: - Passes the `insertionRows` parameter to the `api` project. - References the `db` database. -The value for the `insertionRows` parameter is read from the `Parameters` section of the app host configuration file _:::no-loc text="appsettings.json":::_: +The value for the `insertionRows` parameter is read from the `Parameters` section of the AppHost configuration file _:::no-loc text="appsettings.json":::_: :::code language="json" source="snippets/params/Parameters.AppHost/appsettings.json"::: diff --git a/docs/fundamentals/http-commands.md b/docs/fundamentals/http-commands.md index 8bf150a934..d3dd1bb76b 100644 --- a/docs/fundamentals/http-commands.md +++ b/docs/fundamentals/http-commands.md @@ -1,7 +1,7 @@ --- title: Custom HTTP commands in .NET Aspire description: Learn how to create custom HTTP commands in .NET Aspire. -ms.date: 03/25/2025 +ms.date: 08/07/2025 ms.topic: how-to --- @@ -15,9 +15,7 @@ To implement custom HTTP commands, you define a command on a resource and a corr The available APIs provide extensive capabilities with numerous parameters to customize the HTTP command. To add an HTTP command to a resource, use the `WithHttpCommand` extension method on the resource builder. There are two overloads available: - - -The `WithHttpCommand` API provides two overloads to add custom HTTP commands to resources in .NET Aspire. These APIs are designed to offer flexibility and cater to different use cases when defining HTTP commands. +The API provides two overloads to add custom HTTP commands to resources in .NET Aspire. These APIs are designed to offer flexibility and cater to different use cases when defining HTTP commands. 1. **Overload with `endpointName`:** @@ -35,11 +33,11 @@ These APIs are designed to integrate seamlessly with the .NET Aspire ecosystem, Since HTTP commands are exposed via HTTP endpoints, consider potential security risks. Limit these endpoints to development or staging environments when possible. Always validate incoming requests to ensure they originate from trusted sources. For more information, see [ASP.NET Core security](/aspnet/core/security). -Use the `HttpCommandOptions.PrepareRequest` callback to enhance security by adding authentication headers or other measures. A common approach is to use a shared secret, [external parameter](external-parameters.md), or token known only to the app host and resource. This shared value can be used to validate requests and prevent unauthorized access. +Use the `HttpCommandOptions.PrepareRequest` callback to enhance security by adding authentication headers or other measures. A common approach is to use a shared secret, [external parameter](external-parameters.md), or token known only to the AppHost and resource. This shared value can be used to validate requests and prevent unauthorized access. ## Add a custom HTTP command -In your app host _Program.cs_ file, you add a custom HTTP command using the `WithHttpCommand` API on an where `T` is an . Here's an example of how to do this: +In your AppHost _Program.cs_ file, you add a custom HTTP command using the `WithHttpCommand` API on an where `T` is an . Here's an example of how to do this: :::code source="snippets/http-commands/AspireApp/AspireApp.AppHost/Program.cs"::: @@ -64,7 +62,7 @@ The HTTP endpoint is responsible for invalidating the cache. When the command is ### Example HTTP endpoint -The preceding app host code snippet defined a custom HTTP command that sends a request to the `/cache/invalidate` endpoint. The ASP.NET Core minimal API project defines an HTTP endpoint that handles the cache invalidation request. Consider the following code snippet from the project's _Program.cs_ file: +The preceding AppHost code snippet defined a custom HTTP command that sends a request to the `/cache/invalidate` endpoint. The ASP.NET Core minimal API project defines an HTTP endpoint that handles the cache invalidation request. Consider the following code snippet from the project's _Program.cs_ file: :::code source="snippets/http-commands/AspireApp/AspireApp.Api/Program.cs" id="post"::: @@ -80,7 +78,7 @@ The preceding code: ### Example dashboard experiences -The sample app host and corresponding ASP.NET Core minimal API projects demonstrate both sides of the HTTP command implementation. When you run the app host, the dashboard's **Resources** page displays the custom HTTP command as a button. When you specify that the command should be highlighted (`isHighlighted: true`), the button appears on the **Actions** column of the **Resources** page. This allows users to easily trigger the command from the dashboard, as shown in the following screenshot: +The sample AppHost and corresponding ASP.NET Core minimal API projects demonstrate both sides of the HTTP command implementation. When you run the AppHost, the dashboard's **Resources** page displays the custom HTTP command as a button. When you specify that the command should be highlighted (`isHighlighted: true`), the button appears on the **Actions** column of the **Resources** page. This allows users to easily trigger the command from the dashboard, as shown in the following screenshot: :::image type="content" source="media/custom-http-command-highlighted.png" lightbox="media/custom-http-command-highlighted.png" alt-text=".NET Aspire dashboard: Resources page showing a highlighted custom HTTP command."::: diff --git a/docs/fundamentals/includes/dotnet-new-list-aspire-output.md b/docs/fundamentals/includes/dotnet-new-list-aspire-output.md index f0474e5f9b..b09e57c31e 100644 --- a/docs/fundamentals/includes/dotnet-new-list-aspire-output.md +++ b/docs/fundamentals/includes/dotnet-new-list-aspire-output.md @@ -18,7 +18,7 @@ These templates matched your input: 'aspire' Template Name Short Name Language Tags --------------------------------- ---------------------- -------- ------------------------------------------------------- -.NET Aspire App Host aspire-apphost [C#] Common/.NET Aspire/Cloud +.NET Aspire AppHost aspire-apphost [C#] Common/.NET Aspire/Cloud .NET Aspire Empty App aspire [C#] Common/.NET Aspire/Cloud/Web/Web API/API/Service .NET Aspire Service Defaults aspire-servicedefaults [C#] Common/.NET Aspire/Cloud/Web/Web API/API/Service .NET Aspire Starter App aspire-starter [C#] Common/.NET Aspire/Blazor/Web/Web API/API/Service/Cloud diff --git a/docs/fundamentals/integrations-overview.md b/docs/fundamentals/integrations-overview.md index e2d6b255b8..20c4f4b091 100644 --- a/docs/fundamentals/integrations-overview.md +++ b/docs/fundamentals/integrations-overview.md @@ -15,13 +15,13 @@ uid: dotnet/aspire/integrations ## Integration responsibilities -Most .NET Aspire integrations are made up of two separate libraries, each with a different responsibility. One type represents resources within the [_app host_](app-host-overview.md) project—known as [hosting integrations](#hosting-integrations). The other type of integration represents client libraries that connect to the resources modeled by hosting integrations, and they're known as [client integrations](#client-integrations). +Most .NET Aspire integrations are made up of two separate libraries, each with a different responsibility. One type represents resources within the [_AppHost_](app-host-overview.md) project—known as [hosting integrations](#hosting-integrations). The other type of integration represents client libraries that connect to the resources modeled by hosting integrations, and they're known as [client integrations](#client-integrations). ### Hosting integrations Hosting integrations configure applications by provisioning resources (like containers or cloud resources) or pointing to existing instances (such as a local SQL server). These packages model various services, platforms, or capabilities, including caches, databases, logging, storage, and messaging systems. -Hosting integrations extend the interface, enabling the _app host_ project to express resources within its [_app model_](app-host-overview.md#terminology). **Hosting integrations work with any type of application**, not just .NET applications. They provide infrastructure and inject configuration details (such as connection strings, endpoints, and credentials) as environment variables into any project, executable, or container that references them. +Hosting integrations extend the interface, enabling the _AppHost_ project to express resources within its [_app model_](app-host-overview.md#terminology). **Hosting integrations work with any type of application**, not just .NET applications. They provide infrastructure and inject configuration details (such as connection strings, endpoints, and credentials) as environment variables into any project, executable, or container that references them. The official [hosting integration NuGet packages](https://www.nuget.org/packages?q=owner%3A+aspire+tags%3A+aspire+hosting+integration&includeComputedFrameworks=true&prerel=true&sortby=relevance) are tagged with `aspire`, `integration`, and `hosting`. In addition to the official hosting integrations, the [community has created hosting integrations](../community-toolkit/overview.md) for various services and platforms as part of the Community Toolkit. @@ -45,7 +45,7 @@ Consider the following diagram that depicts the relationship between hosting and :::image type="content" source="media/integrations-thumb.png" lightbox="media/integrations.png" alt-text="A diagram "::: -The app host project is where hosting integrations are used. Configuration, specifically environment variables, is injected into projects, executables, and containers, allowing client integrations to connect to the hosting integrations. +The AppHost project is where hosting integrations are used. Configuration, specifically environment variables, is injected into projects, executables, and containers, allowing client integrations to connect to the hosting integrations. ## Integration features @@ -68,7 +68,7 @@ When major breaking changes happen in dependent resources, integrations may temp ## Official integrations -.NET Aspire provides many integrations to help you build cloud-native applications. These integrations are designed to work seamlessly with the .NET Aspire app host and client libraries. The following sections detail cloud-agnostic, Azure-specific, Amazon Web Services (AWS), and Community Toolkit integrations. +.NET Aspire provides many integrations to help you build cloud-native applications. These integrations are designed to work seamlessly with the .NET Aspire AppHost and client libraries. The following sections detail cloud-agnostic, Azure-specific, Amazon Web Services (AWS), and Community Toolkit integrations. ### Cloud-agnostic integrations diff --git a/docs/fundamentals/launch-profiles.md b/docs/fundamentals/launch-profiles.md index f24510911c..79ddac03a2 100644 --- a/docs/fundamentals/launch-profiles.md +++ b/docs/fundamentals/launch-profiles.md @@ -6,7 +6,7 @@ ms.date: 04/15/2025 # .NET Aspire and launch profiles -.NET Aspire makes use of _launch profiles_ defined in both the app host and service projects to simplify the process of configuring multiple aspects of the debugging and publishing experience for .NET Aspire-based distributed applications. +.NET Aspire makes use of _launch profiles_ defined in both the AppHost and service projects to simplify the process of configuring multiple aspects of the debugging and publishing experience for .NET Aspire-based distributed applications. ## Launch profile basics @@ -54,7 +54,7 @@ In Visual Studio it's possible to select the launch profile when launching the a When a .NET application is launched with a launch profile a special environment variable called `DOTNET_LAUNCH_PROFILE` is populated with the name of the launch profile that was used when launching the process. -## Launch profiles for .NET Aspire app host +## Launch profiles for .NET Aspire AppHost In .NET Aspire, the AppHost is just a .NET application. As a result it has a `launchSettings.json` file just like any other application. Here is an example of the `launchSettings.json` file generated when creating a new .NET Aspire project from the starter template (`dotnet new aspire-starter`). @@ -92,19 +92,19 @@ In .NET Aspire, the AppHost is just a .NET application. As a result it has a `la The .NET Aspire templates have a very similar set of _launch profiles_ to a regular ASP.NET Core application. When the .NET Aspire app project launches, it starts a and hosts a web-server which is used by the .NET Aspire Dashboard to fetch information about resources which are being orchestrated by .NET Aspire. -For information about app host configuration options, see [.NET Aspire app host configuration](../app-host/configuration.md). +For information about AppHost configuration options, see [.NET Aspire AppHost configuration](../app-host/configuration.md). -## Relationship between app host launch profiles and service projects +## Relationship between AppHost launch profiles and service projects -In .NET Aspire the app host is responsible for coordinating the launch of multiple service projects. When you run the app host either via the command line or from Visual Studio (or other development environment) a launch profile is selected for the app host. In turn, the app host will attempt to find a matching launch profile in the service projects it is launching and use those options to control the environment and default networking configuration for the service project. +In .NET Aspire the AppHost is responsible for coordinating the launch of multiple service projects. When you run the AppHost either via the command line or from Visual Studio (or other development environment) a launch profile is selected for the AppHost. In turn, the AppHost will attempt to find a matching launch profile in the service projects it is launching and use those options to control the environment and default networking configuration for the service project. -When the app host launches a service project it doesn't simply launch the service project using the `--launch-profile` option. Therefore, there will be no `DOTNET_LAUNCH_PROFILE` environment variable set for service projects. This is because .NET Aspire modifies the `ASPNETCORE_URLS` environment variable (derived from the `applicationUrl` field in the launch profile) to use a different port. By default, .NET Aspire inserts a reverse proxy in front of the ASP.NET Core application to allow for multiple instances of the application using the method. +When the AppHost launches a service project it doesn't simply launch the service project using the `--launch-profile` option. Therefore, there will be no `DOTNET_LAUNCH_PROFILE` environment variable set for service projects. This is because .NET Aspire modifies the `ASPNETCORE_URLS` environment variable (derived from the `applicationUrl` field in the launch profile) to use a different port. By default, .NET Aspire inserts a reverse proxy in front of the ASP.NET Core application to allow for multiple instances of the application using the method. Other settings such as options from the `environmentVariables` field are passed through to the application without modification. ## Control launch profile selection -Ideally, it's possible to align the launch profile names between the app host and the service projects to make it easy to switch between configuration options on all projects coordinated by the app host at once. However, it may be desirable to control launch profile that a specific project uses. The extension method provides a mechanism to do this. +Ideally, it's possible to align the launch profile names between the AppHost and the service projects to make it easy to switch between configuration options on all projects coordinated by the AppHost at once. However, it may be desirable to control launch profile that a specific project uses. The extension method provides a mechanism to do this. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -124,7 +124,7 @@ To force a service project to launch without a launch profile the `launchProfile ## Launch profiles and endpoints -When adding an ASP.NET Core project to the app host, .NET Aspire will parse the _launchSettings.json_ file selecting the appropriate launch profile and automatically generate endpoints in the application model based on the URL(s) present in the `applicationUrl` field. To modify the endpoints that are automatically injected the extension method. +When adding an ASP.NET Core project to the AppHost, .NET Aspire will parse the _launchSettings.json_ file selecting the appropriate launch profile and automatically generate endpoints in the application model based on the URL(s) present in the `applicationUrl` field. To modify the endpoints that are automatically injected the extension method. ```csharp var builder = DistributedApplication.CreateBuilder(args); diff --git a/docs/fundamentals/networking-overview.md b/docs/fundamentals/networking-overview.md index b83cd8e138..50b5663b23 100644 --- a/docs/fundamentals/networking-overview.md +++ b/docs/fundamentals/networking-overview.md @@ -36,8 +36,8 @@ When you add one or more container resources, .NET Aspire creates a dedicated co The network's lifetime depends on the container resources: -- If all containers have a session lifetime, the network is also session-based and is cleaned up when the app host process ends. -- If any container has a persistent lifetime, the network is persistent and remains running after the app host process terminates. Aspire reuses this network on subsequent runs, allowing persistent containers to keep communicating even when the app host isn't running. +- If all containers have a session lifetime, the network is also session-based and is cleaned up when the AppHost process ends. +- If any container has a persistent lifetime, the network is persistent and remains running after the AppHost process terminates. Aspire reuses this network on subsequent runs, allowing persistent containers to keep communicating even when the AppHost isn't running. For more information on container lifetimes, see [Container resource lifetime](orchestrate-resources.md#container-resource-lifetime). @@ -46,7 +46,7 @@ Here are the naming conventions for container networks: - **Session networks**: `aspire-session-network--` - **Persistent networks**: `aspire-persistent-network--` -Each app host instance gets its own network resources. The only differences are the network's lifetime and name; service discovery works the same way for both. +Each AppHost instance gets its own network resources. The only differences are the network's lifetime and name; service discovery works the same way for both. Containers register themselves on the network using their resource name. Aspire uses this name for service discovery between containers. For example, a `pgadmin` container can connect to a database resource named `postgres` using `postgres:5432`. @@ -55,7 +55,7 @@ Containers register themselves on the network using their resource name. Aspire ## Launch profiles -When you call , the app host looks for _Properties/launchSettings.json_ to determine the default set of endpoints. The app host selects a specific launch profile using the following rules: +When you call , the AppHost looks for _Properties/launchSettings.json_ to determine the default set of endpoints. The AppHost selects a specific launch profile using the following rules: 1. An explicit `launchProfileName` argument passed when calling `AddProject`. 1. The `DOTNET_LAUNCH_PROFILE` environment variable. For more information, see [.NET environment variables](/dotnet/core/tools/dotnet-environment-variables). @@ -91,7 +91,7 @@ The preceding configuration specifies an `Https` endpoint. The `Url` property is With the Kestrel endpoint configured, the project should remove any configured `applicationUrl` from the _launchSettings.json_ file. > [!NOTE] -> If the `applicationUrl` is present in the _launchSettings.json_ file and the Kestrel endpoint is configured, the app host will throw an exception. +> If the `applicationUrl` is present in the _launchSettings.json_ file and the Kestrel endpoint is configured, the AppHost will throw an exception. When you add a project resource, there's an overload that lets you specify that the Kestrel endpoint should be used instead of the _launchSettings.json_ file: diff --git a/docs/fundamentals/orchestrate-resources.md b/docs/fundamentals/orchestrate-resources.md index 5ddf7fc187..40be341891 100644 --- a/docs/fundamentals/orchestrate-resources.md +++ b/docs/fundamentals/orchestrate-resources.md @@ -1,13 +1,13 @@ --- title: Orchestrate resources in Aspire description: Learn techniques to control the behavior of Aspire resources such as project, containers, and executable resources. -ms.date: 07/25/2025 +ms.date: 08/07/2025 uid: dotnet/aspire/orchestrate-resources --- # Orchestrate resources in .NET Aspire -In this article, you learn how to customize the behavior of resources further by writing code in the app host project. In Aspire, a **resource** is a dependent part of a cloud-native application. Resource types include: +In this article, you learn how to customize the behavior of resources further by writing code in the AppHost project. In Aspire, a **resource** is a dependent part of a cloud-native application. Resource types include: - **.NET Project**: A custom microservice, responsible for specific functionality in your cloud-native application, and often built by a separate team of developers. - **Executable**: If you need to build microservices with tools like Node.js or Orleans, they run as executable resources. @@ -90,7 +90,7 @@ Waiting for a resource can be bypassed using the **Start** command in the dashbo ## APIs for adding and expressing resources -Aspire [hosting integrations](integrations-overview.md#hosting-integrations) and [client integrations](integrations-overview.md#client-integrations) are both delivered as NuGet packages, but they serve different purposes. While _client integrations_ provide client library configuration for consuming apps outside the scope of the app host, _hosting integrations_ provide APIs for expressing resources and dependencies within the app host. For more information, see [Aspire integrations overview: Integration responsibilities](integrations-overview.md#integration-responsibilities). +Aspire [hosting integrations](integrations-overview.md#hosting-integrations) and [client integrations](integrations-overview.md#client-integrations) are both delivered as NuGet packages, but they serve different purposes. While _client integrations_ provide client library configuration for consuming apps outside the scope of the AppHost, _hosting integrations_ provide APIs for expressing resources and dependencies within the AppHost. For more information, see [Aspire integrations overview: Integration responsibilities](integrations-overview.md#integration-responsibilities). ## Express container resources @@ -150,7 +150,7 @@ For more information and additional APIs available, see is used to determine what container image to create and start. Under the hood, Aspire runs the container using the defined container image by delegating calls to the appropriate OCI-compliant container runtime, either Docker or Podman. The following commands are used: +When the AppHost is run, the is used to determine what container image to create and start. Under the hood, Aspire runs the container using the defined container image by delegating calls to the appropriate OCI-compliant container runtime, either Docker or Podman. The following commands are used: #### [Docker](#tab/docker) @@ -176,7 +176,7 @@ Beyond the base resource types, API and pass : +By default, container resources use the _session_ container lifetime. This means that every time the AppHost process is started, the container is created and started. When the AppHost stops, the container is stopped and removed. Container resources can opt-in to a _persistent_ lifetime to avoid unnecessary restarts and use persisted container state. To achieve this, chain a call the API and pass : ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -189,9 +189,7 @@ The preceding code adds a container resource named "ollama" with the image "olla ## Express external service resources - - -External services are third-party APIs and services that your application depends on but that exist outside your Aspire solution. These services are already running elsewhere and aren't managed by Aspire. To express an `ExternalServiceResource` you add it to an instance by calling the `AddExternalService` method: +External services are third-party APIs and services that your application depends on but that exist outside your Aspire solution. These services are already running elsewhere and aren't managed by Aspire. To express an you add it to an instance by calling the method: ```csharp var builder = DistributedApplication.CreateBuilder(args); diff --git a/docs/fundamentals/persist-data-volumes.md b/docs/fundamentals/persist-data-volumes.md index 756051c18b..d3e3699fac 100644 --- a/docs/fundamentals/persist-data-volumes.md +++ b/docs/fundamentals/persist-data-volumes.md @@ -42,7 +42,7 @@ Volumes are the recommended way to persist data generated by containers and they - **`target`**: The target path in the container of the data you want to persist. - **`isReadOnly`**: A Boolean flag that indicates whether the data in the volume can be changed. The default value is `false`. -For the remainder of this article, imagine that you're exploring a `Program` class in a .NET Aspire [app host project](app-host-overview.md) that's already defined the distributed app builder bits: +For the remainder of this article, imagine that you're exploring a `Program` class in a .NET Aspire [AppHost project](app-host-overview.md) that's already defined the distributed app builder bits: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -54,7 +54,7 @@ var builder = DistributedApplication.CreateBuilder(args); builder.Build().Run(); ``` -The first code snippet to consider uses the API to configure a volume for a SQL Server resource. The following code demonstrates how to configure a volume for a SQL Server resource in a .NET Aspire app host project: +The first code snippet to consider uses the API to configure a volume for a SQL Server resource. The following code demonstrates how to configure a volume for a SQL Server resource in a .NET Aspire AppHost project: :::code language="csharp" source="snippets/volumes/VolumeMounts.AppHost/Program.WithVolume.cs" id="volume"::: @@ -64,9 +64,9 @@ All .NET Aspire container resources can utilize volumes, and some provide conven :::code language="csharp" source="snippets/volumes/VolumeMounts.AppHost/Program.ImplicitVolume.cs" id="implicitvolume"::: -With the app host project being named `VolumeMount.AppHost`, the `WithDataVolume` method automatically creates a named volume as `VolumeMount.AppHost-sql-data` and is mounted to the `/var/opt/mssql` path in the SQL Server container. The naming convention is as follows: +With the AppHost project being named `VolumeMount.AppHost`, the `WithDataVolume` method automatically creates a named volume as `VolumeMount.AppHost-sql-data` and is mounted to the `/var/opt/mssql` path in the SQL Server container. The naming convention is as follows: -- `{appHostProjectName}-{resourceName}-data`: The volume name is derived from the app host project name and the resource name. +- `{appHostProjectName}-{resourceName}-data`: The volume name is derived from the AppHost project name and the resource name. ## Use bind mounts @@ -98,9 +98,9 @@ Named volumes require a consistent password between app launches. .NET Aspire co Since the `password` parameter isn't provided when calling `AddSqlServer`, .NET Aspire automatically generates a password for the SQL Server resource. > [!IMPORTANT] -> This isn't a persistent password! Instead, it changes every time the app host runs. +> This isn't a persistent password! Instead, it changes every time the AppHost runs. -To create a _persistent_ password, you must override the generated password. To do this, run the following command in your app host project directory to set a local password in your .NET user secrets: +To create a _persistent_ password, you must override the generated password. To do this, run the following command in your AppHost project directory to set a local password in your .NET user secrets: ```dotnetcli dotnet user-secrets set Parameters:sql-password diff --git a/docs/fundamentals/setup-tooling.md b/docs/fundamentals/setup-tooling.md index 822dd882ed..d919b117b9 100644 --- a/docs/fundamentals/setup-tooling.md +++ b/docs/fundamentals/setup-tooling.md @@ -170,7 +170,7 @@ Both commands should succeed and return valid results before running your .NET A ## .NET Aspire dashboard -.NET Aspire templates that expose the [app host](app-host-overview.md) project also include a useful developer [dashboard](dashboard/overview.md) that's used to monitor and inspect various aspects of your app, such as logs, traces, and environment configurations. This dashboard is designed to improve the local development experience and provides an overview of the overall state and structure of your app. +.NET Aspire templates that expose the [AppHost](app-host-overview.md) project also include a useful developer [dashboard](dashboard/overview.md) that's used to monitor and inspect various aspects of your app, such as logs, traces, and environment configurations. This dashboard is designed to improve the local development experience and provides an overview of the overall state and structure of your app. The .NET Aspire dashboard is only visible while the app is running and starts automatically when you start the _*.AppHost_ project. Visual Studio and Visual Studio Code launch both your app and the .NET Aspire dashboard for you automatically in your browser. If you start the app using the .NET CLI, copy and paste the dashboard URL from the output into your browser, or hold Ctrl and select the link (if your terminal supports hyperlinks). @@ -186,7 +186,7 @@ The .NET Aspire dashboard is also available in a standalone mode. For more infor ## Visual Studio tooling -Visual Studio provides extra features for working with .NET Aspire integrations and the App Host orchestrator project. Not all of these features are currently available in Visual Studio Code or through the CLI. +Visual Studio provides extra features for working with .NET Aspire integrations and the AppHost orchestrator project. Not all of these features are currently available in Visual Studio Code or through the CLI. ### Add an integration package diff --git a/docs/fundamentals/snippets/annotations-overview/Program.cs b/docs/fundamentals/snippets/annotations-overview/Program.cs index 683d10bfe4..bda768c5f5 100644 --- a/docs/fundamentals/snippets/annotations-overview/Program.cs +++ b/docs/fundamentals/snippets/annotations-overview/Program.cs @@ -108,7 +108,7 @@ public class Program public static void Main(string[] args) { // This is a minimal example showing annotation usage - // In a real app host, you would use actual resources + // In a real AppHost, you would use actual resources Console.WriteLine("Annotations overview examples"); } } diff --git a/docs/get-started/add-aspire-existing-app.md b/docs/get-started/add-aspire-existing-app.md index a17c30a548..42091fbb55 100644 --- a/docs/get-started/add-aspire-existing-app.md +++ b/docs/get-started/add-aspire-existing-app.md @@ -204,7 +204,7 @@ Template Name Short Name Language Tags .NET Aspire Tes... aspire-xunit [C#] Common/.NET Aspire/Cloud/Web/Web API/API/Service/Test/xUnit ``` -In this tutorial, you'll add a App Host project and a Service Defaults project. +In this tutorial, you'll add a AppHost project and a Service Defaults project. If the previous command didn't find any templates you must install them. Execute this command: @@ -256,15 +256,15 @@ Also notice that the **eShopLite.AppHost** project, now depends on both the **St :::zone-end :::zone pivot="vscode,dotnet-cli" -### Create an app host project +### Create an AppHost project -In order to orchestrate the existing projects, you need to create a new _app host_ project. To create a new [_app host_ project](../fundamentals/app-host-overview.md) from the available .NET Aspire templates, use the following .NET CLI command: +In order to orchestrate the existing projects, you need to create a new _AppHost_ project. To create a new [_AppHost_ project](../fundamentals/app-host-overview.md) from the available .NET Aspire templates, use the following .NET CLI command: ```dotnetcli dotnet new aspire-apphost -o eShopLite.AppHost ``` -Add the _app host_ project to existing solution: +Add the _AppHost_ project to existing solution: ## [Unix](#tab/unix) @@ -280,7 +280,7 @@ dotnet sln .\eShopLite.sln add .\eShopLite.AppHost\eShopLite.AppHost.csproj --- -Add the **Store** project as a project reference to the _app host_ project using the following .NET CLI command: +Add the **Store** project as a project reference to the _AppHost_ project using the following .NET CLI command: ## [Unix](#tab/unix) @@ -300,7 +300,7 @@ For more information on the available templates, see [.NET Aspire templates](../ ### Create a service defaults project -After the app host project is created, you need to create a new _service defaults_ project. To create a new [_service defaults_ project](../fundamentals/service-defaults.md) from the available .NET Aspire templates, use the following .NET CLI command: +After the AppHost project is created, you need to create a new _service defaults_ project. To create a new [_service defaults_ project](../fundamentals/service-defaults.md) from the available .NET Aspire templates, use the following .NET CLI command: ```dotnetcli dotnet new aspire-servicedefaults -o eShopLite.ServiceDefaults @@ -322,7 +322,7 @@ dotnet sln .\eShopLite.sln add .\eShopLite.ServiceDefaults\eShopLite.ServiceDefa --- -Update the _app host_ project to add a project reference to the **Products** project: +Update the _AppHost_ project to add a project reference to the **Products** project: ## [Unix](#tab/unix) @@ -376,9 +376,9 @@ In both the **Store** and **Products** projects, update their _:::no-loc text="P builder.AddServiceDefaults(); ``` -### Update the app host project +### Update the AppHost project -Open the _:::no-loc text="Program.cs":::_ file of the _app host_ project, and replace its contents with the following C# code: +Open the _:::no-loc text="Program.cs":::_ file of the _AppHost_ project, and replace its contents with the following C# code: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -416,7 +416,7 @@ builder.AddProject("store") builder.Build().Run(); ``` -The preceding code expresses that the _Store_ project depends on the _Products_ project. For more information, see [.NET Aspire app host: Reference resources](../fundamentals/app-host-overview.md#reference-resources). This reference is used to discover the address of the _Products_ project at run time. Additionally, the _Store_ project is configured to use external HTTP endpoints. If you later choose to deploy this app, you'd need the call to to ensure that it's public to the outside world. Finally, the API ensures that _Store_ app waits for the _Products_ app to be ready to serve requests. +The preceding code expresses that the _Store_ project depends on the _Products_ project. For more information, see [.NET Aspire AppHost: Reference resources](../fundamentals/app-host-overview.md#reference-resources). This reference is used to discover the address of the _Products_ project at run time. Additionally, the _Store_ project is configured to use external HTTP endpoints. If you later choose to deploy this app, you'd need the call to to ensure that it's public to the outside world. Finally, the API ensures that _Store_ app waits for the _Products_ app to be ready to serve requests. Next, update the _:::no-loc text="appsettings.json":::_ in the _Store_ project with the following JSON: @@ -435,7 +435,7 @@ Next, update the _:::no-loc text="appsettings.json":::_ in the _Store_ project w } ``` -The addresses for both the endpoints now uses the "products" name that was added to the orchestrator in the _app host_. These names are used to discover the address of the _Products_ project. +The addresses for both the endpoints now uses the "products" name that was added to the orchestrator in the _AppHost_. These names are used to discover the address of the _Products_ project. ## Explore the enrolled app @@ -456,9 +456,9 @@ Let's start the solution and examine the new behavior that .NET Aspire provides. :::zone-end :::zone pivot="vscode" -Delete the _launch.json_ file that you created earlier, it no longer serves a purpose. Instead, start the _app host_ project, which orchestrates the other projects: +Delete the _launch.json_ file that you created earlier, it no longer serves a purpose. Instead, start the _AppHost_ project, which orchestrates the other projects: -1. Start the _app host_ project by right-clicking the **eShopLite.AppHost** project in the **Solution Explorer** and selecting **Debug** > **Start New Instance**: +1. Start the _AppHost_ project by right-clicking the **eShopLite.AppHost** project in the **Solution Explorer** and selecting **Debug** > **Start New Instance**: :::image type="content" source="media/vscode-run-app-host.png" lightbox="media/vscode-run-app-host.png" alt-text="Visual Studio Code: Solution Explorer selecting Debug > Start New Instance." ::: @@ -468,7 +468,7 @@ Delete the _launch.json_ file that you created earlier, it no longer serves a pu :::zone-end :::zone pivot="dotnet-cli" -1. Start the _app host_ project by running the following command: +1. Start the _AppHost_ project by running the following command: ```dotnetcli dotnet run --project ./eShopLite.AppHost/eShopLite.AppHost.csproj diff --git a/docs/get-started/aspire-overview.md b/docs/get-started/aspire-overview.md index 7a353159d9..940039d3ed 100644 --- a/docs/get-started/aspire-overview.md +++ b/docs/get-started/aspire-overview.md @@ -15,7 +15,7 @@ Extensibility is a core focus. Aspire's APIs are designed so you can adapt the p ### Key capabilities -- **App host orchestration:** Define services, dependencies, and configuration in code. +- **AppHost orchestration:** Define services, dependencies, and configuration in code. - **Rich integrations:** NuGet packages for popular services with standardized interfaces. - **Consistent tooling:** Project templates and experiences for **Visual Studio, VS Code, and the CLI.** @@ -23,9 +23,9 @@ For the official support information, see the [Aspire Support Policy](https://do ## The AppHost -Aspire's app host is where you define your app's services and dependencies in code—no complex configuration files required. The app host provides orchestration for your local development environment by simplifying the management of service discovery, environment variables, and container configurations. +Aspire's AppHost is where you define your app's services and dependencies in code—no complex configuration files required. The AppHost provides orchestration for your local development environment by simplifying the management of service discovery, environment variables, and container configurations. -Picture a common three-tier architecture: a frontend, which depends on an API, which connects to a database. In Aspire, this topology is represented in the app host as shown in the following code: +Picture a common three-tier architecture: a frontend, which depends on an API, which connects to a database. In Aspire, this topology is represented in the AppHost as shown in the following code: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -47,7 +47,7 @@ var frontend = builder.AddProject("frontend") builder.Build().Run(); ``` -The app host assists with the following concerns: +The AppHost assists with the following concerns: - **App composition**: Specify the projects, containers, executables, and cloud resources that make up your application. - **Service discovery and connection string management**: Automatically inject the right connection strings and network configurations. @@ -75,7 +75,7 @@ Resources you can integrate include: Integrations are two-fold: "hosting" integrations represent the service you're connecting to, while "client" integrations represent the consumer of that service. > [!TIP] -> Under the hood, a _hosting_ [integration](../fundamentals/integrations-overview.md) can represent a container, an executable, or even just C# code that configures resources without running a separate process. You can add any container image, codebase, script, or cloud resource to your app host. Creating reusable Aspire integrations is similar to building reusable components for your apps. +> Under the hood, a _hosting_ [integration](../fundamentals/integrations-overview.md) can represent a container, an executable, or even just C# code that configures resources without running a separate process. You can add any container image, codebase, script, or cloud resource to your AppHost. Creating reusable Aspire integrations is similar to building reusable components for your apps. ## Monitor and troubleshoot with the Aspire dashboard @@ -94,7 +94,7 @@ Learn more in the [dashboard overview](../fundamentals/dashboard/overview.md), o ## From development to deployment -When you compose your distributed app in Aspire's app host, you're not just defining services for local development—you're setting up the foundation for deployment. The same composition you use to run and debug locally becomes the blueprint for production deployment, ensuring consistency from development through to production. +When you compose your distributed app in Aspire's AppHost, you're not just defining services for local development—you're setting up the foundation for deployment. The same composition you use to run and debug locally becomes the blueprint for production deployment, ensuring consistency from development through to production. Aspire provides project templates and tooling experiences for your favorite development environments. These [templates include opinionated defaults](../fundamentals/aspire-sdk-templates.md) with boilerplate code for health checks, logging, and telemetry. The templates also include service defaults that handle common configurations: @@ -121,7 +121,7 @@ Consider how the three-tier architecture example can be deployed across differen > [!TIP] > These are just a few examples of how you can deploy Aspire apps. -Aspire's deployment capabilities are flexible and don't interfere with your existing workflows. You can continue using your preferred tools and services while benefiting from the consistent app topology defined in your app host. +Aspire's deployment capabilities are flexible and don't interfere with your existing workflows. You can continue using your preferred tools and services while benefiting from the consistent app topology defined in your AppHost. For more information, see [Deploy Aspire apps](../deployment/overview.md). diff --git a/docs/get-started/build-aspire-apps-with-nodejs.md b/docs/get-started/build-aspire-apps-with-nodejs.md index e2eccc0c23..d3ba75b141 100644 --- a/docs/get-started/build-aspire-apps-with-nodejs.md +++ b/docs/get-started/build-aspire-apps-with-nodejs.md @@ -1,6 +1,6 @@ --- title: Orchestrate Node.js apps in .NET Aspire -description: Learn how to integrate Node.js and npm apps into a .NET Aspire App Host project. +description: Learn how to integrate Node.js and npm apps into a .NET Aspire AppHost project. ms.date: 05/27/2025 ms.custom: sfi-image-nochange --- @@ -98,7 +98,7 @@ For more information on the Vue app, see [explore the Vue client](#explore-the-v ## Run the sample app -To run the sample app, call the [dotnet run](/dotnet/core/tools/dotnet-run) command given the orchestrator app host _AspireJavaScript.AppHost.csproj_ as the `--project` switch: +To run the sample app, call the [dotnet run](/dotnet/core/tools/dotnet-run) command given the orchestrator AppHost _AspireJavaScript.AppHost.csproj_ as the `--project` switch: ```dotnetcli dotnet run --project ./AspireJavaScript.AppHost/AspireJavaScript.AppHost.csproj @@ -112,20 +112,20 @@ The `weatherapi` service endpoint resolves to a Swagger UI page that documents t In the same terminal session that you used to run the app, press Ctrl + C to stop the app. -## Explore the app host +## Explore the AppHost -To help understand how each client app resource is orchestrated, look to the app host project. The app host requires the [Aspire.Hosting.NodeJS](https://nuget.org/packages/Aspire.Hosting.NodeJS) NuGet package to host Node.js apps: +To help understand how each client app resource is orchestrated, look to the AppHost project. The AppHost requires the [Aspire.Hosting.NodeJS](https://nuget.org/packages/Aspire.Hosting.NodeJS) NuGet package to host Node.js apps: :::code language="xml" highlight="15,22-30" source="~/aspire-samples/samples/AspireWithJavaScript/AspireJavaScript.AppHost/AspireJavaScript.AppHost.csproj"::: -The project file also defines a build target that ensures that the npm dependencies are installed before the app host is built. The app host code (_Program.cs_) declares the client app resources using the API. +The project file also defines a build target that ensures that the npm dependencies are installed before the AppHost is built. The AppHost code (_Program.cs_) declares the client app resources using the API. :::code source="~/aspire-samples/samples/AspireWithJavaScript/AspireJavaScript.AppHost/AppHost.cs"::: The preceding code: - Creates a . -- Adds the "weatherapi" service as a project to the app host. +- Adds the "weatherapi" service as a project to the AppHost. - Marks the HTTP endpoints as external. - With a reference to the "weatherapi" service, adds the "angular", "react", and "vue" client apps as npm apps. - Each client app is configured to run on a different container port, and uses the `PORT` environment variable to determine the port. @@ -133,7 +133,7 @@ The preceding code: For more information on inner-loop networking, see [.NET Aspire inner-loop networking overview](../fundamentals/networking-overview.md). For more information on deploying apps, see [.NET Aspire manifest format for deployment tool builders](../deployment/manifest-format.md). -When the app host orchestrates the launch of each client app, it uses the `npm run start` command. This command is defined in the `scripts` section of the _package.json_ file for each client app. The `start` script is used to start the client app on the specified port. Each client app relies on a proxy to request the "weatherapi" service. +When the AppHost orchestrates the launch of each client app, it uses the `npm run start` command. This command is defined in the `scripts` section of the _package.json_ file for each client app. The `start` script is used to start the client app on the specified port. Each client app relies on a proxy to request the "weatherapi" service. The proxy is configured in: @@ -147,7 +147,7 @@ There are several key modifications from the original Angular template. The firs :::code language="javascript" source="~/aspire-samples/samples/AspireWithJavaScript/AspireJavaScript.Angular/proxy.conf.js"::: -The .NET Aspire app host sets the `services__weatherapi__http__0` environment variable, which is used to resolve the "weatherapi" service endpoint. The preceding configuration proxies HTTP requests that start with `/api` to the target URL specified in the environment variable. +The .NET Aspire AppHost sets the `services__weatherapi__http__0` environment variable, which is used to resolve the "weatherapi" service endpoint. The preceding configuration proxies HTTP requests that start with `/api` to the target URL specified in the environment variable. Then include the proxy file to in the _angular.json_ file. Update the `serve` target to include the `proxyConfig` option, referencing to the created _proxy.conf.js_ file. @@ -217,7 +217,7 @@ As the `TheWelcome` integration is `mounted`, it calls the `/api/weatherforecast :::code language="typescript" source="~/aspire-samples/samples/AspireWithJavaScript/AspireJavaScript.Vue/vite.config.ts"::: -Additionally, the Vite config specifies the `server.proxy` property to forward requests to the "weatherapi" service. This is achieved by using the `services__weatherapi__http__0` environment variable, which is set by the .NET Aspire app host. +Additionally, the Vite config specifies the `server.proxy` property to forward requests to the "weatherapi" service. This is achieved by using the `services__weatherapi__http__0` environment variable, which is set by the .NET Aspire AppHost. The final update from the template is made to the _TheWelcome.vue_ file. This file calls the `/api/WeatherForecast` endpoint to retrieve the weather forecast data, and displays the data in a table. It includes [CSS, HTML, and TypeScript updates](https://github.com/dotnet/aspire-samples/blob/ef6868b0999c6eea3d42a10f2b20433c5ea93720/samples/AspireWithJavaScript/AspireJavaScript.Vue/src/components/TheWelcome.vue). @@ -239,7 +239,7 @@ The client apps are currently configured to run as true SPA apps, and aren't con ## Node.js server app considerations -While this article focuses on client apps, you might have scenarios where you need to host a Node.js server app. The same semantics are required to host a Node.js server app as a SPA client app. The .NET Aspire app host requires a package reference to the [Aspire.Hosting.NodeJS](https://nuget.org/packages/Aspire.Hosting.NodeJS) NuGet package and the code needs to call either `AddNodeApp` or `AddNpmApp`. These APIs are useful for adding existing JavaScript apps to the .NET Aspire app host. +While this article focuses on client apps, you might have scenarios where you need to host a Node.js server app. The same semantics are required to host a Node.js server app as a SPA client app. The .NET Aspire AppHost requires a package reference to the [Aspire.Hosting.NodeJS](https://nuget.org/packages/Aspire.Hosting.NodeJS) NuGet package and the code needs to call either `AddNodeApp` or `AddNpmApp`. These APIs are useful for adding existing JavaScript apps to the .NET Aspire AppHost. When configuring secrets and passing environment variables to JavaScript-based apps, whether they are client or server apps, use parameters. For more information, see [.NET Aspire: External parameters—secrets](../fundamentals/external-parameters.md#secret-values). diff --git a/docs/get-started/build-aspire-apps-with-python.md b/docs/get-started/build-aspire-apps-with-python.md index 258d245c91..926cd82e69 100644 --- a/docs/get-started/build-aspire-apps-with-python.md +++ b/docs/get-started/build-aspire-apps-with-python.md @@ -1,13 +1,13 @@ --- title: Orchestrate Python apps in .NET Aspire -description: Learn how to integrate Python apps into a .NET Aspire app host project. +description: Learn how to integrate Python apps into a .NET Aspire AppHost project. ms.date: 04/15/2025 ms.custom: sfi-image-nochange --- # Orchestrate Python apps in .NET Aspire -In this article, you learn how to use Python apps in a .NET Aspire app host. The sample app in this article demonstrates launching a Python application. The Python extension for .NET Aspire requires the use of virtual environments. +In this article, you learn how to use Python apps in a .NET Aspire AppHost. The sample app in this article demonstrates launching a Python application. The Python extension for .NET Aspire requires the use of virtual environments. [!INCLUDE [aspire-prereqs](../includes/aspire-prereqs.md)] @@ -37,13 +37,13 @@ In the same terminal session, change directories into the newly created project: cd PythonSample ``` -After the template is created, launch the app host with the following command to ensure that the app host and the [.NET Aspire dashboard](../fundamentals/dashboard/overview.md) run successfully: +After the template is created, launch the AppHost with the following command to ensure that the AppHost and the [.NET Aspire dashboard](../fundamentals/dashboard/overview.md) run successfully: ```dotnetcli dotnet run --project ./PythonSample.AppHost/PythonSample.AppHost.csproj ``` -If the .NET Aspire Dashboard doesn't open, open it with the link in the console output. At this point the dashboard won't show any resources. Stop the app host by pressing Ctrl + C in the terminal. +If the .NET Aspire Dashboard doesn't open, open it with the link in the console output. At this point the dashboard won't show any resources. Stop the AppHost by pressing Ctrl + C in the terminal. ## Prepare a Python app @@ -124,7 +124,7 @@ if __name__ == '__main__': The preceding code creates a simple Flask app that listens on port 8111 and returns the message `"Hello, World!"` when the root endpoint is accessed. -## Update the app host project +## Update the AppHost project Install the Python hosting package by running the following command: @@ -136,7 +136,7 @@ After the package is installed, the project XML should have a new package refere :::code language="xml" source="snippets/PythonSample/PythonSample.AppHost/PythonSample.AppHost.csproj" highlight="15"::: -Replace the app host _Program.cs_ code with the following snippet. This code adds the Python project to .NET Aspire by calling the `AddPythonApp` API and specifying the project name, project path, and the entry point file: +Replace the AppHost _Program.cs_ code with the following snippet. This code adds the Python project to .NET Aspire by calling the `AddPythonApp` API and specifying the project name, project path, and the entry point file: :::code source="snippets/PythonSample/PythonSample.AppHost/Program.cs" highlight="6"::: @@ -145,7 +145,7 @@ Replace the app host _Program.cs_ code with the following snippet. This code add ## Run the app -Now that you've added the Python hosting package, updated the app host _Program.cs_ file, and created a Python project, you can run the app host: +Now that you've added the Python hosting package, updated the AppHost _Program.cs_ file, and created a Python project, you can run the AppHost: ```dotnetcli dotnet run --project ../PythonSample.AppHost/PythonSample.AppHost.csproj @@ -159,7 +159,7 @@ Select the **Endpoints** link to open the `hello-python` endpoint in a new brows :::image source="media/python-hello-world.png" lightbox="media/python-hello-world.png" alt-text=".NET Aspire dashboard: Python sample app endpoint."::: -Stop the app host by pressing Ctrl + C in the terminal. +Stop the AppHost by pressing Ctrl + C in the terminal. ## Add telemetry support @@ -177,20 +177,20 @@ The preceding command installs the **OpenTelemetry** package and the **OTLP** ex :::code language="python" source="snippets/PythonSample/hello-python/main.py"::: -Update the app host project's _launchSettings.json_ file to include the `ASPIRE_ALLOW_UNSECURED_TRANSPORT` environment variable under the `http` profile: +Update the AppHost project's _launchSettings.json_ file to include the `ASPIRE_ALLOW_UNSECURED_TRANSPORT` environment variable under the `http` profile: :::code language="json" source="snippets/PythonSample/PythonSample.AppHost/Properties/launchSettings.json" highlight="26"::: -The `ASPIRE_ALLOW_UNSECURED_TRANSPORT` variable is required because when running locally the OpenTelemetry client in Python rejects the local development certificate. Launch the _app host_ again: +The `ASPIRE_ALLOW_UNSECURED_TRANSPORT` variable is required because when running locally the OpenTelemetry client in Python rejects the local development certificate. Launch the _AppHost_ again: ```dotnetcli dotnet run --project ../PythonSample.AppHost/PythonSample.AppHost.csproj --launch-profile http ``` > [!IMPORTANT] -> The .NET Aspire app host must be run using HTTP instead of HTTPS. The **OpenTelemetry** library requires HTTP when running in a local dev environment. +> The .NET Aspire AppHost must be run using HTTP instead of HTTPS. The **OpenTelemetry** library requires HTTP when running in a local dev environment. -Once the app host is running, navigate to the dashboard and select the **Structured** logging tab. Notice that it now contains logging events. +Once the AppHost is running, navigate to the dashboard and select the **Structured** logging tab. Notice that it now contains logging events. :::image source="media/python-telemetry-in-dashboard.png" lightbox="media/python-telemetry-in-dashboard.png" alt-text=".NET Aspire dashboard: Structured logging from Python process."::: diff --git a/docs/get-started/build-your-first-aspire-app.md b/docs/get-started/build-your-first-aspire-app.md index 760ad7589a..dd14f9bb46 100644 --- a/docs/get-started/build-your-first-aspire-app.md +++ b/docs/get-started/build-your-first-aspire-app.md @@ -182,7 +182,7 @@ Consider the _:::no-loc text="Program.cs":::_ file of the _AspireSample.AppHost_ :::code source="snippets/quickstart/AspireSample/AspireSample.AppHost/Program.cs"::: -If you've used either the [.NET Generic Host](/dotnet/core/extensions/generic-host) or the [ASP.NET Core Web Host](/aspnet/core/fundamentals/host/web-host) before, the app host programming model and builder pattern should be familiar to you. The preceding code: +If you've used either the [.NET Generic Host](/dotnet/core/extensions/generic-host) or the [ASP.NET Core Web Host](/aspnet/core/fundamentals/host/web-host) before, the AppHost programming model and builder pattern should be familiar to you. The preceding code: - Creates an instance from calling . - Calls with the name `"cache"` to add a Redis server to the app, assigning the returned value to a variable named `cache`, which is of type `IResourceBuilder`. diff --git a/docs/get-started/dev-containers.md b/docs/get-started/dev-containers.md index c444bd165f..38d290306d 100644 --- a/docs/get-started/dev-containers.md +++ b/docs/get-started/dev-containers.md @@ -50,7 +50,7 @@ To configure Dev Containers in Visual Studio Code, use the _.devcontainer/devcon :::image source="media/vscode-run-button.png" lightbox="media/vscode-run-button.png" alt-text="Run button in editor."::: - Visual Studio Code builds and starts the .NET Aspire app host and automatically opens the .NET Aspire Dashboard. Because the endpoints hosted in the container are using a self-signed certificate the first time, you access an endpoint for a specific Dev Container you're presented with a certificate error. + Visual Studio Code builds and starts the .NET Aspire AppHost and automatically opens the .NET Aspire Dashboard. Because the endpoints hosted in the container are using a self-signed certificate the first time, you access an endpoint for a specific Dev Container you're presented with a certificate error. :::image source="media/browser-certificate-error.png" lightbox="media/browser-certificate-error.png" alt-text="Browser certificate error."::: diff --git a/docs/get-started/github-codespaces.md b/docs/get-started/github-codespaces.md index 214fcadec2..3fca4d9910 100644 --- a/docs/get-started/github-codespaces.md +++ b/docs/get-started/github-codespaces.md @@ -51,9 +51,9 @@ To configure GitHub Codespaces for .NET Aspire, use the _.devcontainer/devcontai :::image source="media/codespaces-explorer-panel.png" lightbox="media/codespaces-explorer-panel.png" alt-text="Codespaces Explorer panel"::: -1. Launch the app host via the _HelloAspire.AppHost/Program.cs_ file, by selecting the **Run project** button near the top-right corner of the **Tab bar**. +1. Launch the AppHost via the _HelloAspire.AppHost/Program.cs_ file, by selecting the **Run project** button near the top-right corner of the **Tab bar**. - :::image source="media/codespace-launch-apphost.png" lightbox="media/codespace-launch-apphost.png" alt-text="Launch app host in Codespace"::: + :::image source="media/codespace-launch-apphost.png" lightbox="media/codespace-launch-apphost.png" alt-text="Launch AppHost in Codespace"::: After a few moments the **Debug Console** panel is displayed, and it includes a link to the .NET Aspire dashboard exposed on a GitHub Codespaces endpoint with the authentication token. diff --git a/docs/get-started/migrate-from-docker-compose.md b/docs/get-started/migrate-from-docker-compose.md index 4633f4f13a..1bd0968a94 100644 --- a/docs/get-started/migrate-from-docker-compose.md +++ b/docs/get-started/migrate-from-docker-compose.md @@ -272,7 +272,7 @@ builder.Build().Run(); **Related links:** - [Docker Compose specification](https://docs.docker.com/compose/compose-file/) -- [.NET Aspire app host overview](../fundamentals/app-host-overview.md) +- [.NET Aspire AppHost overview](../fundamentals/app-host-overview.md) - [Add Dockerfiles to your .NET app model](../app-host/withdockerfile.md) ## Migration strategy @@ -289,7 +289,7 @@ Before migrating, inventory your Docker Compose setup: - **Environment variables**: List all configuration variables and secrets. - **Custom networks**: Identify any custom networking requirements and configurations. -### 2. Create the .NET Aspire app host +### 2. Create the .NET Aspire AppHost Start by creating a new .NET Aspire project: @@ -317,7 +317,7 @@ For persistent data: ### 5. Test and validate -- Start the .NET Aspire app host and verify all services start correctly. +- Start the .NET Aspire AppHost and verify all services start correctly. - Check the dashboard to confirm service health and connectivity status. - Validate that inter-service communication works as expected. - Test with your existing client applications to ensure compatibility. diff --git a/docs/get-started/upgrade-to-aspire-9.md b/docs/get-started/upgrade-to-aspire-9.md index d3e1f7a8c5..c6612423be 100644 --- a/docs/get-started/upgrade-to-aspire-9.md +++ b/docs/get-started/upgrade-to-aspire-9.md @@ -63,13 +63,13 @@ Previously the **aspire workload** was required to create and run .NET Aspire pr To upgrade your projects to .NET Aspire 9.0, you need to update your project files. The following steps guide you through the process: -- Edit your [app host](xref:dotnet/aspire/app-host) project file to use the new .NET Aspire 9.0 SDK (`Aspire.AppHost.Sdk`). +- Edit your [AppHost](xref:dotnet/aspire/app-host) project file to use the new .NET Aspire 9.0 SDK (`Aspire.AppHost.Sdk`). - Update the NuGet packages in your project files to the latest versions. - Adjust your _Program.cs_ file to use the new APIs and remove any obsolete APIs. -### Edit your app host project file +### Edit your AppHost project file -To upgrade your app host project to .NET Aspire 9.0, you need to update your project file to use the new [📦 Aspire.AppHost.Sdk](https://www.nuget.org/packages/Aspire.AppHost.Sdk): +To upgrade your AppHost project to .NET Aspire 9.0, you need to update your project file to use the new [📦 Aspire.AppHost.Sdk](https://www.nuget.org/packages/Aspire.AppHost.Sdk): ```diff @@ -120,9 +120,9 @@ To upgrade your app host project to .NET Aspire 9.0, you need to update your pro For more information on TFMs, see [Target frameworks in SDK-style projects: Latest versions](/dotnet/standard/frameworks#latest-versions). -### Overall app host project differences +### Overall AppHost project differences -If you followed all of the preceding steps, your app host project file should look like this: +If you followed all of the preceding steps, your AppHost project file should look like this: ```diff @@ -166,14 +166,14 @@ Regardless of how you install the Upgrade Assistant, you can use it to upgrade y :::zone pivot="visual-studio" -To upgrade the .NET Aspire app host project to .NET Aspire 9.0 with Visual Studio, right-click the project in **Solution Explorer** and select **Upgrade**. +To upgrade the .NET Aspire AppHost project to .NET Aspire 9.0 with Visual Studio, right-click the project in **Solution Explorer** and select **Upgrade**. > [!IMPORTANT] > If the **Upgrade Assistant** isn't already installed, you'll be prompted to install it. The Upgrade Assistant displays a welcome package. Select the **Aspire upgrades** option: -:::image type="content" source="media/upgrade-assistant-welcome-aspire.png" lightbox="media/upgrade-assistant-welcome-aspire.png" alt-text="Visual Studio: Upgrade Assistant welcome page with .NET Aspire app host project."::: +:::image type="content" source="media/upgrade-assistant-welcome-aspire.png" lightbox="media/upgrade-assistant-welcome-aspire.png" alt-text="Visual Studio: Upgrade Assistant welcome page with .NET Aspire AppHost project."::: With the **Aspire upgrades** option selected, the Upgrade Assistant displays the selectable upgrade target components. Leave all the options checked and select **Upgrade selection**: @@ -181,12 +181,12 @@ With the **Aspire upgrades** option selected, the Upgrade Assistant displays the Finally, after selecting the components to upgrade, the Upgrade Assistant displays the results of the upgrade process. If everything was successful, you see green check marks next to each component: -:::image type="content" source="media/upgrade-assistant-aspire-upgraded.png" lightbox="media/upgrade-assistant-aspire-upgraded.png" alt-text="Visual Studio: Upgrade Assistant .NET Aspire app host project upgraded successfully."::: +:::image type="content" source="media/upgrade-assistant-aspire-upgraded.png" lightbox="media/upgrade-assistant-aspire-upgraded.png" alt-text="Visual Studio: Upgrade Assistant .NET Aspire AppHost project upgraded successfully."::: :::zone-end :::zone pivot="vscode,dotnet-cli" -To upgrade the .NET Aspire app host project, ensure that you installed the Upgrade Assistant CLI. Open a terminal session at the root directory of the .NET Aspire app host project file, and run the following command: +To upgrade the .NET Aspire AppHost project, ensure that you installed the Upgrade Assistant CLI. Open a terminal session at the root directory of the .NET Aspire AppHost project file, and run the following command: ```dotnetcli upgrade-assistant upgrade @@ -256,7 +256,7 @@ To take advantage of the latest updates in your .NET Aspire solution, update all :::zone-end :::zone pivot="vscode,dotnet-cli" -To update your app host project, use the following .NET CLI command to update the `Aspire.Hosting.AppHost` package to version `9.0.0`: +To update your AppHost project, use the following .NET CLI command to update the `Aspire.Hosting.AppHost` package to version `9.0.0`: ```dotnetcli dotnet add package Aspire.Hosting.AppHost --version 9.0.0 @@ -266,7 +266,7 @@ When a package reference already exists, the `dotnet add package` command update :::zone-end -With the app host project updated, your project file should look like this: +With the AppHost project updated, your project file should look like this: ```diff diff --git a/docs/github/github-models-integration.md b/docs/github/github-models-integration.md index 860f8ca17b..4c91fe85f2 100644 --- a/docs/github/github-models-integration.md +++ b/docs/github/github-models-integration.md @@ -34,7 +34,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add a GitHub Model resource -To add a `GitHubModelResource` to your app host project, call the `AddGitHubModel` method: +To add a `GitHubModelResource` to your AppHost project, call the `AddGitHubModel` method: ```csharp var builder = DistributedApplication.CreateBuilder(args); diff --git a/docs/index.yml b/docs/index.yml index 75e52cce6e..a9454ba2f0 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -11,7 +11,7 @@ metadata: description: Learn about .NET Aspire, a cloud-ready stack for building distributed applications. Browse API reference, tutorials, and more. ms.topic: hub-page ms.service: dotnet-aspire - ms.date: 05/30/2025 + ms.date: 08/08/2025 highlightedContent: items: @@ -22,7 +22,7 @@ highlightedContent: title: Build your first .NET Aspire solution url: get-started/build-your-first-aspire-app.md - itemType: concept - title: App host orchestration + title: AppHost orchestration url: fundamentals/app-host-overview.md - itemType: concept title: .NET Aspire integrations diff --git a/docs/logging/seq-integration.md b/docs/logging/seq-integration.md index b7947824ef..18f5ebdbf2 100644 --- a/docs/logging/seq-integration.md +++ b/docs/logging/seq-integration.md @@ -15,7 +15,7 @@ During development, .NET Aspire runs and connects to the [`datalust/seq` contain ## Hosting integration -The Seq hosting integration models the server as the type. To access this type and the API, add the [📦 Aspire.Hosting.Seq](https://www.nuget.org/packages/Aspire.Hosting.Seq) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +The Seq hosting integration models the server as the type. To access this type and the API, add the [📦 Aspire.Hosting.Seq](https://www.nuget.org/packages/Aspire.Hosting.Seq) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -36,7 +36,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add a Seq resource -In your app host project, call to add and return a Seq resource builder. +In your AppHost project, call to add and return a Seq resource builder. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -66,7 +66,7 @@ Seq shouldn't be part of the .NET Aspire [deployment manifest](../deployment/man ### Persistent logs and traces -Register Seq with a data directory in your app host project to retain Seq's data and configuration across application restarts: +Register Seq with a data directory in your AppHost project to retain Seq's data and configuration across application restarts: ```csharp var seq = builder.AddSeq("seq", seqDataDirectory: "./seqdata") @@ -145,7 +145,7 @@ builder.AddSeqEndpoint(connectionName: "seq"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Seq resource in the app host project. In other words, when you call `AddSeq` and provide a name of `seq` that same name should be used when calling `AddSeqEndpoint`. For more information, see [Add a Seq resource](#add-a-seq-resource). +> The `connectionName` parameter must match the name used when adding the Seq resource in the AppHost project. In other words, when you call `AddSeq` and provide a name of `seq` that same name should be used when calling `AddSeqEndpoint`. For more information, see [Add a Seq resource](#add-a-seq-resource). ### Configuration diff --git a/docs/messaging/azure-event-hubs-integration.md b/docs/messaging/azure-event-hubs-integration.md index e4a2ace3c8..63a6225df7 100644 --- a/docs/messaging/azure-event-hubs-integration.md +++ b/docs/messaging/azure-event-hubs-integration.md @@ -20,7 +20,7 @@ The .NET Aspire [Azure Event Hubs](https://azure.microsoft.com/products/event-hu - : Represents an Azure Event Hubs emulator as a container resource. - : Represents a consumer group within an Event Hub resource. -To access these types and APIs for expressing them within your [app host](xref:dotnet/aspire/app-host) project, install the [📦 Aspire.Hosting.Azure.EventHubs](https://www.nuget.org/packages/Aspire.Hosting.Azure.EventHubs) NuGet package: +To access these types and APIs for expressing them within your [AppHost](xref:dotnet/aspire/app-host) project, install the [📦 Aspire.Hosting.Azure.EventHubs](https://www.nuget.org/packages/Aspire.Hosting.Azure.EventHubs) NuGet package: ### [.NET CLI](#tab/dotnet-cli) @@ -41,7 +41,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add an Azure Event Hubs resource -To add an to your app host project, call the method providing a name, and then call : +To add an to your AppHost project, call the method providing a name, and then call : ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -55,7 +55,7 @@ builder.AddProject() // After adding all resources, run the app... ``` -When you add an Azure Event Hubs resource to the app host, it exposes other useful APIs to add Event Hub resources, consumer groups, express explicit provisioning configuration, and enables the use of the Azure Event Hubs emulator. The preceding code adds an Azure Event Hubs resource named `event-hubs` and an Event Hub named `messages` to the app host project. The method passes the connection information to the `ExampleService` project. +When you add an Azure Event Hubs resource to the AppHost, it exposes other useful APIs to add Event Hub resources, consumer groups, express explicit provisioning configuration, and enables the use of the Azure Event Hubs emulator. The preceding code adds an Azure Event Hubs resource named `event-hubs` and an Event Hub named `messages` to the AppHost project. The method passes the connection information to the `ExampleService` project. > [!IMPORTANT] > When you call , it implicitly calls —which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see [Local provisioning: Configuration](../azure/local-provisioning.md#configuration) @@ -114,7 +114,7 @@ builder.AddProject() For more information on treating Azure Event Hubs resources as existing resources, see [Use existing Azure resources](../azure/integrations-overview.md#use-existing-azure-resources). > [!NOTE] -> Alternatively, instead of representing an Azure Event Hubs resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). +> Alternatively, instead of representing an Azure Event Hubs resource, you can add a connection string to the AppHost. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). ### Add Event Hub consumer group @@ -342,7 +342,7 @@ builder.AddAzureEventHubProducerClient(connectionName: "event-hubs"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Event Hubs resource in the app host project. For more information, see [Add an Azure Event Hubs resource](#add-an-azure-event-hubs-resource). +> The `connectionName` parameter must match the name used when adding the Event Hubs resource in the AppHost project. For more information, see [Add an Azure Event Hubs resource](#add-an-azure-event-hubs-resource). After adding the `EventHubProducerClient`, you can retrieve the client instance using dependency injection. For example, to retrieve your data source object from an example service define it as a constructor parameter and ensure the `ExampleService` class is registered with the dependency injection container: diff --git a/docs/messaging/azure-service-bus-integration.md b/docs/messaging/azure-service-bus-integration.md index 321748cba7..56520d57f1 100644 --- a/docs/messaging/azure-service-bus-integration.md +++ b/docs/messaging/azure-service-bus-integration.md @@ -21,7 +21,7 @@ The .NET Aspire [Azure Service Bus](https://azure.microsoft.com/services/service - : Represents an Azure Service Bus topic resource. - : Represents an Azure Service Bus emulator resource. -To access these types and APIs for expressing them, add the [📦 Aspire.Hosting.Azure.ServiceBus](https://www.nuget.org/packages/Aspire.Hosting.Azure.ServiceBus) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +To access these types and APIs for expressing them, add the [📦 Aspire.Hosting.Azure.ServiceBus](https://www.nuget.org/packages/Aspire.Hosting.Azure.ServiceBus) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -42,7 +42,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add Azure Service Bus resource -In your app host project, call to add and return an Azure Service Bus resource builder. +In your AppHost project, call to add and return an Azure Service Bus resource builder. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -52,7 +52,7 @@ var serviceBus = builder.AddAzureServiceBus("messaging"); // After adding all resources, run the app... ``` -When you add an to the app host, it exposes other useful APIs to add queues and topics. In other words, you must add an `AzureServiceBusResource` before adding any of the other Service Bus resources. +When you add an to the AppHost, it exposes other useful APIs to add queues and topics. In other words, you must add an `AzureServiceBusResource` before adding any of the other Service Bus resources. > [!IMPORTANT] > When you call , it implicitly calls —which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see [Configuration](../azure/local-provisioning.md#configuration). @@ -110,7 +110,7 @@ builder.AddProject("web") For more information on treating Azure Service Bus resources as existing resources, see [Use existing Azure resources](../azure/integrations-overview.md#use-existing-azure-resources). > [!NOTE] -> Alternatively, instead of representing an Azure Service Bus resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). +> Alternatively, instead of representing an Azure Service Bus resource, you can add a connection string to the AppHost. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). ### Add Azure Service Bus queue @@ -192,7 +192,7 @@ var serviceBus = builder.AddAzureServiceBus("messaging") // After adding all resources, run the app... ``` -When you call `RunAsEmulator`, it configures your Service Bus resources to run locally using an emulator. The emulator in this case is the [Azure Service Bus Emulator](/azure/service-bus-messaging/overview-emulator). The Azure Service Bus Emulator provides a free local environment for testing your Azure Service Bus apps and it's a perfect companion to the .NET Aspire Azure hosting integration. The emulator isn't installed, instead, it's accessible to .NET Aspire as a container. When you add a container to the app host, as shown in the preceding example with the `mcr.microsoft.com/azure-messaging/servicebus-emulator` image (and the companion `mcr.microsoft.com/azure-sql-edge` image), it creates and starts the container when the app host starts. For more information, see [Container resource lifecycle](../fundamentals/orchestrate-resources.md#container-resource-lifecycle). +When you call `RunAsEmulator`, it configures your Service Bus resources to run locally using an emulator. The emulator in this case is the [Azure Service Bus Emulator](/azure/service-bus-messaging/overview-emulator). The Azure Service Bus Emulator provides a free local environment for testing your Azure Service Bus apps and it's a perfect companion to the .NET Aspire Azure hosting integration. The emulator isn't installed, instead, it's accessible to .NET Aspire as a container. When you add a container to the AppHost, as shown in the preceding example with the `mcr.microsoft.com/azure-messaging/servicebus-emulator` image (and the companion `mcr.microsoft.com/azure-sql-edge` image), it creates and starts the container when the AppHost starts. For more information, see [Container resource lifecycle](../fundamentals/orchestrate-resources.md#container-resource-lifecycle). #### Configure Service Bus emulator container @@ -305,7 +305,7 @@ builder.AddAzureServiceBusClient(connectionName: "messaging"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Service Bus resource in the app host project. In other words, when you call `AddAzureServiceBus` and provide a name of `messaging` that same name should be used when calling `AddAzureServiceBusClient`. For more information, see [Add Azure Service Bus resource](#add-azure-service-bus-resource). +> The `connectionName` parameter must match the name used when adding the Service Bus resource in the AppHost project. In other words, when you call `AddAzureServiceBus` and provide a name of `messaging` that same name should be used when calling `AddAzureServiceBusClient`. For more information, see [Add Azure Service Bus resource](#add-azure-service-bus-resource). You can then retrieve the instance using dependency injection. For example, to retrieve the connection from an example service: diff --git a/docs/messaging/azure-web-pubsub-integration.md b/docs/messaging/azure-web-pubsub-integration.md index bd5df0d2bd..26eeb65edc 100644 --- a/docs/messaging/azure-web-pubsub-integration.md +++ b/docs/messaging/azure-web-pubsub-integration.md @@ -19,7 +19,7 @@ The .NET Aspire [Azure Web PubSub](https://azure.microsoft.com/products/web-pubs - : Represents an Azure Web PubSub resource, including connection information to the underlying Azure resource. - : Represents a Web PubSub hub settings resource, which contains the settings for a hub. For example, you can specify if the hub allows anonymous connections or add event handlers to the hub. -To access these types and APIs for expressing them within your [app host](xref:dotnet/aspire/app-host) project, install the [📦 Aspire.Hosting.Azure.WebPubSub](https://www.nuget.org/packages/Aspire.Hosting.Azure.WebPubSub) NuGet package: +To access these types and APIs for expressing them within your [AppHost](xref:dotnet/aspire/app-host) project, install the [📦 Aspire.Hosting.Azure.WebPubSub](https://www.nuget.org/packages/Aspire.Hosting.Azure.WebPubSub) NuGet package: ### [.NET CLI](#tab/dotnet-cli) @@ -40,7 +40,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add an Azure Web PubSub resource -To add an Azure Web PubSub resource to your app host project, call the method providing a name: +To add an Azure Web PubSub resource to your AppHost project, call the method providing a name: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -53,14 +53,14 @@ builder.AddProject() // After adding all resources, run the app... ``` -The preceding code adds an Azure Web PubSub resource named `web-pubsub` to the app host project. The method passes the connection information to the `ExampleProject` project. +The preceding code adds an Azure Web PubSub resource named `web-pubsub` to the AppHost project. The method passes the connection information to the `ExampleProject` project. > [!IMPORTANT] > When you call `AddAzureWebPubSub`, it implicitly calls —which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see [Local provisioning: Configuration](../azure/local-provisioning.md#configuration). ### Add an Azure Web PubSub hub resource -When you add an Azure Web PubSub resource, you can also add a child hub resource. The hub resource is a logical grouping of connections and event handlers. To add an Azure Web PubSub hub resource to your app host project, chain a call to the method providing a resource and hub name: +When you add an Azure Web PubSub resource, you can also add a child hub resource. The hub resource is a logical grouping of connections and event handlers. To add an Azure Web PubSub hub resource to your AppHost project, chain a call to the method providing a resource and hub name: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -149,7 +149,7 @@ builder.AddProject() For more information on treating Azure Web PubSub resources as existing resources, see [Use existing Azure resources](../azure/integrations-overview.md#use-existing-azure-resources). > [!NOTE] -> Alternatively, instead of representing an Azure AI Search resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). +> Alternatively, instead of representing an Azure AI Search resource, you can add a connection string to the AppHost. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). ## Client integration @@ -188,7 +188,7 @@ builder.AddAzureWebPubSubServiceClient( ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Web PubSub resource in the app host project. For more information, see [Add an Azure Web PubSub resource](#add-an-azure-web-pubsub-resource). +> The `connectionName` parameter must match the name used when adding the Web PubSub resource in the AppHost project. For more information, see [Add an Azure Web PubSub resource](#add-an-azure-web-pubsub-resource). After adding the `WebPubSubServiceClient`, you can retrieve the client instance using dependency injection. For example, to retrieve your data source object from an example service define it as a constructor parameter and ensure the `ExampleService` class is registered with the dependency injection container: diff --git a/docs/messaging/kafka-integration.md b/docs/messaging/kafka-integration.md index bb24a2be27..fbe084ba6e 100644 --- a/docs/messaging/kafka-integration.md +++ b/docs/messaging/kafka-integration.md @@ -14,7 +14,7 @@ ms.custom: sfi-ropc-nochange ## Hosting integration -The Apache Kafka hosting integration models a Kafka server as the type. To access this type, install the [📦 Aspire.Hosting.Kafka](https://www.nuget.org/packages/Aspire.Hosting.Kafka) NuGet package in the [app host](xref:dotnet/aspire/app-host) project, then add it with the builder. +The Apache Kafka hosting integration models a Kafka server as the type. To access this type, install the [📦 Aspire.Hosting.Kafka](https://www.nuget.org/packages/Aspire.Hosting.Kafka) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project, then add it with the builder. ### [.NET CLI](#tab/dotnet-cli) @@ -35,7 +35,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add Kafka server resource -In your app host project, call on the `builder` instance to add a Kafka server resource: +In your AppHost project, call on the `builder` instance to add a Kafka server resource: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -48,7 +48,7 @@ builder.AddProject() // After adding all resources, run the app... ``` -When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `docker.io/confluentinc/confluent-local` image, it creates a new Kafka server instance on your local machine. A reference to your Kafka server (the `kafka` variable) is added to the `ExampleProject`. The Kafka server resource includes default ports +When .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `docker.io/confluentinc/confluent-local` image, it creates a new Kafka server instance on your local machine. A reference to your Kafka server (the `kafka` variable) is added to the `ExampleProject`. The Kafka server resource includes default ports The method configures a connection in the `ExampleProject` named `"kafka"`. For more information, see [Container resource lifecycle](../fundamentals/orchestrate-resources.md#container-resource-lifecycle). @@ -71,7 +71,7 @@ builder.AddProject() // After adding all resources, run the app... ``` -The Kafka UI is a free, open-source web UI to monitor and manage Apache Kafka clusters. .NET Aspire adds another container image [`docker.io/kafbat/kafka-ui`](https://hub.docker.com/r/kafbat/kafka-ui) to the app host that runs the Kafka UI. +The Kafka UI is a free, open-source web UI to monitor and manage Apache Kafka clusters. .NET Aspire adds another container image [`docker.io/kafbat/kafka-ui`](https://hub.docker.com/r/kafbat/kafka-ui) to the AppHost that runs the Kafka UI. ### Change the Kafka UI host port diff --git a/docs/messaging/nats-integration.md b/docs/messaging/nats-integration.md index a1ec6eb037..ddf48c3bb6 100644 --- a/docs/messaging/nats-integration.md +++ b/docs/messaging/nats-integration.md @@ -14,7 +14,7 @@ ms.custom: sfi-ropc-nochange ## Hosting integration -NATS hosting integration for .NET Aspire models a NATS server as the type. To access this type, install the [📦 Aspire.Hosting.Nats](https://www.nuget.org/packages/Aspire.Hosting.Nats) NuGet package in the [app host](xref:dotnet/aspire/app-host) project, then add it with the builder. +NATS hosting integration for .NET Aspire models a NATS server as the type. To access this type, install the [📦 Aspire.Hosting.Nats](https://www.nuget.org/packages/Aspire.Hosting.Nats) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project, then add it with the builder. ### [.NET CLI](#tab/dotnet-cli) @@ -35,7 +35,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add NATS server resource -In your app host project, call on the `builder` instance to add a NATS server resource: +In your AppHost project, call on the `builder` instance to add a NATS server resource: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -48,7 +48,7 @@ builder.AddProject() // After adding all resources, run the app... ``` -When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `docker.io/library/nats` image, it creates a new NATS server instance on your local machine. A reference to your NATS server (the `nats` variable) is added to the `ExampleProject`. +When .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `docker.io/library/nats` image, it creates a new NATS server instance on your local machine. A reference to your NATS server (the `nats` variable) is added to the `ExampleProject`. The method configures a connection in the `ExampleProject` named `"nats"`. For more information, see [Container resource lifecycle](../fundamentals/orchestrate-resources.md#container-resource-lifecycle). @@ -171,7 +171,7 @@ builder.AddNatsClient(connectionName: "nats"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the NATS server resource in the app host project. For more information, see [Add NATS server resource](#add-nats-server-resource). +> The `connectionName` parameter must match the name used when adding the NATS server resource in the AppHost project. For more information, see [Add NATS server resource](#add-nats-server-resource). You can then retrieve the `INatsConnection` instance using dependency injection. For example, to retrieve the client from a service: diff --git a/docs/messaging/rabbitmq-integration.md b/docs/messaging/rabbitmq-integration.md index f5000dd93e..2276de2377 100644 --- a/docs/messaging/rabbitmq-integration.md +++ b/docs/messaging/rabbitmq-integration.md @@ -1,7 +1,7 @@ --- title: .NET Aspire RabbitMQ integration description: Learn how to use the .NET Aspire RabbitMQ message-broker integration, which includes both hosting and client integrations. -ms.date: 02/19/2025 +ms.date: 08/07/2025 uid: messaging/rabbitmq-integration ms.custom: sfi-ropc-nochange --- @@ -18,7 +18,7 @@ TODO: Diagram showing the thing we're integrating with and the components of the ## Hosting integration -The RabbitMQ hosting integration models a RabbitMQ server as the type. To access this type and its APIs add the [📦 Aspire.Hosting.RabbitMQ](https://www.nuget.org/packages/Aspire.Hosting.RabbitMQ) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +The RabbitMQ hosting integration models a RabbitMQ server as the type. To access this type and its APIs add the [📦 Aspire.Hosting.RabbitMQ](https://www.nuget.org/packages/Aspire.Hosting.RabbitMQ) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -39,7 +39,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add RabbitMQ server resource -In your app host project, call on the `builder` instance to add a RabbitMQ server resource: +In your AppHost project, call on the `builder` instance to add a RabbitMQ server resource: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -52,7 +52,7 @@ builder.AddProject() // After adding all resources, run the app... ``` -When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `docker.io/library/rabbitmq` image, it creates a new RabbitMQ server instance on your local machine. A reference to your RabbitMQ server (the `rabbitmq` variable) is added to the `ExampleProject`. The RabbitMQ server resource includes default credentials with a `username` of `"guest"` and randomly generated `password` using the method. +When .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `docker.io/library/rabbitmq` image, it creates a new RabbitMQ server instance on your local machine. A reference to your RabbitMQ server (the `rabbitmq` variable) is added to the `ExampleProject`. The RabbitMQ server resource includes default credentials with a `username` of `"guest"` and randomly generated `password` using the method. The method configures a connection in the `ExampleProject` named `"messaging"`. For more information, see [Container resource lifecycle](../fundamentals/orchestrate-resources.md#container-resource-lifecycle). @@ -138,7 +138,7 @@ builder.AddProject() // After adding all resources, run the app... ``` -The RabbitMQ management plugin provides an HTTP-based API for management and monitoring of your RabbitMQ server. .NET Aspire adds another container image [`docker.io/library/rabbitmq-management`](https://hub.docker.com/_/rabbitmq) to the app host that runs the management plugin. You can access the management plugin from the .NET Aspire dashboard by selecting an endpoint for your RabbitMQ resource: +The RabbitMQ management plugin provides an HTTP-based API for management and monitoring of your RabbitMQ server. .NET Aspire adds another container image [`docker.io/library/rabbitmq-management`](https://hub.docker.com/_/rabbitmq) to the AppHost that runs the management plugin. You can access the management plugin from the .NET Aspire dashboard by selecting an endpoint for your RabbitMQ resource: :::image type="content" source="media/dashboard-access-rabbitmq-management.png" alt-text="Screenshot of the .NET Aspire dashboard showing how to connect to the RabbitMQ management plugin."::: @@ -146,9 +146,7 @@ Log into the management plugin using the credentials you configured with paramet :::image type="content" source="media/rabbitmq-management-plugin.png" alt-text="Screenshot of the RabbitMQ management plugin."::: - +For more information, see [Container resource lifetimes](../fundamentals/orchestrate-resources.md#container-resource-lifetime). ### Hosting integration health checks @@ -187,7 +185,7 @@ builder.AddRabbitMQClient(connectionName: "messaging"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the RabbitMQ server resource in the app host project. For more information, see [Add RabbitMQ server resource](#add-rabbitmq-server-resource). +> The `connectionName` parameter must match the name used when adding the RabbitMQ server resource in the AppHost project. For more information, see [Add RabbitMQ server resource](#add-rabbitmq-server-resource). You can then retrieve the `IConnection` instance using dependency injection. For example, to retrieve the connection from an example service: diff --git a/docs/proxies/yarp-integration.md b/docs/proxies/yarp-integration.md index b61f6a6f9e..8d06cbcf5a 100644 --- a/docs/proxies/yarp-integration.md +++ b/docs/proxies/yarp-integration.md @@ -1,7 +1,7 @@ --- title: YARP integration description: Learn how to use the .NET Aspire YARP reverse proxy integration, which includes hosting integration for containerized YARP instances. -ms.date: 07/25/2025 +ms.date: 08/07/2025 ai-usage: ai-assisted --- @@ -13,7 +13,7 @@ ai-usage: ai-assisted ## Hosting integration -The YARP hosting integration models a containerized YARP reverse proxy as the `YarpResource` type . To access this type and its APIs add the [📦 Aspire.Hosting.Yarp](https://www.nuget.org/packages/Aspire.Hosting.Yarp) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +The YARP hosting integration models a containerized YARP reverse proxy as the type. To access this type and its APIs add the [📦 Aspire.Hosting.Yarp](https://www.nuget.org/packages/Aspire.Hosting.Yarp) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -34,7 +34,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add YARP resource -In your app host project, call `AddYarp` on the `builder` instance to add a YARP resource: +In your AppHost project, call on the `builder` instance to add a YARP resource: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -53,7 +53,7 @@ var gateway = builder.AddYarp("gateway") // After adding all resources, run the app... ``` -When .NET Aspire adds a YARP resource to the app host, it creates a new containerized YARP instance using the [mcr.microsoft.com/dotnet/nightly/yarp](https://mcr.microsoft.com/product/dotnet/nightly/yarp/about) container image. This official Microsoft container image contains a preconfigured YARP reverse proxy server that can be dynamically configured through Aspire's hosting APIs. +When .NET Aspire adds a YARP resource to the AppHost, it creates a new containerized YARP instance using the [mcr.microsoft.com/dotnet/nightly/yarp](https://mcr.microsoft.com/product/dotnet/nightly/yarp/about) container image. This official Microsoft container image contains a preconfigured YARP reverse proxy server that can be dynamically configured through Aspire's hosting APIs. The container image provides: @@ -62,11 +62,11 @@ The container image provides: - Integration with .NET service discovery. - Built-in health checks and monitoring capabilities. -The YARP resource can be configured programmatically using the `WithConfiguration` method or through external configuration files. +The YARP resource can be configured programmatically using the method or through external configuration files. ### Add YARP resource with external configuration -To configure the YARP resource using an external JSON configuration file, use the `WithConfigFile` method: +To configure the YARP resource using an external JSON configuration file, use the method: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -139,7 +139,7 @@ The `yarp.json` configuration file can reference services using their resource n ### Programmatic configuration -The YARP integration provides a fluent API for configuring routes, clusters, and transforms programmatically using the `IYarpConfigurationBuilder` : +The YARP integration provides a fluent API for configuring routes, clusters, and transforms programmatically using the : ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -229,7 +229,7 @@ yarp.AddRoute("/api/{**catch-all}", basketService) ### Customize host port -To configure the host port that the YARP resource is exposed on, use the `WithHostPort` method: +To configure the host port that the YARP resource is exposed on, use the method: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -248,9 +248,7 @@ By default, YARP uses a randomly assigned port. Using `WithHostPort` allows you ### Service discovery integration - - -The YARP integration automatically works with .NET service discovery when targeting resources that implement `IResourceWithServiceDiscovery`. This enables dynamic endpoint resolution for backend services: +The YARP integration automatically works with .NET service discovery when targeting resources that implement . This enables dynamic endpoint resolution for backend services: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -265,11 +263,7 @@ var gateway = builder.AddYarp("gateway") }); ``` - - -For external services, use `AddExternalService`: +For external services, use : ```csharp var externalApi = builder.AddExternalService("external-api") diff --git a/docs/real-time/azure-signalr-scenario.md b/docs/real-time/azure-signalr-scenario.md index 3eb74fd622..249d4948ad 100644 --- a/docs/real-time/azure-signalr-scenario.md +++ b/docs/real-time/azure-signalr-scenario.md @@ -1,7 +1,7 @@ --- title: .NET Aspire Azure SignalR Service integration description: Learn how to integrate Azure SignalR Service with .NET Aspire. -ms.date: 07/22/2025 +ms.date: 08/07/2025 ms.custom: sfi-ropc-nochange --- @@ -20,7 +20,7 @@ The .NET Aspire Azure SignalR Service hosting integration models Azure SignalR r - : Represents an Azure SignalR Service resource, including connection information to the underlying Azure resource. - : Represents an emulator for Azure SignalR Service, allowing local development and testing without requiring an Azure subscription. -To access the hosting types and APIs for expressing these resources in the distributed application builder, install the [📦 Aspire.Hosting.Azure.SignalR](https://www.nuget.org/packages/Aspire.Hosting.Azure.SignalR) NuGet package in your [app host](../fundamentals/app-host-overview.md#app-host-project) project: +To access the hosting types and APIs for expressing these resources in the distributed application builder, install the [📦 Aspire.Hosting.Azure.SignalR](https://www.nuget.org/packages/Aspire.Hosting.Azure.SignalR) NuGet package in your [AppHost](../fundamentals/app-host-overview.md#apphost-project) project: ### [.NET CLI](#tab/dotnet-cli) @@ -41,7 +41,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add an Azure SignalR Service resource -To add an Azure SignalR Service resource to your app host project, call the method: +To add an Azure SignalR Service resource to your AppHost project, call the method: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -68,7 +68,7 @@ In the preceding example: This architecture allows the `webapp` project to communicate with the `api` project, which in turn communicates with the Azure SignalR Service resource. > [!IMPORTANT] -> Calling `AddAzureSignalR` implicitly enables Azure provisioning support. Ensure your app host is configured with the appropriate Azure subscription and location. For more information, see [Local provisioning: Configuration](../azure/local-provisioning.md#configuration). +> Calling `AddAzureSignalR` implicitly enables Azure provisioning support. Ensure your AppHost is configured with the appropriate Azure subscription and location. For more information, see [Local provisioning: Configuration](../azure/local-provisioning.md#configuration). ### Provisioning-generated Bicep @@ -122,7 +122,7 @@ builder.AddProject() For more information on treating Azure SignalR resources as existing resources, see [Use existing Azure resources](../azure/integrations-overview.md#use-existing-azure-resources). > [!NOTE] -> Alternatively, instead of representing an Azure SignalR Service resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). +> Alternatively, instead of representing an Azure SignalR Service resource, you can add a connection string to the AppHost. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). ### Add an Azure SignalR Service emulator resource @@ -145,20 +145,14 @@ builder.AddProject("apiService") // After adding all resources, run the app... ``` -In the preceding example, the `RunAsEmulator` method configures the Azure SignalR Service resource to run as an emulator. The emulator is based on the `mcr.microsoft.com/signalr/signalr-emulator:latest` container image. The emulator is started when the app host is run, and is stopped when the app host is stopped. +In the preceding example, the `RunAsEmulator` method configures the Azure SignalR Service resource to run as an emulator. The emulator is based on the `mcr.microsoft.com/signalr/signalr-emulator:latest` container image. The emulator is started when the AppHost is run, and is stopped when the AppHost is stopped. #### Azure SignalR Service modes While the Azure SignalR Service emulator only supports the _Serverless_ mode, the Azure SignalR Service resource can be configured to use either of the following modes: -- `AzureSignalRServiceMode.Default` -- `AzureSignalRServiceMode.Serverless` - - +- +- The _Default_ mode is the "default" configuration for Azure SignalR Service. Each mode has its own set of features and limitations. For more information, see [Azure SignalR Service modes](/azure/azure-signalr/concept-service-mode). @@ -219,7 +213,7 @@ The `AddNamedAzureSignalR` method configures the project to use the Azure Signal ### Configure Azure SignalR Service in Serverless mode -If you're app host is using the Azure SignalR emulator, you'll also need to install the [📦 Microsoft.Azure.SignalR.Management](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Management) NuGet package. +If you're AppHost is using the Azure SignalR emulator, you'll also need to install the [📦 Microsoft.Azure.SignalR.Management](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Management) NuGet package. ### [.NET CLI](#tab/dotnet-cli) diff --git a/docs/search/elasticsearch-integration.md b/docs/search/elasticsearch-integration.md index 051b19be35..d2599d5fda 100644 --- a/docs/search/elasticsearch-integration.md +++ b/docs/search/elasticsearch-integration.md @@ -14,7 +14,7 @@ ms.custom: sfi-ropc-nochange ## Hosting integration -The Elasticsearch hosting integration models an Elasticsearch instance as the type. To access this type and APIs that allow you to add it to your [📦 Aspire.Hosting.Elasticsearch](https://www.nuget.org/packages/Aspire.Hosting.Elasticsearch) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +The Elasticsearch hosting integration models an Elasticsearch instance as the type. To access this type and APIs that allow you to add it to your [📦 Aspire.Hosting.Elasticsearch](https://www.nuget.org/packages/Aspire.Hosting.Elasticsearch) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -35,7 +35,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add Elasticsearch resource -In your app host project, call on the `builder` instance to add an Elasticsearch resource: +In your AppHost project, call on the `builder` instance to add an Elasticsearch resource: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -48,7 +48,7 @@ builder.AddProject() // After adding all resources, run the app... ``` -When .NET Aspire adds a container image to the app host, as shown in the preceding example with the `docker.io/library/elasticsearch` image, it creates a new Elasticsearch instance on your local machine. A reference to your Elasticsearch resource (the `elasticsearch` variable) is added to the `ExampleProject`. The Elasticsearch resource includes default credentials with a `username` of `"elastic"` and randomly generated `password` using the method when a password wasn't provided. +When .NET Aspire adds a container image to the AppHost, as shown in the preceding example with the `docker.io/library/elasticsearch` image, it creates a new Elasticsearch instance on your local machine. A reference to your Elasticsearch resource (the `elasticsearch` variable) is added to the `ExampleProject`. The Elasticsearch resource includes default credentials with a `username` of `"elastic"` and randomly generated `password` using the method when a password wasn't provided. The method configures a connection in the `ExampleProject` named `"elasticsearch"`. For more information, see [Container resource lifecycle](../fundamentals/orchestrate-resources.md#container-resource-lifecycle). @@ -147,7 +147,7 @@ builder.AddElasticsearchClient(connectionName: "elasticsearch"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Elasticsearch resource in the app host project. For more information, see [Add Elasticsearch resource](#add-elasticsearch-resource). +> The `connectionName` parameter must match the name used when adding the Elasticsearch resource in the AppHost project. For more information, see [Add Elasticsearch resource](#add-elasticsearch-resource). You can then retrieve the `ElasticsearchClient` instance using dependency injection. For example, to retrieve the connection from an example service: diff --git a/docs/security/azure-security-key-vault-integration.md b/docs/security/azure-security-key-vault-integration.md index ab00e61337..370af7d78f 100644 --- a/docs/security/azure-security-key-vault-integration.md +++ b/docs/security/azure-security-key-vault-integration.md @@ -14,7 +14,7 @@ ms.custom: sfi-ropc-nochange ## Hosting integration -The Azure Key Vault hosting integration models a Key Vault resource as the type. To access this type and APIs for expressing them within your [app host](xref:dotnet/aspire/app-host) project, install the [📦 Aspire.Hosting.Azure.KeyVault](https://www.nuget.org/packages/Aspire.Hosting.Azure.KeyVault) NuGet package: +The Azure Key Vault hosting integration models a Key Vault resource as the type. To access this type and APIs for expressing them within your [AppHost](xref:dotnet/aspire/app-host) project, install the [📦 Aspire.Hosting.Azure.KeyVault](https://www.nuget.org/packages/Aspire.Hosting.Azure.KeyVault) NuGet package: ### [.NET CLI](#tab/dotnet-cli) @@ -35,7 +35,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add Azure Key Vault resource -In your app host project, call on the builder instance to add an Azure Key Vault resource: +In your AppHost project, call on the builder instance to add an Azure Key Vault resource: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -110,7 +110,7 @@ builder.AddProject() For more information on treating Azure Key Vault resources as existing resources, see [Use existing Azure resources](../azure/integrations-overview.md#use-existing-azure-resources). > [!NOTE] -> Alternatively, instead of representing an Azure Key Vault resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). +> Alternatively, instead of representing an Azure Key Vault resource, you can add a connection string to the AppHost. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). ## Client integration @@ -148,7 +148,7 @@ builder.Configuration.AddAzureKeyVaultSecrets(connectionName: "key-vault"); > The `AddAzureKeyVaultSecrets` API name has caused a bit of confusion. The method is used to configure the `SecretClient` based on the given connection name, and _it's not used_ to add secrets to the configuration. > [!TIP] -> The `connectionName` parameter must match the name used when adding the Azure Key Vault resource in the app host project. For more information, see [Add Azure Key Vault resource](#add-azure-key-vault-resource). +> The `connectionName` parameter must match the name used when adding the Azure Key Vault resource in the AppHost project. For more information, see [Add Azure Key Vault resource](#add-azure-key-vault-resource). You can then retrieve a secret-based configuration value through the normal APIs, or even by binding to strongly-typed classes with the [options pattern](/dotnet/core/extensions/options). To retrieve a secret from an example service class that's been registered with the dependency injection container, consider the following snippets: @@ -193,7 +193,7 @@ builder.AddAzureKeyVaultClient(connectionName: "key-vault"); ``` > [!TIP] -> The `connectionName` parameter must match the name used when adding the Azure Key Vault resource in the app host project. For more information, see [Add Azure Key Vault resource](#add-azure-key-vault-resource). +> The `connectionName` parameter must match the name used when adding the Azure Key Vault resource in the AppHost project. For more information, see [Add Azure Key Vault resource](#add-azure-key-vault-resource). After adding the `SecretClient` to the builder, you can get the instance using dependency injection. For example, to retrieve the client from an example service define it as a constructor parameter and ensure the `ExampleService` class is registered with the dependency injection container: diff --git a/docs/serverless/functions.md b/docs/serverless/functions.md index c945aa485b..07f9f31fe8 100644 --- a/docs/serverless/functions.md +++ b/docs/serverless/functions.md @@ -12,7 +12,7 @@ zone_pivot_groups: dev-environment > [!IMPORTANT] > The .NET Aspire Azure Functions integration is currently in preview and is subject to change. -[Azure Functions](/azure/azure-functions/functions-overview) is a serverless solution that allows you to write less code, maintain less infrastructure, and save on costs. The .NET Aspire Azure Functions integration enables you to develop, debug, and orchestrate an Azure Functions .NET project as part of the app host. +[Azure Functions](/azure/azure-functions/functions-overview) is a serverless solution that allows you to write less code, maintain less infrastructure, and save on costs. The .NET Aspire Azure Functions integration enables you to develop, debug, and orchestrate an Azure Functions .NET project as part of the AppHost. It's expected that you've installed the required Azure tooling: @@ -87,7 +87,7 @@ In Visual Studio, try checking for an update on the Azure Functions tooling. Ope ## Hosting integration -The Azure Functions hosting integration models an Azure Functions resource as the (subtype of ) type. To access this type and APIs that allow you to add it to your [app host](xref:dotnet/aspire/app-host) project install the [📦 Aspire.Hosting.Azure.Functions](https://www.nuget.org/packages/Aspire.Hosting.Azure.Functions) NuGet package. +The Azure Functions hosting integration models an Azure Functions resource as the (subtype of ) type. To access this type and APIs that allow you to add it to your [AppHost](xref:dotnet/aspire/app-host) project install the [📦 Aspire.Hosting.Azure.Functions](https://www.nuget.org/packages/Aspire.Hosting.Azure.Functions) NuGet package. ### [.NET CLI](#tab/dotnet-cli) @@ -108,7 +108,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add Azure Functions resource -In your app host project, call on the `builder` instance to add an Azure Functions resource: +In your AppHost project, call on the `builder` instance to add an Azure Functions resource: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -123,7 +123,7 @@ builder.AddProject() // After adding all resources, run the app... ``` -When .NET Aspire adds an Azure Functions project resource the app host, as shown in the preceding example, the `functions` resource can be referenced by other project resources. The method configures a connection in the `ExampleProject` named `"functions"`. If the Azure Resource was deployed and it exposed an HTTP trigger, its endpoint would be external due to the call to . For more information, see [Reference resources](../fundamentals/app-host-overview.md#reference-resources). +When .NET Aspire adds an Azure Functions project resource the AppHost, as shown in the preceding example, the `functions` resource can be referenced by other project resources. The method configures a connection in the `ExampleProject` named `"functions"`. If the Azure Resource was deployed and it exposed an HTTP trigger, its endpoint would be external due to the call to . For more information, see [Reference resources](../fundamentals/app-host-overview.md#reference-resources). ### Add Azure Functions resource with host storage @@ -167,7 +167,7 @@ builder.AddAzureFunctionsProject("functions") builder.Build().Run(); ``` -The preceding code adds an Azure Storage resource to the app host and references it in the Azure Functions project. The `blobs` resource is added to the `storage` resource and then referenced by the `functions` resource. The connection information required to connect to the `blobs` resource is automatically injected into the Azure Functions project and enables the project to define a `BlobTrigger` that relies on `blobs` resource. +The preceding code adds an Azure Storage resource to the AppHost and references it in the Azure Functions project. The `blobs` resource is added to the `storage` resource and then referenced by the `functions` resource. The connection information required to connect to the `blobs` resource is automatically injected into the Azure Functions project and enables the project to define a `BlobTrigger` that relies on `blobs` resource. ## See also diff --git a/docs/storage/azure-storage-blobs-integration.md b/docs/storage/azure-storage-blobs-integration.md index 25a41adc7a..896300d3d6 100644 --- a/docs/storage/azure-storage-blobs-integration.md +++ b/docs/storage/azure-storage-blobs-integration.md @@ -18,7 +18,7 @@ ms.custom: sfi-ropc-nochange ### Add Azure Blob Storage resource -In your app host project, register the Azure Blob Storage integration by chaining a call to on the `IResourceBuilder` instance returned by . The following example demonstrates how to add an Azure Blob Storage resource named `storage` and a blob container named `blobs`: +In your AppHost project, register the Azure Blob Storage integration by chaining a call to on the `IResourceBuilder` instance returned by . The following example demonstrates how to add an Azure Blob Storage resource named `storage` and a blob container named `blobs`: ```csharp var builder = DistributedApplication.CreateBuilder(args); diff --git a/docs/storage/azure-storage-queues-integration.md b/docs/storage/azure-storage-queues-integration.md index c1cfa58280..07b6306d56 100644 --- a/docs/storage/azure-storage-queues-integration.md +++ b/docs/storage/azure-storage-queues-integration.md @@ -18,7 +18,7 @@ ms.custom: sfi-ropc-nochange ### Add Azure Queue Storage resource -In your app host project, register the Azure Queue Storage integration by chaining a call to on the `IResourceBuilder` instance returned by . The following example demonstrates how to add an Azure Queue Storage resource named `storage` and a queue resource named `queues`: +In your AppHost project, register the Azure Queue Storage integration by chaining a call to on the `IResourceBuilder` instance returned by . The following example demonstrates how to add an Azure Queue Storage resource named `storage` and a queue resource named `queues`: ```csharp var builder = DistributedApplication.CreateBuilder(args); diff --git a/docs/storage/azure-storage-tables-integration.md b/docs/storage/azure-storage-tables-integration.md index dc77bd4eb0..6c1d28a1fd 100644 --- a/docs/storage/azure-storage-tables-integration.md +++ b/docs/storage/azure-storage-tables-integration.md @@ -17,7 +17,7 @@ uid: storage/azure-data-tables-integration ### Add Azure Table Storage resource -In your app host project, register the Azure Table Storage integration by chaining a call to on the `IResourceBuilder` instance returned by . The following example demonstrates how to add an Azure Table Storage resource named `storage` and a table resource named `tables`: +In your AppHost project, register the Azure Table Storage integration by chaining a call to on the `IResourceBuilder` instance returned by . The following example demonstrates how to add an Azure Table Storage resource named `storage` and a table resource named `tables`: ```csharp var builder = DistributedApplication.CreateBuilder(args); diff --git a/docs/storage/includes/storage-app-host.md b/docs/storage/includes/storage-app-host.md index 02a5730452..318236c8f9 100644 --- a/docs/storage/includes/storage-app-host.md +++ b/docs/storage/includes/storage-app-host.md @@ -11,7 +11,7 @@ The .NET Aspire [Azure Storage](/azure/storage/) hosting integration models the - : Represents an Azure Queue storage resource. - : Represents an Azure Table storage resource. -To access these types and APIs for expressing them, add the [📦 Aspire.Hosting.Azure.Storage](https://www.nuget.org/packages/Aspire.Hosting.Azure.Storage) NuGet package in the [app host](xref:dotnet/aspire/app-host) project. +To access these types and APIs for expressing them, add the [📦 Aspire.Hosting.Azure.Storage](https://www.nuget.org/packages/Aspire.Hosting.Azure.Storage) NuGet package in the [AppHost](xref:dotnet/aspire/app-host) project. ### [.NET CLI](#tab/dotnet-cli) @@ -32,7 +32,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac ### Add Azure Storage resource -In your app host project, call to add and return an Azure Storage resource builder. +In your AppHost project, call to add and return an Azure Storage resource builder. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -48,7 +48,7 @@ var storage = builder.AddAzureStorage("storage"); // After adding all resources, run the app... ``` -When you add an `AzureStorageResource` to the app host, it exposes other useful APIs to add Azure Blob, Queue, and Table storage resources. In other words, you must add an `AzureStorageResource` before adding any of the other storage resources. +When you add an `AzureStorageResource` to the AppHost, it exposes other useful APIs to add Azure Blob, Queue, and Table storage resources. In other words, you must add an `AzureStorageResource` before adding any of the other storage resources. > [!IMPORTANT] > When you call , it implicitly calls —which adds support for generating Azure resources dynamically during app startup. The app must configure the appropriate subscription and location. For more information, see [Local provisioning: Configuration](../../azure/local-provisioning.md#configuration). @@ -80,7 +80,7 @@ builder.AddProject() For more information on treating Azure Storage resources as existing resources, see [Use existing Azure resources](../../azure/integrations-overview.md#use-existing-azure-resources). > [!NOTE] -> Alternatively, instead of representing an Azure Storage account resource, you can add a connection string to the app host. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). +> Alternatively, instead of representing an Azure Storage account resource, you can add a connection string to the AppHost. This approach is weakly-typed, and doesn't work with role assignments or infrastructure customizations. For more information, see [Add existing Azure resources with connection strings](../../azure/integrations-overview.md#add-existing-azure-resources-with-connection-strings). ### Add Azure Storage emulator resource @@ -95,7 +95,7 @@ var storage = builder.AddAzureStorage("storage") // After adding all resources, run the app... ``` -When you call `RunAsEmulator`, it configures your storage resources to run locally using an emulator. The emulator in this case is [Azurite](/azure/storage/common/storage-use-azurite). The Azurite open-source emulator provides a free local environment for testing your Azure Blob, Queue Storage, and Table Storage apps and it's a perfect companion to the .NET Aspire Azure hosting integration. Azurite isn't installed, instead, it's accessible to .NET Aspire as a container. When you add a container to the app host, as shown in the preceding example with the `mcr.microsoft.com/azure-storage/azurite` image, it creates and starts the container when the app host starts. For more information, see [Container resource lifecycle](../../fundamentals/orchestrate-resources.md#container-resource-lifecycle). +When you call `RunAsEmulator`, it configures your storage resources to run locally using an emulator. The emulator in this case is [Azurite](/azure/storage/common/storage-use-azurite). The Azurite open-source emulator provides a free local environment for testing your Azure Blob, Queue Storage, and Table Storage apps and it's a perfect companion to the .NET Aspire Azure hosting integration. Azurite isn't installed, instead, it's accessible to .NET Aspire as a container. When you add a container to the AppHost, as shown in the preceding example with the `mcr.microsoft.com/azure-storage/azurite` image, it creates and starts the container when the AppHost starts. For more information, see [Container resource lifecycle](../../fundamentals/orchestrate-resources.md#container-resource-lifecycle). #### Configure Azurite container @@ -189,18 +189,18 @@ var storage = builder.AddAzureStorage("storage").RunAsEmulator( [!INCLUDE [data-bind-mount-vs-volumes](../../includes/data-bind-mount-vs-volumes.md)] -Data bind mounts rely on the host machine's filesystem to persist the Azurite data across container restarts. The data bind mount is mounted at the `../Azurite/Data` path on the host machine relative to the app host directory () in the Azurite container. For more information on data bind mounts, see [Docker docs: Bind mounts](https://docs.docker.com/engine/storage/bind-mounts). +Data bind mounts rely on the host machine's filesystem to persist the Azurite data across container restarts. The data bind mount is mounted at the `../Azurite/Data` path on the host machine relative to the AppHost directory () in the Azurite container. For more information on data bind mounts, see [Docker docs: Bind mounts](https://docs.docker.com/engine/storage/bind-mounts). ### Connect to storage resources -When the .NET Aspire app host runs, the storage resources can be accessed by external tools, such as the [Azure Storage Explorer](https://azure.microsoft.com/features/storage-explorer/). If your storage resource is running locally using Azurite, it will automatically be picked up by the Azure Storage Explorer. +When the .NET Aspire AppHost runs, the storage resources can be accessed by external tools, such as the [Azure Storage Explorer](https://azure.microsoft.com/features/storage-explorer/). If your storage resource is running locally using Azurite, it will automatically be picked up by the Azure Storage Explorer. > [!NOTE] > The Azure Storage Explorer discovers Azurite storage resources assuming the default ports are used. If you've [configured the Azurite container to use different ports](#configure-azurite-container-ports), you'll need to configure the Azure Storage Explorer to connect to the correct ports. To connect to the storage resource from Azure Storage Explorer, follow these steps: -1. Run the .NET Aspire app host. +1. Run the .NET Aspire AppHost. 1. Open the Azure Storage Explorer. 1. View the **Explorer** pane. 1. Select the **Refresh all** link to refresh the list of storage accounts. diff --git a/docs/storage/includes/storage-connections.md b/docs/storage/includes/storage-connections.md index 28f1d8db80..13b65a7966 100644 --- a/docs/storage/includes/storage-connections.md +++ b/docs/storage/includes/storage-connections.md @@ -4,7 +4,7 @@ ms.topic: include ### Connect to an existing Azure Storage account -You might have an existing Azure Storage account that you want to connect to. Instead of representing a new Azure Storage resource, you can add a connection string to the app host. To add a connection to an existing Azure Storage account, call the method: +You might have an existing Azure Storage account that you want to connect to. Instead of representing a new Azure Storage resource, you can add a connection string to the AppHost. To add a connection to an existing Azure Storage account, call the method: ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -19,7 +19,7 @@ builder.AddProject("web") [!INCLUDE [connection-strings-alert](../../includes/connection-strings-alert.md)] -The connection string is configured in the app host's configuration, typically under [User Secrets](/aspnet/core/security/app-secrets), under the `ConnectionStrings` section. The app host injects this connection string as an environment variable into all dependent resources, for example: +The connection string is configured in the AppHost's configuration, typically under [User Secrets](/aspnet/core/security/app-secrets), under the `ConnectionStrings` section. The AppHost injects this connection string as an environment variable into all dependent resources, for example: ```json { @@ -33,14 +33,14 @@ The dependent resource can access the injected connection string by calling the ### Connect to storage resources -When the .NET Aspire app host runs, the storage resources can be accessed by external tools, such as the [Azure Storage Explorer](https://azure.microsoft.com/features/storage-explorer/). If your storage resource is running locally using Azurite, it will automatically be picked up by the Azure Storage Explorer. +When the .NET Aspire AppHost runs, the storage resources can be accessed by external tools, such as the [Azure Storage Explorer](https://azure.microsoft.com/features/storage-explorer/). If your storage resource is running locally using Azurite, it will automatically be picked up by the Azure Storage Explorer. > [!NOTE] > The Azure Storage Explorer discovers Azurite storage resources assuming the default ports are used. If you've [configured the Azurite container to use different ports](#configure-azurite-container-ports), you'll need to configure the Azure Storage Explorer to connect to the correct ports. To connect to the storage resource from Azure Storage Explorer, follow these steps: -1. Run the .NET Aspire app host. +1. Run the .NET Aspire AppHost. 1. Open the Azure Storage Explorer. 1. View the **Explorer** pane. 1. Select the **Refresh all** link to refresh the list of storage accounts. diff --git a/docs/storage/includes/storage-emulator.md b/docs/storage/includes/storage-emulator.md index 52ef95bdbe..6799b0023e 100644 --- a/docs/storage/includes/storage-emulator.md +++ b/docs/storage/includes/storage-emulator.md @@ -15,7 +15,7 @@ var storage = builder.AddAzureStorage("storage") // After adding all resources, run the app... ``` -When you call `RunAsEmulator`, it configures your storage resources to run locally using an emulator. The emulator in this case is [Azurite](/azure/storage/common/storage-use-azurite). The Azurite open-source emulator provides a free local environment for testing your Azure Blob, Queue Storage, and Table Storage apps and it's a perfect companion to the .NET Aspire Azure hosting integration. Azurite isn't installed; instead, it's accessible to .NET Aspire as a container. When you add a container to the app host, as shown in the preceding example with the `mcr.microsoft.com/azure-storage/azurite` image, it creates and starts the container when the app host starts. For more information, see [Container resource lifecycle](../../fundamentals/orchestrate-resources.md#container-resource-lifecycle). +When you call `RunAsEmulator`, it configures your storage resources to run locally using an emulator. The emulator in this case is [Azurite](/azure/storage/common/storage-use-azurite). The Azurite open-source emulator provides a free local environment for testing your Azure Blob, Queue Storage, and Table Storage apps and it's a perfect companion to the .NET Aspire Azure hosting integration. Azurite isn't installed; instead, it's accessible to .NET Aspire as a container. When you add a container to the AppHost, as shown in the preceding example with the `mcr.microsoft.com/azure-storage/azurite` image, it creates and starts the container when the AppHost starts. For more information, see [Container resource lifecycle](../../fundamentals/orchestrate-resources.md#container-resource-lifecycle). #### Configure Azurite container @@ -109,4 +109,4 @@ var storage = builder.AddAzureStorage("storage").RunAsEmulator( [!INCLUDE [data-bind-mount-vs-volumes](../../includes/data-bind-mount-vs-volumes.md)] -Data bind mounts rely on the host machine's filesystem to persist the Azurite data across container restarts. The data bind mount is mounted at the `../Azurite/Data` path on the host machine relative to the app host directory () in the Azurite container. For more information on data bind mounts, see [Docker docs: Bind mounts](https://docs.docker.com/engine/storage/bind-mounts). +Data bind mounts rely on the host machine's filesystem to persist the Azurite data across container restarts. The data bind mount is mounted at the `../Azurite/Data` path on the host machine relative to the AppHost directory () in the Azurite container. For more information on data bind mounts, see [Docker docs: Bind mounts](https://docs.docker.com/engine/storage/bind-mounts). diff --git a/docs/testing/accessing-resources.md b/docs/testing/accessing-resources.md index 96efe2602a..934ea46bb8 100644 --- a/docs/testing/accessing-resources.md +++ b/docs/testing/accessing-resources.md @@ -1,6 +1,6 @@ --- title: Access resources in .NET Aspire tests -description: Learn how to access the resources from the .NET Aspire app host in your tests. +description: Learn how to access the resources from the .NET Aspire AppHost in your tests. ms.date: 02/24/2025 zone_pivot_groups: unit-testing-framework ms.custom: sfi-ropc-nochange @@ -8,11 +8,11 @@ ms.custom: sfi-ropc-nochange # Access resources in .NET Aspire tests -In this article, you learn how to access the resources from the .NET Aspire app host in your tests. The app host represents the full application environment and contains all the resources that are available to the application. When writing functional or integration tests with .NET Aspire, you might need to access these resources to verify the behavior of your application. +In this article, you learn how to access the resources from the .NET Aspire AppHost in your tests. The AppHost represents the full application environment and contains all the resources that are available to the application. When writing functional or integration tests with .NET Aspire, you might need to access these resources to verify the behavior of your application. ## Access HTTP resources -To access an HTTP resource, use the to request and receive responses. The and the both provide a method that's used to create an `HttpClient` instance for a specific resource, based on the resource name from the app host. This method also takes an optional `endpointName` parameter, so if the resource has multiple endpoints, you can specify which one to use. +To access an HTTP resource, use the to request and receive responses. The and the both provide a method that's used to create an `HttpClient` instance for a specific resource, based on the resource name from the AppHost. This method also takes an optional `endpointName` parameter, so if the resource has multiple endpoints, you can specify which one to use. ## Access other resources @@ -48,4 +48,4 @@ This resource-notification pattern ensures that the resources are available befo ## See also - [Write your first .NET Aspire test](./write-your-first-test.md) -- [Managing the app host in .NET Aspire tests](./manage-app-host.md) +- [Managing the AppHost in .NET Aspire tests](./manage-app-host.md) diff --git a/docs/testing/manage-app-host.md b/docs/testing/manage-app-host.md index 6e604c384b..88e4e48f94 100644 --- a/docs/testing/manage-app-host.md +++ b/docs/testing/manage-app-host.md @@ -1,30 +1,30 @@ --- -title: Manage the app host in .NET Aspire tests -description: Learn how to manage the app host in .NET Aspire tests. +title: Manage the AppHost in .NET Aspire tests +description: Learn how to manage the AppHost in .NET Aspire tests. ms.date: 02/24/2025 zone_pivot_groups: unit-testing-framework --- -# Manage the app host in .NET Aspire tests +# Manage the AppHost in .NET Aspire tests -When writing functional or integration tests with .NET Aspire, managing the [app host](../fundamentals/app-host-overview.md) instance efficiently is crucial. The app host represents the full application environment and can be costly to create and tear down. This article explains how to manage the app host instance in your .NET Aspire tests. +When writing functional or integration tests with .NET Aspire, managing the [AppHost](../fundamentals/app-host-overview.md) instance efficiently is crucial. The AppHost represents the full application environment and can be costly to create and tear down. This article explains how to manage the AppHost instance in your .NET Aspire tests. -For writing tests with .NET Aspire, you use the [📦 `Aspire.Hosting.Testing`](https://www.nuget.org/packages/Aspire.Hosting.Testing) NuGet package which contains some helper classes to manage the app host instance in your tests. +For writing tests with .NET Aspire, you use the [📦 `Aspire.Hosting.Testing`](https://www.nuget.org/packages/Aspire.Hosting.Testing) NuGet package which contains some helper classes to manage the AppHost instance in your tests. ## Use the `DistributedApplicationTestingBuilder` class -In the [tutorial on writing your first test](./write-your-first-test.md), you were introduced to the class which can be used to create the app host instance: +In the [tutorial on writing your first test](./write-your-first-test.md), you were introduced to the class which can be used to create the AppHost instance: ```csharp var appHost = await DistributedApplicationTestingBuilder .CreateAsync(); ``` -The `DistributedApplicationTestingBuilder.CreateAsync` method takes the app host project type as a generic parameter to create the app host instance. While this method is executed at the start of each test, it's more efficient to create the app host instance once and share it across tests as the test suite grows. +The `DistributedApplicationTestingBuilder.CreateAsync` method takes the AppHost project type as a generic parameter to create the AppHost instance. While this method is executed at the start of each test, it's more efficient to create the AppHost instance once and share it across tests as the test suite grows. :::zone pivot="xunit" -With xUnit, you implement the [IAsyncLifetime](https://github.com/xunit/xunit/blob/master/src/xunit.core/IAsyncLifetime.cs) interface on the test class to support asynchronous initialization and disposal of the app host instance. The `InitializeAsync` method is used to create the app host instance before the tests are run and the `DisposeAsync` method disposes the app host once the tests are completed. +With xUnit, you implement the [IAsyncLifetime](https://github.com/xunit/xunit/blob/master/src/xunit.core/IAsyncLifetime.cs) interface on the test class to support asynchronous initialization and disposal of the AppHost instance. The `InitializeAsync` method is used to create the AppHost instance before the tests are run and the `DisposeAsync` method disposes the AppHost once the tests are completed. ```csharp public class WebTests : IAsyncLifetime @@ -52,7 +52,7 @@ public class WebTests : IAsyncLifetime :::zone-end :::zone pivot="mstest" -With MSTest, you use the and on static methods of the test class to provide the initialization and cleanup of the app host instance. The `ClassInitialize` method is used to create the app host instance before the tests are run and the `ClassCleanup` method disposes the app host instance once the tests are completed. +With MSTest, you use the and on static methods of the test class to provide the initialization and cleanup of the AppHost instance. The `ClassInitialize` method is used to create the AppHost instance before the tests are run and the `ClassCleanup` method disposes the AppHost instance once the tests are completed. ```csharp [TestClass] @@ -83,7 +83,7 @@ public class WebTests :::zone-end :::zone pivot="nunit" -With NUnit, you use the [OneTimeSetUp](https://docs.nunit.org/articles/nunit/writing-tests/attributes/onetimesetup.html) and [OneTimeTearDown](https://docs.nunit.org/articles/nunit/writing-tests/attributes/onetimeteardown.html) attributes on methods of the test class to provide the setup and teardown of the app host instance. The `OneTimeSetUp` method is used to create the app host instance before the tests are run and the `OneTimeTearDown` method disposes the app host instance once the tests are completed. +With NUnit, you use the [OneTimeSetUp](https://docs.nunit.org/articles/nunit/writing-tests/attributes/onetimesetup.html) and [OneTimeTearDown](https://docs.nunit.org/articles/nunit/writing-tests/attributes/onetimeteardown.html) attributes on methods of the test class to provide the setup and teardown of the AppHost instance. The `OneTimeSetUp` method is used to create the AppHost instance before the tests are run and the `OneTimeTearDown` method disposes the AppHost instance once the tests are completed. ```csharp public class WebTests @@ -112,11 +112,11 @@ public class WebTests :::zone-end -By capturing the app host in a field when the test run is started, you can access it in each test without the need to recreate it, decreasing the time it takes to run the tests. Then, when the test run completes, the app host is disposed, which cleans up any resources that were created during the test run, such as containers. +By capturing the AppHost in a field when the test run is started, you can access it in each test without the need to recreate it, decreasing the time it takes to run the tests. Then, when the test run completes, the AppHost is disposed, which cleans up any resources that were created during the test run, such as containers. -## Pass arguments to your app host +## Pass arguments to your AppHost -You can access the arguments from your app host with the `args` parameter. Arguments are also passed to [.NET's configuration system](/dotnet/core/extensions/configuration), so you can override many configuration settings this way. In the following example, you override the [environment](/aspnet/core/fundamentals/environments) by specifying it as a command line option: +You can access the arguments from your AppHost with the `args` parameter. Arguments are also passed to [.NET's configuration system](/dotnet/core/extensions/configuration), so you can override many configuration settings this way. In the following example, you override the [environment](/aspnet/core/fundamentals/environments) by specifying it as a command line option: ```csharp var builder = await DistributedApplicationTestingBuilder @@ -126,9 +126,9 @@ var builder = await DistributedApplicationTestingBuilder ]); ``` -Other arguments can be passed to your app host `Program` and made available in your app host. In the next example, you pass an argument to the app host and use it to control whether you add data volumes to a Postgres instance. +Other arguments can be passed to your AppHost `Program` and made available in your AppHost. In the next example, you pass an argument to the AppHost and use it to control whether you add data volumes to a Postgres instance. -In the app host `Program`, you use configuration to support enabling or disabling volumes: +In the AppHost `Program`, you use configuration to support enabling or disabling volumes: ```csharp var postgres = builder.AddPostgres("postgres1"); @@ -138,7 +138,7 @@ if (builder.Configuration.GetValue("UseVolumes", true)) } ``` -In test code, you pass `"UseVolumes=false"` in the `args` to the app host: +In test code, you pass `"UseVolumes=false"` in the `args` to the AppHost: ```csharp public async Task DisableVolumesFromTest() @@ -159,7 +159,7 @@ public async Task DisableVolumesFromTest() ## Use the `DistributedApplicationFactory` class -While the `DistributedApplicationTestingBuilder` class is useful for many scenarios, there might be situations where you want more control over starting the app host, such as executing code before the builder is created or after the app host is built. In these cases, you implement your own version of the class. This is what the `DistributedApplicationTestingBuilder` uses internally. +While the `DistributedApplicationTestingBuilder` class is useful for many scenarios, there might be situations where you want more control over starting the AppHost, such as executing code before the builder is created or after the AppHost is built. In these cases, you implement your own version of the class. This is what the `DistributedApplicationTestingBuilder` uses internally. ```csharp public class TestingAspireAppHost() @@ -169,13 +169,13 @@ public class TestingAspireAppHost() } ``` -The constructor requires the type of the app host project reference as a parameter. Optionally, you can provide arguments to the underlying host application builder. These arguments control how the app host starts and provide values to the args variable used by the _Program.cs_ file to start the app host instance. +The constructor requires the type of the AppHost project reference as a parameter. Optionally, you can provide arguments to the underlying host application builder. These arguments control how the AppHost starts and provide values to the args variable used by the _Program.cs_ file to start the AppHost instance. ### Lifecycle methods -The `DistributionApplicationFactory` class provides several lifecycle methods that can be overridden to provide custom behavior throughout the preparation and creation of the app host. The available methods are `OnBuilderCreating`, `OnBuilderCreated`, `OnBuilding`, and `OnBuilt`. +The `DistributionApplicationFactory` class provides several lifecycle methods that can be overridden to provide custom behavior throughout the preparation and creation of the AppHost. The available methods are `OnBuilderCreating`, `OnBuilderCreated`, `OnBuilding`, and `OnBuilt`. -For example, we can use the `OnBuilderCreating` method to set configuration, such as the subscription and resource group information for Azure, before the app host is created and any dependent Azure resources are provisioned, resulting in our tests using the correct Azure environment. +For example, we can use the `OnBuilderCreating` method to set configuration, such as the subscription and resource group information for Azure, before the AppHost is created and any dependent Azure resources are provisioned, resulting in our tests using the correct Azure environment. ```csharp public class TestingAspireAppHost() : DistributedApplicationFactory(typeof(Projects.AspireApp_AppHost)) @@ -192,7 +192,7 @@ public class TestingAspireAppHost() : DistributedApplicationFactory(typeof(Proje Because of the order of precedence in the .NET configuration system, the environment variables will be used over anything in the _appsettings.json_ or _secrets.json_ file. -Another scenario you might want to use in the lifecycle is to configure the services used by the app host. In the following example, consider a scenario where you override the `OnBuilderCreated` API to add resilience to the `HttpClient`: +Another scenario you might want to use in the lifecycle is to configure the services used by the AppHost. In the following example, consider a scenario where you override the `OnBuilderCreated` API to add resilience to the `HttpClient`: ```csharp protected override void OnBuilderCreated( diff --git a/docs/testing/overview.md b/docs/testing/overview.md index c9077b5708..84728fea8a 100644 --- a/docs/testing/overview.md +++ b/docs/testing/overview.md @@ -6,7 +6,7 @@ ms.date: 03/11/2025 # .NET Aspire testing overview -.NET Aspire supports automated testing of your application through the [📦 Aspire.Hosting.Testing](https://www.nuget.org/packages/Aspire.Hosting.Testing) NuGet package. This package provides the class, which is used to create a test host for your application. The testing builder launches your app host project in a background thread and manages its lifecycle, allowing you to control and manipulate the application and its resources through or instances. +.NET Aspire supports automated testing of your application through the [📦 Aspire.Hosting.Testing](https://www.nuget.org/packages/Aspire.Hosting.Testing) NuGet package. This package provides the class, which is used to create a test host for your application. The testing builder launches your AppHost project in a background thread and manages its lifecycle, allowing you to control and manipulate the application and its resources through or instances. By default, the testing builder disables the dashboard and randomizes the ports of proxied resources to enable multiple instances of your application to run concurrently. Once your test completes, disposing of the application or testing builder cleans up your app resources. @@ -14,18 +14,18 @@ To get started writing your first integration test with .NET Aspire, see the [Wr ## Testing .NET Aspire solutions -.NET Aspire's testing capabilities are designed specifically for closed-box integration testing of your entire distributed application. Unlike unit tests or open-box integration tests, which typically run individual components in isolation, .NET Aspire tests launch your complete solution (the app host and all its resources) as separate processes, closely simulating real-world scenarios. +.NET Aspire's testing capabilities are designed specifically for closed-box integration testing of your entire distributed application. Unlike unit tests or open-box integration tests, which typically run individual components in isolation, .NET Aspire tests launch your complete solution (the AppHost and all its resources) as separate processes, closely simulating real-world scenarios. -Consider the following diagram that shows how the .NET Aspire testing project starts the app host, which then starts the application and its resources: +Consider the following diagram that shows how the .NET Aspire testing project starts the AppHost, which then starts the application and its resources: :::image type="content" source="media/testing-diagram-thumb.png" alt-text=".NET Aspire testing diagram" lightbox="media/testing-diagram.png"::: -1. The **test project** starts the app host. -1. The **app host** process starts. -1. The **app host** runs the `Database`, `API`, and `Frontend` applications. +1. The **test project** starts the AppHost. +1. The **AppHost** process starts. +1. The **AppHost** runs the `Database`, `API`, and `Frontend` applications. 1. The **test project** sends an HTTP request to the `Frontend` application. -The diagram illustrates that the **test project** starts the app host, which then orchestrates all dependent app resources—regardless of their type. The test project is able to send an HTTP request to the `Frontend` app, which depends on an `API` app, and the `API` app depends on a `Database`. A successful request confirms that the `Frontend` app can communicate with the `API` app, and that the `API` app can successfully get data from the `Database`. For more information on seeing this approach in action, see the [Write your first .NET Aspire test](write-your-first-test.md) article. +The diagram illustrates that the **test project** starts the AppHost, which then orchestrates all dependent app resources—regardless of their type. The test project is able to send an HTTP request to the `Frontend` app, which depends on an `API` app, and the `API` app depends on a `Database`. A successful request confirms that the `Frontend` app can communicate with the `API` app, and that the `API` app can successfully get data from the `Database`. For more information on seeing this approach in action, see the [Write your first .NET Aspire test](write-your-first-test.md) article. > [!IMPORTANT] > .NET Aspire testing doesn't enable scenarios for mocking, substituting, or replacing services in dependency injection—as the tests run in a separate process. @@ -70,5 +70,5 @@ var builder = await DistributedApplicationTestingBuilder ## See also - [Write your first .NET Aspire test](./write-your-first-test.md) -- [Managing the app host in .NET Aspire tests](./manage-app-host.md) +- [Managing the AppHost in .NET Aspire tests](./manage-app-host.md) - [Access resources in .NET Aspire tests](./accessing-resources.md) diff --git a/docs/testing/write-your-first-test.md b/docs/testing/write-your-first-test.md index dd4a3e206d..803a96ed98 100644 --- a/docs/testing/write-your-first-test.md +++ b/docs/testing/write-your-first-test.md @@ -9,7 +9,7 @@ zone_pivot_groups: unit-testing-framework In this article, you learn how to create a test project, write tests, and run them for your .NET Aspire solutions. The tests in this article aren't unit tests, but rather functional or integration tests. .NET Aspire includes several variations of [testing project templates](../fundamentals/setup-tooling.md#net-aspire-templates) that you can use to test your .NET Aspire resource dependencies—and their communications. The testing project templates are available for MSTest, NUnit, and xUnit testing frameworks and include a sample test that you can use as a starting point for your tests. -The .NET Aspire test project templates rely on the [📦 Aspire.Hosting.Testing](https://www.nuget.org/packages/Aspire.Hosting.Testing) NuGet package. This package exposes the class, which is used to create a test host for your distributed application. The distributed application testing builder launches your app host project with instrumentation hooks so that you can access and manipulate the host at various stages of its lifecyle. In particular, provides you access to and class to create and start the [app host](../fundamentals/app-host-overview.md). +The .NET Aspire test project templates rely on the [📦 Aspire.Hosting.Testing](https://www.nuget.org/packages/Aspire.Hosting.Testing) NuGet package. This package exposes the class, which is used to create a test host for your distributed application. The distributed application testing builder launches your AppHost project with instrumentation hooks so that you can access and manipulate the host at various stages of its lifecyle. In particular, provides you access to and class to create and start the [AppHost](../fundamentals/app-host-overview.md). ## Create a test project @@ -41,7 +41,7 @@ For more information, see the .NET CLI [dotnet new](/dotnet/core/tools/dotnet-ne ## Explore the test project -The following example test project was created as part of the **.NET Aspire Starter Application** template. If you're unfamiliar with it, see [Quickstart: Build your first .NET Aspire project](../get-started/build-your-first-aspire-app.md). The .NET Aspire test project takes a project reference dependency on the target app host. Consider the template project: +The following example test project was created as part of the **.NET Aspire Starter Application** template. If you're unfamiliar with it, see [Quickstart: Build your first .NET Aspire project](../get-started/build-your-first-aspire-app.md). The .NET Aspire test project takes a project reference dependency on the target AppHost. Consider the template project: :::zone pivot="xunit" @@ -63,7 +63,7 @@ The preceding project file is fairly standard. There's a `PackageReference` to t The template test project includes a `IntegrationTest1` class with a single test. The test verifies the following scenario: -- The app host is successfully created and started. +- The AppHost is successfully created and started. - The `webfrontend` resource is available and running. - An HTTP request can be made to the `webfrontend` resource and returns a successful response (HTTP 200 OK). @@ -87,8 +87,8 @@ Consider the following test class: The preceding code: -- Relies on the API to asynchronously create the app host. - - The `appHost` is an instance of `IDistributedApplicationTestingBuilder` that represents the app host. +- Relies on the API to asynchronously create the AppHost. + - The `appHost` is an instance of `IDistributedApplicationTestingBuilder` that represents the AppHost. - The `appHost` instance has its service collection configured with the standard HTTP resilience handler. For more information, see [Build resilient HTTP apps: Key development patterns](/dotnet/core/resilience/http-resilience). - The `appHost` has its method invoked, which returns the `DistributedApplication` instance as the `app`. - The `app` has its service provider get the instance. @@ -120,7 +120,7 @@ To further test resources and their expressed dependencies in your .NET Aspire s The preceding code: -- Relies on the API to asynchronously create the app host. +- Relies on the API to asynchronously create the AppHost. - The `builder` instance is used to retrieve an instance named "webfrontend" from the . - The `webfrontend` resource is used to call to retrieve its configured environment variables. - The argument is passed when calling `GetEnvironmentVariableValuesAsync` to specify environment variables that are published to the resource as binding expressions. diff --git a/docs/toc.yml b/docs/toc.yml index 2219f5e787..5bb19136d0 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -41,7 +41,7 @@ items: - name: Architecture overview displayName: aspire architecture,aspire app,aspire apphost,aspire app model href: architecture/overview.md - - name: App host overview + - name: AppHost overview displayName: orchestration,aspire apphost,aspire app,dev-time,inner-loop href: fundamentals/app-host-overview.md - name: Locally orchestrate @@ -55,7 +55,7 @@ items: - name: Python apps in .NET Aspire displayName: python,flask,fastapi href: get-started/build-aspire-apps-with-python.md - - name: App host configuration + - name: AppHost configuration href: app-host/configuration.md - name: Customize resources items: @@ -158,7 +158,7 @@ items: href: testing/overview.md - name: Write your first .NET Aspire test href: testing/write-your-first-test.md - - name: Managing the app host + - name: Managing the AppHost href: testing/manage-app-host.md - name: Accessing resources in tests href: testing/accessing-resources.md diff --git a/docs/troubleshooting/allow-unsecure-transport.md b/docs/troubleshooting/allow-unsecure-transport.md index 76b5030f58..4a73d2bf1a 100644 --- a/docs/troubleshooting/allow-unsecure-transport.md +++ b/docs/troubleshooting/allow-unsecure-transport.md @@ -6,7 +6,7 @@ ms.date: 04/15/2025 # Allow unsecure transport in .NET Aspire -Starting with .NET Aspire preview 5, the app host will crash if an `applicationUrl` is configured with an unsecure transport (non-TLS `http`) protocol. This is a security feature to prevent accidental exposure of sensitive data. However, there are scenarios where you might need to allow unsecure transport. This article explains how to allow unsecure transport in .NET Aspire projects. +Starting with .NET Aspire preview 5, the AppHost will crash if an `applicationUrl` is configured with an unsecure transport (non-TLS `http`) protocol. This is a security feature to prevent accidental exposure of sensitive data. However, there are scenarios where you might need to allow unsecure transport. This article explains how to allow unsecure transport in .NET Aspire projects. ## Symptoms @@ -21,7 +21,7 @@ This configuration is commonly set in the launch profile. ## How to allow unsecure transport -To allow an unsecure transport in .NET Aspire, set the `ASPIRE_ALLOW_UNSECURED_TRANSPORT` environment variable to `true`. This environment variable is used to control the behavior of the app host when an `applicationUrl` is configured with an insecure transport protocol: +To allow an unsecure transport in .NET Aspire, set the `ASPIRE_ALLOW_UNSECURED_TRANSPORT` environment variable to `true`. This environment variable is used to control the behavior of the AppHost when an `applicationUrl` is configured with an insecure transport protocol: ## [Unix](#tab/unix) diff --git a/docs/whats-new/dotnet-aspire-9.1.md b/docs/whats-new/dotnet-aspire-9.1.md index e1409537b6..c223d8880c 100644 --- a/docs/whats-new/dotnet-aspire-9.1.md +++ b/docs/whats-new/dotnet-aspire-9.1.md @@ -27,7 +27,7 @@ Whether you're new to .NET Aspire or have been with us since the preview, it's i Moving between minor releases of .NET Aspire is simple: -1. In your app host project file (that is, _MyApp.AppHost.csproj_), update the [📦 Aspire.AppHost.Sdk](https://www.nuget.org/packages/Aspire.AppHost.Sdk) NuGet package to version `9.1.0`: +1. In your AppHost project file (that is, _MyApp.AppHost.csproj_), update the [📦 Aspire.AppHost.Sdk](https://www.nuget.org/packages/Aspire.AppHost.Sdk) NuGet package to version `9.1.0`: ```xml @@ -51,7 +51,7 @@ Moving between minor releases of .NET Aspire is simple: > [!NOTE] > The `dotnet new update` command updates all of your templates to the latest version. -If your app host project file doesn't have the `Aspire.AppHost.Sdk` reference, you might still be using .NET Aspire 8. To upgrade to 9.0, you can follow [the documentation from last release](../get-started/upgrade-to-aspire-9.md). +If your AppHost project file doesn't have the `Aspire.AppHost.Sdk` reference, you might still be using .NET Aspire 8. To upgrade to 9.0, you can follow [the documentation from last release](../get-started/upgrade-to-aspire-9.md). ## 🌱 Improved onboarding experience @@ -109,7 +109,7 @@ For more information, see [.NET Aspire dashboard: Resources page](../fundamental You can now set the `ASPIRE_DASHBOARD_CORS_ALLOWED_ORIGINS` environment variable to allow the dashboard to receive telemetry from other browser apps, such as if you have resources running on custom localhost domains. -For more information, see [.NET Aspire app host: Dashboard configuration](../app-host/configuration.md#dashboard). +For more information, see [.NET Aspire AppHost: Dashboard configuration](../app-host/configuration.md#dashboard). ### 🪵 Flexibility with console logs @@ -137,7 +137,7 @@ In .NET Aspire 9.1, several improvements to streamline your local development ex ### ▶️ Start resources on demand -You can now tell resources not to start with the rest of your app by using on the resource in your app host. Then, you can start it whenever you're ready from inside the dashboard. +You can now tell resources not to start with the rest of your app by using on the resource in your AppHost. Then, you can start it whenever you're ready from inside the dashboard. For more information, see [Configure explicit resource start](../fundamentals/orchestrate-resources.md#configure-explicit-resource-start). @@ -153,9 +153,9 @@ In 9.1, we addressed a persistent issue where Docker networks created by .NET As ### ✅ Socket address issues fixed -Several users reported issues ([#6693](https://github.com/dotnet/aspire/issues/6693), [#6704](https://github.com/dotnet/aspire/issues/6704), [#7095](https://github.com/dotnet/aspire/issues/7095)) with restarting the .NET Aspire app host, including reconciliation errors and "address already in use" messages. +Several users reported issues ([#6693](https://github.com/dotnet/aspire/issues/6693), [#6704](https://github.com/dotnet/aspire/issues/6704), [#7095](https://github.com/dotnet/aspire/issues/7095)) with restarting the .NET Aspire AppHost, including reconciliation errors and "address already in use" messages. -This release introduces a more robust approach to managing socket addresses, ensuring only one instance of each address is used at a time. Additionally, improvements were made to ensure proper project restarts and resource releases, preventing hanging issues. These changes enhance the stability and reliability of the app host, especially during development and testing. +This release introduces a more robust approach to managing socket addresses, ensuring only one instance of each address is used at a time. Additionally, improvements were made to ensure proper project restarts and resource releases, preventing hanging issues. These changes enhance the stability and reliability of the AppHost, especially during development and testing. ## 🔌 Integration updates @@ -199,9 +199,9 @@ Along with support for the new emulator, Cosmos DB added the following features. Previously, the Cosmos DB integration used access keys and a Key Vault secret to connect to the service. .NET Aspire 9.1 added support for using more secure authentication using managed identities by default. If you need to keep using access key authentication, you can get back to the previous behavior by calling . -##### 💽 Support for modeling Database and Containers in the app host +##### 💽 Support for modeling Database and Containers in the AppHost -You can define a Cosmos DB database and containers in the app host and these resources are available when you run the application in both the emulator and in Azure. This allows you to define these resources up front and no longer need to create them from the application, which might not have permission to create them. +You can define a Cosmos DB database and containers in the AppHost and these resources are available when you run the application in both the emulator and in Azure. This allows you to define these resources up front and no longer need to create them from the application, which might not have permission to create them. For example API usage to add database and containers, see the following related articles: @@ -246,7 +246,7 @@ For more information using Azure Functions with .NET Aspire, see [.NET Aspire Az #### 🚚 Service Bus and Event Hubs -Similar to Cosmos DB, the Service Bus and Event Hubs integrations now allow you to define Azure Service Bus queues, topics, subscriptions, and Azure Event Hubs instances and consumer groups directly in your app host code. This enhancement simplifies your application logic by enabling the creation and management of these resources outside the application itself. +Similar to Cosmos DB, the Service Bus and Event Hubs integrations now allow you to define Azure Service Bus queues, topics, subscriptions, and Azure Event Hubs instances and consumer groups directly in your AppHost code. This enhancement simplifies your application logic by enabling the creation and management of these resources outside the application itself. For more information, see the following updated articles: @@ -300,15 +300,15 @@ The [📦 Aspire.Hosting.AWS](https://www.nuget.org/packages/Aspire.Hosting.AWS) ## 🧪 Testing in .NET Aspire -.NET Aspire 9.1 simplifies writing cross-functional integration tests with a robust approach. The app host allows you to create, evaluate, and manage containerized environments seamlessly within a test run. This functionality supports popular testing frameworks like xUnit, NUnit, and MSTest, enhancing your testing capabilities and efficiency. +.NET Aspire 9.1 simplifies writing cross-functional integration tests with a robust approach. The AppHost allows you to create, evaluate, and manage containerized environments seamlessly within a test run. This functionality supports popular testing frameworks like xUnit, NUnit, and MSTest, enhancing your testing capabilities and efficiency. -Now, you're able to disable port randomization or enable the [dashboard](../fundamentals/dashboard/overview.md). For more information, see [.NET Aspire testing overview](../testing/overview.md). Additionally, you can now [Pass arguments to your app host](../testing/manage-app-host.md#pass-arguments-to-your-app-host). +Now, you're able to disable port randomization or enable the [dashboard](../fundamentals/dashboard/overview.md). For more information, see [.NET Aspire testing overview](../testing/overview.md). Additionally, you can now [Pass arguments to your AppHost](../testing/manage-app-host.md#pass-arguments-to-your-apphost). Some of these enhancements were introduced as a result of stability issues that were reported, such as [.NET Aspire GitHub issue #6678](https://github.com/dotnet/aspire/issues/6678)—where some resources failed to start do to "address in use" errors. ## 🚀 Deployment -Significant improvements to the Azure Container Apps (ACA) deployment process are included in .NET Aspire 9.1, enhancing both the `azd` CLI and app host options. One of the most requested features—support for deploying `npm` applications to ACA—is now implemented. This new capability allows `npm` apps to be deployed to ACA just like other resources, streamlining the deployment process and providing greater flexibility for developers. +Significant improvements to the Azure Container Apps (ACA) deployment process are included in .NET Aspire 9.1, enhancing both the `azd` CLI and AppHost options. One of the most requested features—support for deploying `npm` applications to ACA—is now implemented. This new capability allows `npm` apps to be deployed to ACA just like other resources, streamlining the deployment process and providing greater flexibility for developers. We recognize there's more work to be done in the area of deployment. Future releases will continue to address these opportunities for improvement. For more information on deploying .NET Aspire to ACA, see [Deploy a .NET Aspire project to Azure Container Apps](../deployment/azure/aca-deployment.md). diff --git a/docs/whats-new/dotnet-aspire-9.2.md b/docs/whats-new/dotnet-aspire-9.2.md index 960cd292f9..727c35cfcf 100644 --- a/docs/whats-new/dotnet-aspire-9.2.md +++ b/docs/whats-new/dotnet-aspire-9.2.md @@ -25,7 +25,7 @@ It's important to note that .NET Aspire releases out-of-band from .NET releases. Moving between minor releases of .NET Aspire is simple: -1. In your app host project file (that is, _MyApp.AppHost.csproj_), update the [📦 Aspire.AppHost.Sdk](https://www.nuget.org/packages/Aspire.AppHost.Sdk) NuGet package to version `9.2.0`: +1. In your AppHost project file (that is, _MyApp.AppHost.csproj_), update the [📦 Aspire.AppHost.Sdk](https://www.nuget.org/packages/Aspire.AppHost.Sdk) NuGet package to version `9.2.0`: ```diff @@ -62,17 +62,17 @@ Moving between minor releases of .NET Aspire is simple: > [!IMPORTANT] > The `dotnet new update` command updates all of your templates to the latest version. -If your app host project file doesn't have the `Aspire.AppHost.Sdk` reference, you might still be using .NET Aspire 8. To upgrade to 9.0, follow [the upgrade guide](../get-started/upgrade-to-aspire-9.md). +If your AppHost project file doesn't have the `Aspire.AppHost.Sdk` reference, you might still be using .NET Aspire 8. To upgrade to 9.0, follow [the upgrade guide](../get-started/upgrade-to-aspire-9.md). -## 🖥️ App host enhancements +## 🖥️ AppHost enhancements -The [app host](../fundamentals/app-host-overview.md) is the core of .NET Aspire, providing the local hosting environment for your distributed applications. In .NET Aspire 9.2, we've made several improvements to the app host: +The [AppHost](../fundamentals/app-host-overview.md) is the core of .NET Aspire, providing the local hosting environment for your distributed applications. In .NET Aspire 9.2, we've made several improvements to the AppHost: ### 🚧 Project file changes -The .NET Aspire app host project file no longer requires the `IsAspireHost` property. This property was moved to the `Aspire.AppHost.Sdk` SDK, therefore, you can remove it from your project file. For more information, see [dotnet/aspire issue #8144](https://github.com/dotnet/aspire/pull/8144). +The .NET Aspire AppHost project file no longer requires the `IsAspireHost` property. This property was moved to the `Aspire.AppHost.Sdk` SDK, therefore, you can remove it from your project file. For more information, see [dotnet/aspire issue #8144](https://github.com/dotnet/aspire/pull/8144). ### 🔗 Define custom resource URLs @@ -448,7 +448,7 @@ The following NuGet packages expose preview publishers: > [!IMPORTANT] > The Docker and Kubernetes publishers were contributed by community contributor, [Dave Sekula](https://github.com/Prom3theu5)—a great example of the community stepping up to extend the model. 💜 Thank you, Dave! -To use a publisher, add the corresponding NuGet package to your app host project file and then call the `Add[Name]Publisher()` method in your app host builder. +To use a publisher, add the corresponding NuGet package to your AppHost project file and then call the `Add[Name]Publisher()` method in your AppHost builder. ```csharp builder.AddDockerComposePublisher(); @@ -481,9 +481,9 @@ aspire publish --publisher docker-compose #### Available commands: - `new