AFDataReference Class

AFDataReference is an extension mechanism that allows an attribute to read and write data from sources outside of AF. OSIsoft provides several pre-defined AFDataReferences for accessing PI Points, accessing Table data, computing formulas, and other tasks. It is possible to extend the capabilities of AF by writing custom data references. Common examples of custom AFDataReferences include custom computations or reading and writing data that resides outside the PI System.

Each custom AFDataReference class implementation requires a unique System.Runtime.InteropServices.GuidAttribute attribute to be specified to uniquely identify the data reference in AF. A System.SerializableAttribute and System.ComponentModel.DescriptionAttribute are also required on the class before an AFDataReference can be used in AF.

Custom AFDataReferences can store configuration data as part of an AFAttribute definition, supply a user interface to permit AF users to configure the AFDataReference, and compute values by accessing their own values and using other AFAttributes as inputs. AFDataReferences can also write back data values to data stores outside the PI System. AFDataReferences can differ in the capabilities and complexity of their implementation, and a custom AFDataReference can implement only the subset of capabilities necessary to meet the functional needs of the AFDataReference. Other required functionality is provided by the AFDataReference base class. The capabilities of custom AFDataReferences are exposed using the SupportedMethods and SupportedDataMethods properties.

SupportedMethods is used to define the methods that are exposed in a custom AFDataReference by returning members of the AFDataReferenceMethod enumeration. Only methods that are returned from this property will be called.

OSIsoft.AF.Data support can be added to a custom AFDataReference by overriding SupportedDataMethods and returning the set of OSIsoft.AF.Data methods supported by the AFDataReference. Supported OSIsoft.AF.Data methods are defined using the AFDataMethods enumeration.

Storing configuration is achieved by overriding the default implementation of the ConfigString property. The ConfigString property will be persisted as part of the AFAttribute definition. The ConfigString is usually used to store navigation or connection information to access data values returned in the GetValue(Object, Object, AFAttributeList, AFValues) and GetValues(Object, AFTimeRange, Int32, AFAttributeList, AFValues) methods, or set in the SetValue(Object, AFValue) method.

A configuration user interface can be provided by overriding the EditorType property. The EditorType must be a .NET Type that inherits from System.Windows.Forms. The constructor of the EditorType must accept an AFDataReference and a Boolean in the constructor. The EditorType user interface should modify the ConfigString in the AFDataReference to persist changes.

Retrieval of custom values is enabled by overriding the GetValue(Object, Object, AFAttributeList, AFValues) and GetValues(Object, AFTimeRange, Int32, AFAttributeList, AFValues) methods which are called when the AFAttribute hosting the AFDataReference is instantiated.

Setting of values is accomplished by overriding the SetValue(Object, AFValue) method to write to a data store outside the PI System or to write a transformed/calculated value to a PI Data or PI AF Server. For this method to be called, it must be specified in the SupportedDataMethods property.

A custom AFDataReference can reference other AFAttributes in AF. These references and other persistent configuration data can be configured in the EditorType user interface and stored in the ConfigString property of the AFDataReference. If the custom AFDataReference supports referencing other AFAttributes then the implementer should override the GetInputs(Object) method to return the list of AFAttributes referenced by the custom AFDataReference. When this is done, AF will return the current values of the AFAttributes to the GetValue(Object, Object, AFAttributeList, AFValues) and GetValues(Object, AFTimeRange, Int32, AFAttributeList, AFValues) methods. Implementing GetInputs(Object) will provide better performance than retrieving attribute values in the AFDataReference implementation.

During development a custom AFDataReference can be tested by running the RegPlugin.exe or RegPlugin64.exe tool that is installed with the AF SDK. These tools can be found in the same directory where the AF SDK was installed. It is recommended that initial development of custom AFDataReferences occur on a PI AF Server that is not being used in production. When a custom data reference is tested and ready to be deployed in production, running RegPlugIn.exe or RegPlugin64.exe specifying the production server will deploy the custom AFDataReference.