dapr / dotnet-sdk

Dapr SDK for .NET

Dapr SDK for .NET

Dapr SDK for .NET allows you to:

• Interact with Dapr applications through a Dapr client
• Build routes and controllers in ASP.NET
• Implement the Virtual Actor model, based on the actor design pattern

This SDK can run locally, in a container, and in any distributed systems environment.

Releases

We publish nuget packages to nuget.org for each release.

Using nugets built locally in your project

<RepoRoot> is the path where you cloned this repository. Nuget packages are dropped under /bin/<Debug|Release>/nugets when you build locally.

Example

# Add Dapr.Actors nuget package
dotnet add package Dapr.Actors -s <RepoRoot>/bin/<Debug|Release>/nugets

# Add Dapr.Actors.AspNetCore nuget package
dotnet add package Dapr.Actors.AspNetCore -s <RepoRoot>/bin/<Debug|Release>/nugets

Documentation

The docs for the Dapr .NET SDK can be found on the Dapr docs site.

Examples

Visit the examples folder for a variety of examples to get you up and running with the Dapr .NET SDK.

Contributing

This repo builds the following packages:

• Dapr.Client
• Dapr.AspNetCore
• Dapr.Actors
• Dapr.Actors.AspNetCore
• Dapr.Extensions.Configuration
• Dapr.Workflow

Prerequisites

Each project is a normal C# project. At minimum, you need .NET 6.0 SDK to build, test, and generate NuGet packages.

Also make sure to reference the .NET SDK contribution guide

macOS/Linux:

On macOS or Linux we recommend Visual Studio Code with the C# Extension. See here for a getting started guide for VS Code and .NET.

Windows:

On Windows, we recommend installing the latest Visual Studio 2019 which will set you up with all the .NET build tools and allow you to open the solution files. Community Edition is free and can be used to build everything here.

Make sure you update Visual Studio to the most recent release.

Build

To build everything and generate NuGet packages, run dotnet cli commands. Binaries and NuGet packages will be dropped in a bin directory at the repo root.

# Build sdk, samples and tests.
dotnet build -c Debug  # for release, -c Release

# Run unit-test
dotnet test

# Generate nuget packages in /bin/Debug/nugets
dotnet pack

Each project can also be built individually directly through the CLI or your editor/IDE. You can open the solution file all.sln in repo root to load all sdk, samples and test projects.

dotnet-sdk's Issues

Throw a custom Exception in Remoting, inner exception will be the serialized exception from user service code.

currently the code throws the exception directly on the client side which rewrites the call stack, the code should wrap the exception in another Exception.
Alternatively an Aggregate Exception can also be thrown with the actual exception as its inner exception. Since user code awaits on tasks, throwing AggregateExceptions will not be right thing to do as await should not throw AggregateException and instead unwrap.

Handle Cloud Events from dapr in aspnetcore integration

Dapr sends events for topics in a cloudevent format, aspnetcore integration should handle it.

Remove Query all statenames from IActorStateManager because it does not behave as expected

need support from runtime dapr/dapr#27

NonRemoting calls: Write exception from Actor method invocation in response body

NonRemoting calls: Write exception from Actor method invocation in response body

Integrate reentrancy for Actors in C# sdk when implemented in Dapr runtime.

needs runtime support dapr/dapr#21

Enable non-RPC method calls using ActorProxy.

Add non-RPC calls using ActorProxy., this allows for cross-language/direct-http of Actors methods.

Change projectUrl in nuspec files once Dapr goes public

Change projecturl to https://github.com/dapr

dotnet-sdk/src/Microsoft.Dapr.Actors.AspNetCore/nuspec/Microsoft.Dapr.Actors.AspNetCore.nuspec

Line 10 in 7c74ed9

<projectUrl>http://aka.ms/actions</projectUrl>

dotnet-sdk/src/Microsoft.Dapr.AspNetCore/nuspec/Microsoft.Dapr.AspNetCore.nuspec

Line 10 in 7c74ed9

<projectUrl>http://aka.ms/actions</projectUrl>

Handle SaveState correctly when an actor method throws an exception.

Relationship with cloudevents/sdk-csharp

I'm digging through #74 - and there's a bunch of non-trivial stuff that CloudEvents do.

It's going to be easy to do #74 because the scope is very limited - but for the longer term, have you had any conversations with the maintainers of that project? Someone who wants to process CloudEvents other than their payload will likely end up using it - I'm hoping we can make that a good experience - however I haven't had the time to go deep into it.

This might be something for @davidfowl and I to chase.

Create documentation to show usage of cs-sdk for actors

Update license to MIT in all .cs files

Handle exceptions in non-remoting calls using proxy.

Update AspnetCore integration to handle namechange

Update AspnetCore integration to handle namechange

Change namespace, assembly & package to Dapr.*

Change namespace, assembly & package to Dapr.* from Microsoft.Dapr.*

Automatically publish Nuget packages on CI build

Support CancellationToken for Remoting calls

Support CancellationToken in actor method calls with remoting. When CancellationToken is cancelled on the client side, the cnacellation token in remote method should be cancelled as well.

Publish nuget package to nuget.org for public preview

For public preview, we need to publish nuget pkg to nuget.org.

• - Review OSS pkg release - https://devdiv.visualstudio.com/DevDiv/_wiki/wikis/DevDiv.wiki?pagePath=%2FProduct%20Development%20Reference%2FNuGet&pageId=972&wikiVersion=GBwikiMaster
• - Publish nuget package to nuget.org

