Using .NET and the ADO.NET Managed Provider with Caché
Using the Caché Entity Framework Provider
[Home] [Back] 
InterSystems: The power behind what matters   
Class Reference   

Entity Framework is an object-relational mapper that enables .NET developers to work with relational data using domain-specific objects. It eliminates the need for most of the data-access code that developers usually need to write. Caché includes the Caché Entity Framework Provider which enables you to use Entity Framework 6 technology to access a Caché database. (If you are using Entity Framework 5, ask your Intersystems representative for instructions.) For more information on the .NET Entity Framework, see

This chapter contains the following sections:
This section describes three approaches to getting started with Entity Framework.
Setting Up Caché Entity Framework Provider
Follow the instructions in this section to install and set up Caché Entity Framework Provider.
System Requirements
To use Caché Entity Framework Provider, you need the following software:
Run Setup and Set Variables
Follow these steps:
  1. Extract the contents of installdir\dev\dotnet\bin\v4.0.30309\ into a folder (in the same directory as the zip file) called CacheEF. Run \CacheEF\setup.cmd.
  2. In the displayed Windows Explorer folder, right-click Developer Command Prompt for VS2013 > Run as Administrator and enter:
    devenv /setup
    This command repopulates this key from HKEY_LOCAL_MACHINE:
Copy Files to Visual Studio
Copy the two files from the CacheEF directory to Visual Studio:
from the directory <cacheinstalldir>\dev\dotnet\bin\v4.0.30319\CacheEF\Templates to the directory C:\Program Files (x86)\Microsoft Visual Studio 1x.0\Common7\IDE\Extensions\Microsoft\Entity Framework Tools\DBGen
Connect Visual Studio to Caché Server
To connect Visual Studio to a Caché instance, follow the steps below:
  1. Open Visual Studio and select View > Server Explorer.
  2. Right-click Data Connections and select Add Connection. In the Add Connection Dialog:
    1. Select Server
    2. Enter Username and password. Click Connect.
    3. Select a namespace from the list. Click OK.
Configure Caché Nuget Local Repository
Follow these steps to configure the Package Manager to find the local Nuget repository:
  1. Create a directory as a Nuget repository. You might call it Nuget Repository. You could put it anywhere – a good choice might be <yourdoclibraryVS2013>\Projects (where Visual Studio stores projects by default).
  2. Copy the file <installdir>\dev\dotnet\bin\v4.0.30319\CacheEF\Nuget\InterSystems.Data.Entity6. and paste it into your Nuget repository directory. Click OK.
  3. Click the plus sign+. Enter the path that contains InterSystems.Data.Entity6. Click OK
