Writing .NET code using properties

Summary
This topic shows how to write .NET code by reading the graphical interface keys on interface and property help pages in the ArcObjects namespace reference.

In this topic

About writing .NET code using properties
There are several ways to use the available properties on the ArcObject interfaces. Understanding how to read the graphical representation on the interface help pages and the .NET syntax of the individual property help pages is vital to enhancing your ArcObjects coding experience.
The following table shows graphical symbols that are used extensively in the object model diagrams (OMDs) and on the interface help pages of the ArcObjects namespace reference. The following are the five property types and associated interface keys (for more information, see Property types in this topic):
Interface key
Property type
Property Get
Property Put
Property Get/Put
Property Put by reference
Property Get/Put by reference
  • In the previous table, the solid barbells indicate the data types are by value (ByVal). The hollow barbells indicate the data types are by reference (ByRef).
  • By value (ByVal) means data is assigned to a value type. The data is stored in the variable on the stack. The stack is a memory area in which processes and threads store data of a fixed size.
  • By reference (ByRef) means data is assigned to a reference type. The data is stored on the managed heap. For reference data types, the address of the data is stored in the stack and the heap holds the data. Data in the heap is dynamic in size. In some programming languages—for example, C++ and Java—this is the same as storing a pointer.
The graphical symbols tell a lot about the usage of a specific member on an interface. To write your .NET code correctly, click the member's property link to use the correct syntax in .NET. See the following screen shot:

There are two types of properties—Get and Put (or Set). As a general rule, Get means the property is used on the right side of the equal sign and Put (or Set) means the property is used on the left side of the equal sign. However, there are a few ArcObjects that do not follow this convention. For more information, see Coding caveats in this topic.

Property types
The following property types are discussed in detail:
Property Get
The Property Get () means you can only retrieve the value of that property (that is, it is read-only). Its data type is by value (ByVal). IField.AliasName is an example of a Property Get (read-only) type. See the following screen shot:
See the following code example showing how to use the Property Get:
[VB.NET] 
Public Class Class1
    
    Public Sub Test()
        
        ' Create a new field object.
        Dim field As IField = New FieldClass
        
        ' The following is the appropriate use of the Property Get:
        Dim myString As System.String = field.AliasName
        
        ' The following is an inappropriate use of the Property Get:
        ' The code will not compile and returns the following error message:
        ' Property 'AliasName' is 'ReadOnly.'
        field.AliasName = "Won't Work - Write Only Property"
        
    End Sub
    
