azure / azure-sdk-for-net

This repository is for active development of the Azure SDK for .NET. For consumers of the SDK we recommend visiting our public developer docs at https://learn.microsoft.com/dotnet/azure/ or our versioned developer docs at https://azure.github.io/azure-sdk-for-net.

Azure SDK for .NET

This repository is for active development of the Azure SDK for .NET. For consumers of the SDK we recommend visiting our public developer docs or our versioned developer docs.

Getting started

To get started with a library, see the README.md file located in the library's project folder. You can find these library folders grouped by service in the /sdk directory.

For tutorials, samples, quick starts, and other documentation, go to Azure for .NET Developers.

Packages available

Each service might have a number of libraries available from each of the following categories:

• Client - New Releases
• Client - Previous Versions
• Management - New Releases
• Management - Previous Versions

Client: New Releases

New wave of packages that we are announcing as GA and several that are currently releasing in preview. These libraries follow the Azure SDK Design Guidelines for .NET and share a number of core features such as HTTP retries, logging, transport protocols, authentication protocols, etc., so that once you learn how to use these features in one client library, you will know how to use them in other client libraries. You can learn about these shared features at Azure.Core.

These new client libraries can be identified by the naming used for their folder, package, and namespace. Each will start with Azure, followed by the service category, and then the name of the service. For example Azure.Storage.Blobs.

For a complete list of available packages, please see the latest available packages page.

NOTE: If you need to ensure your code is ready for production we strongly recommend using one of the stable, non-preview libraries.

Client: Previous Versions

Last stable versions of packages that are production-ready. These libraries provide similar functionalities to the preview packages, as they allow you to use and consume existing resources and interact with them, for example: upload a storage blob. Stable library directories typically contain 'Microsoft.Azure' in their names, e.g. 'Microsoft.Azure.KeyVault'. They might not implement the guidelines or have the same feature set as the November releases. They do however offer wider coverage of services.

Management: New Releases

A new set of management libraries that follow the Azure SDK Design Guidelines for .NET and based on Azure.Core libraries are now in Public Preview. These new libraries provide a number of core capabilities that are shared amongst all Azure SDKs, including the intuitive Azure Identity library, an HTTP Pipeline with custom policies, error-handling, distributed tracing, and much more. You can find the list of new packages on this page.

To get started with these new libraries, please see the quickstart guide here. These new libraries can be identified by namespaces that start with Azure.ResourceManager, e.g. Azure.ResourceManager.Network

NOTE: If you need to ensure your code is ready for production use one of the stable, non-preview libraries.

Management: Previous Versions

For a complete list of management libraries which enable you to provision and manage Azure resources, please check here. They might not have the same feature set as the new releases but they do offer wider coverage of services. Previous versions of management libraries can be identified by namespaces that start with Microsoft.Azure.Management, e.g. Microsoft.Azure.Management.Network

Documentation and code samples for these libraries can be found here.

Need help?

• For reference documentation visit the Azure SDK for .NET API Reference.
• For tutorials, samples, quick starts, and other documentation, go to Azure for .NET Developers.
• File an issue via Github Issues.
• Check previous questions or ask new ones on StackOverflow using azure and .net tags.

Community

• Chat with other community members

Reporting security issues and security bugs

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) [email protected]. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the Security TechCenter.

We want your thoughts!

Feature Requests

What features are important to you? You can let us know by looking at our open feature requests and sharing your thoughts by giving the issue a thumbs up or thumbs down. (Note the list is sorted by number of thumbs up in descending order.)

Design Discussions

We would love to incorporate the community's input into our library design process. Here's a list of design discussions that we're currently having. Participate in the discussions by leaving your comments in the issue!

Contributing

For details on contributing to this repository, see the contributing guide.

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 https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

azure-sdk-for-net's Issues

add XTaskAsync method overloads

something like AddMessageTaskAsync

SB code review notes for winmd servicelayer lib

From Jayu:

