|
| 1 | +# CoreWCF Azure Queue Storage library for .NET |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +## Getting started |
| 6 | + |
| 7 | +### Install the package |
| 8 | + |
| 9 | +Install the Microsoft.CoreWCF.Azure.StorageQueues library for .NET with [NuGet][nuget]: |
| 10 | + |
| 11 | +```dotnetcli |
| 12 | +dotnet add package Microsoft.CoreWCF.Azure.StorageQueues |
| 13 | +``` |
| 14 | + |
| 15 | +### Prerequisites |
| 16 | + |
| 17 | +You need an [Azure subscription][azure_sub] and a |
| 18 | +[Storage Account][storage_account_docs] to use this package. |
| 19 | + |
| 20 | +To create a new Storage Account, you can use the [Azure portal][storage_account_create_portal], |
| 21 | +[Azure PowerShell][storage_account_create_ps], or the [Azure CLI][storage_account_create_cli]. |
| 22 | +Here's an example using the Azure CLI: |
| 23 | + |
| 24 | +```azurecli |
| 25 | +az storage account create --name MyStorageAccount --resource-group MyResourceGroup --location westus --sku Standard_LRS |
| 26 | +``` |
| 27 | + |
| 28 | +### Configure ASP.NET Core to use CoreWCF with Queue transports |
| 29 | + |
| 30 | +In order to receive requests from the Azure Queue Storage service, you'll need to configure CoreWCF to use queue transports. |
| 31 | + |
| 32 | +```C# Snippet:Configure_CoreWCF_QueueTransport |
| 33 | +public void ConfigureServices(IServiceCollection services) |
| 34 | +{ |
| 35 | + services.AddServiceModelServices() |
| 36 | + .AddQueueTransport(); |
| 37 | +} |
| 38 | +``` |
| 39 | + |
| 40 | +### Authenticate the service to Azure Queue Storage |
| 41 | + |
| 42 | +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][identity] makes it easy to add Microsoft Entra ID support for authenticating with Azure services. |
| 43 | + |
| 44 | +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`. |
| 45 | + |
| 46 | +```C# Snippet:CoreWCF_Azure_Storage_Queues_Sample_DefaultAzureCredential |
| 47 | +public void Configure(IApplicationBuilder app) |
| 48 | +{ |
| 49 | + app.UseServiceModel(serviceBuilder => |
| 50 | + { |
| 51 | + // Configure CoreWCF to dispatch to service type Service |
| 52 | + serviceBuilder.AddService<Service>(); |
| 53 | + |
| 54 | + // Create a binding instance to use Azure Queue Storage, passing an optional queue name for the dead letter queue |
| 55 | + // The default client credential type is Default, which uses DefaultAzureCredential |
| 56 | + var aqsBinding = new AzureQueueStorageBinding("DEADLETTERQUEUENAME"); |
| 57 | + |
| 58 | + // Add a service endpoint using the AzureQueueStorageBinding |
| 59 | + string queueEndpointString = "https://MYSTORAGEACCOUNT.queue.core.windows.net/QUEUENAME"; |
| 60 | + serviceBuilder.AddServiceEndpoint<Service, IService>(aqsBinding, queueEndpointString); |
| 61 | + }); |
| 62 | +} |
| 63 | +``` |
| 64 | + |
| 65 | +Learn more about enabling Microsoft Entra ID for authentication with Azure Storage in [our documentation][storage_ad]. |
| 66 | + |
| 67 | +### Other authentication credential mechanisms |
| 68 | + |
| 69 | +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. |
| 70 | + |
| 71 | +```C# Snippet:CoreWCF_Azure_Storage_Queus_Sample_StorageSharedKey |
| 72 | +public void Configure(IApplicationBuilder app) |
| 73 | +{ |
| 74 | + app.UseServiceModel(serviceBuilder => |
| 75 | + { |
| 76 | + // Configure CoreWCF to dispatch to service type Service |
| 77 | + serviceBuilder.AddService<Service>(); |
| 78 | + |
| 79 | + // Create a binding instance to use Azure Queue Storage, passing an optional queue name for the dead letter queue |
| 80 | + var aqsBinding = new AzureQueueStorageBinding("DEADLETTERQUEUENAME"); |
| 81 | + |
| 82 | + // Configure the client credential type to use StorageSharedKeyCredential |
| 83 | + aqsBinding.Security.Transport.ClientCredentialType = AzureClientCredentialType.StorageSharedKey; |
| 84 | + |
| 85 | + // Add a service endpoint using the AzureQueueStorageBinding |
| 86 | + string queueEndpointString = "https://MYSTORAGEACCOUNT.queue.core.windows.net/QUEUENAME"; |
| 87 | + serviceBuilder.AddServiceEndpoint<Service, IService>(aqsBinding, queueEndpointString); |
| 88 | + |
| 89 | + // Use extension method to configure CoreWCF to use AzureServiceCredentials and set the |
| 90 | + // StorageSharedKeyCredential instance. |
| 91 | + serviceBuilder.UseAzureCredentials<Service>(credentials => |
| 92 | + { |
| 93 | + credentials.StorageSharedKey = GetStorageSharedKey(); |
| 94 | + }); |
| 95 | + }); |
| 96 | +} |
| 97 | + |
| 98 | +public StorageSharedKeyCredential GetStorageSharedKey() |
| 99 | +{ |
| 100 | + // Fetch shared key using a secure mechanism such as Azure Key Vault |
| 101 | + // and construct an instance of StorageSharedKeyCredential to return; |
| 102 | + return default; |
| 103 | +} |
| 104 | +``` |
| 105 | + |
| 106 | +Other values for ClientCredentialType are `Sas`, `Token`, and `ConnectionString`. The credentials class `AzureServiceCredentials` has corresponding properties to set each of these credential types. |
| 107 | + |
| 108 | +## Troubleshooting |
| 109 | + |
| 110 | +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. |
| 111 | + |
| 112 | +```C# Snippet:CoreWCF_Azure_Storage_Queus_Sample_Logging |
| 113 | +.ConfigureLogging((logging) => |
| 114 | +{ |
| 115 | + logging.AddFilter("Microsoft.CoreWCF", LogLevel.Debug); |
| 116 | +}); |
| 117 | +``` |
| 118 | + |
| 119 | +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. |
| 120 | + |
| 121 | +## Key concepts |
| 122 | + |
| 123 | +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. |
| 124 | + |
| 125 | +More general samples of using CoreWCF can be found in the [CoreWCF samples repository][corewcf_repo]. To create a client to send messages to an Azure Storage Queue, see the[Microsoft.WCF.Azure.StorageQueues documentation][wcf_docs]. |
| 126 | + |
| 127 | +## Contributing |
| 128 | + |
| 129 | +See the [Storage CONTRIBUTING.md][storage_contrib] for details on building,testing, and contributing to this library. |
| 130 | + |
| 131 | +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][cla]. |
| 132 | + |
| 133 | +This project has adopted the [Microsoft Open Source Code of Conduct][coc]. |
| 134 | +For more information see the [Code of Conduct FAQ ][coc_faq] or contact [[email protected]][coc_contact] with any additional questions or comments. |
| 135 | + |
| 136 | +<!-- LINKS --> |
| 137 | +[nuget]: https://www.nuget.org/ |
| 138 | +[storage_account_docs]: https://learn.microsoft.com/azure/storage/common/storage-account-overview |
| 139 | +[storage_account_create_ps]: https://learn.microsoft.com/azure/storage/common/storage-account-create?tabs=azure-powershell |
| 140 | +[storage_account_create_cli]: https://learn.microsoft.com/azure/storage/common/storage-account-create?tabs=azure-cli |
| 141 | +[storage_account_create_portal]: https://learn.microsoft.com/azure/storage/common/storage-account-create?tabs=azure-portal |
| 142 | +[azure_cli]: https://learn.microsoft.com/cli/azure/ |
| 143 | +[azure_sub]: https://azure.microsoft.com/free/dotnet/ |
| 144 | +[identity]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/identity/Azure.Identity/README.md |
| 145 | +[storage_ad]: https://learn.microsoft.com/azure/storage/blobs/authorize-access-azure-active-directory |
| 146 | +[storage_contrib]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/storage/CONTRIBUTING.md |
| 147 | +[cla]: https://opensource.microsoft.com/cla/ |
| 148 | +[coc]: https://opensource.microsoft.com/codeofconduct/ |
| 149 | +[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ |
| 150 | +[coc_contact]: mailto:[email protected] |
| 151 | +[corewcf_repo]: https://github.com/CoreWCF/samples/ |
| 152 | +[wcf_docs]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/extensions/wcf/Microsoft.WCF.Azure.StorageQueues |
0 commit comments