Merge master

22 files changed, 707 insertions, 148 deletions

diff --git a/src/csharp/Grpc.Core/Channel.cs b/src/csharp/Grpc.Core/Channel.cs
index e9930b6fbc..7ce929dfa3 100644
--- a/src/csharp/Grpc.Core/Channel.cs
+++ b/src/csharp/Grpc.Core/Channel.cs
@@ -72,9 +72,9 @@ namespace Grpc.Core
             this.environment = GrpcEnvironment.AddRef();
 
             this.completionQueue = this.environment.PickCompletionQueue();
-            using (var nativeCredentials = credentials.ToNativeCredentials())
             using (var nativeChannelArgs = ChannelOptions.CreateChannelArgs(this.options.Values))
             {
+                var nativeCredentials = credentials.GetNativeCredentials();
                 if (nativeCredentials != null)
                 {
                     this.handle = ChannelSafeHandle.CreateSecure(nativeCredentials, target, nativeChannelArgs);
@@ -136,7 +136,7 @@ namespace Grpc.Core
         /// </summary>
         public async Task WaitForStateChangedAsync(ChannelState lastObservedState, DateTime? deadline = null)
         {
-            var result = await WaitForStateChangedInternalAsync(lastObservedState, deadline).ConfigureAwait(false);
+            var result = await TryWaitForStateChangedAsync(lastObservedState, deadline).ConfigureAwait(false);
             if (!result)
             {
                 throw new TaskCanceledException("Reached deadline.");
@@ -147,7 +147,7 @@ namespace Grpc.Core
         /// Returned tasks completes once channel state has become different from
         /// given lastObservedState (<c>true</c> is returned) or if the wait has timed out (<c>false</c> is returned).
         /// </summary>
-        internal Task<bool> WaitForStateChangedInternalAsync(ChannelState lastObservedState, DateTime? deadline = null)
+        public Task<bool> TryWaitForStateChangedAsync(ChannelState lastObservedState, DateTime? deadline = null)
         {
             GrpcPreconditions.CheckArgument(lastObservedState != ChannelState.Shutdown,
                 "Shutdown is a terminal state. No further state changes can occur.");
@@ -297,6 +297,12 @@ namespace Grpc.Core
             activeCallCounter.Decrement();
         }
 
+        // for testing only
+        internal long GetCallReferenceCount()
+        {
+            return activeCallCounter.Count;
+        }
+
         private ChannelState GetConnectivityState(bool tryToConnect)
         {
             try
diff --git a/src/csharp/Grpc.Core/ChannelCredentials.cs b/src/csharp/Grpc.Core/ChannelCredentials.cs
index ba482897d7..3ce32f31b7 100644
--- a/src/csharp/Grpc.Core/ChannelCredentials.cs
+++ b/src/csharp/Grpc.Core/ChannelCredentials.cs
@@ -31,6 +31,19 @@ namespace Grpc.Core
     public abstract class ChannelCredentials
     {
         static readonly ChannelCredentials InsecureInstance = new InsecureCredentialsImpl();
+        readonly Lazy<ChannelCredentialsSafeHandle> cachedNativeCredentials;
+
+        /// <summary>
+        /// Creates a new instance of channel credentials
+        /// </summary>
+        public ChannelCredentials()
+        {
+            // Native credentials object need to be kept alive once initialized for subchannel sharing to work correctly
+            // with secure connections. See https://github.com/grpc/grpc/issues/15207.
+            // We rely on finalizer to clean up the native portion of ChannelCredentialsSafeHandle after the ChannelCredentials
+            // instance becomes unused.
+            this.cachedNativeCredentials = new Lazy<ChannelCredentialsSafeHandle>(() => CreateNativeCredentials());
+        }
 
         /// <summary>
         /// Returns instance of credentials that provides no security and 
@@ -57,11 +70,22 @@ namespace Grpc.Core
         }
 
         /// <summary>
-        /// Creates native object for the credentials. May return null if insecure channel
-        /// should be created.
+        /// Gets native object for the credentials, creating one if it already doesn't exist. May return null if insecure channel
+        /// should be created. Caller must not call <c>Dispose()</c> on the returned native credentials as their lifetime
+        /// is managed by this class (and instances of native credentials are cached).
+        /// </summary>
+        /// <returns>The native credentials.</returns>
+        internal ChannelCredentialsSafeHandle GetNativeCredentials()
+        {
+            return cachedNativeCredentials.Value;
+        }
+
+        /// <summary>
+        /// Creates a new native object for the credentials. May return null if insecure channel
+        /// should be created. For internal use only, use <see cref="GetNativeCredentials"/> instead.
         /// </summary>
         /// <returns>The native credentials.</returns>
-        internal abstract ChannelCredentialsSafeHandle ToNativeCredentials();
+        internal abstract ChannelCredentialsSafeHandle CreateNativeCredentials();
 
         /// <summary>
         /// Returns <c>true</c> if this credential type allows being composed by <c>CompositeCredentials</c>.
@@ -73,7 +97,7 @@ namespace Grpc.Core
 
         private sealed class InsecureCredentialsImpl : ChannelCredentials
         {
-            internal override ChannelCredentialsSafeHandle ToNativeCredentials()
+            internal override ChannelCredentialsSafeHandle CreateNativeCredentials()
             {
                 return null;
             }
@@ -145,7 +169,7 @@ namespace Grpc.Core
             get { return true; }
         }
 
-        internal override ChannelCredentialsSafeHandle ToNativeCredentials()
+        internal override ChannelCredentialsSafeHandle CreateNativeCredentials()
         {
             return ChannelCredentialsSafeHandle.CreateSslCredentials(rootCertificates, keyCertificatePair);
         }
@@ -173,12 +197,11 @@ namespace Grpc.Core
             GrpcPreconditions.CheckArgument(channelCredentials.IsComposable, "Supplied channel credentials do not allow composition.");
         }
 
-        internal override ChannelCredentialsSafeHandle ToNativeCredentials()
+        internal override ChannelCredentialsSafeHandle CreateNativeCredentials()
         {
-            using (var channelCreds = channelCredentials.ToNativeCredentials())
             using (var callCreds = callCredentials.ToNativeCredentials())
             {
-                var nativeComposite = ChannelCredentialsSafeHandle.CreateComposite(channelCreds, callCreds);
+                var nativeComposite = ChannelCredentialsSafeHandle.CreateComposite(channelCredentials.GetNativeCredentials(), callCreds);
                 if (nativeComposite.IsInvalid)
                 {
                     throw new ArgumentException("Error creating native composite credentials. Likely, this is because you are trying to compose incompatible credentials.");
diff --git a/src/csharp/Grpc.Core/ChannelOptions.cs b/src/csharp/Grpc.Core/ChannelOptions.cs
index 6ad5d56cad..880f2bef5f 100644
--- a/src/csharp/Grpc.Core/ChannelOptions.cs
+++ b/src/csharp/Grpc.Core/ChannelOptions.cs
@@ -26,8 +26,10 @@ namespace Grpc.Core
     /// <summary>
     /// Channel option specified when creating a channel.
     /// Corresponds to grpc_channel_args from grpc/grpc.h.
+    /// Commonly used channel option names are defined in <c>ChannelOptions</c>,
+    /// but any of the GRPC_ARG_* channel options names defined in grpc_types.h can be used.
     /// </summary>
-    public sealed class ChannelOption
+    public sealed class ChannelOption : IEquatable<ChannelOption>
     {
         /// <summary>
         /// Type of <c>ChannelOption</c>.
@@ -119,10 +121,60 @@ namespace Grpc.Core
                 return stringValue;
             }
         }
+
+        /// <summary>
+        /// Determines whether the specified object is equal to the current object.
+        /// </summary>
+        public override bool Equals(object obj)
+        {
+            return Equals(obj as ChannelOption);
+        }
+
+        /// <summary>
+        /// Determines whether the specified object is equal to the current object.
+        /// </summary>
+        public bool Equals(ChannelOption other)
+        {
+            return other != null &&
+                   type == other.type &&
+                   name == other.name &&
+                   intValue == other.intValue &&
+                   stringValue == other.stringValue;
+        }
+
+        /// <summary>
+        /// A hash code for the current object.
+        /// </summary>
+        public override int GetHashCode()
+        {
+            var hashCode = 1412678443;
+            hashCode = hashCode * -1521134295 + type.GetHashCode();
+            hashCode = hashCode * -1521134295 + EqualityComparer<string>.Default.GetHashCode(name);
+            hashCode = hashCode * -1521134295 + intValue.GetHashCode();
+            hashCode = hashCode * -1521134295 + EqualityComparer<string>.Default.GetHashCode(stringValue);
+            return hashCode;
+        }
+
+        /// <summary>
+        /// Equality operator.
+        /// </summary>
+        public static bool operator ==(ChannelOption option1, ChannelOption option2)
+        {
+            return EqualityComparer<ChannelOption>.Default.Equals(option1, option2);
+        }
+
+        /// <summary>
+        /// Inequality operator.
+        /// </summary>
+        public static bool operator !=(ChannelOption option1, ChannelOption option2)
+        {
+            return !(option1 == option2);
+        }
     }
 
     /// <summary>
-    /// Defines names of supported channel options.
+    /// Defines names of most commonly used channel options.
+    /// Other supported options names can be found in grpc_types.h (GRPC_ARG_* definitions)
     /// </summary>
     public static class ChannelOptions
     {
diff --git a/src/csharp/Grpc.Core/ClientBase.cs b/src/csharp/Grpc.Core/ClientBase.cs
index fac34071be..05edce7467 100644
--- a/src/csharp/Grpc.Core/ClientBase.cs
+++ b/src/csharp/Grpc.Core/ClientBase.cs
@@ -151,12 +151,12 @@ namespace Grpc.Core
         {
             private class ClientBaseConfigurationInterceptor : Interceptor
             {
-                readonly Func<IMethod, string, CallOptions, Tuple<string, CallOptions>> interceptor;
+                readonly Func<IMethod, string, CallOptions, ClientBaseConfigurationInfo> interceptor;
 
                 /// <summary>
                 /// Creates a new instance of ClientBaseConfigurationInterceptor given the specified header and host interceptor function.
                 /// </summary>
-                public ClientBaseConfigurationInterceptor(Func<IMethod, string, CallOptions, Tuple<string, CallOptions>> interceptor)
+                public ClientBaseConfigurationInterceptor(Func<IMethod, string, CallOptions, ClientBaseConfigurationInfo> interceptor)
                 {
                     this.interceptor = GrpcPreconditions.CheckNotNull(interceptor, nameof(interceptor));
                 }
@@ -166,7 +166,7 @@ namespace Grpc.Core
                     where TResponse : class
                 {
                     var newHostAndCallOptions = interceptor(context.Method, context.Host, context.Options);
-                    return new ClientInterceptorContext<TRequest, TResponse>(context.Method, newHostAndCallOptions.Item1, newHostAndCallOptions.Item2);
+                    return new ClientInterceptorContext<TRequest, TResponse>(context.Method, newHostAndCallOptions.Host, newHostAndCallOptions.CallOptions);
                 }
 
                 public override TResponse BlockingUnaryCall<TRequest, TResponse>(TRequest request, ClientInterceptorContext<TRequest, TResponse> context, BlockingUnaryCallContinuation<TRequest, TResponse> continuation)
@@ -195,6 +195,18 @@ namespace Grpc.Core
                 }
             }
 
+            internal struct ClientBaseConfigurationInfo
+            {
+                internal readonly string Host;
+                internal readonly CallOptions CallOptions;
+
+                internal ClientBaseConfigurationInfo(string host, CallOptions callOptions)
+                {
+                    Host = host;
+                    CallOptions = callOptions;
+                }
+            }
+
             readonly CallInvoker undecoratedCallInvoker;
             readonly string host;
 
@@ -206,7 +218,7 @@ namespace Grpc.Core
 
             internal CallInvoker CreateDecoratedCallInvoker()
             {
-                return undecoratedCallInvoker.Intercept(new ClientBaseConfigurationInterceptor((method, host, options) => Tuple.Create(this.host, options)));
+                return undecoratedCallInvoker.Intercept(new ClientBaseConfigurationInterceptor((method, host, options) => new ClientBaseConfigurationInfo(this.host, options)));
             }
 
             internal ClientBaseConfiguration WithHost(string host)
diff --git a/src/csharp/Grpc.Core/DeserializationContext.cs b/src/csharp/Grpc.Core/DeserializationContext.cs
new file mode 100644
index 0000000000..5b6372ef85
--- /dev/null
+++ b/src/csharp/Grpc.Core/DeserializationContext.cs
@@ -0,0 +1,46 @@
+#region Copyright notice and license
+
+// Copyright 2018 The gRPC Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#endregion
+
+namespace Grpc.Core
+{
+    /// <summary>
+    /// Provides access to the payload being deserialized when deserializing messages.
+    /// </summary>
+    public abstract class DeserializationContext
+    {
+        /// <summary>
+        /// Get the total length of the payload in bytes.
+        /// </summary>
+        public abstract int PayloadLength { get; }
+
+        /// <summary>
+        /// Gets the entire payload as a newly allocated byte array.
+        /// Once the byte array is returned, the byte array becomes owned by the caller and won't be ever accessed or reused by gRPC again.
+        /// NOTE: Obtaining the buffer as a newly allocated byte array is the simplest way of accessing the payload,
+        /// but it can have important consequences in high-performance scenarios.
+        /// In particular, using this method usually requires copying of the entire buffer one extra time.
+        /// Also, allocating a new buffer each time can put excessive pressure on GC, especially if
+        /// the payload is more than 86700 bytes large (which means the newly allocated buffer will be placed in LOH,
+        /// and LOH object can only be garbage collected via a full ("stop the world") GC run).
+        /// NOTE: Deserializers are expected not to call this method more than once per received message
+        /// (as there is no practical reason for doing so) and <c>DeserializationContext</c> implementations are free to assume so.
+        /// </summary>
+        /// <returns>byte array containing the entire payload.</returns>
+        public abstract byte[] PayloadAsNewBuffer();
+    }
+}
diff --git a/src/csharp/Grpc.Core/Internal/AsyncCall.cs b/src/csharp/Grpc.Core/Internal/AsyncCall.cs
index 3c9e090ba4..4cdf0ee6a7 100644
--- a/src/csharp/Grpc.Core/Internal/AsyncCall.cs
+++ b/src/csharp/Grpc.Core/Internal/AsyncCall.cs
@@ -17,6 +17,7 @@
 #endregion
 
 using System;
+using System.Threading;
 using System.Threading.Tasks;
 using Grpc.Core.Logging;
 using Grpc.Core.Profiling;
@@ -34,6 +35,8 @@ namespace Grpc.Core.Internal
         readonly CallInvocationDetails<TRequest, TResponse> details;
         readonly INativeCall injectedNativeCall;  // for testing
 
+        bool registeredWithChannel;
+
         // Dispose of to de-register cancellation token registration
         IDisposable cancellationTokenRegistration;
 
@@ -77,43 +80,59 @@ namespace Grpc.Core.Internal
             using (profiler.NewScope("AsyncCall.UnaryCall"))
             using (CompletionQueueSafeHandle cq = CompletionQueueSafeHandle.CreateSync())
             {
-                byte[] payload = UnsafeSerialize(msg);
+                bool callStartedOk = false;
+                try
+                {
+                    unaryResponseTcs = new TaskCompletionSource<TResponse>();
 
-                unaryResponseTcs = new TaskCompletionSource<TResponse>();
+                    lock (myLock)
+                    {
+                        GrpcPreconditions.CheckState(!started);
+                        started = true;
+                        Initialize(cq);
 
-                lock (myLock)
-                {
-                    GrpcPreconditions.CheckState(!started);
-                    started = true;
-                    Initialize(cq);
+                        halfcloseRequested = true;
+                        readingDone = true;
+                    }
 
-                    halfcloseRequested = true;
-                    readingDone = true;
-                }
+                    byte[] payload = UnsafeSerialize(msg);
 
-                using (var metadataArray = MetadataArraySafeHandle.Create(details.Options.Headers))
-                {
-                    var ctx = details.Channel.Environment.BatchContextPool.Lease();
-                    try
+                    using (var metadataArray = MetadataArraySafeHandle.Create(details.Options.Headers))
                     {
-                        call.StartUnary(ctx, payload, GetWriteFlagsForCall(), metadataArray, details.Options.Flags);
-                        var ev = cq.Pluck(ctx.Handle);
-                        bool success = (ev.success != 0);
+                        var ctx = details.Channel.Environment.BatchContextPool.Lease();
                         try
                         {
-                            using (profiler.NewScope("AsyncCall.UnaryCall.HandleBatch"))
+                            call.StartUnary(ctx, payload, GetWriteFlagsForCall(), metadataArray, details.Options.Flags);
+                            callStartedOk = true;
+
+                            var ev = cq.Pluck(ctx.Handle);
+                            bool success = (ev.success != 0);
+                            try
                             {
-                                HandleUnaryResponse(success, ctx.GetReceivedStatusOnClient(), ctx.GetReceivedMessage(), ctx.GetReceivedInitialMetadata());
+                                using (profiler.NewScope("AsyncCall.UnaryCall.HandleBatch"))
+                                {
+                                    HandleUnaryResponse(success, ctx.GetReceivedStatusOnClient(), ctx.GetReceivedMessage(), ctx.GetReceivedInitialMetadata());
+                                }
+                            }
+                            catch (Exception e)
+                            {
+                                Logger.Error(e, "Exception occurred while invoking completion delegate.");
                             }
                         }
-                        catch (Exception e)
+                        finally
                         {
-                            Logger.Error(e, "Exception occurred while invoking completion delegate.");
+                            ctx.Recycle();
                         }
                     }
-                    finally
+                }
+                finally
+                {
+                    if (!callStartedOk)
                     {
-                        ctx.Recycle();
+                        lock (myLock)
+                        {
+                            OnFailedToStartCallLocked();
+                        }
                     }
                 }
                     
@@ -130,22 +149,35 @@ namespace Grpc.Core.Internal
         {
             lock (myLock)
             {
-                GrpcPreconditions.CheckState(!started);
-                started = true;
+                bool callStartedOk = false;
+                try
+                {
+                    GrpcPreconditions.CheckState(!started);
+                    started = true;
 
-                Initialize(details.Channel.CompletionQueue);
+                    Initialize(details.Channel.CompletionQueue);
 
-                halfcloseRequested = true;
-                readingDone = true;
+                    halfcloseRequested = true;
+                    readingDone = true;
 
-                byte[] payload = UnsafeSerialize(msg);
+                    byte[] payload = UnsafeSerialize(msg);
 
-                unaryResponseTcs = new TaskCompletionSource<TResponse>();
-                using (var metadataArray = MetadataArraySafeHandle.Create(details.Options.Headers))
+                    unaryResponseTcs = new TaskCompletionSource<TResponse>();
+                    using (var metadataArray = MetadataArraySafeHandle.Create(details.Options.Headers))
+                    {
+                        call.StartUnary(UnaryResponseClientCallback, payload, GetWriteFlagsForCall(), metadataArray, details.Options.Flags);
+                        callStartedOk = true;
+                    }
+
+                    return unaryResponseTcs.Task;
+                }
+                finally
                 {
-                    call.StartUnary(UnaryResponseClientCallback, payload, GetWriteFlagsForCall(), metadataArray, details.Options.Flags);
+                    if (!callStartedOk)
+                    {
+                        OnFailedToStartCallLocked();
+                    }
                 }
-                return unaryResponseTcs.Task;
             }
         }
 
@@ -157,20 +189,32 @@ namespace Grpc.Core.Internal
         {
             lock (myLock)
             {
-                GrpcPreconditions.CheckState(!started);
-                started = true;
+                bool callStartedOk = false;
+                try
+                {
+                    GrpcPreconditions.CheckState(!started);
+                    started = true;
 
-                Initialize(details.Channel.CompletionQueue);
+                    Initialize(details.Channel.CompletionQueue);
 
-                readingDone = true;
+                    readingDone = true;
+
+                    unaryResponseTcs = new TaskCompletionSource<TResponse>();
+                    using (var metadataArray = MetadataArraySafeHandle.Create(details.Options.Headers))
+                    {
+                        call.StartClientStreaming(UnaryResponseClientCallback, metadataArray, details.Options.Flags);
+                        callStartedOk = true;
+                    }
 
-                unaryResponseTcs = new TaskCompletionSource<TResponse>();
-                using (var metadataArray = MetadataArraySafeHandle.Create(details.Options.Headers))
+                    return unaryResponseTcs.Task;
+                }
+                finally
                 {
-                    call.StartClientStreaming(UnaryResponseClientCallback, metadataArray, details.Options.Flags);
+                    if (!callStartedOk)
+                    {
+                        OnFailedToStartCallLocked();
+                    }
                 }
-
-                return unaryResponseTcs.Task;
             }
         }
 
@@ -181,21 +225,33 @@ namespace Grpc.Core.Internal
         {
             lock (myLock)
             {
-                GrpcPreconditions.CheckState(!started);
-                started = true;
+                bool callStartedOk = false;
+                try
+                {
+                    GrpcPreconditions.CheckState(!started);
+                    started = true;
 
-                Initialize(details.Channel.CompletionQueue);
+                    Initialize(details.Channel.CompletionQueue);
 
-                halfcloseRequested = true;
+                    halfcloseRequested = true;
 
-                byte[] payload = UnsafeSerialize(msg);
+                    byte[] payload = UnsafeSerialize(msg);
 
-                streamingResponseCallFinishedTcs = new TaskCompletionSource<object>();
-                using (var metadataArray = MetadataArraySafeHandle.Create(details.Options.Headers))
+                    streamingResponseCallFinishedTcs = new TaskCompletionSource<object>();
+                    using (var metadataArray = MetadataArraySafeHandle.Create(details.Options.Headers))
+                    {
+                        call.StartServerStreaming(ReceivedStatusOnClientCallback, payload, GetWriteFlagsForCall(), metadataArray, details.Options.Flags);
+                        callStartedOk = true;
+                    }
+                    call.StartReceiveInitialMetadata(ReceivedResponseHeadersCallback);
+                }
+                finally
                 {
-                    call.StartServerStreaming(ReceivedStatusOnClientCallback, payload, GetWriteFlagsForCall(), metadataArray, details.Options.Flags);
+                    if (!callStartedOk)
+                    {
+                        OnFailedToStartCallLocked();
+                    }
                 }
-                call.StartReceiveInitialMetadata(ReceivedResponseHeadersCallback);
             }
         }
 
@@ -207,17 +263,29 @@ namespace Grpc.Core.Internal
         {
             lock (myLock)
             {
-                GrpcPreconditions.CheckState(!started);
-                started = true;
+                bool callStartedOk = false;
+                try
+                {
+                    GrpcPreconditions.CheckState(!started);
+                    started = true;
 
-                Initialize(details.Channel.CompletionQueue);
+                    Initialize(details.Channel.CompletionQueue);
 
-                streamingResponseCallFinishedTcs = new TaskCompletionSource<object>();
-                using (var metadataArray = MetadataArraySafeHandle.Create(details.Options.Headers))
+                    streamingResponseCallFinishedTcs = new TaskCompletionSource<object>();
+                    using (var metadataArray = MetadataArraySafeHandle.Create(details.Options.Headers))
+                    {
+                        call.StartDuplexStreaming(ReceivedStatusOnClientCallback, metadataArray, details.Options.Flags);
+                        callStartedOk = true;
+                    }
+                    call.StartReceiveInitialMetadata(ReceivedResponseHeadersCallback);
+                }
+                finally
                 {
-                    call.StartDuplexStreaming(ReceivedStatusOnClientCallback, metadataArray, details.Options.Flags);
+                    if (!callStartedOk)
+                    {
+                        OnFailedToStartCallLocked();
+                    }
                 }
-                call.StartReceiveInitialMetadata(ReceivedResponseHeadersCallback);
             }
         }
 
@@ -325,9 +393,22 @@ namespace Grpc.Core.Internal
             }
         }
 
-        protected override void OnAfterReleaseResources()
+        protected override void OnAfterReleaseResourcesLocked()
         {
-            details.Channel.RemoveCallReference(this);
+            if (registeredWithChannel)
+            {
+                details.Channel.RemoveCallReference(this);
+                registeredWithChannel = false;
+            }
+        }
+
+        protected override void OnAfterReleaseResourcesUnlocked()
+        {
+            // If cancellation callback is in progress, this can block
+            // so we need to do this outside of call's lock to prevent
+            // deadlock.
+            // See https://github.com/grpc/grpc/issues/14777
+            // See https://github.com/dotnet/corefx/issues/14903
             cancellationTokenRegistration?.Dispose();
         }
 
@@ -385,10 +466,27 @@ namespace Grpc.Core.Internal
             var call = CreateNativeCall(cq);
 
             details.Channel.AddCallReference(this);
+            registeredWithChannel = true;
             InitializeInternal(call);
+
             RegisterCancellationCallback();
         }
 
+        private void OnFailedToStartCallLocked()
+        {
+            ReleaseResources();
+
+            // We need to execute the hook that disposes the cancellation token
+            // registration, but it cannot be done from under a lock.
+            // To make things simple, we just schedule the unregistering
+            // on a threadpool.
+            // - Once the native call is disposed, the Cancel() calls are ignored anyway
+            // - We don't care about the overhead as OnFailedToStartCallLocked() only happens
+            //   when something goes very bad when initializing a call and that should
+            //   never happen when gRPC is used correctly.
+            ThreadPool.QueueUserWorkItem((state) => OnAfterReleaseResourcesUnlocked());
+        }
+
         private INativeCall CreateNativeCall(CompletionQueueSafeHandle cq)
         {
             if (injectedNativeCall != null)
@@ -448,6 +546,7 @@ namespace Grpc.Core.Internal
             TResponse msg = default(TResponse);
             var deserializeException = TryDeserialize(receivedMessage, out msg);
 
+            bool releasedResources;
             lock (myLock)
             {
                 finished = true;
@@ -464,7 +563,12 @@ namespace Grpc.Core.Internal
                     streamingWriteTcs = null;
                 }
 
-                ReleaseResourcesIfPossible();
+                releasedResources = ReleaseResourcesIfPossible();
+            }
+
+            if (releasedResources)
+            {
+                OnAfterReleaseResourcesUnlocked();
             }
 
             responseHeadersTcs.SetResult(responseHeaders);
@@ -494,6 +598,7 @@ namespace Grpc.Core.Internal
 
             TaskCompletionSource<object> delayedStreamingWriteTcs = null;
 
+            bool releasedResources;
             lock (myLock)
             {
                 finished = true;
@@ -504,7 +609,12 @@ namespace Grpc.Core.Internal
                     streamingWriteTcs = null;
                 }
 
-                ReleaseResourcesIfPossible();
+                releasedResources = ReleaseResourcesIfPossible();
+            }
+
+            if (releasedResources)
+            {
+                OnAfterReleaseResourcesUnlocked();
             }
 
             if (delayedStreamingWriteTcs != null)
diff --git a/src/csharp/Grpc.Core/Internal/AsyncCallBase.cs b/src/csharp/Grpc.Core/Internal/AsyncCallBase.cs
index 3273c26b88..a93dc34620 100644
--- a/src/csharp/Grpc.Core/Internal/AsyncCallBase.cs
+++ b/src/csharp/Grpc.Core/Internal/AsyncCallBase.cs
@@ -189,17 +189,21 @@ namespace Grpc.Core.Internal
         /// </summary>
         protected abstract Exception GetRpcExceptionClientOnly();
 
-        private void ReleaseResources()
+        protected void ReleaseResources()
         {
             if (call != null)
             {
                 call.Dispose();
             }
             disposed = true;
-            OnAfterReleaseResources();
+            OnAfterReleaseResourcesLocked();
         }
 
-        protected virtual void OnAfterReleaseResources()
+        protected virtual void OnAfterReleaseResourcesLocked()
+        {
+        }
+
+        protected virtual void OnAfterReleaseResourcesUnlocked()
         {
         }
 
@@ -235,6 +239,7 @@ namespace Grpc.Core.Internal
         {
             bool delayCompletion = false;
             TaskCompletionSource<object> origTcs = null;
+            bool releasedResources;
             lock (myLock)
             {
                 if (!success && !finished && IsClient) {
@@ -252,7 +257,12 @@ namespace Grpc.Core.Internal
                     streamingWriteTcs = null;    
                 }
 
-                ReleaseResourcesIfPossible();
+                releasedResources = ReleaseResourcesIfPossible();
+            }
+
+            if (releasedResources)
+            {
+                OnAfterReleaseResourcesUnlocked();
             }
 
             if (!success)
@@ -282,9 +292,15 @@ namespace Grpc.Core.Internal
         /// </summary>
         protected void HandleSendStatusFromServerFinished(bool success)
         {
+            bool releasedResources;
             lock (myLock)
             {
-                ReleaseResourcesIfPossible();
+                releasedResources = ReleaseResourcesIfPossible();
+            }
+
+            if (releasedResources)
+            {
+                OnAfterReleaseResourcesUnlocked();
             }
 
             if (!success)
@@ -310,6 +326,7 @@ namespace Grpc.Core.Internal
             var deserializeException = (success && receivedMessage != null) ? TryDeserialize(receivedMessage, out msg) : null;
 
             TaskCompletionSource<TRead> origTcs = null;
+            bool releasedResources;
             lock (myLock)
             {
                 origTcs = streamingReadTcs;
@@ -332,7 +349,12 @@ namespace Grpc.Core.Internal
                     streamingReadTcs = null;
                 }
 
-                ReleaseResourcesIfPossible();
+                releasedResources = ReleaseResourcesIfPossible();
+            }
+
+            if (releasedResources)
+            {
+                OnAfterReleaseResourcesUnlocked();
             }
 
             if (deserializeException != null && !IsClient)
diff --git a/src/csharp/Grpc.Core/Internal/AsyncCallServer.cs b/src/csharp/Grpc.Core/Internal/AsyncCallServer.cs
index 11acb27533..0ceca4abb8 100644
--- a/src/csharp/Grpc.Core/Internal/AsyncCallServer.cs
+++ b/src/csharp/Grpc.Core/Internal/AsyncCallServer.cs
@@ -184,7 +184,7 @@ namespace Grpc.Core.Internal
             throw new InvalidOperationException("Call be only called for client calls");
         }
 
-        protected override void OnAfterReleaseResources()
+        protected override void OnAfterReleaseResourcesLocked()
         {
             server.RemoveCallReference(this);
         }
@@ -206,6 +206,7 @@ namespace Grpc.Core.Internal
         {
             // NOTE: because this event is a result of batch containing GRPC_OP_RECV_CLOSE_ON_SERVER,
             // success will be always set to true.
+            bool releasedResources;
             lock (myLock)
             {
                 finished = true;
@@ -217,7 +218,12 @@ namespace Grpc.Core.Internal
                     streamingReadTcs = new TaskCompletionSource<TRequest>();
                     streamingReadTcs.SetResult(default(TRequest));
                 }
-                ReleaseResourcesIfPossible();
+                releasedResources = ReleaseResourcesIfPossible();
+            }
+
+            if (releasedResources)
+            {
+                OnAfterReleaseResourcesUnlocked();
             }
 
             if (cancelled)
diff --git a/src/csharp/Grpc.Core/Internal/MarshalUtils.cs b/src/csharp/Grpc.Core/Internal/MarshalUtils.cs
index 3f9605bfdd..09ded1a036 100644
--- a/src/csharp/Grpc.Core/Internal/MarshalUtils.cs
+++ b/src/csharp/Grpc.Core/Internal/MarshalUtils.cs
@@ -35,6 +35,13 @@ namespace Grpc.Core.Internal
         /// </summary>
         public static string PtrToStringUTF8(IntPtr ptr, int len)
         {
+            if (len == 0)
+            {
+                return "";
+            }
+
+            // TODO(jtattermusch): once Span dependency is added,
+            // use Span-based API to decode the string without copying the buffer.
             var bytes = new byte[len];
             Marshal.Copy(ptr, bytes, 0, len);
             return EncodingUTF8.GetString(bytes);
diff --git a/src/csharp/Grpc.Core/Internal/NativeMetadataCredentialsPlugin.cs b/src/csharp/Grpc.Core/Internal/NativeMetadataCredentialsPlugin.cs
index 4d695e8850..faeb51e6f7 100644
--- a/src/csharp/Grpc.Core/Internal/NativeMetadataCredentialsPlugin.cs
+++ b/src/csharp/Grpc.Core/Internal/NativeMetadataCredentialsPlugin.cs
@@ -68,8 +68,8 @@ namespace Grpc.Core.Internal
             }
             catch (Exception e)
             {
-                Native.grpcsharp_metadata_credentials_notify_from_plugin(callbackPtr, userDataPtr, MetadataArraySafeHandle.Create(Metadata.Empty), StatusCode.Unknown, GetMetadataExceptionStatusMsg);
-                Logger.Error(e, GetMetadataExceptionLogMsg);
+                // eat the exception, we must not throw when inside callback from native code.
+                Logger.Error(e, "Exception occurred while invoking native metadata interceptor handler.");
             }
         }
 
@@ -87,7 +87,8 @@ namespace Grpc.Core.Internal
             }
             catch (Exception e)
             {
-                Native.grpcsharp_metadata_credentials_notify_from_plugin(callbackPtr, userDataPtr, MetadataArraySafeHandle.Create(Metadata.Empty), StatusCode.Unknown, GetMetadataExceptionStatusMsg);
+                string detail = GetMetadataExceptionStatusMsg + " " + e.ToString();
+                Native.grpcsharp_metadata_credentials_notify_from_plugin(callbackPtr, userDataPtr, MetadataArraySafeHandle.Create(Metadata.Empty), StatusCode.Unknown, detail);
                 Logger.Error(e, GetMetadataExceptionLogMsg);
             }
         }
diff --git a/src/csharp/Grpc.Core/Internal/NativeMethods.Generated.cs b/src/csharp/Grpc.Core/Internal/NativeMethods.Generated.cs
index 153a52f947..a45cbe4107 100644
--- a/src/csharp/Grpc.Core/Internal/NativeMethods.Generated.cs
+++ b/src/csharp/Grpc.Core/Internal/NativeMethods.Generated.cs
@@ -505,7 +505,7 @@ namespace Grpc.Core.Internal
             public delegate void grpcsharp_redirect_log_delegate(GprLogDelegate callback);
             public delegate CallCredentialsSafeHandle grpcsharp_metadata_credentials_create_from_plugin_delegate(NativeMetadataInterceptor interceptor);
             public delegate void grpcsharp_metadata_credentials_notify_from_plugin_delegate(IntPtr callbackPtr, IntPtr userData, MetadataArraySafeHandle metadataArray, StatusCode statusCode, string errorDetails);
-            public delegate ServerCredentialsSafeHandle grpcsharp_ssl_server_credentials_create_delegate(string pemRootCerts, string[] keyCertPairCertChainArray, string[] keyCertPairPrivateKeyArray, UIntPtr numKeyCertPairs, int forceClientAuth);
+            public delegate ServerCredentialsSafeHandle grpcsharp_ssl_server_credentials_create_delegate(string pemRootCerts, string[] keyCertPairCertChainArray, string[] keyCertPairPrivateKeyArray, UIntPtr numKeyCertPairs, SslClientCertificateRequestType clientCertificateRequest);
             public delegate void grpcsharp_server_credentials_release_delegate(IntPtr credentials);
             public delegate ServerSafeHandle grpcsharp_server_create_delegate(ChannelArgsSafeHandle args);
             public delegate void grpcsharp_server_register_completion_queue_delegate(ServerSafeHandle server, CompletionQueueSafeHandle cq);
@@ -752,7 +752,7 @@ namespace Grpc.Core.Internal
             public static extern void grpcsharp_metadata_credentials_notify_from_plugin(IntPtr callbackPtr, IntPtr userData, MetadataArraySafeHandle metadataArray, StatusCode statusCode, string errorDetails);
             
             [DllImport(ImportName)]
-            public static extern ServerCredentialsSafeHandle grpcsharp_ssl_server_credentials_create(string pemRootCerts, string[] keyCertPairCertChainArray, string[] keyCertPairPrivateKeyArray, UIntPtr numKeyCertPairs, int forceClientAuth);
+            public static extern ServerCredentialsSafeHandle grpcsharp_ssl_server_credentials_create(string pemRootCerts, string[] keyCertPairCertChainArray, string[] keyCertPairPrivateKeyArray, UIntPtr numKeyCertPairs, SslClientCertificateRequestType clientCertificateRequest);
             
             [DllImport(ImportName)]
             public static extern void grpcsharp_server_credentials_release(IntPtr credentials);
@@ -1045,7 +1045,7 @@ namespace Grpc.Core.Internal
             public static extern void grpcsharp_metadata_credentials_notify_from_plugin(IntPtr callbackPtr, IntPtr userData, MetadataArraySafeHandle metadataArray, StatusCode statusCode, string errorDetails);
             
             [DllImport(ImportName)]
-            public static extern ServerCredentialsSafeHandle grpcsharp_ssl_server_credentials_create(string pemRootCerts, string[] keyCertPairCertChainArray, string[] keyCertPairPrivateKeyArray, UIntPtr numKeyCertPairs, int forceClientAuth);
+            public static extern ServerCredentialsSafeHandle grpcsharp_ssl_server_credentials_create(string pemRootCerts, string[] keyCertPairCertChainArray, string[] keyCertPairPrivateKeyArray, UIntPtr numKeyCertPairs, SslClientCertificateRequestType clientCertificateRequest);
             
             [DllImport(ImportName)]
             public static extern void grpcsharp_server_credentials_release(IntPtr credentials);
diff --git a/src/csharp/Grpc.Core/Internal/ServerCredentialsSafeHandle.cs b/src/csharp/Grpc.Core/Internal/ServerCredentialsSafeHandle.cs
index 545e581f94..5f8c95c4ea 100644
--- a/src/csharp/Grpc.Core/Internal/ServerCredentialsSafeHandle.cs
+++ b/src/csharp/Grpc.Core/Internal/ServerCredentialsSafeHandle.cs
@@ -32,13 +32,13 @@ namespace Grpc.Core.Internal
         {
         }
 
-        public static ServerCredentialsSafeHandle CreateSslCredentials(string pemRootCerts, string[] keyCertPairCertChainArray, string[] keyCertPairPrivateKeyArray, bool forceClientAuth)
+        public static ServerCredentialsSafeHandle CreateSslCredentials(string pemRootCerts, string[] keyCertPairCertChainArray, string[] keyCertPairPrivateKeyArray, SslClientCertificateRequestType clientCertificateRequest)
         {
             GrpcPreconditions.CheckArgument(keyCertPairCertChainArray.Length == keyCertPairPrivateKeyArray.Length);
             return Native.grpcsharp_ssl_server_credentials_create(pemRootCerts,
                                                                   keyCertPairCertChainArray, keyCertPairPrivateKeyArray,
                                                                   new UIntPtr((ulong)keyCertPairCertChainArray.Length),
-                                                                  forceClientAuth ? 1 : 0);
+                                                                  clientCertificateRequest);
         }
 
         protected override bool ReleaseHandle()
