ITaskPlugin

Interface in Oadm.Sdk.Plugins · Oadm.Sdk.dll

An entry of the device context menu that runs on the server, one task per selected device. Implement it in a *.Server.dll with a public parameterless constructor, or contribute it through ICorePlugin.TaskPlugins.

public interface ITaskPlugin : IPlugin

Extends IPlugin

Guide: Task plugins

Properties

Group

string Group { get; }

Default implementation

Submenu of the device context menu this task appears in. Reuse a TaskGroups constant when one fits; a new name creates a new submenu. Default TaskGroups.General.

MaxParallelDevices

int? MaxParallelDevices { get; }

Default implementation

How many tasks of this plugin may run at the same time (one task = one device); further tasks wait in Queued. Can only lower the server setting Tasks.MaxParallelPerPlugin (default 16): the engine uses the smaller of the two. Null: the server setting. Firmware upgrades use 4.

Permissions

IReadOnlyList<PermissionDefinition> Permissions { get; }

Default implementation

Finer rights inside this task for choices that differ in risk, e.g. Users “add”, “update” and “remove”. Empty (the default): the task has one permission, “task:<id>”. With permissions declared there is no plain “task:<id>”: the menu entry shows when the role has at least one of them, and each run needs the ones ITaskPlugin.RequiredPermissions names.

RequiresDialog

bool RequiresDialog { get; }

When true the client opens the matching ITaskPluginDialog before running.

ShowInMenus

bool ShowInMenus { get; }

Default implementation

False hides the plugin from the device context menu and the toolbar (it is not listed by TaskService.ListTaskPlugins). Used by tasks a core plugin starts itself from its page, e.g. the VAPIX Commander rollout. Default true.

ShowInToolbar

bool ShowInToolbar { get; }

Also a button in the Devices toolbar, enabled when the task can run on the whole selection.

Methods

CanRun

bool CanRun(IDeviceInfo device)

Synchronous filter for the context menu. Plugins that change the device MUST check the required API versions here via device.Apis.Supports(...) (cached from the last full refresh) and again in ITaskPlugin.ExecuteAsync against a fresh ctx.Vapix.GetApiListAsync with Require(...) before the first write.

ExecuteAsync

Task ExecuteAsync(ITaskExecutionContext ctx, IDeviceInfo device, string? payloadJson, CancellationToken ct)

Runs once per device. Return normally for Done, call ITaskExecutionContext.ReportWarning for Done with warnings, throw for Failed. payloadJson comes from the dialog; it is kept in memory only and never persisted, so it may carry secrets such as passwords.

GetTaskName

string GetTaskName(string? payloadJson)

Default implementation

The name of one task in the tasks pane: exactly what this task does with this payload, e.g. “Add user joe”, “Set static IP 10.0.0.60”, “Upgrade firmware to 12.11.77”, not the menu name. At most TaskPluginNames.MaxTaskNameLength characters (the host shortens longer names with an ellipsis and logs a warning). Never include secrets such as passwords: the name is persisted and shown to every user. Called once per Run (all devices of a run share the name); return IPlugin.DisplayName when the payload cannot be read. Default: the display name.

NotSupportedReason

string? NotSupportedReason(IDeviceInfo device)

Default implementation

Why ITaskPlugin.CanRun is false for this device, in plain language: what is missing and what to do, e.g. “Needs AXIS OS 11.11 or later (this device has 10.12.338)” or “Needs the Time API”. The context menu shows the task greyed out with this text as tooltip. Called only when CanRun is false, with cached data only (cheap, no request). A detail about this one device goes at the end in parentheses starting with “this device” (see TaskSupportReasons.ThisDevice): the host leaves it out when it sums up several devices. Null: TaskSupportReasons.Default. Helpers: TaskSupportReasons. Exceptions are caught by the host (default text, logged once). Default: null.

RequiredPermissions

IReadOnlyList<string>? RequiredPermissions(string? payloadJson)

Default implementation

The keys of ITaskPlugin.Permissions one run needs, from its payload (the run is refused before any task starts when the role lacks one). Called only for a plugin that declares permissions; null, empty or an exception means every declared permission (fail closed). Read the payload only, never contact devices.