Using the Caché Object Binding for .NET

Using the Caché Object Binding Wizard

The Caché Object Binding Wizard can be run either as a stand-alone program (CacheNetWizard.exe, located in <Cache-install-dir>\dev\dotnet\bin\v2.0.50727 by default) or as a tool integrated into Visual Studio (See “Adding the Caché Object Binding Wizard to Visual Studio”).

When you start the Wizard, the following window is displayed:

Enter the following information:

1. Select the Caché server you wish to connect to:

   Select the server containing the Caché classes for which you want to generate .NET classes. To select the server:

   • Click Connect and select your server

   • Enter your username and password at the prompt. The Cache Connection Manager is displayed:

     

   • Select the namespace containing your class (this will be SAMPLES for the bookdemos project)

   • Click OK.

2. Select language:

   For the bookdemos project, you would select Language: C#.

3. Select where the Wizard output will go:

   Generally, this will be the same folder that contains the .csproj file for your project. In this example, the file will be named WizardCode.cs, and will be placed in the main bookdemos project directory.

4. Select the classes you wish to use:

   For this exercise, you should select the Sample.Person and Sample.Company classes from the SAMPLES namespace. The Sample.Address and Sample.Employee classes will be included automatically because they are used by Sample.Person and Sample.Company. If you check Show System Classes, classes from %SYS (the standard Caché Class Library) will be displayed along with those from SAMPLES.

5. Generator options:

   For this exercise, check Methods with default arguments and leave the other fields empty. The options are:

   • Use .Net Compact Framework — generate proxy code for mobile applications.

   • Methods with default arguments — generates some optional overloads for certain system methods.

   • Application Namespace — optional namespace that will be added to the names of all generated proxy classes. For example, if you entered MyNamespace, the generated code would contain references to MyNamespace.Sample.Person rather than just Sample.Person.

     Note:

     The server will not know about this namespace. To ensure that proxy objects referenced through relations will be generated properly, you should either use the name of your application's main assembly, or set CacheConnection.AppNamespace to the value you enter here (see “Instantiating a Proxy Object by Name” in “Using Caché Proxy Objects” for more information).

6. Press 'Generate' to create classes:

   The generated file can now be added to your project (see “Adding Proxy Code to a Project”).

Running the Proxy Generator from the Command Line

The command-line proxy generator program (dotnet_generator.exe, located in <Cache-install-dir>\dev\dotnet\bin\v2.0.50727

by default) is useful when the same set of proxy files must be regenerated frequently. This is important when the Caché classes are still under development, since the proxy classes must be regenerated whenever the interface of a Caché class changes.

The command-line generator always requires information about the connection string, output path and type of output file (cs or vb), and a list of the classes to be generated. The following arguments are used:

• -conn <connection string> — standard connection string (see “Creating a Connection”).

• If generating a single output file for all classes, use -path:

  • -path <full filename> — path and name of the output file for the generated code. Type of output file to be generated is determined by extension of the filename (for example, C:\somepath\WizardCode.vb will generate a Visual Basic code file).

• If generating one output file for each class, use -dir and -src-kind:

  • -dir <path> — directory where the generated proxy files will be placed.

  • -src-kind <cs|vb> — type of proxy file to generate. For each class, a file named <namespace_classname>.<src-kind> will be generated in the directory specified by -dir. Options are cs or vb.

• -class-list <full filename> — path and name of a text file containing a list of the classes to be used. Each class name must be on a separate line.

The following optional arguments are also available:

• -gen-default-args <true | false> — switch that controls generation of optional overloads to certain generated system methods. Options are true or false.

• -app-nsp<namespace> — optional namespace that will be added to the names of all generated proxy classes. For example, if you entered MyNamespace, the generated code would contain references to MyNamespace.Sample.Person rather than just Sample.Person..

• -use-cf <true | false> — switch that controls whether code is generated for mobile devices or standard PCs. Options are true or false.

• -ok-api-changes-file — specifies the name of an XML file with a list of server API changes that should be ignored when checking the previously generated code at runtime.

The DOS batch file in this example calls dotnet_generator twice, generating the following output:

1. The first call generates a single file containing several proxy classes. This command generates exactly the same WizardCode.cs file as the Object Binding Wizard (see the example in “Using the Caché Object Binding Wizard”).

