Skip to main content

XProtect Smart Client

Smart Client script language and limits

Last Updated: 5 minute read
Version2026 R2
LanguageEnglish

Smart Client scripts use a limited set of C# inside XML. When XProtect Smart Client loads a script file, it checks the file against a list of allowed language features and actions. If any part of the script is invalid, the script body and event triggers will not run; however, the <Login> block is still applied.

File structure

Save the file with the .scs extension, encoded as UTF-8. UTF-8 without BOM is recommended.

Element

Required

Description

<ScriptEngine>

Yes

Root element.

<SchemaVersion>

No

File format version. The default and current version is 1. If a file declares a newer version than the installed XProtect Smart Client supports, the file is refused.

<Login>

No

Login information. See Automate login with scripts.

<Script>

No

Script body. Runs once per login.

<OnEvent Name="…">

No

Event trigger. A file can have one per event.

Note

Legacy elements such as <ScriptExtension> and any <ScriptLanguage> other than C# are refused by the script engine.)

Special characters

XML reads <, >, and & as markup. Wrap script code in <![CDATA[ … ]]>, which is recommended, or replace each character with its XML entity:

Character

Entity

<

&lt;

>

&gt;

&

&amp;

Supported language

Variables

Details

Variables

var, strings, integers, and Boolean values (both var and explicit types such as int are supported).

Conditions

if, else if, else

Loops

for and foreach, with break and continue. foreach works only on actions that return a list.

Operators

+, -, *, /, +=, -=, comparison operators, &&, \|\|, and postfix i++

Strings

Double quotes are recommended (single quotes are accepted by the engine but generate a warning and are not valid C#). Join strings with +.

Comments

// and /* … */

Actions

Action type

Syntax

Notes

Built-in actions

SCS.<Group>.<Action>(<arguments>);

Direct methods provided by the Smart Client script engine (for example, SCS.Application.Minimize();). Most actions take arguments.

The available groups are Application, Views, Browse, Camera, Ptz, MultiWindow, General, and Keyboard.

Views, outputs, events, and PTZ presets

SCS.Invoke("<name>");

The <name> is not the display name shown in the UI. It begins with Views.All., Outputs.All., Events.All., or Ptz.Presets., followed by the configured hierarchy names joined by dots. Any character other than an alphanumeric letter or digit is converted to an underscore (_).

Example: Views.All.Basic_User_Group.All_cameras_Group._10x10_All_cameras

These names are identical across all client display languages. If two items in the same group differ only by special characters (such as Cam 1 and Cam-1), they generate the same identifier, and only one is reachable; rename one of the items to resolve the collision.

MIP plugin actions, by name

SCS.Invoke("<name>");

The <name> consists of the display names that the client shows for the plugin’s groups and action, joined by dots. Because the plugin defines and can localize these names, this form depends on the current client language. If multiple actions share the same name, the script engine refuses the name; call the action by its ID instead.

Actions by ID

SCS.Invoke("<action-id>");

Language-independent unique identifier. Both names and IDs are listed in the generated script reference file when Include configuration items is checked, allowing you to copy the exact ID directly into your script.

To see all the actions available on your system, generate a script reference.

Built-in functions

Function

Description

Thread.Sleep(milliseconds)

Pauses the script without freezing XProtect Smart Client. Accepts 0–30,000 ms.

MessageBox.Show(message), MessageBox.Show(message, caption)

Shows a notification in the notification area. It doesn't block the script or the UI.

DateTime.Now, DateTime.Today, DateTime.Parse(), new DateTime(…)

Date and time values. You can read .Year, .Month, .Day, .Hour, .Minute and .Second.

Guid.Empty, Guid.Parse(), new Guid("<id as text>")

Unique identifier operations. new Guid("<id as text>") requires exactly one string argument.

SCS.Application.WriteLog(level, message)

Writes to MIPLog.txt. The level is Info, Debug, or Error.

SCS.Application.GetEventWindowId()

In an event trigger, returns the ID of the window where the event happened. Returns empty text for the main window, in the script body and in ConfigurationReloadCompleted.

Note: This function can return the ID of an embedded window (such as a view area inside a tab) which no SCS.MultiWindow action recognizes. Compare the ID with known floating window IDs first, or ignore unrecognized window IDs.

Event triggers

Define <OnEvent> blocks inside the <ScriptEngine> root element to react to user actions and workspace changes.

Event

Runs

ConfigurationReloadCompleted

After each completed configuration reload, once views and tabs have settled. Doesn't run at the first login.

SelectedViewChanged

After a different view is selected, in any window.

SelectedViewItemChanged

After a different view item is selected, in any window.

ShownWorkSpaceChanged

After the selected tab changes, or a window switches between Live and Playback.

Note

Some workspaces, such as Alarm Manager and Exports, contain their own embedded view areas. Each embedded view area reports its creation using an ID that does not belong to a floating window. Switching to one of these tabs can therefore run ShownWorkSpaceChanged multiple times (for example, Alarm Manager has two embedded view areas and Exports has one, so switching to Alarm Manager can run the trigger up to three times). Your script should ignore unrecognized window IDs.

  • Event triggers are checked together with the script body. An unknown event name is an error.

  • Event triggers become active before the script body runs and stay active until logout.

  • An event trigger doesn't run again because of a change made by its own actions.

  • Event names are case-sensitive.

  • Each event type can be declared at most once in a script.

  • View or tab changes initiated by the script body (<Script>) also trigger these events.

Limits

Limit

Value

Statements per run

100,000

Run time per run

30 seconds

Thread.Sleep per call

30 seconds

Runs per event trigger

60 per minute. Any more runs in that minute are skipped.

Iterations per loop

10,000

String length

65,536 characters

Each run of the script body or an event trigger has its own limits. If a run reaches a limit or an action fails, the rest of that run stops and the event is logged in MIPLog.txt, but XProtect Smart Client and any other event triggers keep running. When you log out or close XProtect Smart Client, it stops any running scripts.

Not supported

Not supported

Use instead

while, do/while

for

switch

if / else if

try/catch, throw

Verify script… before you deploy the script

Conditional operator (?:)

if / else

Prefix increment (++i)

Postfix increment (i++)

String interpolation ($"…")

+

Comma expressions, multiple variable declarations in for

Separate statements

Arrays, collection literals, and indexing

Not supported

%, *=, /=, %=, bitwise operators

Not supported

Methods, classes, interfaces, namespaces, dynamic

MIP plugin

ScriptExtension

Use built-in script actions or a MIP plugin

Timers, Task, new Thread(), async, delegates, lambdas

Thread.Sleep or event triggers

File, registry, network and process access, reflection

MIP plugin