AF SDK Reference

AFValue.GetAnnotation Method

Save PDF

TABLE OF CONTENTS

AFValue.GetAnnotation Method

Save PDF

Last UpdatedNov 18, 2025
5 minute read

Gets the annotation associated with this AF value.

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

Syntax

public Object GetAnnotation()

Public Function GetAnnotation As Object

Dim instance As AFValue
Dim returnValue As Object

returnValue = instance.GetAnnotation()

public:
Object^ GetAnnotation()

member GetAnnotation : unit -> Object

Return Value

Type: Object
Will return either a list of structured AFAnnotations or a simple annotation value of any type, but most typically of type String.

Exceptions

Exception	Condition
NotSupportedException	The data reference does not support the this method.

Remarks

This method will retrieve the annotation associated this AF value. To update an existing annotation, use the SetAnnotation(Object) method.

The Attribute must indicate that it supports retrieving 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 ReadData security rights to read 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