AFElement.LoadAttributes Method (PISystem, IList(Guid), IList(AFAttributeTemplate), Object)
- Last UpdatedNov 18, 2025
- 8 minute read
- PI System
- AF SDK 2024 R2
- Developer
Namespace: OSIsoft.AF.Asset
Assembly: OSIsoft.AFSDK (in OSIsoft.AFSDK.dll) Version: 3.1.1.1182
Syntax
public static AFNamedCollectionList<AFElement> LoadAttributes( PISystem system, IList<Guid> ids, IList<AFAttributeTemplate> templates, Object queryDate = null )
Public Shared Function LoadAttributes ( system As PISystem, ids As IList(Of Guid), templates As IList(Of AFAttributeTemplate), Optional queryDate As Object = Nothing ) As AFNamedCollectionList(Of AFElement) Dim system As PISystem Dim ids As IList(Of Guid) Dim templates As IList(Of AFAttributeTemplate) Dim queryDate As Object Dim returnValue As AFNamedCollectionList(Of AFElement) returnValue = AFElement.LoadAttributes(system, ids, templates, queryDate)
public: static AFNamedCollectionList<AFElement^>^ LoadAttributes( PISystem^ system, IList<Guid>^ ids, IList<AFAttributeTemplate^>^ templates, Object^ queryDate = nullptr )
static member LoadAttributes : system : PISystem * ids : IList<Guid> * templates : IList<AFAttributeTemplate> * ?queryDate : Object (* Defaults: let _queryDate = defaultArg queryDate null *) -> AFNamedCollectionList<AFElement>
Parameters
- system
- Type: OSIsoft.AFPISystem
The PISystem to search for the desired objects. - ids
- Type: System.Collections.GenericIListGuid
The list of the element unique identifiers to be loaded. If , then this method does nothing. All elements represented by the unique identifiers in the list must be from the same PISystem. - templates
- Type: System.Collections.GenericIListAFAttributeTemplate
The list of attribute templates which define the attributes of the element to be loaded. If a nested attribute template is specified (its Parent property is not ), then its parents will automatically be loaded. - queryDate (Optional)
- Type: SystemObject
The query date used to load the objects. Specify (the default value) or AFTime.MaxValue for most recent versions of the objects. The value may be an AFTime, DateTime, PITime, String, or numeric. A DateTime (or a DATE will be treated as UTC time if its Kind property is set to Unspecified. Because DATE values from COM or VB6 clients are marshalled as Unspecified, these client applications must convert to UTC prior to marshalling. An integer numeric represents the number of ticks (100-nanosecond intervals) since January 1, 0001. A floating point numeric represents the number of seconds since January 1, 1970 UTC. A String is interpreted as local time, unless it contains a time zone indicator such as a trailing "Z" or "GMT". Strings will be interpreted with the AFTime.Parse Overload methods so that relative formats with intervals ("*", "T+3h", etc.) are also supported. Relative time intervals are based on AFTime.Now.
Return Value
Type: AFNamedCollectionListAFElementA list of the AFElement objects in the PISystem which match the unique identifiers at the specified queryDate with their attributes partially loaded. If the object cannot be found, it will not be returned in the list.
Remarks
This method will ensure that each AFElement for the list of ids are at least partially loaded with each AFAttribute defined by the AFAttributeTemplate specified in the templates list. Use this method after finding a list of element unique identifiers using FindObjectIds(Int32, Int32) method and you only need to access a few of the element's attributes. This will reduce the number of round-trips to the server to load the desired information for each element and reduce the amount of memory used for the loaded element.
If this method is called again for the same element, then any new attributes will be loaded and any existing attributes will be updated. An element will not be updated if it has been modified within the current application and its IsDirty property is .
When using a partially loaded element, you will want to avoid making calls that will cause the element to fully load. The Name or ID can be used when looking up an attribute, but avoid looking up by index or using the Count on the attributes collection. If an attribute is configured with a DataReferencePlugIn, then you should ensure that all of the input attributes used by the DataReference are also at least partially loaded.
| This will only load elements and attributes that have been checked into the server. |
Examples
// Get the Database PISystems myPISystems = new PISystems(); PISystem myPISystem = myPISystems.DefaultPISystem; if (myPISystem == null) throw new InvalidOperationException("Default PISystem was not found."); AFDatabase myDB = myPISystem.Databases[dbName]; if (myDB == null) throw new InvalidOperationException("Database was not found."); // Use attribute value query to find a list of tanks that are // In Service (tanks which are out-of-service have their // Status attribute set to "OS"). int totalCount = 0; using (var search = new AFElementSearch(myDB, "FindTanks", @"Template:'TankAdvanced' |Status:<>'OS'")) { search.CacheTimeout = TimeSpan.FromMinutes(10); // Because we are only going to use a few of the attributes for each // of the elements found, we can reduce the load time and memory space // by just loading the attributes we need. Note that if we inadvertently // use attributes other than these, we will incur a load penalty. AFElementTemplate tankTemplate = myDB.ElementTemplates["Tank"]; AFNamedCollectionList<AFAttributeTemplate> myAttributes = new AFNamedCollectionList<AFAttributeTemplate>(); myAttributes.Add(tankTemplate.AttributeTemplates["Volume"]); myAttributes.Add(tankTemplate.AttributeTemplates["Level"]); myAttributes.Add(tankTemplate.AttributeTemplates["Level|HighLimit"]); myAttributes.Add(tankTemplate.AttributeTemplates["Level|LowLimit"]); // Get today's date and UOMs to be used for converting values. AFTime today = new AFTime("T", CultureInfo.CurrentCulture); UOM bbl = myDB.PISystem.UOMDatabase.UOMs["bbl"]; UOM meter = myDB.PISystem.UOMDatabase.UOMs["m"]; const int pageSize = 1000; int startIndex = 0; IList<Guid> myElementIds = new List<Guid>(pageSize); do { // Find the element IDs and load the attributes we will be using. var results = search.FindObjectIds(startIndex, pageSize: pageSize); myElementIds.Clear(); int c = 0; foreach (Guid id in results) { totalCount++; myElementIds.Add(id); c++; if (c >= pageSize) break; } if (myElementIds.Count == 0) break; AFNamedCollectionList<AFElement> elements = AFElement.LoadAttributes(myPISystem, myElementIds, myAttributes); // Once the elements are loaded, we can process them. foreach (AFElement element in elements) { try { AFAttributeList attributes = new AFAttributeList(); attributes.Add(element.Attributes["Volume"]); attributes.Add(element.Attributes["Level"]); attributes.Add(element.Attributes["Level|HighLimit"]); attributes.Add(element.Attributes["Level|LowLimit"]); AFValues values = attributes.GetValue(today); if (values[0].IsGood && values[1].IsGood && values[2].IsGood && values[3].IsGood) { double volume = (double)values[0].Convert(bbl).Value; double level = (double)values[1].Convert(meter).Value; double high = (double)values[2].Convert(meter).Value; double low = (double)values[3].Convert(meter).Value; Console.WriteLine("Tank Inventory for '{0}' is {1} bbl. %Full={2}", element.Name, volume, 100 * (high - low) / level); } else { Console.WriteLine("Bad data in Tank '{0}'", element.Name); } } catch (FormatException) { Console.WriteLine("Error in Tank '{0}'", element.Name); } } startIndex += myElementIds.Count; // Advance to next page. } while (myElementIds.Count > 0 && myElementIds.Count >= pageSize); } Console.WriteLine("Processed {0} Elements.", totalCount);
' Get the Database Dim myPISystems As New PISystems() Dim myPISystem As PISystem = myPISystems.DefaultPISystem If myPISystem Is Nothing Then Throw New InvalidOperationException("Default PISystem was not found.") End If Dim myDB As AFDatabase = myPISystem.Databases(dbName) If myDB Is Nothing Then Throw New InvalidOperationException("Database was not found.") End If ' Use attribute value query to find a list of tanks that are ' In Service (tanks which are out-of-service have their ' Status attribute set to "OS"). Dim totalCount As Integer = 0 Using search As New AFElementSearch(myDB, "FindTanks", "Template:'TankAdvanced' |Status:<>'OS'") search.CacheTimeout = TimeSpan.FromMinutes(10) ' Because we are only going to use a few of the attributes for each ' of the elements found, we can reduce the load time and memory space ' by just loading the attributes we need. Note that if we inadvertently ' use attributes other than these, we will incur a load penalty. Dim tankTemplate As AFElementTemplate = myDB.ElementTemplates("Tank") Dim myAttributes As New AFNamedCollectionList(Of AFAttributeTemplate)() myAttributes.Add(tankTemplate.AttributeTemplates("Volume")) myAttributes.Add(tankTemplate.AttributeTemplates("Level")) myAttributes.Add(tankTemplate.AttributeTemplates("Level|HighLimit")) myAttributes.Add(tankTemplate.AttributeTemplates("Level|LowLimit")) ' Get today's date and UOMs to be used for converting values. Dim today As New AFTime("T", CultureInfo.CurrentCulture) Dim bbl As UOM = myDB.PISystem.UOMDatabase.UOMs("bbl") Dim meter As UOM = myDB.PISystem.UOMDatabase.UOMs("m") Const pageSize As Integer = 1000 Dim startIndex As Integer = 0 Dim myElementIds As IList(Of Guid) = New List(Of Guid)(pageSize) Do ' Find the elements and load the attributes we will be using. Dim results As IEnumerable(Of Guid) = search.FindObjectIds(startIndex, pageSize:=pageSize) myElementIds.Clear() Dim c As Integer = 0 For Each id As Guid In results totalCount += 1 myElementIds.Add(id) c += 1 If c >= pageSize Then Exit For End If Next If myElementIds.Count = 0 Then Exit Do End If Dim elements As AFNamedCollectionList(Of AFElement) = AFElement.LoadAttributes(myPISystem, myElementIds, myAttributes) ' Once the elements are loaded, we can process them. For Each element As AFElement In elements Try Dim attributes As New AFAttributeList() attributes.Add(element.Attributes("Volume")) attributes.Add(element.Attributes("Level")) attributes.Add(element.Attributes("Level|HighLimit")) attributes.Add(element.Attributes("Level|LowLimit")) Dim values As AFValues = attributes.GetValue(today) If values(0).IsGood AndAlso values(1).IsGood AndAlso values(2).IsGood AndAlso values(3).IsGood Then Dim volume As Double = CDbl(values(0).Convert(bbl).Value) Dim level As Double = CDbl(values(1).Convert(meter).Value) Dim high As Double = CDbl(values(2).Convert(meter).Value) Dim low As Double = CDbl(values(3).Convert(meter).Value) Console.WriteLine("Tank Inventory for '{0}' is {1} bbl. %Full={2}", element.Name, volume, 100 * (high - low) / level) Else Console.WriteLine("Bad data in Tank '{0}'", element.Name) End If Catch generatedExceptionName As FormatException Console.WriteLine("Error in Tank '{0}'", element.Name) End Try Next ' Advance to next page. startIndex += myElementIds.Count Loop While myElementIds.Count > 0 AndAlso myElementIds.Count >= pageSize End Using Console.WriteLine("Processed {0} Elements.", totalCount)
No code example is currently available or this language may not be supported.
No code example is currently available or this language may not be supported.