AF SDK Reference

AFSecurity.SetSecurityString Method

Save PDF

TABLE OF CONTENTS

AFSecurity.SetSecurityString Method

Save PDF

Last UpdatedNov 18, 2025
5 minute read

Sets the access control security rules for the associated object.

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

Syntax

public void SetSecurityString(
	string accessRules,
	bool applyToChildren
)

Public Sub SetSecurityString ( 
	accessRules As String,
	applyToChildren As Boolean
)

Dim instance As AFSecurity
Dim accessRules As String
Dim applyToChildren As Boolean

instance.SetSecurityString(accessRules, 
	applyToChildren)

public:
void SetSecurityString(
	String^ accessRules, 
	bool applyToChildren
)

member SetSecurityString : 
        accessRules : string * 
        applyToChildren : bool -> unit

Parameters

accessRules

Type: SystemString
The new access control rules for the associated object.

applyToChildren

Type: SystemBoolean

This parameter only has an effect if the associated object is an AFElement or AFEventFrame that has been added to a collection and saved to the server. For all other objects or if this parameter is , then the new access permissions are only applied to the associated object.

If and the associated object is an AFElement or AFEventFrame that has been added to a collection, then the access permissions for any parent or child objects might also change. The behavior depends on the reference type:

For weak reference types, access permissions are never inherited. So, if you change the access permissions for the parent object, the permissions for the child object are not affected. Similarly, if you change the access permissions for the child object, the permissions for the parent object are not affected.
For parent-child reference types, child permissions change when you change the permissions on the primary parent permissions. Parent permissions do not change when you change child permissions. Child elements that have a parent-child reference to the parent element, but are owned by a different element, are not in the primary path and will not have their permissions modified.

If the AFElement or AFEventFrame is a new object that has not been saved to the server, then it will be automatically saved so that the server can apply the security changes to the children.

Notes to Callers
For composition reference types, access permissions for child and parent are always the same, therefore the value of this parameter is ignored. So, if you change the access permissions for the child, the parent access permissions are automatically changed to match the child permissions. Similarly, if you change the access permissions for the parent, the child access permissions are automatically changed to match the parent permissions. These changes cascade down (and up) through the hierarchy.

Notes to Callers

For composition reference types, access permissions for child and parent are always the same, therefore the value of this parameter is ignored. So, if you change the access permissions for the child, the parent access permissions are automatically changed to match the child permissions. Similarly, if you change the access permissions for the parent, the child access permissions are automatically changed to match the parent permissions. These changes cascade down (and up) through the hierarchy.

Exceptions

Exception	Condition
ArgumentNullException	This exception is thrown if the accessRules is or an empty string.
NotSupportedException	This exception is thrown if attempting to set security on an AFSecurityIdentity or AFSecurityMapping object.

Remarks

This method allows the setting of the security descriptor for the object using a more readable text format than the native Security Descriptor String Format used in the SetAccessControl(String, Boolean) method. This the preferred method for setting security for AF 2.7 and newer servers. For older servers that only support the Security Descriptor String Format, this method only sets the DACL portion of the security descriptor, which is the only information relevant for determining security rights. See the Security String Format section of the Security Formats topic for a description of the format of the accessRules string parameter.

Important
Setting security on AFSecurityIdentity or AFSecurityMapping is not supported. You must the security on the corresponding PISystem collection for these object types.

Examples

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

// Create the Element
AFElement myElement = myDB.Elements.Add("MyElement#1");
myElement.CheckIn();

// Set Security String to Deny Write and WriteDate for World
AFSecurity security = myElement.Security;
string accessRules = "World:A(r,rd)|World:D(w,wd)";
security.SetSecurityString(accessRules, false);

// Check Security Rights
Console.WriteLine("Element CanRead = {0}", security.CanRead);
Console.WriteLine("Element CanWrite = {0}", security.CanWrite);

// Ensure element is returned in search results for current user
AFElementSearch search = new AFElementSearch(myDB, "Search", "Name:'MyElement*");
int totalCount = search.GetTotalCount();
Console.WriteLine("Element count = {0}", totalCount);

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

' Create the Element
Dim myElement As AFElement = myDB.Elements.Add("MyElement#1")
myElement.CheckIn()

' Set Security Descriptor to Deny Write and WriteData for Everyone
Dim security As AFSecurity = myElement.Security
Dim accessRules As String = "World:A(r,rd)|World:D(w,wd)"
security.SetSecurityString(accessRules, False)

' Check Security Rights
Console.WriteLine("Element CanRead = {0}", security.CanRead)
Console.WriteLine("Element CanWrite = {0}", security.CanWrite)

' Ensure element is returned in search results for current user
Dim search As New AFElementSearch(myDB, "Search", "Name:'MyElement*")
Dim totalCount As Integer = search.GetTotalCount()
Console.WriteLine("Element count = {0}", totalCount)

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

AF SDK Reference