Build only for .net core 3.0

Proposal: This is the proposal to build cs-sdk for .netcore 3.0 only
This would put us on the most latest release for .netcore.

What it means for users: This would mean that user applications have to be built with .netcore 3.0. They will not be able to build full framework version.

What it means for partners during private preview: Since .netcore 3.0 is in preview, partners will have to install preview versions of .netcore 3.0 and preview versions of VS 2019 which support .netcore 3.0. It should be available in 1st week of Sept 2013 in VS 2019.

Cons: Users must target apps for .net core 3.0 (and higher), https://github.com/dotnet/standard/blob/master/docs/versions.md). This means that .net full framework apps cannot be developed using the sdk. .netcore 3.0 would be released in November and is currently in preview.

Pros: Puts us on the latest netcore version and only target .netcore workloads. If we build for .netstandard 2.0, we will have to continue to support it for the foreseeable future which would put extra burden on the team since .Net Framework will not support newer .netstandard versions.
gRPC is supported in aspnetcore starting with aspnetcore 3.0

Amount of work needed: Update the CI, update dev environments and .csproj, use new apis available in .netcore3.0 and aspnetcore 3.0

So it simply boils down to the decision if we want to only support .netcore and not .net full framework moving forward?
cc: @msfussell @shalabhms @lukekim

Update icons in nugets to dapr icon

Update icons in nugets to dapr icon

Serialize actor state as json by default

Serialize actor state as json by default, currently the state is DataContract serializable to follow the Service Fabric reliable Actor models. Change the behavior to serialize state as json and consider adding a compatibility option as an attribute on Actor type for allowing Data Contract serialization for state so that SF Reliable Actors can also run using Dapr

Remove usage of Newtonsoft.Json and use System.Text.Json

after move to .netcore 3.0, remove usage of NewtonsoftJson and use System.Text.Json so that Microsoft.Actions.Actors package has no external pkg dependency.

Samples - Add k8s deployment yaml to demoactor sample

It'd be helpful to create a Dockerfile and detail how one goes about building the C# actor into a Docker image and then deploying it to Kubernetes with Dapr.

Create README

Merge Actor activation and first method/reminder call to user service.

Handle the changes in SDK for runtime behavior change dapr/dapr#219

Scan the Issues/Pull Requests and code for any offensive terms in the context

Run tools to scan for offensive terms in every context and triage the term if found and correct it.

Enable RPC like calls using ActorProxy.

Add codegen to enable RPC like calls using ActorProxy to allow following strongly typed invocations:

// This only creates a proxy object, it does not activate an actor or invoke any methods yet.
IMyActor myActor = ActorProxy.Create<IMyActor>("ActorType")
// This will invoke a method on the actor. 
myActor.DoWorkAsync();

Throw unwrapped exception instead of Aggregate Exception

Currently in the actor remoting based request, the exception is thrown as Aggregate exception which is not adhering to new async/await pattern. The exception should be thrown as unwrapped to the client.

Create preview kit for private preview release

Allow users to plug-in custom serialization for remoting calls.

Fix Dapr API specifications to point to docs reference

Fix Dapr API specifications to point to docs reference

Add integration test for C# actor runtime components with Dapr runtime

Adopt open-telemetry to dotnet sdk

it is good to consider using open-telemetry in dotnet-sdk; open-telemetry for dot-net sdk - https://github.com/open-telemetry/opentelemetry-dotnet

Note: open-telemetry is new telemetry library which replaces open-census and open-tracing. open-census and open-tracing projects will be deprecated soon.

Update Gettting started and aspnetcore samples for name change

Merge Skeleton branch to master branch

With appropriate engineering review/gates/

Moar gRPC?

Now that we've got a gRPC client - do we want to take a more thorough look at the experience for ASP.NET Core + gRPC + Dapr? I happen to know a guy.

At this minimum this would probably be a review of some of the practices + more samples, at the maximum we might identify more features and integration points.

Add generaetd grpc client and a sample showing its usage.

Describe the proposal

Add retry for exceptions for remoting calls.

Split nuget package into Actors and Actors.AspNetcore

Split nuget package into Actors and Actors.AspNetcore so that client side code doesn't need to depend on AspNetcore.

Create test infrastructure for testing CS SDK with Dapr

Modify code to use new name dapr

Add Actor runtime core components to sdk.

Add following runtime components to SDK:

1. Actor registration.
2. Actor activation/deactivation.
3. Method invocation.
4. Reminder/Timer firing.
5. Actor state management.
6. Add routes for activation, deactivation, method, reminder, timer invocation.

ESRP signing step is not working after installing dotnetcore 3.0

ESRP signing is broken because ESRP package is using dotnet core 2.0.

Use Exists api for granular state management to determine of a state exists.

Update nuget package versions

Handle state deserialization from base64 encoded string for data contact serialization.

Setup C# SDK CI build including Nupkg publish

Extend Distributed Tracing Header into Actor SDK.

This allows calls into actors sdk to participate into Distributed Tracing.

Remove signing for binaries and nugets

Change repo name from cs-sdk to dotnet-sdk

Regardless of language, anyone who use dotnet core can use dapr cs-sdk so it makes sense to rename the repo from cs-sdk to dotnet-sdk

Allow users to provide custom serializer foractor states,