1. Noun/Verb alignment: Rename UnlockXxx -> AbandonXxx
2. The methods are duplicated between Topic/Subscription and queues. This can lead to method explosion as we enhance REST protocol to support more operations. It would be reduce the overall surface area if you abstracted the path. E.g. introduce a new type EntityPath with two constructors EntityPath(string queueName), EntityPath(string topicName, string subscriptionName) and then used EntityPath as the parameter for both queue/topic.
   a. Fyi: We solving this problem by creating one type for each first class entity (TopicClient, SubscriptionClient, QueueClient).
3. Proxy type name (ServiceBusService): Can we call this ServiceBusClient? “Client” suffix is also being used by Windows Azure Queue APIs (which are wrappers over ours)? It’s your call though.
4. Re this (in the notes below), you can change the setter of MessageCount property to internal to avoid confusion

from Alex:

• We must replace user/password parameters with issuer name/issuer password;
• We need to be consistent on naming – names must be similar to those used in .Net client library;
• Factory class (ServiceBusService) should go away. The service bus should be a class, not an interface. That class may require several constructors in the future to implement different flavors of SB (REST-based, etc);
• *Info classes should be renamed into *Description ones.
• It was advised to use single Description class instead of having input Settings and output Description classes (single QueueDescription vs. QueueSettings + QueueDescription), which would allow using an existing object as a template for creating new ones. I still prefer the original approach because output parameters may have more members than input one (specifying MessageCount on creating a queue doesn’t make sense) and because our users won’t have to deal with nullable parameters on descriptions they obtained from the server. However, I will add a constructor for each Settings class to instantiate it from the corresponding Description class to allow using existing objects as templates.

[winmd servicebus] exception thrown doesn't have much details

var sb = ServiceBusService.Create("");
try
{
sb.DeleteQueueAsync("test").AsTask();
}
catch (Exception exc)
{
}

Actual: exception details has : - "A task was canceled." System.Exception
{System.Threading.Tasks.TaskCanceledException}

Expected: Detail regarding the underlying exception

Figure out what to do with multi-line error messages

We need to find out whether splitting an error message into multiple lines is acceptable for WinRT exceptions. If not - we should review our HTTP error messages, which include the short message, the status code and the reason string, each on a new line.

[winmd servicebus] custom message properties as date throws InvalidCastException

Winmd code: var messagesend = BrokeredMessageSettings.CreateFromText("test/xml","this is my message");
messagesend.Properties["orderid"] = new DateTime();
sb.SendMessageAsync("test", messagesend).AsTask().Wait();

invalid cast is thrown by
https://github.com/WindowsAzure/azure-sdk-for-net/blob/dev/microsoft-azure-servicelayer/Microsoft.WindowsAzure.ServiceLayer/ServiceBus/CustomPropertiesDictionary.cs
datetime cast needs to be added to the encode and decode function

this was fixed for datetimeoffset, datetime is also a popular structure used which should be fixed.

[winmd servicebus] custom numeric properties are getting converted to double

Customerpropertiesdictionary converts the numeric value of custom properties to double causing a mismatch between the data sent and received to the queue.

BrokeredMessageSettings messagesent = BrokeredMessageSettings.CreateFromText("message");
message.Properties["id"] = 0;

BrokeredMessageInfo message = await Service.PeekQueueMessageAsync(queueName, new TimeSpan(1000));
Assert.AreEqual(messagesent.Properties["id"], 0,"Message custom property 'id' value received doesn't match what was sent earlier");

Assert fails with actual value of messagesent.Properties["id"] to be 0.0

Add a logger HTTP handler

Would be nice to give our customers a built-in HTTP handler for logging requests and responses, which would help them debugging HTTP-related issues.

[winmd servicebus] Error message for invalidcast exception

winmd code: https://github.com/WindowsAzure/azure-sdk-for-net/blob/dev/microsoft-azure-servicelayer/Microsoft.WindowsAzure.ServiceLayer/ServiceBus/CustomPropertiesDictionary.cs
Creating this issue to track - error message needs to be implemented in EncodeValue method

[winmd servicebus] custom message properties as date throws InvalidCastException