diff --git a/src/csharp/Grpc.Core/Internal/UnmanagedLibrary.cs b/src/csharp/Grpc.Core/Internal/UnmanagedLibrary.cs
index 7185d68efe..1786fc2e3f 100644
--- a/src/csharp/Grpc.Core/Internal/UnmanagedLibrary.cs
+++ b/src/csharp/Grpc.Core/Internal/UnmanagedLibrary.cs
@@ -51,11 +51,12 @@ namespace Grpc.Core.Internal
 
             Logger.Debug("Attempting to load native library \"{0}\"", this.libraryPath);
 
-            this.handle = PlatformSpecificLoadLibrary(this.libraryPath);
+            this.handle = PlatformSpecificLoadLibrary(this.libraryPath, out string loadLibraryErrorDetail);
 
             if (this.handle == IntPtr.Zero)
             {
-                throw new IOException(string.Format("Error loading native library \"{0}\"", this.libraryPath));
+                throw new IOException(string.Format("Error loading native library \"{0}\". {1}",
+                                                    this.libraryPath, loadLibraryErrorDetail));
             }
         }
 
@@ -129,31 +130,44 @@ namespace Grpc.Core.Internal
         /// <summary>
         /// Loads library in a platform specific way.
         /// </summary>
-        private static IntPtr PlatformSpecificLoadLibrary(string libraryPath)
+        private static IntPtr PlatformSpecificLoadLibrary(string libraryPath, out string errorMsg)
         {
             if (PlatformApis.IsWindows)
             {
+                // TODO(jtattermusch): populate the error on Windows
+                errorMsg = null;
                 return Windows.LoadLibrary(libraryPath);
             }
             if (PlatformApis.IsLinux)
             {
                 if (PlatformApis.IsMono)
                 {
-                    return Mono.dlopen(libraryPath, RTLD_GLOBAL + RTLD_LAZY);
+                    return LoadLibraryPosix(Mono.dlopen, Mono.dlerror, libraryPath, out errorMsg);
                 }
                 if (PlatformApis.IsNetCore)
                 {
-                    return CoreCLR.dlopen(libraryPath, RTLD_GLOBAL + RTLD_LAZY);
+                    return LoadLibraryPosix(CoreCLR.dlopen, CoreCLR.dlerror, libraryPath, out errorMsg);
                 }
-                return Linux.dlopen(libraryPath, RTLD_GLOBAL + RTLD_LAZY);
+                return LoadLibraryPosix(Linux.dlopen, Linux.dlerror, libraryPath, out errorMsg);
             }
             if (PlatformApis.IsMacOSX)
             {
-                return MacOSX.dlopen(libraryPath, RTLD_GLOBAL + RTLD_LAZY);
+                return LoadLibraryPosix(MacOSX.dlopen, MacOSX.dlerror, libraryPath, out errorMsg);
             }
             throw new InvalidOperationException("Unsupported platform.");
         }
 
