Learning
Community
Open Exchange
Global Masters
InterSystems IRIS Data Platform 2019.4 / Application Development / Using the InterSystems Managed Provider for .NET / Introduction
Previous section   Next section

Introduction

This book describes how to use the SqlClient .NET assembly, which provides two different but complementary ways to access InterSystems databases from a .NET application:
The SqlClient 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 chapter describes how to install the Managed Provider (see “SqlClient Installation and Configuration”) and provides additional instructions for setting up Entity Framework (see “Setting Up the Entity Framework Provider”).
Note:
The .NET Help File
The .NET help file provides the most current and detailed documentation for both object and relational APIs. This file is named IrisProvider.chm, and it is available as a stand-alone help file in <iris-install-dir>\dev\dotnet\help.

SqlClient Installation and Configuration

This section provides specifies requirements, and provides instructions for installing the SqlClient assembly and configuring Visual Studio.

Requirements

  • The .NET Framework, versions 2.0, 4.0, or 4.5.
  • InterSystems IRIS.
  • Visual Studio 2013 or later.
InterSystems IRIS is not required on computers that run your .NET client applications, but the clients must have a TCP/IP connection to the InterSystems server and must be running a supported version of the .NET Framework.

Installation

The SqlClient assembly (InterSystems.Data.IRISClient.dll) is installed along with the rest of InterSystems IRIS, and requires no special preparation.
  • When installing InterSystems IRIS in Windows, select the Setup Type: Development option.
  • If InterSystems IRIS has been installed with security level 2, open the Management Portal and go to System Administration > Security > Services, select %Service_CallIn, and make sure the Service Enabled box is checked. If you installed InterSystems IRIS with security level 1 (minimal) it should already be checked.
To use the SqlClient 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).
There is a separate version of InterSystems.Data.IRISClient.dll for each supported version of .NET. These files are located in the following subdirectories of <iris-install-dir>\dev\dotnet\bin:
  • .NET version 2.0: \bin\v2.0.50727
  • .NET version 4.0: \bin\v4.0.30319
  • .NET version 4.5: \bin\v4.5
See “Installation Directory” in the Installation Guide for the location of <iris-install-dir> on your system.
All InterSystems assemblies for .NET are installed to the .NET GAC (Global Assembly Cache) when InterSystems IRIS is installed.

Configuring Visual Studio

This section describes how to set up a Visual Studio project using the SqlClient assembly.
To add a SqlClient 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 <iris-install-dir>\dev\dotnet\bin that contains the assembly for the version of .NET used in your project (as listed in the previous section), select InterSystems.Data.IRISClient.dll, and click OK.
  4. In the Visual Studio Solution Explorer, the InterSystems.Data.IRISClient 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.IRISClient.dll assembly before the beginning of your application's namespace. InterSystems.Data.IRISClient provides code in the namespace InterSystems.Data.IRISClient, so this namespace must be referenced in the using statement.
  using InterSystems.Data.IRISClient;

  namespace DotNetSample {
    ...
  }
Both the SqlClient and IRISTypes namespaces are included in the InterSystems.Data.IRISClient.dll assembly.

Setting Up the Entity Framework Provider

Follow the instructions in this section if you want to use the InterSystems Entity Framework Provider.

System Requirements

To use Entity Framework Provider, you need the following software:
  • Visual Studio 2013 (Professional or Ultimate) with Update 5 (or later update)
  • InterSystems IRIS Entity Framework Provider distribution, located in the directory install-dir\dev\dotnet\bin\v4.0.30309. This directory includes the following files, which you use in the setup instructions:
    • IrisEF.zip, installation files.
    • IrisEF.zip\setup.cmd, which installs the DLLs InterSystems.Data.IRISClient.dll and InterSystems.Data.IRISVSTools.dll.
    • IrisEF.zip\Nuget\InterSystems.Data.Entity6.4.5.0.0.nupkg which installs Entity Framework Provider.
    • IrisEF.zip\CreateNorthwindEFDB.sql which is used to create a sample database.

Run Setup and Set Variables

Follow these steps:
  1. Extract the contents of install-dir\dev\dotnet\bin\v4.0.30309\IrisEF.zip into a folder (in the same directory as the zip file) called IrisEF. Run \IrisEF\setup.cmd.
  2. In Windows, select All Programs > Visual Studio 2013 > Visual Studio Tools.
  3. 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:
    HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\12.0_Config //VS 2013

Copy Files to Visual Studio

Copy the two files from the IrisEF directory to Visual Studio:
  • SSDLToIrisSQL.tt
  • GenerateIrisSQL.Utility.ttinclude
from the directory <iris-install-dir>\dev\dotnet\bin\v4.0.30319\IrisEF\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 the Server

To connect Visual Studio to an InterSystems database 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 Data source as InterSystems IRIS Data Source (.Net Framework Data Provider for InterSystems IRIS)
    2. Select Server
    3. Enter Username and password. Click Connect.
    4. Select a namespace from the list. Click OK.

Configure 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\IrisEF\Nuget\InterSystems.Data.Entity6.4.5.0.0.nupkg and paste it into your Nuget repository directory. Click OK.
  3. In Visual Studio, select Project > Manage Nuget Packages > Settings > Package Manager > Package Sources.
  4. Click the plus sign+. Enter the path that contains InterSystems.Data.Entity6.4.5.0.0.nupkg. Click OK
Previous section   Next section