/ServiceBus.AttachmentPlugin

Microsoft Azure Service Bus attachment plugin

Primary LanguageC#MIT LicenseMIT

2023-12-14: The latest ASB SDK doesn't support plugins and requires inheritance. See details in #201.

2021-07-14: Consider using native Azure Service Bus service large messages feature for attachments up-to 100 MB.

Icon

Allows sending messages that exceed maximum size by implementing Claim Check pattern with Azure Storage.

license develop opened issues

Nuget package

NuGet Status

Available here http://nuget.org/packages/ServiceBus.AttachmentPlugin

To Install from the Nuget Package Manager Console

PM> Install-Package ServiceBus.AttachmentPlugin

Contents

Examples

Convert body into attachment, no matter how big it is

Configuration and registration

var sender = new MessageSender(connectionString, queueName);
var config = new AzureStorageAttachmentConfiguration(storageConnectionString);
sender.RegisterAzureStorageAttachmentPlugin(config);

snippet source | anchor

Sending

var payload = new MyMessage
{
    MyProperty = "The Value"
};
var serialized = JsonConvert.SerializeObject(payload);
var payloadAsBytes = Encoding.UTF8.GetBytes(serialized);
var message = new Message(payloadAsBytes);

snippet source | anchor

Receiving

var receiver = new MessageReceiver(connectionString, entityPath, ReceiveMode.ReceiveAndDelete);
receiver.RegisterAzureStorageAttachmentPlugin(config);
var message = await receiver.ReceiveAsync().ConfigureAwait(false);
// message will contain the original payload

snippet source | anchor

Sending a message without exposing the storage account to receivers

Configuration and registration with blob SAS URI

var sender = new MessageSender(connectionString, queueName);
var config = new AzureStorageAttachmentConfiguration(storageConnectionString)
    .WithBlobSasUri(
        sasTokenValidationTime: TimeSpan.FromHours(4),
        messagePropertyToIdentifySasUri: "mySasUriProperty");
sender.RegisterAzureStorageAttachmentPlugin(config);

snippet source | anchor

Sending

var payload = new MyMessage
{
    MyProperty = "The Value"
};
var serialized = JsonConvert.SerializeObject(payload);
var payloadAsBytes = Encoding.UTF8.GetBytes(serialized);
var message = new Message(payloadAsBytes);

snippet source | anchor

Receiving only mode (w/o Storage account credentials)

// Override message property used to identify SAS URI
// .RegisterAzureStorageAttachmentPluginForReceivingOnly() is using "$attachment.sas.uri" by default
messageReceiver.RegisterAzureStorageAttachmentPluginForReceivingOnly("mySasUriProperty");
var message = await messageReceiver.ReceiveAsync().ConfigureAwait(false);

snippet source | anchor

Configure blob container name

Default container name is "attachments". The value is available via AzureStorageAttachmentConfigurationConstants.DefaultContainerName constant.

new AzureStorageAttachmentConfiguration(storageConnectionString, containerName:"blobs");

Configure message property to identify attachment blob

Default blob identifier property name is "$attachment.blob". The value is available via AzureStorageAttachmentConfigurationConstants.DefaultMessagePropertyToIdentifyAttachmentBlob constant.

new AzureStorageAttachmentConfiguration(storageConnectionString, messagePropertyToIdentifyAttachmentBlob: "myblob");

Configure custom blob name override

Default blob name is a GUID.

var sender = new MessageSender(connectionString, queueName);
var config = new AzureStorageAttachmentConfiguration(storageConnectionString)
    .OverrideBlobName(message =>
    {
        var tenantId = message.UserProperties["tenantId"].ToString();
        var blobName = $"{tenantId}/{message.MessageId}";
        return blobName;
    });
sender.RegisterAzureStorageAttachmentPlugin(config);

snippet source | anchor

Configure message property for SAS uri to attachment blob

Default SAS uri property name is "$attachment.sas.uri". The value is available via AzureStorageAttachmentConfigurationConstants.DefaultMessagePropertyToIdentitySasUri constant.

Default SAS token validation time is 7 days.

new AzureStorageAttachmentConfiguration(storageConnectionString)
    .WithBlobSasUri(
        messagePropertyToIdentifySasUri: "mySasUriProperty",
        sasTokenValidationTime: TimeSpan.FromHours(12));

snippet source | anchor

Configure criteria for message max size identification

Default is to convert any body to attachment.

// messages with body > 200KB should be converted to use attachments
new AzureStorageAttachmentConfiguration(storageConnectionString,
    messageMaxSizeReachedCriteria: message => message.Body.Length > 200 * 1024);

snippet source | anchor

Configuring connection string provider

When Storage connection string needs to be retrieved rather than passed in as a plain text, AzureStorageAttachmentConfiguration accepts implementation of IProvideStorageConnectionString. The plugin comes with a PlainTextConnectionStringProvider and can be used in the following way.

var provider = new PlainTextConnectionStringProvider(connectionString);
var config = new AzureStorageAttachmentConfiguration(provider);

snippet source | anchor

Configuring plugin using StorageCredentials (Service or Container SAS)

var credentials = new StorageCredentials( /*Shared key OR Service SAS OR Container SAS*/);
var config = new AzureStorageAttachmentConfiguration(credentials, blobEndpoint);

snippet source | anchor

See StorageCredentials for more details.

Using attachments with Azure Functions

Azure Functions currently has no way to register plugins, these extension methods are a workaround until this feature is added.

To use the extensions, your Function must return (send) or take as parameter (receive) an instance of Message.

Upload attachment to Azure Storage blob

//To make it possible to use SAS URI when downloading, use WithBlobSasUri() when creating configuration object
await message.UploadAzureStorageAttachment(config);

snippet source | anchor

Download attachment from Azure Storage blob

//Using SAS URI with default message property ($attachment.sas.uri)
await message.DownloadAzureStorageAttachment();

//Using SAS URI with custom message property
await message.DownloadAzureStorageAttachment("$custom-attachment.sas.uri");

//Using configuration object
await message.DownloadAzureStorageAttachment(config);

snippet source | anchor

Additional providers

Cleanup

The plugin does NOT implement cleanup for the reasons stated here. When cleanup is required, there are a few options available depending on the use case.

Who's trusting this plugin in production

Microsoft Codit Hemonto

Proudly list your company here if use this plugin in production

Icon

Created by Dinosoft Labs from the Noun Project.