dotnet-core/release-notes/Microsoft.Bcl.Async.md

Microsoft.Bcl.Async

Information

• NuGet Package
• Announcement
• Report an issue

Version History

1.0.168

• Updated package dependencies and clarified supported platforms.

1.0.166

• Added Windows Phone 8.1 support

1.0.166-beta

• Fixed issue with missing Microsoft.Threading.Tasks.Extensions.Desktop.dll when targeting .Net 4.5

1.0.165

• Announcement
• Updated license to remove Windows-only restriction

1.0.16

• Switched to RTM
• Added support for build-time warnings around missing package references
• Release announcement can be found here

1.0.14-rc

• Changed: Moved to latest Microsoft.Bcl package (1.0.16-rc).

1.0.13-beta

• Fixed: ConfigureAwait(false) still continue on captured context when using Async Targeting Pack
• Fixed: Silverlight 4 projects now get Microsoft.Threading.Tasks.Extensions.Silverlight
• Added: Package now references System.Net.dll automatically for .NET 4.0 projects so that networking extension methods work out of the box.
• Changed: Moved types in Microsoft.Threading.Tasks from System.* to Microsoft.* namespace to prevent name conflicts
• Changed: Package now includes Microsoft.Threading.Tasks for .NET 4.5, Windows Store apps and Windows Phone 8 projects to enable the consumption of custom awaiters.
• Changed: Microsoft.Bcl dependency is now not included for .NET 4.5, Windows Store apps and Windows Phone 8 projects because it is not needed.

1.0.12-beta

• Fixed: TypeLoadException when using Async for WP7.5 version 1.0.11-beta

1.0.11-beta

• Initial release
• Announcement

Troubleshooting

Issue 1

Symptom

You may get the following error when trying to add a reference to the Microsoft.Bcl.Async package:

Attempting to resolve dependency 'Microsoft.Bcl (= 1.0.0-beta)'.
Successfully installed 'Microsoft.Bcl 1.0.10-beta'.
Successfully installed 'Microsoft.Bcl.Async 1.0.10-beta'.
Successfully uninstalled 'Microsoft.Bcl 1.0.10-beta'.
Install failed. Rolling back...
Could not install package 'Microsoft.Bcl 1.0.10-beta'.
You are trying to install this package into a project that targets '.NETPortable,Version=v4.0,Profile=Profile4',
but the package does not contain any assembly references or content files that are compatible with that framework.
For more information, contact the package author.

Resolution

This happens when trying to reference a NuGet package from a Portable Class Library that supports platforms not supported by the package. For Microsoft.Bcl.Async, this usually occurs when trying to reference it from a Portable Class Library which supports Windows Phone 7.0. To resolve this, change the Portable Class Library to target Windows Phone 7.5 and higher.

Issue 2

Symptom

After installing the Microsoft.Bcl or Microsoft.Bcl.Async packages to certain projects, you may get build errors or warnings similar to:

Cannot await 'System.Threading.Tasks.Task'.

-or-

The primary reference "Microsoft.Threading.Tasks" could not be resolved because it has an indirect dependency on the framework assembly "System.Runtime, Version=1.5.10.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" which could not be resolved in the currently targeted framework. ".NETFramework,Version=v4.0". To resolve this problem, either remove the reference "Microsoft.Threading.Tasks" or retarget your application to a framework version which contains "System.Runtime, Version=1.5.10.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a".

Resolution

Microsoft.Bcl.Async package is not supported in Visual Basic Web Application projects. As a workaround, place all async/await usage in a class library and consume that from the Web Application project.

Otherwise, for other project types add an App.Config to the project with the following contents, replacing [version] with the version (for example, 2.5.10.0) of System.Runtime and System.Threading.Tasks that you are referencing:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
        <assemblyIdentity name="System.Runtime" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
        <bindingRedirect oldVersion="0.0.0.0-[version]" newVersion="[version]" />
      </dependentAssembly>
      <dependentAssembly>
        <assemblyIdentity name="System.Threading.Tasks" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
        <bindingRedirect oldVersion="0.0.0.0-[version]" newVersion="[version]" />
      </dependentAssembly>
    </assemblyBinding>
  </runtime>
</configuration>

Issue 3

Symptom

After retargeting a .NET Framework, Portable or Windows Phone project from an older target framework version to a newer target framework version, you may get build warnings similar to:

The predefined type 'System.Runtime.CompilerServices.AsyncStateMachineAttribute' is defined in multiple assemblies in the global alias; using definition from 'c:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.5\mscorlib.dll'

Resolution

Higher versions of these platforms already include the types from the Microsoft.Bcl and Microsoft.Bcl.Async packages. Uninstall them from the project, and remove the <assemblyBinding> elements from any app.config that refers to System.Runtime and System.Threading.Tasks.

Issue 4

Symptom

You get syntax errors when you attempt to use the Microsoft.Bcl.Async package in a web site project, similar to:

The type or namespace name 'async' could not be found (are you missing a using directive or an assembly reference?)

-or-

The type or namespace name 'await' could not be found (are you missing a using directive or an assembly reference?)

Solution

Microsoft.Bcl.Async package is not supported in Web Sites. As a workaround, place all async/await usage in a class library and consume that from the Web Site.

Issue 5

Symptoms

When using the NuGet package restore feature the code doesn’t build with the following error message:

The imported project "<ProjectPath>\packages\Microsoft.Bcl.Build.<version>\tools\Microsoft.Bcl.Build.targets" was not found. Confirm that the path in the <Import> declaration is correct, and that the file exists on disk.

Solution

Package Restore is a feature of NuGet that will download any missing packages as part of the build, which means the packages folder doesn’t need to be checked into source control. However, this doesn’t work for NuGet packages that inject MSBuild targets files. You will need to make sure all *.targets files under the packages folder are being checked into version control.

For Microsoft.Bcl.Build you need check in the following file:

Microsoft.Bcl.Build.<version>\tools\Microsoft.Bcl.Build.targets

Issue 6

Symptoms

When adding the NuGet package to a project that is consumed by another project with a different target framework you might see warnings similar to the following:

The primary reference "Microsoft.Threading.Tasks, Version=1.0.12.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL" could not be resolved because it has an indirect dependency on the framework assembly "System.Runtime, Version=2.5.19.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" which could not be resolved in the currently targeted framework. ".NETFramework,Version=v4.5". To resolve this problem, either remove the reference "Microsoft.Threading.Tasks, Version=1.0.12.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL" or retarget your application to a framework version which contains "System.Runtime, Version=2.5.19.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a".
The primary reference "Microsoft.Threading.Tasks.Extensions, Version=1.0.12.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL" could not be resolved because it has an indirect dependency on the framework assembly "System.Runtime, Version=2.5.19.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" which could not be resolved in the currently targeted framework. ".NETFramework,Version=v4.5". To resolve this problem, either remove the reference "Microsoft.Threading.Tasks.Extensions, Version=1.0.12.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, processorArchitecture=MSIL" or retarget your application to a framework version which contains "System.Runtime, Version=2.5.19.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a".

Solution

The problem is that NuGet added incorrect binding redirects for platform assemblies. To remove them, please open the app.config for the project that caused the warnings and remove the highlighted entries:

<?xmlversion="1.0"encoding="utf-8"?>
<configuration>
  <runtime>
    <assemblyBindingxmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
        <assemblyIdentityname="System.Runtime"publicKeyToken="b03f5f7f11d50a3a"culture="neutral" />
        <bindingRedirectoldVersion="0.0.0.0-2.5.19.0"newVersion="2.5.19.0" />
      </dependentAssembly>
      <dependentAssembly>
        <assemblyIdentityname="System.Threading.Tasks"publicKeyToken="b03f5f7f11d50a3a"culture="neutral" />
        <bindingRedirectoldVersion="0.0.0.0-2.5.19.0"newVersion="2.5.19.0" />
      </dependentAssembly>
    </assemblyBinding>
  </runtime>
</configuration>

Issue 7

Symptoms

When building a Windows Runtime Component (.winmd) you might get one of the following error messages:

Could not resolve reference 'Assembly(Name=System.Threading.Tasks, Version=1.5.11.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a)'.
Could not resolve reference 'Assembly(Name=System.Threading.Tasks, Version=2.5.11.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a)'.

Please note the version number that it mentions.

Solution

This is an issue with the tool that creates a Windows Runtime Component (WINMDEXP). Until we address this issue you will need to work around this by adding a reference to the assembly directly by following these steps:

1. Unload the Windows Runtime Component project by right click the project node in Solution Explorer and selecting Unload Project.
2. Edit the project by right clicking it again in Solution Explorer and selecting Edit <Project Name>.
3. Jump to end of the file (after the imports). Depending on the version number of the error message paste in one of the following snippets before the closing </Project> element.

Version 1.5.x:

<Target Name="InjectAsyncDependencies" BeforeTargets="ExportWindowsMDFile">
  <ItemGroup>
    <ReferencePath Include="..\packages\Microsoft.Bcl.1.0.19\lib\sl4\System.Threading.Tasks.dll" />
  </ItemGroup>
</Target>

Version 2.5.x:

<Target Name="InjectAsyncDependencies" BeforeTargets="ExportWindowsMDFile">
  <ItemGroup>
    <ReferencePath Include="..\packages\Microsoft.Bcl.1.0.19\lib\net40\System.Threading.Tasks.dll" />
  </ItemGroup>
</Target>

Issue 8

Symptom

When targeting .NET 4 you get the following error:

Could not load file or assembly 'System.Core, Version=2.0.5.0

Resolution

Using Microsoft.Bcl.Async on .NET 4 requires http://support.microsoft.com/kb/2468871 to be installed.

Issue 9

Symptom

ClickOnce applications targeting .NET Framework 4.0 that reference the Microsoft.Bcl or Microsoft.Bcl.Async packages may experience a TypeLoadException or other errors after being installed.

Resolution

This occurs because ClickOnce fails to deploy certain required assemblies. As a workaround, do the following:

1. Right-click on the project and choose Add Existing Item
2. Browse to the folde net40 within the Microsoft.Bcl package folder
3. In the File name text box enter *.*
4. Holding CTRL, select System.Runtime.dll and System.Threading.Tasks.dll
5. Click the down-arrow next to the Add button and choose Add as Link
6. In Solution Explorer, holding CTRL select System.Runtime.dll and System.Threading.Taks.dll
7. Right-click the selection, choose Properties and change Copy to Output Directory to Copy always
8. Republish