End Class
[C#] 
public class Class1
{

    public void test()
    {

        // Create a new field object.
        IField field = new FieldClass();

        // The following is the appropriate use of the Property Get:
        System.String myString = field.AliasName;

        // The following is an inappropriate use of the Property Get:
        // The code will not compile and returns the following error message:
        // Property or indexer 'ESRI.ArcGIS.Geodatabase.IField.AliasName' cannot be assigned to; it is read-only.
        field.AliasName = "Won't Work - Write Only Property";
    }

}
Property Put
The Property Put or Set () means that you can only set the value of that property (that is, it is write-only). Its data type is by value (ByVal). IFieldEdit.AliasName is an example of a Property Put (write-only) type. See the following screen shot:
 
See the following code example showing how to use the Property Put or Set:
 
[VB.NET] 
Public Class Class1
    
    Public Sub Test()
        
        ' Create a new field object.
        Dim field As IField = New FieldClass
        
        ' Create a fieldEdit object from the field object.
        Dim fieldEdit As IFieldEdit = CType(field, IFieldEdit)
        
        ' The following is the appropriate use of the Property Put (or Set):
        fieldEdit.AliasName_2 = "My Write Only Name"
        
        ' The following is an inappropriate use of the Property Put (or Set):
        ' The code will not compile and returns the following error message:
        ' Property 'AliasName_2' is 'WriteOnly.'
        Dim myString As System.String = fieldEdit.AliasName_2
        
    End Sub
    
End Class
[C#] 
public class Class1
{

    public void test()
    {
        // Create a new field object.
        IField field = new FieldClass();

        // Create a fieldEdit object from the field object.
        IFieldEdit fieldEdit = (IFieldEdit)field;

        // The following is the appropriate use of the Property Put (or Set):
        fieldEdit.AliasName_2 = "My Write Only Name";

        // The following is an inappropriate use of the Property Put (or Set):
        // The code will not compile and returns the following error message:
        // The property or indexer 'ESRI.ArcGIS.Geodatabase.IFieldEdit.AliasName_2' cannot be used in this context because it lacks the get accessor.
        System.String myString = fieldEdit.AliasName_2;
    }

}
Property Get/Put
The Property Get/Put () means that you can retrieve and set the value of that property (that is, it is read/write). Both properties data type is by value (ByVal). IEnvelope.Depth is an example of a Property Get/Put (read/write) type. See the following screen shot:
See the following code example showing how to use the Property Get/Put:
[VB.NET] 
Public Class Class1
    
    Public Sub Test()
        
        ' Create a new envelope object.
        Dim envelope As IEnvelope = New EnvelopeClass
        
        ' The following is the appropriate use of the Property Put (or Set):
        envelope.Depth = 25
        
        ' The following is the appropriate use of the Property Get:
        Dim myDouble As System.Double = envelope.Depth
        
    End Sub
    
End Class
[C#] 
public class Class1
{

    public void test()
    {
        // Create a new envelope object.
        IEnvelope envelope = new EnvelopeClass();

        // The following is the appropriate use of the Property Put (or Set):
        envelope.Depth = 25;

        // The following is the appropriate use of the Property Get:
        System.Double myDouble = envelope.Depth;
    }

}
Property Put by reference
Property Put or Set () by reference means you can only set the value of that property (that is, it is write-only). It uses the same style of .NET syntax as the Property Put. Additional insight can be gained by understanding the graphical representation on the interface page in conjunction with using the syntax usage of the property page.
 
The Property Put by reference symbol (hollow barbell) means when you make an assignment, you are using a pointer in memory. If the memory changes, so will any values used by reference. IDisplayFeedback.Display is an example of a Property Put by reference (write-only) type. See the following screen shots:
 
 
See the following code example showing how to use the Property Put by reference:
[VB.NET] 
Public Class Class1
    
    Public Sub Test(ByVal activeView As ESRI.ArcGIS.Carto.IActiveView)
        
        ' Create a newEnvelopeFeedback object.
        Dim newEnvelopeFeedback As INewEnvelopeFeedback = New NewEnvelopeFeedback
        
        ' Use the Property Put or Set to set the newEnvelopeFeedback object's
        ' .Display property by reference.
        newEnvelopeFeedback.Display = activeView.ScreenDisplay
        
        ' The following is an inappropriate use of the Property Put or Set (it is write-only):
        ' The code will not compile and returns the following error:
        ' Property 'Display' is 'WriteOnly.'
        Dim display As IDisplay = newEnvelopeFeedback.Display
        
    End Sub
    
End Class
[C#] 
public class Class1
{

    public void test(ESRI.ArcGIS.Carto.IActiveView activeView)
    {
        // Create a newEnvelopeFeedback object.
        INewEnvelopeFeedback newEnvelopeFeedback = new NewEnvelopeFeedback();

        // Use the Property Put or Set to set the newEnvelopeFeedback object's
        // .Display property by reference.
        newEnvelopeFeedback.Display = activeView.ScreenDisplay;

        // The following is an inappropriate use of the Property Put or Set (it is write-only):
        // The code will not compile and returns the following error:
        // The property or indexer 'ESRI.ArcGIS.Display.INewEnvelopeFeedback.Display' cannot be used in this context because it lacks the get accessor.
        IDisplay display = newEnvelopeFeedback.Display;
    }

}
Property Get/Put by reference
The Property Get/Put or Get/Set () by reference means that you can retrieve and set the value of that property (it is read/write). It uses the same style of .NET syntax as the Property Get/Put. Additional insight can be gained by understanding the graphical representation on the interface page in conjunction with using the syntax usage of the property page.
The Put by reference symbol (hollow barbell) means when you make an assignment, you are using a pointer in memory. If the memory changes, so will any values used by reference (ByRef). However, the Get property uses the default by value (ByVal) operation and as such, cannot be changed unless another by value assignment is given within the code. IGeometry.SpatialReference is an example of a Property Get/Put by reference (it is read/write) type. See the following screen shots:
 
 
See the following code example showing how to use the Property Get/Put by reference:
 
[VB.NET] 
Public Class Class1
    
    
    Public Sub Test()
        
        ' Create a test SpatialReference.
        Dim spatialReferenceFactory2 As ISpatialReferenceFactory2 = New SpatialReferenceEnvironmentClass
        Dim spatialReference As ISpatialReference = spatialReferenceFactory2.CreateSpatialReference(esriSRProjCSType.esriSRProjCS_World_Robinson)
        
        ' Create a new point.
        Dim point As IPoint = New PointClass
        
        ' Put or Set by reference the SpatialReference of the point.
        point.SpatialReference = spatialReference
        System.Windows.Forms.MessageBox.Show(point.SpatialReference.Name) ' Displays "World Robinson"
        
        ' Create another SpatialReference from an existing SpatialReference of a point (Get) by value.
        Dim anotherSpatialReference As ISpatialReference = point.SpatialReference
        System.Windows.Forms.MessageBox.Show(anotherSpatialReference.Name) ' Displays "World Robinson."
        
        ' Create a third test SpatialReference (different from the original).
        Dim spatialReferenceFactory2_THIRD As ISpatialReferenceFactory2 = New SpatialReferenceEnvironmentClass
        Dim spatialReference_THIRD As ISpatialReference = spatialReferenceFactory2_THIRD.CreateSpatialReference(esriSRProjCSType.esriSRProjCS_World_Sinusoidal)
        
        ' Since you perform a Put or Set by reference, the name changes.
        point.SpatialReference = spatialReference_THIRD
        System.Windows.Forms.MessageBox.Show(point.SpatialReference.Name) ' Displays "World Sinusoidal."
        
        ' AnotherSpatialReference was originally created from point.SpatialReference, but
        ' it was done using by value and therefore, retains its original value.
        System.Windows.Forms.MessageBox.Show(anotherSpatialReference.Name) ' Still displays "World Robinson."
        
    End Sub
    
End Class
[C#] 
public class Class1
{

    public void test()
    {
        // Create a test SpatialReference.
        ISpatialReferenceFactory2 spatialReferenceFactory2 = new
            SpatialReferenceEnvironmentClass();
        ISpatialReference spatialReference =
            spatialReferenceFactory2.CreateSpatialReference((int)
            esriSRProjCSType.esriSRProjCS_World_Robinson);

        // Create a new point.
        IPoint point = new PointClass();

        // Put or Set by reference the SpatialReference of the point.
        point.SpatialReference = spatialReference;
        System.Windows.Forms.MessageBox.Show(point.SpatialReference.Name); 
            // Displays "World Robinson."

        // Create another SpatialReference from an existing SpatialReference of a point (Get) by value.
        ISpatialReference anotherSpatialReference = point.SpatialReference;
        System.Windows.Forms.MessageBox.Show(anotherSpatialReference.Name); 
            // Displays "World Robinson."

        // Create a third test SpatialReference (different from the original).
        ISpatialReferenceFactory2 spatialReferenceFactory2_THIRD = new
            SpatialReferenceEnvironmentClass();
        ISpatialReference spatialReference_THIRD =
            spatialReferenceFactory2_THIRD.CreateSpatialReference((int)
            esriSRProjCSType.esriSRProjCS_World_Sinusoidal);

        // Since you performed a Put or Set by reference, the name changes.
        point.SpatialReference = spatialReference_THIRD;
        System.Windows.Forms.MessageBox.Show(point.SpatialReference.Name); 
            // Displays "World Sinusoidal."

        // AnotherSpatialReference was originally created from point.SpatialReference, but
        // it was done using by value and therefore, retains its original value.
        System.Windows.Forms.MessageBox.Show(anotherSpatialReference.Name); 
            // Still displays "World Robinson."
    }

}

Coding caveats
For ArcObjects properties that take one or more input arguments, they do not follow standard coding conventions—the property name does not match how it is accessed by code or the property usage is syntactically closer to a method in usage. You can tell if you have one of these atypical properties when viewing the help page if you see get_ or set_ prefacing the property name in the code usage section. IStatusBar.Message property is an example of one of these coding caveats. See the following screen shot:
 
 
VB .NET code
For VB .NET code to handle these unusual situations, ignore the get_ and set_ prefacing of the property name when using the property in code—use the property name as it appears at the top of the help page. If necessary, use Visual Studio's IntelliSense options to determine the correct code usage.
Using a method in VB .NET always involves parameters being encased in parentheses. In general, properties do not have their parameters encased in parentheses; properties set a variable equal to something or have something equal to a variable. In the rare occurrences where get_ and set_ types of properties are used, you may find that the property acts like a method.
C# code
For C# code to handle these unusual situations, use the get_ and set_ prefixes to the property name when using the property in code. The documentation on the particular help page gives the accurate syntax to use in Visual Studio.
 
For the previous VB .NET and C# cases, see the following code example showing how to use the correct syntax in Visual Studio:
 
[VB.NET] 
Public Class Class1
    
    Public Sub Test(ByVal application As IApplication)
        
        ' Property Put (or Set).
        application.StatusBar.Message(0) = "This is a message"
        
        'Property Get.
        Dim message As String = application.StatusBar.Message(0)
    End Sub
    
End Class
[C#] 
public class Class1
{

    public void test(IApplication application)
    {
        // Property Put (or Set).
        application.StatusBar.set_Message(0, "This is message");

        //Property Get.
        string message = application.StatusBar.get_Message(0);
    }

}


See Also:

Understanding the ArcObjects namespace reference



To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
Development licensing Deployment licensing
ArcGIS for Desktop Basic ArcGIS for Desktop Basic
ArcGIS for Desktop Standard ArcGIS for Desktop Standard
ArcGIS for Desktop Advanced Engine
Engine Developer Kit Engine