Winmd code: var messagesend = BrokeredMessageSettings.CreateFromText("test/xml","this is my message");
messagesend.Properties["orderid"] = new DateTime();
sb.SendMessageAsync("test", messagesend).AsTask().Wait();

invalid cast is thrown by
https://github.com/WindowsAzure/azure-sdk-for-net/blob/dev/microsoft-azure-servicelayer/Microsoft.WindowsAzure.ServiceLayer/ServiceBus/CustomPropertiesDictionary.cs
datetime cast needs to be added to the encode and decode function

AzureApplicationSettings.GetServiceSetting is not used; should be removed

AzureApplicationSettings.GetServiceSetting is an unused private method. Dead code should be removed.

Get rid of IServiceBusService and service bus factory

SB team requests that the service bus service should be implemented as a regular class with parameters passing in the constructor. The SB interface and the factory class must go away.

[winmd servicebus] QueueInfo class in the winmd library to have properties similar to QueueDescription

Code: https://github.com/WindowsAzure/azure-sdk-for-net/blob/dev/microsoft-azure-servicelayer/Microsoft.WindowsAzure.ServiceLayer/ServiceBus/QueueInfo.cs

I would like to suggest

• uri property to be removed and
• name property to be renamed as "path"

Advantages:

• To have queueinfo class similar to the convenience layer http://msdn.microsoft.com/en-us/library/windowsazure/microsoft.servicebus.messaging.queuedescription.aspx
• This would also make consuming the path (which is a string) easier in a javascript app

Rename Unlock* methods to Abandon*

Per SB team request, we need to rename all SB's Unlock* methods to Abandon* for consistency with WCF.

[servicebus winmd] BrokeredMessageSettings and BrokeredMessageDescription

Most of the times I am confused between using BrokeredMessageSettings and BrokeredMessageDescription. VS intellisense also doesn't provide much help (intellisense doesn't show the description added to the winrt method when coding on the JS editor)
Not sure what it could be renamed to, to have a clearer separation or may be the design should be revisited.

Methods for dealing with messages should take MessageInfo classes

Currently these methods take lockToken and sequenceId which come from the message anyway. This will make the code easier to read.

brokeredmessage constructor with contenttype

winmd : https://github.com/aliakb/azure-sdk-for-net/blob/Clean/microsoft-azure-servicelayer/Microsoft.WindowsAzure.ServiceLayer/ServiceBus/BrokeredMessageSettings.cs

Specifying Content type for creating the message seems to be a overkill, should not be required to be explicitly passed to the constructor . An example for .net sdk is here http://www.windowsazure.com/en-us/develop/net/how-to-guides/service-bus-queues/ for javasdk as well content-type is text/xml by default.

Port unit tests to MSTEST

MSTEST can work with Metro libraries, which enables more testing scenarios than we have right now.

Create a single message source class for reading messages.

We have two sets of methods for reading messages: one for queues, and another for subscriptions; both sets have the same signatures. Having a single class would reduce the code without introducing extra complexity.

I suggest the following:

1. Add a MessageReader class with methods for reading messages
2. Add IServiceBusService.CreateReader(string queueName) - for queues.
3. Add IServiceBusService.CreateReader(string topicName, string subscriptionName) - for subscriptions.

[servicebus winmd] build.

winmd lib should be verified on the latest build.

[winmd servicebus] brokermessage*.text to be changed to brokermessage*.body

winmd code in dev branch: https://github.com/aliakb/azure-sdk-for-net/blob/17b26ab72d31af987b557c40127f83842e726305/microsoft-azure-servicelayer/Microsoft.WindowsAzure.ServiceLayer/ServiceBus/BrokeredMessageInfo.cs

Minor change - to be consistent with the .net api Text property should be renamed to "body".

new test issue

If I can close it

[Microsoft.WindowsAzure.Configuration] catch roleenviromentexception

Write the following code in your webrole referening the configuration assembly:
AzureConfigurationManager.AppSettings.GetSetting("storagestring1")
where storagestring1 is defined in web.config. It doesn't exist in azure configuration setting.

Actual:
It throws RoleEnvironment exception

