Picton 8.0.0

.NET 5.0
Install-Package Picton -Version 8.0.0
dotnet add package Picton --version 8.0.0
<PackageReference Include="Picton" Version="8.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Picton --version 8.0.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: Picton, 8.0.0"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install Picton as a Cake Addin
#addin nuget:?package=Picton&version=8.0.0

// Install Picton as a Cake Tool
#tool nuget:?package=Picton&version=8.0.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Picton

License Build status Coverage Status CodeFactor FOSSA Status

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.

NuGet Version

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

FOSSA Status

Product Versions
.NET net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Picton:

Package Downloads
Picton.Messaging

High performance message processor (also known as a message "pump") designed to process messages from an Azure storage queue as efficiently as possible

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
8.0.0 89 4/8/2022
7.1.0 514 3/16/2020
7.0.0 386 3/13/2020
6.0.0 578 5/19/2019
5.0.0 582 1/29/2019
4.1.0 495 1/15/2019
4.0.0 890 5/31/2018
3.1.0 703 5/24/2018
3.0.0 1,225 2/13/2018
2.3.1 702 2/13/2018
2.3.0 687 2/11/2018
2.2.1 1,012 12/27/2017
2.2.0 836 12/26/2017
2.1.0 1,641 7/14/2017
2.0.0 771 7/4/2017
1.4.1 742 10/7/2016
1.4.0 702 10/7/2016
1.3.0 700 10/3/2016
1.2.0 765 9/12/2016
1.1.0 729 9/6/2016