+        private static IntPtr LoadLibraryPosix(Func<string, int, IntPtr> dlopenFunc, Func<IntPtr> dlerrorFunc, string libraryPath, out string errorMsg)
+        {
+            errorMsg = null;
+            IntPtr ret = dlopenFunc(libraryPath, RTLD_GLOBAL + RTLD_LAZY);
+            if (ret == IntPtr.Zero)
+            {
+                errorMsg = Marshal.PtrToStringAnsi(dlerrorFunc());
+            }
+            return ret;
+        }
+
         private static string FirstValidLibraryPath(string[] libraryPathAlternatives)
         {
             GrpcPreconditions.CheckArgument(libraryPathAlternatives.Length > 0, "libraryPathAlternatives cannot be empty.");
@@ -184,6 +198,9 @@ namespace Grpc.Core.Internal
             internal static extern IntPtr dlopen(string filename, int flags);
 
             [DllImport("libdl.so")]
+            internal static extern IntPtr dlerror();
+
+            [DllImport("libdl.so")]
             internal static extern IntPtr dlsym(IntPtr handle, string symbol);
         }
 
@@ -193,6 +210,9 @@ namespace Grpc.Core.Internal
             internal static extern IntPtr dlopen(string filename, int flags);
 
             [DllImport("libSystem.dylib")]
