AFElement.FindElementsByAttribute Method (AFElement, String, String, AFCategory, AFAttributeValueQuery[], Boolean, AFSortField, AFSortOrder, Int32)

Save PDF

Feedback

HomeAF SDK Reference...NamespacesOSIsoft.AF.AssetAFElement ClassAFElement MethodsFindElementsByAttribute Method AFElement.FindElementsByAttribute Method (AFElement, String, String, AFCategory, AFAttributeValueQuery[], Boolean, AFSortField, AFSortOrder, Int32)

TABLE OF CONTENTS

AFElement.FindElementsByAttribute Method (AFElement, String, String, AFCategory, AFAttributeValueQuery[], Boolean, AFSortField, AFSortOrder, Int32)

Save PDF

Feedback

Last UpdatedSep 18, 2024

Note: This API is now 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.

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

Syntax

[BrowsableAttribute(false)]
[ObsoleteAttribute("This method has been replaced by the 'AFElementSearch' class using the 'Root', 'Name', 'Description', 'Category', and attribute value filters.")]
public static AFNamedCollectionList<AFElement> FindElementsByAttribute(
	AFElement searchRoot,
	string nameFilter,
	string descriptionFilter,
	AFCategory elemCategory,
	AFAttributeValueQuery[] valueQuery,
	bool searchFullHierarchy,
	AFSortField sortField,
	AFSortOrder sortOrder,
	int maxCount
)

<BrowsableAttribute(false)>
<ObsoleteAttribute("This method has been replaced by the 'AFElementSearch' class using the 'Root', 'Name', 'Description', 'Category', and attribute value filters.")>
Public Shared Function FindElementsByAttribute ( 
	searchRoot As AFElement,
	nameFilter As String,
	descriptionFilter As String,
	elemCategory As AFCategory,
	valueQuery As AFAttributeValueQuery(),
	searchFullHierarchy As Boolean,
	sortField As AFSortField,
	sortOrder As AFSortOrder,
	maxCount As Integer
) As AFNamedCollectionList(Of AFElement)

Dim searchRoot As AFElement
Dim nameFilter As String
Dim descriptionFilter As String
Dim elemCategory As AFCategory
Dim valueQuery As AFAttributeValueQuery()
Dim searchFullHierarchy As Boolean
Dim sortField As AFSortField
Dim sortOrder As AFSortOrder
Dim maxCount As Integer
Dim returnValue As AFNamedCollectionList(Of AFElement)

returnValue = AFElement.FindElementsByAttribute(searchRoot, 
	nameFilter, descriptionFilter, elemCategory, 
	valueQuery, searchFullHierarchy, 
	sortField, sortOrder, maxCount)

public:
[BrowsableAttribute(false)]
[ObsoleteAttribute(L"This method has been replaced by the 'AFElementSearch' class using the 'Root', 'Name', 'Description', 'Category', and attribute value filters.")]
static AFNamedCollectionList<AFElement^>^ FindElementsByAttribute(
	AFElement^ searchRoot, 
	String^ nameFilter, 
	String^ descriptionFilter, 
	AFCategory^ elemCategory, 
	array<AFAttributeValueQuery>^ valueQuery, 
	bool searchFullHierarchy, 
	AFSortField sortField, 
	AFSortOrder sortOrder, 
	int maxCount
)

[<BrowsableAttribute(false)>]
[<ObsoleteAttribute("This method has been replaced by the 'AFElementSearch' class using the 'Root', 'Name', 'Description', 'Category', and attribute value filters.")>]
static member FindElementsByAttribute : 
        searchRoot : AFElement * 
        nameFilter : string * 
        descriptionFilter : string * 
        elemCategory : AFCategory * 
        valueQuery : AFAttributeValueQuery[] * 
        searchFullHierarchy : bool * 
        sortField : AFSortField * 
        sortOrder : AFSortOrder * 
        maxCount : int -> AFNamedCollectionList<AFElement>

Parameters

searchRoot

Type: OSIsoft.AF.Asset.AFElement
The root object to start the search. If null, then the search starts at the AFDatabase.

nameFilter

Type: System.String
The name filter string used for finding objects.

The query string (or match pattern) can include regular characters and wildcard characters. Regular characters must match exactly the characters specified in the query string. Wildcard characters can be matched with arbitrary fragments of the query string. Wildcard characters can be escaped using the single backslash (\) character. Use a double backslash (\\) to match a single backslash. The syntax of the query string has the following rules:

