How to persist data in a document

In this topic

• Persisting data in a document
  • Creating an extension with persistence
• What can be persisted?
  • Arrays
  • Custom components
• Managing version compatibility

Persisting data in a document

Creating an extension with persistence

1. Create an extension class by implementing IExtension, IPersistVariant, and other optional interfaces by Using item templates to extend ArcObjects:
   1. Using the Application Extension item template under ArcGIS Desktop
      1. Select the Configurable Extension option (for example, Configurable Extension [ArcMap]). This extension class implements IExtension, IExtensionConfig, and IPersistVariant.
   2. Using the ArcGIS Add Class Wizard to extend ArcObjects:
      1. On the Base Implementation page, select Application Framework from the Customization group and Extension from the base component list. 
      2. On the Optional Interfaces page, add the ESRI.ArcGIS.esriSystem.IPersistVariant interface.
      3. Check the appropriate application component category for the extension on the Component Category page (for example, ArcMap Extension).
2. Set the IExtension.Name property that is used to identify the extension class being persisted in the document. The length of the name must not exceed 31 characters.
3. In the IPersistVariant.ID property, return the class identifier (CLSID) for the class.
4. Determine what data should be persisted and how. Consider version compatibility to prepare for potential extension evolution over time or versions.
5. Implement the IPersistVariant.Save method to write data when the document is saved.
   1. Use the IVariantStream.Write method of the input parameter to write data to the stream.
   2. If version compatibility is enforced, use either IDocumentVersion or your own internal persistence version number to mark the version.
6. Implement the IPersistVariant.Load method by using the IVariantStream.Read method of the input parameter to read data when the document is opened.
   1. Streams are sequential, so you must use the same order to read from the stream as the data was written.
   2. If version compatibility is enforced, determine the persistence version to read the data correctly.
   3. Handle any exceptions and raise an appropriate error back to the application when necessary.
7. In .NET, you must release the stream object using the System.Runtime.InteropServices.Marshal.ReleaseCOMObject method at the end of the Save and Load implementations.

namespace HowTo
{
    [ClassInterface(ClassInterfaceType.None)][Guid(
        "6de1d416-7a87-44b9-954a-cdd5e82ff998")]
    public class HowToExtension: IExtension, IPersistVariant
    {
        private string m_value1;
        private int m_value2;

        string IExtension.Name
        {
            get
            {
                return "HowToExtensionPersistence";
            }
        }
        void IExtension.Shutdown(){}
        void IExtension.Startup(ref object initializationData){}

        #region IPersistVariant Members
        public UID ID
        {
            get
            {
                UID typeID=new UIDClass();
                typeID.Value=GetType().GUID.ToString("B");
                return typeID;
            }
        }
        public void Load(IVariantStream Stream)
        {
            m_value1=Convert.ToString(Stream.Read());
            m_value2=Convert.ToInt32(Stream.Read());
            Marshal.ReleaseComObject(Stream);
        }

        public void Save(IVariantStream Stream)
        {
            Stream.Write(m_value1);
            Stream.Write(m_value2);
            Marshal.ReleaseComObject(Stream);
        }

        #endregion 
    }

}

<ComClass("cc9715ed-e54f-4c2b-ac76-308a1069cfca")> _
          Public Class HowToExtension
    Implements IExtension
    Implements IPersistVariant
    
    Private m_value1 As String
    Private m_value2 As Integer
    
    Public Sub New()
        MyBase.New()
    End Sub
    
    Public ReadOnly Property Name() As String Implements IExtension.Name
    Get
    Return "HowToExtensionPersistence"
    End Get
End Property

Public Sub Shutdown() Implements IExtension.Shutdown
End Sub

Public Sub Startup(ByRef initializationData As Object) Implements IExtension.Startup
End Sub

#Region "IPersistVariant Members"
Public ReadOnly Property ID() As UID Implements IPersistVariant.ID
Get
Dim typeID As New UIDClass()
typeID.Value=Me.GetType().GUID.ToString("B")
Return typeID
End Get
End Property

Public Sub Load(ByVal Stream As IVariantStream) Implements IPersistVariant.Load
    m_value1=Convert.ToString(Stream.Read())
    m_value2=Convert.ToInt32(Stream.Read())
    Marshal.ReleaseComObject(Stream)
End Sub

Public Sub Save(ByVal Stream As IVariantStream) Implements IPersistVariant.Save
    Stream.Write(m_value1)
    Stream.Write(m_value2)
    Marshal.ReleaseComObject(Stream)
End Sub

#End Region

End Class

What can be persisted?

Arrays

Custom components

Managing version compatibility

• ESRI.ArcGIS.System (ESRI.ArcGIS.esriSystem)
• System.Runtime.InteropServices