We posted a series of hello world examples coded using our SDK and showed how easy it was for developers to get started with the Oracle NoSQL Database cloud.  In this post, I will show the same hello world example coded in the .NET framework, and if you are a .NET developer and already have access to the Oracle Cloud, I believe you will be up and running in 10 minutes or less by using the Oracle NoSQL Database Cloud service with the .NET SDK.

In the very first “hello world” post, We also talked about why you might want to use a NoSQL Database for certain applications.   For that discussion, you can check out the post here 15-minutes-to-hello-world. The remainder of this post will focus on writing .NET code for your first Oracle NoSQL Database cloud application.

Getting Started with the Oracle NoSQL Database Cloud Service

The Oracle NoSQL Database Cloud Service is a server-less, fully managed data store that delivers predictable single-digit response times and allows the application to scale on-demand via provisioning API calls. There are five simple steps to getting started with the Oracle NoSQL Database Cloud Service.

  1. Download the Oracle NoSQL Database .NET SDK
  2.  Create a compartment for your table (if you do not want your table in the root compartment)
  3.  Connect to the Oracle NoSQL Database cloud service
  4.  Create a table with provisioned reads/sec, writes/sec, and GB storage
  5.  Write data to the table and read data from the table

Furthermore, you can use free cloud credits to do all of this and not pay a single penny.  

Once you have created a cloud account, you can either navigate to the Oracle NoSQL Database table management console or if you are like most developers, quickly move onto writing your first hello world code.  You can write your first hello world program using Python, Node.js, Java, Go, and other popular programming languages.  I will use C#, running in .NET for the remainder of this blog.

Download the Oracle NoSQL Database .NET SDK

Since access to the Oracle NoSQL Cloud Service is via HTTP, you can run your application directly on your laptop and connect to the database service over the internet.  While I would never recommend using the internet as a network transport for performance-sensitive applications, it works perfectly for our hello world example.  In fact, it is likely that you would want to deploy a real application by running inside your own tenancy, co-located in the same Oracle Cloud Infrastructure region as your Oracle NoSQL table, and use the Oracle Cloud Infrastructure Service Gateway to connect to the NoSQL Cloud Service.

Like other open-source .NET packages, you can find the Oracle NoSQL Database .NET SDK at NuGet.

When you search for Oracle.NoSQL.SDK, you will see that the latest Oracle NoSQL Driver that lets you connect to the cloud service, is called Oracle NoSQL .NET  and its current version is 5.1.3, so I will choose to install this one locally on my development environment.

Note: Oracle offers NoSQL Database SDK and OCI SDK, we will use NoSQL Database SDK because it offers a rich set of functionalities. OCI SDK is not providing all the features of NoSQL SDK.

You may install the SDK independently into a directory of your choice by using nuget.exe CLI . Or You may add the SDK NuGet Package as a reference to your project by using .Net CLI. Alternatively, you may perform the same using NuGet Package Manager in Visual Studio.

cd <your-project-directory>
dotnet add package Oracle.NoSQL.SDK

nuget.exe install Oracle.NoSQL.SDK -OutputDirectory <your-packages-directory>

Create a Compartment for Your Table

If you would like your table to be created in your own compartment (e.g. demonosql) rather than the root compartment

1) On the left side drop-down (left of Oracle Cloud banner), go to Identity & Security and then Compartments.

2) Click on Create Compartment. This opens up a new window.

Enter demonosql as compartment name, enter a description, and hit ‘Create Compartment’ button at bottom of the window. The parent compartment will display your current parent compartment — this does not need to be changed.

3) Copy the Compartment OCID. It will be used later.

Connect to the Oracle NoSQL Database Cloud Service

