Getting Started
This topic describes how to install and configure the SDK for .NET.
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
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
- To install the OCI SDK for .NET using yum:
-
For Oracle Linux 7:
sudo yum-config-manager --enable ol7_developer sudo yum install oci-dotnet-sdk
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:
...or...<?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>
- 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/
- Create a file named
- 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
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
.
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");
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 ClientConfiguration
class. 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.
- 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 theInfo()
method. For example:var logger = NLog.LogManager.GetCurrentClassLogger(); logger.Info("Hello World");
Only SDK logging will be captured if you don't create a logger from an application.