Summary

See you there!

Today, we’ve published another beta of HttpClient that will address those concerns.

• A brand new Microsoft.Bcl.Compression (Beta). A portable compression library that supports stream based compression (gzip, deflate) as well as ZIP archives.
• An updated Microsoft.Net.Http 2.2 (Beta). Last week we shipped an RTM version. Today, we released a new beta that provides automatic decompression by taking a dependency on the Microsoft.Bcl.Compression package.

Before we go into the details, let’s first take a look at why compression is particularly interesting for HttpClient.

We believe we’ve baked Microsoft.Bcl.Async enough to flip the switch and mark it as stable. This might not sound like a big deal but it is the NuGet equivalent of shipping an RTM.

C-3PO: "Sir, it's quite possible this package is not entirely stable."

Han Solo: "Not entirely stable? Well, I'm glad you're here to tell us

these things. Chewie, take the professor in the back and

show him how to upgrade the NuGet package!"

--- Star Wars as Immo remembers it

What’s the big deal with being stable?

Being stable means the owner of that package states that API and functionality are unlikely to change and therefore suitable for use in production. This also enables 3rd parties to publish stable NuGet packages that depend on our package because NuGet prevents stable packages from depending on pre-release packages.

What about Microsoft.CompilerServices.AsyncTargetingPack?

Before we shipped Microsoft.Bcl.Async we shipped another NuGet package which was provided by the language team to gather feedback on the async and await keywords (“Async Targeting Pack”)

https://www.nuget.org/packages/Microsoft.CompilerServices.AsyncTargetingPack

Our stable release of Microsoft.Bcl.Async officially supersedes the Async Targeting Pack. We haven’t removed it, but we unlisted it on NuGet so that new developers aren’t accidentally using the old version. We’ve also added a readme.txt which is automatically displayed by VS when existing consumers upgrade their package references.

Fixed Issues

The majority of customer issues we’ve seen was due to two issues:

1. Outdated version of NuGet. In order to use the Async package from a portable class library, you need to run the NuGet 2.1 or higher. To address this in the future, we have worked with the NuGet team and NuGet 2.3 will add this ability. For now, you will need to know to install an updated version of NuGet (see instructions in section “How to Upgrade” below).
2. Missing reference to the async package from all referencing projects. In order to make the async functionality work across all platforms, we make use of a CLR feature called assembly unification. For that to work properly, all projects must have a reference to the Async NuGet package. Since this can be easy to forget, we’ve added a warning mechanism to our package that tells you what to do. I’ll discuss this in more detail below.

After upgrading, you will see the following build warning:

After fixing this, you might see the following warnings:

In both cases, the project that causes the warning is missing a NuGet package reference. Adding these references will fix the warnings.

Tip: If your solution contains many projects, you may want bulk-add the async packages to several projects at once. You can do this by right clicking your solution and selecting Manage NuGet Packages for Solution. Select the NuGet package and click Manage. A dialog appears that enables you to select the projects you want to update.

Add references for Microsoft.Bcl, Microsoft.Bcl.Async, and Microsoft.Bcl.Build to all projects that show the warnings mentioned previously.

Branding

We’ve added some branding to make our packages easier to recognize. Our dotnetframework user now displays the .NET gravatar.

and so does our async NuGet package:

How to Upgrade

Important: Since our package contains portable class libraries, you need to use NuGet 2.1 or higher. You can check whether you have the latest version by going to Tools | Extensions and Updates. When the Extensions and Updates dialog opens, select Updates | Visual Studio Gallery and look for an entry titled NuGet Package Manager.

In order to upgrade to the RTM version, right click your project and select Manage NuGet Packages. In the resulting dialog, select the Updates section on the left hand side. In the center, the Async NuGet package should show up. Simply click the Update button.

Summary

Microsoft.Bcl.Async is now stable which means you can use it in production. Of course, software is never truly done, so we still want to hear from you if things don’t work for you. You can contact us via comments under this blog posts or via our NuGet contact page. Also, make sure to check out the known issues list.

Two months ago, we shipped a NuGet package with support for immutable collections. We’ve also talked about it on Channel 9. Since then we received feedback through various channels and we’re happy to announce we shipped an update on NuGet that addresses your feedback.

Feedback Channels

First of all: how are we tracking your feedback? We track social media, such as Twitter, Reddit and our official Facebook page. We also track StackOverflow, Connect, the comments on this blog, and last but not least emails send through the NuGet’s Contact Owners mechanism. Yes, we really want your feedback!

The most direct way to contact us is via NuGet or comments on this blog.

Your Feedback

Package Installation Issues

Some customers reported issues with installing the NuGet package. In all cases, the root cause was an outdated version of the NuGet package manager. Immutable collections use portable class libraries and they are only supported by NuGet 2.1 or higher.

In order to update the immutable collections package, please install the latest version of NuGet. You can check whether you have the latest version by going to Tools | Extensions and Updates. When the Extensions and Updates dialog opens, select Updates | Visual Studio Gallery and look for an entry titled NuGet Package Manager.

