Update API for SameSitemode (dotnet#3569)

BillWagner · web-flow · commit 7f1e86ffb2f5 · 2019-11-26T12:55:34.000-05:00
* Update API for SameSitemode

On framework systems, the behavior of SameSiteMode.None has changed.

This PR documents the new behavior, and links to the KB articles.

* Update xml/System.Web/SameSiteMode.xml

Co-Authored-By: Chris Ross &lt;Tratcher@Outlook.com&gt;

* respond to feedback.

* update per review.

* Update default description.

* missing an opening bracket.

* Apply suggestions from code review

Co-Authored-By: Scott Addie &lt;10702007+scottaddie@users.noreply.github.com&gt;

* Update xml/System.Web/SameSiteMode.xml

Co-Authored-By: Genevieve Warren &lt;gewarren@microsoft.com&gt;

* Update xml/System.Web/SameSiteMode.xml

Co-Authored-By: Chris Ross &lt;Tratcher@Outlook.com&gt;

* respond to feedback.

* final proofread updates.
diff --git a/xml/System.Web/HttpCookie.xml b/xml/System.Web/HttpCookie.xml
@@ -404,8 +404,18 @@ The <xref:System.Web.HttpCookie.Path%2A> property extends the <xref:System.Web.H
       </ReturnValue>
       <Docs>
         <summary>Gets or sets the value for the SameSite attribute of the cookie.</summary>
-        <value>One of the enumeration values that represents the enforcement mode of the cookie. If the application targets the .NET Framework 4.7.2 or later versions, the default value is <see cref="F:System.Web.SameSiteMode.Lax" />; otherwise, the default value is <see cref="F:System.Web.SameSiteMode.None" />.</value>
-        <remarks>To be added.</remarks>
+        <value>One of the enumeration values that represents the enforcement mode of the cookie or `(SameSiteMode)(-1)` (represented by the string `Unspecified` in config files). The default value depends on updates. For more information on defaults and recent updates, see Remarks.</value>
+        <remarks><format type="text/markdown"><![CDATA[  
+  
+## Remarks
+
+The default value of this property was modifed by updates described in [KB article 4531182](https://support.microsoft.com/help/4531182/kb4531182) and [KB article 4524421](https://support.microsoft.com/help/4524421/kb4524421).
+
+Without these updates, the default value is <see cref="F:System.Web.SameSiteMode.None" />, which does not emit the `SameSite` cookie header. This conforms to [https://tools.ietf.org/html/draft-west-first-party-cookies-07#section-4.1](https://tools.ietf.org/html/draft-west-first-party-cookies-07#section-4.1).
+
+After these updates have been applied, the default value is `(SameSiteMode)(-1)`, which corresponds to `Unspecified`. This preserves the earlier behavior. Setting `SameSiteMode.None` causes "SameSite=None" to be emitted. This new behavior conforms to [https://tools.ietf.org/html/draft-west-cookie-incrementalism-00](https://tools.ietf.org/html/draft-west-cookie-incrementalism-00). 
+]]></format>
+</remarks>
       </Docs>
     </Member>
     <Member MemberName="Secure">
diff --git a/xml/System.Web/SameSiteMode.xml b/xml/System.Web/SameSiteMode.xml
@@ -14,7 +14,20 @@
   </Base>
   <Docs>
     <summary>Specifies constants that indicate the value for the SameSite attribute of the cookie.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks
+
+The behavior of <see cref="F:System.Web.SameSiteMode.None" /> was modified by updates described in [KB article 4531182](https://support.microsoft.com/help/4531182/kb4531182) and [KB article 4524421](https://support.microsoft.com/help/4524421/kb4524421).
+
+Without these updates, the <see cref="F:System.Web.SameSiteMode.None" /> value does not emit the `SameSite` cookie header. This conforms to [https://tools.ietf.org/html/draft-west-first-party-cookies-07#section-4.1](https://tools.ietf.org/html/draft-west-first-party-cookies-07#section-4.1).
+
+After these updates have been applied, the <see cref="F:System.Web.SameSiteMode.None" /> value emits the `SameSite=None` cookie header. This new behavior conforms to [https://tools.ietf.org/html/draft-west-cookie-incrementalism-00](https://tools.ietf.org/html/draft-west-cookie-incrementalism-00). As part of this change, FormsAuth and SessionState cookies will be issued with SameSite = `Lax` instead of the previous default of `None`, though these values can be overridden in web.config. 
+
+On systems where these updates have been applied, you can specify the previous behavior by setting the `SameSiteMode` to `(SameSiteMode)(-1)`. You can specify this behavior using the string `Unspecified` in web.config.
+]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName="Lax">
@@ -54,7 +67,7 @@
       </ReturnValue>
       <MemberValue>0</MemberValue>
       <Docs>
-        <summary>No mode is specified.</summary>
+        <summary>The cookie will be sent with all requests (see remarks).</summary>
       </Docs>
     </Member>
     <Member MemberName="Strict">
@@ -74,7 +87,7 @@
       </ReturnValue>
       <MemberValue>2</MemberValue>
       <Docs>
-        <summary>When the value is Strict, or if the value is invalid, the cookie will only be sent along with "same-site" requests.</summary>
+        <summary>When the value is Strict the cookie will only be sent along with "same-site" requests.</summary>
       </Docs>
     </Member>
   </Members>