+            internal static extern IntPtr dlerror();
+
+            [DllImport("libSystem.dylib")]
             internal static extern IntPtr dlsym(IntPtr handle, string symbol);
         }
 
@@ -209,6 +229,9 @@ namespace Grpc.Core.Internal
             internal static extern IntPtr dlopen(string filename, int flags);
 
             [DllImport("__Internal")]
+            internal static extern IntPtr dlerror();
+
+            [DllImport("__Internal")]
             internal static extern IntPtr dlsym(IntPtr handle, string symbol);
         }
 
@@ -223,6 +246,9 @@ namespace Grpc.Core.Internal
             internal static extern IntPtr dlopen(string filename, int flags);
 
             [DllImport("libcoreclr.so")]
+            internal static extern IntPtr dlerror();
+
+            [DllImport("libcoreclr.so")]
             internal static extern IntPtr dlsym(IntPtr handle, string symbol);
         }
     }
diff --git a/src/csharp/Grpc.Core/Marshaller.cs b/src/csharp/Grpc.Core/Marshaller.cs
index 1d758ca935..0af9aa586b 100644
--- a/src/csharp/Grpc.Core/Marshaller.cs
+++ b/src/csharp/Grpc.Core/Marshaller.cs
@@ -29,36 +29,129 @@ namespace Grpc.Core
         readonly Func<T, byte[]> serializer;
         readonly Func<byte[], T> deserializer;
 
