oracle / oci-dotnet-sdk

Oracle Cloud Infrastructure SDK for .NET
https://cloud.oracle.com/cloud-infrastructure
Other
53 stars 22 forks source link
cloud csharp dotnet oracle oracle-cloud oracle-cloud-infrastructure sdk

Oracle Cloud Infrastructure SDK for .NET

About

The oci-dotnet-sdk provides an SDK for .NET that you can use to manage your Oracle Cloud Infrastructure resources.

The project is open source and maintained by Oracle Corp.

Dependencies

SDK Organization

The oci-dotnet-sdk contain the following 3 groups of packages:

Install Packages

The SDK is published as Nuget packages.

Use either dotnet CLI or Visual Studio to install and consume a package from nuget.org.

dotnet add package <PACKAGE_ID> --version <VERSION> (If version not specified then it pulls the latest version)

Example:
dotnet add package OCI.DotNetSDK.Core (Installs the latest version of the Core Service package)
dotnet add package OCI.DotNetSDK.Identity -v 1.0.0 (Installs version 1.0.0 of the Identity Service package)

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

Documentation

Public documentation and API Reference for the sdk can be found here.

Working with the .NET SDK

To start working with oci-dotnet-sdk, you need to create a .NET project, install packages, create a client, and then use that client to send requests to service endpoint.

Configuring

Before using the SDK, set up a config file with the required credentials. See SDK and Tool Configuration for instructions.

Creating Client

To create a service client, you need to set up the client to use the credentials. Check here on how to configure it.

Example that shows creating the Audit Service client using ConfigFileAuthenticationDetailsProvider Class for configuring credentials:

var provider = new ConfigFileAuthenticationDetailsProvider("DEFAULT");
var client = new AuditClient(provider, new ClientConfiguration());

Sending Request

To send a request to an Oracle Cloud Infrastructure service endpoint, build a request object and send it using the client created above.

var listEventsRequest = new ListEventsRequest
{
    // Assumption: the compartment id has been set in environment variable.
    CompartmentId = compartmentId,
    StartTime = DateTime.Now.AddDays(-1),
    EndTime = DateTime.Now
};

try
{
    var response = await client.ListEvents(listEventsRequest);
}
catch (Exception e)
{
    // Handle the exception.
}

Enable Logging

NLog package is used for logging in .NET projects. This package gets auto-installed as a dependency when you install OCI .NET SDK package. In order to view .NET SDK logs, you will need to:

Only SDK logging will be captured if logger is not created in user application.


Examples

Examples can be found here.

Examples for all supported services can be found at the API reference under their respective reference doc.

To use the example code: copy the sample, change the parameter values to values that make sense for your use case (ex: OCI instance ID with your OCI instance ID), and then you can run the code to have a working automation against OCI.

Building and Testing

Build

Building the SDK can be done at the root of the whole solution or at individual project level under it. At the root level, to build the whole solution, run with dotnet cli command:

dotnet build

or use the included Makefile:

make build

The Makefile also provides an option to build individal projects from the root level:

make build PROJECT_PATH=Common

Alternatively, individual project and be built using dotnet cli inside project directory.

Test

The common package has corresponding unit tests. These tests can be run using dotnet cli command or through Makefile. To run the unit tests from the root, a test filter needs to be provided:

dotnet test --filter Category=Unit

Alternatively, running tests inside common_tests project does not require the filter. To run tests using Makefile:

make unit-test

Help

Contributing

This project welcomes contributions from the community. Before submitting a pull request, please review our contribution guide

Security

Please consult the security guide for our responsible security vulnerability disclosure process

License

Copyright (c) 2020, 2021 Oracle and/or its affiliates. All rights reserved.

This SDK is dual licensed under the Universal Permissive License 1.0 and the Apache License 2.0.

See LICENSE for more details.

Changes

See CHANGELOG

Known Issues

You can find information on any known issues with the SDK at Oracle Cloud Infrastructure Known Issues and under the Issues tab of this project's GitHub repository.