2. The second call generates one proxy file for each class, and generates Visual Basic code rather than C#. The filenames will be of the form <namespace_classname>.vb.

Both calls use the same connection string, output directory, and class list file.

set netgen=C:\InterSystems\Cache\dev\dotnet\bin\v2.0.50727\dotnet_generator.exe
set clist=C:\InterSystems\Cache\dev\dotnet\samples\bookdemos\Classlist.txt
set out=C:\InterSystems\Cache\dev\dotnet\samples\bookdemos
set conn="Server=localhost;Port=1972;Namespace=SAMPLES;Password=SYS;User ID=_SYSTEM;"

rem CALL #1: Generate a single WizardCode.cs proxy file
%netgen% -conn %conn% -class-list %clist% -path %out%\WizardCode.cs -gen-default-args true

rem CALL #2: Generate one <namespace_classname>.vb proxy file for each class
%netgen% -conn %conn% -class-list %clist% -dir %out% -src-kind vb -gen-default-args true

The contents of the class list file, Classlist.txt, are:

Sample.Company
Sample.Person

Although only two classes are listed, proxy classes for Sample.AddressOpens in a new tab and Sample.EmployeeOpens in a new tab are generated automatically because they are used by Sample.PersonOpens in a new tab and Sample.CompanyOpens in a new tab.

Generating Proxy Files Programmatically

The CacheConnection class includes the following methods that can be used to generate proxy files from within a .NET program:

CacheConnection.GenSourceFile()

Generates a new CS or VB proxy file that may contain definitions for several classes.

CacheConnection.GenSourceFile(filepath, generator, classlist, options, errors);

Parameters:

• filepath — A string containing the path and filename of the file to be generated.

• generator — A CodeDomProvider object that generates either CS or VB code.

• classlist — An IEnumerator iterator pointing to the list of classes that will be generated.

• options — a CacheClient.ObjBind.GeneratorOptions object.

• errors — An IList array used to store any returned error messages.

CacheConnection.GenMultipleSourceFiles()

Generates a separate CS or VB proxy file named <classname>.<filetype> for each class in classlist.

CacheConnection.GenMultipleSourceFiles(dirpath, filetype, generator, classlist, options, errors);

Parameters:

• dirpath — A string containing the directory path for the files to be generated.

• filetype — A string containing either ".vb" or ".cs", depending on the code to be generated.

• generator — A CodeDomProvider object that generates either CS or VB code.

• classlist — An IEnumerator iterator pointing to the list of classes that will be generated.

• options — A CacheClient.ObjBind.GeneratorOptions object.

• errors — An IList array used to store any returned error messages.

For a working example that uses both methods, see the Proxy_8_MakeProxyFiles() method in the bookdemos sample program (see “The Caché .NET Sample Programs”).

Using the Proxy Generator Methods

The following code fragments provide examples for defining the method parameters, and for calling each of the proxy generator methods.

generator parameter

The generator can be either a CSharpCodeProvider or a VBCodeProvider.

   System.CodeDom.Compiler.CodeDomProvider CS_generator = new CSharpCodeProvider();
   System.CodeDom.Compiler.CodeDomProvider VB_generator = new VBCodeProvider();

classlist parameter

Each of the methods accepts an iterator pointing to the list of classes to be generated. Although only two classes are listed in the following example, proxy classes for Sample.AddressOpens in a new tab and Sample.EmployeeOpens in a new tab are generated automatically because they are used by Sample.PersonOpens in a new tab and Sample.CompanyOpens in a new tab.

   ArrayList classes = new ArrayList();
   classes.Add("Sample.Company");
   classes.Add("Sample.Person");

   System.Collections.IEnumerator classlist
   classlist = classes.GetEnumerator();

options parameter

In this example, no special namespace will be generated for the proxy code, a complete set of inherited methods will be generated for each class, and no extra code will be generated for use by mobile applications.

   InterSystems.Data.CacheClient.ObjBind.GeneratorOptions options
   options = new GeneratorOptions();
   options.AppNamespace = ""; 
   options.GenDefaultArgMethods = true;
   options.UseCF = false;

errors parameter

The errors parameter will store the error messages (if any) returned from the proxy generator method call. All three methods use this parameter.

   System.Collections.IList errors
   errors = new System.Collections.ArrayList();

Example 1: Generate a new CS proxy file

