API Documentation .NET Framework
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.
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.
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
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);
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);
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);
}
Cloud providers 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.
To get a list of folders, call ListFolders which returns a List objects. CloudFolder.Name contains the folder name.
List<CloudFolder> folders = storage.ListFolders();
foreach(CloudFolder folder in folders)
{
Console.WriteLine(folder.Name);
}
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);
}