From de09ba175ec614552869d0297f2042fb729063c5 Mon Sep 17 00:00:00 2001 From: David Pine Date: Thu, 23 May 2024 14:06:26 -0500 Subject: [PATCH 1/2] Various updates to help address issue #937 --- docs/fundamentals/app-host-overview.md | 8 ++++---- docs/fundamentals/components-overview.md | 4 ++-- docs/fundamentals/service-defaults.md | 6 ++++-- docs/get-started/aspire-overview.md | 12 ++++++------ 4 files changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/fundamentals/app-host-overview.md b/docs/fundamentals/app-host-overview.md index 47547cb7df..53b897793e 100644 --- a/docs/fundamentals/app-host-overview.md +++ b/docs/fundamentals/app-host-overview.md @@ -1,20 +1,20 @@ --- 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: 05/15/2024 +ms.date: 05/23/2024 ms.topic: overview --- # .NET Aspire orchestration overview -.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. +.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). -- **Reference**: A reference defines a connection between resources, expressed as a dependency. For more information, see [Reference resources](#reference-resources). +- **Reference**: A reference defines a connection between resources, expressed as a dependency using the `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. @@ -77,7 +77,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 information. In the preceding example, an environment variable is injected into the "webfronend" resource with the name `ConnectionStrings__cache`. This environment variable contains a connection string that the webfrontend can use to connect to redis via the .NET Aspire Redis component, 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](../service-discovery/overview.md) information. In the preceding example, an environment variable is injected into the "webfronend" resource with the name `ConnectionStrings__cache`. This environment variable contains a connection string that the webfrontend can use to connect to redis via the .NET Aspire Redis component, for example, `ConnectionStrings__cache="localhost:62354"`. ### Connection string and endpoint references diff --git a/docs/fundamentals/components-overview.md b/docs/fundamentals/components-overview.md index 114fcd9358..28e22b4332 100644 --- a/docs/fundamentals/components-overview.md +++ b/docs/fundamentals/components-overview.md @@ -1,13 +1,13 @@ --- title: .NET Aspire components overview description: Explore the fundamental concepts of .NET Aspire components and learn how to integrate them into your apps. -ms.date: 05/22/2024 +ms.date: 05/23/2024 ms.topic: conceptual --- # .NET Aspire components overview -.NET Aspire components are a curated suite of NuGet packages specifically selected to facilitate the integration of cloud-native applications with prominent services and platforms, including but not limited to Redis and PostgreSQL. Each component furnishes essential cloud-native functionalities through either automatic provisioning or standardized configuration patterns. .NET Aspire components can be used without an orchestrator project, but they're designed to work best with the [.NET Aspire app host](app-host-overview.md). +.NET Aspire components are a curated suite of NuGet packages specifically selected to facilitate the integration of cloud-native applications with prominent services and platforms, including but not limited to Redis and PostgreSQL. Each component furnishes essential cloud-native functionalities through either automatic provisioning or standardized configuration patterns. .NET Aspire components can be used without an app host (orchestrator) project, but they're designed to work best with the [.NET Aspire app host](app-host-overview.md). .NET Aspire components should not be confused with .NET Aspire hosting packages, as they serve different purposes. Hosting packages are used to model and configure various resources in a .NET Aspire app, while components are used to map configuration to various client libraries. diff --git a/docs/fundamentals/service-defaults.md b/docs/fundamentals/service-defaults.md index e73aac89c6..5b6b7b1216 100644 --- a/docs/fundamentals/service-defaults.md +++ b/docs/fundamentals/service-defaults.md @@ -1,17 +1,19 @@ --- title: .NET Aspire service defaults description: Learn about the .NET Aspire service defaults project. -ms.date: 04/05/2024 +ms.date: 05/23/2024 ms.topic: reference --- # .NET Aspire service defaults +In this article, you learn about the .NET Aspire service defaults project, a set of extension methods that wire up [telemetry](telemetry.md), [health checks](health-checks.md), [service discovery](../service-discovery/overview.md), and are designed to be customizable and extensible. + Cloud-native applications often require extensive configurations to ensure they work across different environments reliably and securely. .NET 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 .NET Aspire orchestration**](setup-tooling.md#enlist-in-orchestration) or [create a new .NET Aspire project](../get-started/build-your-first-aspire-app.md), the _YourAppName.ServiceDefaults_ 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: +When you either [**Enlist in .NET Aspire orchestration**](setup-tooling.md#enlist-in-orchestration) or [create a new .NET 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(); diff --git a/docs/get-started/aspire-overview.md b/docs/get-started/aspire-overview.md index a8998c8b96..e4548be18e 100644 --- a/docs/get-started/aspire-overview.md +++ b/docs/get-started/aspire-overview.md @@ -1,7 +1,7 @@ --- title: .NET Aspire overview description: Learn about .NET Aspire, an application stack designed to improve the experience of building cloud-native applications. -ms.date: 05/17/2024 +ms.date: 05/23/2024 --- # .NET Aspire overview @@ -19,24 +19,24 @@ ms.date: 05/17/2024 :::column-end::: :::row-end::: -A _distributed application_ is one that uses computational resources across multiple nodes, such as containers running on different hosts. Such nodes must communicate over network boundaries to deliver responses to users. A cloud-native app is a specific type of distributed app that takes full advantage of the scalability, resilience, and manageability of cloud infrastructures. +A _distributed application_ is one that uses computational _resources_ across multiple nodes, such as containers running on different hosts. Such nodes must communicate over network boundaries to deliver responses to users. A cloud-native app is a specific type of distributed app that takes full advantage of the scalability, resilience, and manageability of cloud infrastructures. ## Why .NET Aspire? .NET Aspire is designed to improve the experience of building .NET cloud-native apps. It provides a consistent, opinionated set of tools and patterns that help you build and run distributed apps. .NET Aspire is designed to help you with: -- [**Orchestration**](#orchestration): .NET Aspire provides features for running and connecting multi-project applications and their dependencies for local development environments. +- [**Orchestration**](#orchestration): .NET Aspire provides features for running and connecting multi-project applications and their dependencies for [local development environments](../fundamentals/networking-overview.md). - [**Components**](#net-aspire-components): .NET Aspire components are NuGet packages for commonly used services, such as Redis or Postgres, with standardized interfaces ensuring they connect consistently and seamlessly with your app. -- [**Tooling**](#project-templates-and-tooling): .NET Aspire comes with project templates and tooling experiences for Visual Studio and the [dotnet CLI](/dotnet/core/tools/) to help you create and interact with .NET Aspire apps. +- [**Tooling**](#project-templates-and-tooling): .NET Aspire comes with project templates and tooling experiences for Visual Studio, Visual Studio Code, and the [dotnet CLI](/dotnet/core/tools/) to help you create and interact with .NET Aspire apps. ## Orchestration -In .NET Aspire, orchestration primarily focuses on enhancing the local development experience by simplifying the management of your cloud-native app's configuration and interconnections. It's important to note that .NET Aspire's orchestration is not intended to replace the robust systems used in production environments, such as [Kubernetes](../deployment/overview.md#deploy-to-kubernetes). Instead, it provides a set of abstractions that streamline the setup of service discovery, environment variables, and container configurations, eliminating the need to deal with low-level implementation details. These abstractions ensure a consistent setup pattern across apps with numerous components and services, making it easier to manage complex applications during the development phase. +In .NET Aspire, orchestration primarily focuses on enhancing the _local development_ experience by simplifying the management of your cloud-native app's configuration and interconnections. It's important to note that .NET Aspire's orchestration isn't intended to replace the robust systems used in production environments, such as [Kubernetes](../deployment/overview.md#deploy-to-kubernetes). Instead, it provides a set of abstractions that streamline the setup of service discovery, environment variables, and container configurations, eliminating the need to deal with low-level implementation details. These abstractions ensure a consistent setup pattern across apps with numerous components and services, making it easier to manage complex applications during the development phase. .NET Aspire orchestration assists with the following concerns: - **App composition**: Specify the .NET projects, containers, executables, and cloud resources that make up the application. -- **Service discovery and connection string management**: The app host manages injecting the right connection strings and service discovery information to simplify the developer experience. +- **Service discovery and connection string management**: The app host manages injecting the right connection strings or newtork configurations and service discovery information to simplify the developer experience. For example, using .NET Aspire, the following code creates a local Redis container resource and configures the appropriate connection string in the `"frontend"` project with only two helper method calls: From 1e2db48a39d900b1d90605fc683cf87024549188 Mon Sep 17 00:00:00 2001 From: David Pine Date: Thu, 23 May 2024 15:19:17 -0500 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Cam Soper --- docs/get-started/aspire-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/get-started/aspire-overview.md b/docs/get-started/aspire-overview.md index e4548be18e..9c25dd70e9 100644 --- a/docs/get-started/aspire-overview.md +++ b/docs/get-started/aspire-overview.md @@ -36,7 +36,7 @@ In .NET Aspire, orchestration primarily focuses on enhancing the _local developm .NET Aspire orchestration assists with the following concerns: - **App composition**: Specify the .NET projects, containers, executables, and cloud resources that make up the application. -- **Service discovery and connection string management**: The app host manages injecting the right connection strings or newtork configurations and service discovery information to simplify the developer experience. +- **Service discovery and connection string management**: The app host manages injecting the right connection strings or network configurations and service discovery information to simplify the developer experience. For example, using .NET Aspire, the following code creates a local Redis container resource and configures the appropriate connection string in the `"frontend"` project with only two helper method calls: