Skip to content

Latest commit

 

History

History
140 lines (99 loc) · 5.21 KB

README.md

File metadata and controls

140 lines (99 loc) · 5.21 KB
Raw

DS3 .Net SDK

Build Status Apache V2 License

An SDK conforming to the DS3 specification.

Contact Us

Join us at our Google Groups forum to ask questions, or see frequently asked questions.

Setting up NuGet

The SDK is distributed as a NuGet package for .Net 4.5.1 and above. From the NuGet website:

What is NuGet?

NuGet is the package manager for the Microsoft development platform including .NET. The NuGet client tools provide the ability to produce and consume packages. The NuGet Gallery is the central package repository used by all package authors and consumers.

Create a package feed on your computer using the latest release:

  1. Download the .nupkg file from the Releases page to a new directory of your choice.
  2. Follow the NuGet instructions on Creating Local Feeds using the directory that you've created.

This makes the DS3 SDK available for installation into a Visual Studio .NET Project.

Using the Examples Project

The Releases page has an examples project that references the DS3 SDK package.

  1. Unzip DS3Examples.zip and open the DS3Examples.sln file in Visual Studio.
  2. Edit the App.config file to use the endpoint, access key, and secret key for your DS3 applicance.
  3. Right-click the DS3Examples project in the Solution Explorer and click "Properties".
  4. Choose which of the four examples you'd like to run from the "Startup Object" dropdown box.
  5. Press the F5 key to run the program within Visual Studio.

Each of the example programs in the project contains a description at the top explaining what the program does.

Installing the DS3 SDK Into Your Own Project

You can also install the SDK into your own project.

  1. Open your existing .NET project or create a new one.
  2. Right-click the project and click "Manage NuGet Packages..."
  3. Click "Online" on the left panel.
  4. In the search box on the upper right, type "DS3".
  5. Click the "Install" button next to the "DS3 .NET SDK" package and close the package manager dialog.

Your project should now reference the SDK and be able to use its API.

About the API

The SDK consists of two levels of abstraction:

  1. A high level interface (Ds3.Helpers.IDs3ClientHelpers) that abstracts several very common application requirements.
  2. The core client interface (Ds3.IDs3Client) whose method calls each result in exactly one HTTP request.

Some aspects of the low-level Amazon S3 and Spectra Logic DS3 requests require a fair amount of non-obvious boilerplate logic that's the same in every application. Thus we strongly recommend that all SDK users use the higher level interface wherever possible.

As an example, the standard Amazon S3 request to list objects in a bucket only returns 1,000 results at a time and must be called repeatedly with paging parameters to get a complete list. Since the code to do this will likely be the same regardless of the application, we've created the ListObjects method to handle this paging for you.

Instantiating the API

The example below shows how to configure and instantiate Ds3.IDs3Client and Ds3.Helpers.IDs3ClientHelpers.

using Ds3;
using Ds3.Helpers;
using System.Configuration;

namespace YourApplication
{
    class YourClass
    {
        public void YourMethod()
        {
            // Configure and build the core client.
            IDs3Client client = new Ds3Builder(
                "http://ds3-endpoint",
                new Credentials("access key", "secrete key")
            ).Build();

            // Set up the high-level abstractions.
            IDs3ClientHelpers helpers = new Ds3ClientHelpers(client);

            // Use functionality from 'helpers' and 'client', preferring 'helpers'.
            // ...
        }
    }
}

SDK Development Resources

Running Unit Tests

Building from Source

Building the DS3 SDK NuGet Package

API documentation resides in the gh-pages branch. See the README.md there for information on how to regenerate the API documentation.

Creating a New Release

Update the version of the SDK before creating a new release. The format is <major>.<minor>.<patch>, where the <major>.<minor> numbers must match the version of BP. The <patch> is an incrementing number that increments with each SDK release for a given major/minor release.

The version is located in VersionInfo.cs.