Table of Contents

DCR Runtime Setup

To create an instance of the DCR Workflow Runtime, you need to provide both configuration and (optionally) access to relevant services. How you do this depends on both your environment (dotnet version, whether you are using dependency-injection) and whether you need just one runtime configuration or many different ones. The latter situation arises in some multi-tenant settings.

Setup variants

We sketch the setup in the relevant cases below.

Single runtime configuration, without DI

Assume we want to build from configuration file config.json.

  1. Add the DCR.Workflow nuget package to your project.
  2. Use DCR.Workflow.Runtime.Create to create Runtime:
var runtime = Runtime.Create(builder => 
    builder.AddJsonConfigurationFile("config.json")
);

Refer to sample.net461 for an example of how to get logging even when the regular .NET logging mechanism is not available.

Single runtime configuration, with DI

  1. Add the DCR.Workflow nuget package to your project.
  2. Add Runtime as a service using . E.g., in a razor application in Program.cs:
Warning

It looks like the sample you are looking for does not exist.

The runtime will be setup as a singleton service. If you are implementing your own effects, and these effects require access to scoped services, change the lifetime of the DCR Runtime to scoped:

builder.Services.AddDcrRuntime(lifetime: ServiceLifeTime.Scoped);

Multiple runtime configurations, with DI

  1. In Program.cs, declare Runtime to be a scoped service:
builder.Services.AddDcrRuntime(lifetime: ServiceLifeTime.Scoped /* ... */);
  1. For each required configuration, load that configuration from json from file or db:
    Stream jsonStream = ...
    RuntimeConfiguration cfg = RuntimeConfiguration.FromJson(jsonStream);

Tip: Specify the top-level configuration key under which configuration is situated using the optional prefix argument. Default is DCR:Workflow.

  1. Implement a IRuntimeConfigurationService and make sure it always reflect the RuntimeConfiguration for the current tenant. The DCR Runtime constructor will consult this service when constructing itself, so to use a Runtime, just inject it:
    Runtime _runtime; 

    public MyClass(Runtime runtime)
    {
	_runtime = runtime

Configuring the Runtime

You can customize which side-effects to use as follows. E.g., to use DCR Runtime with only robots and no other effects:

builder.Services.AddDcrRuntime(builder => 
    builder.AddRobots()
);

Find additional information about customizing (Runtime.Execute)[xref:DCR.Workflow.Runtime.Execute] behaviour here:

Description Type
Setting overall behaviour ServiceCollectionExtensions
Picking individual features RuntimeBuilderExtensions
Tinkering with Runtime.Execute behaviour RuntimeOptions

Customizing logging

The runtime by default records a log of executed events and stores that record as part of the serialized DCR models. This record is essential to supporting replay of DCR models and features that rely on such replay, principally model upgrade, compliance verification, and process search.

To avoid keeping large data objects or sensitive information, you may instruct the runtime to avoid logging data value for activities by setting the tag DCR.Workflow.DoNotLogData on those activities.

Warning

Suppressing data values may cause model replay to fail. Make sure that no expression references the value of an activity that does not log its data values.

You may turn turn off logging entirely, using the configuration option UpdateModelLog. This option is provided exclusively in case you wish to control persistence of logs manually. We do not recommend running DCR models without logging.

Validating configuration

If an activity in a model references effects that are not available in the configuration, or fails to set required parameter for an effect, executing that activity will result in an exception at runtime. To guard agains such runtime exceptions occurring, use the ValidateEffects on Workflow.Runtime to check whether any activities would cause such failures:

    DCR.Workflow.Runtime runtime = ... 
    DCR.Workflow.Model model = ... 

    foreach (var failure in runtime.ValidateEffects(model))
    {
	Console.WriteLine($"Effect {failure.EffectId} on activity {failure.ActivityId} failed: {failure.Error}"); 
    }

The resulting IEnumerable is empty if there are no such failures.

Required services

Description Type Required? Comment
Logging LoggerFactory No
Configuration IConfiguration Yes
HTTP-client HttpClient No Used for HTTP effects

DCR Runtime Usage

Refer to Quick start for quick usage instruction.

At runtime, effects in the DCR Runtime may need access to context and secrets provided by the host system. Context might be the id of the current case or the current user; secrets might be an OAUTH2 machine-generated token associated with the current user necessary for accessing some remote service (via an effect).

DCR implemented effects guarantee that data passed in as secrets cannot possibly be accessed by computations in models. (Data passed in via context might; e.g., using parameter substitution in a Constant effect.)

Context and secrets can be passed in either directly (as parameters to ExecuteAsync and friends), or be specified via a DI-service. In the latter case, provide a IRuntimeContextService in the DI-container of the runtime.

Edit this page