Topic outline

• .NET QuickStart

  .NET QuickStart

  InterSystems supports three lightweight .NET APIs that provide direct access to InterSystems IRIS® databases via relational tables, objects, or multidimensional storage.
  

  .NET features available in InterSystems IRIS include:

  • Relational access through an ADO.NET API
  • Object access through the InterSystems XEP API
  • Access to multidimensional storage through the InterSystems Native API
  • Multi-model access to use multiple APIs together
  • Support for third-party APIs such as Entity Framework
  • An underlying consistent structure, avoiding data duplication

  Watch the video, then try the exercise below!

  • Mark me "complete" for this exercise.

    Not available unless: Your ID number is not empty
• Collapse allExpand all
  Try It

  Try It

  With .NET, you can interact with InterSystems IRIS relationally (with ADO.NET), using objects (with XEP or Entity Framework), or natively (with the Native API). In the steps below, you will access a set of sample stock data using each of the ways described.

  Start the exercise in one of three ways:

  1. Use an InterSystems IRIS Learning Lab by clicking the launcher below.
  2. Use AWS, Azure, or GCP, first following the steps to change the password for InterSystems IRIS.
  3. Try the exercise locally with an instance of InterSystems IRIS and an IDE that supports .NET (such as Microsoft Visual Studio).

  •  You must be logged in to launch an InterSystems IRIS instance.

    • Log in with your existing account.
    • Don't have an InterSystems account? Create a new account.
  • Set up

    1. Load sample stock data into InterSystems IRIS:
       • If you are using InterSystems Learning Labs, the data is already loaded. Continue to Step 2.
       • If you have your own instance:
         1. Clone or download this repository: https://github.com/intersystems/Samples-Stock-Data. This repository has a folder named data, which contains all files needed to load the sample stock data.
         2. In the Management Portal, navigate to System Explorer > Classes and import DemoStockCls.xml and StocksUtil.xml files into the USER namespace from the data folder.
         3. In the InterSystems IRIS Terminal, type the following command. Replace repo_home with the directory of Sample-Stock-Data repo that you recently cloned:

            do ##class(Demo.Stock).LoadData("repo_home/data/all_stocks_1yr.csv")

    2. To get the sample .NET code, download or clone the following repo into your IDE:
       git clone https://github.com/intersystems/quickstarts-dotnet
       
       With Microsoft Visual Studio:
       1. Select File > Open > Project/Solution. Choose the quickstarts-dotnet.sln file you recently cloned.
       2. Select View > Solution Explorer to view project structure.
       3. Right-click Solution. Select Add > Existing item. Choose config.txt.
       4. Open config.txt file and modify the IP and password to be the correct values for your InterSystems IRIS instance. Port and username are most likely the defaults but you can verify those as well.

    You should now have several classes for ADO.NET, XEP, Native API, and multi-model. Due to its complexity, Entity Framework requires separate set up for IDE and configuration files, which will be explained in detail in Step 6.

    3. If you are using an InterSystems Learning Lab, correct the credentials in the connections.config file:
       1. Change the value of the IP from localhost to the InterSystems IP that is provided when you launch the Learning Lab.
       2. On the next line, change the value of port to the InterSystems 1972 Port provided.
  • Use the standard ADO.NET API for SQL-based access to relational tables
    

    1. In ADO folder, open adoNETplaystocks.cs to view the ADO.NET code. You will notice the connection string uses these variables to connect:
       
       connect.ConnectionString = "Server = " + ip + "; Port = " + port + "; Namespace =  " + Namespace + "; Password = " + password + "; User ID = " + username;
       
       
    2. Run adoNETplaystocks.cs. This code simulates a stock trading application, allowing you to manage your personal portfolio and see how you would have done selling on a particular date.
       • Run option 1: View the top 10 stocks on 2016-08-12.
         
       • Run option 2: Create the Portfolio table.
         
       • Run option 3: Add three new portfolio items (for AMZN, GOOGL, and EQIX) using a value between the opening and closing price on 2016-08-12.
       • Run option 6: See how much you would have made on your portfolio if you sold on 2017-08-10.
       • Run option 7: Quit.
         
       
       This code uses standard ADO.NET to create, read, update, and delete data within InterSystems IRIS. With the InterSystems IRIS driver, you can easily connect and use ADO.NET in the way you expect.
  • Use XEP for high performance, real-time object insertions
    

    1. In XEP folder, open xepplaystocks.cs to view the XEP code. You will notice the connection string uses these variables to connect:
       
       xepPersister.Connect(ip, port, Namespace, username, password); 
       
       
    2. Run xepplaystocks.cs. This code simulates real-time stock trades.
       • Run option 1: Make a sample trade. For example, trade two shares on 2016-08-12 for $300/share, using your own name as the trader.
         
       • Run option 2: Save this trade.
         
       • Run option 3: Generate 500 generic trades.
         
       • Run option 5: Retrieve the trade objects from the database.
       • Run option 6: Update the names to prepend NYSE- to each stock name and retrieve the trade objects from the database again.
       • Run option 7: Quit.
         
       
       With XEP, you can efficiently stores objects directly to InterSystems IRIS, requiring no translation to rows.
       
  • Use the Native API to store to a custom structure and call InterSystems IRIS methods or routines
    

    1. In Native API folder, open nativeplaystocks.cs to view the Native API code. You will notice the connection string uses these variables to connect:
       
       connect.ConnectionString = "Server = " + ip + "; Port = " + port + "; Namespace =  " + Namespace + "; Password = " + password + "; User ID = " + username;
    
    
    2. Run nativeplaystocks.cs. This code stores stock data in a custom data structure.
       • Run option 2: Store the stock data in a custom structure.
         
       • Run option 3: Retrieve and view the stock data from this custom structure.
         
       • Run option 4: Call population methods within InterSystems IRIS to generate better information for trades, as seen in the XEP example above.
         
       • Run option 5: Print the version of IRIS to the screen. This is retrieved by calling a routine within InterSystems IRIS.
         
       • Run option 6: Quit.
         
       
       With the Native API, you can efficiently store data in your own custom data structure, allowing you to answer questions you could not answer using tables or objects. Additionally, you can call class methods and routines from within InterSystems IRIS using the Native API.
       
  • Use ADO.NET, XEP, and Native access side-by-side, choosing the best model for each task
    

    1. In the Multi-model folder, open multimodelplaystocks.cs to see how all APIs work together. You will notice the connection string uses these variables to connect:
       
       xepPersister.Connect(ip, port, Namespace, username, password);
       
       Notice this code connects using the XEP connection. Since EventPersister inherits from IRISConnection, all ways to connect leverage the same underlying connection to InterSystems IRIS.
    
    
    2. Run multimodelplaystocks.cs. This code stores information about the stocks of various companies.
       • Run option 1: Retrieve quickly all distinct stock names from the Demo.Stock table with ADO.NET.
       • Run option 2: Create objects and store them directly to the database with XEP, avoiding any translation back to tables.
         
       • Run option 3: Call population methods within InterSystems IRIS for founder and mission statement with the Native API.
         
       • Run option 4: Quit.
       
       With InterSystems IRIS, you can use one connection to InterSystems IRIS and use the method that is best for each task, decreasing the time it takes to develop your applications while also increasing your application performance. XEP efficiently stores objects directly to InterSystems IRIS, requiring no translation to rows. It is worth it to mention that ADO.NET can also be used to retrieve the data stored using XEP, reducing data redundancy.
       
  • Use Entity Framework, a third-party API, to store objects to InterSystems IRIS
    

    1. In the Window directories:
       1. Navigate to the folder you recently cloned. Then, go to EFPlay/IrisEF.
       2. Add the IrisEF folder path into the system variables path. Details can be found here: Change the PATH system variable
          
       3. Right-click setup.cmd and select Run as Administrator.
    2. Make sure Visual Studio is closed. Then, in Windows search, type Developer Command Prompt for VS2017. Right-click Developer Command Prompt for VS2017 > Run as Administrator and enter devenv /setup
       
    3. Open Microsoft Visual Studio. Inside the EFPlay folder, open App.config and modify the SERVER (IP) and password to be the correct values for your InterSystems IRIS instance. Port and user are most likely the defaults, but you can verify those as well.
       
       Begin code:
       SERVER = "localhost";
port = 51773;
NAMESPACE = "USER";
USER = _SYSTEM;
password = SYS;


       End code.
    4. Run Program.cs. This code stores stock data in a custom data structure.
       • Run option 1: Make a new trade for AMZN on 2016-08-12 with price: 200, # of shares: 2 and your own information as a new trader.
         
       • Run option 4: Find all traders with your last name.
         
       • Run option 5: View the leaderboard.
         
       • Run option 6: Quit.
         
       
       With Entity Framework, you can connect to InterSystems IRIS using object-relational mapping. Entity Framework with InterSystems IRIS works exactly the way you expect, allowing you to easily upgrade your Entity Framework applications to work with InterSystems IRIS.
• What's Next?

  What's Next?

  • URLConnecting .NET Applications to InterSystems Products (learning path, 3h)

    Connect your .NET applications to InterSystems products and technologies using ADO.NET, XEP, Entity Framework, or the Native API.
    

  • URLDocumentation: Using the InterSystems Managed Provider for .NET

    Learn the different options you have for connecting .NET applications to InterSystems IRIS.
    

  • Share Your Feedback!