Entities, Keys, and the Command Model

In the GENESIS PowerShell interface, every piece of configuration is an entity—a single configurable item such as an asset, a historian tag, a trigger, or a security account. The commands in every provider module operate on entities using a consistent pattern, so once you understand how one module works, you can use them all.

This consistency is what makes the interface predictable. The same verbs act on every entity type, entities are addressed the same way across modules, and parent-child relationships are expressed the same way everywhere. Understanding these shared ideas is the foundation for using the PowerShell interface.

Common Verbs

Each entity type supports the same set of actions, named with a standard PowerShell verb followed by the entity name:

Get—Reads an entity from the configuration, for example Get-AcEquipment.
New—Creates a new entity, for example New-AcEquipment.
Set—Updates an existing entity, for example Set-AcEquipment.
Remove—Deletes an entity, for example Remove-AcEquipment.

The Get verb has three forms.

Get-AcEquipment (the singular form)—Returns one entity that you identify.
Get-AcEquipments (the plural form)—Returns all entities of the specified type.
Get-AcEquipmentsByParent (the by-parent form)—Returns the children of a specified parent. The Command Naming Reference describes these patterns in full.

Identifying an Entity

Commands that act on a single entity, such as Get, Set, and Remove, accept the entity by the -Name parameter, which is flexible about what it receives. You can identify the entity by any of the following:

name, for example Get-GasAlias Building.
key, a handle returned by another command.
identifier in the configuration database, for example Get-GasAlias 1.
the entity itself when it has already been loaded into a variable.

Since the same parameter accepts all of the above, you can read an entity one way and pass the result straight into another command.

Keys

A key is a lightweight reference to an entity. Rather than carrying a whole entity object around, you can store its key in a variable and reuse it wherever a command needs to point at that entity—most often when setting a foreign-key parameter that links one entity to another, such as assigning a collector group to a historian tag.

You can obtain a key in two common ways:

Read an entity and take its Key property, for example (Get-AcEquipment 'Baking line').Key.
Build a key explicitly from a type name and identifier with New-WbKey, or create an empty key with New-WbEmptyKey.

Keys make scripts readable and efficient: you resolve an entity once, store its key, and refer to it by a variable from then on.

Parent-Child Hierarchy

Many entity types are organized into a tree. An asset can contain child assets and properties; a trigger can live inside a trigger folder. Commands express this relationship with a -ParentName parameter on the New and Set commands, which accepts the parent's name, key, or identifier exactly as the -Name parameter does. Creating an entity without a -ParentName places it at the root of its provider's structure.