-
Notifications
You must be signed in to change notification settings - Fork 344
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Updating Dapr .NET SDK documentation (#1409)
* Updated documentation to reflect new DaprClient DI injection capabilities Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Clarified relationship between DAPR_HTTP_ENDPOINT and DAPR_HTTP_PORT as well as DAPR_GRPC_ENDPOINT and DAPR_GRPC_PORT. Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Clarified configuration prioritization order on DaprClientBuilder as of 1.15 and provided more information/example around sourcing from IConfiguration. Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Fixed typo - great catch Philip! Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Added information about using Dapr.Jobs favoring dependency injection Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Building out .NET AI docs Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Building out .NET AI docs Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Added first-draft of .NET Aspire docs Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Added first-draft of .NET Aspire docs Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Added first-draft of .NET Aspire docs Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Reordered the weighting of the development docs to reflect investment level Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Updated .NET SDK links to point to a better endpoint Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Updated more of the .NET SDK links Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Reweighted document order Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Building out pubsub docs Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Tweak to clarify use of the Dapr SDK Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Added missing whitespace for clarity Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Simplified alert about .NET versioning Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Added Dapr.Jobs as a prereq Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Added some minor formatting tweaks Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Added body of the pubsub how to documentation Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Updated table layout + reformatted Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Added note about using DI functionality in best practices Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Fixed several typos Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Corrected updated overload Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Added best practices documentation for PubSub functionality Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Updated contribution guide Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Added current .NET version support to contributor guide Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Minor word addition Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Renamed for consistency Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Tweaks to introduction text Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Added Conversation usage documentation Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Updated to reflect updated extension method name following merge of #1423 Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Built out Jobs introduction Signed-off-by: Whit Waldo <whit.waldo@innovian.net> * Updated support message for Dapr.Workflows Signed-off-by: Whit Waldo <whit.waldo@innovian.net> --------- Signed-off-by: Whit Waldo <whit.waldo@innovian.net>
- Loading branch information
Showing
18 changed files
with
1,127 additions
and
139 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,83 +1,12 @@ | ||
| _index.md | ||
|
|
||
| --- | ||
| type: docs | ||
| title: "Getting started with the Dapr AI .NET SDK client" | ||
| title: "Dapr AI .NET SDK" | ||
| linkTitle: "AI" | ||
| weight: 10000 | ||
| description: How to get up and running with the Dapr AI .NET SDK | ||
| no_list: true | ||
| weight: 50000 | ||
| description: Get up and running with the Dapr AI .NET SDK | ||
| --- | ||
|
|
||
| The Dapr AI client package allows you to interact with the AI capabilities provided by the Dapr sidecar. | ||
|
|
||
| ## Installation | ||
|
|
||
| To get started with the Dapr AI .NET SDK client, install the following package from NuGet: | ||
| ```sh | ||
| dotnet add package Dapr.AI | ||
| ``` | ||
|
|
||
| A `DaprConversationClient` holes access to networking resources in the form of TCP sockets used to communicate with the Dapr sidecar. | ||
|
|
||
| ### Dependency Injection | ||
|
|
||
| The `AddDaprAiConversation()` method will register the Dapr client ASP.NET Core dependency injection and is the recommended approach | ||
| for using this package. This method accepts an optional options delegate for configuring the `DaprConversationClient` and a | ||
| `ServiceLifetime` argument, allowing you to specify a different lifetime for the registered services instead of the default `Singleton` | ||
| value. | ||
|
|
||
| The following example assumes all default values are acceptable and is sufficient to register the `DaprConversationClient`: | ||
|
|
||
| ```csharp | ||
| services.AddDaprAiConversation(); | ||
| ``` | ||
|
|
||
| The optional configuration delegate is used to configure the `DaprConversationClient` by specifying options on the | ||
| `DaprConversationClientBuilder` as in the following example: | ||
| ```csharp | ||
| services.AddSingleton<DefaultOptionsProvider>(); | ||
| services.AddDaprAiConversation((serviceProvider, clientBuilder) => { | ||
| //Inject a service to source a value from | ||
| var optionsProvider = serviceProvider.GetRequiredService<DefaultOptionsProvider>(); | ||
| var standardTimeout = optionsProvider.GetStandardTimeout(); | ||
|
|
||
| //Configure the value on the client builder | ||
| clientBuilder.UseTimeout(standardTimeout); | ||
| }); | ||
| ``` | ||
|
|
||
| ### Manual Instantiation | ||
| Rather than using dependency injection, a `DaprConversationClient` can also be built using the static client builder. | ||
|
|
||
| For best performance, create a single long-lived instance of `DaprConversationClient` and provide access to that shared instance throughout | ||
| your application. `DaprConversationClient` instances are thread-safe and intended to be shared. | ||
|
|
||
| Avoid creating a `DaprConversationClient` per-operation. | ||
|
|
||
| A `DaprConversationClient` can be configured by invoking methods on the `DaprConversationClientBuilder` class before calling `.Build()` | ||
| to create the client. The settings for each `DaprConversationClient` are separate and cannot be changed after calling `.Build()`. | ||
|
|
||
| ```csharp | ||
| var daprConversationClient = new DaprConversationClientBuilder() | ||
| .UseJsonSerializerSettings( ... ) //Configure JSON serializer | ||
| .Build(); | ||
| ``` | ||
|
|
||
| See the .NET [documentation here]({{< ref dotnet-client >}}) for more information about the options available when configuring the Dapr client via the builder. | ||
|
|
||
| ## Try it out | ||
| Put the Dapr AI .NET SDK to the test. Walk through the samples to see Dapr in action: | ||
|
|
||
| | SDK Samples | Description | | ||
| | ----------- | ----------- | | ||
| | [SDK samples](https://github.com/dapr/dotnet-sdk/tree/master/examples) | Clone the SDK repo to try out some examples and get started. | | ||
|
|
||
| ## Building Blocks | ||
|
|
||
| This part of the .NET SDK allows you to interface with the Conversations API to send and receive messages from | ||
| large language models. | ||
|
|
||
| ### Send messages | ||
|
|
||
| With the Dapr AI package, you can interact with the Dapr AI workloads from a .NET application. | ||
|
|
||
| Today, Dapr provides the Conversational API to engage with large language models. To get started with this workload, | ||
| walk through the [Dapr Conversational AI]({{< ref dotnet-ai-conversation-howto.md >}}) how-to guide. |
90 changes: 90 additions & 0 deletions
90
daprdocs/content/en/dotnet-sdk-docs/dotnet-ai/dotnet-ai-conversation-howto.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,90 @@ | ||
| --- | ||
| type: docs | ||
| title: "How to: Create and use Dapr AI Conversations in the .NET SDK" | ||
| linkTitle: "How to: Use the AI Conversations client" | ||
| weight: 500100 | ||
| description: Learn how to create and use the Dapr Conversational AI client using the .NET SDK | ||
| --- | ||
|
|
||
| ## Prerequisites | ||
| - [.NET 6](https://dotnet.microsoft.com/download/dotnet/6.0), [.NET 8](https://dotnet.microsoft.com/download/dotnet/8.0), or [.NET 9](https://dotnet.microsoft.com/download/dotnet/9.0) installed | ||
| - [Dapr CLI](https://docs.dapr.io/getting-started/install-dapr-cli/) | ||
| - [Initialized Dapr environment](https://docs.dapr.io/getting-started/install-dapr-selfhost) | ||
|
|
||
| {{% alert title="Note" color="primary" %}} | ||
|
|
||
| .NET 6 is supported as the minimum required for the Dapr .NET SDK packages in this release. Only .NET 8 and .NET 9 | ||
| will be supported in Dapr v1.16 and later releases. | ||
|
|
||
| {{% /alert %}} | ||
|
|
||
| ## Installation | ||
|
|
||
| To get started with the Dapr AI .NET SDK client, install the [Dapr.AI package](https://www.nuget.org/packages/Dapr.AI) from NuGet: | ||
| ```sh | ||
| dotnet add package Dapr.AI | ||
| ``` | ||
|
|
||
| A `DaprConversationClient` maintains access to networking resources in the form of TCP sockets used to communicate with the Dapr sidecar. | ||
|
|
||
| ### Dependency Injection | ||
|
|
||
| The `AddDaprAiConversation()` method will register the Dapr client ASP.NET Core dependency injection and is the recommended approach | ||
| for using this package. This method accepts an optional options delegate for configuring the `DaprConversationClient` and a | ||
| `ServiceLifetime` argument, allowing you to specify a different lifetime for the registered services instead of the default `Singleton` | ||
| value. | ||
|
|
||
| The following example assumes all default values are acceptable and is sufficient to register the `DaprConversationClient`: | ||
|
|
||
| ```csharp | ||
| services.AddDaprAiConversation(); | ||
| ``` | ||
|
|
||
| The optional configuration delegate is used to configure the `DaprConversationClient` by specifying options on the | ||
| `DaprConversationClientBuilder` as in the following example: | ||
| ```csharp | ||
| services.AddSingleton<DefaultOptionsProvider>(); | ||
| services.AddDaprAiConversation((serviceProvider, clientBuilder) => { | ||
| //Inject a service to source a value from | ||
| var optionsProvider = serviceProvider.GetRequiredService<DefaultOptionsProvider>(); | ||
| var standardTimeout = optionsProvider.GetStandardTimeout(); | ||
|
|
||
| //Configure the value on the client builder | ||
| clientBuilder.UseTimeout(standardTimeout); | ||
| }); | ||
| ``` | ||
|
|
||
| ### Manual Instantiation | ||
| Rather than using dependency injection, a `DaprConversationClient` can also be built using the static client builder. | ||
|
|
||
| For best performance, create a single long-lived instance of `DaprConversationClient` and provide access to that shared instance throughout | ||
| your application. `DaprConversationClient` instances are thread-safe and intended to be shared. | ||
|
|
||
| Avoid creating a `DaprConversationClient` per-operation. | ||
|
|
||
| A `DaprConversationClient` can be configured by invoking methods on the `DaprConversationClientBuilder` class before calling `.Build()` | ||
| to create the client. The settings for each `DaprConversationClient` are separate and cannot be changed after calling `.Build()`. | ||
|
|
||
| ```csharp | ||
| var daprConversationClient = new DaprConversationClientBuilder() | ||
| .UseJsonSerializerSettings( ... ) //Configure JSON serializer | ||
| .Build(); | ||
| ``` | ||
|
|
||
| See the .NET [documentation here]({{< ref dotnet-client >}}) for more information about the options available when configuring the Dapr client via the builder. | ||
|
|
||
| ## Try it out | ||
| Put the Dapr AI .NET SDK to the test. Walk through the samples to see Dapr in action: | ||
|
|
||
| | SDK Samples | Description | | ||
| | ----------- | ----------- | | ||
| | [SDK samples](https://github.com/dapr/dotnet-sdk/tree/master/examples) | Clone the SDK repo to try out some examples and get started. | | ||
|
|
||
| ## Building Blocks | ||
|
|
||
| This part of the .NET SDK allows you to interface with the Conversations API to send and receive messages from | ||
| large language models. | ||
|
|
||
| ### Send messages | ||
|
|
||
|
|
Oops, something went wrong.