Merge pull request #17 from dotnet/terrajobst/release-notes

Initial import of our release notes

release-notes/Microsoft.Bcl.Async.md

@@ -0,0 +1,292 @@
+# Microsoft.Bcl.Async
+
+## Information
+
+* [NuGet Package](https://nuget.org/packages/Microsoft.Bcl.Async)
+* [Announcement](http://blogs.msdn.com/b/bclteam/archive/2013/04/17/microsoft-bcl-async-is-now-stable.aspx)
+* [Report an issue](https://www.nuget.org/packages/Microsoft.Bcl.Async/ContactOwners)
+
+## 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](http://blogs.msdn.com/b/dotnet/archive/2013/11/13/pcl-and-net-nuget-libraries-are-now-enabled-for-xamarin.aspx)
+* 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](http://blogs.msdn.com/b/bclteam/archive/2013/04/17/microsoft-bcl-async-is-now-stable.aspx)
+
+### 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](http://connect.microsoft.com/VisualStudio/feedback/details/767008/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](https://connect.microsoft.com/VisualStudio/feedback/details/768521/system-typeloadexception-when-using-async-for-wp7-5-version-1-0-11-beta)
+
+### 1.0.11-beta
+
+* Initial release
+* [Announcement](http://blogs.msdn.com/b/bclteam/archive/2012/10/22/using-async-await-without-net-framework-4-5.aspx)
+
+## 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
+<?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:
+
+```xml
+<?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:
+
+```xml
+<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:
+
+```xml
+<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

release-notes/Microsoft.Bcl.Build.md

@@ -0,0 +1,51 @@
+# Microsoft.Bcl.Build
+
+## Information
+
+* [NuGet Package](https://nuget.org/packages/Microsoft.Bcl.Build)
+* [Announcement](http://blogs.msdn.com/b/dotnet/archive/2013/08/12/improved-package-restore.aspx)
+* [Report an issue](https://www.nuget.org/packages/Microsoft.Bcl.Build/ContactOwners)
+
+## Version History
+
+### 1.0.21
+
+* Updated to stable, no other changes.
+
+### 1.0.20-Beta
+
+* Remove PowerShell scripts and use Nuget's built-in targets file support.
+
+### 1.0.17-Beta
+
+* Updated to use in-box binding redirect functionality for supported projects
+ types from VS2013 onwards
+
+### 1.0.14
+
+* Added Windows Phone 8.1 support
+
+### 1.0.13
+
+* [Announcement](http://blogs.msdn.com/b/dotnet/archive/2013/11/13/pcl-and-net-nuget-libraries-are-now-enabled-for-xamarin.aspx)
+* Updated license to remove Windows-only restriction
+
+### 1.0.10
+
+* [Announcement](http://blogs.msdn.com/b/dotnet/archive/2013/08/12/improved-package-restore.aspx)
+* Marked as stable
+
+### 1.0.9-beta
+
+* Improved experience around package restore. The import to the targets is now
+ optional which allows VS to load the project, even if the package is missing.
+ A build that restored packages will now fail with an error message asking to
+ build again.
+
+### 1.0.8
+
+* Marked as stable
+
+### 1.0.7
+
+* Fixed issues with building on a .NET 4 machine

release-notes/Microsoft.Bcl.Compression.md

@@ -0,0 +1,3 @@
+# Microsoft.Bcl.Compression
+
+This package has been renamed to [System.IO.Compression](System.IO.Compression.md).

release-notes/Microsoft.Bcl.Metadata.md

@@ -0,0 +1,3 @@
+# Microsoft.Bcl.Metadata
+
+This package has been renamed to [System.Reflection.Metadata](System.Reflection.Metadata.md).

release-notes/Microsoft.Bcl.Simd.md

@@ -0,0 +1,3 @@
+# Microsoft.Bcl.Simd
+
+This package has been renamed to [System.Numerics.Vectors](System.Numerics.Vectors.md).