Skip to main content

Custom C# Object capabilities

Prefer Object capabilities from installed packages for most equipment. Write a custom C# Provider in the current App only when existing capabilities cannot cover a vendor SDK, proprietary protocol, or customer-specific device.

When it fits​

  • A vendor SDK or proprietary communication protocol is required.
  • Connection, cancellation, timeout, and resource cleanup need one owner.
  • Pages and QG need stable, strongly typed business methods.
  • The capability must own explicit persistent state for the current App.

Prefer QG for ordinary sequencing, conditions, and state composition. A general capability that must be reused across projects should be released as a package through the team's process instead of copied between Apps.

Create it​

  1. Select New C# Provider under Resources → Scripts.
  2. Keep source under providers-src/**/*.cs in the project.
  3. Give each Object type a short, engineer-facing capability and equipment description.
  4. Save, resolve current source feedback, and then run Build.

Do not copy compiled output or generated files into the project, and do not infer usage by scanning an installation directory.

Source model​

  • Write a concrete class derived from ObjectBase and declare its Object type with [ObjectType].
  • Public methods form the method surface available to Pages and QG.
  • Use [ObjectMethod] only when a stable ID or display name must be overridden.
  • Declare Object references as [ObjectReference("...")] ObjectRef<T>, where T is another concrete Object type or a reference type published by an installed package.
  • Do not add a parallel interface, abstract capability base, handwritten Provider definition, or manually maintained client class.

Names, descriptions, parameters, and units should express business meaning. Keep register addresses, protocol details, and vendor error codes inside the Provider boundary, then expose stable states, actions, and explicit errors.

Build and acceptance​

Saving source updates the project only. After a change:

  1. Confirm that every related Object property and reference is valid.
  2. Stop the current App.
  3. Run Build and resolve source, type, or reference errors in Problems.
  4. Begin with read-only methods, then test reversible, idempotent, low-risk actions in stages.
  5. Use Start or Debug to verify timeout, cancellation, disconnect, unknown-result, and recovery paths.

The capability enters the delivered version only after Build succeeds. After a device-call timeout or disconnect, never assume the action did not occur; read independent state and obtain site feedback first.

Engineering boundaries​

  • Put credentials only in dedicated settings, never in source, logs, conversations, or version control.
  • Give connection and resources an explicit Provider owner, and release them correctly on Stop, fault, or cancellation.
  • Expose methods that express process intent instead of handing low-level protocol order to a Page.
  • Software stop, exception handling, and permission checks do not replace emergency stops, safety controllers, or process interlocks.

Return to Configure Objects and equipment to finish instance configuration and site acceptance.