This example generates a C# proxy file named WizardCode.cs in directory C:\MyApp\. The file will contain code for Sample.PersonOpens in a new tab, Sample.CompanyOpens in a new tab, Sample.AddressOpens in a new tab, and Sample.EmployeeOpens in a new tab.

   string filepath = @"C:\MyApp\WizardCode.cs";
   System.CodeDom.Compiler.CodeDomProvider generator = new CSharpCodeProvider();
   conn.GenSourceFile(filepath, generator, classlist, options, errors);

Example 2: Generate a set of single-class VB proxy files

This example generates a single VB proxy file for each class.

   string dirpath = @"C:\MyApp\";
   string filetype = ".vb";
   System.CodeDom.Compiler.CodeDomProvider generator = new VBCodeProvider();
   conn.GenMultipleSourceFiles(dirpath, filetype, generator, classlist, options, errors);

The following files will be generated in C:\MyApp\:

   Person.vb
   Company.vb
   Address.vb
   Employee.vb

The proxy files for Sample.AddressOpens in a new tab and Sample.EmployeeOpens in a new tab are generated automatically because they are used by Sample.PersonOpens in a new tab and Sample.CompanyOpens in a new tab.

Adding Proxy Code to a Project

After generating .NET proxy files, add the code to your project as follows:

• From the Visual Studio main menu, select Project > Add Existing Item...

• Browse to the generated proxy file (or files, if you chose to generate one file for each class) and click Add.

The file will be listed in the Visual Studio Solution Explorer.

You can now use proxy objects as described in the following sections.

Methods Inherited from Caché System Classes

The proxy file generators also provide proxy methods for certain classes inherited from the standard Caché Class Library. For example, the Sample classes inherit methods from Caché %Library.PersistentOpens in a new tab and %Library.PopulateOpens in a new tab. Proxies for these methods are automatically added when you generate the proxy files. This section provides a quick summary of the most commonly used methods. For more detailed information on a method, see the entries for these classes in the Caché Class Reference. For a generic guide to the use of Caché objects, see “Working with Registered Objects” in Using Caché Objects.

The following %Library.PersistentOpens in a new tab proxies are generated:

• Id() — Returns the persistent object ID, if there is one, of this object. Returns a null string if there is no object ID.

    string ID = person.Id(); 
  
  

  

• Save() — Stores an in-memory version of an object to disk. If the object was stored previously (and thus, already has an OID), Save() updates the on-disk version. Otherwise, Save() saves the object and generates a new OID for it.

    CacheStatus sc = person.Save(); 
  
  

  

• Open() — Loads an object from the database into memory and returns an OREF referring to the object.

• OpenId() — Loads an object from the database into memory and returns an OREF referring to the object. OpenId() is identical in operation to the Open() method except that it uses an ID value instead of an OID value to retrieve an instance.

    Sample.Person person = Sample.Person.OpenId(CacheConnect, "1");
  

  

• ExistsId() — Checks to see if the object identified by the specified ID exists in the extent.

    if (!(bool)Sample.Person.ExistsId(CacheConnect, ID)) {
      string Message = "No person with id " + ID + " in database."; };
  
  

  

• DeleteId() — Deletes the stored version of the object with the specified ID from the database.

    CacheStatus sc = Sample.Person.DeleteId(CacheConnect, ID); 
  
  

  

• Extent() — This is a system provided query that yields a result set containing every instance within this extent.

    CacheCommand Command = Sample.Person.Extent(CacheConnect); 
  
  

  

• KillExtent() — Deletes all instances of a class and its subclasses.

    CacheStatus sc = Sample.Person.KillExtent(CacheConnect) 
  
  

  

The following %Library.PopulateOpens in a new tab proxies are generated:

• Populate() — Creates a specified number of instances of a class and stores them in the database.

    long newrecs = (long)Sample.Person.Populate(CacheConnect, 100);
   
  

  

• OnPopulate() — For additional control over the generated data you can define an OnPopulate() method within your class. If an OnPopulate() method is defined then the Populate() method will call it for each object it generates.

• PopulateSerial() — Create a single instance of a serial object.

For a working example that uses the KillExtent() and Populate() methods, see the Proxy_6_Repopulate() method in the bookdemos sample program (see “The Caché .NET Sample Programs”).

Opening and Reading Objects

