diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 69f98fc4d3..27bd228d96 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -843,6 +843,22 @@ { "source_path_from_root": "/docs/diagnostics/aspireazure002.md", "redirect_url": "https://aspire.dev/diagnostics/aspireazure002/" + }, + { + "source_path_from_root": "/docs/fundamentals/health-checks.md", + "redirect_url": "https://aspire.dev/fundamentals/health-checks/" + }, + { + "source_path_from_root": "/docs/fundamentals/service-defaults.md", + "redirect_url": "https://aspire.dev/fundamentals/service-defaults/" + }, + { + "source_path_from_root": "/docs/fundamentals/launch-profiles.md", + "redirect_url": "https://aspire.dev/fundamentals/launch-profiles/" + }, + { + "source_path_from_root": "/docs/service-discovery/overview.md", + "redirect_url": "https://aspire.dev/fundamentals/service-discovery/" } ] } diff --git a/docs/app-host/configuration.md b/docs/app-host/configuration.md index fae32a076d..2df663b392 100644 --- a/docs/app-host/configuration.md +++ b/docs/app-host/configuration.md @@ -44,7 +44,7 @@ The preceding launch settings file: - 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 AppHost. -For more information, see [Aspire and launch profiles](../fundamentals/launch-profiles.md). +For more information, see [Aspire and launch profiles](https://aspire.dev/fundamentals/launch-profiles/). > [!NOTE] > Configuration described on this page is for Aspire AppHost project. To configure the standalone dashboard, see [dashboard configuration](https://aspire.dev/dashboard/configuration/). diff --git a/docs/deployment/aspire-deploy/application-insights.md b/docs/deployment/aspire-deploy/application-insights.md index ac763e15dd..f1656bc41c 100644 --- a/docs/deployment/aspire-deploy/application-insights.md +++ b/docs/deployment/aspire-deploy/application-insights.md @@ -153,7 +153,7 @@ builder.Build().Run(); To make exporting to Azure Monitor simpler, this example uses the Azure Monitor Exporter Repo. This is a wrapper package around the Azure Monitor OpenTelemetry Exporter package that makes it easier to export to Azure Monitor with a set of common defaults. -Add the following package to the `ServiceDefaults` project, so that it will be included in each of the Aspire services. For more information, see [Aspire service defaults](../../fundamentals/service-defaults.md). +Add the following package to the `ServiceDefaults` project, so that it will be included in each of the Aspire services. For more information, see [Aspire service defaults](https://aspire.dev/fundamentals/service-defaults/). ``` xml ("webfrontend") builder.Build().Run(); ``` -References between project resource types result in [service discovery](../service-discovery/overview.md) variables being injected into the referencing project. References to well known reference types such as Redis result in connection strings being injected. +References between project resource types result in [service discovery](https://aspire.dev/fundamentals/service-discovery/) variables being injected into the referencing project. References to well known reference types such as Redis result in connection strings being injected. :::image type="content" source="media/manifest-placeholder-strings.png" lightbox="media/manifest-placeholder-strings.png" alt-text="A diagram showing which resources contribute to which corresponding placeholder strings."::: @@ -920,4 +920,4 @@ When resources as configured as Azure resources, the `azure.bicep.v0` resource t - [Aspire overview](../get-started/aspire-overview.md) - [Aspire orchestration overview](../fundamentals/app-host-overview.md) - [Aspire integrations overview](../fundamentals/integrations-overview.md) -- [Service discovery in Aspire](../service-discovery/overview.md) +- [Service discovery in Aspire](https://aspire.dev/fundamentals/service-discovery/) diff --git a/docs/extensibility/custom-client-integration.md b/docs/extensibility/custom-client-integration.md index cb3c97cdab..b7f60bae38 100644 --- a/docs/extensibility/custom-client-integration.md +++ b/docs/extensibility/custom-client-integration.md @@ -87,7 +87,7 @@ The registration of health checks, and telemetry are described in a bit more det ### Add health checks -[Health checks](../fundamentals/health-checks.md) are a way to monitor the health of an integration. With MailKit, you can check if the connection to the SMTP server is healthy. Add the following code to the `MailKit.Client` project in a file named _MailKitHealthCheck.cs_: +[Health checks](https://aspire.dev/fundamentals/health-checks/) are a way to monitor the health of an integration. With MailKit, you can check if the connection to the SMTP server is healthy. Add the following code to the `MailKit.Client` project in a file named _MailKitHealthCheck.cs_: :::code source="snippets/MailDevResourceAndComponent/MailKit.Client/MailKitHealthCheck.cs"::: diff --git a/docs/extensibility/custom-hosting-integration.md b/docs/extensibility/custom-hosting-integration.md index f52a1665b9..29bcfdb40a 100644 --- a/docs/extensibility/custom-hosting-integration.md +++ b/docs/extensibility/custom-hosting-integration.md @@ -60,7 +60,7 @@ dir Once the project is created, you should see a listing containing the following: - `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.ServiceDefaults`: The [service defaults](https://aspire.dev/fundamentals/service-defaults/) project for use in service-related projects. - `MailDevResource.sln`: The solution file referencing both projects. Verify that the project can build and run successfully by executing the following command: diff --git a/docs/extensibility/dev-tunnels-integration.md b/docs/extensibility/dev-tunnels-integration.md index f98dfbb407..995a0a4f6f 100644 --- a/docs/extensibility/dev-tunnels-integration.md +++ b/docs/extensibility/dev-tunnels-integration.md @@ -98,7 +98,7 @@ The preceding code: ### Service discovery integration -When another resource references a dev tunnel, environment variables are injected using the [Aspire service discovery](../service-discovery/overview.md) configuration format. Use the `WithReference` overloads that accept the `IResourceBuilder` parameter to reference a dev tunnel. This injects environment variables like: +When another resource references a dev tunnel, environment variables are injected using the [Aspire service discovery](https://aspire.dev/fundamentals/service-discovery/) configuration format. Use the `WithReference` overloads that accept the `IResourceBuilder` parameter to reference a dev tunnel. This injects environment variables like: ```env WEB_HTTPS=https://myweb-1234.westeurope.devtunnels.ms/ @@ -180,5 +180,5 @@ Verify that: - [Dev tunnels service documentation](/azure/developer/dev-tunnels/overview) - [Dev tunnels FAQ](/azure/developer/dev-tunnels/faq) -- [Aspire service discovery](../service-discovery/overview.md) +- [Aspire service discovery](https://aspire.dev/fundamentals/service-discovery/) - [Aspire networking overview](../fundamentals/networking-overview.md) diff --git a/docs/extensibility/secure-communication-between-integrations.md b/docs/extensibility/secure-communication-between-integrations.md index 718a89dddb..6511d8275f 100644 --- a/docs/extensibility/secure-communication-between-integrations.md +++ b/docs/extensibility/secure-communication-between-integrations.md @@ -24,7 +24,7 @@ The resulting solution from these previous articles contains the following proje - _MailDev.Hosting_: Contains the custom resource type for the MailDev container. - _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. +- _MailDevResource.ServiceDefaults_: Contains the [default service configurations](https://aspire.dev/fundamentals/service-defaults/) intended for sharing. - _MailKit.Client_: Contains the custom client integration that exposes the MailKit `SmtpClient` through a factory. ## Update the MailDev resource diff --git a/docs/fundamentals/app-host-overview.md b/docs/fundamentals/app-host-overview.md index 95959350c7..5b06d29395 100644 --- a/docs/fundamentals/app-host-overview.md +++ b/docs/fundamentals/app-host-overview.md @@ -194,7 +194,7 @@ builder.AddProject("webfrontend") .WithReference(cache); ``` -The "webfrontend" project resource uses to add a dependency on the "cache" container resource. These dependencies can represent connection strings or [service discovery](../service-discovery/overview.md) information. In the preceding example, an environment variable is _injected_ into the "webfrontend" resource with the name `ConnectionStrings__cache`. This environment variable contains a connection string that the `webfrontend` uses to connect to Redis via the [Aspire Redis integration](https://aspire.dev/integrations/caching/redis/), for example, `ConnectionStrings__cache="localhost:62354"`. +The "webfrontend" project resource uses to add a dependency on the "cache" container resource. These dependencies can represent connection strings or [service discovery](https://aspire.dev/fundamentals/service-discovery/) information. In the preceding example, an environment variable is _injected_ into the "webfrontend" resource with the name `ConnectionStrings__cache`. This environment variable contains a connection string that the `webfrontend` uses to connect to Redis via the [Aspire Redis integration](https://aspire.dev/integrations/caching/redis/), for example, `ConnectionStrings__cache="localhost:62354"`. ### Connection string and endpoint references @@ -226,7 +226,7 @@ Aspire injects two types of environment variables for service references: - **Simplified format** (e.g., `APISERVICE_HTTP`): Uses the pattern `{RESOURCENAME}_{ENDPOINTNAME}` in uppercase. This format is simpler and more suitable for non-.NET languages and polyglot scenarios. - **.NET service discovery format** (e.g., `services__apiservice__http__0`): Uses the pattern `services__{servicename}__{endpointname}__{index}` in lowercase. This format is used by .NET's configuration-based service discovery. -For more information, see [Aspire service discovery](../service-discovery/overview.md). +For more information, see [Aspire service discovery](https://aspire.dev/fundamentals/service-discovery/). To get specific endpoints from a or an , use one of the following endpoint APIs: @@ -252,7 +252,7 @@ var apiservice = builder.AddProject("apiservice") |---------------------------|-------------------------------------------------------| | `WithReference(endpoint)` | `MYAPP_ENDPOINT="https://localhost:9043"`
`services__myapp__endpoint__0="https://localhost:9043"` | -The `port` parameter is the port that the container is listening on. For more information on container ports, see [Container ports](networking-overview.md#container-ports). For more information on service discovery, see [Aspire service discovery](../service-discovery/overview.md). +The `port` parameter is the port that the container is listening on. For more information on container ports, see [Container ports](networking-overview.md#container-ports). For more information on service discovery, see [Aspire service discovery](https://aspire.dev/fundamentals/service-discovery/). ### Service endpoint environment variable format @@ -377,7 +377,7 @@ This logic can easily be inverted to connect to an existing Redis resource when - [Aspire integrations overview](integrations-overview.md) - [Aspire SDK](dotnet-aspire-sdk.md) - [Eventing in Aspire](../app-host/eventing.md) -- [Service discovery in Aspire](../service-discovery/overview.md) -- [Aspire service defaults](service-defaults.md) +- [Service discovery in Aspire](https://aspire.dev/fundamentals/service-discovery/) +- [Aspire service defaults](https://aspire.dev/fundamentals/service-defaults/) - [Expressing external parameters](external-parameters.md) - [Aspire inner-loop networking overview](networking-overview.md) diff --git a/docs/fundamentals/aspire-sdk-templates.md b/docs/fundamentals/aspire-sdk-templates.md index f3f7ab7f34..096be70ccf 100644 --- a/docs/fundamentals/aspire-sdk-templates.md +++ b/docs/fundamentals/aspire-sdk-templates.md @@ -27,7 +27,7 @@ The following Aspire solution templates are available, assume the solution is na - **Aspire Empty App**: A minimal Aspire project that includes the following: - [**AspireSample.AppHost**](#app-host): An orchestrator project designed to connect and configure the different projects and services of your app. - - [**AspireSample.ServiceDefaults**](#service-defaults): A 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). + - [**AspireSample.ServiceDefaults**](#service-defaults): A 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](https://aspire.dev/fundamentals/service-discovery/), and [telemetry](telemetry.md). @@ -59,10 +59,10 @@ The following Aspire project templates are available: -- **Aspire Service Defaults**: A standalone **.ServiceDefaults** project that can be used 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). +- **Aspire Service Defaults**: A standalone **.ServiceDefaults** project that can be used to manage configurations that are reused across the projects in your solution related to [resilience](/dotnet/core/resilience/http-resilience), [service discovery](https://aspire.dev/fundamentals/service-discovery/), and [telemetry](./telemetry.md). > [!IMPORTANT] - > The service defaults project template takes a `FrameworkReference` dependency on `Microsoft.AspNetCore.App`. This may not be ideal for some project types. For more information, see [Aspire service defaults](service-defaults.md). + > The service defaults project template takes a `FrameworkReference` dependency on `Microsoft.AspNetCore.App`. This may not be ideal for some project types. For more information, see [Aspire service defaults](https://aspire.dev/fundamentals/service-defaults/). ## Install the Aspire templates diff --git a/docs/fundamentals/health-checks.md b/docs/fundamentals/health-checks.md deleted file mode 100644 index bce008f617..0000000000 --- a/docs/fundamentals/health-checks.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -title: Aspire health checks -description: Explore Aspire health checks -ms.date: 09/24/2024 -ms.topic: quickstart -uid: dotnet/aspire/health-checks ---- - -# Health checks in Aspire - -Health checks provide availability and state information about an app. Health checks are often exposed as HTTP endpoints, but can also be used internally by the app to write logs or perform other tasks based on the current health. Health checks are typically used in combination with an external monitoring service or container orchestrator to check the status of an app. - -In Aspire, health checks operate in two main contexts: - -- **AppHost resource health checks** - Run in the AppHost project to determine resource readiness for orchestration and dependency management. These checks control when dependent resources start and are displayed in the Aspire dashboard. -- **Application health check endpoints** - Run within individual applications and services to expose `/health` and `/alive` endpoints for monitoring and load balancing decisions. - -The data reported by health checks can be used for various scenarios: - -- Influence decisions made by container orchestrators, load balancers, API gateways, and other management services. For instance, if the health check for a containerized app fails, it might be skipped by a load balancer routing traffic. -- Verify that underlying dependencies are available, such as a database or cache, and return an appropriate status message. -- Trigger alerts or notifications when an app isn't responding as expected. - -## Aspire health check endpoints - -Aspire exposes two default health check HTTP endpoints in **Development** environments when the `AddServiceDefaults` and `MapDefaultEndpoints` methods are called from the _:::no-loc text="Program.cs":::_ file: - -- The `/health` endpoint indicates if the app is running normally where it's ready to receive requests. All health checks must pass for app to be considered ready to accept traffic after starting. - - ```http - GET /health - ``` - - The `/health` endpoint returns an HTTP status code 200 and a `text/plain` value of when the app is _healthy_. - -- The `/alive` indicates if an app is running or has crashed and must be restarted. Only health checks tagged with the _live_ tag must pass for app to be considered alive. - - ```http - GET /alive - ``` - - The `/alive` endpoint returns an HTTP status code 200 and a `text/plain` value of when the app is _alive_. - -The `AddServiceDefaults` and `MapDefaultEndpoints` methods also apply various configurations to your app beyond just health checks, such as [OpenTelemetry](telemetry.md) and [service discovery](../service-discovery/overview.md) configurations. - -### Non-development environments - -In non-development environments, the `/health` and `/alive` endpoints are disabled by default. If you need to enable them, its recommended to protect these endpoints with various routing features, such as host filtering and/or authorization. For more information, see [Health checks in ASP.NET Core](/aspnet/core/host-and-deploy/health-checks#use-health-checks-routing). - -Additionally, it may be advantageous to configure request timeouts and output caching for these endpoints to prevent abuse or denial-of-service attacks. To do so, consider the following modified `AddDefaultHealthChecks` method: - -:::code language="csharp" source="snippets/healthz/Healthz.ServiceDefaults/Extensions.cs" id="healthchecks"::: - -The preceding code: - -- Adds a timeout of 5 seconds to the health check requests with a policy named `HealthChecks`. -- Adds a 10-second cache to the health check responses with a policy named `HealthChecks`. - -Now consider the updated `MapDefaultEndpoints` method: - -:::code language="csharp" source="snippets/healthz/Healthz.ServiceDefaults/Extensions.cs" id="mapendpoints"::: - -The preceding code: - -- Groups the health check endpoints under the `/` path. -- Caches the output and specifies a request time with the corresponding `HealthChecks` policy. - -In addition to the updated `AddDefaultHealthChecks` and `MapDefaultEndpoints` methods, you must also add the corresponding services for both request timeouts and output caching. - -In the appropriate consuming app's entry point (usually the _:::no-loc text="Program.cs":::_ file), add the following code: - -```csharp -// Wherever your services are being registered. -// Before the call to Build(). -builder.Services.AddRequestTimeouts(); -builder.Services.AddOutputCache(); - -var app = builder.Build(); - -// Wherever your app has been built, before the call to Run(). -app.UseRequestTimeouts(); -app.UseOutputCache(); - -app.Run(); -``` - -For more information, see [Request timeouts middleware in ASP.NET Core](/aspnet/core/performance/timeouts) and [Output caching middleware in ASP.NET Core](/aspnet/core/performance/caching/output). - -## Integration health checks - -Aspire integrations can also register additional health checks for your app. These health checks contribute to the returned status of the `/health` and `/alive` endpoints. For example, the Aspire PostgreSQL integration automatically adds a health check to verify the following conditions: - -- A database connection could be established -- A database query could be executed successfully - -If either of these operations fail, the corresponding health check also fails. - -### Configure health checks - -You can disable health checks for a given integration using one of the available configuration options. Aspire integrations support [Microsoft.Extensions.Configurations](/dotnet/api/microsoft.extensions.configuration) to apply settings through config files such as _:::no-loc text="appsettings.json":::_: - -```json -{ - "Aspire": { - "Npgsql": { - "DisableHealthChecks": true, - } - } -} -``` - -You can also use an inline delegate to configure health checks: - -```csharp -builder.AddNpgsqlDbContext( - "postgresdb", - static settings => settings.DisableHealthChecks = true); -``` - -## AppHost resource health checks - -AppHost resource health checks are different from the health check endpoints described earlier. These health checks are configured in the AppHost project and determine the readiness of resources from the orchestrator's perspective. They're particularly important for controlling when dependent resources start via the [`WaitFor`](orchestrate-resources.md#waiting-for-resources) functionality and are displayed in the Aspire dashboard. - -### Resource readiness with health checks - -When a resource has health checks configured, the AppHost uses them to determine if the resource is ready before starting dependent resources. If no health checks are registered for a resource, the AppHost waits for the resource to be in the state. - -### HTTP health checks for resources - -For resources that expose HTTP endpoints, you can add health checks that poll specific paths: - -```csharp -var builder = DistributedApplication.CreateBuilder(args); - -var catalogApi = builder.AddContainer("catalog-api", "catalog-api") - .WithHttpEndpoint(targetPort: 8080) - .WithHttpHealthCheck("/health"); - -builder.AddProject("webapp") - .WithReference(catalogApi) - .WaitFor(catalogApi); // Waits for /health to return HTTP 200 -``` - -The `WithHttpHealthCheck` method can also be applied to project resources: - -```csharp -var backend = builder.AddProject("backend") - .WithHttpHealthCheck("/health"); - -builder.AddProject("frontend") - .WithReference(backend) - .WaitFor(backend); -``` - -### Custom resource health checks - -You can create custom health checks for more complex readiness scenarios. Start by defining the health check in the AppHost's service collection, then associate it with resources: - -```csharp -var builder = DistributedApplication.CreateBuilder(args); - -var startAfter = DateTime.Now.AddSeconds(30); - -builder.Services.AddHealthChecks().AddCheck("mycheck", () => - { - return DateTime.Now > startAfter - ? HealthCheckResult.Healthy() - : HealthCheckResult.Unhealthy(); - }); - -var pg = builder.AddPostgres("pg") - .WithHealthCheck("mycheck"); - -builder.AddProject("myapp") - .WithReference(pg) - .WaitFor(pg); // Waits for both the Postgres container to be running - // AND the custom "mycheck" health check to be healthy -``` - -The method registers the health check, and associates it with specific resources. For more details about creating and registering custom health checks, see [Create health checks](/aspnet/core/host-and-deploy/health-checks#create-health-checks). - -### Dashboard integration - -Resource health check status is displayed in the Aspire dashboard, providing real-time visibility into resource readiness. When resources are waiting for health checks to pass, the dashboard shows the current status and any failure details. - -:::image type="content" source="media/health-checks-dashboard-status.png" alt-text="Screenshot of the Aspire dashboard showing health check status for resources" lightbox="media/health-checks-dashboard-status.png"::: - -For more information about using health checks with resource dependencies, see [Waiting for resources](orchestrate-resources.md#waiting-for-resources). - -## See also - -- [.NET app health checks in C#](/dotnet/core/diagnostics/diagnostic-health-checks) -- [Health checks in ASP.NET Core](/aspnet/core/host-and-deploy/health-checks) diff --git a/docs/fundamentals/integrations-overview.md b/docs/fundamentals/integrations-overview.md index f361ccf879..f7128650dd 100644 --- a/docs/fundamentals/integrations-overview.md +++ b/docs/fundamentals/integrations-overview.md @@ -32,7 +32,7 @@ For information on creating a custom _hosting integration_, see [Create custom A ### Client integrations -Client integrations wire up client libraries to [dependency injection (DI)](/dotnet/core/extensions/dependency-injection), define configuration schema, and add [health checks](health-checks.md), [resiliency](/dotnet/core/resilience), and [telemetry](telemetry.md) where applicable. Aspire client integration libraries are prefixed with `Aspire.` and then include the full package name that they integrate with, such as `Aspire.StackExchange.Redis`. +Client integrations wire up client libraries to [dependency injection (DI)](/dotnet/core/extensions/dependency-injection), define configuration schema, and add [health checks](https://aspire.dev/fundamentals/health-checks/), [resiliency](/dotnet/core/resilience), and [telemetry](telemetry.md) where applicable. Aspire client integration libraries are prefixed with `Aspire.` and then include the full package name that they integrate with, such as `Aspire.StackExchange.Redis`. These packages configure existing client libraries to connect to hosting integrations. They extend the interface allowing client-consuming projects, such as your web app or API, to use the connected resource. The official [client integration NuGet packages](https://www.nuget.org/packages?q=owner%3A+aspire+tags%3A+aspire+client+integration&includeComputedFrameworks=true&prerel=true&sortby=relevance) are tagged with `aspire`, `integration`, and `client`. In addition to the official client integrations, the [community has created client integrations](https://aspire.dev/integrations/) for various services and platforms as part of the Community Toolkit. @@ -55,7 +55,7 @@ The AppHost project is where hosting integrations are used. Configuration, speci ## Integration features -When you add a client integration to a project within your Aspire solution, [service defaults](service-defaults.md) are automatically applied to that project; meaning the Service Defaults project is referenced and the `AddServiceDefaults` extension method is called. These defaults are designed to work well in most scenarios and can be customized as needed. The following service defaults are applied: +When you add a client integration to a project within your Aspire solution, [service defaults](https://aspire.dev/fundamentals/service-defaults/) are automatically applied to that project; meaning the Service Defaults project is referenced and the `AddServiceDefaults` extension method is called. These defaults are designed to work well in most scenarios and can be customized as needed. The following service defaults are applied: - **Observability and telemetry**: Automatically sets up logging, tracing, and metrics configurations: @@ -63,7 +63,7 @@ When you add a client integration to a project within your Aspire solution, [ser - **[Tracing](/dotnet/core/diagnostics/distributed-tracing)**: A specialized form of logging that helps you localize failures and performance issues within applications distributed across multiple machines or processes. - **[Metrics](/dotnet/core/diagnostics/metrics)**: Numerical measurements recorded over time to monitor application performance and health. Metrics are often used to generate alerts when potential problems are detected. -- **[Health checks](health-checks.md)**: Exposes HTTP endpoints to provide basic availability and state information about an app. Health checks are used to influence decisions made by container orchestrators, load balancers, API gateways, and other management services. +- **[Health checks](https://aspire.dev/fundamentals/health-checks/)**: Exposes HTTP endpoints to provide basic availability and state information about an app. Health checks are used to influence decisions made by container orchestrators, load balancers, API gateways, and other management services. - **[Resiliency](/dotnet/core/resilience/http-resilience)**: The ability of your system to react to failure and still remain functional. Resiliency extends beyond preventing failures to include recovering and reconstructing your cloud-native environment back to a healthy state. ## Understand host integration extension methods diff --git a/docs/fundamentals/launch-profiles.md b/docs/fundamentals/launch-profiles.md deleted file mode 100644 index 6f967f0743..0000000000 --- a/docs/fundamentals/launch-profiles.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: Aspire and launch profiles -description: Learn how Aspire integrates with .NET launch profiles. -ms.date: 04/15/2025 ---- - -# Aspire and launch profiles - -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 Aspire-based distributed applications. - -## Launch profile basics - -When creating a new .NET application from a template developers will often see a `Properties` directory which contains a file named _launchSettings.json_. The launch settings file contains 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. - -The code below is an example of launch profiles in a _launchSettings.json_ file for an **ASP.NET Core** application. - -```json -{ - "$schema": "http://json.schemastore.org/launchsettings.json", - "profiles": { - "http": { - "commandName": "Project", - "dotnetRunMessages": true, - "launchBrowser": false, - "applicationUrl": "http://localhost:5130", - "environmentVariables": { - "ASPNETCORE_ENVIRONMENT": "Development" - } - }, - "https": { - "commandName": "Project", - "dotnetRunMessages": true, - "launchBrowser": false, - "applicationUrl": "https://localhost:7106;http://localhost:5130", - "environmentVariables": { - "ASPNETCORE_ENVIRONMENT": "Development" - } - } - } -} -``` - -The _launchSettings.json_ file above defines two _launch profiles_, `http` and `https`. Each has its own set of environment variables, launch URLs and other options. When launching a .NET Core application developers can choose which launch profile to use. - -```dotnetcli -dotnet run --launch-profile https -``` - -If no launch profile is specified, then the first launch profile is selected by default. It is possible to launch a .NET Core application without a launch profile using the `--no-launch-profile` option. Some fields from the _launchSettings.json_ file are translated to environment variables. For example, the `applicationUrl` field is converted to the `ASPNETCORE_URLS` environment variable which controls which address and port ASP.NET Core binds to. - -In Visual Studio it's possible to select the launch profile when launching the application making it easy to switch between configuration scenarios when manually debugging issues: - -:::image type="content" loc-scope="visual-studio" source="./media/launch-profiles/vs-launch-profile-toolbar.png" lightbox="./media/launch-profiles/vs-launch-profile-toolbar.png" alt-text="Screenshot of the standard toolbar in Visual Studio with the launch profile selector highlighted."::: - -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 Aspire AppHost - -In 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 Aspire project from the starter template (`dotnet new aspire-starter`). - -```json -{ - "$schema": "https://json.schemastore.org/launchsettings.json", - "profiles": { - "https": { - "commandName": "Project", - "dotnetRunMessages": true, - "launchBrowser": true, - "applicationUrl": "https://localhost:17134;http://localhost:15170", - "environmentVariables": { - "ASPNETCORE_ENVIRONMENT": "Development", - "DOTNET_ENVIRONMENT": "Development", - "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "https://localhost:21030", - "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:22057" - } - }, - "http": { - "commandName": "Project", - "dotnetRunMessages": true, - "launchBrowser": true, - "applicationUrl": "http://localhost:15170", - "environmentVariables": { - "ASPNETCORE_ENVIRONMENT": "Development", - "DOTNET_ENVIRONMENT": "Development", - "ASPIRE_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19240", - "ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20154" - } - } - } -} -``` - -The Aspire templates have a very similar set of _launch profiles_ to a regular ASP.NET Core application. When the Aspire app project launches, it starts a and hosts a web-server which is used by the Aspire Dashboard to fetch information about resources which are being orchestrated by Aspire. - -For information about AppHost configuration options, see [Aspire AppHost configuration](../app-host/configuration.md). - -## Relationship between AppHost launch profiles and service projects - -In 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 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 Aspire modifies the `ASPNETCORE_URLS` environment variable (derived from the `applicationUrl` field in the launch profile) to use a different port. By default, 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 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); -builder.AddProject( - "inventoryservice", - launchProfileName: "mylaunchprofile"); -``` - -The preceding code shows that the `inventoryservice` resource (a .NET project) is launched using the options from the `mylaunchprofile` launch profile. The launch profile precedence logic is as follows: - -1. Use the launch profile specified by `launchProfileName` argument if specified. -2. Use the launch profile with the same name as the AppHost (determined by reading the `DOTNET_LAUNCH_PROFILE` environment variable). -3. Use the default (first) launch profile in _launchSettings.json_. -4. Don't use a launch profile. - -To force a service project to launch without a launch profile the `launchProfileName` argument on the method can be set to null. - -## Launch profiles and endpoints - -When adding an ASP.NET Core project to the AppHost, 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); -builder.AddProject("inventoryservice") - .WithEndpoint("https", endpoint => endpoint.IsProxied = false); -``` - -The preceding code shows how to disable the reverse proxy that Aspire deploys in front for the .NET Core application and instead allows the .NET Core application to respond directly on requests over HTTP(S). For more information on networking options within Aspire see [Aspire inner loop networking overview](./networking-overview.md). - -## See also - -- [Kestrel configured endpoints](networking-overview.md#kestrel-configured-endpoints) diff --git a/docs/fundamentals/networking-overview.md b/docs/fundamentals/networking-overview.md index c3067529b1..7cc59efebc 100644 --- a/docs/fundamentals/networking-overview.md +++ b/docs/fundamentals/networking-overview.md @@ -51,7 +51,7 @@ Each AppHost instance gets its own network resources. The only differences are t 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`. > [!NOTE] -> Host services, such as projects or other executables, don't use container networks. They rely on exposed container ports for service discovery and communication with containers. For more details on service discovery, see [service discovery overview](../service-discovery/overview.md). +> Host services, such as projects or other executables, don't use container networks. They rely on exposed container ports for service discovery and communication with containers. For more details on service discovery, see [service discovery overview](https://aspire.dev/fundamentals/service-discovery/). ## Launch profiles @@ -78,7 +78,7 @@ To specify the **http** and **https** launch profiles, configure the `applicatio > [!IMPORTANT] > If there's no _launchSettings.json_ (or launch profile), there are no bindings by default. -For more information, see [Aspire and launch profiles](launch-profiles.md). +For more information, see [Aspire and launch profiles](https://aspire.dev/fundamentals/launch-profiles/). ## Kestrel configured endpoints @@ -202,7 +202,7 @@ builder.Services.AddHttpClient( client => client.BaseAddress = new Uri("http://_admin.apiservice")); ``` -The `Uri` is constructed using the `admin` endpoint name prefixed with the `_` sentinel. This is a convention to indicate that the `admin` segment is the endpoint name belonging to the `apiservice` service. For more information, see [Aspire service discovery](../service-discovery/overview.md). +The `Uri` is constructed using the `admin` endpoint name prefixed with the `_` sentinel. This is a convention to indicate that the `admin` segment is the endpoint name belonging to the `apiservice` service. For more information, see [Aspire service discovery](https://aspire.dev/fundamentals/service-discovery/). ### Additional considerations diff --git a/docs/fundamentals/service-defaults.md b/docs/fundamentals/service-defaults.md deleted file mode 100644 index 3f99603e0b..0000000000 --- a/docs/fundamentals/service-defaults.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -title: Aspire service defaults -description: Learn about the Aspire service defaults project. -ms.date: 04/21/2025 -ms.topic: reference -uid: dotnet/aspire/service-defaults ---- - -# Aspire service defaults - -In this article, you learn about the Aspire service defaults project, a set of extension methods that: - -- Connect [telemetry](telemetry.md), [health checks](health-checks.md), [service discovery](../service-discovery/overview.md) to your app. -- Are customizable and extensible. - -Cloud-native applications often require extensive configurations to ensure they work across different environments reliably and securely. Aspire provides many helper methods and tools to streamline the management of configurations for OpenTelemetry, health checks, environment variables, and more. - -## Explore the service defaults project - -When you either [**Enlist in Aspire orchestration**](setup-tooling.md#enlist-in-orchestration) or [create a new Aspire project](../get-started/build-your-first-aspire-app.md), the _YourAppName.ServiceDefaults.csproj_ project is added to your solution. For example, when building an API, you call the `AddServiceDefaults` method in the _:::no-loc text="Program.cs":::_ file of your apps: - -```csharp -builder.AddServiceDefaults(); -``` - -The `AddServiceDefaults` method handles the following tasks: - -- Configures OpenTelemetry metrics and tracing. -- Adds default health check endpoints. -- Adds service discovery functionality. -- Configures to work with service discovery. - -For more information, see [Provided extension methods](#provided-extension-methods) for details on the `AddServiceDefaults` method. - -> [!IMPORTANT] -> The Aspire service defaults project is specifically designed for sharing the _Extensions.cs_ file and its functionality. Don't include other shared functionality or models in this project. Use a conventional shared class library project for those purposes. - -## Project characteristics - -The _YourAppName.ServiceDefaults_ project is a .NET 9.0 library that contains the following XML: - -:::code language="xml" source="snippets/template/YourAppName/YourAppName.ServiceDefaults.csproj" highlight="11"::: - -The service defaults project template imposes a `FrameworkReference` dependency on `Microsoft.AspNetCore.App`. - -> [!TIP] -> If you don't want to take a dependency on `Microsoft.AspNetCore.App`, you can create a custom service defaults project. For more information, see [Custom service defaults](#custom-service-defaults). - -The `IsAspireSharedProject` property is set to `true`, which indicates that this project is a shared project. The Aspire tooling uses this project as a reference for other projects added to an Aspire solution. When you enlist the new project for orchestration, it automatically references the _YourAppName.ServiceDefaults_ project and updates the _:::no-loc text="Program.cs":::_ file to call the `AddServiceDefaults` method. - -## Provided extension methods - -The _YourAppName.ServiceDefaults_ project exposes a single _Extensions.cs_ file that contains several opinionated extension methods: - -- `AddServiceDefaults`: Adds service defaults functionality. -- `ConfigureOpenTelemetry`: Configures OpenTelemetry metrics and tracing. -- `AddDefaultHealthChecks`: Adds default health check endpoints. -- `MapDefaultEndpoints`: Maps the health checks endpoint to `/health` and the liveness endpoint to `/alive`. - -### Add service defaults functionality - -The `AddServiceDefaults` method defines default configurations with the following opinionated functionality: - -:::code source="snippets/template/YourAppName/Extensions.cs" id="addservicedefaults"::: - -The preceding code: - -- Configures OpenTelemetry metrics and tracing, by calling the `ConfigureOpenTelemetry` method. -- Adds default health check endpoints, by calling the `AddDefaultHealthChecks` method. -- Adds [service discovery](../service-discovery/overview.md) functionality, by calling the `AddServiceDiscovery` method. -- Configures defaults, by calling the `ConfigureHttpClientDefaults` method—which is based on [Build resilient HTTP apps: Key development patterns](/dotnet/core/resilience/http-resilience): - - Adds the standard HTTP resilience handler, by calling the `AddStandardResilienceHandler` method. - - Specifies that the should use service discovery, by calling the `UseServiceDiscovery` method. -- Returns the `IHostApplicationBuilder` instance to allow for method chaining. - -### OpenTelemetry configuration - -Telemetry is a critical part of any cloud-native application. Aspire provides a set of opinionated defaults for OpenTelemetry, which are configured with the `ConfigureOpenTelemetry` method: - -:::code source="snippets/template/YourAppName/Extensions.cs" id="configureotel"::: - -The `ConfigureOpenTelemetry` method: - -- Adds [Aspire telemetry](telemetry.md) logging to include formatted messages and scopes. -- Adds OpenTelemetry metrics and tracing that include: - - Runtime instrumentation metrics. - - ASP.NET Core instrumentation metrics. - - HttpClient instrumentation metrics. - - In a development environment, the `AlwaysOnSampler` is used to view all traces. - - Tracing details for ASP.NET Core, gRPC and HTTP instrumentation. -- Adds OpenTelemetry exporters, by calling `AddOpenTelemetryExporters`. - -The `AddOpenTelemetryExporters` method is defined privately as follows: - -:::code source="snippets/template/YourAppName/Extensions.cs" id="addotelexporters"::: - -The `AddOpenTelemetryExporters` method adds OpenTelemetry exporters based on the following conditions: - -- If the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable is set, the OpenTelemetry exporter is added. -- Optionally consumers of Aspire service defaults can uncomment some code to enable the Prometheus exporter, or the Azure Monitor exporter. - -For more information, see [Aspire telemetry](telemetry.md). - -### Health checks configuration - -Health checks are used by various tools and systems to assess the readiness of your app. Aspire provides a set of opinionated defaults for health checks, which are configured with the `AddDefaultHealthChecks` method: - -:::code source="snippets/template/YourAppName/Extensions.cs" id="addhealthchecks"::: - -The `AddDefaultHealthChecks` method adds a default liveness check to ensure the app is responsive. The call to registers the . For more information, see [Aspire health checks](health-checks.md). - -#### Web app health checks configuration - -To expose health checks in a web app, Aspire automatically determines the type of project being referenced within the solution, and adds the appropriate call to `MapDefaultEndpoints`: - -:::code source="snippets/template/YourAppName/Extensions.cs" id="mapdefaultendpoints"::: - -The `MapDefaultEndpoints` method: - -- Allows consumers to optionally uncomment some code to enable the Prometheus endpoint. -- Maps the health checks endpoint to `/health`. -- Maps the liveness endpoint to `/alive` route where the health check tag contains `live`. - -> [!NOTE] -> Starting with Aspire 9.2, the [starter template](aspire-sdk-templates.md#solution-templates) has been updated to include a call to for ASP.NET Core projects. To keep the request trace logs cleaner during development, traces for the configured health endpoints (`/health` and `/alive`) are now excluded by default in the **Service Defaults** project template. - -## Custom service defaults - -If the default service configuration provided by the project template is not sufficient for your needs, you have the option to create your own service defaults project. This is especially useful when your consuming project, such as a Worker project or WinForms project, cannot or does not want to have a `FrameworkReference` dependency on `Microsoft.AspNetCore.App`. - -To do this, create a new .NET 9.0 class library project and add the necessary dependencies to the project file, consider the following example: - -```xml - - - - Library - net9.0 - - - - - - - - - - - - -``` - -Then create an extensions class that contains the necessary methods to configure the app defaults: - -```csharp -using Microsoft.Extensions.DependencyInjection; -using Microsoft.Extensions.Logging; -using OpenTelemetry.Logs; -using OpenTelemetry.Metrics; -using OpenTelemetry.Trace; - -namespace Microsoft.Extensions.Hosting; - -public static class AppDefaultsExtensions -{ - public static IHostApplicationBuilder AddAppDefaults( - this IHostApplicationBuilder builder) - { - builder.ConfigureAppOpenTelemetry(); - - builder.Services.AddServiceDiscovery(); - - builder.Services.ConfigureHttpClientDefaults(http => - { - // Turn on resilience by default - http.AddStandardResilienceHandler(); - - // Turn on service discovery by default - http.AddServiceDiscovery(); - }); - - return builder; - } - - public static IHostApplicationBuilder ConfigureAppOpenTelemetry( - this IHostApplicationBuilder builder) - { - builder.Logging.AddOpenTelemetry(logging => - { - logging.IncludeFormattedMessage = true; - logging.IncludeScopes = true; - }); - - builder.Services.AddOpenTelemetry() - .WithMetrics(static metrics => - { - metrics.AddRuntimeInstrumentation(); - }) - .WithTracing(tracing => - { - if (builder.Environment.IsDevelopment()) - { - // We want to view all traces in development - tracing.SetSampler(new AlwaysOnSampler()); - } - - tracing.AddGrpcClientInstrumentation() - .AddHttpClientInstrumentation(); - }); - - builder.AddOpenTelemetryExporters(); - - return builder; - } - - private static IHostApplicationBuilder AddOpenTelemetryExporters( - this IHostApplicationBuilder builder) - { - var useOtlpExporter = - !string.IsNullOrWhiteSpace( - builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"]); - - if (useOtlpExporter) - { - builder.Services.Configure( - logging => logging.AddOtlpExporter()); - builder.Services.ConfigureOpenTelemetryMeterProvider( - metrics => metrics.AddOtlpExporter()); - builder.Services.ConfigureOpenTelemetryTracerProvider( - tracing => tracing.AddOtlpExporter()); - } - - return builder; - } -} -``` - -This is only an example, and you can customize the `AppDefaultsExtensions` class to meet your specific needs. - -## Next steps - -This code is derived from the Aspire Starter Application template and is intended as a starting point. You're free to modify this code however you deem necessary to meet your needs. It's important to know that service defaults project and its functionality are automatically applied to all project resources in an Aspire solution. - -- [Service discovery in Aspire](../service-discovery/overview.md) -- [Aspire SDK](dotnet-aspire-sdk.md) -- [Aspire templates](aspire-sdk-templates.md) -- [Health checks in Aspire](health-checks.md) -- [Aspire telemetry](telemetry.md) -- [Build resilient HTTP apps: Key development patterns](/dotnet/core/resilience/http-resilience) diff --git a/docs/fundamentals/telemetry.md b/docs/fundamentals/telemetry.md index 3d1d088fe9..fda6f31653 100644 --- a/docs/fundamentals/telemetry.md +++ b/docs/fundamentals/telemetry.md @@ -18,13 +18,13 @@ Together, these types of telemetry allow you to gain insights into your applicat ## Aspire OpenTelemetry integration -The [.NET OpenTelemetry SDK](https://github.com/open-telemetry/opentelemetry-dotnet) includes features for gathering data from several .NET APIs, including , , , and . These APIs correspond to telemetry features like logging, tracing, and metrics. Aspire projects define OpenTelemetry SDK configurations in the _ServiceDefaults_ project. For more information, see [Aspire service defaults](service-defaults.md). +The [.NET OpenTelemetry SDK](https://github.com/open-telemetry/opentelemetry-dotnet) includes features for gathering data from several .NET APIs, including , , , and . These APIs correspond to telemetry features like logging, tracing, and metrics. Aspire projects define OpenTelemetry SDK configurations in the _ServiceDefaults_ project. For more information, see [Aspire service defaults](https://aspire.dev/fundamentals/service-defaults/). By default, the `ConfigureOpenTelemetry` method enables logging, tracing, and metrics for the app. It also adds exporters for these data points so they can be collected by other monitoring tools. ## Export OpenTelemetry data for monitoring -The .NET OpenTelemetry SDK facilitates the export of this telemetry data to a data store or reporting tool. The telemetry export mechanism relies on the [OpenTelemetry protocol (OTLP)](https://opentelemetry.io/docs/specs/otel/protocol), which serves as a standardized approach for transmitting telemetry data through REST or gRPC. The `ConfigureOpenTelemetry` method also registers exporters to provide your telemetry data to other monitoring tools, such as Prometheus or Azure Monitor. For more information, see [OpenTelemetry configuration](service-defaults.md#opentelemetry-configuration). +Aspire enables export of telemetry data to a data store or reporting tool. The telemetry export mechanism relies on the [OpenTelemetry protocol (OTLP)](https://opentelemetry.io/docs/specs/otel/protocol), which serves as a standardized approach for transmitting telemetry data through REST or gRPC. The `ConfigureOpenTelemetry` method also registers exporters to provide your telemetry data to other monitoring tools, such as Prometheus or Azure Monitor. For more information, see [OpenTelemetry configuration](https://aspire.dev/fundamentals/service-defaults/#opentelemetry-configuration). ## OpenTelemetry environment variables diff --git a/docs/get-started/add-aspire-existing-app.md b/docs/get-started/add-aspire-existing-app.md index daf35c20d3..1b24ce992f 100644 --- a/docs/get-started/add-aspire-existing-app.md +++ b/docs/get-started/add-aspire-existing-app.md @@ -228,7 +228,7 @@ Now, let's enroll the **Store** project, which implements the web user interface You should now have two new projects, both added to the solution: - **eShopLite.AppHost**: An orchestrator project designed to connect and configure the different projects and services of your app. The orchestrator is set as the _Startup project_, and it depends on the **eShopLite.Store** project. -- **eShopLite.ServiceDefaults**: A 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](../fundamentals/telemetry.md). +- **eShopLite.ServiceDefaults**: A 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](https://aspire.dev/fundamentals/service-discovery/), and [telemetry](../fundamentals/telemetry.md). In the **eShopLite.AppHost** project, open the _:::no-loc text="AppHost.cs":::_ file. Notice this line of code, which registers the **Store** project in the Aspire orchestration: @@ -300,7 +300,7 @@ For more information on the available templates, see [Aspire templates](../funda ### Create a service defaults project -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 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](https://aspire.dev/fundamentals/service-defaults/) from the available Aspire templates, use the following .NET CLI command: ```dotnetcli dotnet new aspire-servicedefaults -o eShopLite.ServiceDefaults @@ -338,7 +338,7 @@ dotnet add .\eShopLite.AppHost\eShopLite.AppHost.csproj reference .\Products\Pro --- -Both the **Store** and **Products** projects need to reference the _service defaults_ project so that they can easily include [service discovery](../service-discovery/overview.md). To add a reference to the _service defaults_ project in the **Store** project, use the following .NET CLI command: +Both the **Store** and **Products** projects need to reference the _service defaults_ project so that they can easily include [service discovery](https://aspire.dev/fundamentals/service-discovery/). To add a reference to the _service defaults_ project in the **Store** project, use the following .NET CLI command: ## [Unix](#tab/unix) @@ -401,7 +401,7 @@ The preceding code: ## Service Discovery -At this point, both projects are part of Aspire orchestration, but the **Store** project needs to rely on the **Products** backend address through [Aspire's service discovery](../service-discovery/overview.md). To enable service discovery, open the _:::no-loc text="AppHost.cs":::_ file in **eShopLite.AppHost** project and update the code so that the `builder` adds a reference to the _Products_ project: +At this point, both projects are part of Aspire orchestration, but the **Store** project needs to rely on the **Products** backend address through [Aspire's service discovery](https://aspire.dev/fundamentals/service-discovery/). To enable service discovery, open the _:::no-loc text="AppHost.cs":::_ file in **eShopLite.AppHost** project and update the code so that the `builder` adds a reference to the _Products_ project: ```csharp var builder = DistributedApplication.CreateBuilder(args); diff --git a/docs/get-started/aspire-overview.md b/docs/get-started/aspire-overview.md index c0723409e1..295fb6e26a 100644 --- a/docs/get-started/aspire-overview.md +++ b/docs/get-started/aspire-overview.md @@ -108,7 +108,7 @@ When added to your C# code, this method configures: - **Health checks**: Default endpoints that tools can query to monitor your app. - **Service discovery**: Enables service discovery and configures accordingly. -For more information, see [Aspire service defaults](../fundamentals/service-defaults.md). +For more information, see [Aspire service defaults](https://aspire.dev/fundamentals/service-defaults/). Consider how the three-tier architecture example can be deployed across different environments: diff --git a/docs/get-started/build-aspire-apps-with-nodejs.md b/docs/get-started/build-aspire-apps-with-nodejs.md index 79c43604d0..7111379d20 100644 --- a/docs/get-started/build-aspire-apps-with-nodejs.md +++ b/docs/get-started/build-aspire-apps-with-nodejs.md @@ -54,7 +54,7 @@ From this directory, there are six child directories described in the following - **AspireJavaScript.AppHost**: A Aspire project that orchestrates the other apps in this sample. For more information, see [Aspire orchestration overview](../fundamentals/app-host-overview.md). - **AspireJavaScript.MinimalApi**: An HTTP API that returns randomly generated weather forecast data. - **AspireJavaScript.React**: A React app that consumes the weather forecast API and displays the data in a table. -- **AspireJavaScript.ServiceDefaults**: The default shared project for Aspire projects. For more information, see [Aspire service defaults](../fundamentals/service-defaults.md). +- **AspireJavaScript.ServiceDefaults**: The default shared project for Aspire projects. For more information, see [Aspire service defaults](https://aspire.dev/fundamentals/service-defaults/). - **AspireJavaScript.Vue**: A Vue app that consumes the weather forecast API and displays the data in a table. ## Install client dependencies diff --git a/docs/get-started/build-your-first-aspire-app.md b/docs/get-started/build-your-first-aspire-app.md index 5023e06232..9db5d23de3 100644 --- a/docs/get-started/build-your-first-aspire-app.md +++ b/docs/get-started/build-your-first-aspire-app.md @@ -157,8 +157,8 @@ The solution consists of the following projects: - **AspireSample.ApiService**: An ASP.NET Core Minimal API project is used to provide data to the front end. This project depends on the shared **AspireSample.ServiceDefaults** project. - **AspireSample.AppHost**: An orchestrator project designed to connect and configure the different projects and services of your app. The orchestrator should be set as the _Startup project_, and it depends on the **AspireSample.ApiService** and **AspireSample.Web** projects. -- **AspireSample.ServiceDefaults**: A 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](../fundamentals/telemetry.md). -- **AspireSample.Web**: An ASP.NET Core Blazor App project with default Aspire service configurations, this project depends on the **AspireSample.ServiceDefaults** project. For more information, see [Aspire service defaults](../fundamentals/service-defaults.md). +- **AspireSample.ServiceDefaults**: A 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](https://aspire.dev/fundamentals/service-discovery/), and [telemetry](../fundamentals/telemetry.md). +- **AspireSample.Web**: An ASP.NET Core Blazor App project with default Aspire service configurations, this project depends on the **AspireSample.ServiceDefaults** project. For more information, see [Aspire service defaults](https://aspire.dev/fundamentals/service-defaults/). Your _AspireSample_ directory should resemble the following structure: @@ -200,7 +200,7 @@ The _*.ServiceDefaults_ project is a shared project that's used to manage config :::code language="xml" source="snippets/quickstart/AspireSample/AspireSample.ServiceDefaults/AspireSample.ServiceDefaults.csproj" highlight="7"::: -The service defaults project exposes an extension method on the type, named `AddServiceDefaults`. The service defaults project from the template is a starting point, and you can customize it to meet your needs. For more information, see [Aspire service defaults](../fundamentals/service-defaults.md). +The service defaults project exposes an extension method on the type, named `AddServiceDefaults`. The service defaults project from the template is a starting point, and you can customize it to meet your needs. For more information, see [Aspire service defaults](https://aspire.dev/fundamentals/service-defaults/). ## Orchestrate service communication @@ -231,9 +231,9 @@ For more information, see [Aspire CLI Overview](../cli/overview.md) and [Install ## See also - [Aspire integrations overview](../fundamentals/integrations-overview.md) -- [Service discovery in Aspire](../service-discovery/overview.md) -- [Aspire service defaults](../fundamentals/service-defaults.md) -- [Health checks in Aspire](../fundamentals/health-checks.md) +- [Service discovery in Aspire](https://aspire.dev/fundamentals/service-discovery/) +- [Aspire service defaults](https://aspire.dev/fundamentals/service-defaults/) +- [Health checks in Aspire](https://aspire.dev/fundamentals/health-checks/) - [Aspire telemetry](../fundamentals/telemetry.md) - [Troubleshoot untrusted localhost certificate in Aspire](../troubleshooting/untrusted-localhost-certificate.md) diff --git a/docs/get-started/docker-compose-to-apphost-reference.md b/docs/get-started/docker-compose-to-apphost-reference.md index 4a099e7b49..78e6047b1e 100644 --- a/docs/get-started/docker-compose-to-apphost-reference.md +++ b/docs/get-started/docker-compose-to-apphost-reference.md @@ -116,7 +116,7 @@ This reference provides systematic mappings from Docker Compose YAML syntax to e **Related links:** - [Docker Compose networks reference](https://docs.docker.com/compose/compose-file/05-services/#networks) -- [Aspire service discovery](../service-discovery/overview.md) +- [Aspire service discovery](https://aspire.dev/fundamentals/service-discovery/) ## Resource limits @@ -139,7 +139,7 @@ This reference provides systematic mappings from Docker Compose YAML syntax to e **Related links:** - [Docker Compose healthcheck reference](https://docs.docker.com/compose/compose-file/05-services/#healthcheck) -- [Aspire health checks](../fundamentals/health-checks.md) +- [Aspire health checks](https://aspire.dev/fundamentals/health-checks/) ## Restart policies diff --git a/docs/get-started/migrate-from-docker-compose.md b/docs/get-started/migrate-from-docker-compose.md index cb5962b388..b7caaab68d 100644 --- a/docs/get-started/migrate-from-docker-compose.md +++ b/docs/get-started/migrate-from-docker-compose.md @@ -375,7 +375,7 @@ When migrating from Docker Compose to Aspire, you might encounter some common ch After migrating to Aspire: - Explore [Aspire integrations](../fundamentals/integrations-overview.md) to replace custom container configurations. -- Set up [health checks](../fundamentals/health-checks.md) for better monitoring. +- Set up [health checks](https://aspire.dev/fundamentals/health-checks/) for better monitoring. - Configure [telemetry](../fundamentals/telemetry.md) for observability. - Learn about [deployment options](../deployment/overview.md) for production environments. - Consider [testing](https://aspire.dev/testing/overview/) your distributed application. diff --git a/docs/includes/client-integration-health-checks.md b/docs/includes/client-integration-health-checks.md index d3cc5f3c54..a179ac8f5e 100644 --- a/docs/includes/client-integration-health-checks.md +++ b/docs/includes/client-integration-health-checks.md @@ -6,7 +6,7 @@ ms.topic: include ### Client integration health checks -By default, Aspire _client integrations_ have [health checks](../fundamentals/health-checks.md) enabled for all services. Similarly, many Aspire _hosting integrations_ also enable health check endpoints. For more information, see: +By default, Aspire _client integrations_ have [health checks](https://aspire.dev/fundamentals/health-checks/) enabled for all services. Similarly, many Aspire _hosting integrations_ also enable health check endpoints. For more information, see: - [.NET app health checks in C#](/dotnet/core/diagnostics/diagnostic-health-checks) - [Health checks in ASP.NET Core](/aspnet/core/host-and-deploy/health-checks) diff --git a/docs/index.yml b/docs/index.yml index f5e210f642..2e5ecf9d3b 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -29,7 +29,7 @@ highlightedContent: url: fundamentals/integrations-overview.md - itemType: concept title: Service discovery - url: service-discovery/overview.md + url: https://aspire.dev/fundamentals/service-discovery/ - itemType: deploy title: Deploy a Aspire projects url: deployment/overview.md @@ -60,13 +60,13 @@ conceptualContent: url: fundamentals/setup-tooling.md - itemType: concept text: Aspire service discovery - url: service-discovery/overview.md + url: https://aspire.dev/fundamentals/service-discovery/ - itemType: concept text: Aspire and launch profiles - url: fundamentals/launch-profiles.md + url: https://aspire.dev/fundamentals/launch-profiles/ - itemType: reference text: Aspire service defaults - url: fundamentals/service-defaults.md + url: https://aspire.dev/fundamentals/service-defaults/ - itemType: reference text: Aspire dashboard url: https://aspire.dev/dashboard/overview/ diff --git a/docs/reference/aspire-faq.yml b/docs/reference/aspire-faq.yml index feafde811e..275fabd1d0 100644 --- a/docs/reference/aspire-faq.yml +++ b/docs/reference/aspire-faq.yml @@ -121,7 +121,7 @@ sections: - question: | How to fix integrations and Service Discovery issues when deploying Aspire apps to IIS? answer: | - Aspire integrations require specific configuration that must be provided manually. The same is true for [Service Discovery](../service-discovery/overview.md), ideally, you should deploy to something other than IIS. + Aspire integrations require specific configuration that must be provided manually. The same is true for [Service Discovery](https://aspire.dev/fundamentals/service-discovery/), ideally, you should deploy to something other than IIS. - question: | What is the purpose of the Community Toolkit project? diff --git a/docs/service-discovery/overview.md b/docs/service-discovery/overview.md deleted file mode 100644 index 1ce58acfb8..0000000000 --- a/docs/service-discovery/overview.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: Aspire service discovery -description: Understand essential service discovery concepts in Aspire. -ms.date: 07/17/2025 -ms.topic: quickstart ---- - -# Aspire service discovery - -In this article, you learn how service discovery works within an Aspire project. Aspire includes functionality for configuring service discovery at development and testing time. Service discovery functionality works by providing configuration in the format expected by the _configuration-based endpoint resolver_ from the Aspire AppHost project to the individual service projects added to the application model. For more information, see [Service discovery in .NET](/dotnet/core/extensions/service-discovery). - -## Implicit service discovery by reference - -Configuration for service discovery is only added for services that are referenced by a given project. For example, consider the following AppHost program: - -```csharp -var builder = DistributedApplication.CreateBuilder(args); - -var catalog = builder.AddProject("catalog"); -var basket = builder.AddProject("basket"); - -var frontend = builder.AddProject("frontend") - .WithReference(basket) - .WithReference(catalog); -``` - -In the preceding example, the _frontend_ project references the _catalog_ project and the _basket_ project. The two calls instruct the Aspire project to pass service discovery information for the referenced projects (_catalog_, and _basket_) into the _frontend_ project. - -## Named endpoints - -Some services expose multiple, named endpoints. Named endpoints can be resolved by specifying the endpoint name in the host portion of the HTTP request URI, following the format `scheme://_endpointName.serviceName`. For example, if a service named "basket" exposes an endpoint named "dashboard", then the URI `https+http://_dashboard.basket` can be used to specify this endpoint, for example: - -```csharp -builder.Services.AddHttpClient( - static client => client.BaseAddress = new("https+http://basket")); - -builder.Services.AddHttpClient( - static client => client.BaseAddress = new("https+http://_dashboard.basket")); -``` - -In the preceding example, two classes are added, one for the core basket service and one for the basket service's dashboard. - -### Named endpoints using configuration - -With the configuration-based endpoint resolver, named endpoints can be specified in configuration by prefixing the endpoint value with `_endpointName.`, where `endpointName` is the endpoint name. For example, consider this _:::no-loc text="appsettings.json":::_ configuration which defined a default endpoint (with no name) and an endpoint named "dashboard": - -```json -{ - "Services": { - "basket": { - "https": "https://10.2.3.4:8080", /* the https endpoint, requested via https://basket */ - "dashboard": "https://10.2.3.4:9999" /* the "dashboard" endpoint, requested via https://_dashboard.basket */ - } - } -} -``` - -In the preceding JSON: - -- The default endpoint, when resolving `https://basket` is `10.2.3.4:8080`. -- The "dashboard" endpoint, resolved via `https://_dashboard.basket` is `10.2.3.4:9999`. - -### Named endpoints in Aspire - -Named endpoints can also be exposed by code in the App Host. For instance the previous example can be modeled as: - -```csharp -var basket = builder.AddProject("basket") - .WithHttpsEndpoint(port: 9999, name: "dashboard"); -``` - -### Named endpoints in Kubernetes using DNS SRV - -When deploying to [Kubernetes](../deployment/overview.md#deploy-to-kubernetes), the DNS SRV service endpoint resolver can be used to resolve named endpoints. For example, the following resource definition will result in a DNS SRV record being created for an endpoint named "default" and an endpoint named "dashboard", both on the service named "basket". - -```yml -apiVersion: v1 -kind: Service -metadata: - name: basket -spec: - selector: - name: basket-service - clusterIP: None - ports: - - name: default - port: 8080 - - name: dashboard - port: 9999 -``` - -To configure a service to resolve the "dashboard" endpoint on the "basket" service, add the DNS SRV service endpoint resolver to the host builder as follows: - -```csharp -builder.Services.AddServiceDiscoveryCore(); -builder.Services.AddDnsSrvServiceEndpointProvider(); -``` - -For more information, see and . - -The special port name "default" is used to specify the default endpoint, resolved using the URI `https://basket`. - -As in the previous example, add service discovery to an `HttpClient` for the basket service: - -```csharp -builder.Services.AddHttpClient( - static client => client.BaseAddress = new("https://basket")); -``` - -Similarly, the "dashboard" endpoint can be targeted as follows: - -```csharp -builder.Services.AddHttpClient( - static client => client.BaseAddress = new("https://_dashboard.basket")); -``` - - - -## See also - -- [Service discovery in .NET](/dotnet/core/extensions/service-discovery) -- [Make HTTP requests with the HttpClient class](/dotnet/fundamentals/networking/http/httpclient) -- [IHttpClientFactory with .NET](/dotnet/core/extensions/httpclient-factory) diff --git a/docs/toc.yml b/docs/toc.yml index 3fada1a932..946a48a453 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -146,19 +146,19 @@ items: items: - name: Service discovery displayName: service discovery,service to service communication,Kubernetes,k8s - href: service-discovery/overview.md + href: https://aspire.dev/fundamentals/service-discovery/ - name: Service defaults - href: fundamentals/service-defaults.md + href: https://aspire.dev/fundamentals/service-defaults/ - name: Resource annotations displayName: annotations,metadata,custom annotations,resource annotations href: fundamentals/annotations-overview.md - name: Launch profiles - href: fundamentals/launch-profiles.md + href: https://aspire.dev/fundamentals/launch-profiles/ - name: Telemetry displayName: otel,otlp,telemetry,grpc,opentelemetry,protobuf,traceparent href: fundamentals/telemetry.md - name: Health checks - href: fundamentals/health-checks.md + href: https://aspire.dev/fundamentals/health-checks/ - name: Integrations href: https://aspire.dev/integrations/gallery/ diff --git a/docs/troubleshooting/hosting-startup-not-supported.md b/docs/troubleshooting/hosting-startup-not-supported.md index 5242211f62..2577081517 100644 --- a/docs/troubleshooting/hosting-startup-not-supported.md +++ b/docs/troubleshooting/hosting-startup-not-supported.md @@ -67,7 +67,7 @@ For detailed migration guidance, see: ## Additional considerations -- **Service discovery**: Aspire integrations automatically configure service discovery. If you were using HostingStartup for service-to-service communication, consider using Aspire's [service discovery features](../service-discovery/overview.md). +- **Service discovery**: Aspire integrations automatically configure service discovery. If you were using HostingStartup for service-to-service communication, consider using Aspire's [service discovery features](https://aspire.dev/fundamentals/service-discovery/). - **Configuration management**: Instead of hard-coding connection strings in HostingStartup, use Aspire's configuration patterns with connection string names that map to resources in your app host. diff --git a/docs/whats-new/dotnet-aspire-9.md b/docs/whats-new/dotnet-aspire-9.md index 1ef1af0f94..35abcf6b2e 100644 --- a/docs/whats-new/dotnet-aspire-9.md +++ b/docs/whats-new/dotnet-aspire-9.md @@ -129,7 +129,7 @@ For more information, see [Aspire AppHost: Waiting for resources](../fundamental #### Resource health checks -The `WaitFor` API uses standard [.NET health checks](../fundamentals/health-checks.md) to determine if a resource is ready. But what does "a resource being ready" mean? The best part is, that's configurable by the consumer beyond their default values. +The `WaitFor` API uses standard [.NET health checks](https://aspire.dev/fundamentals/health-checks/) to determine if a resource is ready. But what does "a resource being ready" mean? The best part is, that's configurable by the consumer beyond their default values. When a resource doesn't expose any health checks (no health checks registered in the app), the AppHost waits for the resource to be in the state before starting the dependent resource. diff --git a/docs/whats-new/dotnet-docs-aspire-mod1.md b/docs/whats-new/dotnet-docs-aspire-mod1.md index d8ef4219b8..26197e94df 100644 --- a/docs/whats-new/dotnet-docs-aspire-mod1.md +++ b/docs/whats-new/dotnet-docs-aspire-mod1.md @@ -27,9 +27,9 @@ Welcome to what's new in the Aspire docs for April 2025. This article lists some ### Updated articles -- [Aspire and launch profiles](../fundamentals/launch-profiles.md) - Rename configs-replace prefix +- [Aspire and launch profiles](https://aspire.dev/fundamentals/launch-profiles/) - Rename configs-replace prefix - [Aspire orchestration overview](../fundamentals/app-host-overview.md) - Split content -- [Aspire service defaults](../fundamentals/service-defaults.md) - Update service defaults and add filtering details +- [Aspire service defaults](https://aspire.dev/fundamentals/service-defaults/) - Update service defaults and add filtering details - [Aspire setup and tooling](../fundamentals/setup-tooling.md) - Rename configs-replace prefix - [Aspire templates](../fundamentals/aspire-sdk-templates.md) - Add dev-cert details to templates content - [Custom HTTP commands in Aspire](../fundamentals/http-commands.md) - Split content