wwtools/aot/README.md

ArchestrA Object Toolkit (AOT) Reference Material

LLM-oriented copy of the AVEVA / Wonderware ArchestrA Object Toolkit 2014 v4.0 documentation, converted from the shipped CHM files. Original CHMs live with the AOT install at C:\Program Files (x86)\Wonderware\Toolkits\ArchestrA Object\Docs\.

Layout

• dev-guide/ — Development Guide: chapters and appendices on object design, primitives, attributes, internationalization, building/versioning, debugging, and best practices.
• reference/ — API Reference for the ArchestrA.Toolkit namespace: 69 types (classes, structs, enums) with members and code samples.
• Samples/ — Verbatim AOT 2014 sample Visual Studio solutions (Monitor, Watchdog). C# .sln plus per-tier projects (<Name>, <Name>Configtime, <Name>Editor, <Name>Runtime). Vendor samples — do not modify unless the user asks.

Key concepts to keep straight

When the user asks AOT questions, these distinctions matter:

• ApplicationObject vs. Primitive. ApplicationObjects model real-world equipment (pump, valve). Primitives are reusable code/attribute modules composed into objects. Every object implicitly contains the hidden "Common" primitive.
• Three project tiers per object. An AOT object is split across *Configtime (config-time logic in the IDE), *Runtime (deployed runtime behavior), and *Editor (custom editor form derived from aaBaseEditorForm). The samples follow this exact tier split.
• Build artifacts. Building an ApplicationObject produces an .aaPDF; a reusable primitive produces an .aaPRI. Building requires Visual Studio launched with administrator privileges.
• CMx* value wrappers. Attribute values are not raw .NET types — they are wrapped in CMxString, CMxInteger, CMxFloat, CMxBoolean, etc. (and their *Array siblings). CMxValue/CMxType/CMxVariant sit above them. Indirects use CMxIndirect / CMxIndirectBase / CMxIndirectWriteOnly.
• Event-arg classes (SetHandlerEventArgs, ConfigtimeSetHandlerEventArgs, RuntimeSetHandlerEventArgs, RuntimeStartupEventArgs, etc.) are how user code hooks into the object lifecycle.

Working in this repo

• Treat dev-guide/ and reference/ as authoritative source-of-truth when answering AOT questions; they were converted from the official AVEVA CHMs. Cite the specific Markdown file when relevant.
• The dev-guide chapter ordering matches the original CHM TOC (01- … 09-, then appendix-*). Prefer the most specific file (e.g., attribute categories live in appendix-f-attribute-categories.md, security classifications in appendix-e-security-classifications.md).
• The samples (Monitor, Watchdog) are the canonical worked examples — refer to them for patterns like the three-tier project split, [AObject] / [ObjectAttributes.*] decoration, dictionary (.aaDCT) wiring, and reusable-primitive references ([AReusablePrimitiveRef]).
• No build/test commands apply at this folder root. To actually build a sample, open it in Visual Studio (run as Administrator) with the AOT installed — not from this directory.

Resource index — by task

Task	Go to
Conceptual overview, workflow, UI tour	dev-guide/01-overview.md
Planning an object's shape (attributes, primitives, virtuals)	dev-guide/02-object-design.md
Visual Studio project setup for AOT	dev-guide/03-working-with-projects.md
Defining an ApplicationObject in the Object Designer	dev-guide/04-defining-application-objects.md
Defining a reusable primitive	dev-guide/05-defining-primitives.md
Attribute configuration, set handlers, locking	dev-guide/06-configuring-attributes.md
Localization / multilingual dictionaries	dev-guide/07-internationalizing.md
Building .aaPDF / .aaPRI, versioning, deployment	dev-guide/08-building-and-versioning.md
Attaching the VS debugger to Application Server	dev-guide/09-debugging.md
Programming techniques and recommended workflow	dev-guide/appendix-a-ref-guide.md
Best practices (config-time, run-time, editor, quality, naming)	dev-guide/appendix-a-best-practices.md
Sample project walkthroughs	dev-guide/appendix-b-sample-projects.md
ArchestrA data type catalog (MxDouble, MxBoolean, …)	dev-guide/appendix-d-data-types.md
Security classifications (Free Access, Operate, Tune, …)	dev-guide/appendix-e-security-classifications.md
Attribute categories (Configurable, Calculated, Writeable_*, …)	dev-guide/appendix-f-attribute-categories.md
API lookup for any ArchestrA.Toolkit type	reference/README.md (one file per type)
Worked C# example, three-tier object	Samples/Monitor/
Worked C# example with stats sub-project	Samples/Watchdog/

