plugin sdk restricted configuration

About plugin restricted configuration

Role.RestrictedConfiguration stores plugin configuration that requires tighter access than Role.SpecificConfiguration. It provides administrator-managed text through AdminConfigXml and private values that only the owning plugin can retrieve.

Storage options

Restricted configuration has two storage options with different access rules:

Storage	Use it for	Value type	Read access	Write and delete access
AdminConfigXml	Configuration managed by an administrator and consumed by the plugin	string	The owning plugin and administrators with access to the role	The owning plugin and administrators with write access to the role
Private values	Credentials or other values that only the owning plugin should retrieve	SecureString	The owning plugin	The owning plugin and SDK callers authorized to edit the role

Use Role.SpecificConfiguration for ordinary plugin settings that do not require these access restrictions. For more information, see Plugin SDK configuration.

Administrator-managed configuration

AdminConfigXml is a read-write string property. Despite its name, the SDK does not validate the value as XML. Store serialized text that your plugin understands, such as JSON or XML.

The following example stores and retrieves administrator-managed configuration:

using Genetec.Sdk.Entities;

Role role = engine.GetEntity<Role>(pluginRoleGuid);
IRestrictedConfiguration restricted =
    role.RestrictedConfiguration;

restricted.AdminConfigXml =
    "{\"Mode\":\"automatic\"}";

string serializedConfiguration =
    restricted.AdminConfigXml;

Do not use AdminConfigXml for a value that administrators must not be able to read. Use a private value instead.

Private values

A private value associates an application-defined key with a SecureString. The key identifies a value in your plugin's configuration. It is not a property on the Role entity.

Use these members to manage private values:

• SetPrivateValue(string, SecureString) stores or replaces a value.
• GetPrivateValue(string) retrieves a value and reports an error if the key does not exist.
• TryGetPrivateValue(string, out SecureString) returns false if the key does not exist.
• DeletePrivateValue(string) deletes a value.

Only the owning plugin can retrieve private values. An administrator or another authorized SDK caller can set or delete a value without being able to read it.

The SDK returns a read-only copy of the stored SecureString. Dispose the returned value after use. The following example retrieves a required private value from inside the owning plugin and disposes it when the current scope ends:

using System.Security;
using Genetec.Sdk.Entities;

Role role = engine.GetEntity<Role>(pluginRoleGuid);
IRestrictedConfiguration restricted =
    role.RestrictedConfiguration;

using SecureString password =
    restricted.GetPrivateValue("Password");

Use TryGetPrivateValue instead when the value is optional or might not have been configured yet. Both retrieval methods enforce the same access rules.

Detecting changes

Subscribe to Role.FieldsChanged to detect changes to AdminConfigXml or private values. The event is also raised for unrelated changes to the role. FieldsChangedEventArgs exposes IsLocalUpdate, but it does not identify the changed property or private-value key.

Treat the event as a signal to reload the restricted configuration that your plugin uses:

Role.FieldsChanged
├── Re-read AdminConfigXml
└── Re-read each private-value key used by the plugin

After the event is raised:

• Re-read AdminConfigXml, then compare or apply the current serialized configuration.
• Call TryGetPrivateValue for each private-value key the plugin uses. A false result means the value is not configured. Dispose every returned SecureString after use.

Because the notification does not identify what changed, the plugin cannot determine from the event alone whether an administrator changed AdminConfigXml, changed a private value, deleted a private value, or modified an unrelated role property. Subscribe when the plugin loads and unsubscribe when it is disposed.

Access failures

Restricted-configuration operations require a connected SDK engine and a compatible plugin role. The SDK reports an error when the caller lacks the required access, the role does not support the operation, or the engine is disconnected. TryGetPrivateValue prevents an error only for a missing key; it does not bypass connection or access checks.

See also

• Plugin SDK lifecycle: Plugin initialization and disposal phases
• Workspace SDK config pages: Config Tool pages that edit role configuration