AF SDK Reference

AFElement Class

Save PDF

TABLE OF CONTENTS

AFElement Class

Save PDF

Last UpdatedNov 18, 2025
22 minute read

AFElement Class

The AFElement is a logical grouping of attributes and child elements.

Inheritance Hierarchy

SystemObject
  OSIsoft.AFAFObject
    OSIsoft.AF.AssetAFBaseElement
      OSIsoft.AF.AssetAFElement
        OSIsoft.AF.ModelingAFModel

Namespace: OSIsoft.AF.Asset
Assembly: OSIsoft.AFSDK (in OSIsoft.AFSDK.dll) Version: 3.1.1.1182

Syntax

[SerializableAttribute]
public class AFElement : AFBaseElement, IAFTransactable, 
	IAFChangedEvent, IAFSecurable, IAFVersionable, IComparable<AFElement>

<SerializableAttribute>
Public Class AFElement
	Inherits AFBaseElement
	Implements IAFTransactable, IAFChangedEvent, IAFSecurable, IAFVersionable, 
	IComparable(Of AFElement)

Dim instance As AFElement

[SerializableAttribute]
public ref class AFElement : public AFBaseElement, 
	IAFTransactable, IAFChangedEvent, IAFSecurable, IAFVersionable, IComparable<AFElement^>

[<SerializableAttribute>]
type AFElement =  
    class
        inherit AFBaseElement
        interface IAFTransactable
        interface IAFChangedEvent
        interface IAFSecurable
        interface IAFVersionable
        interface IComparable<AFElement>
    end

The AFElement type exposes the following members.

Constructors

	Name	Description
	AFElement	Initializes a new instance of the class with default values.
	AFElement(String)	Initializes a new instance of the class with the specified name.
	AFElement(String, AFElementTemplate)	Initializes a new instance of the class with the specified name.

Properties

	Name	Description
	Analyses	This is a collection of analyses that target this element.
	Attributes	This is a collection of attributes that are owned by this element. (Inherited from AFBaseElement.)
	Categories	This is a user-defined collection of categories for the object that can be used for querying and/or reporting purposes. (Inherited from AFBaseElement.)
	CategoriesString	This read-only property returns the list of categories in a string separated by semicolons. (Inherited from AFBaseElement.)
	CheckOutInfo	This read-only property returns the checked out status information for the object.
	Database	This read-only property returns the AFDatabase where this object is defined. (Inherited from AFBaseElement.)
	DefaultAttribute	The default AFAttribute for the AFBaseElement. (Inherited from AFBaseElement.)
	DefaultInputPort	The default input AFPort for the AFBaseElement. (Inherited from AFBaseElement.)
	DefaultOutputPort	The default output AFPort for the AFBaseElement. (Inherited from AFBaseElement.)
	DefaultUndirectedPort	The default undirected AFPort for the AFBaseElement. (Inherited from AFBaseElement.)
	Description	Read/write property that provides a more detailed description of the object. (Inherited from AFBaseElement.)
	Elements	This is a collection of child elements that have been added to this element.
	ExtendedProperties	A dictionary of extended properties that can be used to store application specific information. (Inherited from AFBaseElement.)
	HasAnalyses	This read-only property returns if there are any AFAnalysis objects that target this element.
	HasChildren	This read-only property returns if the element has child elements.
	HasNotifications	This read-only property returns if there are any AFNotification objects that target this element.
	ID	Read-only property that provides a unique identifier for the object to be used for quick access that is not dependent upon the index. (Inherited from AFObject.)
	Identity	This read-only property contains identity of the object. (Inherited from AFObject.)
	IsAnnotated	This property indicates whether this element has any annotations. (Inherited from AFBaseElement.)
	IsDeleted	This read-only property indicates whether the object has been deleted. (Inherited from AFObject.)
	IsDirty	This read-only property indicates whether the object has been modified since the last save to the PI AF Server.
	IsNew	This read-only property indicates whether the object is new and has never been saved to the PI AF Server.
	IsRoot	This read-only property returns if the element is a member of the AFDatabase.Elements collection.
	Name	Read/write property that identifies the name of the object. (Inherited from AFBaseElement.)
	None	An AFElement that represents no element.
	NotificationRules	This is a collection of AFNotificationRule objects that target this element.
	Parent	This property returns the primary parent AFElement that owns the element if it is referenced by another element.
	Parents	Obsolete. This is a collection of all AFElement objects that reference this element.
	PISystem	This read-only property allows access to the PISystem associated with this object. (Inherited from AFObject.)
	Ports	This is a collection of AFPort objects representing the possible connection ports for this element. Ports are used in a AFModel to define an AFConnection between AFBaseElement object. (Inherited from AFBaseElement.)
	QueryDate	This read-only property returns the date used to retrieve the version of an object.
	Security	This read-only property returns the AFSecurity information for the object.
	Template	The AFElementTemplate that was used to define this object. (Inherited from AFBaseElement.)
	Type	This property specifies the base type of the element. (Overrides AFBaseElementType.)
	UniqueID	Read-only property that provides the object's ID as a String. (Inherited from AFObject.)
	Version	This read-only property returns the current version information as an AFVersion object.

