First Look: .NET Object Persistence with XEP

Before You Begin

To use the procedure, you will need a Windows system to work on, with the .NET framework and Visual Studio installed, and a running InterSystems IRIS instance to connect to. Your choices for InterSystems IRIS include several types of licensed and free evaluation instances; the instance need not be hosted by the system you are working on (although they must have network access to each other). For information on how to deploy each type of instance if you do not already have one to work with, see Deploying InterSystems IRISOpens in a new tab in InterSystems IRIS Basics: Connecting an IDE. Connect Visual Studio to your InterSystems IRIS instance using the information in InterSystems IRIS Connection InformationOpens in a new tab and .Net IDEsOpens in a new tab in the same document.

Adding a Sample Class

Before creating the program source file, you will add a class that the main program will access to generate sample objects for storage. In Visual Studio, use Project > Add Class to add a C# class file to the netxep project. Delete the default contents of the class file, and copy and paste the following code into the file.

using System;

namespace xep.samples
{
    public class SingleStringSample {
        public string name;
        public SingleStringSample() { }
        internal SingleStringSample(string str) {
            name = str;
        }

        public static SingleStringSample[] generateSampleData(int objectCount) {
            SingleStringSample[] data = new SingleStringSample[objectCount];
            for (int i = 0; i < objectCount; i++)
            {
                data[i] = new SingleStringSample("single string test");
            }
            return data;
        }
    }
}

Because this class is very simple, XEP does not need any annotations to generate an effective schema from it. For more complex classes in a real-world application, you can use various options to optimize the import.

Creating the XEP Demo Program

Now you are ready to create the XEPSimple demo program. In Visual Studio, find the default program.cs file that was created when you created the project. Delete the default contents of the file and paste in the code that follows, substituting the connection information for your InterSystems IRIS instanceOpens in a new tab for the values of the host, port, irisnamespace, username, and password variables. You can specify the USER namespace as shown, or you can choose another that you have created on your installed instance.

using System;
using InterSystems.XEP;
using xep.samples;

namespace XepSimpleNamespace
{
    public class XepSimple
    {
        public static void Main(string[] args)
        {
            // Generate 12 SingleStringSample objects for use as test data
            SingleStringSample[] sampleArray = SingleStringSample.generateSampleData(12);
            
            // EventPersister
            EventPersister xepPersister = PersisterFactory.CreatePersister();
            
            String host = "127.0.0.1"; // InterSystems IRIS host
            int port = 51774; // InterSystems IRIS Superserver port
            String irisnamespace = "USER"; // InterSystems IRIS namespace
            String username = "_system"; // Credentials for InterSystems IRIS
            String password = "SYS"; //Credentials for InterSystems IRIS
                        
            xepPersister.Connect(host,port,irisnamespace,username,password); // connect to localhost
            xepPersister.DeleteExtent("xep.samples.SingleStringSample");   // remove old test data
            xepPersister.ImportSchema("xep.samples.SingleStringSample");   // import flat schema

            // Event
            Event xepEvent = xepPersister.GetEvent("xep.samples.SingleStringSample");

            long[] itemIdList = xepEvent.Store(sampleArray);  
            int itemCount = 0;
            for (int i = 0; i < itemIdList.Length; i++)
            {
                if (itemIdList[i] > 0) itemCount++;
            }
            Console.WriteLine("Stored " + itemCount + " of " + sampleArray.Length + " events");
            

            // EventQuery
            EventQuery<SingleStringSample> xepQuery = null;
            String sqlQuery = "SELECT * FROM xep_samples.SingleStringSample WHERE %ID BETWEEN ? AND ?";
            xepQuery = xepEvent.CreateQuery<SingleStringSample>(sqlQuery);
            xepQuery.AddParameter(3);    // assign value 3 to first SQL parameter
            xepQuery.AddParameter(12);   // assign value 12 to second SQL parameter
            xepQuery.Execute();            // get resultset for IDs between 3 and 12
            
            
            xepQuery.Close();
            xepEvent.Close();
            xepPersister.Close();
        } // end main()
    } // end class xepSimple
}

The demo program is divided into three sections, each of which demonstrates one of the three main XEP classes, EventPersister, Event, and EventQuery. When run, the XepSimple demo program performs the following tasks:

• First, some sample objects are generated by calling a method of your sample data class, xep.samples.SingleStringSample.

• EventPersister is the main entry point for XEP, and provides the connection to the database.

  It creates an instance named xepPersister, which establishes a TCP/IP connection to the User namespace in the database and deletes any existing sample data. It then calls ImportSchema() to analyze the sample class and send the schema to the database, thus creating an the corresponding ObjectScript schema to hold persistent SingleStringSample objects.

• Event encapsulates an interface between a .NET object and the corresponding database object.

  Once the schema has been generated, xepPersister can create an Event object named xepEvent for the sample class. The Store() method stores the array of .NET objects as persistent events.

• EventQuery is used to prepare and execute a limited subset of SQL queries.

  An EventQuery<SingleStringSample> object named xepQuery is created by passing a query string to the xepEvent object’s CreateQuery() method. The string defines an SQL query that accepts two parameters (the ? characters). The parameter values are defined by calls to AddParameter(), and a call to Execute() fetches the query resultset.

• When processing is done, it cleans up by calling the close() methods for the XEP objects.

Running the XEPSimple Program

You are now ready to build and run the XEPSimple demo program. Press Ctrl + F5 to run the program so the command prompt stays open when the program ends.

Next Steps

The XepSimple demo is designed to give you a taste of XEP without bogging you down in details, and is not a model for real production code — it didn’t even bother with exception checking. The most important simplification was in the sample data. You persisted a few tiny .NET objects from a class that doesn’t require annotation or other mechanisms to aid in schema generation and optimization. Though you usually need annotations and other options in a real world application, these options are straightforward and easy to use. The APIs are similarly simple and easy to use.

For a comprehensive description of all XEP features, see Persisting .NET Objects with InterSystems XEP.