Expected:
To return the web.config setting.
Code required to changed: to consume the roleenvironment exception when trying to read the setting from azure configuration

[servicebus winmd] warning for optional param.

I am getting a warning for BrokeredMessageSettings.CreateFromText(System.String, System.String)' has parameter 'contentType' which is optional.

[servicebus winmd] httphandler usability for javascript developers

httphandler extension is not very usable for javascript developers. Should make it easy to be used from javascript by providing delegates based httphandler.

Add localizable error messages

We do not have error messages yet. This has to be done after porting unit tests to MSTEST (reading from resources using WinRT classes doesn't work in plain class libraries, so all tests that generate exceptions with our error messages will start failing if we don't convert to mstest).

[servicebus winmd] CreateFromByteArray attribute error

Remove XUnit unit tests from the solution

We already have mstest tests, which use RC bits, and because we're targeting RC, XUnit tests should be removed.

[winmd servicebus] Brokeredmessagesettings constructor overload to create message from stream/byte

code:https://github.com/WindowsAzure/azure-sdk-for-net/blob/dev/microsoft-azure-servicelayer/Microsoft.WindowsAzure.ServiceLayer/ServiceBus/BrokeredMessageSettings.cs

winmd library to have stream and byte overload to create a message, something like java sdk https://github.com/WindowsAzure/azure-sdk-for-java/blob/master/microsoft-azure-api/src/main/java/com/microsoft/windowsazure/services/serviceBus/models/BrokeredMessage.java or .net sdk http://msdn.microsoft.com/en-us/library/windowsazure/microsoft.servicebus.messaging.brokeredmessage.aspx

Readme is inaccurate

The Readme file is contradictory. The opening sentence suggests the SDK supports "messaging through Service Bus, distributed caching through cache.":

This SDK allows you to build Windows Azure applications that take advantage of Azure scalable cloud computing resources: table and blob storage, messaging through Service Bus, distributed caching through cache.

[winmd servicebus] queue and topic data types to match .net library

All int properties in Queueinfo, queuesettings,topicinfo and topicsetting should be long should match .net to avoid possible loss of data.

[winmd servicebus] content type should not be explicitly required while creating a brokeredmessage

winmd code: https://github.com/WindowsAzure/azure-sdk-for-net/blob/dev/microsoft-azure-servicelayer/Microsoft.WindowsAzure.ServiceLayer/ServiceBus/BrokeredMessageSettings.cs

• As per the msdn document http://msdn.microsoft.com/en-us/library/windowsazure/hh780742.aspx content type is preserved when message is returned but is not required as such.
• Also for java and .net sdk while creating a brokeredmessage explicitly specifying content-type is not required

current: public static BrokeredMessageSettings CreateFromText(string contentType, string messageText)

proposed: public static BrokeredMessageSettings CreateFromText(string messageText)

code changes required:

• removing exception handling for null content type
• in _content = new StringContent(messageText, Encoding.UTF8); (which would make it default to text/plain)
• set content type implementation

thx.

[storage] unit tests/mocks to storage client libraries

Create interface/virtual methods so we can easily write unit tests.

#6

Configuration: Fix all warnings found when running Code Analysis with "Microsoft All Rules"

Best practice is to review all warnings, and fix all unless there is a significant reason not to. Here are the current warnings from the dev branch:

1. CA2210 : Microsoft.Design : Sign 'Microsoft.WindowsAzure.Configuration.dll' with a strong name key.
2. CA1014 : Microsoft.Design : Mark 'Microsoft.WindowsAzure.Configuration.dll' with CLSCompliant(true) because it exposes externally visible types.
3. CA1824 : Microsoft.Performance : Because assembly 'Microsoft.WindowsAzure.Configuration.dll' contains a ResX-based resource file, mark it with the NeutralResourcesLanguage attribute, specifying the language of the resources within the assembly. This could improve lookup performance the first time a resource is retrieved.
4. CA1811 : Microsoft.Performance : 'AzureApplicationSettings.GetServiceSetting(string)' appears to have no upstream public or protected callers.

Rename *Info classes into *Description

Per SB team request.

