Skip to content

DotNet DLL Workers

The DotNetDllEngine (mime type application/x-dotnet-dll) loads a worker's compiled .NET assembly into an isolated AssemblyLoadContext inside the WorkManager.Runtime process that hosts it. Under NativeAOT it does so in an embedded, JIT-capable CoreCLR; see In-Process DotNet DLL Workers.

How to write a worker (WorkerBase<TInput, TOutput>, codecs, envelopes) is documented with Worker.DevKit: worker-devkit.docs.virtufin.com. This page covers what the Runtime expects of the package.

Packaging

A worker ships as a standard NuGet .nupkg; the engine reads its assembly, target framework and metadata with NuGet.Packaging:

dotnet pack -c Release -o . \
  -p:PackageId=Virtufin.Worker.MyWorker \
  -p:PackageVersion=0.0.1 \
  -p:NuspecProperties="virtufinAbiVersion=2"

lib/<tfm>/<id>.dll is the worker assembly; the engine picks the TFM that best matches its own. Third-party dependencies, Virtufin.Worker.Host included, belong in the nuspec's <dependencies> (what dotnet pack writes from your PackageReferences), not vendored into lib/<tfm>/. Don't reference CloudNative.CloudEvents directly: it comes transitively through Worker.Host, and a direct pin risks a type-identity conflict with the host's copy.

Deploying

Publish the nupkg to the org feed and create the worker from its URL. The private feed needs the virtufin named credential (CodeSource.credential.named, see the API reference); a public URL needs none, e.g. with the Python client:

from virtufin.workmanager import WorkManagerClient

async with WorkManagerClient("localhost", 5002) as client:
    worker_id = await client.create_worker(
        code_source={"url": "https://example.com/Virtufin.Worker.MyWorker.0.0.1.nupkg"},
        mime_type="application/x-dotnet-dll",
        topics=["wrk.myworker.command"],
    )
    await client.start_worker(worker_id)  # deferred until the load finishes

Discovery

The engine takes the worker assembly's one public, non-abstract type implementing Virtufin.Worker.Host.IWorker and creates it with its public parameterless constructor (one whose parameters are all optional does not count). A type in the assembly that fails to load fails the worker with the loader's own messages.

Multiple outputs

IWorker.ProcessAsync returns a list: the Runtime publishes every output in order, each to its own publishtopic (else its ce-type). An empty list publishes nothing. Give every output its own CloudEvent id.

Dependency resolution

At load time NuGetDependencyInstaller (in the DotNetDll bridge) resolves the nuspec's <dependencies>, transitively, and downloads them: third-party packages at the lowest version satisfying each range from DOTNET_DEFAULT_NUGET_SOURCE_URL (default nuget.org), Virtufin.* packages at the highest published stable version from the org feed, so every library fix reaches every worker without a re-pin. The Runtime re-checks those versions every LIBRARY_UPDATE_POLL_SECONDS (default 300) and reloads a worker when one changed.

Host-shared assemblies (Virtufin.Worker.Host, CloudNative.CloudEvents, Virtufin.Api.Client, Virtufin.Naming, and any other assembly the Runtime has loaded) are aliased to the Runtime's own copies, matched by simple name, for type identity, whatever version was resolved. So a worker gets the Runtime's Virtufin.Naming, with the naming fragments embedded in it. A worker that uses a name added in a newer Naming (such as the core worker entity's metrics event, Naming 0.18.1, WorkManager 0.41.6) needs a Runtime that ships it: release and deploy the WorkManager with the new Naming first.

Errors and timing

Case Result
No IWorker implementation The load fails (load-failed lifecycle event)
A dependency fails to resolve or download The load fails before the assembly is loaded
The worker throws The Runtime logs it; the event yields no output

A load with cached dependencies takes well under a second; a cold dependency cache takes seconds (network-bound). The first DotNetDll load in a Runtime pod also starts the embedded CoreCLR, which is done at startup behind /ready.