Getting Started

This topic describes how to install and configure the SDK for .NET.

To use a specific Oracle Cloud Infrastructure service in your project, you can use the dotnet add package command from the root directory of your project workspace that contains the project file. The syntax for the add package command is:

dotnet add package <PACKAGE_ID> -v <DESIRED_VERSION>

If you do not specify a version number, the add package command will install the latest version.

This example installs the latest version of the Core Service package:

dotnet add package OCI.DotNetSDK.Core

This example installs version 1.0.0 of the Identity Service package:

dotnet add package OCI.DotNetSDK.Identity -v 1.0.0

Note

To avoid dependency conflicts, you should use the same versions of all OCI. NET SDK Nuget packages within an application.

Downloading the SDK from GitHub

You can download the SDK for .NET as a zip archive from GitHub. It contains the SDK, all of its dependencies, documentation, and examples.

Installing the SDK with Yum

If you're using Oracle Linux 7 or 8, you can use yum to install the OCI SDK for .NET.

To install the OCI SDK for .NET using yum:
1. For Oracle Linux 7:
```
sudo yum-config-manager --enable ol7_developer
sudo yum install oci-dotnet-sdk
```
2. For Oracle Linux 8:
```
sudo yum-config-manager --enable ol8_developer
sudo yum install oci-dotnet-sdk
```
  The OCI Dotnet SDK service packages and its dependencies are located in /usr/lib/dotnet/NuPkgs/.

So the dotnet CLI can find the installed packages, you must do one of the following:

Create a file named nuget.config in the root of your .NET application project and add the following content:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
      <!--To inherit the global NuGet package sources remove the <clear/> line below -->
      <clear />
      <add key="local" value="/usr/lib/dotnet/NuPkgs" />
  </packageSources>
</configuration>

...or...

Use the --source option with the dotnet CLI commands, passing in the directory /usr/lib/dotnet/NuPkgs/. For example:
```
dotnet build --source /usr/lib/dotnet/NuPkgs/
dotnet restore --source /usr/lib/dotnet/NuPkgs/
dotnet add package OCI.DotNetSDK.Common --source /usr/lib/dotnet/NuPkgs/
```

To get information about the installed package, run the following command:
```
rpm  -qi oci-dotnet-sdk
```

Add the OCI Service packages to your project using the dotnet command line:

dotnet add package OCI.DotNetSDK.Common
dotnet add package OCI.DotNetSDK.Audit --version 4.3.0
dotnet add package OCI.DotNetSDK.Audit --version 4.3.0 --source /usr/lib/dotnet/NuPkgs/

You can now import namespaces into your project. For example:

using Oci.AuditService;
using Oci.AuditService.Models;
using Oci.Common;
using Oci.Common.Auth;

Using the SDK for .NET with Nuget

Nuget.

Configuring the SDK

The SDK services need two types of configuration: credentials and client-side HTTP settings.

Configuring Credentials

First, you need to set up your credentials and config file. For instructions, see SDK and CLI Configuration File.

Next, you need to set up the client to use the credentials. The credentials are abstracted through an IAuthenticationDetailsProvider interface that the client needs to implement.

These examples shows implementations of ConfigFileAuthenticationDetailsProvider and SimpleAuthenticationDetailsProvider.

Using a Standard Configuration

If you use standard config file keys and the standard config file location, you can use ConfigFileAuthenticationDetailsProvider:


using Oci.Common.Auth;
 
// uses DEFAULT profile in default file location: i.e ~/.oci/config
var provider = new ConfigFileAuthenticationDetailsProvider("DEFAULT");
// uses custom configuration
var provider = new ConfigFileAuthenticationDetailsProvider("custom_file_location", "CUSTOM_PROFILE");

Using a Custom Configuration

If you are using custom key names in the config file, you can use SimpleAuthenticationDetailsProvider

To load a config with or without a profile:

using Oci.Common;
 
var config = ConfigFileReader.Parse(ConfigFileReader.DEFAULT_FILE_PATH);
var configWithProfile = ConfigFileReader.Parse(ConfigFileReader.DEFAULT_FILE_PATH, "DEFAULT");

Next, create an Auth provider using SimpleAuthenticationDetailsProvider:

using Oci.Common;
using Oci.Common.Auth;
 
var config = ConfigFileReader.Parse(ConfigFileReader.DEFAULT_FILE_PATH);
 
// The private key supplier can be created with the file path,or using the config file
var provider = new SimpleAuthenticationDetailsProvider {
                TenantId = config.GetValue("tenancy"),
                UserId = config.GetValue("user"),
                Fingerprint = config.GetValue("fingerprint"),
                Region = Region.FromRegionId(config.GetValue("region")),
                PrivateKeySupplier = new FilePrivateKeySupplier(config.GetValue("key_file"), config.GetValue("pass_phrase"))
               };

Configuring Client-Side Options

Create a client-side configuration through the ClientConfigurationclass. If you do not provide your own configuration, the SDK for .NET uses a default configuration.

The following example shows how to provide your own configuration:

var clientConfiguration = new ClientConfiguration
{
   ClientUserAgent = "DotNet-SDK-Example",
   RetryConfiguration = new RetryConfiguration
   {
      // maximum number of attempts to retry the same request
      MaxAttempts = 5,
      // retries the request if the response status code is in the range [400-499] or [500-599]
      RetryableStatusCodeFamilies = new List<int> { 4, 5 } 
   }
};

Configuring Custom Options

In the configuration file, you can insert custom key-value pairs that you define, and then reference them as necessary. For example, you could specify a frequently used compartment ID in the config file:

[DEFAULT]
user=ocid1.user.oc1..<your_unique_id>
fingerprint=<your_fingerprint>
key_file=~/.oci/oci_api_key.pem
tenancy=ocid1.tenancy.oc1..<your_unique_id>
customCompartmentId=ocid1.compartment.oc1..<your_unique_id>

Then you can retrieve the value:

using Oci.Common;
var config = ConfigFileReader.parse(ConfigFileReader.DEFAULT_FILE_PATH);
String compartmentId = config.GetValue("customCompartmentId");

Enabling Logging

The OCI SDK for .NET uses the NLog package for logging. NLog is automatically installed with the .NET SDK, so no additional installation is required.

To enable logging in your project:

Add an NLog.config file at the project's root directory. You can find an example NLog.config file here

Add an ItemGroup section in the project file. For example:

<ItemGroup>
     <Content Include="PATH TO NLog.config File" >
          <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
     </Content>
</ItemGroup>

To log from an application, create a Logger and use the Info() method. For example:
```
var logger = NLog.LogManager.GetCurrentClassLogger();
logger.Info("Hello World");
```

Note

Only SDK logging will be captured if you don't create a logger from an application.

Oracle Cloud Infrastructure Documentation