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 <eric.erhardt@microsoft.com>

* Rename heading to see how it reads now

* Remove service discovery

---------

Co-authored-by: Eric Erhardt <eric.erhardt@microsoft.com>

Author: IEvangelist

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.
 
+<span id="terminology"></span>
+
 Before continuing, consider some common terminology used in .NET Aspire:
 
 - **App model**: A collection of resources that make up your distributed application (<xref:Aspire.Hosting.DistributedApplication>). 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 <xref:Aspire.Hosting.ResourceBuilderExtensions.WithReference*> 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.

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

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,35 +15,52 @@ 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 <xref:Aspire.Hosting.IDistributedApplicationBuilder> 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 <xref:Aspire.Hosting.IDistributedApplicationBuilder> 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 <xref:Microsoft.Extensions.DependencyInjection.IServiceCollection> 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 <xref:Microsoft.Extensions.Hosting.IHostApplicationBuilder> 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:
 
 :::image type="content" source="media/integrations-thumb.png" lightbox="media/integrations.png" alt-text="A diagram ":::
 
 The app host project is where hosting integrations are used. Configuration, specifically environment variables, is injected into projects, executables, and containers, allowing client integrations to connect to the hosting integrations.
 
-## 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.
 
 <!-- markdownlint-disable MD033 MD045 -->
 | 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:
 
 <!-- markdownlint-disable MD033 MD045 -->
 | Integration | Docs and NuGet packages | Description |
@@ -97,10 +115,7 @@ Azure integrations configure applications to use Azure resources. These hosting
 | <img src="media/icons/AzureWebPubSub_256x.png" alt="Azure Web PubSub logo." role="presentation" width="78" data-linktype="relative-path"> | - **Learn more**: [📄 Azure Web PubSub](../messaging/azure-web-pubsub-integration.md) <br/> - **Hosting**: [📦 Aspire.Hosting.Azure.WebPubSub](https://www.nuget.org/packages/Aspire.Hosting.Azure.WebPubSub)<br>- **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. |
 <!-- markdownlint-enable MD033 MD045 -->
 
-> [!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
 
 <!-- markdownlint-disable MD033 MD045 -->
 | Integration | Docs and NuGet packages | Description |
@@ -109,50 +124,3 @@ Azure integrations configure applications to use Azure resources. These hosting
 <!-- markdownlint-enable MD033 MD045 -->
 
 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).

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

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