Introduction

Installation and Configuration

This section provides specifies requirements and provides instructions for installing Caché and configuring Visual Studio.

Configuring Visual Studio

This chapter describes how to set up a Visual Studio project using the CacheClient assembly, and how to add the Caché Object Binding Wizard to Visual Studio. The following topics are covered:

• Configuring a Visual Studio Project — describes how to add a CacheClient assembly reference and Using statements.

• Adding the Caché Object Binding Wizard to Visual Studio — describes how to add the Caché proxy class creation wizard to the Visual Studio Tools menu.

Configuring a Visual Studio Project

To add a CacheClient assembly reference to a project:

1. From the Visual Studio main menu, select Project > Add Reference

2. In the Add Reference window, click on Browse...

3. Browse to the subdirectory of <Cache-install-dir>\dev\dotnet\bin that contains the assembly for the version of .NET used in your project (see “Installation”), select InterSystems.Data.CacheClient.dll, and click OK.

   

4. In the Visual Studio Solution Explorer, the InterSystems.Data.CacheClient assembly should now be listed under References:

   

Add Using Statements to the Application

Add Using statements for the two main namespaces in the InterSystems.Data.CacheClient.dll assembly before the beginning of your application's namespace.

  using InterSystems.Data.CacheClient;
  using InterSystems.Data.CacheTypes;

  namespace DotNetSample {
    ...
  }

Both the CacheClient and CacheTypes namespaces are included in the InterSystems.Data.CacheClient.dll assembly.

Adding the Object Binding Wizard to Visual Studio

The Caché Object Binding Wizard is a program to generate Caché proxy objects (see “Using the Caché Object Binding Wizard”). It can be run from the command line, but will be more readily available if you integrate it into Visual Studio by adding it to the External Tools menu.

To add the Caché Object Binding Wizard to the Tools menu:

1. From the Visual Studio main menu, select Tools > External Tools...

   

2. In the External Tools window:

   • Click Add

   • In the Title field, enter : Cache Object Binding Wizard

   • In the Command field, browse to the <Cache-install-dir>\dev\dotnet\bin\v2.0.50727 directory and select CacheNetWizard.exe. (Although this executable is located in the .NET 2.0 directory, it provides the Binding Wizard for all supported versions of .NET. For the location of <Cache-install-dir> on your system, see “Caché Installation Directory” in the Caché Installation Guide).

   • Click OK

   The Caché Object Binding Wizard now will be displayed as an option on the Visual Studio Tools menu.

   

Caché .NET Binding Architecture

The Caché .NET binding gives .NET applications a way to interoperate with objects contained within a Caché server. These objects can be persistent objects stored within the Caché object database or they can be transient objects that perform operations within a Caché server.

The Caché .NET Binding consists of the following components:

• The Caché Object Server — a high performance server process that manages communication between .NET objects and a Caché database server using standard networking protocols (TCP/IP). Caché uses a common server for .NET, C++, Java, Perl, Python, ODBC, and JDBC access.

• The InterSystems.Data.CacheClient assembly — a set of .NET classes that implement all the functionality of the .NET classes created by the Caché Proxy Generator. It also provides a set of proxy classes for a few Object Server classes that are projected differently to make them fit into the framework of the .NET standard library.

• The Caché Proxy Generator — a set of methods that generate .NET classes from classes defined in the Caché Class Dictionary. Several different interfaces are available (see “Generating Caché Proxy Classes”).

The Proxy Generator can create .NET proxy classes for any class in the Caché Class Dictionary. The proxy classes contain only managed .NET code, which the Proxy Generator creates by inspecting the class definitions found in the Caché Class Dictionary. Instances of the .NET proxy classes on the client communicate at runtime (using TCP/IP sockets) with their corresponding Caché objects on a Caché server. This is illustrated in the following diagram:

The basic mechanism works as follows:

• You define one or more classes within Caché. These can be persistent objects stored within the Caché database or transient objects that run within a Caché server.

• The Caché Proxy Generator creates .NET proxy classes that correspond to your Caché classes. These classes contain stub methods and properties that correspond to Caché object methods and properties on the server.

• At runtime, your .NET application connects to a Caché server. It can then create instances of .NET proxy objects that correspond to objects within the Caché server. You can use these proxy objects as you would any other .NET objects. Caché automatically manages all communications as well as client-side data caching.

The runtime architecture consists of the following:

• A Caché database server (or servers).

• A .NET client application into which your generated and compiled .NET proxy classes have been linked.

At runtime, the .NET application connects to Caché using an object connection interface (provided by the CacheConnection class). All communication between the .NET application and the Caché server uses the standard TCP/IP protocol.

The Caché .NET Help File

The Caché .NET help file provides the most current and detailed documentation for both object and relational APIs. Although the file is named CacheProvider.chm, it covers both ADO.NET Managed Provider classes (InterSystems.Data.CacheClient) and Object Binding classes (InterSystems.Data.CacheClient.ObjBind), as well as classes used by both bindings. CacheProvider.chm is available as a stand-alone help file in <Cache-install-dir>\dev\dotnet\help.

The Caché .NET Sample Programs

Caché comes with a set of sample projects that demonstrate the use of the Caché .NET binding. These samples are located in the <Cache-install-dir>/dev/dotnet/samples/ subdirectory of the Caché installation (see “Caché Installation Directory” in the Caché Installation Guide for the location of <Cache-install-dir> on your system).

• adoform — A simple program to access and manipulate the Sample.PersonOpens in a new tab database. The same program is presented in three different Visual Studio languages: C#, Basic, and C++.

• bookdemos — Contains complete, working versions of the examples in this document. The project is a small, easily modified test bed for short sample routines. All of the relevant sample code is in one file: SampleCode.cs. You may need to regenerate the ..\bookdemos\WizardCode.cs file, which contains proxy classes for the Sample package (see “Generating Caché Proxy Classes” for detailed instructions).

• console — A console program that demonstrates the bare minimum requirements for a Caché .NET project.

• mobiledevice — Similar to adoform, but demonstrates how the mobile version of the CacheClient assembly deals with transient connections.

• objbind — Similar to adoform, but demonstrates how to write code that uses both ADO.NET Managed Provider classes and Caché Object Binding classes in a complementary fashion.

All of these projects use classes from the Sample package in the SAMPLES namespace. You can use Studio to examine the ObjectScript code for these classes.

Note:

Most of these samples are written only in C#. If you decide to convert a sample to Visual Basic, bear in mind that a new Visual Basic .NET project will have a default namespace that contains every class defined by the project. If this is ignored, code such as:

   Dim p As New Sample.Person
   p = p.OpenId(CacheConnection, "1")

will fail because the root namespace has not been referenced. This can be easily corrected by disabling the "Root namespace" option in the Visual Studio project preferences.