Improve IFormCollection.Items documentation

Fixes #36712

Author: sebastienros

src/Http/Http.Features/src/IFormCollection.cs

@@ -77,10 +77,24 @@ public interface IFormCollection : IEnumerable<KeyValuePair<string, StringValues
     /// <exception cref="System.ArgumentNullException">
     ///     key is null.
     /// </exception>
+    /// <exception cref="System.InvalidOperationException">
+    ///     incorrect content-type.
+    /// </exception>
     /// <remarks>
+    ///     <para>
     ///     <see cref="IFormCollection" /> has a different indexer contract than
     ///     <see cref="IDictionary{TKey, TValue}" />, as it will return <c>StringValues.Empty</c> for missing entries
     ///     rather than throwing an Exception.
+    ///     </para>
+    ///     <para>
+    ///     This indexer can only be used on POST requests. Otherwise an exception of type
+    ///     <see cref="System.InvalidOperationException" /> is thrown.
+    ///     </para>
+    ///     <para>
+    ///     Invoking this property could result in thread exhaustion since it's wrapping an asynchronous implementation.
+    ///     To prevent this the method <see cref="Microsoft.AspNetCore.Http.Features.FormFeature.ReadFormAsync"> can be used.
+    ///     For more information please read https://devblogs.microsoft.com/pfxteam/should-i-expose-synchronous-wrappers-for-asynchronous-methods/.
+    ///     </para>
     /// </remarks>
     StringValues this[string key] { get; }
 

src/Http/Http/src/Features/FormFeature.cs

@@ -101,10 +101,10 @@ public IFormCollection ReadForm()
 
         if (!HasFormContentType)
         {
-            throw new InvalidOperationException("Incorrect Content-Type: " + _request.ContentType);
+            throw new InvalidOperationException("Form Collection properties can only be accessed from a POST request");
         }
 
-        // TODO: Issue #456 Avoid Sync-over-Async http://blogs.msdn.com/b/pfxteam/archive/2012/04/13/10293638.aspx
+        // TODO: Issue #456 Avoid Sync-over-Async https://devblogs.microsoft.com/pfxteam/should-i-expose-synchronous-wrappers-for-asynchronous-methods/
         // TODO: How do we prevent thread exhaustion?
         return ReadFormAsync().GetAwaiter().GetResult();
     }