AF SDK Reference

AFValue.SetAnnotation Method

Save PDF

TABLE OF CONTENTS

AFValue.SetAnnotation Method

Save PDF

Last UpdatedNov 18, 2025
5 minute read

Associates an annotation with this AF value.

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

Syntax

public void SetAnnotation(
	Object annotation
)

Public Sub SetAnnotation ( 
	annotation As Object
)

Dim instance As AFValue
Dim annotation As Object

instance.SetAnnotation(annotation)

public:
void SetAnnotation(
	Object^ annotation
)

member SetAnnotation : 
        annotation : Object -> unit

Parameters

annotation: Type: SystemObject
The value of the annotation to associate with this AF value. It can be a list of structured AFAnnotations or a single value of type Object. To remove an annotation from an existing value, set the annotation value to an Empty string.

Exceptions

Exception	Condition
ArgumentNullException	The annotation is .
NotSupportedException	The data reference does not support the this method, or a data reference has not been configured.

Remarks

This method will associate the annotation with this AF value; however, the annotation is not committed until the value is updated using UpdateValue(AFValue, AFUpdateOption)

The attribute must indicate that it supports setting annotations by including the Annotations flag in its SupportedDataMethods.

Notes to Callers
This method, property, or class is not available in the legacy .NET 3.5 version of the SDK.

Security Note
You must have WriteData security rights to write a data value.

Examples

// This example demonstrates how to create an attribute for an
// element and retrieve and set annotations on values.

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

// Create an Element
AFElement myElement = myDB.Elements.Add("MyElement");

// Create an Attribute
AFAttribute myAttribute = myElement.Attributes.Add("MyAttribute");
myAttribute.DefaultUOM = myPISystem.UOMDatabase.UOMs["kelvin"];
myAttribute.DataReferencePlugIn = AFDataReference.GetPIPointDataReference(myPISystem);
myAttribute.ConfigString = @"\\%Server%\sinusoid;ReadOnly=False";

// Create New Simple Annotation
AFValue myValue1 = new AFValue(155.432, AFTime.Now);
myValue1.SetAnnotation("New Event with Simple Annotation");
myAttribute.Data.UpdateValue(myValue1, AFUpdateOption.InsertNoCompression);

// Update an Existing Annotation
myValue1.SetAnnotation(100);
myAttribute.Data.UpdateValue(myValue1, AFUpdateOption.Replace);

// Create an AFFile to be used as an Annotation value
string path = System.IO.Path.Combine(System.IO.Path.GetTempPath(), "TestFile.txt");
using (System.IO.File.Create(path)) { }
AFFile myFile = new AFFile();
myFile.Upload(path);

// Create New Structured Annotation
AFAnnotations myAnnotations = new AFAnnotations();
AFValue myValue2 = new AFValue(255.543);
AFAnnotation myAnnotation = myAnnotations.Add("Annotation#1", 400.456);
myAnnotation.Description = "1st Annotation is a Double.";
myAnnotation = myAnnotations.Add("Annotation#2", "My Annotation Value");
myAnnotation.Description = "2nd Annotation is a String.";
myAnnotation = myAnnotations.Add("Annotation#3", myFile);
myAnnotation.Description = "3rd Annotation is an AFFile.";
myValue2.SetAnnotation(myAnnotations);
myAttribute.Data.UpdateValue(myValue2, AFUpdateOption.InsertNoCompression);

// Read Annotations
object theAnnotation = myValue1.GetAnnotation();
DisplayAnnotation(myValue1, theAnnotation);

theAnnotation = myValue2.GetAnnotation();
DisplayAnnotation(myValue2, theAnnotation);

AFValue myValue = myAttribute.GetValue();
theAnnotation = myValue.GetAnnotation();
DisplayAnnotation(myValue, theAnnotation);

' This example demonstrates how to create an attribute for an
' element and retrieve and set annotations on values.

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

' Create An Element
Dim myElement As AFElement = myDB.Elements.Add("MyElement")

