Microsoft.CoreWCF.Azure.StorageQueues 1.0.0-beta.1

CoreWCF Azure Queue Storage library for .NET

CoreWCF Azure Queue Storage is the service side library that will help existing WCF services to be able to use Azure Queue Storage to communicate with clients as a modern replacement to using MSMQ.

Getting started

Install the package

Install the Microsoft.CoreWCF.Azure.StorageQueues library for .NET with NuGet:

dotnet add package Microsoft.CoreWCF.Azure.StorageQueues --prerelease

Prerequisites

You need an Azure subscription and a Storage Account to use this package.

To create a new Storage Account, you can use the Azure portal, Azure PowerShell, or the Azure CLI. Here's an example using the Azure CLI:

az storage account create --name MyStorageAccount --resource-group MyResourceGroup --location westus --sku Standard_LRS

Configure ASP.NET Core to use CoreWCF with Queue transports

In order to receive requests from the Azure Queue Storage service, you'll need to configure CoreWCF to use queue transports.

public void ConfigureServices(IServiceCollection services)
{
    services.AddServiceModelServices()
            .AddQueueTransport();
}

Authenticate the service to Azure Queue Storage

To receive requests from the Azure Queue Storage service, you'll need to configure CoreWCF with the appropriate endpoint, and configure credentials. The Azure Identity library makes it easy to add Microsoft Entra ID support for authenticating with Azure services.

There are multiple authentication mechanisms for Azure Queue Storage. Which mechanism to use is configured via the property AzureQueueStorageBinding.Security.Transport.ClientCredentialType. The default authentication mechanism is Default, which uses DefaultAzureCredential.

public void Configure(IApplicationBuilder app)
{
    app.UseServiceModel(serviceBuilder =>
    {
        // Configure CoreWCF to dispatch to service type Service
        serviceBuilder.AddService<Service>();

        // Create a binding instance to use Azure Queue Storage, passing an optional queue name for the dead letter queue
        // The default client credential type is Default, which uses DefaultAzureCredential
        var aqsBinding = new AzureQueueStorageBinding("DEADLETTERQUEUENAME");

        // Add a service endpoint using the AzureQueueStorageBinding
        string queueEndpointString = "https://MYSTORAGEACCOUNT.queue.core.windows.net/QUEUENAME";
        serviceBuilder.AddServiceEndpoint<Service, IService>(aqsBinding, queueEndpointString);
    });
}

Learn more about enabling Microsoft Entra ID for authentication with Azure Storage in our documentation.

Other authentication credential mechanisms

If you are using a different credential mechanism such as StorageSharedKeyCredential, you configure the appropriate ClientCredentialType on the binding and set the credential on an AzureServiceCredentials instance via an extension method.

public void Configure(IApplicationBuilder app)
{
    app.UseServiceModel(serviceBuilder =>
    {
        // Configure CoreWCF to dispatch to service type Service
        serviceBuilder.AddService<Service>();

        // Create a binding instance to use Azure Queue Storage, passing an optional queue name for the dead letter queue
        var aqsBinding = new AzureQueueStorageBinding("DEADLETTERQUEUENAME");

        // Configure the client credential type to use StorageSharedKeyCredential
        aqsBinding.Security.Transport.ClientCredentialType = AzureClientCredentialType.StorageSharedKey;

        // Add a service endpoint using the AzureQueueStorageBinding
        string queueEndpointString = "https://MYSTORAGEACCOUNT.queue.core.windows.net/QUEUENAME";
        serviceBuilder.AddServiceEndpoint<Service, IService>(aqsBinding, queueEndpointString);

        // Use extension method to configure CoreWCF to use AzureServiceCredentials and set the
        // StorageSharedKeyCredential instance.
        serviceBuilder.UseAzureCredentials<Service>(credentials =>
        {
            credentials.StorageSharedKey = GetStorageSharedKey();
        });
    });
}

public StorageSharedKeyCredential GetStorageSharedKey()
{
    // Fetch shared key using a secure mechanism such as Azure Key Vault
    // and construct an instance of StorageSharedKeyCredential to return;
    return default;
}

Other values for ClientCredentialType are Sas, Token, and ConnectionString. The credentials class AzureServiceCredentials has corresponding properties to set each of these credential types.

Troubleshooting

If there are any errors receiving a message from Azure Queue Storage, the CoreWCF transport will log the details at the Debug log level. You can configure logging for the category Microsoft.CoreWCF at the Debug level to see any errors.

.ConfigureLogging((logging) =>
{
    logging.AddFilter("Microsoft.CoreWCF", LogLevel.Debug);
});

If a message was recevied from the queue, but wasn't able to be processed, it will be placed in the dead letter queue. You can sepcify the dead letter queue name by passing it to the constructor of AzureQueueStorageBinding. If not specified, the default value of default-dead-letter-queue will be used.

Key concepts

CoreWCF is an implementation of the service side features of Windows Communication Foundation (WCF) for .NET. The goal of this project is to enable migrating existing WCF services to .NET that are currently using MSMQ and wish to deploy their service to Azure, replacing MSMQ with Azure Queue Storage.

More general samples of using CoreWCF can be found in the CoreWCF samples repository. To create a client to send messages to an Azure Storage Queue, see theMicrosoft.WCF.Azure.StorageQueues documentation.

Contributing

See the Storage CONTRIBUTING.md for details on building,testing, and contributing to this library.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.