Using .NET and the ADO.NET Managed Provider with Caché
Introduction
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This book describes how to use the CacheClient .NET assembly, which provides two different but complimentary ways to access Caché from a .NET application:

This combination is unique in that it provides a .NET application with simultaneous relational and object access to data, using a common API and without requiring any object-to-relational mapping. The CacheClient assembly is implemented using .NET managed code throughout, making it easy to deploy within a .NET environment. It is thread-safe and can be used within multithreaded .NET applications.
Installation and Configuration
This section provides specifies requirements and provides instructions for installing Caché and configuring Visual Studio.
Requirements
Caché is not required on computers that run your Caché .NET client applications, but they must have a TCP/IP connection to the Caché Server and must be running a supported version of the .NET Framework.
Installation
The CacheClient assembly (InterSystems.Data.CacheClient.dll) is installed along with the rest of Caché, and requires no special preparation.
To use the CacheClient assembly in a .NET project, you must add a reference to the assembly, and add the corresponding Using statements to your code (as described in the following section, Configuring Visual Studio).
There is a separate version of InterSystems.Data.CacheClient.dll for each supported version of .NET. In the current release of Caché, these files are located in the following subdirectories of <Cache-install-dir>\dev\dotnet\bin:
See Caché Installation Directory in the Caché Installation Guide for the location of <Cache-install-dir> on your system.
All Caché assemblies for .NET are installed to the .NET GAC (Global Assembly Cache) when Caché is installed.
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
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:
    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 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:
Caché .NET Binding Client/Server Architecture
The basic mechanism works as follows:
The runtime architecture consists of the following:
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).
All of these projects use classes from the Sample package in the SAMPLES namespace. You can use Caché 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.