Methods

	Name	Description
	ApplyChanges	This method applies the changes to the object and makes those changes available to other objects for the current user.
	ApplyQueryDate	Applies the specified query date to the current object and returns an object in the new context.
	ChangeReferenceType	Change the existing AFReferenceType between a child element or the AFDatabase.
	CheckIn	This method checks in (commits) all the changes to the object by saving the information to persistent storage.
	CheckOut	This method locks the object so that its configuration can be modified.
	CheckOutElements	Check out the objects with the specified unique identifiers at the specified query date.
	CompareTo(Object)	Compares this instance with a specified Object. (Inherited from AFObject.)
	CompareTo(AFObject)	Compares this instance with a specified AFObject. (Inherited from AFObject.)
	ConvertTo	Converts the current object to the specified type of an AFElement.
	CreateDefaultPorts	This method can be used to create the default connection ports based upon the element's type.
	CreateElementTemplate	Create an AFElementTemplate based upon the element. (Inherited from AFBaseElement.)
	Delete	Deletes all versions of this element from the AFDatabase.
	DeleteElements	Delete the objects with the specified unique identifiers.
	Equals(Object)	Determines whether the specified Object is equal to the current object. (Inherited from AFObject.)
	Equals(AFObject)	Indicates whether the current object is equal to another object of the same type. (Inherited from AFObject.)
	FindElement(PISystem, Guid)	Retrieves the AFElement object with the specified unique identifier at the AFTime.MaxValue query date.
	FindElement(PISystem, Guid, Guid)	Retrieves the AFElement object with the specified unique identifier and the specified version id.
	FindElement(PISystem, Guid, Object)	Retrieves the AFElement object with the specified unique identifier at the specified query date.
	FindElements(PISystem, Guid, Object)	Performs a search within the PISystem to retrieve a collection of AFElement objects with the specified list of unique identifiers.
	FindElements(AFDatabase, AFElement, String, AFSearchField, Boolean, AFSortField, AFSortOrder, Int32)	Performs a non-paged text search within the AFDatabase to retrieve a collection of AFElement objects which have a field that matches the specified query string.
	FindElements(AFDatabase, AFElement, String, AFCategory, AFElementTemplate, AFElementType, Boolean, AFSortField, AFSortOrder, Int32)	Obsolete. Performs a search on the element's name within the AFDatabase to retrieve a non-paged collection of AFElement objects that match the specified query string and additional filters.
	FindElements(AFDatabase, AFElement, String, AFSearchField, Boolean, AFSortField, AFSortOrder, Int32, Int32, Int32)	Performs a paged text search within the AFDatabase to retrieve a collection of AFElement objects which have a field that matches the specified query string.
	FindElements(AFDatabase, AFElement, String, String, AFCategory, AFElementTemplate, AFElementType, Boolean, AFSortField, AFSortOrder, Int32)	Obsolete. Performs a search on the element's name within the AFDatabase to retrieve a non-paged collection of AFElement objects that match the specified query string and additional filters.
	FindElements(AFDatabase, AFElement, String, AFCategory, AFElementTemplate, AFElementType, Boolean, AFSortField, AFSortOrder, Int32, Int32, Int32)	Obsolete. Performs a search on the element's name within the AFDatabase to retrieve a paged collection of AFElement objects that match the specified query string and additional filters.
	FindElements(AFDatabase, AFElement, String, String, AFCategory, AFElementTemplate, AFElementType, Boolean, AFSortField, AFSortOrder, Int32, Int32, Int32)	Obsolete. Performs a search on the element's name within the AFDatabase to retrieve a paged collection of AFElement objects that match the specified query string and additional filters.
	FindElementsByAttribute(AFElement, String, AFAttributeValueQuery, Boolean, AFSortField, AFSortOrder, Int32)	Obsolete. Performs a search on the element's name and attribute values within the AFDatabase to retrieve a non-paged collection of AFElement objects.
	FindElementsByAttribute(AFElement, String, AFAttributeValueQuery, Boolean, AFSortField, AFSortOrder, Int32, Int32, Int32)	Obsolete. Performs a search on the element's name and attribute values within the AFDatabase to retrieve a paged collection of AFElement objects.
	FindElementsByAttribute(AFElement, String, String, AFCategory, AFAttributeValueQuery, Boolean, AFSortField, AFSortOrder, Int32)	Obsolete. Performs a search on the element's name, category, and attribute values within the AFDatabase to retrieve a non-paged collection of AFElement objects.
	FindElementsByAttribute(AFElement, String, String, AFCategory, AFAttributeValueQuery, Boolean, AFSortField, AFSortOrder, Int32, Int32, Int32)	Obsolete. Performs a search on the element's name, description, category, and attribute values within the AFDatabase to retrieve a paged collection of AFElement objects.
	FindElementsByCategory(AFDatabase, AFElement, AFCategory, Boolean, AFSortField, AFSortOrder, Int32)	Obsolete. Retrieves a non-paged collection of AFElement objects that have the specified AFCategory defined for the element.
	FindElementsByCategory(AFDatabase, AFElement, AFCategory, Boolean, AFSortField, AFSortOrder, Int32, Int32, Int32)	Obsolete. Retrieves a paged collection of AFElement objects that have the specified AFCategory defined for the element.
	FindElementsByExtendedProperty(AFDatabase, String, IEnumerableGuid, Int32)	Retrieves a list of AFElement objects that have the specified extended property Guid values defined for the element.
	FindElementsByExtendedProperty(AFDatabase, String, IEnumerableString, Int32)	Retrieves a list of AFElement objects that have the specified extended property string values defined for the element.
	FindElementsByPath(IEnumerableString, AFObject)	Retrieves the AFElement objects identified by the path strings as keyed results.
	FindElementsByPath(IEnumerableString, AFObject, IDictionaryString, String)	Retrieves the AFElement objects identified by the path strings as a list.
	FindElementsByReferenceType(AFDatabase, AFElement, AFReferenceType, AFSortField, AFSortOrder, Int32)	Obsolete. Retrieves a non-paged collection of AFElement objects that are referenced by the AFReferenceType under the specified searchRoot or AFDatabase.
	FindElementsByReferenceType(AFDatabase, AFElement, AFReferenceType, AFSortField, AFSortOrder, Int32, Int32, Int32)	Obsolete. Retrieves a paged collection of AFElement objects that are referenced by the AFReferenceType under the specified searchRoot or AFDatabase.
	FindElementsByTemplate(AFDatabase, AFObject, AFElementTemplate, Boolean, AFSortField, AFSortOrder, Int32)	Retrieves a non-paged collection of AFElement objects that are instantiated from the specified AFElementTemplate.
	FindElementsByTemplate(AFDatabase, AFObject, AFElementTemplate, Boolean, AFSortField, AFSortOrder, Int32, Int32, Int32)	Retrieves a paged collection of AFElement objects that are instantiated from the specified AFElementTemplate.
	GetAnalyses	Obsolete. Retrieves a collection of AFAnalysis objects that target this element.
	GetAnnotations	Retrieves a collection of existing AFAnnotation objects belonging to this AFBaseElement. (Inherited from AFBaseElement.)
	GetAttributeByTrait	Retrieves the child AFAttribute with the specified AFAttributeTrait. (Inherited from AFBaseElement.)
	GetAttributesByTrait	Retrieves a list of child AFAttribute objects identified by the specified list of attribute traits. (Inherited from AFBaseElement.)
	GetAttributeValues(PISystem, IListAFAttributeValueQueryID, Object, Boolean, WindowsIdentity)	This method gets a collection of AFValue objects for the specified attributes. The collection will be the same length and in the same order as the objectIds collection.
	GetAttributeValues(PISystem, IListAFAttributeValueQueryID, ClaimsIdentity, Object, Boolean)	This method gets a collection of AFValue objects for the specified attributes. The collection will be the same length and in the same order as the objectIds collection.
	GetElements(AFSortField, AFSortOrder, Int32)	Obsolete. Retrieves a non-paged collection of child AFElement objects that have been added to this element.
	GetElements(AFSortField, AFSortOrder, Int32, Int32, Int32)	Obsolete. Retrieves a paged collection of child AFElement objects that have been added to this element.
	GetEventFrames(Object, Int32, Int32, AFEventFrameSearchMode, String, AFCategory, AFElementTemplate)	Obsolete. Retrieves a paged collection of AFEventFrame objects that reference this element limited to the specified count beginning at the requested start time in the specified direction.
	GetEventFrames(AFSearchMode, Object, Object, String, AFCategory, AFElementTemplate, AFSortField, AFSortOrder, Int32, Int32)	Obsolete. Retrieves a paged collection of AFEventFrame objects that reference this element within the specified time range.
	GetHashCode	Gets the hash code for this instance of the object which is suitable for use in hashing algorithms and data structures like a hash table. (Inherited from AFObject.)
	GetNotifications	Retrieves a collection of AFNotification objects that target this element.
	GetParents(AFSortField, AFSortOrder, Int32)	Retrieves a non-paged collection of AFElement objects that reference this element.
	GetParents(AFCategory, AFSortField, AFSortOrder, Int32)	Retrieves a non-paged collection of AFElement objects that reference this element using the specified AFCategory.
	GetParents(AFReferenceType, AFSortField, AFSortOrder, Int32)	Retrieves a non-paged collection of AFElement objects that reference this element using the specified AFReferenceType.
	GetParents(AFSortField, AFSortOrder, Int32, Int32, Int32)	Retrieves a paged collection of AFElement objects that reference this element.
	GetParents(AFCategory, AFSortField, AFSortOrder, Int32, Int32, Int32)	Retrieves a paged collection of AFElement objects that reference this element using the specified AFCategory.
	GetParents(AFReferenceType, AFSortField, AFSortOrder, Int32, Int32, Int32)	Retrieves a paged collection of AFElement objects that reference this element using the specified AFReferenceType.
	GetPath	Returns the full path to the object, using just the names. (Inherited from AFObject.)
	GetPath(AFObject)	Returns the path to the object relative from another object. (Inherited from AFObject.)
	GetPath(String, IListAFElement)	Get a path to the child elements.
	GetPath(AFEncodeType, AFObject)	Returns the path to the object relative from another object, using the name and/or id as specified by encodeType. (Inherited from AFObject.)
	GetPaths	Get all the full paths to this AFElement.
	GetPaths(String)	Get all the relative paths to this AFElement.
	GetPaths(String, IListAFElement)	Get all paths to the child elements.
	GetReferenceTypes	Retrieves a collection of all AFReferenceType objects that represent types of references from this element to its child elements.
	GetReferenceTypes(AFElement)	Retrieves a collection of AFReferenceType objects that represent types of references between this element and the specified related element.
	GetSecurity	Gets the AFSecurity information of the specified security item associated with the object.
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	IsTypeOf	Checks if the current AFBaseElement is derived from the specified AFElementTemplate. (Inherited from AFBaseElement.)
	LoadAttributes(IListAFElement, IListAFAttributeTemplate)	Partially load the list of elements with the specified attributes.
	LoadAttributes(PISystem, IListGuid, IListAFAttributeTemplate, Object)	Partially loads the AFElement objects for the list of unique identifiers with the specified attributes.
	LoadElementReferences	Loads the AFElement objects referenced by the specified elements.
	LoadElements(IListAFElement)	Loads the specified list AFElement objects.
	LoadElements(PISystem, Guid, Object)	Loads the AFElement objects with the specified unique identifiers at the specified query date.
	LoadElementsToDepth	Loads the specified list AFElement objects and their child elements to the hierarchical depth specified.
	LoadParents	Loads the primary parent of each AFElement specified in the list.
	Persist	This method returns the persistence string for the object. (Inherited from AFObject.)
	Refresh	Refreshes the client with any changes that have been made to the object since loaded.
	ToString	Returns a String that represents the current object. (Inherited from AFObject.)
	UndoCheckOut	This method discards all the changes to the object and all sub-objects since the last call to CheckOut. Any changes since the check out will be lost.

