Skip to main content
Previous sectionNext section

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 {
    ...
  }
Copy code to clipboard
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\
Copy code to clipboard

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
Copy code to clipboard

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, 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
    Copy code to clipboard

    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