Table of Contents

Interface IDeviceRegistry

Namespace
Acuit.Pinpoint.IO
Assembly
Acuit.Pinpoint.IO.Abstractions.dll

The device registry.

public interface IDeviceRegistry
Extension Methods

Remarks

The device registry service simplifies implementing and using devices within Acuit Pinpoint by providing a standard device management infrastructure integrated with Acuit Pinpoint's configuration settings and health check systems. The following tasks are performed automatically by Acuit Pinpoint's device registry service, eliminating the need to reimplement these for every new device type:

  • Provide a standard way to configure device settings, automatically reading settings, validating them, and applying them to device instances.
  • Provide feedback about configuration problems via the health check system.
  • Establish and maintain connections with external devices, providing feedback about connection problems via the health check system.

The device registry is used for standard device types used within Acuit Pinpoint, such as bar code scanners and light stacks, but it should also be used for custom devices used by plug-ins such as test equipment.

See Devices for an overview of the device registry.

Devices are tracked as separate collections of device types, where each device collection is identified by a Type of which each device in the collection must be or be derived from. Each Type used to identify a device collection:

  • Must be a nullable reference type.

Devices within a device type collection are expected to be compatible with the device collection Type, although it is not strictly required or enforced. Concrete device types (i.e., the Type of device object instances) can vary within a particular device type collection. Each concrete device type:

  • Must provide a single public constructor, with optional parameters for injectable dependencies (e.g., which can be any dependencies provided by Acuit Pinpoint Workstation or by any loaded plug-ins). This constructor should not throw any exceptions.
  • Should provide public settable properties for any configurable settings, which will be set via Bind(IConfiguration, object) against the applicable configurable section, when appropriate. These properties will be set once, immediately after constructing the device instance. If any configuration settings change after the device instance is created, the device instance will be disposed (if disposable), and a new device instance will be created, as needed.
  • Should use data annotation attributes on the properties or class to provide validation rules. Any validation mechanisms supported by RecursiveValidator can be used. If there are any validation errors, a health check problem will be raised. This validation occurs only once, after the properties have been initialized from the configuration settings.
  • Should use BrowsableAttribute with false (e.g., [Browsable(false)]) on any other public properties that don't represent settable settings so that they will not appear in the device's "Effective Properties" view in Configure Local Hardware in Acuit Pinpoint Workstation.
  • Can use DisplayAttribute to provide additional information in the device's "Effective Properties" view in Configure Local Hardware in Acuit Pinpoint Workstation:
    • Description can be specified to add a description that will appear when the property is selected.
    • Order can be specified to control the order that the properties are listed.
    • Name should not be used, as it will cause the property name, which is used to configure the setting, to not be shown.
    • GroupName should not be used, as groups aren't displayed.
  • Can implement Acuit.Pinpoint.Workstation.Configuration.IInitializableOptions to perform additional options initialization.
  • Should implement IDisposable when appropriate to dispose of any internal disposables or otherwise disconnect from external devices.
  • Should implement IAsyncDisposable if the device disconnection process is itself asynchronous. This will ensure that all devices are completely disconnected before new device instances are created in response to changes in configuration settings. If IAsyncDisposable is implemented, then IDisposable must also be implemented to perform a synchronous dispose.
  • Should implement IConnectedDevice if there is an external device to which a connection must be established, or to otherwise know when to initiate operation after initialization is complete.
  • Should implement IHealthCheck to implement health check logic beyond (1) ensuring the configuration is valid, and (2) ensuring a connection exists (via IConnectedDevice). CheckHealthAsync(HealthCheckRegistration, CancellationToken) must be implemented in a thread-safe manner.

Methods

GetDevice(Type, string)

Gets a registered device of a particular device type.

object GetDevice(Type deviceType, string name = null)

Parameters

deviceType Type

The device type.

name string

An optional device name.

Returns

object

The device, or null if not found. See the remarks for more details.

Remarks

  1. If device type deviceType has never been registered or currently has no configured devices, null will be returned.
  2. Otherwise, if name is null or empty, then the first registered device of type deviceType will be returned.
  3. Otherwise, the first registered device of type deviceType with a name that matches name (case-sensitive) will be returned, or null if a match is not found.

Any configuration changes while the application is running that cause the device list for type deviceType to be regenerated will cause all active devices of that type to be disposed (if they implement IDisposable and recreated from the new configuration. While configuration changes typically only happen during application startup, clients should nonetheless hold on to and use the returned reference for only as long as is needed. Clients can use RegisterRegistrationWatcher(Type, IDeviceTypeRegistrationWatcher) to be notified of configuration changes that affect devices.

Exceptions

ArgumentNullException

deviceType is null.

GetDeviceList(Type)

Gets the list of registered devices of a particular device type.

IReadOnlyList<IRegisteredDevice> GetDeviceList(Type deviceType)

Parameters

deviceType Type

The device type.

Returns

IReadOnlyList<IRegisteredDevice>

The list of devices. If device type deviceType has never been registered or currently has no configured devices, an empty list will be returned.

Remarks

Any configuration changes while the application is running that cause the device list for type deviceType to be regenerated will cause all active devices of that type to be disposed (if they implement IDisposable and recreated from the new configuration. While configuration changes typically only happen during application startup, clients should nonetheless hold on to and use the returned references for only as long as is needed. Clients can use RegisterRegistrationWatcher(Type, IDeviceTypeRegistrationWatcher) to be notified of configuration changes that affect devices.

Exceptions

ArgumentNullException

deviceType is null.

GetDeviceTypeRegistrationOptions(Type)

Gets the device type registration options for a registered device type.

DeviceTypeRegistrationOptions GetDeviceTypeRegistrationOptions(Type deviceType)

Parameters

deviceType Type

The device type.

Returns

DeviceTypeRegistrationOptions

The registration options for the device type, or null if there is no registration for deviceType.

Exceptions

ArgumentNullException

deviceType is null.

GetRegisteredDeviceTypes()

Gets the list of registered device types.

IList<Type> GetRegisteredDeviceTypes()

Returns

IList<Type>

The list of registered device types.

RegisterDeviceType(Type, DeviceTypeRegistrationOptions)

Registers a device type.

IDisposable RegisterDeviceType(Type deviceType, DeviceTypeRegistrationOptions options)

Parameters

deviceType Type

The device type. See the remarks for IDeviceRegistry for requirements and best practices for this type along with concrete device type implementations.

options DeviceTypeRegistrationOptions

The device type registration options.

Returns

IDisposable

A IDisposable that can be used to remove this registration.

Exceptions

ArgumentNullException

deviceType is null.

ArgumentNullException

options is null.

InvalidOperationException

A registration for deviceType already exists.

RegisterRegistrationWatcher(Type, IDeviceTypeRegistrationWatcher)

Registers a registration watcher for a device type.

IDisposable RegisterRegistrationWatcher(Type deviceType, IDeviceTypeRegistrationWatcher watcher)

Parameters

deviceType Type

The device type.

watcher IDeviceTypeRegistrationWatcher

Returns

IDisposable

A IDisposable that can be used to unregister the watcher.

Remarks

This will provide notifications as expected even when this is called before the device type is registered.

Exceptions

ArgumentNullException

deviceType is null.

ArgumentNullException

watcher is null.