Skip to content

Commit 1454043

Browse files
WhitWaldoWhitWaldo
authored
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]>
1 parent 3d500e8 commit 1454043

18 files changed

+1127
-139
lines changed

‎daprdocs/content/en/dotnet-sdk-contributing/dotnet-contributing.md‎

Lines changed: 98 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,22 +6,112 @@ weight: 3000
66
description: Guidelines for contributing to the Dapr .NET SDK
77
---
88

9-
When contributing to the [.NET SDK](https://github.com/dapr/dotnet-sdk) the following rules and best-practices should be followed.
9+
# Welcome!
10+
If you're reading this, you're likely interested in contributing to Dapr and/or the Dapr .NET SDK. Welcome to the project
11+
and thank you for your interest in contributing!
12+
13+
Please review the documentation, familiarize yourself with what Dapr is and what it's seeking to accomplish and reach
14+
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
15+
with ideas and suggestions.
16+
17+
There are many ways to contribute to Dapr:
18+
- 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)
19+
- Propose new [runtime capabilities](https://github.com/dapr/proposals/issues/new/choose) or [SDK functionality](https://github.com/dapr/dotnet-sdk/issues/new/choose)
20+
- 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)
21+
- Add new or improve existing [components](https://github.com/dapr/components-contrib/) that implement the various building blocks
22+
- Augment the [.NET pluggable component SDK capabilities](https://github.com/dapr-sandbox/components-dotnet-sdk)
23+
- Improve the Dapr .NET SDK code base and/or fix a bug (detailed below)
24+
25+
If you're new to the code base, please feel encouraged to ask in the #dotnet-sdk channel in Discord about how
26+
to implement changes or generally ask questions. You are not required to seek permission to work on anything, but do
27+
note that if an issue is assigned to someone, it's an indication that someone might have already started work on it.
28+
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
29+
still something they're interested in pursuing or whether you can take over, and open a pull request with your
30+
implementation.
31+
32+
If you'd like to assign yourself to an issue, respond to the conversation with "/assign" and the bot will assign you
33+
to it.
34+
35+
We have labeled some issues as `good-first-issue` or `help wanted` indicating that these are likely to be small,
36+
self-contained changes.
37+
38+
If you're not certain about your implementation, please create it as a draft pull request and solicit feedback
39+
from the [.NET maintainers](https://github.com/orgs/dapr/teams/maintainers-dotnet-sdk) by tagging
40+
`@dapr/maintainers-dotnet-sdk` and providing some context about what you need assistance with.
41+
42+
# Contribution Rules and Best Practices
43+
44+
When contributing to the [.NET SDK](https://github.com/dapr/dotnet-sdk) the following rules and best-practices should
45+
be followed.
46+
47+
## Pull Requests
48+
Pull requests that contain only formatting changes are generally discouraged. Pull requests should instead seek to
49+
fix a bug, add new functionality, or improve on existing capabilities.
50+
51+
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
52+
are not likely to be reviewed or accepted in a short timeframe. Accommodating many different issues in a single PR makes
53+
it hard to determine whether your code fully addresses the underlying issue(s) or not and complicates the code review.
54+
55+
## Tests
56+
All pull requests should include unit and/or integration tests that reflect the nature of what was added or changed
57+
so it's clear that the functionality works as intended. Avoid using auto-generated tests that duplicate testing the
58+
same functionality several times. Rather, seek to improve code coverage by validating each possible path of your
59+
changes so future contributors can more easily navigate the contours of your logic and more readily identify limitations.
1060

1161
## Examples
1262

13-
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:
63+
The `examples` directory contains code samples for users to run to try out specific functionality of the various
64+
Dapr .NET SDK packages and extensions. When writing new and updated samples keep in mind:
1465

15-
- 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" >}})
16-
- 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.
66+
- All examples should be runnable on Windows, Linux, and MacOS. While .NET Core code is consistent among operating
67+
systems, any pre/post example commands should provide options through
68+
[codetabs]({{< ref "contributing-docs.md#tabbed-content" >}})
69+
- Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be
70+
able to start on the example and complete it without an error. Links to external download pages are fine.
1771

18-
## Docs
72+
## Documentation
1973

20-
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:
74+
The `daprdocs` directory contains the markdown files that are rendered into the [Dapr Docs](https://docs.dapr.io) website. When the
75+
documentation website is built this repo is cloned and configured so that its contents are rendered with the docs
76+
content. When writing docs keep in mind:
2177

2278
- All rules in the [docs guide]({{< ref contributing-docs.md >}}) should be followed in addition to these.
23-
- All files and directories should be prefixed with `dotnet-` to ensure all file/directory names are globally unique across all Dapr documentation.
79+
- All files and directories should be prefixed with `dotnet-` to ensure all file/directory names are globally
80+
- unique across all Dapr documentation.
81+
82+
All pull requests should strive to include both XML documentation in the code clearly indicating what functionality
83+
does and why it's there as well as changes to the published documentation to clarify for other developers how your change
84+
improves the Dapr framework.
2485

2586
## GitHub Dapr Bot Commands
2687

27-
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.
88+
Checkout the [daprbot documentation](https://docs.dapr.io/contributing/daprbot/) for Github commands you can run in this repo for common tasks. For example,
89+
you can comment `/assign` on an issue to assign it to yourself.
90+
91+
## Commit Sign-offs
92+
All code submitted to the Dapr .NET SDK must be signed off by the developer authoring it. This means that every
93+
commit must end with the following:
94+
> Signed-off-by: First Last <[email protected]>
95+
96+
The name and email address must match the registered GitHub name and email address of the user committing the changes.
97+
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.
98+
99+
If you notice that a PR has failed to validate because of a failed DCO check early on in the PR history, please consider
100+
squashing the PR locally and resubmitting to ensure that the sign-off statement is included in the commit history.
101+
102+
# Languages, Tools and Processes
103+
All source code in the Dapr .NET SDK is written in C# and targets the latest language version available to the earliest
104+
supported .NET SDK. As of v1.15, this means that because .NET 6 is still supported, the latest language version available
105+
is [C# version 10](https://learn.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-version-history#c-version-10).
106+
107+
As of v1.15, the following versions of .NET are supported:
108+
109+
| Version | Notes |
110+
| --- |-----------------------------------------------------------------|
111+
| .NET 6 | Will be discontinued in v1.16 |
112+
| .NET 7 | Only supported in Dapr.Workflows, will be discontinued in v1.16 |
113+
| .NET 8 | Will continue to be supported in v1.16 |
114+
| .NET 9 | Will continue to be supported in v1.16 |
115+
116+
Contributors are welcome to use whatever IDE they're most comfortable developing in, but please do not submit
117+
IDE-specific preference files along with your contributions as these will be rejected.

‎daprdocs/content/en/dotnet-sdk-docs/dotnet-ai/_index.md‎

Lines changed: 6 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,83 +1,12 @@
1-
_index.md
2-
31
---
42
type: docs
5-
title: "Getting started with the Dapr AI .NET SDK client"
3+
title: "Dapr AI .NET SDK"
64
linkTitle: "AI"
7-
weight: 10000
8-
description: How to get up and running with the Dapr AI .NET SDK
9-
no_list: true
5+
weight: 50000
6+
description: Get up and running with the Dapr AI .NET SDK
107
---
118

12-
The Dapr AI client package allows you to interact with the AI capabilities provided by the Dapr sidecar.
13-
14-
## Installation
15-
16-
To get started with the Dapr AI .NET SDK client, install the following package from NuGet:
17-
```sh
18-
dotnet add package Dapr.AI
19-
```
20-
21-
A `DaprConversationClient` holes access to networking resources in the form of TCP sockets used to communicate with the Dapr sidecar.
22-
23-
### Dependency Injection
24-
25-
The `AddDaprAiConversation()` method will register the Dapr client ASP.NET Core dependency injection and is the recommended approach
26-
for using this package. This method accepts an optional options delegate for configuring the `DaprConversationClient` and a
27-
`ServiceLifetime` argument, allowing you to specify a different lifetime for the registered services instead of the default `Singleton`
28-
value.
29-
30-
The following example assumes all default values are acceptable and is sufficient to register the `DaprConversationClient`:
31-
32-
```csharp
33-
services.AddDaprAiConversation();
34-
```
35-
36-
The optional configuration delegate is used to configure the `DaprConversationClient` by specifying options on the
37-
`DaprConversationClientBuilder` as in the following example:
38-
```csharp
39-
services.AddSingleton<DefaultOptionsProvider>();
40-
services.AddDaprAiConversation((serviceProvider, clientBuilder) => {
41-
//Inject a service to source a value from
42-
var optionsProvider = serviceProvider.GetRequiredService<DefaultOptionsProvider>();
43-
var standardTimeout = optionsProvider.GetStandardTimeout();
44-
45-
//Configure the value on the client builder
46-
clientBuilder.UseTimeout(standardTimeout);
47-
});
48-
```
49-
50-
### Manual Instantiation
51-
Rather than using dependency injection, a `DaprConversationClient` can also be built using the static client builder.
52-
53-
For best performance, create a single long-lived instance of `DaprConversationClient` and provide access to that shared instance throughout
54-
your application. `DaprConversationClient` instances are thread-safe and intended to be shared.
55-
56-
Avoid creating a `DaprConversationClient` per-operation.
57-
58-
A `DaprConversationClient` can be configured by invoking methods on the `DaprConversationClientBuilder` class before calling `.Build()`
59-
to create the client. The settings for each `DaprConversationClient` are separate and cannot be changed after calling `.Build()`.
60-
61-
```csharp
62-
var daprConversationClient = new DaprConversationClientBuilder()
63-
.UseJsonSerializerSettings( ... ) //Configure JSON serializer
64-
.Build();
65-
```
66-
67-
See the .NET [documentation here]({{< ref dotnet-client >}}) for more information about the options available when configuring the Dapr client via the builder.
68-
69-
## Try it out
70-
Put the Dapr AI .NET SDK to the test. Walk through the samples to see Dapr in action:
71-
72-
| SDK Samples | Description |
73-
| ----------- | ----------- |
74-
| [SDK samples](https://github.com/dapr/dotnet-sdk/tree/master/examples) | Clone the SDK repo to try out some examples and get started. |
75-
76-
## Building Blocks
77-
78-
This part of the .NET SDK allows you to interface with the Conversations API to send and receive messages from
79-
large language models.
80-
81-
### Send messages
82-
9+
With the Dapr AI package, you can interact with the Dapr AI workloads from a .NET application.
8310

11+
Today, Dapr provides the Conversational API to engage with large language models. To get started with this workload,
12+
walk through the [Dapr Conversational AI]({{< ref dotnet-ai-conversation-howto.md >}}) how-to guide.

‎daprdocs/content/en/dotnet-sdk-docs/dotnet-ai/dotnet-ai-conversation-howto.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
type: docs
3+
title: "How to: Create and use Dapr AI Conversations in the .NET SDK"
4+
linkTitle: "How to: Use the AI Conversations client"
5+
weight: 500100
6+
description: Learn how to create and use the Dapr Conversational AI client using the .NET SDK
7+
---
8+
9+
## Prerequisites
10+
- [.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
11+
- [Dapr CLI](https://docs.dapr.io/getting-started/install-dapr-cli/)
12+
- [Initialized Dapr environment](https://docs.dapr.io/getting-started/install-dapr-selfhost)
13+
14+
{{% alert title="Note" color="primary" %}}
15+
16+
.NET 6 is supported as the minimum required for the Dapr .NET SDK packages in this release. Only .NET 8 and .NET 9
17+
will be supported in Dapr v1.16 and later releases.
18+
19+
{{% /alert %}}
20+
21+
## Installation
22+
23+
To get started with the Dapr AI .NET SDK client, install the [Dapr.AI package](https://www.nuget.org/packages/Dapr.AI) from NuGet:
24+
```sh
25+
dotnet add package Dapr.AI
26+
```
27+
28+
A `DaprConversationClient` maintains access to networking resources in the form of TCP sockets used to communicate with the Dapr sidecar.
29+
30+
### Dependency Injection
31+
32+
The `AddDaprAiConversation()` method will register the Dapr client ASP.NET Core dependency injection and is the recommended approach
33+
for using this package. This method accepts an optional options delegate for configuring the `DaprConversationClient` and a
34+
`ServiceLifetime` argument, allowing you to specify a different lifetime for the registered services instead of the default `Singleton`
35+
value.
36+
37+
The following example assumes all default values are acceptable and is sufficient to register the `DaprConversationClient`:
38+
39+
```csharp
40+
services.AddDaprAiConversation();
41+
```
42+
43+
The optional configuration delegate is used to configure the `DaprConversationClient` by specifying options on the
44+
`DaprConversationClientBuilder` as in the following example:
45+
```csharp
46+
services.AddSingleton<DefaultOptionsProvider>();
47+
services.AddDaprAiConversation((serviceProvider, clientBuilder) => {
48+
//Inject a service to source a value from
49+
var optionsProvider = serviceProvider.GetRequiredService<DefaultOptionsProvider>();
50+
var standardTimeout = optionsProvider.GetStandardTimeout();
51+
52+
//Configure the value on the client builder
53+
clientBuilder.UseTimeout(standardTimeout);
54+
});
55+
```
56+
57+
### Manual Instantiation
58+
Rather than using dependency injection, a `DaprConversationClient` can also be built using the static client builder.
59+
60+
For best performance, create a single long-lived instance of `DaprConversationClient` and provide access to that shared instance throughout
61+
your application. `DaprConversationClient` instances are thread-safe and intended to be shared.
62+
63+
Avoid creating a `DaprConversationClient` per-operation.
64+
65+
A `DaprConversationClient` can be configured by invoking methods on the `DaprConversationClientBuilder` class before calling `.Build()`
66+
to create the client. The settings for each `DaprConversationClient` are separate and cannot be changed after calling `.Build()`.
67+
68+
```csharp
69+
var daprConversationClient = new DaprConversationClientBuilder()
70+
.UseJsonSerializerSettings( ... ) //Configure JSON serializer
71+
.Build();
72+
```
73+
74+
See the .NET [documentation here]({{< ref dotnet-client >}}) for more information about the options available when configuring the Dapr client via the builder.
75+
76+
## Try it out
77+
Put the Dapr AI .NET SDK to the test. Walk through the samples to see Dapr in action:
78+
79+
| SDK Samples | Description |
80+
| ----------- | ----------- |
81+
| [SDK samples](https://github.com/dapr/dotnet-sdk/tree/master/examples) | Clone the SDK repo to try out some examples and get started. |
82+
83+
## Building Blocks
84+
85+
This part of the .NET SDK allows you to interface with the Conversations API to send and receive messages from
86+
large language models.
87+
88+
### Send messages
89+
90+

0 commit comments

Comments
 (0)