add sln and .gitignore file

I'm trying to work on a pull request for #6 (unit tests and mocks), but there seems to be no .gitignore file and .sln file (only .csproj).

Could you guys add the .gitignore and the solution file for microsoft-azure-api folder. Currently only microsoft-azure-servicelayer in dev branch seems to contain the gitignore and .sln file.

[servicebus winmd] rename BrokermessageSettings constructor to CreateFromHttpcontent

BrokeredMessageSettings currently has factory methods for CreateFromText, CreateFromByteArray, CreateFromStream. BrokermessageSettings constructor accepting httpcontent makes it little confusing on how to instantiate the type and makes other factory methods less discoverable.
Would like to propose to rename the constructor to CreateFromHttpContent.

Thanks.

hierarchical namespace similar to a file system and CloudBlobContainer class inconsistency

When I create a hierarchical namespace similar to a file system and try to retrieve it with the CloudBlobContainer class, IListBlobItem.Uri comes back incorrectly. Here is a sample:

In my container, I have a file named album/foo.jpg. I try to list the blobs under my container with the following code:

  // Retrieve a reference to a container 
  CloudBlobContainer blobContainer =
      _myBlobStorageService.GetCloudBlobContainer();

  List<string> blobs = new List<string>();

  // Loop over blobs within the container and output the URI to each of them
  foreach (var blobItem in blobContainer.ListBlobs())
      blobs.Add(blobItem.Uri.ToString());

It returns the Uri property of all the blobs correctly if they don't have "/". In this case Uri comes back as http://mystorage.table.core.windows.net/mycontainer/album/ but it should be http://mystorage.table.core.windows.net/mycontainer/album/foo.jpg.

NOTE:

Probably has nothing to do with this but _myBlobStorageService code is as bellow:

    public CloudBlobContainer GetCloudBlobContainer() {

        // Retrieve storage account from connection-string
        CloudStorageAccount storageAccount = CloudStorageAccount.Parse(
                RoleEnvironment.GetConfigurationSettingValue("StorageString")
            );

        // Create the blob client 
        CloudBlobClient blobClient = storageAccount.CreateCloudBlobClient();

        // Retrieve a reference to a container 
        CloudBlobContainer blobContainer = blobClient.GetContainerReference("dummy");

        return blobContainer;
    }

Cloud configuration assembly is not strong named

All of the other azure assemblies have a strong name, but the cloud configuration does not. This includes the assembly you can get via NuGet, as well as the one installed with the SDK.

Get rid of all TODO statements

We need to review and to remove all TODO statements before we ship.

[winmd servicebus] getMessageAsync on an empty message queue returns cancelled error

winmd code: https://github.com/aliakb/azure-sdk-for-net/blob/Clean/microsoft-azure-servicelayer/Microsoft.WindowsAzure.ServiceLayer/ServiceBus/IServiceBusService.cs

For an empty Servicebus queue getMessageAsync call returns cancelled error.

Expected: To return success with null result that the application can process on. An empty queue should not be treated as an exception.

for example in JS, I want to check if message is received then process on it. Empty queue is also a valid state and should not throw an exception.

sb.getMessageAsync("myq", 20).then(
function (result) {
if(result!=null)
logOutput("Received message" + result.text);

    },
    function (result) {
        logOutput("error receiving message" + result);
    }
    );

Make SB URIs configurable

Currently SB URI's are hardcoded to https://.servicebus.windows.net and https://-sb.accesscontrol.windows.net/wrapv0.9. We need to make this configurable.

Better error messages for table storage