Unfortunately, there is currently no way for a package to specify a minimum required version of NuGet. To address this in the future, we have worked with the NuGet team and NuGet 2.3 will add this ability. For now, you will need to know to install an updated version of NuGet.

Construction

We explicitly decided not to provide constructors for immutable collections. The reason for this is that immutable collections typically start with an empty instance. Since all empty instances would be the same, this would result in a lot of wasted objects. Instead, we decided to use a singleton as the empty instance.

Unfortunately this decision resulted in quite verbose code:

    var list = ImmutableList<int>.Empty.Add(1, 2, 3);

Furthermore, this approach doesn’t support type inference as the generic arguments must be specified. Besides having to type more this also means that anonymous types aren’t supported (remember: only Jon Skeet knows their names).

We’ve fixed this by using a solution similar to what we use for Tuple. We’ve created non-generic types that serve as a factory for creating immutable collections. Also, we’ve removed the Empty property and replaced it by a factory method (it still returns a singleton but this makes the design more consistent).

This allows you to write code like this:

    var anEmptyList = ImmutableList.Create<int>();
    var oneTwoThree = ImmutableList.Create<int>(1, 2, 3);

which can be shortened as it allows for type inference:

    var oneTwoThree = ImmutableList.Create(1, 2, 3);

which in turn enables anonymous types:

    var andrew = new { FirstName = “Andrew”, LastName = “Arnott” };
    var matt = new { FirstName = “Matt”, LastName = “Cohn” };
    var immo = new { FirstName = “Immo”, LastName = “Landwerth” };
    var list = ImmutableList.Create(andrew, matt, immo);

Interoperating with existing collections

As you are probably aware, the existing mutable collection interfaces in the BCL support the notion of read-only-ness. In our original design we made the decision that immutable collections shouldn’t implement the standard mutable interfaces. The idea was that you had to explicitly call a method on them to convert them to the standard collection interfaces, such as ImmutableList<T>.ToReadOnlyCollection().

However, we received the feedback that people had a hard time figuring out how to pass an immutable list to en existing method that took, for example, IList<T>.

Also, we came to the conclusion that this design was inconsistent with our existing collection types. For example, List<T> implements IReadOnlyList<T> which means you can view a mutable list as if it were a collection that doesn’t support modifications. In the same way it makes sense to view an immutable list as list that doesn’t support modifications and thus implements IList<T> but returns true for IsReadOnly.

In the end, we decided to remove the method to explicitly convert the collections to read-only collections and simply implemented the existing collection interfaces in a read-only fashion.

The following table summarizes the relationship between the immutable collections and the existing interfaces:

Equality semantics