The Oracle NoSQL Database Cloud Service uses the Oracle Cloud Infrastructure native cloud Identity Access Manager (IAM) for authentication and authorization.  In the .NET API documentation, (https://oracle.github.io/nosql-dotnet-sdk/tutorials/connect-cloud.html) for the SDK, you can follow the tutorial called Connecting an Application to Oracle NoSQL Database Cloud Service. You can learn all about the NoSQLClient class, which is what I will use to instantiate a connection to the cloud service and authenticate.  In this example, I will use Authorizing with Instance Principal.

Instance Principal is an IAM service feature that enables instances to be authorized actors (or principals) to perform actions on service resources. Each compute instance has its own identity, and it authenticates using the certificates that are added to it.

The code below is structured as follows:

  1. First, call the function NoSQLClient–  This method will perform authentication with the Oracle NoSQL Cloud Service and return a handle to the service.   
  2. Followed by the function ExecuteTableDDLWithCompletionAsync – This function will create a table with two columns; an ID column of type LONG and a content column of type JSON.
  3. Call the following functions:
    • PutAsync– This function will write a single record to the hello world table.
    • GetAsync– This function will read a single record from the hello world table and return this record as a JSON string.
    • DeleteAsync– this function will delete a single record from the hello world table.
  4. Finally, call the function ExecuteTableDDLWithCompletionAsync to drop the hello world table
using Oracle.NoSQL.SDK;
 
var client = new NoSQLClient(
        new NoSQLConfig
          {
              Region = Region.US_ASHBURN_1,
              Compartment = Environment.GetEnvironmentVariable("NOSQL_COMPID"),
              AuthorizationProvider = IAMAuthorizationProvider.CreateWithInstancePrincipal()
          });
 
var tableName = "hello_world";
 
// Create a table
var tableResult = await client.ExecuteTableDDLWithCompletionAsync(
    $"CREATE TABLE IF NOT EXISTS {tableName}(id LONG, content JSON, PRIMARY KEY(id))", new TableLimits(1, 5, 1));
Console.WriteLine("Table {0} created, table state is {1}", tableName, tableResult.TableState);
 
// Put a row
var putResult = await client.PutAsync(tableName, new MapValue
{
    ["id"] = 1,
    ["content"] = new MapValue
    {
        ["Hello"] = "World"
    }
});
 
if (putResult.ConsumedCapacity != null)
{
    Console.WriteLine("Put used: {0}", putResult.ConsumedCapacity);
}
 
var primaryKey = new MapValue
{
    ["id"] = 1
};
 
// Get a row
var getResult = await client.GetAsync(tableName, primaryKey);
if (getResult.Row != null)
{
    Console.WriteLine("Got row: {0}\n", getResult.Row.ToJsonString());
}
else
{
    Console.WriteLine("Row with primaryKey {0} doesn't exist", primaryKey.ToJsonString());
}
 
// Delete a row
var deleteResult = await client.DeleteAsync(tableName, primaryKey);
Console.WriteLine("Delete {0}.", deleteResult.Success ? "succeeded": "failed");
 
// Drop a table
tableResult = await client.ExecuteTableDDLWithCompletionAsync( $"DROP TABLE {tableName}");
Console.WriteLine("Table {0} dropped, table state is {1}", tableName, tableResult.TableState);

If you take the code above and place it in a file entitled Program.cs and set your env variable NOSQL_COMPID to the compartment OCID where you want your table created,  you can run this file as specified below:

$ scl enable rh-dotnet60 bash
 
$ dotnet new console -o MyApp
 
The template "Console App" was created successfully.
 
Processing post-creation actions...
Running 'dotnet restore' on /home/opc/gettingDotNet/MyApp/MyApp.csproj...
  Determining projects to restore...
  Restored /home/opc/gettingDotNet/MyApp/MyApp.csproj (in 106 ms).
Restore succeeded.
 
$ cd MyApp/
 
$ dotnet add package Oracle.NoSQL.SDK
  Determining projects to restore...
  Writing /tmp/tmpb7HUav.tmp
info : Adding PackageReference for package 'Oracle.NoSQL.SDK' into project '/home/opc/gettingDotNet/MyApp/MyApp.csproj'.
info :   GET https://api.nuget.org/v3/registration5-gz-semver2/oracle.nosql.sdk/index.json
info :   OK https://api.nuget.org/v3/registration5-gz-semver2/oracle.nosql.sdk/index.json 88ms
info : Restoring packages for /home/opc/gettingDotNet/MyApp/MyApp.csproj...
info : Package 'Oracle.NoSQL.SDK' is compatible with all the specified frameworks in project '/home/opc/gettingDotNet/MyApp/MyApp.csproj'.
info : PackageReference for package 'Oracle.NoSQL.SDK' version '5.1.3' added to file '/home/opc/gettingDotNet/MyApp/MyApp.csproj'.
info : Committing restore...
info : Writing assets file to disk. Path: /home/opc/gettingDotNet/MyApp/obj/project.assets.json
log  : Restored /home/opc/gettingDotNet/MyApp/MyApp.csproj (in 103 ms).
 
# copy the code
$ vi Program.cs
 
 
$ dotnet run
Table hello_world created, table state is Active
Put used: ReadUnits: 0, ReadKB: 0, WriteUnits: 1, WriteKB: 1
Got row: {"id":1,"content":{"Hello":"World"}}
 
Delete succeeded.
Table hello_world dropped, table state is Dropped

For more information about the .NET SDK and pointers to more example code on Github, take a look here https://github.com/oracle/nosql-dotnet-sdk

If you have questions regarding this exercise, please send an email to oraclenosql-info_ww@oracle.com with “Hello World – .NET” in the subject line, and someone will get back to you as soon as possible.