Skip to main content

Configuration and Requirements

This chapter covers the following topics:

Configuring the IRISClient assembly

Support for both providers is implemented in the IRISClient assembly, using .NET managed code throughout, making it easy to deploy within a .NET environment. IRISClient is thread-safe and can be used within multithreaded .NET applications. This section provides specifies requirements, and provides instructions for installing the IRISClient assembly and configuring Visual Studio.

Note:
.Net Core 2 Support

InterSystems also supports .NET Core 2 for ADO.NET on both Windows and Linux. For more information, see .“.NET Core 2 Installation and Configuration” later in this chapter.

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.

IRISClient Assembly Setup

The IRISClient 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 IRISClient 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 IRISClient assembly.

To add a IRISClient 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 {
    ...
  }
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.

.NET Core 2 Installation and Configuration

InterSystems supports .NET Core 2 for ADO.NET on both Windows and Linux (except for Entity Framework, which will be supported in later releases). This section assumes that readers are familiar with the .NET CLI (command line interface) commands which are to build, run, test, and manage packages for .NET Core projects. See https://docs.microsoft.com/en-us/dotnet/core/tools/?tabs=netcore2x for more information.

NuGet packages are used on all operating systems. Packages are available in installdir/dev/dotnet/bin/Core21. These packages can be installed into a project via Visual Studio or via the dotnet command line tool.

Installing from Visual Studio

On Windows, you can install NuGet packages from Visual Studio:

  • In the VStudio menu, go to Tools -> NuGet Package Manager -> Package Manager Settings -> Package Sources and add a new local repository that points to a directory containing the IRIS NuGet packages.

  • For your application, right click the application, choose Manage nuget packages for solution, then click browse, set the source dropdown to point to the local repository from step one and install the packages.

Installing from the Command Line

On Linux and Mac OS, use the dotnet command line tool (see https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-add-package).

For example:

   dotnet add TestAdd.csproj package IRISProviderCore21 -s <install-dir>\dev\dotnet\bin\Core21\

where -s indicates the path to the IRISProviderCore21.1.0.0.nupkg package.

NuGet packages are installed to the local cache. At some point you may need to issue the following command to clear the cache of NuGet packages:

   dotnet nuget locals all --clear

Setting Up the Entity Framework Provider

Follow the instructions in this section to configure the InterSystems Entity Framework Provider.

System Requirements

To use Entity Framework Provider with InterSystems IRIS, the following software is required:

  • Visual Studio 2013 or later (first valid release was VS 2013 Professional/Ultimate with update 5).

  • InterSystems IRIS Entity Framework Provider distribution, described in the following section.

Creating the IrisEF Directory

The InterSystems IRIS Entity Framework Provider distribution file is IrisEF.zip, located in install-dir\dev\dotnet\bin\v4.0.30309.

  1. Create a new directory named install-dir\dev\dotnet\bin\v4.0.30309\IrisEF.

  2. Extract the contents of IrisEF.zip to the new directory.

This .zip file contains the following files, which you use in the setup instructions:

  • setup.cmd, which installs the DLLs InterSystems.Data.IRISClient.dll and InterSystems.Data.IRISVSTools.dll.

  • Nuget\InterSystems.Data.Entity6.4.5.0.0.nupkg which installs the Entity Framework Provider.

  • CreateNorthwindEFDB.sql which is used to create a sample database (see “Setting Up a Sample Database”).

Configure Visual Studio and install EF Provider

Note:

If you are running VS 2013 or 2015, reverse steps 2 and 3: first run setup.cmd, then run devenv /setup.

  1. Move to the new IrisEF directory. The following instructions assume that IrisEF is the current directory.

  2. Set up the Visual Studio development environment:

    • In Windows, select All Programs > Visual Studio 201x > Visual Studio Tools.

    • In the displayed Windows Explorer folder, right-click Developer Command Prompt for VS201x > Run as Administrator and enter:

      devenv /setup

    This command repopulates the environment setting from the registry key that specifies the path to your version of Visual Studio.

  3. At the command prompt, run setup.cmd. This installs InterSystems Entity Framework Provider files InterSystems.Data.IRISClient.dll and InterSystems.Data.IRISVSTools.dll.

Copy Files to Visual Studio

Copy the following files from IrisEF subdirectory IrisEF\Templates to Visual Studio:

  • SSDLToIrisSQL.tt

  • GenerateIrisSQL.Utility.ttinclude

Copy from <iris-install-dir>\dev\dotnet\bin\v4.0.30319\IrisEF\Templates

to <VisualStudio-install-dir>\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 the 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 if you have not already done so. You can use any name and location. For example, you could create directory NuGet Repository in the default Visual Studio project directory (<yourdoclibraryVS201x>\Projects).

  2. Copy the InterSystems.Data.Entity6.4.5.0.0.nupkg file from IrisEF subdirectory IrisEF\Nuget\ to 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

Feedback