Common gotchas

These trip people up regularly when working in AOT / System Platform. Long-form versions live in dev-guide/appendix-a-best-practices.md; summarized here so they surface without a doc dive.

• Visual Studio must run as Administrator to build an AOT object. Builds will fail or produce no .aaPDF otherwise.
• No DeviceIntegration objects. AOT 2014 cannot create DI objects — only ApplicationObjects and reusable primitives.
• Galaxy Dump/Load bypasses the editor. Validation must live in OnValidate (config-time), not in the editor form. Editor-only validation is silently skipped during a Galaxy Load.
• Set handlers must accept "set to current value" silently. Rejecting a no-op set causes spurious noise during Dump/Load. Don't reject just because the attribute isn't currently editable.
• Avoid write-only attributes that mutate object shape. If a set handler adds/renames/removes a primitive based on a value that isn't readable back, Dump/Load can't reproduce the object. Expose the state as a readable array instead.
• Engine scans are ~100 µs budgets. Runtime methods must be non-blocking and short. Push slow/blocking work to a thread, and tear those threads down on shutdown — otherwise the engine "overscans".
• Quality is not enforced against value. A Good-quality attribute can still hold NaN; a Bad-quality attribute can hold a normal-looking number. Always check both before using a value.
• Initializing is a substate of Bad. It's transient (until first input arrives). Don't raise "bad value" alarms while a value is Initializing, or you'll get transient alarms on every OnScan.
• Don't write through the wrapper to set quality on Input/Output/InputOutput attributes. Unsupported, and may cause unexpected I/O writes.
• OnScan/OffScan quality discipline. Set CalculatedQuality attributes to Bad on OffScan and Good (or Initializing) on OnScan. Forgetting this leaves stale-but-Good values after the object stops scanning.
• Outputs on startup. The default contract is "object mirrors PLC" — never auto-write to the field on startup/deploy/OnScan unless you're explicitly implementing the rare reverse case. Use ESTARTUPCONTEXT to detect why startup happened.
• Failover/dynamic attributes need explicit calls. Call UpdateDynamicAttributeData() after changing a dynamic attribute's name/type/category/security/set-handler-flag, CheckpointDynamicAttributeData() after value changes, and RestoreDynamicAttributes() from the Startup handler. Skipping any of these silently breaks failover.
• Quarantine state is sticky. An unhandled exception in a primitive freezes its set handlers and Execute until the object is undeployed — attributes are still readable for forensics, but the object is effectively dead.
• Naming restrictions are strict. Spaces and . + - * / \ = ( ) \ ~ ! % ^ & @ [ ] { } | : ; " , < > ?` are invalid in ArchestrA names. Each segment between periods is capped at 32 chars; full attribute names cap at 329 chars, primitives at 255. Localized characters work in external names only, not internal names.
• Logger is for trapped errors and dev diagnostics, not operator info. Per-scan logging will tank performance; gate any retained diagnostic logging behind a flag.
• SendEvent (Application Data Change) is for object-initiated changes only. Don't fire it for user/operator sets — those are already logged by the infrastructure, and you'll double-log.

Maintenance

When adding new tools, samples, or doc sets, update both this README and the root ../CLAUDE.md so the task → resource map stays consistent. See ../DOCS-GUIDE.md for the full doctrine.