1.0.0 Release Notes and Known issues

Squashed commit after reviews and updates.
This commit is contained in:
leecow 2016-06-25 17:59:47 -07:00
parent 31e0632def
commit 0f839769fb
4 changed files with 3129 additions and 1 deletions

File diff suppressed because it is too large Load diff

View file

@ -1,2 +1,107 @@
#Release Notes
TBD
## .NET Core 1.0.0 released 6/27/2016
Details on this release can be read about on
[the .NET Blog](https://blogs.msdn.microsoft.com/dotnet/2016/06/27/announcing-net-core-1-0) and if you haven't already discovered the updated [.NET Portal](http://go.microsoft.com/fwlink/?LinkID=798306), make that your next destination for getting started with .NET Core.
There are a few issues to be aware of, which are described in the [.NET Core 1.0.0 Known Issues](known-issues-1.0.0.md) document.
### RTM Platform Support
We've added a number of distros to our support list. Below is the complete set for 1.0.0.
* Red Hat Enterprise Linux 7.2
* CentOS 7.1+
* Debian 8.2+
* Fedora 23
* Linux Mint 17.1
* OpenSUSE 13.2
* Oracle Linux 7.1
* Ubuntu 14.04 & 16.04
* Mac OS X 10.11
* Windows 7+ / Server 2012 R2+
* Windows Nano Server TP5
A little style note for the rest of this document - any references to 'Unix' encompasses the Linux distros detailed above and OS X / macOS.
### Dependencies
No changes from RC2.
| Library | Function | Mode |Debian/Ubuntu | CentOS/RHEL | OS X |
| ------------------- | ---------------------------------------------------------------- | ------------- | ------------- | ------------- | --------------------- |
| libc, librt | I/O, process management, time, etc. | Runtime | glibc | glibc | Part of OS |
| libunwind | call chain determination for exception handling and stack traces | Runtime | libunwind8 | libunwind | Part of OS |
| gettext | resource strings | Development | gettext | gettext | n/a |
| libicu | globalization | Runtime | libicu52 | libicu | Part of OS |
| libuuid | guid generation | Runtime | libuuid1 | libuuid | Part of OS |
| libcurl | HTTP | Runtime | libcurl3 | libcurl | Part of OS |
| libssl & libcrypto | cryptography | Runtime | libssl1.0.0 | openssl-libs | Openssl from homebrew |
| libz | deflate and gzip | Runtime | zlib1g |zlib | Part of OS |
| liblttng | runtime tracing | Diagnostic | liblttng-ust0 | liblttng-ust0 | n/a |
### Introduction of .NET Core API Documentation
* Conceptual: http://docs.microsoft.com/dotnet
* API: http://dotnet.github.io/api/
### Production-quality .NET Core Runtime and Framework libraries
* Background GC on Unix
* Support for basic cross-process synchronization in the Mutex class on Unix
* Reliability improvements
* R2R Performance improvements for Generics
* Portable PDB support in Exception.ToString() and System.Diagnostics.StackTrace
* New SOS commands "!CLRStack -r"
* Limited managed profiling support on Windows
### BCL
Below is a summary of API changes made since RC2. A complete and detailed listing of API changes can be seen in the [RC2 to Final API Diff](RC2-Final_API_diff.md).
New .NET Core APIs
* System.ComponentModel.TypeConverter - TypeDescriptor support
* System.Data.Common - DBEnumerator
* System.Diagnostics.Tracing - EventCounter
* System.IO.FileSystem.Watcher - FileSystemWatcher.WaitForChanged
* System.Net.Http - new properties on HttpClientHandler
* System.Net.Sockets - add back Tcp|UdpClient.Client property
* System.Reflection.Metadata - MetadataReaderProvider
* Many types have been removed from the 1.3 surface area and moved to 1.4 which remains in pre-release. If you depend on these types update to the 1.4.0 pre-release package.
* System.Resources.ReaderWriter - types are now in separate assemblies System.Resources.Reader and System.Resources.Writer
* System.Runtime.CompilerServices.Unsafe - New static helper methods for dealing with unsafe pointers
* System.Security.Cryptography
* ECDsa supports creating keys for arbitrary named and explicit curves (Windows 10, OS X, Linux)
* ECDsa supports importing and exporting keys via the platform-independent ECParameters type
* EnvelopedCms is now supported via the System.Security.Cryptography.Pkcs package
* System.Security.SecureString
* System.Text.RegularExpressions - precompiled regex
### CLI
<<<<<<< HEAD
* Offline support: now you don't have to be connected to the internet to write applications that target only the .NET Core runtime and libraries. This means the core libraries are cached locally after running various dotnet commands the first time. Restoring packages which are not part of the Shared Framework do generally require and do need an internet connection to gather the packages from NuGet.
=======
* Offline support: now you don't have to be connected to the internet to write applications that target only the .NET Core runtime and libraries. This means the core libraries are cached locally after running various dotnet commands the first time. Restoring packages which are not part of the Shared Framework do generally require and internet connection to gather the packages from NuGet.
>>>>>>> master
* New Templates: web, lib and xunittest
### WCF
Details on work the WCF team has done since RC2 can be found in the [WCF Release Notes](https://github.com/dotnet/wcf/releases/tag/v1.0.0).
## Closed issues
The lists of issues closed for this and past releases can be found here:
* [CLR issues](https://github.com/dotnet/coreclr/issues?q=is%3Aissue+no%3Amilestone+is%3Aclosed)
* [BCL issues](https://github.com/dotnet/corefx/issues?q=is%3Aissue+no%3Amilestone+is%3Aclosed)
## Commits for 1.0.0
The lists of commits for this release can be viewed here:
* [CLR commits](https://github.com/dotnet/coreclr/commits/release/1.0.0)
* [BCL commits](https://github.com/dotnet/corefx/commits/release/1.0.0)

View file

@ -0,0 +1,13 @@
# .NET Core 1.0.0 and .NET Core 1.0.0 SDK - Preview 2 Contributor List
A big *Thank You* to all who contributed!
## CoreCLR
## CoreFX
## .NET Core Tools
## WCF
## Core Docs

View file

@ -0,0 +1,275 @@
# 1.0.0 Known Issues
This document lists known issues for *.NET Core 1.0.0* and *.NET Core SDK 1.0.0 Preview 2* which may be encountered during usage.
## .NET Core native prerequisites
See the [.NET Core prequisites document](https://github.com/dotnet/core/blob/master/Documentation/prereqs.md) to understand any installation or setup requirements for you OS which are not handled by the .NET Core 1.0.0 installers.
## NegotiateStream
```NegotiateStream``` relies on the gssapi implementation available on the platform.
* On Linux flavors, the default gssapi implementation provided is [MIT's krb5 library](http://web.mit.edu/kerberos/) which is available on all the linux platforms
* On OS X, the default implementation is heimdal-based GSS.framework
On both Linux and OS X, NegotiateStream uses SPNEGO and relies on the underlying implementation for supporting Kerberos or NTLM as the underlying security protocol.
* On OS X, Gss.framework supports SPNEGO mechanism with Kerberos and NTLM as the security protocols.
* On Linux, mit krb5 library supports SPENGO mechanism and Kerberos as the out of the box security protocol. The implementation can be made to support NTLM too by installing [GSS-NTLMSSP plugin](https://fedorahosted.org/gss-ntlmssp/) or another plugin with similar functionality. The fallback to NTLM is thus dependent on runtime availability of such a plugin.
On RHEL and CENTOS, the plugin GSS-NTLMSSP is available from the package managers. The same is also available on Ubuntu 16. It can be installed on the other flavors of linux.
There's no compile time dependency on this plugin.
## NegotiateStream.Write interop issues on Linux/OS X
There are some combinations of Kerberos/NTLM, SignOnly/EncryptAndSign etc. that cause the ```gss_wrap``` call on Unix client to fail against a Windows server using ```NegotiateStream```. Here are the failing combinations of credentials and protection level passed in ```AuthenticateAsClientAsync```
On Linux:
- Kerberos creds with Sign: Server complains that signature is valid but contents not encrypted
- NTLM creds with EncrypAndSign: Server rejects signature
- NTLM creds with Sign: Server rejects signature
On OS X:
- Kerberos creds with Sign: Server complains that signature is valid but contents not encrypted
- NTLM creds with EncryptAndSign: Server complains about message format
- NTLM creds with Sign: gss_wrap fails on client side
The fix has been pushed to MIT Kerberos source <https://github.com/krb5/krb5/pull/436> which will make the fix available for all unix platforms, starting krb5-1.15. Red Hat reports the fix will be backported to RHEL 7.
<https://github.com/dotnet/corefx/issues/6767>
### Socket.Connect and ConnectAsync instance methods support only one IPAddress
The Socket class provides instance and extension Connect and ConnectAsync methods, each with multiple overloads. Some of these overloads take an IPAddress, some take an array of IPAddresses, some take a string host name, and others take an EndPoint. On Linux and on OS X, only some of these methods are functional in this release, due to the capabilities of the underlying platform. Specifically, any of these overloads that may need to work with multiple addresses will throw a PlatformNotSupportedException; that includes not only the overloads that take an array of IPAddress instances, but also the overloads that take a string host, as well as the overloads that take an EndPoint if a DnsEndPoint is supplied (when the DNS lookup is performed, the host name may end up mapping to multiple addresses).
As a workaround, a new Socket instance may be created for each address to be tried, e.g.
```C#
public static class SocketUtilities
{
public static async Task<Socket> ConnectAsync(string host, int port)
{
IPAddress[] addresses = await Dns.GetHostAddressesAsync(host).ConfigureAwait(false);
return await ConnectAsync(addresses, port).ConfigureAwait(false);
}
public static async Task<Socket> ConnectAsync(IPAddress[] addresses, int port)
{
ExceptionDispatchInfo lastException = null;
foreach (IPAddress address in addresses)
{
var socket = new Socket(address.AddressFamily, SocketType.Stream, ProtocolType.Tcp);
try
{
await socket.ConnectAsync(address, port).ConfigureAwait(false);
return socket;
}
catch (Exception exc)
{
socket.Dispose();
lastException = ExceptionDispatchInfo.Capture(exc);
}
}
lastException?.Throw();
throw new ArgumentOutOfRangeException(nameof(addresses));
}
}
```
<https://github.com/dotnet/corefx/issues/9235>
## HttpClient handler header parsing strictness on Linux and OS X
HttpClient response header parsing logic on Linux and on OS X fairly strictly follows the RFC. Certain "invalid" headers, such as with spaces between the header name and the colon, might be accepted by other browsers or even by HttpClient on Windows, but could be rejected when run on Linux or on OS X.
<https://github.com/dotnet/corefx/issues/9240>
## NTFS and FAT not supported on unix
Adding certs to an X509Store fails when the current user's home directory is an NTFS volume on unix.
The user's home directory (or, the directory referenced by $HOME) must be on a standard filesystem (such as ext4) supporting chmod.
## OS X has an external dependency on OpenSSL
.NET Core uses OpenSSL as the provider for cryptographic primitives and the SSL/TLS protocol. While there is a pre-installed version of OpenSSL on OS X 10.11, that version is no longer supported, and is not used by .NET Core. In order to satisfy the OpenSSL dependency, `libcrypto.1.0.0.dylib` and `libssl.1.0.0.dylib` must be loadable via rpath probing. One such way of satisfying this requirement is via Homebrew:
```bash
brew install openssl
# without this next step Homebrew will not register a symlink in a standard rpath location,
# so .NET Core will still be unable to find the installed libraries.
brew link --force openssl
```
When this dependency is not met, an application making direct or indirect use of cryptography will get an exception similar to
`System.DllNotFoundException: Unable to load DLL 'System.Security.Cryptography.Native': The specified module could not be found.`.
### A note on producing standalone OS X applications
Since .NET Core loads libcrypto and libssl via rpath probing these libraries can be copied into the working directory of an application before being copied to another machine. But when trying to use this configuration users should be advised that the Homebrew version of libssl has an absolute path dependency on libcrypto. The local copy of libssl may need to be modified to search for libcrypto via rpath with the install_name_tool utility.
<https://github.com/dotnet/corefx/issues/9171>
## Debian users may experience unexpected failure when using SSL/TLS
When new Root Certificate Authorities are being created it is not uncommon for the new CA public key to be "cross certified" by an existing Certificate Authority to boostrap the trust relationship into existing environments. For example, the "Baltimore CyberTrust Root" CA was cross-certified by the existing "GTE CyberTrust Global Root" CA. This process is usually considered to make clients more accepting.
Metadata from the server can cause OpenSSL 1.0.1 to consider the cross-certified certificate chain without considering the direct-root chain. Combined with Debian's removal of some older trusted Root Certificate Authorities in the 20141019+deb8u1 version of the ca-certificates package, these certificate chains will be incomplete (and therefore untrusted).
Microsoft has no specific guidance to offer users affected by this configuration state. This is currently tracked as [bug 812488 in the Debian bug system](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=812488).
<https://github.com/dotnet/corefx/issues/9244>
## HttpClient.GetAsync
HttpClient.GetAsync throws an exception, if server response has more than one "WWW-Authenticate: Basic" header with different realm. The following sample illustrates the error.
```csharp
var handler = new HttpClientHandler();
handler.UseDefaultCredentials = false;
handler.Credentials = System.Net.CredentialCache.DefaultCredentials;
handler.AllowAutoRedirect = true;
using (var client = new HttpClient(handler))
{
client.BaseAddress = new Uri("type you server URI here");
HttpResponseMessage response = await client.GetAsync("api/values");
}
```
<https://github.com/dotnet/corefx/issues/9124>
## uCRT dependency on Windows
With 1.0 of .NET Core, all applications that target .NET Core and run on Windows have a Universal CRT (UCRT) dependency. This dependency is needed on all non-Windows 10 editions. This especially impacts the self-contained applications, as it means that the machine that they are to be run on needs to have UCRT installed.
If the dependency is not present, applications will fail to run and errors will be thrown.
The UCRT dependency can be installed via Windows Update and as a recommended update it will be installed automatically if the user left the default settings for Windows Update operational.
<https://github.com/dotnet/corefx/issues/9389>
## ULIMIT on OS X
When an app exceeds ULIMIT on OS X and throws an exception, the user will get a bogus error from the CLR instead of a good call stack for the real exception. The workaround is to manually increase ULIMIT.
<https://github.com/dotnet/coreclr/issues/5782>
## Unexpected OutOfMemoryException on unix
App on unix can throw OutOfMemoryException when there is still enough memory available in case the number of memory mappings it has made exceeds the `/proc/sys/vm/max_map_count`.
Set the `/proc/sys/vm/max_map_count` to a larger value for applications that experience that problem or are expected to create a large number of mappings. One source of such mappings is excessive usage of `System.Reflection.Emit.AssemblyBuilder.DefineDynamicAssembly` with the access parameter set to `AssemblyBuilderAccess.Run`.
## Lazily binding an assembly from Resolving event for static load can result in a crash
If an app has a static assembly reference to an assembly that is missing (which is not the normal case since .NET Core app have their dependencies complete) OR attempts to do Assembly.Load against an assembly that is missing AND has wired up to the Resolving event to load the assemblies from custom locations, then the event will not return a valid reference and could result in a crash.
The workaround to address the above problem is one of the following:
Load the assembly using `LoadFromAssemblyName` instead of Assembly.Load, OR
Create a custom `AssemblyLoadContext` and override its Load method to resolve the assembly.
<https://github.com/dotnet/coreclr/issues/5837#issuecomment-226657996>
## global.json needs to be in UTF-8
If global.json file has an UTF-16 BOM, dotnet commands will fail due to not supporting UTF-16 BOM with the error:
```
A JSON parsing exception occurred: * Line 1, Column 2 Syntax error: Malformed token
```
This situation may arise if using tools that by default produce UTF-16 files with the BOM, such as PowerShell's Out-File cmdlet.
**The workaround** is to either remove the BOM or change it to UTF-8 BOM, as these are the currently supported. Visual Studio by default uses UTF-8. If you are using PowerShell, you can specify the encoding for the Out-File cmdlet with the -Encoding argument, `Out-File -Encoding utf8`.
<https://github.com/dotnet/core-setup/issues/185>
<https://github.com/dotnet/cli/issues/2159>
## dotnet restore can fail on Fedora 23 with NSS 3.24 installed with timeouts and SSL connection errors
At this time, the workaround is to downgrade NSS.
```
sudo dnf downgrade nspr nss-util nss-softokn-freebl nss-softokn nss-sysinit nss nss-tools
```
<https://github.com/dotnet/cli/issues/3676>
## Line numbers missing from exception call stack on Windows 7
When an exception goes unhandled, the exception call stack doesn't include the source line numbers. On the other hand, the source line numbers are included when Exception.ToString() or Exception.StackTrace is called on an exception object.
```csharp
// Catch the exception and call Exception.ToString() on it, e.g.
try
{
throw new Exception();
}
catch (Exception ex)
{
Console.WriteLine(ex.ToString());
}
```
<https://github.com/dotnet/coreclr/issues/5828>
## Nano Server TP5
When working on TP5 of Nano server, users will encounter the following error if they try to run either portable or self-contained application:
```
Failed to load the dll from [C:\hwapp_s\bin\Debug\netcoreapp1.0\win10-x64\hostpolicy.dll], HRESULT: 0x8007007E
An error occurred while loading required library hostpolicy.dll from [C:\hwapp_s\bin\Debug\netcoreapp1.0\win10-x64]
```
If youre using Nano Server Technical Preview 5 with .NET Core CLI, due to a bug in the product, you will need to copy binaries from `c:\windows\system32\forwarders`. The destination depends on the type of deployment that you are choosing for your application.
For portable applications, the forwarders need to be copied to the shared runtime location. The shared runtime can be found wherever you installed .NET Core 1.0.0 (by default, it is `C:\Program Files\dotnet`) under the following path: `shared\Microsoft.NETCore.App\<version>\`.
For self-contained applications, the forwarders need to be copied over into the application folder, that is, whereever you put the published output.
This process will ensure that that the dotnet host finds the appropriate APIs it needs. If your Nano Server Technical Preview 5 build is updated or serviced, please make sure to repeat this process, in case any of the DLLs have been updated as well.
## Windows 7
**Issue:**
Some libraries that Pinvoke into api-set's and target .NET Framework in our nuget packages might fail to run on Windows 7.
**Workarounds:**
Some of the api-sets are installed by the UCRT update: <https://support.microsoft.com/en-us/kb/2999226>
and <https://support.microsoft.com/en-us/kb/2790113> but these installations may not be a comprehensive fix.
- If you're using project.json you can just reference the Microsoft.NETCore.Windows.ApiSets package from your app and be sure to deploy for runtime win7-x86 or win7-x64, as appropriate.
- If you're using packages.config you'll need to manually download and extract the packages, as appropriate for the bitness of your app:
[runtime.win7-x64.Microsoft.NETCore.Windows.ApiSets](https://dotnet.myget.org/F/dotnet-core/api/v2/package/runtime.win7-x64.Microsoft.NETCore.Windows.ApiSets/1.0.1)
[runtime.win7-x86.Microsoft.NETCore.Windows.ApiSets](https://dotnet.myget.org/F/dotnet-core/api/v2/package/runtime.win7-x86.Microsoft.NETCore.Windows.ApiSets/1.0.1)
## UCRT Dependency on Windows 7 and System.IO.Compression
With 1.0 of .NET Core, all applications that target .NET Core and run on Windows have a [Universal CRT (UCRT)](https://blogs.msdn.microsoft.com/vcblog/2015/03/03/introducing-the-universal-crt/) dependency. This dependency is needed on all non-Windows 10 editions. This especially impacts the [self-contained](https://dotnet.github.io/docs/core-concepts/app-types.html) applications, as it means that the machine that they are to be run on needs to have UCRT installed.
If the dependency is not present, applications will fail to run and errors will be thrown. The error will be:
> The program can't start because api-ms-win-crt-runtime-1-1-0.dll is missing from your computer. Try reinstalling the program to fix this problem.
The UCRT dependency can be installed via Windows Update (name: "Update for Universal C Runtime in Windows" as according to <https://support.microsoft.com/en-us/kb/2999226>) and as a recommended update it will be installed automatically if the user left the default settings for Windows Update operational. It can also be downloaded from [Microsoft Download Center](https://www.microsoft.com/en-us/download/details.aspx?id=48234).
<https://github.com/dotnet/corefx/issues/9083>
## Bash on Ubuntu on Windows
[Bash on Windows (WSL)](https://msdn.microsoft.com/en-us/commandline/wsl/about) is not yet supported by .NET Core. Attempting to run applications in the environment can experience interittent crashes.
<https://github.com/Microsoft/BashOnWindows/issues/520>