API Documentation .NET Framework

David Pallmann edited this page Feb 1, 2019 · 7 revisions

PolyCloud.Storage API | .NET Framework Documentation

Overview

PolyCloud.Storage is a unified API for accessing cloud storage on multiple cloud platforms. The API provides basic operations for working with folders (buckets on AWS and GCP; containers on Azure) and files (objects on AWS and GCP; blobs on Azure). The API focuses on common operations available for the three cloud platforms; to get at features specific to only one platform, you'll need to write your own code.

Connecting

To connect to a particular platform, call Storage.AWS, Storage.Azure, or Storage.GCP and pass in credentials. The credential arguments are different for each platform. This will return an AWSStorage, AzureStorage, or GCPStorage instance, all of which are implementations of base class Storage.

After instantiating an instance, call the Open method to open the connection. After performing storage operations, call Close to close the connection.

Example:

Storage storage = Storage.AWS(accessKey, secretKey, endpointName);
storage.Open();
List<CloudFolder> folders = storage.ListFolders();
...do something...
storage.Close();

Be sure to always protect your storage credentials.

AWS

To connect to an AWS S3 account, call Storage.AWS, specifying access key, secretkey, and S3 region name, such as "us-east-1".

String accessKey = "BKIAIBVVWJCZIPZQM2ZA";
String secretKey = "vQlSUFBSLr5x3FvyccBJy5rcD3e93Ftwzic18gQH";
String endpoint = "us-east-1";

Storage storage = Storage.AWS(accessKey, secretKey, endpointName);    // Explicit authentication

Note that if your code will be running on EC2, you may leave out access key and secret key; this will use implicit credentials based on the role assigned to your EC2 instance. This is an AWS security best practice, but can only be used when your code is running on EC2; when running elsewhere (on your desktop PC for example) you'll need to specify an access key and secret key.

Storage storage = Storage.AWS(endpointName);    // Implicit authentication on EC2

Azure

To connect to an Azure Blob Storage account, call Storage.Azure, specifying account Id and account Key.

String accountId = "my-blob-account-name";
String accountKey = "Y7JTgm7B2g53t8MZ1N+GmuQ8d3aHyf0tGo5uglt7OIF3M2roaFiX6jPPI2mWmIOh/6suLEAMVXF5GPXPFl2nOQ==";

Storage storage = Storage.Azure(accountId, accountKey);

Google CloudPlatform

To connect to a Google Cloud Platorm Storage account, call Storage.GCP, specifying the path to your downloaded JSON file and your project Id.

String jsonPath = @"C:\gcp-storage\helloworld-328219-ca4bb62a59c8.json";
String projectId = "918968012956";

Storage storage = Storage.GCP(jsonPath, projectId);

Error Handling

Most of the time, it's good for an API to allow the caller to handle errors. This permits explicit catching of specific exceptions and preserves the option to bubble up to a higher level for handling. However, the unique multi-platform nature of PolyCloud.Storage makes this a burden the developer may want handled for them. For this reason, PolyCloud.Storage handles exceptions by default. Most methods either return true on success / false on error; or return an object on success / null on error. In this mode, the caller can always find out the last exception using the Exception property of the Storage object.

// Default error handling

Storage storage = Storage.GCP(jsonPath, projectId);
...
if (!storage.NewFolder("my-new-folder"))
{
    Console.WriteLine("An error occurred creating the folder: " + storage.Exception.Message);
}

If the caller prefers control over error handling, simply set the HandleErrors property to false after instantiating. The caller should then use try-catch to deal with errors.

// Caller-controller error handling

Storage storage = Storage.GCP(jsonPath, projectId);
storage.HandleErrors = false;
...
try
{
    bool result = storage.NewFolder("my-new-folder");
}
catch(Google.GoogleApiException ex)
{
    Console.WriteLine("An error occurred creating the folder: " + ex.Message);
}

Working with Folders

Cloud platforms use different terms for collections of storage objects: Azure calls them containers, while AWS and GCP call them buckets. PolyCloud.Storage uses the more familiar term folders.

List Folders

To get a list of folders, call ListFolders which returns a List object. CloudFolder.Name contains the folder name. Note: on some platforms, listing folders will only return the first 1000 folders.

List<CloudFolder> folders = storage.ListFolders();
if (folders != null)
{
    foreach(CloudFolder folder in folders)
    {
        Console.WriteLine(folder.Name);
    }
}

Create a Folder

To create a new folder, call the NewFolder method and specify the new folder name. Be careful to observe the target platform's rules for valid folder names which typically must be unique. You may be restricted to certain characters, a certain case, and a maximum length. A result of true indicates success.

if (!storage.NewFolder("my-new-folder"))
{
    Console.WriteLine("An error occurred creating the folder: " + storage.Exception.Message);
}

Delete a Folder

To delete a folder, call the DeleteFolder method and specify the folder name. A result of true indicates success. Note: on some platforms such as GCP, a folder may not be deleted if it contains files.

storage.DeleteFolder(folderName);

Working with Files

As with folders, cloud platforms use different terms for storage objects: Azure calls them blobs, while AWS and GCP call them objects. PolyCloud.Storage uses the more familiar term files.

List Files

To get a list of files in a folder, call ListFiles which returns a List object, specifying the name of the target folder. CloudFile.Name contains the file name. Note: on some platforms, listing files will only return the first 1000 files.

List<CloudFile> files = storage.ListFiles("my-folder");
if (files != null)
{
    foreach(CloudFile file in files)
    {
        Console.WriteLine(file.Name);
    }
}

Upload a File

To upload a file to cloud storage, call the UploadFile method. Specify the folder name and a local path to the file. A result of true indicates success.

String folderName = "my-folder";
String filePath = "c:\\docs\\document1.pdf";
storage.UploadFile(folderName, filePath);

Download a File

To download a file from cloud storage, call the DownloadFile method. Specify the folder name, file name, and local file path. A result of true indicates success.

String folderName = "my-folder";
String fileName = "document1.pdf";
String filePath = "c:\\docs\\document1.pdf";
storage.DownloadFile(folderName, fileName, filePath);
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.