Improve IFormCollection.Items documentation (#44372)

Fixes #36712

Co-authored-by: Safia Abdalla <[email protected]>
Co-authored-by: James Newton-King <[email protected]>

Author: 3 people

src/Http/Http.Abstractions/src/HttpRequest.cs

@@ -120,11 +120,24 @@ public abstract class HttpRequest
     /// <summary>
     /// Gets or sets the request body as a form.
     /// </summary>
+    /// <exception cref="System.InvalidOperationException">
+    ///     incorrect content-type.
+    /// </exception>
+    /// <remarks>
+    ///     <para>
+    ///     Invoking this property could result in thread exhaustion since it's wrapping an asynchronous implementation.
+    ///     To prevent this the method <see cref="ReadFormAsync(CancellationToken)"/> can be used.
+    ///     For more information, see <see href="https://aka.ms/aspnet/forms-async" />.
+    ///     </para>
+    /// </remarks>
     public abstract IFormCollection Form { get; set; }
 
     /// <summary>
     /// Reads the request body if it is a form.
     /// </summary>
+    /// <exception cref="System.InvalidOperationException">
+    ///     incorrect content-type.
+    /// </exception>
     /// <returns></returns>
     public abstract Task<IFormCollection> ReadFormAsync(CancellationToken cancellationToken = new CancellationToken());
 

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.
+    ///     The <c>HttpRequest.ReadFormAsync(CancellationToken)</c> method can get the form without blocking.
+    ///     For more information, see <see href="https://aka.ms/aspnet/forms-async" />.
+    ///     </para>
     /// </remarks>
     StringValues this[string key] { get; }
 

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

@@ -101,11 +101,10 @@ public IFormCollection ReadForm()
 
         if (!HasFormContentType)
         {
-            throw new InvalidOperationException("Incorrect Content-Type: " + _request.ContentType);
+            throw new InvalidOperationException("This request does not have a Content-Type header. Forms are available from requests with bodies like POSTs and a form Content-Type of either application/x-www-form-urlencoded or multipart/form-data.");
         }
 
-        // TODO: Issue #456 Avoid Sync-over-Async http://blogs.msdn.com/b/pfxteam/archive/2012/04/13/10293638.aspx
-        // TODO: How do we prevent thread exhaustion?
+        // c.f., https://aka.ms/aspnet/forms-async
         return ReadFormAsync().GetAwaiter().GetResult();
     }