dohertj2/wwtools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
wwtools/aot/reference/ConfigtimeBase.md
T
Joseph Doherty 32f26272ae Initial commit: Wonderware / System Platform tools and reference 
Five tools under one repo, all docs organized per DOCS-GUIDE.md:

- aalogcli: .NET 4.8 / x86 CliFx CLI for reading System Platform binary
  logs (*.aaLGX) for LLM debugging, built on aaOpenSource/aaLog. Commands:
  last, tail, range, unread, fields. Stable JSON envelope under --llm-json.
  Build template under lib/build/ for rebuilding aaLogReader.dll.

- aot: ArchestrA Object Toolkit 2014 v4.0 reference material. Dev guide
  (Markdown converted from CHM), API reference for the ArchestrA.Toolkit
  namespace, and the Monitor / Watchdog VS sample solutions.

- graccesscli: .NET 4.8 / x86 CliFx CLI that automates Galaxy
  configuration via the ArchestrA GRAccess COM interop. Includes session
  daemon, IPC protocol, and llm-json envelope contract.

- grdb: SQL/DDL exploration of the Galaxy Repository database. DDL
  captures, reusable queries, hierarchy / contained-name <-> tag-name
  translation notes.

- histdb: LLM-oriented reference for AVEVA Historian retrieval. INSQL
  linked-server, extension tables, every wwXxx time-domain extension,
  every retrieval mode, alarm/event SQL recipes, REST API. Distilled
  from the 243-page Historian Retrieval Guide.

Root contains:
- CLAUDE.md: thin index pointing into each tool's README.
- DOCS-GUIDE.md: doctrine for organizing docs for LLM consumption.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-03 18:22:20 -04:00

1023 lines
22 KiB
Markdown
Raw Permalink Blame History

