platform sdk macros

Managing macros

A Platform SDK application can create, configure, start, and monitor macro entities. Calling Macro.Execute requests execution on a Security Center server; the Platform SDK application does not run the UserMacro code. For developing the UserMacro class, see the Macro SDK developer guide. The macro entity members are in Genetec.Sdk.dll; validating source code before setting it also uses Genetec.Sdk.Scripting.Compiler.dll and Genetec.Sdk.Scripting.Interfaces.dll.

Creating a macro

Create the entity with CreateEntity and cast it to Macro. A new macro contains generated template source. The template's Execute method throws NotImplementedException, so replace the source before calling Execute. Passing a parent entity is not supported. The creation is committed immediately; to batch it with other changes, run it inside a transaction:

public Macro CreateMacro(Engine engine, string name)
{
    return (Macro)engine.CreateEntity(
        name, EntityType.Macro);
}

Setting the source code

SetSourceCode requires an administrator; other users get SdkException with SdkError.UnsufficientPrivilege and the message Only administrators can set source code of the macros. On a published macro, the source is compiled with the system's configured assembly references, and a compilation failure throws SdkException with SdkError.InvalidOperation and the message Source code contains compilation errors. Run compilation with MacroCompiler to get error details. On a draft macro, the source is stored without compiling. Read the stored source back through the get-only SourceCode property.

To obtain detailed compiler diagnostics before setting the source, compile it with the macro assembly references configured in Security Center:

public bool TrySetSource(
    Engine engine, Macro macro, string source)
{
    SystemConfiguration systemConfiguration =
        engine.GetEntity<SystemConfiguration>(
            SystemConfiguration.SystemConfigurationGuid);

    IReadOnlyCollection<string> assemblyReferences =
        systemConfiguration.GetMacroAssemblyReferences();

    MacroCompiler compiler = new MacroCompiler();
    ICompilationDetails details = compiler.Compile(
        source,
        assemblyReferences,
        CodeLanguage.CsharpRoslyn);

    if (!details.IsSuccess)
    {
        foreach (IError error in details.Errors)
        {
            Console.WriteLine(
                $"{error.Line}:{error.Column} " +
                error.Message);
        }

        return false;
    }

    macro.SetSourceCode(source);
    return true;
}

Default parameters

The macro's parameters are defined by its compiled source: every public property with a public setter whose type is int, uint, double, long, float, bool, string, Guid, or DateTime becomes a parameter. A property named PermissionSet is reserved and never becomes a parameter. Recompiling preserves the values of parameters that keep the same name and type.

The SetDefaultThreshold and RunWithThreshold examples assume that the compiled UserMacro class declares public int Threshold { get; set; }.

Read the values through DefaultParameters. The collection is read-only, so you cannot add or remove parameters, but each MacroParameter.Value is writable. Each read of DefaultParameters returns a new copy. Changing a value in that copy does not update the macro's saved defaults; pass the modified collection to SetDefaultParameters to save the changes. The string indexer throws KeyNotFoundException for an unknown name, and assigning a value of the wrong type throws InvalidCastException. SetDefaultParameters applies values whose names and types match the compiled parameters and ignores the rest. The change is committed immediately unless a transaction is active:

public void SetDefaultThreshold(Macro macro, int threshold)
{
    Macro.ReadOnlyMacroParameterCollection parameters = macro.DefaultParameters;
    parameters["Threshold"].Value = threshold;
    macro.SetDefaultParameters(parameters);
}

Executing and monitoring

Execute() runs the macro with its default parameter values; Execute(parameters) runs it with the values you pass. Both submit the request without waiting for the macro to finish and return an execution identifier when Security Center accepts the request. If Security Center rejects the request without returning an execution identifier, the methods throw InvalidOperationException. This can occur, for example, when the logged-on user lacks the Execute macros privilege or the macro is a draft:

public Guid RunWithThreshold(Macro macro, int threshold)
{
    Macro.ReadOnlyMacroParameterCollection parameters = macro.DefaultParameters;
    parameters["Threshold"].Value = threshold;
    return macro.Execute(parameters);
}

Use the static Macro.MacroStarted, Macro.MacroCompleted, and Macro.MacroAborted events to monitor macro executions received by the Engine. To monitor a particular macro entity, use its Started, Completed, and Aborted instance events. Each event provides MacroEventArgs: MacroGuid identifies the macro, and InstanceGuid identifies the execution and matches the identifier returned by Execute.

Engine.GetMacroInstances() returns a snapshot of the running macro instances. Each MacroInstance provides Entity, ExecutionId, Instigator, and StartTime. AbortInstance starts an asynchronous abort request for one execution; it does not confirm that the execution has ended before returning. Handle the matching Aborted event or call GetMacroInstances() again to confirm that the execution identifier is no longer present:

public void RequestAbortForMacroInstances(Engine engine, Macro macro)
{
    foreach (MacroInstance instance in engine.GetMacroInstances())
    {
        if (instance.Entity == macro.Guid)
        {
            macro.AbortInstance(instance.ExecutionId);
        }
    }
}

Event-to-action rules run macros through the ExecuteMacroAction; see Event-to-actions.

Draft and published macros

IsDraft reports the state. Both SetMacroToDraft and PublishMacro require the logged-on user to be an administrator. SetMacroToDraft turns a macro into a draft, whose source is stored without compiling and which cannot be executed. PublishMacro recompiles the stored source; when publishing fails, the macro returns to draft. Both methods throw SdkException with SdkError.InvalidOperation and the message Feature is not yet available. when the system disables draft macros.

See also

• Macro SDK overview: Config Tool procedures, execution contexts, and automation triggers.
• Macros in the Web SDK: Creating, starting, and stopping macros over the Web SDK.