Use the OpenId() method to access an instance by ID (instances can also be accessed through SQL queries, as discussed later in “Using Caché Queries”). OpenId() is a static class method, qualified with the type name rather than an instance name:

  Sample.Person person = Sample.Person.OpenId(CacheConnect, "1");

Once the object has been instantiated, you can use standard dot notation to read and write the person information:

  string Name = person.Name
  string ID = person.Id();

  person.Home.City = "Smallville";
  person.Home.State = "MN";

In this example, person.Home is actually an embedded Sample.AddressOpens in a new tab object. It is automatically created or destroyed along with the Sample.PersonOpens in a new tab object.

For a working example, see the Proxy_1_ReadObject() method in the bookdemos sample program (see “The Caché .NET Sample Programs”).

Creating and Saving Objects

Caché proxy object constructors use information in a CacheConnection object to create a link between the proxy object and a corresponding object on the Caché server:

  Sample.Person person = new Sample.Person(CacheConnect);
  person.Name = "Luthor, Lexus A.";
  person.SSN = "999-45-6789";

Use the Save() method to create a persistent instance in the database. Once the instance has been saved, the Id() method can be used to get the newly generated ID number:

  CacheStatus sc = person.Save();
  Display.WriteLine("Save status: " + sc.IsOK.ToString());
  string ID = person.Id();
  Display.WriteLine("Saved id: " + person.Id());

The ExistsId() class method can be used to test whether or not an instance exists in the database:

  string personExists = Sample.Person.ExistsId(CacheConnect, ID).ToString()
  Display.WriteLine("person " + ID + " exists: " + personExists)

For a working example, see the Proxy_2_SaveDelete() method in the bookdemos sample program (see “The Caché .NET Sample Programs”).

Instantiating a Proxy Object by Name

In some cases, an object that is returned from the server differs from the object that the client requested. For example, the client may request an instance of Sample.PersonOpens in a new tab, but the server returns Sample.EmployeeOpens in a new tab. In order to instantiate an object of the desired class, the binding has to know the exact name of the proxy type, including the application namespace (if any).

When a proxy class is generated, there is an option to specify the namespace that contains it. For example, if the application namespace is MyAppNsp, the Sample.PersonOpens in a new tab proxy class can be specified as MyAppNsp.Sample.Person. Alternatively, the object could be generated as Sample.PersonOpens in a new tab and then "MyAppNsp" could be assigned to the connection.AppNamespace property. Either option allows the binding to deduce that the full name of the proxy type is "MyAppNsp.Sample.Person".

The binding tries to avoid instantiation by name as much as possible, so if a class is already loaded in memory, the binding uses the type in memory to create an instance. In this case, the exact class name is not necessary. In the following example, Y() returns a proxy object that the client knows must be Sample.PersonOpens in a new tab:

  Sample.Person p = new Sample.Person(conn); 
  Sample.Person q = x.Y();

The first line creates object p, and loads Sample.PersonOpens in a new tab in memory. In this case, the binding does not need to the full name, and x.Y() will not throw an exception. When the first line is commented out, the second line will fail if the full name of the proxy class is actually something like "MyAppNsp.Sample.Person".

Closing Proxy Objects

The Close() method disconnects a proxy object and closes the corresponding object on the server, but does not change the persistent instance in the database:

  person.Close();

By default Close() calls are cached. Although the proxy object can no longer be used, it is not actually destroyed until the reference count can be decremented on the server. This does not happen until the server is called again (for example, when a different proxy object calls a method).

In some situations, caching may not be desirable. For example, if an object is opened with Concurrency Level 4 (Exclusive Lock), the lock will not be released until the next server call. To destroy the object immediately, you can call Close() with the optional useCache parameter set to false:

  person.Close(false);

This causes a message to be sent to the server immediately, destroying the proxy object and releasing its resources.

Deleting Persistent Objects from the Database

The DeleteId() class method deletes the instance from the database. You can use the ExistsId() method to make sure that it is gone:

  CacheStatus sc = Sample.Person.DeleteId(CacheConnect, ID);
  Display.WriteLine("Delete status: " + sc.IsOK.ToString());
  Display.WriteLine("person " + ID + " exists: " 
    + Sample.Person.ExistsId(CacheConnect, ID).ToString());

For a working example, see the Proxy_2_SaveDelete() method in the bookdemos sample program (see “The Caché .NET Sample Programs”).