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.

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

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.

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.

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:

To add a CacheClient assembly reference to a project:

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.

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:

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:

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 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.

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 Studio to examine the ObjectScript code for these classes.

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