Today, all collections in the BCL have reference equality semantics and don’t overload the equals operator (== in C#, = in Visual Basic).

In the preview release we chose to override the Object.Equals method to provide value equality, but did not overload the equals operator in line with the other collections. After reviewing this design more carefully we concluded that we don’t want to override the Equals method.

Value equality on collections can be fairly expensive to compute and comparing for equality on nested collections, such as ImmutableDictionary<string, ImmutableList<string>> is more difficult to define. Finally, providing this functionality leads to more issues when different comparers are involved, as customers have pointed out.

In many cases, we believe that reference equality is sufficient. In other cases, the app should provide its own equality policy. As a result, we have removed the overrides of the Equals methods.

Naming

Several people pointed out that the design of our immutable collections is known as persistent data structures. Thus, it was suggested to rename our data types accordingly, for example, PersistentList<T>. We’ve given it a lot of thought and decided to keep the name “immutable”.

We want to keep the concept count low. The BCL already provides mutable collections, read-only collections, and now immutable collections. Traditionally, we don’t introduce new concepts unless deemed necessary.

From a high-level perspective, the important characteristic you get from immutable collections is that they guarantee that their contents will never ever change. The fact that these collections also enable you to efficiently create new versions of an existing instance without naively copying all their contents is of secondary importance. We feel the “Immutable” name focuses on the most important aspect.

In addition, we’ll consider adding an ImmutableArray<T>. This would be a struct that simply wraps an underlying array without ever exposing it. Naming wise, it makes sense to name it ImmutableArray<T>. It wouldn’t have persistent character though, as we wouldn’t offer any methods to create new versions with different values. If you wanted this behavior, you should use ImmutableList<T> instead. The goal of ImmutableArray<T> is simply to provide a low overhead wrapper around an array to enforce it can never change.

To me this indicates that “immutable” is a more useful term for the BCL as it is precise and yet general purpose enough to not require adding more terminology down the road when the design evolves.

The Small Things Count

We’ve also improved several smaller things, for example, we’ve added a ImmutableList<T>.RemoveRange(IEnumerable<T>) method. The existing remove range that took an index and a count was not super useful in mainstream scenarios.

Hold on – aren’t those breaking changes?

Yes! The NuGet package is marked as a “pre-release”. Pre-release packages are non-stable previews of a product. That is, we don’t guarantee the final shape of the API and/or functionality and want to be able to change them based on customer feedback. In the end, the sole purpose of pre-release packages is gathering feedback.

That is a very different experience from a beta of the .NET Framework. Typically, a beta is the first public release of the framework but it is already very close to RTM. In fact, for .NET 4.5 we shipped the beta with a go-live license that supports use in production. On one hand, this is great for early adopters, but on the other hand it means we couldn’t react to major design change requests because the design was already set.

Pre-releases on NuGet allow us to give you the bits really early and react to your feedback in a meaningful way. For example, if changing the API shape is the right thing, we’ll do it.

However, once we mark packages as stable (AKA “RTM”) we hold the same bar for breaking changes as in-box .NET Framework components.

Summary

Please try out the new drop of immutable collections. If you’re already using them, you can simply upgrade your existing packages via the NuGet package manager. Otherwise, just search for Microsoft.Bcl.Immutable and make sure you include pre-releases.

Looking forward to receiving more feedback!

Today we are announcing our Beta release of the portable version of HttpClient, the modern networking API. The HttpClient library is a set of APIs for .NET which provide a flexible and extensible way to access all things exposed through HTTP.

This release of HttpClient adds support for the following platforms:

• .NET framework 4.0
• Windows Phone 7.5 and higher
• Portable class libraries

What does HttpClient do?

HttpClient is a part of .NET Framework 4.5 and Windows Store apps that provides developers an extremely easy way to connect with services across the internet including REST-based services. In fact, the methods exposed by HttpClient are the same verbs the HTTP protocol uses to communicate like GET/PUT/POST/DELETE.

In order to get some content from a web server say www.contoso.com we can write the following simple lines of code

HttpClient httpClient = new HttpClient();
string responseBodyAsText = await httpClient.GetStringAsync(“www.contoso.com”);

…and get a response back from a web service. Obviously this is the simplest example, and the HttpClient library has many more feature and functions.

Why a portable HttpClient?

Before releasing this package, the HttpClient class was not available on all platforms. This complicated the experience for developers trying to share code across Microsoft platforms. For instance, a developer who wanted to target both the Windows Phone and Windows Store app platforms would need to write networking logic using the HttpWebRequest and HttpWebResponse classes for networking, since it was the networking abstraction available in portable. However HttpClient is a much simpler programming interface to code against, in addition to being very close to HTTP semantics, which makes it more intuitive. In addition HttpClient exposes the new Task based asynchronous methods, which makes writing responsive and performant UI applications across all platforms a lot simpler.

In order to bridge this gap we have created a portable class library for HttpClient that will allow developers to consume HttpClient on Windows Phone 7.5 and higher, Windows Store apps, and .NET Framework 4.0 and higher. In addition it also enables other portable library developers who require networking support to use HttpClient while targeting all or a subset of the supported platforms.

What do I need?

In order to use this release of HttpClient you need to ensure that you have two things.

• Visual Studio 2010 (for .NET 4.0 Windows Phone 7.1) or Visual Studio 2012 (required for .NET 4.5, Windows Store and Windows Phone 8).
• The NuGet package manager version 2.1 or higher.

To use the HttpClient package, right click on your solution, go to the Manage Nuget Packages dialog, search for Id Microsoft.Net.Http, and make sure “Include Prerelease” is turned on.

Accept the license terms and agreements and NuGet will install the right packages to your folder.

Writing a Cross platform App

The full surface area for HttpClient as shipped in .NET Framework 4.5 is documented here. This package includes support for that surface area, and introduces a few new methods that are not currently in the documentation above.These new APIs are used to help determine which networking capabilities are supported on the platform on which you’re running, since not all platforms support all capabilities. The new APIs added are:

public static bool SupportsPreAuthenticate(this HttpClientHandler handler);
public static bool SupportsProtocolVersion(this HttpClientHandler handler);
public static bool SupportsTransferEncodingChunked(this HttpClientHandler handler);

In order to write a portable piece of code which would work across all the supported platforms, code that would have previously been

HttpClientHandler handler = new HttpClientHandler();
httpClient = new HttpClient(handler);
HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, resourceAddress);
request.Content = streamContent;
request.Headers.TransferEncodingChunked = true;
HttpResponseMessage response = await httpClient.SendAsync(request);

Will now change to

HttpClientHandler handler = new HttpClientHandler();
httpClient = new HttpClient(handler);
HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, resourceAddress);
request.Content = streamContent;
if (handler.SupportsTransferEncodingChunked())
{
 request.Headers.TransferEncodingChunked = true;
}
HttpResponseMessage response = await httpClient.SendAsync(request);

Using HttpClient on .NET Framework 4.0 or Windows Phone 7.5

If you are writing a cross platform app targeting .Net 4.0 or the windows phone and write the code that you had written above you will get a compile error.

“Cannot await System.Threading.Task<HttpRequestMessage>”

This is because .Net 4.0 and Windows Phone 7.5 did not support the async/await keywords.In order to fix this add a reference to the Microsoft.Bcl.Async nuget package, which adds the support for Async and Await in down level platforms.To read more about this release go here.

This was one of the higher rated user voice requests, so thanks for taking the time to engage with us. Please note this package is marked as prerelease software – that is, there are some rough edges to be expected. We’ve published the known issues here. As usual, we’d like to know if you run into any issues when using it. Simply use the comment section under this blog post.

Happy “Get”ting!