From 9575ca0892ba647f5e0c4ff4d92b9874248de342 Mon Sep 17 00:00:00 2001 From: David Pine Date: Tue, 4 Jun 2024 14:22:01 -0500 Subject: [PATCH 1/7] Address Dapr feedback. Fixes #947 --- docs/frameworks/dapr.md | 40 ++++++++++++------- .../snippets/Dapr/Dapr.AppHost/Program.cs | 14 +++---- .../snippets/Dapr/Dapr.Web/Dapr.Web.csproj | 1 - .../Dapr/Dapr.Web/WeatherApiClient.cs | 9 ++++- 4 files changed, 39 insertions(+), 25 deletions(-) diff --git a/docs/frameworks/dapr.md b/docs/frameworks/dapr.md index f90dd053c1..b5510692ba 100644 --- a/docs/frameworks/dapr.md +++ b/docs/frameworks/dapr.md @@ -1,7 +1,7 @@ --- title: Use Dapr with .NET Aspire description: Learn how to use Dapr with .NET Aspire -ms.date: 05/20/2024 +ms.date: 06/04/2024 ms.topic: overview --- @@ -19,6 +19,21 @@ In addition to the prerequisites for .NET Aspire, you will need: To install Dapr, see [Install the Dapr CLI](https://docs.dapr.io/getting-started/install-dapr-cli/). After installing the Dapr CLI, run the `dapr init` described in [Initialize Dapr in your local environment](https://docs.dapr.io/getting-started/install-dapr-selfhost/). +> [!IMPORTANT] +> If you attempt to run the app without the Dapr CLI, you'll receive the following error: +> +> ```plaintext +> Unable to locate the Dapr CLI. +> ``` + +In addition to having the Dapr CLI installed, it needs to also have been initialized. + +```console +dapr init +``` + +For more information, see [Initialize Dapr in your local environment](https://docs.dapr.io/getting-started/install-dapr-selfhost/). + ## Get started To get started you need to add the Dapr hosting package to your app host project by installing the [Aspire.Hosting.Dapr](https://www.nuget.org/packages/Aspire.Hosting.Dapr) NuGet package. @@ -40,25 +55,22 @@ dotnet add package Aspire.Hosting.Dapr For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-package) or [Manage package dependencies in .NET applications](/dotnet/core/tools/dependencies). -The Dapr resource is added to the .NET Aspire distributed application builder using the `AddDapr()` method. -An overload of the `AddDapr()` method that accepts Dapr options is available. For most applications, the default options will suffice. - -:::code language="csharp" source="snippets/Dapr/Dapr.AppHost/Program.cs" range="4"::: +## Add a Dapr sidecar -Dapr uses the [sidecar pattern](https://docs.dapr.io/concepts/dapr-services/sidecar/) to run alongside your application. The Dapr sidecar runs alongside your application as a lightweight, portable, and stateless HTTP server that listens for incoming HTTP requests from your application. +Dapr uses the [sidecar pattern](https://docs.dapr.io/concepts/dapr-services/sidecar/) to run alongside your application. The Dapr sidecar runs alongside your app as a lightweight, portable, and stateless HTTP server that listens for incoming HTTP requests from your app. -Add a sidecar to a .NET Aspire resource by using the `WithDaprSidecar(string appId)` method. The `appId` parameter is the unique identifier for the Dapr application. +To add a sidecar to a .NET Aspire resource call the method on the desired resource. The `appId` parameter is the unique identifier for the Dapr application, but it's optional. If you don't provide an `appId`, the parent resource name is used instead. -:::code language="csharp" source="snippets/Dapr/Dapr.AppHost/Program.cs" range="18-21" highlight="21"::: +:::code language="csharp" source="snippets/Dapr/Dapr.AppHost/Program.cs" range="5-7" highlight="7"::: -The `WithDaprSidecar` method offers overloads to configure your Dapr sidecar options like app ID and ports. In the following example, the Dapr sidecar is configured with specific ports for GRPC, HTTP, metrics, and a specific App ID. +The `WithDaprSidecar` method offers overloads to configure your Dapr sidecar options like app ID and ports. In the following example, the Dapr sidecar is configured with specific ports for GRPC, HTTP, metrics, and a specific app ID. -:::code language="csharp" source="snippets/Dapr/Dapr.AppHost/Program.cs" range="6-16" highlight="1-7,11"::: +:::code language="csharp" source="snippets/Dapr/Dapr.AppHost/Program.cs" range="9-19" highlight="9-14,19"::: -Putting everything together, here's an example of a .NET Aspire app host project which includes: +Putting everything together, consider the following example of a .NET Aspire app host project which includes: -- A backend that declares a Dapr sidecar with specific ports and app ID. -- A frontend that declares a Dapr sidecar with a specific app ID and default ports. +- A backend API that declares a Dapr sidecar with defaults. +- A frontend that declares a Dapr sidecar with specific options, such as explict ports. :::code language="csharp" source="snippets/Dapr/Dapr.AppHost/Program.cs"::: @@ -94,7 +106,7 @@ Once installed into an ASP.NET Core project, the SDK can be added to the service An instance of `DaprClient` can now be injected into your services to interact with the Dapr sidecar through the Dapr SDK. -:::code language="csharp" source="snippets/Dapr/Dapr.Web/WeatherApiClient.cs" highlight="9-10"::: +:::code language="csharp" source="snippets/Dapr/Dapr.Web/WeatherApiClient.cs" highlight="11-15"::: `InvokeMethodAsync` is a method that sends an HTTP request to the Dapr sidecar. It is a generic method that takes: diff --git a/docs/frameworks/snippets/Dapr/Dapr.AppHost/Program.cs b/docs/frameworks/snippets/Dapr/Dapr.AppHost/Program.cs index 62c71a3f7d..c5dcedb1c1 100644 --- a/docs/frameworks/snippets/Dapr/Dapr.AppHost/Program.cs +++ b/docs/frameworks/snippets/Dapr/Dapr.AppHost/Program.cs @@ -1,23 +1,21 @@ using Aspire.Hosting.Dapr; var builder = DistributedApplication.CreateBuilder(args); -builder.AddDapr(); -DaprSidecarOptions sidecarOptions = new () +var apiService = builder + .AddProject("apiservice") + .WithDaprSidecar(); + +DaprSidecarOptions sidecarOptions = new() { - AppId = "apiservice-dapr", DaprGrpcPort = 50001, DaprHttpPort = 3500, MetricsPort = 9090 }; -var apiService = builder - .AddProject("apiservice") - .WithDaprSidecar(sidecarOptions); - builder.AddProject("webfrontend") .WithExternalHttpEndpoints() .WithReference(apiService) - .WithDaprSidecar("webfrontend-dapr"); + .WithDaprSidecar(sidecarOptions); builder.Build().Run(); diff --git a/docs/frameworks/snippets/Dapr/Dapr.Web/Dapr.Web.csproj b/docs/frameworks/snippets/Dapr/Dapr.Web/Dapr.Web.csproj index 2bf92e2284..7070142780 100644 --- a/docs/frameworks/snippets/Dapr/Dapr.Web/Dapr.Web.csproj +++ b/docs/frameworks/snippets/Dapr/Dapr.Web/Dapr.Web.csproj @@ -8,7 +8,6 @@ - diff --git a/docs/frameworks/snippets/Dapr/Dapr.Web/WeatherApiClient.cs b/docs/frameworks/snippets/Dapr/Dapr.Web/WeatherApiClient.cs index ced40c15bc..618d67d82a 100644 --- a/docs/frameworks/snippets/Dapr/Dapr.Web/WeatherApiClient.cs +++ b/docs/frameworks/snippets/Dapr/Dapr.Web/WeatherApiClient.cs @@ -4,10 +4,15 @@ namespace Dapr.Web; public class WeatherApiClient(DaprClient client) { - public async Task GetWeatherAsync(int maxItems = 10, CancellationToken cancellationToken = default) + public async Task GetWeatherAsync( + int maxItems = 10, CancellationToken cancellationToken = default) { List? forecasts = - await client.InvokeMethodAsync>(HttpMethod.Get, "apiservice-dapr", "/weatherforecast", cancellationToken); ; + await client.InvokeMethodAsync>( + HttpMethod.Get, + "apiservice", + "/weatherforecast", + cancellationToken); ; return forecasts?.ToArray() ?? []; } From 9779b1fada71677068ac84ff94ae5879f176e222 Mon Sep 17 00:00:00 2001 From: David Pine Date: Tue, 4 Jun 2024 14:30:48 -0500 Subject: [PATCH 2/7] Remove redundancy --- docs/frameworks/dapr.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/frameworks/dapr.md b/docs/frameworks/dapr.md index b5510692ba..411ad2ee24 100644 --- a/docs/frameworks/dapr.md +++ b/docs/frameworks/dapr.md @@ -26,14 +26,6 @@ To install Dapr, see [Install the Dapr CLI](https://docs.dapr.io/getting-started > Unable to locate the Dapr CLI. > ``` -In addition to having the Dapr CLI installed, it needs to also have been initialized. - -```console -dapr init -``` - -For more information, see [Initialize Dapr in your local environment](https://docs.dapr.io/getting-started/install-dapr-selfhost/). - ## Get started To get started you need to add the Dapr hosting package to your app host project by installing the [Aspire.Hosting.Dapr](https://www.nuget.org/packages/Aspire.Hosting.Dapr) NuGet package. From d7e12e6dc80c00c45a5e5949db5a7e5f7d39fd07 Mon Sep 17 00:00:00 2001 From: David Pine Date: Tue, 4 Jun 2024 14:33:39 -0500 Subject: [PATCH 3/7] Fix range/highlight and remove horizontal scroll --- docs/frameworks/dapr.md | 4 ++-- docs/frameworks/snippets/Dapr/Dapr.Web/Program.cs | 1 - docs/frameworks/snippets/Dapr/Dapr.Web/WeatherApiClient.cs | 2 +- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/frameworks/dapr.md b/docs/frameworks/dapr.md index 411ad2ee24..ccf49e1a98 100644 --- a/docs/frameworks/dapr.md +++ b/docs/frameworks/dapr.md @@ -53,11 +53,11 @@ Dapr uses the [sidecar pattern](https://docs.dapr.io/concepts/dapr-services/side To add a sidecar to a .NET Aspire resource call the method on the desired resource. The `appId` parameter is the unique identifier for the Dapr application, but it's optional. If you don't provide an `appId`, the parent resource name is used instead. -:::code language="csharp" source="snippets/Dapr/Dapr.AppHost/Program.cs" range="5-7" highlight="7"::: +:::code language="csharp" source="snippets/Dapr/Dapr.AppHost/Program.cs" range="1-7" highlight="7"::: The `WithDaprSidecar` method offers overloads to configure your Dapr sidecar options like app ID and ports. In the following example, the Dapr sidecar is configured with specific ports for GRPC, HTTP, metrics, and a specific app ID. -:::code language="csharp" source="snippets/Dapr/Dapr.AppHost/Program.cs" range="9-19" highlight="9-14,19"::: +:::code language="csharp" source="snippets/Dapr/Dapr.AppHost/Program.cs" range="9-19" highlight="1-6,11"::: Putting everything together, consider the following example of a .NET Aspire app host project which includes: diff --git a/docs/frameworks/snippets/Dapr/Dapr.Web/Program.cs b/docs/frameworks/snippets/Dapr/Dapr.Web/Program.cs index dcc1ca573c..b76e097e4c 100644 --- a/docs/frameworks/snippets/Dapr/Dapr.Web/Program.cs +++ b/docs/frameworks/snippets/Dapr/Dapr.Web/Program.cs @@ -21,7 +21,6 @@ if (!app.Environment.IsDevelopment()) { app.UseExceptionHandler("/Error", createScopeForErrors: true); - // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts. app.UseHsts(); } diff --git a/docs/frameworks/snippets/Dapr/Dapr.Web/WeatherApiClient.cs b/docs/frameworks/snippets/Dapr/Dapr.Web/WeatherApiClient.cs index 618d67d82a..5d01a557cb 100644 --- a/docs/frameworks/snippets/Dapr/Dapr.Web/WeatherApiClient.cs +++ b/docs/frameworks/snippets/Dapr/Dapr.Web/WeatherApiClient.cs @@ -12,7 +12,7 @@ await client.InvokeMethodAsync>( HttpMethod.Get, "apiservice", "/weatherforecast", - cancellationToken); ; + cancellationToken); return forecasts?.ToArray() ?? []; } From 790b1fe952c3e2218f326ab6d908b9dd7b445c7a Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 5 Jun 2024 11:43:51 -0500 Subject: [PATCH 4/7] Add details to Dapr components --- docs/frameworks/dapr.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/frameworks/dapr.md b/docs/frameworks/dapr.md index ccf49e1a98..6e0cb69a01 100644 --- a/docs/frameworks/dapr.md +++ b/docs/frameworks/dapr.md @@ -128,6 +128,14 @@ At first sight Dapr and .NET Aspire may look like they have overlapping function .NET Aspire makes setting up and debugging Dapr applications easier by providing a straightforward API to configure Dapr sidecars, and by exposing the sidecars as resources in the dashboard. +### Explore Darp components with .NET Aspire + +Dapr provides many [built-in components](https://docs.dapr.io/concepts/components-concept), and when you use both Dapr with .NET Aspire you can easily explore and configure these components. For example, consider the following: + +- [Dapr—State stores](https://docs.dapr.io/concepts/components-concept/#state-stores): Call to add an configured state store to your .NET Aspire app. +- [Dapr—Pub Sub](https://docs.dapr.io/concepts/components-concept/#pubsub-brokers): Call to add a configured pub sub to your .NET Aspire app. +- Dapr—Components: Call to add a configured component to your .NET Aspire app. + ## Next steps > [!div class="nextstepaction"] From edb433e41f5c8d0ee6cd7e7e8b16ce93f1006f92 Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 5 Jun 2024 11:44:30 -0500 Subject: [PATCH 5/7] Add more details --- docs/frameworks/dapr.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/frameworks/dapr.md b/docs/frameworks/dapr.md index 6e0cb69a01..ffe3b4ff12 100644 --- a/docs/frameworks/dapr.md +++ b/docs/frameworks/dapr.md @@ -130,7 +130,7 @@ At first sight Dapr and .NET Aspire may look like they have overlapping function ### Explore Darp components with .NET Aspire -Dapr provides many [built-in components](https://docs.dapr.io/concepts/components-concept), and when you use both Dapr with .NET Aspire you can easily explore and configure these components. For example, consider the following: +Dapr provides many [built-in components](https://docs.dapr.io/concepts/components-concept), and when you use both Dapr with .NET Aspire you can easily explore and configure these components. These components are not to be confused with .NET Aspire components. For example, consider the following: - [Dapr—State stores](https://docs.dapr.io/concepts/components-concept/#state-stores): Call to add an configured state store to your .NET Aspire app. - [Dapr—Pub Sub](https://docs.dapr.io/concepts/components-concept/#pubsub-brokers): Call to add a configured pub sub to your .NET Aspire app. From 7713a19d5f8c855b5fd61fc5effc2e47f905b023 Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 5 Jun 2024 13:43:52 -0500 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/frameworks/dapr.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/frameworks/dapr.md b/docs/frameworks/dapr.md index ffe3b4ff12..6ce49ae29a 100644 --- a/docs/frameworks/dapr.md +++ b/docs/frameworks/dapr.md @@ -51,7 +51,7 @@ For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-pac Dapr uses the [sidecar pattern](https://docs.dapr.io/concepts/dapr-services/sidecar/) to run alongside your application. The Dapr sidecar runs alongside your app as a lightweight, portable, and stateless HTTP server that listens for incoming HTTP requests from your app. -To add a sidecar to a .NET Aspire resource call the method on the desired resource. The `appId` parameter is the unique identifier for the Dapr application, but it's optional. If you don't provide an `appId`, the parent resource name is used instead. +To add a sidecar to a .NET Aspire resource, call the method on the desired resource. The `appId` parameter is the unique identifier for the Dapr application, but it's optional. If you don't provide an `appId`, the parent resource name is used instead. :::code language="csharp" source="snippets/Dapr/Dapr.AppHost/Program.cs" range="1-7" highlight="7"::: @@ -59,7 +59,7 @@ The `WithDaprSidecar` method offers overloads to configure your Dapr sidecar opt :::code language="csharp" source="snippets/Dapr/Dapr.AppHost/Program.cs" range="9-19" highlight="1-6,11"::: -Putting everything together, consider the following example of a .NET Aspire app host project which includes: +Putting everything together, consider the following example of a .NET Aspire app host project that includes: - A backend API that declares a Dapr sidecar with defaults. - A frontend that declares a Dapr sidecar with specific options, such as explict ports. @@ -128,11 +128,11 @@ At first sight Dapr and .NET Aspire may look like they have overlapping function .NET Aspire makes setting up and debugging Dapr applications easier by providing a straightforward API to configure Dapr sidecars, and by exposing the sidecars as resources in the dashboard. -### Explore Darp components with .NET Aspire +### Explore Dapr components with .NET Aspire -Dapr provides many [built-in components](https://docs.dapr.io/concepts/components-concept), and when you use both Dapr with .NET Aspire you can easily explore and configure these components. These components are not to be confused with .NET Aspire components. For example, consider the following: +Dapr provides many [built-in components](https://docs.dapr.io/concepts/components-concept), and when you use Dapr with .NET Aspire you can easily explore and configure these components. Don't confuse these components with .NET Aspire components. For example, consider the following: -- [Dapr—State stores](https://docs.dapr.io/concepts/components-concept/#state-stores): Call to add an configured state store to your .NET Aspire app. +- [Dapr—State stores](https://docs.dapr.io/concepts/components-concept/#state-stores): Call to add a configured state store to your .NET Aspire app. - [Dapr—Pub Sub](https://docs.dapr.io/concepts/components-concept/#pubsub-brokers): Call to add a configured pub sub to your .NET Aspire app. - Dapr—Components: Call to add a configured component to your .NET Aspire app. From c7b4b02e52102b4eb068c8dcda7e0071d95fc3b2 Mon Sep 17 00:00:00 2001 From: David Pine Date: Wed, 5 Jun 2024 13:49:37 -0500 Subject: [PATCH 7/7] Correct xrefs --- docs/frameworks/dapr.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/frameworks/dapr.md b/docs/frameworks/dapr.md index 6ce49ae29a..0caaee056d 100644 --- a/docs/frameworks/dapr.md +++ b/docs/frameworks/dapr.md @@ -132,9 +132,9 @@ At first sight Dapr and .NET Aspire may look like they have overlapping function Dapr provides many [built-in components](https://docs.dapr.io/concepts/components-concept), and when you use Dapr with .NET Aspire you can easily explore and configure these components. Don't confuse these components with .NET Aspire components. For example, consider the following: -- [Dapr—State stores](https://docs.dapr.io/concepts/components-concept/#state-stores): Call to add a configured state store to your .NET Aspire app. -- [Dapr—Pub Sub](https://docs.dapr.io/concepts/components-concept/#pubsub-brokers): Call to add a configured pub sub to your .NET Aspire app. -- Dapr—Components: Call to add a configured component to your .NET Aspire app. +- [Dapr—State stores](https://docs.dapr.io/concepts/components-concept/#state-stores): Call to add a configured state store to your .NET Aspire app. +- [Dapr—Pub Sub](https://docs.dapr.io/concepts/components-concept/#pubsub-brokers): Call to add a configured pub sub to your .NET Aspire app. +- Dapr—Components: Call to add a configured component to your .NET Aspire app. ## Next steps