Getting Started with Entity Framework
This section describes three approaches to getting started with Entity Framework.
The sections below show examples of each of these approaches.
Code First
This section shows an example of how to write code to define data classes and then generate tables from the class properties. The example in this section is based on the Entity Framework Tutorial from (
  1. Create a new project in Visual Studio 2013 with FILE > New > Project. With a Template of Visual C# and Console Application highlighted, enter a name for your project, such as CodeStudents. Click OK
  2. Add Caché Entity Framework Provider to the project: Click TOOLS > Nuget Package Manager > Manage Nuget Packages for Solution. Expand Online > Package Source. Caché Entity Framework Provider 6 is displayed. Click Install > Ok > I Accept. Wait for the installation to complete and then click Close.
  3. Compile the project with Build > Build Solution.
  4. Tell the project which system to connect to by identifying it in the App.config file as follows. From the Solution Explorer window, open the App.config file. Add a <connectionStrings> section (like the example shown here) as the last section in the <configuration> section after the <entityFramework> section.
    Check that the server, port, namespace, username, and password are correct for your configuration.
          connectionString="SERVER = localhost;
             NAMESPACE = USER;
             METADATAFORMAT = mssql;
             USER = _SYSTEM;
             password = SYS;
             LOGFILE = C:\\Users\\Public\\logs\\cprovider.log;
             SQLDIALECT = cache;"
  5. In the Program.cs file, add
    using System.Data.Entity;
    using System.Data.Entity.Validation;
    using System.Data.Entity.Infrastructure;
  6. Define classes:
    public class Student
       public Student()
       public int StudentID { get; set; }
       public string StudentName { get; set; }
       public DateTime? DateOfBirth { get; set; }
       public byte[] Photo { get; set; }
       public decimal Height { get; set; }
       public float Weight { get; set; }
       public Standard Standard { get; set; }
    public class Standard
       public Standard()
       public int StandardId { get; set; }
       public string StandardName { get; set; }
       public ICollection<Student> Students { get; set; }
    public class SchoolContext : DbContext
       public SchoolContext() : base("name=SchoolDBConnectionString")
       public DbSet<Student> Students { get; set; }
       public DbSet<Standard> Standards { get; set; }
    Check that class SchoolContext points to your connection in App.config.
  7. Add code to Main.
    using (var ctx = new SchoolContext())
       Student stud = new Student() { StudentName = "New Student" };
  8. Compile and run.
Check the namespace (USER in this case). You see three tables created: dbo.Standards, dbo.Students (which has a new student added), and dbo._MigrationHistory (which holds information about table creation).
Set Up a Sample Database
If you want to set up a sample database for use with the Database First section, follow the steps in this section. These steps set up and load the sample database CreateNorthwindEFDB.sql.
  1. In the Management Portal, select System > Configuration > Namespaces and click Create New Namespace.
  2. Name your namespace NORTHWINDEF.
    1. For Select an Existing Database for Globals, click Create New Database. Enter NORTHWINDEF as the database and <installdir>\mgr\EFdatabase as the directory. Click Next and Finish
    2. For Select an Existing Database for Routines, select NORTHWINDEF from the dropdown list.
    3. Click Save.
  3. In the Management Portal, select System > Configuration > SQL and Object Settings > General SQL Settings.
    1. In the SQL tab, enter the Default SQL Schema Name as dbo.
    2. In the SQL tab, select Support Delimited Identifiers (default is on)
    3. In the DDL tab, select all items.
    4. Click Save.
    1. Set the DIALECT to MSSQL.
    2. Click Save.
  4. In a Terminal window, change to your new namespace with
  5. If this is not the first time you are setting up the database, purge existing data with:
    do $SYSTEM.OBJ.DeleteAll("e") d Purge^%apiSQL()
  6. If you have not already done so, using an unzip program, extract files from installdir\dev\dotnet\bin\v4.0.30319\ to a folder called CacheEF.
  7. To load the ddl, enter
    do $SYSTEM.SQL.DDLImport("MSSQL","_system","<installdir>\dev\dotnet\bin\v4.0.30319\CacheEF\CreateNorthwindEFDB.sql")
In the Server Explorer window, you can expand the Caché server entry to view NorthwindEF database elements: Tables, Views, Function, Procedures. You can examine each element, retrieve Data for Tables and Views, Execute Functions and Procedures. If you right-click an element and select Edit, Studio opens showing corresponding class and position on requested element if applicable.
Database First
To use the database first approach, start with an existing database and use Entity Framemaker to generate code for a web application based on the fields of that database.
  1. Create a new project in Visual Studio 2013 with FILE > New > Project of type Visual C# > Console Application > OK.
  2. Compile the project with Build > Build Solution.
  3. Select PROJECT > Add New Item > Visual C# Items > Ado.NET Entity Data Model. You can give your model a name. Here we use the default of Model1. Click Add.
  4. In the Entity Data Model Wizard:
    1. In the Choose Your Data Connection screen, the data connection field should already be to your Northwind database. It doesn’t matter whether you select Yes, Include or No, exclude to the sensitive data question.
    2. On the bottom of screen you can define a connection settings name. The default is localhostEntities. This name is used later on.
    3. In the Choose Your Database Objects and Settings screen, answer the question Which Database objects do you want to include in your model? by selecting all objects: Tables, Views, and Stored Procedures and Functions. This includes all Northwind tables.
    4. Click Finish.
    5. In several seconds, you’ll see a Security Warning. Click OK to run the template.
    6. Visual Studio may display an Error List with many warnings. You can ignore these.
  5. For a model name of Model1, Visual Studio generates multiple files under Model1.edmx – including a UI diagram as Model1.edmx itself, classes representing tables under, and context class localhostEntities in>Model1.Context.cs.
    In the Solution Explorer window, you can inspect Model1.Context.cs. The constructor Constructer public localhostEntities() : base("name=localhostEntities") points to App.Config connection string:
             provider connection string=&quot;
  6. Compile your project with BUILD > Build Solution.
Below are two program samples that you can paste into Main() in Program.cs:
You can traverse a list of customers using:
using (var context = new localhostEntities()) {
   var customers = context.Customers;
   foreach (var customer in customers) {
      string s = customer.CustomerID + '\t' + customer.ContactName;
You can get a list of orders for CustomerID using:
using (var context = new localhostEntities()) {
   var customerOrders = from c in context.Customers
      where (c.CustomerID == CustomerID)
         select new { c, c.Orders };

   foreach (var order in customerOrders) {
      for (int i = 0 ; i < order.Orders.Count; i++) {
         var orderElement = order.Orders.ElementAt(i);
         string sProduct = "";
         //Product names from OrderDetails table 
         for (int j = 0; j < orderElement.OrderDetails.Count; j++)  
            var product = orderElement.OrderDetails.ElementAt(j);
            sProduct += product.Product.ProductName;
            sProduct += ",";
         string date = orderElement.OrderDate.ToString();
Model First
Use the model first approach by generating a database model basd on the diagram you created in the Database First section. Then generate a database from the model.
This example shows you how to create a database that contains two entities,
  1. Look at the Entity Framework UI edmx diagram Model1.edmx. In a blank area of the diagram, right-click and select Properties.
  2. Compile Project.
  3. In a blank area of the diagram, right-click and select Generate Database From Model. After the DDL is generated, click Finish.
  4. Studio creates and opens the file Model1.edmx.sql.
  5. Import your table definitions into Caché by executing the following command in a terminal:
      do $SYSTEM.SQL.DDLImport("MSSQL","_system","C:\\<myPath>\\Model1.edmx.sql")