' Create an Attribute
Dim myAttribute As AFAttribute = myElement.Attributes.Add("MyAttribute")
myAttribute.DefaultUOM = myPISystem.UOMDatabase.UOMs("Kelvin")
myAttribute.DataReferencePlugIn = AFDataReference.GetPIPointDataReference(myPISystem)
myAttribute.ConfigString = "\\%Server%\sinusoid;ReadOnly=False"

' Create New Simple Annotation
Dim myValue1 As AFValue = New AFValue(155.432, AFTime.Now)
myValue1.SetAnnotation("New Event with Simple Annotation")
myAttribute.Data.UpdateValue(myValue1, AFUpdateOption.InsertNoCompression)

' Update an Existing Annotation
myValue1.SetAnnotation(100)
myAttribute.Data.UpdateValue(myValue1, AFUpdateOption.Replace)

' Create an AFFile to be used as an Annotation value
Dim path As String = System.IO.Path.Combine(System.IO.Path.GetTempPath(), "TestFile.txt")
Dim fs As FileStream = System.IO.File.Create(path)
fs.Close()
Dim myFile As AFFile = New AFFile
myFile.Upload(path)

' Create New Structured Annotation
Dim myAnnotations As AFAnnotations = New AFAnnotations
Dim myValue2 As AFValue = New AFValue(255.543)
Dim myAnnotation As AFAnnotation = myAnnotations.Add("Annotation#1", 400.456)
myAnnotation.Description = "1st Annotation is a Double."
myAnnotation = myAnnotations.Add("Annotation#2", "My Annotation Value")
myAnnotation.Description = "2nd Annotation is a String."
myAnnotation = myAnnotations.Add("Annotation#3", myFile)
myAnnotation.Description = "3rd Annotation is an AFFile."
myValue2.SetAnnotation(myAnnotations)
myAttribute.Data.UpdateValue(myValue2, AFUpdateOption.InsertNoCompression)

' Read Annotations
Dim theAnnotation As Object = myValue1.GetAnnotation
DisplayAnnotation(myValue1, theAnnotation)

theAnnotation = myValue2.GetAnnotation
DisplayAnnotation(myValue2, theAnnotation)

Dim myValue As AFValue = myAttribute.GetValue
theAnnotation = myValue.GetAnnotation
DisplayAnnotation(myValue, theAnnotation)

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

/// <summary>
/// Display information about the annotated value.
/// </summary>
/// <param name="theValue">
/// The AFValue associated with the specified annotation value.
/// </param>
/// <param name="theAnnotation">
/// The annotation value associated with the specified AFValue.
/// </param>
static private void DisplayAnnotation(AFValue theValue, object theAnnotation)
{
    AFAnnotations theAnnotations = theAnnotation as AFAnnotations;
    if (theAnnotations == null)
    {
        Console.WriteLine("Simple Annotation for Value '{0}' = '{1}'", theValue, theAnnotation);
    }
    else
    {
        Console.WriteLine("Structured Annotation for Value '{0}':", theValue);
        foreach (AFAnnotation item in theAnnotations)
        {
            Console.WriteLine("  Value = '{0}', Description = '{1}', Creator = '{2}'",
                item.Value, item.Description, item.Creator);
        }
    }
}

''' <summary>
''' Display information about the annotated value.
''' </summary>
''' <param name="theValue">
''' The AFValue associated with the specified annotation value.
''' </param>
''' <param name="theAnnotation">
''' The annotation value associated with the specified AFValue.
''' </param>
Private Shared Sub DisplayAnnotation(ByVal theValue As AFValue, ByVal theAnnotation As Object)
    Dim theAnnotations As AFAnnotations = TryCast(theAnnotation, AFAnnotations)
    If (theAnnotations Is Nothing) Then
        Console.WriteLine("Simple Annotation for Value '{0}' = '{1}'", theValue, theAnnotation)
    Else
        Console.WriteLine("Structured Annotation for Value '{0}':", theValue)
        For Each item As AFAnnotation In theAnnotations
            Console.WriteLine("  Value = '{0}', Description = '{1}', Creator = '{2}'", item.Value, item.Description, item.Creator)
        Next
    End If
End Sub

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

AF SDK Reference