Picton 9.0.0

Picton

About

Picton is a library intendent to make it easier to work with Azure storage.

The main features in this library are:

1) Extension metods:

The extension methods allow operations on blob while holding a lock (also known as a 'lease'). Specifically:

• Lock a blob for a given period of time with retries in case it is already locked by another process
• Extend an existing lease
• Release an existing lease
• Overwrite the content of a blob with a given string (there are also similar methods to upload a byte array or a stream)
• Append a given string to a blob (there are also similar methods to append a byte array or a stream)
• Update the metadata associated with a blob
• Download the content of a blob to a string (there is also a similar method to download the content to a byte[])
• Make a copy of a blob
• Get a URI which can be used to gain access to a blob for a limid period of time

2) Abstractions:

Early versions of the Picton library contained several interfaces to overcome the fact that most classed in the Azure Storage library where sealed and/or their methods where not marked as virtual and therefore not "mockable". In release 7.0 of the Azure Storage library, Microsoft unsealed most classes and marked most methods as virtual which is quite significant because it allows mocking these classes when they are injected in one of your own classes. The Azure Storage library was further improved in version 8.0 to update the Get*Reference methods with the "virtual" qualifier. The Azure Storage library was again improved in version 9.0 to unseal the StorageAccount class. This was the last hurdle that prevented "mocking" the Azure storage library in unit tests. This means that all interfaces and wrapper classes in the Picton library have become obsolete and have ben removed in version 3.0.

3) Managers

The Blob and Queue managers are helpers that simplify common blob and queue related tasks. For example, the QueueManager automatically serializes and stores a message to a temporary location if the message exceeds the maximum size allowed in an Azure queue. Another example: the Blob queue can automatically request a lock (AKA lease) before attempting to modify the content of a blob and it automatically releases the lock once the operation is completed.

4) Misc

• AzureEmulatorManager alows starting the Azure Storage Emulator which you may need prior to executing integration testing

Nuget

Picton is available as a Nuget package.

Installation

The easiest way to include Picton in your C# project is by grabing the nuget package:

PM> Install-Package Picton

Once you have the Picton library properly referenced in your project, add the following namespace(s):

using Picton;            // This is always required
using Picton.Managers;   // This is only required if you want to use BlobManager or QueueManager

Usage

1) Blob extension metods:

Fist of all, some boilerplate code necessary for the code samples below:

var cancellationToken = CancellationToken.None;
var connectionString = "UseDevelopmentStorage=true";

var container = new BlobContainerClient(connectionString, "mycontainer");
await container.CreateIfNotExistsAsync(PublicAccessType.None, cancellationToken).ConfigureAwait(false);
var blob = container.GetBlockBlobClient("MyBlob.txt");

Here are a few examples how to use the extension methods:

var leaseId = await blob.TryAcquireLeaseAsync(TimeSpan.FromSeconds(15), 5, cancellationToken).ConfigureAwait(false);
await blob.UploadTextAsync("Hello World", leaseId, cancellationToken).ConfigureAwait(false);
await blob.AppendTextAsync("More content", leaseId, cancellationToken).ConfigureAwait(false);
await blob.AppendTextAsync("Even more content", leaseId, cancellationToken).ConfigureAwait(false);
await blob.TryRenewLeaseAsync(leaseId, cancellationToken).ConfigureAwait(false);
await blob.AppendTextAsync("More more more", leaseId, cancellationToken).ConfigureAwait(false);
await blob.ReleaseLeaseAsync(leaseId, cancellationToken).ConfigureAwait(false);

var content = await blob.DownloadTextAsync(cancellationToken).ConfigureAwait(false);
await blob.CopyAsync("MyCopy.txt", cancellationToken).ConfigureAwait(false);

var permission = SharedAccessBlobPermissions.Read;
var duration = TimeSpan.FromMinutes(30);
var accessUri = await blob.GetSharedAccessSignatureUri(permission, duration).ConfigureAwait(false);

2) Managers

var connectionString = "UseDevelopmentStorage=true";
var blobManager = new BlobManager(connectionString, "mycontainer");

await blobManager.CopyBlobAsync("test.txt", "test - Copy of.txt", cancellationToken).ConfigureAwait(false);

await blobManager.UploadTextAsync("test2.txt", "Hello World", cancellationToken: cancellationToken).ConfigureAwait(false);
await blobManager.AppendTextAsync("test2.txt", "qwerty", cancellationToken: cancellationToken).ConfigureAwait(false);

foreach (var blob in blobManager.ListBlobs("test", false, false))
{
    Console.WriteLine(blob.Uri.AbsoluteUri);
}

await blobManager.DeleteBlobAsync("test - Copy of.txt", cancellationToken).ConfigureAwait(false);
await blobManager.DeleteBlobsWithPrefixAsync("test", cancellationToken).ConfigureAwait(false);

3) Misc

class Program
{
    static void Main()
    {
        AzureEmulatorManager.EnsureStorageEmulatorIsStarted();

        var cancellationToken = CancellationToken.None;
        var connectionString = "UseDevelopmentStorage=true";
        var container = new BlobContainerClient(connectionString, "mycontainer");
		await container.CreateIfNotExistsAsync(PublicAccessType.None, cancellationToken).ConfigureAwait(false);
    }
}

License