Any chance we could have better error messages from the table storage client? E.g. I was using table storage in local dev environment. Previously I had created the table, populated it with entity etc. so the actual xml schema in the table was correct. However first there was configuration issue where I was using port 10000 instead of port 10002. After fixing that the second issue was that the address did not have the account name (i.e. it was http://127.0.0.1:10002 instead of http://127.0.0.1:10002/devstoreaccount1). In both cases the error message was something like "Requested input was out of range" when using the CreateQuery() method to query the storage.

So to sum it up it seems that in any configuration error you are faced with error message that doesn't help you at all.

#23

BrokeredMessageInfo is missing the default constructor

Code: https://github.com/aliakb/azure-sdk-for-net/blob/17b26ab72d31af987b557c40127f83842e726305/microsoft-azure-servicelayer/Microsoft.WindowsAzure.ServiceLayer/ServiceBus/BrokeredMessageInfo.cs
BrokeredMessageInfo is missing the default constructor to workaround the JS serialization issue. This causes the brokeredMessageinfo object to be not returned correctly to the JS client from the winmd library.

Add integration with the configuration file

Issuer name, password, and the namespace could be read from the config file without specifying them in the constructor. Should be done after switching to mstest.

[servicebus winmd] javascript failed async operation doesn't give much information regarding the failure

serviceBusClient.createQueueAsync(queueName).then(
function(result){
logHandler("Queue" + result.name + " created successfully");
},
function(result){
logHandler("Queue couldn't be created . Message: " + result.message );
}
);

If queue already exists, the failed handle result contains cancelled and doesn't have much information regarding the error as such.
Expected: http error message and error code in the result.

CloudConfigurationManager throws exception if not run in azure dev emulator

I'm using VS2012 RC with Azure SDK v1.7. I created new cloud service using ASP.NET MVC4 (empty application) and put following code into Application_Start (the setting is configured in web.config and service configuration correctly):

var value = CloudConfigurationManager.GetSetting("setting");

If I set my web application as startup project in VS the line throws exception "Not running in a hosted service or the Development Fabric" This happens when AzureApplicationSettings calls Trace.WriteLine.

So the problem is that by default the Azure DiagnosticMonitorTraceListener is registered in the web.config and if you are not running inside dev emulator all Trace messages fail.

I'm reporting this because I thought the whole point of CloudConfigurationManager was to make it easier to run web application either inside or outside of the azure dev emulator. Simple fix is to replace the azure trace listener from web.config with something that works without azure dev emulator. So maybe this can be fixed with documentation updated on MSDN (couldn't find anything related to this issue) or is there a better way to handle this?

[servicebus winmd] warning when doing analysis CA1001 Microsoft.WindowsAzure.ServiceLayer.Http.HttpChannel

warning when doing analysis:
CA1001 Types that own disposable fields should be disposable Implement IDisposable on 'HttpChannel' because it creates members of the following IDisposable types: 'HttpClient'. If 'HttpChannel' has previously shipped, adding new members that implement IDisposable to this type is considered a breaking change to existing consumers. Microsoft.WindowsAzure.ServiceLayer HttpChannel.cs 30

Should the type be disposable?

[winmd servicebus] deleteQueueMessageAsync(message)

winmd code: https://github.com/aliakb/azure-sdk-for-net/blob/Clean/microsoft-azure-servicelayer/Microsoft.WindowsAzure.ServiceLayer/ServiceBus/IServiceBusService.cs

It would be easier to call deleteQueueMessage with the message object sb.deleteQueueMessageAsync(message) rather than
deleteQueueMessageAsync(queuePath, message.correlationId, message.lockToken)

Configuration: Consider adding automated coding style checks

It is useful to have an automated coding-style checker to verify that the coding style within a project is consistent, especially a project being maintained by multiple people.

One tool that can be used is Style Cop (http://stylecop.codeplex.com/)

StyleCop analyzes C# source code to enforce a set of style and consistency rules. It can be run from inside of Visual Studio or integrated into an MSBuild project. StyleCop has also been integrated into many third-party development tools.

Any rules deemed to be overly strict can be disabled by adding a configuration file in the project.

For example, here are some suggestions from Style Cop:

• Warning SA1101: The call to IsMissingSettingException must begin with the 'this.' prefix to indicate that the item is a member of the class: AzureApplicationSettings.cs:172
• Warning SA1405: A call to Debug.Assert must provide a message in the second parameter describing the reason for the assert: AzureApplicationSettings.cs: 114

[ServiceBus WinMD] Nuget package for winmd library

Creating this to track it. If possible should be for win8 OS only.