-
Notifications
You must be signed in to change notification settings - Fork 345
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 <[email protected]> * 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 <[email protected]> * Clarified configuration prioritization order on DaprClientBuilder as of 1.15 and provided more information/example around sourcing from IConfiguration. Signed-off-by: Whit Waldo <[email protected]> * Fixed typo - great catch Philip! Signed-off-by: Whit Waldo <[email protected]> * Added information about using Dapr.Jobs favoring dependency injection Signed-off-by: Whit Waldo <[email protected]> * Building out .NET AI docs Signed-off-by: Whit Waldo <[email protected]> * Building out .NET AI docs Signed-off-by: Whit Waldo <[email protected]> * Added first-draft of .NET Aspire docs Signed-off-by: Whit Waldo <[email protected]> * Added first-draft of .NET Aspire docs Signed-off-by: Whit Waldo <[email protected]> * Added first-draft of .NET Aspire docs Signed-off-by: Whit Waldo <[email protected]> * Reordered the weighting of the development docs to reflect investment level Signed-off-by: Whit Waldo <[email protected]> * Updated .NET SDK links to point to a better endpoint Signed-off-by: Whit Waldo <[email protected]> * Updated more of the .NET SDK links Signed-off-by: Whit Waldo <[email protected]> * Reweighted document order Signed-off-by: Whit Waldo <[email protected]> * Building out pubsub docs Signed-off-by: Whit Waldo <[email protected]> * Tweak to clarify use of the Dapr SDK Signed-off-by: Whit Waldo <[email protected]> * Added missing whitespace for clarity Signed-off-by: Whit Waldo <[email protected]> * Simplified alert about .NET versioning Signed-off-by: Whit Waldo <[email protected]> * Added Dapr.Jobs as a prereq Signed-off-by: Whit Waldo <[email protected]> * Added some minor formatting tweaks Signed-off-by: Whit Waldo <[email protected]> * Added body of the pubsub how to documentation Signed-off-by: Whit Waldo <[email protected]> * Updated table layout + reformatted Signed-off-by: Whit Waldo <[email protected]> * Added note about using DI functionality in best practices Signed-off-by: Whit Waldo <[email protected]> * Fixed several typos Signed-off-by: Whit Waldo <[email protected]> * Corrected updated overload Signed-off-by: Whit Waldo <[email protected]> * Added best practices documentation for PubSub functionality Signed-off-by: Whit Waldo <[email protected]> * Updated contribution guide Signed-off-by: Whit Waldo <[email protected]> * Added current .NET version support to contributor guide Signed-off-by: Whit Waldo <[email protected]> * Minor word addition Signed-off-by: Whit Waldo <[email protected]> * Renamed for consistency Signed-off-by: Whit Waldo <[email protected]> * Tweaks to introduction text Signed-off-by: Whit Waldo <[email protected]> * Added Conversation usage documentation Signed-off-by: Whit Waldo <[email protected]> * Updated to reflect updated extension method name following merge of #1423 Signed-off-by: Whit Waldo <[email protected]> * Built out Jobs introduction Signed-off-by: Whit Waldo <[email protected]> * Updated support message for Dapr.Workflows Signed-off-by: Whit Waldo <[email protected]> --------- Signed-off-by: Whit Waldo <[email protected]>
- 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
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -6,22 +6,112 @@ weight: 3000 | |
description: Guidelines for contributing to the Dapr .NET SDK | ||
--- | ||
|
||
When contributing to the [.NET SDK](https://github.com/dapr/dotnet-sdk) the following rules and best-practices should be followed. | ||
# Welcome! | ||
If you're reading this, you're likely interested in contributing to Dapr and/or the Dapr .NET SDK. Welcome to the project | ||
and thank you for your interest in contributing! | ||
|
||
Please review the documentation, familiarize yourself with what Dapr is and what it's seeking to accomplish and reach | ||
out on [Discord](https://bit.ly/dapr-discord). Let us know how you'd like to contribute and we'd be happy to chime in | ||
with ideas and suggestions. | ||
|
||
There are many ways to contribute to Dapr: | ||
- Submit bug reports for the [Dapr runtime](https://github.com/dapr/dapr/issues/new/choose) or the [Dapr .NET SDK](https://github.com/dapr/dotnet-sdk/issues/new/choose) | ||
- Propose new [runtime capabilities](https://github.com/dapr/proposals/issues/new/choose) or [SDK functionality](https://github.com/dapr/dotnet-sdk/issues/new/choose) | ||
- Improve the documentation in either the [larger Dapr project](https://github.com/dapr/docs) or the [Dapr .NET SDK specifically](https://github.com/dapr/dotnet-sdk/tree/master/daprdocs) | ||
- Add new or improve existing [components](https://github.com/dapr/components-contrib/) that implement the various building blocks | ||
- Augment the [.NET pluggable component SDK capabilities](https://github.com/dapr-sandbox/components-dotnet-sdk) | ||
- Improve the Dapr .NET SDK code base and/or fix a bug (detailed below) | ||
|
||
If you're new to the code base, please feel encouraged to ask in the #dotnet-sdk channel in Discord about how | ||
to implement changes or generally ask questions. You are not required to seek permission to work on anything, but do | ||
note that if an issue is assigned to someone, it's an indication that someone might have already started work on it. | ||
Especially if it's been a while since the last activity on that issue, please feel free to reach out and see if it's | ||
still something they're interested in pursuing or whether you can take over, and open a pull request with your | ||
implementation. | ||
|
||
If you'd like to assign yourself to an issue, respond to the conversation with "/assign" and the bot will assign you | ||
to it. | ||
|
||
We have labeled some issues as `good-first-issue` or `help wanted` indicating that these are likely to be small, | ||
self-contained changes. | ||
|
||
If you're not certain about your implementation, please create it as a draft pull request and solicit feedback | ||
from the [.NET maintainers](https://github.com/orgs/dapr/teams/maintainers-dotnet-sdk) by tagging | ||
`@dapr/maintainers-dotnet-sdk` and providing some context about what you need assistance with. | ||
|
||
# Contribution Rules and Best Practices | ||
|
||
When contributing to the [.NET SDK](https://github.com/dapr/dotnet-sdk) the following rules and best-practices should | ||
be followed. | ||
|
||
## Pull Requests | ||
Pull requests that contain only formatting changes are generally discouraged. Pull requests should instead seek to | ||
fix a bug, add new functionality, or improve on existing capabilities. | ||
|
||
Do aim to minimize the contents of your pull request to span only a single issue. Broad PRs that touch on a lot of files | ||
are not likely to be reviewed or accepted in a short timeframe. Accommodating many different issues in a single PR makes | ||
it hard to determine whether your code fully addresses the underlying issue(s) or not and complicates the code review. | ||
|
||
## Tests | ||
All pull requests should include unit and/or integration tests that reflect the nature of what was added or changed | ||
so it's clear that the functionality works as intended. Avoid using auto-generated tests that duplicate testing the | ||
same functionality several times. Rather, seek to improve code coverage by validating each possible path of your | ||
changes so future contributors can more easily navigate the contours of your logic and more readily identify limitations. | ||
|
||
## Examples | ||
|
||
The `examples` directory contains code samples for users to run to try out specific functionality of the various .NET SDK packages and extensions. When writing new and updated samples keep in mind: | ||
The `examples` directory contains code samples for users to run to try out specific functionality of the various | ||
Dapr .NET SDK packages and extensions. When writing new and updated samples keep in mind: | ||
|
||
- All examples should be runnable on Windows, Linux, and MacOS. While .NET Core code is consistent among operating systems, any pre/post example commands should provide options through [codetabs]({{< ref "contributing-docs.md#tabbed-content" >}}) | ||
- Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine. | ||
- All examples should be runnable on Windows, Linux, and MacOS. While .NET Core code is consistent among operating | ||
systems, any pre/post example commands should provide options through | ||
[codetabs]({{< ref "contributing-docs.md#tabbed-content" >}}) | ||
- Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be | ||
able to start on the example and complete it without an error. Links to external download pages are fine. | ||
|
||
## Docs | ||
## Documentation | ||
|
||
The `daprdocs` directory contains the markdown files that are rendered into the [Dapr Docs](https://docs.dapr.io) website. When the documentation website is built this repo is cloned and configured so that its contents are rendered with the docs content. When writing docs keep in mind: | ||
The `daprdocs` directory contains the markdown files that are rendered into the [Dapr Docs](https://docs.dapr.io) website. When the | ||
documentation website is built this repo is cloned and configured so that its contents are rendered with the docs | ||
content. When writing docs keep in mind: | ||
|
||
- All rules in the [docs guide]({{< ref contributing-docs.md >}}) should be followed in addition to these. | ||
- All files and directories should be prefixed with `dotnet-` to ensure all file/directory names are globally unique across all Dapr documentation. | ||
- All files and directories should be prefixed with `dotnet-` to ensure all file/directory names are globally | ||
- unique across all Dapr documentation. | ||
|
||
All pull requests should strive to include both XML documentation in the code clearly indicating what functionality | ||
does and why it's there as well as changes to the published documentation to clarify for other developers how your change | ||
improves the Dapr framework. | ||
|
||
## GitHub Dapr Bot Commands | ||
|
||
Checkout the [daprbot documentation](https://docs.dapr.io/contributing/daprbot/) for Github commands you can run in this repo for common tasks. For example, you can comment `/assign` on an issue to assign it to yourself. | ||
Checkout the [daprbot documentation](https://docs.dapr.io/contributing/daprbot/) for Github commands you can run in this repo for common tasks. For example, | ||
you can comment `/assign` on an issue to assign it to yourself. | ||
|
||
## Commit Sign-offs | ||
All code submitted to the Dapr .NET SDK must be signed off by the developer authoring it. This means that every | ||
commit must end with the following: | ||
> Signed-off-by: First Last <[email protected]> | ||
The name and email address must match the registered GitHub name and email address of the user committing the changes. | ||
We use a bot to detect this in pull requests and we will be unable to merge the PR if this check fails to validate. | ||
|
||
If you notice that a PR has failed to validate because of a failed DCO check early on in the PR history, please consider | ||
squashing the PR locally and resubmitting to ensure that the sign-off statement is included in the commit history. | ||
|
||
# Languages, Tools and Processes | ||
All source code in the Dapr .NET SDK is written in C# and targets the latest language version available to the earliest | ||
supported .NET SDK. As of v1.15, this means that because .NET 6 is still supported, the latest language version available | ||
is [C# version 10](https://learn.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-version-history#c-version-10). | ||
|
||
As of v1.15, the following versions of .NET are supported: | ||
|
||
| Version | Notes | | ||
| --- |-----------------------------------------------------------------| | ||
| .NET 6 | Will be discontinued in v1.16 | | ||
| .NET 7 | Only supported in Dapr.Workflows, will be discontinued in v1.16 | | ||
| .NET 8 | Will continue to be supported in v1.16 | | ||
| .NET 9 | Will continue to be supported in v1.16 | | ||
|
||
Contributors are welcome to use whatever IDE they're most comfortable developing in, but please do not submit | ||
IDE-specific preference files along with your contributions as these will be rejected. |
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.