Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions sdkdocs/dotnet/content/en/dotnet-sdk-docs/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ Put the Dapr .NET SDK to the test. Walk through the .NET quickstarts and tutoria
| [Dapr.Actors](https://www.nuget.org/packages/Dapr.Actors) | [Documentation]({{% ref dotnet-actors %}}) | Create virtual actors with state, reminders/timers, and methods. |
| [Dapr.Actors.AspNetCore](https://www.nuget.org/packages/Dapr.Actors) | [Documentation]({{% ref dotnet-actors %}}) | Create virtual actors with state, reminders/timers, and methods with rich integration with ASP.NET Core. |
| [Dapr.Actors.Analyzers](https://www.nuget.org/packages/Dapr.Actors.Analyzers) | [Documentation]({{% ref dotnet-guidance-source-generators %}}) | A collection of Roslyn source generators and analyzers for enabling better practices and preventing common errors when using Dapr Actors in .NET. |
| [Dapr.Actors.Next](https://www.nuget.org/packages/Dapr.Actors.Analyzers) | [Documentation]({{% ref dotnet-actors-next %}}) | Create virtual actors with state, timers/reminders, state machines, integrated Pub/Sub and more! |
| [Dapr.Actors.Next](https://www.nuget.org/packages/Dapr.Actors.Next) | [Documentation]({{% ref dotnet-actors-next %}}) | Create virtual actors with state, timers/reminders, state machines, integrated Pub/Sub and more! |
| [Dapr.Cryptography](https://www.nuget.org/packages/Dapr.Cryptography) | [Documentation]({{% ref dotnet-cryptography %}}) | Encrypt and decrypt streaming state of any size using Dapr's cryptography building block. |
| [Dapr.Jobs](https://www.nuget.org/packages/Dapr.Jobs) | [Documentation]({{% ref dotnet-jobs %}}) | Create and manage the scheduling and orchestration of jobs. |
| [Dapr.Jobs.Analyzers](https://www.nuget.org/packages/Dapr.Jobs.Analyzers) | [Documentation]({{% ref dotnet-guidance-source-generators %}}) | A collection of Roslyn source generators and analyzers for enabling better practices and preventing common errors when using Dapr Jobs in .NET. |
Expand All @@ -66,8 +66,8 @@ Put the Dapr .NET SDK to the test. Walk through the .NET quickstarts and tutoria
| [Dapr.PluggableComponents.Protos](https://www.nuget.org/packages/Dapr.PluggableComponents.Protos) | | **Note:** Developers needn't install this package directly in their applications. |
| [Dapr.Messaging](https://www.nuget.org/packages/Dapr.Messaging) | [Documentation]({{% ref dotnet-messaging %}}) | Build distributed applications using the Dapr Messaging SDK that utilize messaging components like streaming pub/sub subscriptions. |
| [Dapr.Metadata](https://www.nuget.org/packages/Dapr.Metadata) | [Documentation]({{% ref dotnet-metadata %}}) | Retrieve typed Dapr runtime metadata in .NET through the options pattern. |
| [Dapr.StateManagement](https://www.nuget.org/packages/Dapr.StateManagement) | [Document]({{% ref dotnet-state-management %}}) | Create and manage state in Dapr applications. |
| [Dapr.SecretsManagement](https://www.nuget.org/packages/Dapr.SecretsManagement) | [Document]({{% ref dotnet-secrets %}}) | Retrieve secrets in Dapr applications. |
| [Dapr.StateManagement](https://www.nuget.org/packages/Dapr.StateManagement) | [Documentation]({{% ref dotnet-state-management %}}) | Create and manage state in Dapr applications. |
| [Dapr.SecretsManagement](https://www.nuget.org/packages/Dapr.SecretsManagement) | [Documentation]({{% ref dotnet-secrets %}}) | Retrieve secrets in Dapr applications. |
| [Dapr.Testcontainers](https://www.nuget.org/packages/Dapr.Testcontainers) | [Documentation]({{% ref dotnet-guidance-testcontainers.md %}}) | Run Dapr integration tests using Testcontainers-based harnesses. |
| [Dapr.Workflow](https://www.nuget.org/packages/Dapr.Workflow) | [Documentation]({{% ref dotnet-workflow %}}) | Create and manage workflows that work with other Dapr APIs. |

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@ linkTitle: "Actor serialization"
weight: 300000
description: Necessary steps to serialize your types remoted and non-remoted Actors in .NET
---
# Actor Serialization

The Dapr actor package enables you to use Dapr virtual actors within a .NET application with either a weakly- or strongly-typed client. Each utilizes a different serialization approach. This document will review the differences and convey a few key ground rules to understand in either scenario.

Expand Down Expand Up @@ -152,7 +151,7 @@ there are scenarios where this could be useful. Again, assume that you're taskin
enums. You're using the `JsonStringEnumConverter<TType>` detailed above so you're saving the name of the enum to value instead of a numeric value, but if you change
the enum name, that will introduce a breaking change as the name will no longer match what's in state.

Do note that if you opt into using this approach, you should decorate all your enum members with the `[EnumMeber]` attribute so that the values are consistently applied for each enum value instead
Do note that if you opt into using this approach, you should decorate all your enum members with the `[EnumMember]` attribute so that the values are consistently applied for each enum value instead
of haphazardly. Nothing will validate this at build or runtime, but it is considered a best practice operation.

How can you specify the precise value persisted while still changing the name of the enum member in this scenario? Use a custom `JsonConverter` with an extension method that can pull the value
Expand Down Expand Up @@ -543,7 +542,7 @@ There are additional types that aren't actually primitives but have similar buil
- [Uri](https://learn.microsoft.com/dotnet/api/system.uri)
- [XmlQualifiedName](https://learn.microsoft.com/dotnet/api/system.xml.xmlqualifiedname)

Again, if you want to pass these types around via your actor methods, no additional consideration is necessary as they'll be serialized and deserialized without issue. Further, types that are themselves marked with the (SerializeableAttribute)[https://learn.microsoft.com/dotnet/api/system.serializableattribute] attribute will be serialized.
Again, if you want to pass these types around via your actor methods, no additional consideration is necessary as they'll be serialized and deserialized without issue. Further, types that are themselves marked with the [SerializableAttribute](https://learn.microsoft.com/dotnet/api/system.serializableattribute) attribute will be serialized.

#### Enumeration Types
Enumerations, including flag enumerations are serializable if appropriately marked. The enum members you wish to be serialized must be marked with the [EnumMemberAttribute](https://learn.microsoft.com/dotnet/api/system.runtime.serialization.enummemberattribute) attribute in order to be serialized. Passing a custom value into the optional Value argument on this attribute will allow you to specify the value used for the member in the serialized document instead of having the serializer derive it from the name of the member.
Expand Down Expand Up @@ -575,7 +574,7 @@ But what if you're working with polymorphic types and one of your members is a b

When you apply the [KnownTypeAttribute](https://learn.microsoft.com/dotnet/api/system.runtime.serialization.knowntypeattribute) attribute to a type, you are informing the data contract serializer about what subtypes it might encounter allowing it to properly handle the serialization and deserialization of these types, even when the actual type at runtime is different from the declared type.

```chsarp
```csharp
[DataContract]
[KnownType(typeof(DerivedClass))]
public class BaseClass
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,46 @@ builder.Services.AddDaprConversationClient(); //Registers the `DaprConversationC
var app = builder.Build();
```

Sometimes the developer will need to configure the created client using the various configuration options detailed
above. This is done through an overload that passes in the `DaprConversationClientBuilder` and exposes methods for configuring
the necessary options.

```cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDaprConversationClient((_, daprConversationClientBuilder) => {
//Set the API token
daprConversationClientBuilder.UseDaprApiToken("abc123");
//Specify a non-standard HTTP endpoint
daprConversationClientBuilder.UseHttpEndpoint("http://dapr.my-company.com");
});

var app = builder.Build();
```

Finally, it's possible that the developer may need to retrieve information from another service in order to populate
these configuration values. That value may be provided from a `DaprClient` instance, a vendor-specific SDK or some
local service, but as long as it's also registered in DI, it can be injected into this configuration operation via the
last overload:

```cs
var builder = WebApplication.CreateBuilder(args);

//Register a fictional service that retrieves secrets from somewhere
builder.Services.AddSingleton<SecretService>();

builder.Services.AddDaprConversationClient((serviceProvider, daprConversationClientBuilder) => {
//Retrieve an instance of the `SecretService` from the service provider
var secretService = serviceProvider.GetRequiredService<SecretService>();
var daprApiToken = secretService.GetSecret("DaprApiToken").Value;

//Configure the `DaprConversationClientBuilder`
daprConversationClientBuilder.UseDaprApiToken(daprApiToken);
});

var app = builder.Build();
```

## Sending a conversation request

Use `ConversationInput` and `ConversationOptions` to send prompts to your conversation component:
Expand Down Expand Up @@ -194,43 +234,3 @@ if (result.Usage is not null)
var reasoningTokens = result.Usage.CompletionTokensDetails?.ReasoningTokens;
}
```

Sometimes the developer will need to configure the created client using the various configuration options detailed
above. This is done through an overload that passes in the `DaprConversationClientBuiler` and exposes methods for configuring
the necessary options.

```cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDaprConversationClient((_, daprConversationClientBuilder) => {
//Set the API token
daprConversationClientBuilder.UseDaprApiToken("abc123");
//Specify a non-standard HTTP endpoint
daprConversationClientBuilder.UseHttpEndpoint("http://dapr.my-company.com");
});

var app = builder.Build();
```

Finally, it's possible that the developer may need to retrieve information from another service in order to populate
these configuration values. That value may be provided from a `DaprClient` instance, a vendor-specific SDK or some
local service, but as long as it's also registered in DI, it can be injected into this configuration operation via the
last overload:

```cs
var builder = WebApplication.CreateBuilder(args);

//Register a fictional service that retrieves secrets from somewhere
builder.Services.AddSingleton<SecretService>();

builder.Services.AddDaprConversationClient((serviceProvider, daprConversationClientBuilder) => {
//Retrieve an instance of the `SecretService` from the service provider
var secretService = serviceProvider.GetRequiredService<SecretService>();
var daprApiToken = secretService.GetSecret("DaprApiToken").Value;

//Configure the `DaprConversationClientBuilder`
daprConversationClientBuilder.UseDaprApiToken(daprApiToken);
});

var app = builder.Build();
```
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ var daprEncryptionClient = new DaprEncryptionClientBuilder()
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:
Put the Dapr Cryptography .NET SDK to the test. Walk through the samples to see Dapr in action:

| SDK Samples | Description |
|-------------------------------------------------------------------------------------| ----------- |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ try
}
catch (DaprException daprEx)
{
if (daprEx.TryGetExtendedErrorInfo(out DaprExtendedErrorInfo errorInfo)
if (daprEx.TryGetExtendedErrorInfo(out DaprExtendedErrorInfo errorInfo))
{
Console.WriteLine(errorInfo.Code);
Console.WriteLine(errorInfo.Message);
Expand All @@ -32,11 +32,15 @@ catch (DaprException daprEx)
{
Console.WriteLine(detail.ErrorType);
switch (detail.ErrorType)
{
case ExtendedErrorType.ErrorInfo:
Console.WriteLine(detail.Reason);
Console.WriteLine(detail.Domain);
break;
default:
Console.WriteLine(detail.TypeUrl);
break;
}
}
}
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ builder.Services.AddDaprJobsClient((_, daprJobsClientBuilder) =>
var app = builder.Build();
```

Still, it's possible that whatever values you wish to inject need to be retrieved from some other source, itself registered as a dependency. There's one more overload you can use to inject an `IServiceProvider` into the configuration action method. In the following example, we register a fictional singleton that can retrieve secrets from somewhere and pass it into the configuration method for `AddDaprJobClient` so
Still, it's possible that whatever values you wish to inject need to be retrieved from some other source, itself registered as a dependency. There's one more overload you can use to inject an `IServiceProvider` into the configuration action method. In the following example, we register a fictional singleton that can retrieve secrets from somewhere and pass it into the configuration method for `AddDaprJobsClient` so
we can retrieve our Dapr API token from somewhere else for registration here:

```cs
Expand Down Expand Up @@ -355,8 +355,7 @@ public class MyOperation(DaprJobsClient daprJobsClient)
var oneMonthFromNow = now.AddMonths(1);
var firstOfNextMonth = new DateTime(oneMonthFromNow.Year, oneMonthFromNow.Month, 1, 0, 0, 0);

await daprJobsClient.ScheduleJobAsync("myJobName", )
await daprJobsClient.ScheduleCronJobAsync("myJobName", schedule, dueTime: firstOfNextMonth, cancellationToken: cancellationToken);
await daprJobsClient.ScheduleJobAsync("myJobName", schedule, startingFrom: firstOfNextMonth, cancellationToken: cancellationToken);
}
}
```
Expand All @@ -381,8 +380,7 @@ public class MyOperation(DaprJobsClient daprJobsClient)
var oneMonthFromNow = now.AddMonths(1);
var firstOfNextMonth = new DateTime(oneMonthFromNow.Year, oneMonthFromNow.Month, 1, 0, 0, 0);

await daprJobsClient.ScheduleJobAsync("myJobName", )
await daprJobsClient.ScheduleCronJobAsync("myJobName", schedule, dueTime: firstOfNextMonth, cancellationToken: cancellationToken);
await daprJobsClient.ScheduleJobAsync("myJobName", schedule, startingFrom: firstOfNextMonth, cancellationToken: cancellationToken);
}
}
```
Expand All @@ -401,7 +399,7 @@ public class MyOperation(DaprJobsClient daprJobsClient)
{
public async Task<JobDetails> GetJobDetailsAsync(string jobName, CancellationToken cancellationToken)
{
var jobDetails = await daprJobsClient.GetJobAsync(jobName, canecllationToken);
var jobDetails = await daprJobsClient.GetJobAsync(jobName, cancellationToken);
return jobDetails;
}
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ var app = builder.Build();
```

Sometimes the developer will need to configure the created client using the various configuration options detailed
above. This is done through an overload that passes in the `DaprJobsClientBuiler` and exposes methods for configuring
above. This is done through an overload that passes in the `DaprJobsClientBuilder` and exposes methods for configuring
the necessary options.

```cs
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ We'll run a command that starts both the Dapr sidecar and the .NET program at th
```sh
dapr run --app-id pubsubapp --dapr-grpc-port 4001 --dapr-http-port 3500 -- dotnet run
```
> Dapr listens for HTTP requests at `http://localhost:3500` and internal Jobs gRPC requests at `http://localhost:4001`.
> Dapr listens for HTTP requests at `http://localhost:3500` and internal PubSub gRPC requests at `http://localhost:4001`.

## Register the Dapr PubSub client with dependency injection
The Dapr Messaging SDK provides an extension method to simplify the registration of the Dapr PubSub client. Before
Expand Down Expand Up @@ -79,7 +79,7 @@ builder.Services.AddDaprPubSubClient((_, daprPubSubClientBuilder) => {
var app = builder.Build();
```

Still, it's possible that whatever values you wish to inject need to be retrieved from some other source, itself registered as a dependency. There's one more overload you can use to inject an `IServiceProvider` into the configuration action method. In the following example, we register a fictional singleton that can retrieve secrets from somewhere and pass it into the configuration method for `AddDaprJobClient` so
Still, it's possible that whatever values you wish to inject need to be retrieved from some other source, itself registered as a dependency. There's one more overload you can use to inject an `IServiceProvider` into the configuration action method. In the following example, we register a fictional singleton that can retrieve secrets from somewhere and pass it into the configuration method for `AddDaprPubSubClient` so
we can retrieve our Dapr API token from somewhere else for registration here:

```csharp
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -90,16 +90,16 @@ the default settings.
```cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.DaprPublishSubscribeClient(); //Registers the `DaprPublishSubscribeClient` to be injected as needed
builder.Services.AddDaprPublishSubscribeClient(); //Registers the `DaprPublishSubscribeClient` to be injected as needed
var app = builder.Build();
```

Sometimes the developer will need to configure the created client using the various configuration options detailed above. This is done through an overload that passes in the `DaprJobsClientBuiler` and exposes methods for configuring the necessary options.
Sometimes the developer will need to configure the created client using the various configuration options detailed above. This is done through an overload that passes in the `DaprPublishSubscribeClientBuilder` and exposes methods for configuring the necessary options.

```cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDaprJobsClient((_, daprPubSubClientBuilder) => {
builder.Services.AddDaprPubSubClient((_, daprPubSubClientBuilder) => {
//Set the API token
daprPubSubClientBuilder.UseDaprApiToken("abc123");
//Specify a non-standard HTTP endpoint
Expand Down
Loading
Loading