If null or empty string, then everything will be matched.
If no wildcards, then an exact match on the query string is performed.
Wildcard * can be placed anywhere in the query string and matches zero or more characters.
Wildcard ? can be placed anywhere in the query string and matches exactly one character.
One character in a set of characters are matched by placing them within [ ]. For example, a[bc] would match 'ab' or 'ac', but it would not match 'ad' or 'abd'.
One character in a set of characters are not matched by placing them within [! ]. For example, a[!bc] would match 'ad', but it would not match 'ab', 'ac', or 'abd'.
A character in a range of characters from first to last are matched using the following syntax: [first - last]. For example, a[a-c] would match 'aa', 'ab', or 'ac', but it would not match 'ad' or 'abc'.

descriptionFilter

Type: System.String
The element description filter string used for finding objects. Only the first 440 characters of the description will be searched. For servers older than 2.7, a NotSupportedException exception will be thrown if this parameter is specified.

If null or empty string, then everything will be matched.
If no wildcards, then an exact match on the query string is performed.
Wildcard * can be placed anywhere in the query string and matches zero or more characters.
Wildcard ? can be placed anywhere in the query string and matches exactly one character.
One character in a set of characters are matched by placing them within [ ]. For example, a[bc] would match 'ab' or 'ac', but it would not match 'ad' or 'abd'.
One character in a set of characters are not matched by placing them within [! ]. For example, a[!bc] would match 'ad', but it would not match 'ab', 'ac', or 'abd'.
A character in a range of characters from first to last are matched using the following syntax: [first - last]. For example, a[a-c] would match 'aa', 'ab', or 'ac', but it would not match 'ad' or 'abc'.

elemCategory

Type: OSIsoft.AF.AFCategory
Specify that the returned elements must have this category. To not filter by element category, then specify null for this parameter. For servers older than 2.7, a NotSupportedException exception will be thrown if this parameter is specified.

valueQuery

Type:OSIsoft.AF.Asset.AFAttributeValueQuery[]
An array of attribute value queries that are ANDed together to find the desired AFElement objects. At least one value query must be specified.

searchFullHierarchy

Type: System.Boolean
Specifies if the search should include objects nested further than the immediate children of the searchRoot.

sortField

Type: OSIsoft.AF.AFSortField
The field or property of the object used to sort the returned collection.

sortOrder

Type: OSIsoft.AF.AFSortOrder
The order that the returned collection is sorted.

maxCount

Type: System.Int32
The maximum number of objects to be returned.

Return Value

Type: AFNamedCollectionList<AFElement>
Returns a collection containing the first page of AFElement objects which match the specified nameFilter string and attribute value query.

Remarks

An object matches the search if the specified nameFilter is found in the object's Name property, the specified elemCategory matches one of the object's categories, and the attribute's value matches the specified attribute value query conditions.

How results are returned from an AFAttributeValueQuery search depends on whether the attribute template IsIndexed property is set and which AFSearchOperator is used for the search. If the attribute template has the IsIndexed property is set to true, then an indexed search value is stored in the PI AF Server which is truncated to 40 characters for string values so that performance is improved. By default, attribute values are not indexed.

Searching attributes with an AFDataReference defined will be slower because the value does not exist on the server. Each attribute's AFDataReference must be executed on the client to obtain the value to evaluate the query. If the AFAttributeTemplate does not define a DataReferencePlugIn and an AFAttribute overrides the template by setting its DataReferencePlugIn, then the attribute's value from the DataReference will not be used when evaluating the query. This could cause unexpected results to be returned from this method. Therefore, an AFDataReference should be defined on the template if it will be used in a query and an AFAttribute will be defining a DataReference.

Use the PISystem.Supports method to check if the PISystem supports the FindElementsByAttribute feature.

Important
This will only search elements that have been checked into the server. If the attribute's IsConfigurationItem property is true, then only the attribute values that have been checked into the server will be searched. The sandbox is not searched. Any modifications to the element that are in the sandbox but not checked in could be updated to the value in the permanent storage.

Important
The value of any attributes used in the query with a configured DataReference will be evaluated on the client. This means that additional results could be removed from those returned from the server and therefore return less than the specified maxCount.

Examples

See the example Loading Partial Elements which illustrates making the FindElementsByAttribute call.

Version Information

AFSDK

Supported in: 2.8.5, 2.8, 2.7.5, 2.7
Obsolete (compiler warning) in 3.1.0
Obsolete (compiler warning) in 3.0.2
Obsolete (compiler warning) in 3.0.1
Obsolete (compiler warning) in 3.0.0
Obsolete (compiler warning) in 2.10.11
Obsolete (compiler warning) in 2.10.5
Obsolete (compiler warning) in 2.10.0
Obsolete (compiler warning) in 2.10
Obsolete (compiler warning) in 2.9.5
Obsolete (compiler warning) in 2.9

AF SDK Reference

Filters

Product Family