# ConfigtimeBase Class
Namespace: `ArchestrA.Toolkit`
This class provides functionality such as Configtime events handling, Migrate, Dumpload, Primitive wrappers(for Input,Output, and InputOutput primitives), Virtual primitives and Dynamic attributes management.
**Syntax**
```csharp
public class ConfigtimeBase : AObjectBase, IObjectEvent2, IObjectEvent, IMigratePrimitive, IPrimitivePackage, IValueSupport
```
**Remarks**
ConfigtimeBase class is derived from AObjectBase class which is part of the ArchestrA.Toolkit namespace.
## ConfigtimeBase Properties
### AutoRecoverySupported Property
Provides indication of support for recovery of Dynamic Attributes and Virtual Primitives during dump/load.
**Syntax**
```csharp
public bool AutoRecoverySupported { get; }
```
**Returns**
bool
### IsTemplate Property
Provides indication that a template or an instance is executing the code.
**Syntax**
```csharp
public bool IsTemplate { get; }
```
**Returns**
bool
true if template is executing the code.
false if instance is executing the code.
### ParentPrimitive Property
Provides access to the parent Primitive ID.
**Syntax**
```csharp
public short ParentPrimitive { get; }
```
**Returns**
short
### Site Property
Provides access to the ConfigtimeSite.
**Syntax**
```csharp
public IPrimitivePackageSite5 Site { get; }
```
**Returns**
IPrimitivePackageSite5
**Remarks**
The toolkit provides wrappers for most of the commonly used functions such as AddAttribute and so on.
An advanced user can access additional functions from IPrimitivePackageSite5 using the Site Property.
Example to access a primitive's execution order from configtime code:
```csharp
Site.GetPrimitivesExecutionOrder(sPrimitiveId, out pExecutionOrderInfo);
```
### ThisPrimitive Property
Provides access to the current Primitive ID.
**Syntax**
```csharp
public short ThisPrimitive { get; }
```
**Returns**
short
## ConfigtimeBase Methods
### AddAttribute Method (string, MxAttributeCategory, MxDataType, bool, bool)
Provides a method to add a Dynamic Attribute. Use this function if you are adding a non-array attribute.
**Syntax**
```csharp
public bool AddAttribute(
string name,
MxAttributeCategory category,
MxDataType type,
bool cfgSetHandler,
bool rtSetHandler
);
```
**Parameters**
Refer to the section AddAttribute Method Parameters and Return Value.
**Returns**
Refer to the section AddAttribute Method Parameters and Return Value.
### AddAttribute Method (string, MxAttributeCategory, MxDataType, int, bool, bool)
Provides a method to add a Dynamic Attribute Array.
**Syntax**
```csharp
public bool AddAttribute(
string name,
MxAttributeCategory category,
MxDataType type,
int length,
bool cfgSetHandler,
bool rtSetHandler
);
```
**Parameters**
Refer to the section AddAttribute Method Parameters and Return Value.
**Returns**
Refer to the section AddAttribute Method Parameters and Return Value.
### AddAttribute Method (string, MxAttributeCategory, MxDataType, MxPropertyLockedEnum, MxSecurityClassification, bool, bool, bool, short)
Provides a detailed method to add a Dynamic Attribute. Use this function to add a non-array attribute that you want to exclude from Dump/Load.
**Syntax**
```csharp
public bool AddAttribute(
string name,
MxAttributeCategory category,
MxDataType type,
MxPropertyLockedEnum lockType,
MxSecurityClassification security,
bool cfgSetHandler,
bool rtSetHandler,
bool excludeFromDumpLoad,
out short id
);
```
**Parameters**
Refer to the section AddAttribute Method Parameters and Return Value.
**Returns**
Refer to the section AddAttribute Method Parameters and Return Value.
### AddAttribute Method (string, MxAttributeCategory, MxDataType, MxPropertyLockedEnum, MxSecurityClassification, int, bool, bool, bool, short)
Provides a detailed method to add a Dynamic Attribute Array. Use this function to add a array attribute that you want to exclude from Dump/Load.
**Syntax**
```csharp
public bool AddAttribute(
string name,
MxAttributeCategory category,
MxDataType type,
MxPropertyLockedEnum lockType,
MxSecurityClassification security,
int length,
bool cfgSetHandler,
bool rtSetHandler,
bool excludeFromDumpLoad,
out short id
);
```
**Parameters**
Refer to the section AddAttribute Method Parameters and Return Value.
**Returns**
Refer to the section AddAttribute Method Parameters and Return Value.
### AddPrimitive Method (string, string, string)
Provides a method to add a Virtual Primitive instance from a Virtual Primitive using the Primitives Internal Name.
This method can be used to add a virtual instance of child primitive, reusable primitive and utility (Input/Output) primitives.
**Syntax**
```csharp
public bool AddPrimitive(
string virtualPrimitiveName,
string internalName,
string externalName
);
```
**Parameters**
**`virtualPrimitiveName`**
Name of the virtual primitive.
**`internalName`**
New internal name of the instance.
**`externalName`**
New External name of the instance.
**Returns**
true if the Primitive instance addition is successful.
false if the user tries to add a primitive with the same name of an existing primitive or if the user tries to create an instance of the non-virtual primitive.
### AddPrimitive Method (string, string, string, bool, short)
Detailed method to add a virtual primitive instance at configtime.This method can be used to add a virtual instance of child primitive, reusable primitive and Input/Output primitives.
Use this function in case if the ID of the newly created primitive is required and/or you need to exclude the primitive from Dump/Load.
**Syntax**
```csharp
public bool AddPrimitive(
string virtualPrimitiveName,
string internalName,
string externalName,
bool excludeFromDumpLoad,
out short id
);
```
**Parameters**
**`virtualPrimitiveName`**
Name of the virtual primitive.
**`internalName`**
New internal name of the instance.
**`externalName`**
New External name of the instance.
**`excludeFromDumpLoad`**
true excludes the virtual Primitive from Dumpload.
**`id`**
fills the out parameter with the primitive ID of newly created virtual primitive.
**Returns**
bool
true if the Primitive instance addition is successful.
false if the Primitive instance addition fails.
### DeleteAttribute Method
Provides a method to delete a dynamic attribute by name.
**Syntax**
```csharp
public bool DeleteAttribute(string name);
```
**Parameters**
**`name`**
Name of the dynamic attribute.
**Returns**
bool
true if the dynamic attribute deletion is successful.
false if the user tries to delete a non-existing dynamic attribute.
### DeletePrimitive Method
Provides a method to delete a Virtual Primitive instance by the Primitives Internal Name.
**Syntax**
```csharp
public bool DeletePrimitive(string internalName);
```
**Parameters**
**`internalName`**
Internal name of the virtual primitive instance.
**Returns**
bool
true if Primitive instance deletion is successful.
false if the user tries to delete a non-existing primitive instance or the user tries to delete a non-virtual primitive.
### GetHeirarchialName Method
Provides a method to get the Hierarchical Name of the primitive.
**Syntax**
```csharp
public string GetHeirarchialName(short primitiveId);
```
**Parameters**
**`primitiveId`**
Primitive Id.
**Returns**
string
**Remarks**
For an object, the method returns null.
### GetVirtualPrimitiveIdByInternalName Method
Provides a method to get the ID of a child Virtual Primitive using the Primitives Internal Name. If more than one child primitive is found the first one is returned.
**Syntax**
```csharp
public short GetVirtualPrimitiveIdByInternalName(string internalName);
```
**Parameters**
**`internalName`**
internal name of the virtual primitive instance.
**Returns**
short
Returns the primitive ID of the virtual primitive.
**Remarks**
This method finds child primitives.
### IsDynamicPrimitive Method
Determines if the primitive is an instance of a virtual primitive.
**Syntax**
```csharp
public bool IsDynamicPrimitive(short id);
```
**Parameters**
**`id`**
Primitive ID.
**Returns**
bool
true if the primitive is of type dynamic otherwise false.
### IsStaticPrimitive Method
Determines if the primitive is static.
**Syntax**
```csharp
public bool IsStaticPrimitive(short id);
```
**Parameters**
**`id`**
Primitive ID.
**Returns**
bool
true if the primitive is of type static otherwise false.
### IsVirtualPrimitive Method
Determines if the primitive is virtual.
**Syntax**
```csharp
public bool IsVirtualPrimitive(short id);
```
**Parameters**
**`id`**
Primitive ID.
**Returns**
bool
true if the primitive is of type virtual, otherwise false.
### RecoverAttributes Method
Provides a method to recreate dynamic attributes and Virtual Primitives Instances from information stored in the value.This is not typically used by the Object Developer and is added in auto-generated code by the toolkit when Dump/Load Support option is enabled.
An automatically inserted Set Handler associated with the CMxInternalDumpLoadData Attribute calls the RecoverAttributes method. The Set Handler executes during Galaxy Load.The Set Handler is inserted by the toolkit for all Attributes of type CMxInternalDumpLoadData. RecoverAttributes recreates the Dynamic Attributes and Primitives stored in the CMxInternalDumpLoadData Attribute. The values associated with the Dynamic Attributes are recovered from the Dump/Load CSV file.
**Syntax**
```csharp
public void RecoverAttributes(CMxValue value);
```
**Parameters**
**`value`**
The value contains the stored Attribute information (Name/DataType) for the Attributes.
### RenamePrimtive Method
Provides a method to rename a Virtual Primitive instance using the Primitives Internal Name.
**Syntax**
```csharp
public bool RenamePrimtive(
string primitiveInternalName,
string newInternalName,
string newExternalName
);
```
**Parameters**
**`primitiveInternalName`**
Internal name of the virtual primitive instance.
**`newInternalName`**
New Internal name of the virtual primitive instance.
**`newExternalName`**
New External name of the virtual primitive instance.
**Returns**
bool
true if the primitive internal and external names are renamed.
**Remarks**
The user can rename an instance of a Virtual Primitive at Configtime and check the result using PrimitiveResult.message and PrimitiveResult.status.
### UpdateRecoveryData Method
Provides a method to update dynamic attributes name, category, security, type, cfgSetHandler, and runtime SetHandler information for Dump/Load. Also updates Child Primitives external and internal names for Dump/Load.
The user should call this method each time a dynamic attribute's shape (name, category, security, type, cfgSetHandler and runtime SetHandler information) is changed.
**Syntax**
```csharp
public void UpdateRecoveryData();
```
**Remarks**
Example of the usage of UpdateRecoveryData in configtime code:
```csharp
Set("DynamicAttributeName", EATTRIBUTEPROPERTY.idxAttribPropSecurityClassification, MxSecurityClassification.MxSecurityTune);
UpdateRecoveryData();
```
### CanRenamePrimtive Method
Provides a method to check if a virtual primitive instance can be renamed.
**Syntax**
```csharp
public bool CanRenamePrimtive(string primitiveInternalName, string newExternalName)
```
**Parameters**
**`primitiveInternalName`**
Internal name of the virtual primitive instance.
**`newExternalName`**
New External name of the virtual primitive instance.
**Returns**
bool
true if the primitive instance can be renamed with the External name.
### CanDeletePrimitive Method
Provides a method to check if a virtual primitive instance can be deleted.
**Syntax**
```csharp
public bool CanDeletePrimitive(string internalName)
```
**Parameters**
**`internalName`**
Internal name of the virtual primitive instance.
**Returns**
bool
true if the primitive instance can be deleted with the Internal name.
### CanAddPrimitive Method
Provides a method to check if a virtual primitive instance can be added.
**Syntax**
```csharp
public bool CanAddPrimitive(string virtualPrimitiveName, string internalName, string externalName)
```
**Parameters**
**`virtualPrimitiveName`**
Internal name of the virtual primitive.
**`internalName`**
New Internal name of the virtual primitive instance.
**`externalName`**
New External name of the virtual primitive instance.
**Returns**
bool
true if the primitive instance can be added with the Internal and External names.
## ConfigtimeBase Attributes
### AttributeResult Attribute
Holds the result of the last Attribute Action.
**Syntax**
```csharp
public ConfigtimeBase.AttrOpStatus AttributeResult;
```
**Remarks**
AttributeResult.status.bstrReason, AttributeResult.status.eResult will give the information on last Attribute Action.
### PrimitiveResult Attribute
Holds the result of the last Primitive Action.
**Syntax**
```csharp
public ConfigtimeBase.PrimOpStatus PrimitiveResult;
```
**Remarks**
PrimitiveResult.message, PrimitiveResult.status will give the information on last Primitive Action.
## ConfigtimeBase Events
### ConfigtimeDynamic Event
This event fires when the value of a dynamic attribute is changed at configtime.
The toolkit automatically generates code to register the delegate <objectname>Configtime_ConfigtimeDynamic for this event.
Add a separate case to implement set handler code for each your dynamic attributes in this delegate.
**Syntax**
```csharp
public event ConfigtimeDynamicSetHandlerDelegate ConfigtimeDynamic;
```
**Remarks**
This is a common set handler for all the configtime dynamic attributes. Object developer has to handle code separately for each dynamic attribute as required.
### ConfigtimeInitialize Event
This event fires at the time of Object Initialization.
The toolkit automatically generates code to register the delegate <objectname>Configtime_ConfigtimeInitialize for this event.
Any custom initialization can be done here, including caching of attribute values, primitive IDs and so on.
**Syntax**
```csharp
public event ConfigtimeInitializeDelegate ConfigtimeInitialize;
```
### ConfigtimeMigrate Event
ConfigtimeMigrate event is fired when importing a template into a Galaxy that contains a previous version of the template. The template of the previous version must be derived or instantiated for migrate to execute.
The toolkit automatically generates code to register the delegate <objectname>Configtime_ConfigtimeMigrate for this event.
Using the MigrateHandler parameter, user can access the previous version's attribute information in this delegate.
**Syntax**
```csharp
public event MigrateDelegate ConfigtimeMigrate;
```
### ConfigtimeValidate Event
ConfigtimeValidate event is fired when the Object is validated.
Validate sets the warning or error text for the object. It is used to check conditions that would not be checked using a SetHandler, such as reporting that an object was not configured, or that combinations of attributes are illegal.
The toolkit automatically generates code to register the delegate <objectname>Configtime_ConfigtimeValidate for this event.
**Syntax**
```csharp
public event ConfigtimeValidateDelegate ConfigtimeValidate;
```
### PostAssign Event
PostAssign event will be fired for a child object after it is assigned to a parent node. The Child node has to be configured to support the PostAssign event.
The toolkit automatically generates code to register the delegate <objectname>Configtime_PostAssign for this event.
**Syntax**
```csharp
public event GeneralDelegate PostAssign;
```
### PostAssignTo Event
PostAssignTo event will be fired for a parent object after a child node is assigned to it. The Parent node has to be configured to support the PostAssignTo event.
The toolkit automatically generates code to register the delegate <objectname>Configtime_PostAssignTo for this event.
**Syntax**
```csharp
public event GeneralDelegate PostAssignTo;
```
### PostCheckIn Event
PostCheckIn event is fired after an Object is checked-in.
The toolkit automatically generates code to register the delegate <objectname>Configtime_PostCheckIn for this event.
**Syntax**
```csharp
public event SupportEventDelegate PostCheckIn;
```
### PostCreate Event
PostCreate event is fired after an object (or derived template) is created.
The toolkit automatically generates code to register the delegate <objectname>Configtime_PostCreate for this event.
One purpose for implementing this method is to ensure that the initial state of the primitive is valid.
**Syntax**
```csharp
public event ObjectEventDelegate PostCreate;
```
### PostDelete Event
PostDelete event is fired after the object is deleted.
The toolkit automatically generates code to register the delegate <objectname>Configtime_PostDelete for this event.
**Syntax**
```csharp
public event SupportEventDelegate PostDelete;
```
### PostDeploy Event
PostDeploy event is fired after the object is deployed.
The toolkit automatically generates code to register the delegate <objectname>Configtime_PostDeploy for this event.
**Syntax**
```csharp
public event SupportEventDelegate PostDeploy;
```
### PostRename Event
PostRename event is fired after the object is renamed.
The toolkit automatically generates code to register the delegate <objectname>Configtime_PostRename for this event.
**Syntax**
```csharp
public event RenameDelegate PostRename;
```
### PostUnassign Event
PostUnassign event will be fired on the child object after it is unassigned from its parent.
The toolkit automatically generates code to register the delegate <objectname>Configtime_PostUnassign for this event.
**Syntax**
```csharp
public event GeneralDelegate PostUnassign;
```
### PostUnassignFrom Event
PostUnassignFrom event will be fired on the parent object after a child object is unassigned from it.
The toolkit automatically generates code to register the delegate <objectname>Configtime_PostUnassignFrom for this event.
**Syntax**
```csharp
public event GeneralDelegate PostUnassignFrom;
```
### PostUndeploy Event
PostUndeploy will be fired after the object is undeployed.
The toolkit automatically generates code to register the delegate <objectname>Configtime_PostUndeploy for this event.
**Syntax**
```csharp
public event SupportEventDelegate PostUndeploy;
```
### PreAssignTo Event
PreAssignTo will be fired on a parent object before the child object is assigned to it.
The toolkit automatically generates code to register the delegate <objectname>Configtime_PreAssignTo for this event.
**Syntax**
```csharp
public event GeneralDelegate PreAssignTo;
```
### PreCheckIn Event
PreCheckIn event will be fired before the object is checked-in.
The toolkit automatically generates code to register the delegate <objectname>Configtime_PreCheckIn for this event.
**Syntax**
```csharp
public event SupportEventDelegate PreCheckIn;
```
### PreDelete Event
PreDelete event is fired before the object is deleted.
The toolkit automatically generates code to register the delegate <objectname>Configtime_PreDelete for this event.
**Syntax**
```csharp
public event SupportEventDelegate PreDelete;
```
### PreDeploy Event
PreDeploy event is fired before the object is deployed.
The toolkit automatically generates code to register the delegate <objectname>Configtime_PreDeploy for this event.
**Syntax**
```csharp
public event DeployDelegate PreDeploy;
```
### PreRename Event
PreRename event is fired before the object is renamed.
The toolkit automatically generates code to register the delegate <objectname>Configtime_PreRename for this event.
**Syntax**
```csharp
public event RenameDelegate PreRename;
```
### PreUnassign Event
PreUnassign event is fired before the object is unassigned.
The toolkit automatically generates code to register the delegate <objectname>Configtime_PreUnassign for this event.
**Syntax**
```csharp
public event GeneralDelegate PreUnassign;
```
### PreUndeploy Event
PreUndeploy event is fired before the object is undeployed.
The toolkit automatically generates code to register the delegate <objectname>Configtime_PreUndeploy for this event.
**Syntax**
```csharp
public event ConfigtimeValidateDelegate ConfigtimeValidate;
```
### PreValidate Event
PreValidate event is fired before the object is validated.
The toolkit automatically generates code to register the delegate <objectname>Configtime_PreValidate for this event.
**Syntax**
```csharp
public event ObjectEventDelegate PreValidate;
```
## Nested Type: InputOutputPrimitive Class
This class provides a wrapper for InputOutput Primitive.
**Syntax**
```csharp
public class InputOutputPrimitive : ConfigtimeBase.PrimitiveWrapper
```
### InputOutputPrimitive Properties
### InputOutputPrimitive Constructor
### InputOutputPrimitive Methods
## Nested Type: InputPrimitive Class
This class provides a wrapper for Input Primitive.
**Syntax**
```csharp
public class InputPrimitive : ConfigtimeBase.PrimitiveWrapper
```
### InputPrimitive Properties
### InputPrimitive Constructor
### InputPrimitive Methods
## Nested Type: OutputPrimitive Class
This class provides a wrapper for Output Primitive.
**Syntax**
```csharp
public class OutputPrimitive : ConfigtimeBase.PrimitiveWrapper
```
### OutputPrimitive Properties
### OutputPrimitive Constructor
### OutputPrimitive Methods
## Nested Type: PrimitiveWrapper Class
Base class of all IO Wrappers.
**Syntax**
```csharp
public class PrimitiveWrapper
```
### PrimitiveWrapper Property
### PrimitiveWrapper Constructor
### PrimitiveWrapper Methods
## Nested Type: AttrOpStatus Struct
Provides access to the result value associated with the following Attribute operations.
- AddAttribute
- DeleteAttribute
**Syntax**
```csharp
public struct AttrOpStatus
```
### AttrOpStatus Attributes
## Nested Type: PrimOpStatus Struct
Provides access to the result value associated with the following Primitive operations to remove the need to add message parameters for each operation.
- AddPrimitive
- CanAddPrimitive
- CanRenamePrimitive
- GetVirtualPrimitiveIdByInternalName
- DeletePrimitive
- RenamePrimitive
**Syntax**
```csharp
public struct PrimOpStatus
```
### PrimOpStatus Attributes
Reference in New Issue View Git Blame Copy Permalink