+        readonly Action<T, SerializationContext> contextualSerializer;
+        readonly Func<DeserializationContext, T> contextualDeserializer;
+
         /// <summary>
-        /// Initializes a new marshaller.
+        /// Initializes a new marshaller from simple serialize/deserialize functions.
         /// </summary>
         /// <param name="serializer">Function that will be used to serialize messages.</param>
         /// <param name="deserializer">Function that will be used to deserialize messages.</param>
         public Marshaller(Func<T, byte[]> serializer, Func<byte[], T> deserializer)
         {
-            this.serializer = GrpcPreconditions.CheckNotNull(serializer, "serializer");
-            this.deserializer = GrpcPreconditions.CheckNotNull(deserializer, "deserializer");
+            this.serializer = GrpcPreconditions.CheckNotNull(serializer, nameof(serializer));
+            this.deserializer = GrpcPreconditions.CheckNotNull(deserializer, nameof(deserializer));
+            this.contextualSerializer = EmulateContextualSerializer;
+            this.contextualDeserializer = EmulateContextualDeserializer;
         }
 
         /// <summary>
-        /// Gets the serializer function.
+        /// Initializes a new marshaller from serialize/deserialize fuctions that can access serialization and deserialization
+        /// context. Compared to the simple serializer/deserializer functions, using the contextual version provides more
+        /// flexibility and can lead to increased efficiency (and better performance).
+        /// Note: This constructor is part of an experimental API that can change or be removed without any prior notice.
         /// </summary>
