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.