dapr/dotnet-sdk

Dapr SDK for .NET

Any language, any framework, anywhere

Dapr is a portable, serverless, event-driven runtime that makes it easy for developers to build resilient, stateless and stateful microservices that run on the cloud and edge and embraces the diversity of languages and developer frameworks.

Dapr codifies the best practices for building microservice applications into open, independent, building blocks that enable you to build portable applications with the language and framework of your choice. Each building block is independent and you can use one, some, or all of them in your application.

We are a Cloud Native Computing Foundation (CNCF) incubation project.

Goals

• Enable developers using any language or framework to write distributed applications
• Solve the hard problems developers face building microservice applications by providing best practice building blocks
• Be community driven, open and vendor neutral
• Gain new contributors
• Provide consistency and portability through open APIs
• Be platform agnostic across cloud and edge
• Embrace extensibility and provide pluggable components without vendor lock-in
• Enable IoT and edge scenarios by being highly performant and lightweight
• Be incrementally adoptable from existing code, with no runtime dependency

How it works

Dapr injects a side-car (container or process) to each compute unit. The side-car interacts with event triggers and communicates with the compute unit via standard HTTP or gRPC protocols. This enables Dapr to support all existing and future programming languages without requiring you to import frameworks or libraries.

Dapr offers built-in state management, reliable messaging (at least once delivery), triggers and bindings through standard HTTP verbs or gRPC interfaces. This allows you to write stateless, stateful and actor-like services following the same programming paradigm. You can freely choose consistency model, threading model and message delivery patterns.

Dapr runs natively on Kubernetes, as a self hosted binary on your machine, on an IoT device, or as a container that can be injected into any system, in the cloud or on-premises.

Dapr uses pluggable component state stores and message buses such as Redis as well as gRPC to offer a wide range of communication methods, including direct dapr-to-dapr using gRPC and async Pub-Sub with guaranteed delivery and at-least-once semantics.

Why Dapr?

Writing highly performant, scalable and reliable distributed application is hard. Dapr brings proven patterns and practices to you. It unifies event-driven and actors semantics into a simple, consistent programming model. It supports all programming languages without framework lock-in. You are not exposed to low-level primitives such as threading, concurrency control, partitioning and scaling. Instead, you can write your code by implementing a simple web server using familiar web frameworks of your choice.

Dapr is flexible in threading and state consistency models. You can leverage multi-threading if you choose to, and you can choose among different consistency models. This flexibility enables you to implement advanced scenarios without artificial constraints. Dapr is unique because you can transition seamlessly between platforms and underlying implementations without rewriting your code.

Features

• Event-driven Pub-Sub system with pluggable providers and at-least-once semantics
• Input and output bindings with pluggable providers
• State management with pluggable data stores
• Consistent service-to-service discovery and invocation
• Opt-in stateful models: Strong/Eventual consistency, First-write/Last-write wins
• Cross platform virtual actors
• Secret management to retrieve secrets from secure key vaults
• Rate limiting
• Built-in Observability support
• Runs natively on Kubernetes using a dedicated Operator and CRDs
• Supports all programming languages via HTTP and gRPC
• Multi-Cloud, open components (bindings, pub-sub, state) from Azure, AWS, GCP
• Runs anywhere, as a process or containerized
• Lightweight (58MB binary, 4MB physical memory)
• Runs as a sidecar - removes the need for special SDKs or libraries
• Dedicated CLI - developer friendly experience with easy debugging
• Clients for Java, .NET Core, Go, Javascript, Python, Rust and C++

Get Started using Dapr

See our Getting Started guide over in our docs.

Quickstarts and Samples

• See the quickstarts repository for code examples that can help you get started with Dapr.
• Explore additional samples in the Dapr samples repository.

Community

We want your contributions and suggestions! One of the easiest ways to contribute is to participate in discussions on the mailing list, chat on IM or the bi-weekly community calls. For more information on the community engagement, developer and contributing guidelines and more, head over to the Dapr community repo.

Contact Us

Reach out with any questions you may have and we'll make sure to answer them as soon as possible!

Platform	Link
💬 Instant Message Chat (preferred)
📧 Mailing List	https://groups.google.com/forum/#!forum/dapr-dev
🐤 Twitter	@daprdev

Community Call

Every two weeks we host a community call to showcase new features, review upcoming milestones, and engage in a Q&A. All are welcome!

📞 Visit https://aka.ms/dapr-community-call for upcoming dates and the meeting link.

Videos and Podcasts

We have a variety of keynotes, podcasts, and presentations available to reference and learn from.

📺 Visit https://docs.dapr.io/contributing/presentations/ for previous talks and slide decks.

Contributing to Dapr

See the Development Guide to get started with building and developing.

Repositories

Repo	Description
Dapr	The main repository that you are currently in. Contains the Dapr runtime code and overview documentation.
CLI	The Dapr CLI allows you to setup Dapr on your local dev machine or on a Kubernetes cluster, provides debugging support, launches and manages Dapr instances.
Docs	The documentation for Dapr.
Quickstarts	This repository contains a series of simple code samples that highlight the main Dapr capabilities.
Samples	This repository holds community maintained samples for various Dapr use cases.
Components-contrib	The purpose of components contrib is to provide open, community driven reusable components for building distributed applications.
Dashboard	General purpose dashboard for Dapr
Go-sdk	Dapr SDK for Go
Java-sdk	Dapr SDK for Java
JS-sdk	Dapr SDK for JavaScript
Python-sdk	Dapr SDK for Python
Dotnet-sdk	Dapr SDK for .NET
Rust-sdk	Dapr SDK for Rust
Cpp-sdk	Dapr SDK for C++
PHP-sdk	Dapr SDK for PHP

Code of Conduct

Please refer to our Dapr Community Code of Conduct

dotnet-sdk's Issues

Handle SaveState correctly when an actor method throws an exception.

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

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.

Update AspnetCore integration to handle namechange

Update AspnetCore integration to handle namechange

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>

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();

Handle Cloud Events from dapr in aspnetcore integration

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

Enable non-RPC method calls using ActorProxy.

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

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.

Create README

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.

ESRP signing step is not working after installing dotnetcore 3.0

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

Create documentation to show usage of cs-sdk for actors

Remove signing for binaries and nugets

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

need support from runtime dapr/dapr#27

Setup C# SDK CI build including Nupkg publish

Update license to MIT in all .cs files

Modify code to use new name dapr

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

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

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.

Update nuget package versions

Handle exceptions in non-remoting calls using proxy.

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.

Fix Dapr API specifications to point to docs reference

Fix Dapr API specifications to point to docs reference

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.

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

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.

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

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

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.

Update Gettting started and aspnetcore samples for name change

Change namespace, assembly & package to Dapr.*

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

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

Create test infrastructure for testing CS SDK with Dapr

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

needs runtime support dapr/dapr#21

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.

Add retry for exceptions for remoting calls.

Add generaetd grpc client and a sample showing its usage.

Describe the proposal

Merge Skeleton branch to master branch

With appropriate engineering review/gates/

Create preview kit for private preview release

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

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

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

Update icons in nugets to dapr icon

Update icons in nugets to dapr icon

Extend Distributed Tracing Header into Actor SDK.

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

Automatically publish Nuget packages on CI build

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.

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.

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

Allow users to provide custom serializer foractor states,