-        public Func<T, byte[]> Serializer
+        /// <param name="serializer">Function that will be used to serialize messages.</param>
+        /// <param name="deserializer">Function that will be used to deserialize messages.</param>
+        public Marshaller(Action<T, SerializationContext> serializer, Func<DeserializationContext, T> deserializer)
         {
-            get
-            {
-                return this.serializer;
-            }
+            this.contextualSerializer = GrpcPreconditions.CheckNotNull(serializer, nameof(serializer));
+            this.contextualDeserializer = GrpcPreconditions.CheckNotNull(deserializer, nameof(deserializer));
+            // TODO(jtattermusch): once gRPC C# library switches to using contextual (de)serializer,
+            // emulating the simple (de)serializer will become unnecessary.
+            this.serializer = EmulateSimpleSerializer;
+            this.deserializer = EmulateSimpleDeserializer;
         }
 
         /// <summary>
+        /// Gets the serializer function.
+        /// </summary>
+        public Func<T, byte[]> Serializer => this.serializer;
+
+        /// <summary>
         /// Gets the deserializer function.
         /// </summary>
-        public Func<byte[], T> Deserializer
+        public Func<byte[], T> Deserializer => this.deserializer;
+
+        /// <summary>
+        /// Gets the serializer function.
+        /// Note: experimental API that can change or be removed without any prior notice.
+        /// </summary>
+        public Action<T, SerializationContext> ContextualSerializer => this.contextualSerializer;
+
+        /// <summary>
+        /// Gets the serializer function.
+        /// Note: experimental API that can change or be removed without any prior notice.
+        /// </summary>
+        public Func<DeserializationContext, T> ContextualDeserializer => this.contextualDeserializer;
+
+        // for backward compatibility, emulate the simple serializer using the contextual one
+        private byte[] EmulateSimpleSerializer(T msg)
         {
-            get
+            // TODO(jtattermusch): avoid the allocation by passing a thread-local instance
+            // This code will become unnecessary once gRPC C# library switches to using contextual (de)serializer.
+            var context = new EmulatedSerializationContext();
+            this.contextualSerializer(msg, context);
+            return context.GetPayload();
+        }
+
+        // for backward compatibility, emulate the simple deserializer using the contextual one
+        private T EmulateSimpleDeserializer(byte[] payload)
+        {
+            // TODO(jtattermusch): avoid the allocation by passing a thread-local instance
+            // This code will become unnecessary once gRPC C# library switches to using contextual (de)serializer.
+            var context = new EmulatedDeserializationContext(payload);
+            return this.contextualDeserializer(context);
+        }
+
+        // for backward compatibility, emulate the contextual serializer using the simple one
+        private void EmulateContextualSerializer(T message, SerializationContext context)
+        {
+            var payload = this.serializer(message);
+            context.Complete(payload);
+        }
+
+        // for backward compatibility, emulate the contextual deserializer using the simple one
+        private T EmulateContextualDeserializer(DeserializationContext context)
+        {
+            return this.deserializer(context.PayloadAsNewBuffer());
+        }
+
+        internal class EmulatedSerializationContext : SerializationContext
+        {
+            bool isComplete;
+            byte[] payload;
+
+            public override void Complete(byte[] payload)
+            {
+                GrpcPreconditions.CheckState(!isComplete);
+                this.isComplete = true;
+                this.payload = payload;
+            }
+
+            internal byte[] GetPayload()
+            {
+                return this.payload;
+            }
+        }
+
+        internal class EmulatedDeserializationContext : DeserializationContext
+        {
+            readonly byte[] payload;
+            bool alreadyCalledPayloadAsNewBuffer;
+
+            public EmulatedDeserializationContext(byte[] payload)
+            {
+                this.payload = GrpcPreconditions.CheckNotNull(payload);
+            }
+
+            public override int PayloadLength => payload.Length;
+
+            public override byte[] PayloadAsNewBuffer()
             {
-                return this.deserializer;
+                GrpcPreconditions.CheckState(!alreadyCalledPayloadAsNewBuffer);
+                alreadyCalledPayloadAsNewBuffer = true;
+                return payload;
             }
         }
     }
@@ -77,6 +170,15 @@ namespace Grpc.Core
         }
 
         /// <summary>
+        /// Creates a marshaller from specified contextual serializer and deserializer.
+        /// Note: This method is part of an experimental API that can change or be removed without any prior notice.
+        /// </summary>
+        public static Marshaller<T> Create<T>(Action<T, SerializationContext> serializer, Func<DeserializationContext, T> deserializer)
+        {
+            return new Marshaller<T>(serializer, deserializer);
+        }
+
+        /// <summary>
         /// Returns a marshaller for <c>string</c> type. This is useful for testing.
         /// </summary>
         public static Marshaller<string> StringMarshaller
diff --git a/src/csharp/Grpc.Core/Metadata.cs b/src/csharp/Grpc.Core/Metadata.cs
index 0e4456278c..bc263c3469 100644
--- a/src/csharp/Grpc.Core/Metadata.cs
+++ b/src/csharp/Grpc.Core/Metadata.cs
@@ -135,7 +135,7 @@ namespace Grpc.Core
         }
 
         /// <summary>
