.NET Requirements and Configuration
This section provides information on the InterSystems .NET client assemblies. It also provides instructions for Setting Up the Entity Framework Provider.
Managed Providers in the IRISClient assembly
The IRISClient .NET assembly provides two different but complementary Providers that support access to InterSystems databases from a .NET application:
-
The ADO.NET Managed Provider — is InterSystems implementation of the ADO.NET data access interface. It provides easy relational access to data using the standard ADO.NET Managed Provider classes (see “Using ADO.NET Managed Provider Classes”).
-
The Entity Framework Provider — is the InterSystems implementation of the object-relational mapping (ORM) framework for ADO.NET. It enables .NET developers to work with relational data using domain-specific objects (see Setting Up the Entity Framework Provider).
For more information, see the course on Using Entity Framework with InterSystems IRIS Data PlatformOpens in a new tab.
The IRISClient 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.
Supported .NET Versions
For a list of supported .NET versions, see Supported .NET Frameworks in InterSystems Supported Platforms.
Unsupported IRISClient Assemblies
InterSystems IRIS has dropped support for several versions of .NET that are no longer in support by Microsoft (.NET Framework 2.0, 4.0 and 4.5, and .NET Core 1.0 and 2.1). Older projects that use the path to the dll location will need to update the path to correspond to the new assembly file location. For example, a previous path would be:
\<IRIS install location>\dev\dotnet\bin\v4.5\InterSystems.Data.IRISClient.dll
That location will no longer exist under the new installation, and should be changed to:
\<IRIS install location>\dev\dotnet\bin\v4.6.2\InterSystems.Data.IRISClient.dll
In terms of compatibility between versions, the newer 4.6.2 version is backwards compatible and the applications will run on systems that have any .NET Framework 4.x installed.
However, .NET Framework is not forwards-compatible, so if your application targets .NET Framework 4.5 specifically, it cannot use .NET Framework 4.6.2 client libraries as a dependency. In this case, your options are:
-
Change the target framework of the application to be at least 4.6.2. .NET Framework 4.5 has been out of support by Microsoft since 2016, so this will also ensure users are using a supported language version.
-
Use the .NET Framework 3.5 version of the library. You may lose access to certain features or functionality introduced in version 4.0.
-
Continue to use an older version of the client library that targets 4.5. Older versions will not contain the latest bug fixes or functionality, but you will not need to modify the dependencies of your application. This is a temporary solution, since upgrades to future versions the InterSystems IRIS server will eventually make them incompatible with the older clients.
Configuring the IRISClient Assembly
Support 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.
Requirements
-
A supported version of .NET or .NET Framework
-
Visual Studio 2013 or higher.
InterSystems IRIS is not required on computers that run your .NET client applications, but the clients must have a TCP/IP connection to an InterSystems server and must be running a supported version of .NET or .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 option 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 option 1 (minimal) it should already be checked.
If you are not running InterSystems IRIS on a local installation, you may have to download and install the client driver manually. See Connecting Your Application to InterSystems IRISOpens in a new tab for information on this option.
Declaring IRISClient in a .NET Application
To use the IRISClient assembly in a .NET application, you must add a Using statement for the InterSystems.Data.IRISClient.dll assembly before the beginning of your application's namespace.
Both the using statement and the following namespace are required:
using InterSystems.Data.IRISClient;
namespace YourNameSpace {
...
}
There is a separate version of InterSystems.Data.IRISClient.dll for each supported version of .NET and .NET Framework. See “Supported .NET Frameworks” for details.
Configuring Visual Studio
To add a IRISClient assembly reference to a project:
-
From the Visual Studio main menu, select Project > Add Reference
-
In the Add Reference window, click on Browse...
-
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.
-
In the Visual Studio Solution Explorer, the InterSystems.Data.IRISClient assembly should now be listed under References.
Setting Up the Entity Framework Provider
Entity Framework is an object-relational mapper that enables .NET developers to work with relational data using domain-specific objects. The InterSystems Entity Framework Provider enables you to use Entity Framework 6 technology to access an InterSystems database. See Using Entity Framework with InterSystems IRIS Data PlatformOpens in a new tab for a tutorial with working examples using the Entity Framework.
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 supported release is VS 2013 Professional/Ultimate with update 5).
-
A supported version of .NET Framework (.NET Core and later .NET versions are not supported).
-
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.
-
Create a new directory named install-dir\dev\dotnet\bin\v4.0.30309\IrisEF.
-
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 Using Entity Framework with InterSystems IRIS Data PlatformOpens in a new tab for more information).
Configure Visual Studio and install EF Provider
If you are running VS 2013 or 2015, reverse steps 2 and 3 below: first run setup.cmd, then run devenv /setup.
-
Move to the new IrisEF directory. The following instructions assume that IrisEF is the current directory.
-
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.
-
-
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:
-
Open Visual Studio and select View > Server Explorer.
-
Right-click Data Connections and select Add Connection. In the Add Connection Dialog:
-
Select Data source as InterSystems IRIS Data Source (.Net Framework Data Provider for InterSystems IRIS)
-
Select Server
-
Enter Username and password. Click Connect.
-
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:
-
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).
-
Copy the InterSystems.Data.Entity6.4.5.0.0.nupkg file from IrisEF subdirectory IrisEF\Nuget\ to your NuGet repository directory. Click OK.
-
In Visual Studio, select Project > Manage Nuget Packages > Settings > Package Manager > Package Sources.
-
Click the plus sign+. Enter the path that contains InterSystems.Data.Entity6.4.5.0.0.nupkg. Click OK