From 88c8bd371cc04e8cf12fa791b19e8119bc751a5b Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 25 Sep 2024 12:32:24 +0000 Subject: [PATCH 1/5] Bump Swashbuckle.AspNetCore (#1681) Bumps the dotnet group in /docs/extensibility/snippets/MailDevResource with 1 update: [Swashbuckle.AspNetCore](https://github.com/domaindrivendev/Swashbuckle.AspNetCore). Updates `Swashbuckle.AspNetCore` from 6.7.3 to 6.8.0 - [Release notes](https://github.com/domaindrivendev/Swashbuckle.AspNetCore/releases) - [Commits](https://github.com/domaindrivendev/Swashbuckle.AspNetCore/compare/v6.7.3...v6.8.0) --- updated-dependencies: - dependency-name: Swashbuckle.AspNetCore dependency-type: direct:production update-type: version-update:semver-minor dependency-group: dotnet ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .../MailDevResource.NewsletterService.csproj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extensibility/snippets/MailDevResource/MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj b/docs/extensibility/snippets/MailDevResource/MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj index 26215ab40e..f860a324a8 100644 --- a/docs/extensibility/snippets/MailDevResource/MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj +++ b/docs/extensibility/snippets/MailDevResource/MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj @@ -2,7 +2,7 @@ - + From 29c5bf5a7b4c5b38607b85fab10072e01761368d Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 25 Sep 2024 12:38:20 +0000 Subject: [PATCH 2/5] Bump Swashbuckle.AspNetCore (#1682) Bumps the dotnet group in /docs/extensibility/snippets/MailDevResourceAndComponent with 1 update: [Swashbuckle.AspNetCore](https://github.com/domaindrivendev/Swashbuckle.AspNetCore). Updates `Swashbuckle.AspNetCore` from 6.7.3 to 6.8.0 - [Release notes](https://github.com/domaindrivendev/Swashbuckle.AspNetCore/releases) - [Commits](https://github.com/domaindrivendev/Swashbuckle.AspNetCore/compare/v6.7.3...v6.8.0) --- updated-dependencies: - dependency-name: Swashbuckle.AspNetCore dependency-type: direct:production update-type: version-update:semver-minor dependency-group: dotnet ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .../MailDevResource.NewsletterService.csproj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extensibility/snippets/MailDevResourceAndComponent/MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj b/docs/extensibility/snippets/MailDevResourceAndComponent/MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj index 3760cb9599..6525d044b7 100644 --- a/docs/extensibility/snippets/MailDevResourceAndComponent/MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj +++ b/docs/extensibility/snippets/MailDevResourceAndComponent/MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj @@ -2,7 +2,7 @@ - + From be030923aa8e3c54765798f461a00b820ffba345 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 25 Sep 2024 12:42:01 +0000 Subject: [PATCH 3/5] Bump Swashbuckle.AspNetCore (#1683) Bumps the dotnet group in /docs/extensibility/snippets/MailDevResourceWithCredentials/MailDevResource.AppHost with 1 update: [Swashbuckle.AspNetCore](https://github.com/domaindrivendev/Swashbuckle.AspNetCore). Updates `Swashbuckle.AspNetCore` from 6.7.3 to 6.8.0 - [Release notes](https://github.com/domaindrivendev/Swashbuckle.AspNetCore/releases) - [Commits](https://github.com/domaindrivendev/Swashbuckle.AspNetCore/compare/v6.7.3...v6.8.0) --- updated-dependencies: - dependency-name: Swashbuckle.AspNetCore dependency-type: direct:production update-type: version-update:semver-minor dependency-group: dotnet ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .../MailDevResource.NewsletterService.csproj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extensibility/snippets/MailDevResourceWithCredentials/MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj b/docs/extensibility/snippets/MailDevResourceWithCredentials/MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj index 3760cb9599..6525d044b7 100644 --- a/docs/extensibility/snippets/MailDevResourceWithCredentials/MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj +++ b/docs/extensibility/snippets/MailDevResourceWithCredentials/MailDevResource.NewsletterService/MailDevResource.NewsletterService.csproj @@ -2,7 +2,7 @@ - + From 1c4eacca70676e90f95b31c388edb395d6f076e2 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 25 Sep 2024 12:45:24 +0000 Subject: [PATCH 4/5] Bump Swashbuckle.AspNetCore (#1684) Bumps the dotnet group in /docs/deployment/azure/snippets/AppHost.Bicep with 1 update: [Swashbuckle.AspNetCore](https://github.com/domaindrivendev/Swashbuckle.AspNetCore). Updates `Swashbuckle.AspNetCore` from 6.7.3 to 6.8.0 - [Release notes](https://github.com/domaindrivendev/Swashbuckle.AspNetCore/releases) - [Commits](https://github.com/domaindrivendev/Swashbuckle.AspNetCore/compare/v6.7.3...v6.8.0) --- updated-dependencies: - dependency-name: Swashbuckle.AspNetCore dependency-type: direct:production update-type: version-update:semver-minor dependency-group: dotnet ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- docs/deployment/azure/snippets/WebHook.Api/WebHook.Api.csproj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deployment/azure/snippets/WebHook.Api/WebHook.Api.csproj b/docs/deployment/azure/snippets/WebHook.Api/WebHook.Api.csproj index a1cd5de956..e7f5c09faf 100644 --- a/docs/deployment/azure/snippets/WebHook.Api/WebHook.Api.csproj +++ b/docs/deployment/azure/snippets/WebHook.Api/WebHook.Api.csproj @@ -8,7 +8,7 @@ - + From a37f37438902ba045f4cd6e01be65ae7e8ead648 Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 25 Sep 2024 08:03:53 -0500 Subject: [PATCH 5/5] Address feedback in #1670 (#1671) * Address feedback in #1670 * Added more info links and xref * Add cloud-agnostic heading * Remove comma * Rewrite cloud-native features sections * Apply suggestions from code review Co-authored-by: Eric Erhardt * Rename heading to see how it reads now * Remove service discovery --------- Co-authored-by: Eric Erhardt --- docs/fundamentals/app-host-overview.md | 8 +- docs/fundamentals/health-checks.md | 3 +- docs/fundamentals/integrations-overview.md | 88 +++++++--------------- docs/fundamentals/service-defaults.md | 3 +- docs/fundamentals/setup-tooling.md | 3 +- 5 files changed, 39 insertions(+), 66 deletions(-) diff --git a/docs/fundamentals/app-host-overview.md b/docs/fundamentals/app-host-overview.md index 25a6fcc466..570206e3ea 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 to express resource references. -ms.date: 09/12/2024 +ms.date: 09/24/2024 ms.topic: overview uid: aspire/app-host --- @@ -10,13 +10,15 @@ uid: aspire/app-host .NET Aspire provides APIs for expressing resources and dependencies within your distributed application. In addition to these APIs, [there's tooling](setup-tooling.md#install-net-aspire) that enables some compelling scenarios. The orchestrator is intended for local development purposes. + + Before continuing, consider some common terminology used in .NET Aspire: - **App model**: A collection of resources that make up your distributed application (). 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). - **Resource**: A [resource](#built-in-resource-types) represents a part of an application whether it be a .NET project, container, or executable, or some other resource like a database, cache, or cloud service (such as a storage service). -- **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. -- **Reference**: A reference defines a connection between resources, expressed as a dependency using the `WithReference` API. For more information, see [Reference resources](#reference-resources). +- **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). +- **Reference**: A reference defines a connection between resources, expressed as a dependency using the API. For more information, see [Reference resources](#reference-resources). > [!NOTE] > .NET Aspire's orchestration is designed to enhance your local development experience by simplifying the management of your cloud-native app's configuration and interconnections. While it's an invaluable tool for development, it's not intended to replace production environment systems like [Kubernetes](../deployment/overview.md#deploy-to-kubernetes), which are specifically designed to excel in that context. diff --git a/docs/fundamentals/health-checks.md b/docs/fundamentals/health-checks.md index 7f974c4a5c..d1d70bd6fe 100644 --- a/docs/fundamentals/health-checks.md +++ b/docs/fundamentals/health-checks.md @@ -1,8 +1,9 @@ --- title: .NET Aspire health checks description: Explore .NET Aspire health checks -ms.date: 08/12/2024 +ms.date: 09/24/2024 ms.topic: quickstart +uid: aspire/health-checks --- # Health checks in .NET Aspire diff --git a/docs/fundamentals/integrations-overview.md b/docs/fundamentals/integrations-overview.md index 70584639af..4e0a76f2b6 100644 --- a/docs/fundamentals/integrations-overview.md +++ b/docs/fundamentals/integrations-overview.md @@ -1,8 +1,9 @@ --- title: .NET Aspire integrations overview description: Explore the fundamental concepts of .NET Aspire integrations and learn how to integrate them into your apps. -ms.date: 09/23/2024 +ms.date: 09/24/2024 ms.topic: conceptual +uid: aspire/integrations --- # .NET Aspire integrations overview @@ -14,25 +15,25 @@ ms.topic: conceptual ## Integration responsibilities -There are two types of integrations in .NET Aspire, each with a different responsibility. One type represents resources within the app host project—these are known as [hosting integrations](#hosting-integrations). The other type of integration represents client libraries that connect to the aforementioned resources, 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 [_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). ### 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_. 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`. +Hosting integrations extend the interface, enabling the _app host_ project to express resources within its [_app model_](app-host-overview.md#terminology). 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`. -For information on creating a custom hosting integration, see [Create custom .NET Aspire hosting integration](../extensibility/custom-hosting-integration.md). +For information on creating a custom _hosting integration_, see [Create custom .NET Aspire hosting integration](../extensibility/custom-hosting-integration.md). ### Client integrations -Client integrations define configuration schema, wire up client libraries to dependency injection (DI), and add health checks, resiliency, and telemetry where applicable. 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`. +Client integrations wire up client libraries to dependency injection (DI), define configuration schema, and add health checks, resiliency, and telemetry where applicable. 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`. For more information on creating a custom client integration, see [Create custom .NET Aspire client integrations](../extensibility/custom-client-integration.md). ### Relationship between hosting and client integrations -Hosting and client integrations are best when used together, but are **not** coupled and may be used separately. Some hosting integrations may not have a corresponding client integration. Configuration is what makes the hosting integration work with the client integration. +Hosting and client integrations are best when used together, but are **not** coupled and can be used separately. Some hosting integrations don't have a corresponding client integration. Configuration is what makes the hosting integration work with the client integration. Consider the following diagram that depicts the relationship between hosting and client integrations: @@ -40,9 +41,26 @@ Consider the following diagram that depicts the relationship between hosting and 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. -## Available integrations +## Integration features -The following section details the available .NET Aspire integrations, links to their respective NuGet packages, and provides a brief description of each integration. +When you add a client integration to a project within your .NET 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: + +- **Observability and telemetry**: Automatically sets up logging, tracing, and metrics configurations: + + - **[Logging](/dotnet/core/diagnostics/logging-tracing)**: A technique where code is instrumented to produce logs of interesting events that occurred while the program was running. + - **[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. +- **[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. + +## 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, and Amazon Web Services (AWS) integrations. + +### Cloud-agnostic integrations + +The following section details cloud-agnostic .NET Aspire integrations with links to their respective docs and NuGet packages, and provides a brief description of each integration. | Integration | Docs and NuGet packages | Description | @@ -74,7 +92,7 @@ For more information on working with .NET Aspire integrations in Visual Studio, ### Azure integrations -Azure integrations configure applications to use Azure resources. These hosting integrations are available in the `Aspire.Hosting.Azure.*` NuGet packages, while their client integrations are available in the `Aspire.*` NuGet packages.: +Azure integrations configure applications to use Azure resources. These hosting integrations are available in the `Aspire.Hosting.Azure.*` NuGet packages, while their client integrations are available in the `Aspire.*` NuGet packages: | Integration | Docs and NuGet packages | Description | @@ -97,10 +115,7 @@ Azure integrations configure applications to use Azure resources. These hosting | Azure Web PubSub logo. | - **Learn more**: [📄 Azure Web PubSub](../messaging/azure-web-pubsub-integration.md)
- **Hosting**: [📦 Aspire.Hosting.Azure.WebPubSub](https://www.nuget.org/packages/Aspire.Hosting.Azure.WebPubSub)
- **Client**: [📦 Aspire.Azure.Messaging.WebPubSub](https://www.nuget.org/packages/Aspire.Azure.Messaging.WebPubSub) | A library for accessing the [Azure Web PubSub](/azure/azure-web-pubsub/) service. | -> [!IMPORTANT] -> The .NET Aspire Azure hosting libraries rely on `Azure.Provisioning.*` libraries to provision Azure resources. For more information, [Azure provisioning libraries](../deployment/azure/local-provisioning.md). - -### AWS hosting integrations +### Amazon Web Services (AWS) hosting integrations | Integration | Docs and NuGet packages | Description | @@ -109,50 +124,3 @@ Azure integrations configure applications to use Azure resources. These hosting For more information, see [GitHub: Aspire.Hosting.AWS library](https://github.com/dotnet/aspire/tree/main/src/Aspire.Hosting.AWS). - -## Cloud-native features - -Cloud-native applications surface many unique requirements and concerns. The core features of .NET Aspire orchestration and integrations are designed to handle many cloud-native concerns for you with minimal configurations. Some of the key features include: - -- [Orchestration](app-host-overview.md): A lightweight, extensible, and cross-platform app host for .NET Aspire projects. The app host provides a consistent configuration and dependency injection experience for .NET Aspire integrations. -- [Service discovery](../service-discovery/overview.md): A technique for locating services within a distributed application. Service discovery is a key integration of microservice architectures. -- [Service defaults](service-defaults.md): A set of default configurations intended for sharing among resources within .NET Aspire projects. These defaults are designed to work well in most scenarios and can be customized as needed. - -Some .NET Aspire integrations also include more capabilities for specific services or platforms, which can be found in the integration specific reference docs. - -### Observability and telemetry - -.NET Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as _the pillars of observability_. - -- **[Logging](/dotnet/core/diagnostics/logging-tracing)**: A technique where code is instrumented to produce logs of interesting events that occurred while the program was running. A baseline set of log events is enabled for .NET Aspire integrations by default and more extensive logging can be enabled on-demand to diagnose particular problems. - -- **[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. This technique tracks requests through an application to correlate work done by different application integrations and separate it from other work the application may be doing for concurrent requests. - -- **[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. Metrics have low performance overhead and many services configure them as always-on telemetry. - -Together, these types of telemetry allow you to gain insights into your application's behavior and performance using various monitoring and analysis tools. Depending on the backing service, some integrations might only support some of these features. For example, some integrations support logging and tracing, but not metrics. Telemetry features can also be disabled. For more information, see [.NET Aspire service defaults](service-defaults.md). - -### Health checks - -.NET Aspire integrations enable health checks for services by default. Health checks are HTTP endpoints exposed by an app to provide basic availability and state information. These endpoints can be configured to report information 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. - -For example, the .NET Aspire PostgreSQL integration automatically adds a health check at the `/health` URL path to verify the following: - -- A database connection could be established -- A database query could be executed successfully - -If either of these operations fail, the health check also fails. For more information, see [Health checks in .NET Aspire](health-checks.md). - -### Resiliency - -.NET Aspire integrations enable resiliency configurations automatically where appropriate. Resiliency is 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. Examples of resiliency configurations include: - -- **Connection retries**: You can configure some .NET Aspire integrations to retry requests that initially fail. For example, failed database queries can be retried multiple times if the first request fails. This creates tolerance in environments where service dependencies may be briefly unresponsive or unavailable when the system state changes. - -- **Timeouts**: You can configure how long an .NET Aspire integration waits for a request to finish before it times out. Timeout configurations can be useful for handling dependencies with variable response times. - -For more information, see [Build resilient HTTP apps](/dotnet/core/resilience/http-resilience). diff --git a/docs/fundamentals/service-defaults.md b/docs/fundamentals/service-defaults.md index 5b6b7b1216..30b32a97cf 100644 --- a/docs/fundamentals/service-defaults.md +++ b/docs/fundamentals/service-defaults.md @@ -1,8 +1,9 @@ --- title: .NET Aspire service defaults description: Learn about the .NET Aspire service defaults project. -ms.date: 05/23/2024 +ms.date: 09/24/2024 ms.topic: reference +uid: aspire/service-defaults --- # .NET Aspire service defaults diff --git a/docs/fundamentals/setup-tooling.md b/docs/fundamentals/setup-tooling.md index 4c87e1c3f9..3e457aad10 100644 --- a/docs/fundamentals/setup-tooling.md +++ b/docs/fundamentals/setup-tooling.md @@ -1,8 +1,9 @@ --- title: .NET Aspire tooling description: Learn about essential tooling concepts for .NET Aspire. -ms.date: 07/26/2024 +ms.date: 09/24/2024 zone_pivot_groups: dev-environment +uid: aspire/setup-tooling --- # .NET Aspire setup and tooling