-        /// <see cref="T:IList`1"/>
+        /// Adds a new ASCII-valued metadata entry. See <c>Metadata.Entry</c> constructor for params.
         /// </summary>
         public void Add(string key, string value)
         {
@@ -143,7 +143,7 @@ namespace Grpc.Core
         }
 
         /// <summary>
-        /// <see cref="T:IList`1"/>
+        /// Adds a new binary-valued metadata entry. See <c>Metadata.Entry</c> constructor for params.
         /// </summary>
         public void Add(string key, byte[] valueBytes)
         {
@@ -225,8 +225,6 @@ namespace Grpc.Core
         /// </summary>
         public class Entry
         {
-            private static readonly Regex ValidKeyRegex = new Regex("^[a-z0-9_-]+$");
-
             readonly string key;
             readonly string value;
             readonly byte[] valueBytes;
@@ -241,7 +239,7 @@ namespace Grpc.Core
             /// <summary>
             /// Initializes a new instance of the <see cref="Grpc.Core.Metadata.Entry"/> struct with a binary value.
             /// </summary>
-            /// <param name="key">Metadata key, needs to have suffix indicating a binary valued metadata entry.</param>
+            /// <param name="key">Metadata key. Gets converted to lowercase. Needs to have suffix indicating a binary valued metadata entry. Can only contain lowercase alphanumeric characters, underscores, hyphens and dots.</param>
             /// <param name="valueBytes">Value bytes.</param>
             public Entry(string key, byte[] valueBytes)
             {
@@ -255,9 +253,9 @@ namespace Grpc.Core
             }
 
             /// <summary>
-            /// Initializes a new instance of the <see cref="Grpc.Core.Metadata.Entry"/> struct holding an ASCII value.
+            /// Initializes a new instance of the <see cref="Grpc.Core.Metadata.Entry"/> struct with an ASCII value.
             /// </summary>
-            /// <param name="key">Metadata key, must not use suffix indicating a binary valued metadata entry.</param>
+            /// <param name="key">Metadata key. Gets converted to lowercase. Must not use suffix indicating a binary valued metadata entry. Can only contain lowercase alphanumeric characters, underscores, hyphens and dots.</param>
             /// <param name="value">Value string. Only ASCII characters are allowed.</param>
             public Entry(string key, string value)
             {
@@ -358,10 +356,42 @@ namespace Grpc.Core
 
             private static string NormalizeKey(string key)
             {
-                var normalized = GrpcPreconditions.CheckNotNull(key, "key").ToLowerInvariant();
-                GrpcPreconditions.CheckArgument(ValidKeyRegex.IsMatch(normalized), 
-                    "Metadata entry key not valid. Keys can only contain lowercase alphanumeric characters, underscores and hyphens.");
-                return normalized;
+                GrpcPreconditions.CheckNotNull(key, "key");
+
+                GrpcPreconditions.CheckArgument(IsValidKey(key, out bool isLowercase), 
+                    "Metadata entry key not valid. Keys can only contain lowercase alphanumeric characters, underscores, hyphens and dots.");
+                if (isLowercase)
+                {
+                    // save allocation of a new string if already lowercase
+                    return key;
+                }
+                
+                return key.ToLowerInvariant();
+            }
+
+            private static bool IsValidKey(string input, out bool isLowercase)
+            {
+                isLowercase = true;
+                for (int i = 0; i < input.Length; i++)
+                {
+                    char c = input[i];
+                    if ('a' <= c && c <= 'z' ||
+                        '0' <= c && c <= '9' ||
+                        c == '.' ||
+                        c == '_' || 
+                        c == '-' )
+                        continue;
+
+                    if ('A' <= c && c <= 'Z')
+                    {
+                        isLowercase = false;
+                        continue;
+                    }
+
+                    return false;
+                }
+
+                return true;
             }
 
             /// <summary>
diff --git a/src/csharp/Grpc.Core/NativeDeps.Linux.csproj.include b/src/csharp/Grpc.Core/NativeDeps.Linux.csproj.include
index e3bbeb071e..af660064a4 100644
--- a/src/csharp/Grpc.Core/NativeDeps.Linux.csproj.include
+++ b/src/csharp/Grpc.Core/NativeDeps.Linux.csproj.include
@@ -1,6 +1,6 @@
 <Project>
   <ItemGroup>
-    <Content Include="..\..\..\libs\$(NativeDependenciesConfigurationUnix)\libgrpc_csharp_ext.so">
+    <Content Include="..\..\..\cmake\build\libgrpc_csharp_ext.so">
       <Link>libgrpc_csharp_ext.x64.so</Link>
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
       <Pack>false</Pack>
diff --git a/src/csharp/Grpc.Core/NativeDeps.Mac.csproj.include b/src/csharp/Grpc.Core/NativeDeps.Mac.csproj.include
index 309e33d47e..570b0cd8b7 100644
--- a/src/csharp/Grpc.Core/NativeDeps.Mac.csproj.include
+++ b/src/csharp/Grpc.Core/NativeDeps.Mac.csproj.include
@@ -1,6 +1,6 @@
 <Project>
   <ItemGroup>
-    <Content Include="..\..\..\libs\$(NativeDependenciesConfigurationUnix)\libgrpc_csharp_ext.dylib">
+    <Content Include="..\..\..\cmake\build\libgrpc_csharp_ext.dylib">
       <Link>libgrpc_csharp_ext.x64.dylib</Link>
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
       <Pack>false</Pack>
diff --git a/src/csharp/Grpc.Core/RpcException.cs b/src/csharp/Grpc.Core/RpcException.cs
index 94429d74ce..ff89897565 100644
--- a/src/csharp/Grpc.Core/RpcException.cs
+++ b/src/csharp/Grpc.Core/RpcException.cs
@@ -33,10 +33,8 @@ namespace Grpc.Core
         /// Creates a new <c>RpcException</c> associated with given status.
         /// </summary>
         /// <param name="status">Resulting status of a call.</param>
-        public RpcException(Status status) : base(status.ToString())
+        public RpcException(Status status) : this(status, Metadata.Empty, status.ToString())
         {
-            this.status = status;
-            this.trailers = Metadata.Empty;
         }
 
         /// <summary>
@@ -44,10 +42,8 @@ namespace Grpc.Core
         /// </summary>
         /// <param name="status">Resulting status of a call.</param>
         /// <param name="message">The exception message.</param> 
-        public RpcException(Status status, string message) : base(message)
+        public RpcException(Status status, string message) : this(status, Metadata.Empty, message)
         {
-            this.status = status;
-            this.trailers = Metadata.Empty;
         }
 
         /// <summary>
@@ -55,7 +51,17 @@ namespace Grpc.Core
         /// </summary>
         /// <param name="status">Resulting status of a call.</param>
         /// <param name="trailers">Response trailing metadata.</param> 
-        public RpcException(Status status, Metadata trailers) : base(status.ToString())
+        public RpcException(Status status, Metadata trailers) : this(status, trailers, status.ToString())
+        {
+        }
+
+        /// <summary>
+        /// Creates a new <c>RpcException</c> associated with given status, message and trailing response metadata.
+        /// </summary>
+        /// <param name="status">Resulting status of a call.</param>
+        /// <param name="trailers">Response trailing metadata.</param>
+        /// <param name="message">The exception message.</param>
+        public RpcException(Status status, Metadata trailers, string message) : base(message)
         {
             this.status = status;
             this.trailers = GrpcPreconditions.CheckNotNull(trailers);
diff --git a/src/csharp/Grpc.Core/SerializationContext.cs b/src/csharp/Grpc.Core/SerializationContext.cs
new file mode 100644
index 0000000000..cf4d1595da
--- /dev/null
+++ b/src/csharp/Grpc.Core/SerializationContext.cs
@@ -0,0 +1,34 @@
+#region Copyright notice and license
+
+// Copyright 2018 The gRPC Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#endregion
+
+namespace Grpc.Core
+{
+    /// <summary>
+    /// Provides storage for payload when serializing a message.
+    /// </summary>
+    public abstract class SerializationContext
+    {
+        /// <summary>
+        /// Use the byte array as serialized form of current message and mark serialization process as complete.
+        /// Complete() can only be called once. By calling this method the caller gives up the ownership of the
+        /// payload which must not be accessed afterwards.
+        /// </summary>
+        /// <param name="payload">the serialized form of current message</param>
+        public abstract void Complete(byte[] payload);
+    }
+}
diff --git a/src/csharp/Grpc.Core/ServerCredentials.cs b/src/csharp/Grpc.Core/ServerCredentials.cs
index 703f9ff6b3..8e4e44ba50 100644
--- a/src/csharp/Grpc.Core/ServerCredentials.cs
+++ b/src/csharp/Grpc.Core/ServerCredentials.cs
@@ -58,41 +58,106 @@ namespace Grpc.Core
     }
 
     /// <summary>
+    /// Modes of requesting client's SSL certificate by the server.
+    /// Corresponds to <c>grpc_ssl_client_certificate_request_type</c>.
+    /// </summary>
+    public enum SslClientCertificateRequestType {
+        /// <summary>
+        /// Server does not request client certificate.
+        /// The certificate presented by the client is not checked by the server at
+        /// all. (A client may present a self signed or signed certificate or not
+        /// present a certificate at all and any of those option would be accepted)
+        /// </summary>
+        DontRequest = 0,
+        /// <summary>
+        /// Server requests client certificate but does not enforce that the client
+        /// presents a certificate.
+        /// If the client presents a certificate, the client authentication is left to
+        /// the application (the necessary metadata will be available to the
+        /// application via authentication context properties, see grpc_auth_context).
+        /// The client's key certificate pair must be valid for the SSL connection to
+        /// be established.
+        ///</summary>
+        RequestButDontVerify,
+        /// <summary>
+        /// Server requests client certificate but does not enforce that the client
+        /// presents a certificate.
+        /// If the client presents a certificate, the client authentication is done by
+        /// the gRPC framework. (For a successful connection the client needs to either
+        /// present a certificate that can be verified against the root certificate
+        /// configured by the server or not present a certificate at all)
+        /// The client's key certificate pair must be valid for the SSL connection to
+        /// be established.
+        /// </summary>
+        RequestAndVerify,
+        /// <summary>
+        /// Server requests client certificate and enforces that the client presents a
+        /// certificate.
+        /// If the client presents a certificate, the client authentication is left to
+        /// the application (the necessary metadata will be available to the
+        /// application via authentication context properties, see grpc_auth_context).
+        /// The client's key certificate pair must be valid for the SSL connection to
+        /// be established.
+        ///</summary>
+        RequestAndRequireButDontVerify,
+        /// <summary>
+        /// Server requests client certificate and enforces that the client presents a
+        /// certificate.
+        /// The cerificate presented by the client is verified by the gRPC framework.
+        /// (For a successful connection the client needs to present a certificate that
+        /// can be verified against the root certificate configured by the server)
+        /// The client's key certificate pair must be valid for the SSL connection to
+        /// be established.
+        /// </summary>
+        RequestAndRequireAndVerify,
+    }
+    /// <summary>
     /// Server-side SSL credentials.
     /// </summary>
     public class SslServerCredentials : ServerCredentials
     {
         readonly IList<KeyCertificatePair> keyCertificatePairs;
         readonly string rootCertificates;
-        readonly bool forceClientAuth;
+        readonly SslClientCertificateRequestType clientCertificateRequest;
 
         /// <summary>
         /// Creates server-side SSL credentials.
         /// </summary>
         /// <param name="keyCertificatePairs">Key-certificates to use.</param>
         /// <param name="rootCertificates">PEM encoded client root certificates used to authenticate client.</param>
-        /// <param name="forceClientAuth">If true, client will be rejected unless it proves its unthenticity using against rootCertificates.</param>
+        /// <param name="forceClientAuth">Deprecated, use clientCertificateRequest overload instead.</param>
         public SslServerCredentials(IEnumerable<KeyCertificatePair> keyCertificatePairs, string rootCertificates, bool forceClientAuth)
+            : this(keyCertificatePairs, rootCertificates, forceClientAuth ? SslClientCertificateRequestType.RequestAndRequireAndVerify : SslClientCertificateRequestType.DontRequest)
+        {
+        }
+
+        /// <summary>
+        /// Creates server-side SSL credentials.
+        /// </summary>
+        /// <param name="keyCertificatePairs">Key-certificates to use.</param>
+        /// <param name="rootCertificates">PEM encoded client root certificates used to authenticate client.</param>
+        /// <param name="clientCertificateRequest">Options for requesting and verifying client certificate.</param>
+        public SslServerCredentials(IEnumerable<KeyCertificatePair> keyCertificatePairs, string rootCertificates, SslClientCertificateRequestType clientCertificateRequest)
         {
             this.keyCertificatePairs = new List<KeyCertificatePair>(keyCertificatePairs).AsReadOnly();
             GrpcPreconditions.CheckArgument(this.keyCertificatePairs.Count > 0,
                 "At least one KeyCertificatePair needs to be provided.");
-            if (forceClientAuth)
+            if (clientCertificateRequest == SslClientCertificateRequestType.RequestAndRequireAndVerify)
             {
                 GrpcPreconditions.CheckNotNull(rootCertificates,
-                    "Cannot force client authentication unless you provide rootCertificates.");
+                    "Cannot require and verify client certificate unless you provide rootCertificates.");
             }
             this.rootCertificates = rootCertificates;
-            this.forceClientAuth = forceClientAuth;
+            this.clientCertificateRequest = clientCertificateRequest;
         }
 
         /// <summary>
         /// Creates server-side SSL credentials.
-        /// This constructor should be use if you do not wish to autheticate client
-        /// using client root certificates.
+        /// This constructor should be used if you do not wish to authenticate the client.
+        /// (client certificate won't be requested and checked by the server at all).
         /// </summary>
         /// <param name="keyCertificatePairs">Key-certificates to use.</param>
-        public SslServerCredentials(IEnumerable<KeyCertificatePair> keyCertificatePairs) : this(keyCertificatePairs, null, false)
+        public SslServerCredentials(IEnumerable<KeyCertificatePair> keyCertificatePairs) : this(keyCertificatePairs, null, SslClientCertificateRequestType.DontRequest)
         {
         }
 
@@ -119,13 +184,24 @@ namespace Grpc.Core
         }
 
         /// <summary>
-        /// If true, the authenticity of client check will be enforced.
+        /// Deprecated. If true, the authenticity of client check will be enforced.
         /// </summary>
         public bool ForceClientAuthentication
         {
             get
             {
-                return this.forceClientAuth;
+                return this.clientCertificateRequest == SslClientCertificateRequestType.RequestAndRequireAndVerify;
+            }
+        }
+
+        /// <summary>
+        /// Mode of requesting certificate from client by the server.
+        /// </summary>
+        public SslClientCertificateRequestType ClientCertificateRequest
+        {
+            get
+            {
+                return this.clientCertificateRequest;
             }
         }
 
@@ -139,7 +215,7 @@ namespace Grpc.Core
                 certChains[i] = keyCertificatePairs[i].CertificateChain;
                 keys[i] = keyCertificatePairs[i].PrivateKey;
             }
-            return ServerCredentialsSafeHandle.CreateSslCredentials(rootCertificates, certChains, keys, forceClientAuth);
+            return ServerCredentialsSafeHandle.CreateSslCredentials(rootCertificates, certChains, keys, clientCertificateRequest);
         }
     }
 }