Events

	Name	Description
	Changed	Event is raised when the object or one of its sub-objects is changed.

Remarks

An element can be created from a template, or without a template. When based on a template, the element will derive its initial definition of Categories, Attributes, and Ports from the template. Later modifications to the template will be propagated to all elements created from it. If the template allows it, or if the element was not created from a template, then the element's categories, ports, and attributes can be augmented with additional members. The AFElementSearch class can be used for finding elements.

The AFModel object type is also an element that provides additional information to support models. When created from a template, the AFElementTemplate.InstanceType property specifies the type of element to create.

Child elements can be created using one of the AFElements.Add Overload methods of this object's Elements collection. A child element is related to its parent element by a AFReferenceType. An element may be parented by more than one element, although the reference types may restrict that ability in some instances.

An element implements the IAFVersionable interface which supports creating versions. The following properties and collections are common across all versions of the object:

The following properties and collections are specific to a version of the object:

Auto-created Analyses and NotificationRules will only exist on the latest version of the element. Manually created Analyses and NotificationRules will exist across all versions of the element.

Caution
Using object versions can be expensive in memory usage and performance. Extra memory is required to store the versions in the server and for each version of the object loaded in the client. Performance is degraded because of the extra data to be searched in the server and returned back to the client.

Examples

// This example demonstrates how to create an element and display its information.