diff --git a/src/csharp/Grpc.Core/Version.csproj.include b/src/csharp/Grpc.Core/Version.csproj.include
index 45bd8ebd85..ed0d884365 100755
--- a/src/csharp/Grpc.Core/Version.csproj.include
+++ b/src/csharp/Grpc.Core/Version.csproj.include
@@ -1,7 +1,7 @@
 <!-- This file is generated -->
 <Project>
   <PropertyGroup>
-    <GrpcCsharpVersion>1.15.0-dev</GrpcCsharpVersion>
+    <GrpcCsharpVersion>1.17.0-dev</GrpcCsharpVersion>
     <GoogleProtobufVersion>3.6.1</GoogleProtobufVersion>
   </PropertyGroup>
 </Project>
diff --git a/src/csharp/Grpc.Core/VersionInfo.cs b/src/csharp/Grpc.Core/VersionInfo.cs
index 295e0f2577..14714c8c4a 100644
--- a/src/csharp/Grpc.Core/VersionInfo.cs
+++ b/src/csharp/Grpc.Core/VersionInfo.cs
@@ -33,11 +33,11 @@ namespace Grpc.Core
         /// <summary>
         /// Current <c>AssemblyFileVersion</c> of gRPC C# assemblies
         /// </summary>
-        public const string CurrentAssemblyFileVersion = "1.15.0.0";
+        public const string CurrentAssemblyFileVersion = "1.17.0.0";
 
         /// <summary>
         /// Current version of gRPC C#
         /// </summary>
-        public const string CurrentVersion = "1.15.0-dev";
+        public const string CurrentVersion = "1.17.0-dev";
     }
 }