// Get the Database
PISystems myPISystems = new PISystems();
AFDatabase myDB = myPISystems.DefaultPISystem.Databases.DefaultDatabase;

// Create an Element
AFElement myElement = myDB.Elements.Add("MyElement*");
myElement.Description = "This is my element";

// Display Element Information
foreach (AFElement CurElement in myDB.Elements)
{
    Console.WriteLine("Name of Element = {0}", CurElement.Name);
    Console.WriteLine("Description = {0}", CurElement.Description);
}

' This example demonstrates how to create an element and display its information.

' Get the Database
Dim myPISystems As New PISystems
Dim myDB As AFDatabase = myPISystems.DefaultPISystem.Databases.DefaultDatabase

' Create an Element
Dim CurElement As AFElement = myDB.Elements.Add("MyElement*")
CurElement.Description = "This is my element"

' Display Element Information
For Each CurElement In myDB.Elements
    Console.WriteLine("Name of Element = {0}", CurElement.Name)
    Console.WriteLine("Description = {0}", CurElement.Description)
Next CurElement

No code example is currently available or this language may not be supported.

AF SDK Reference

AFElement Class

Table of Contents

AFElement Class

Inheritance Hierarchy

Syntax

Constructors

Properties

Methods

Events

Remarks

Examples

Version Information

AFSDK

See Also

Reference

Other Resources

In This Topic

Related Links