Skip to content

Commit 38b0dc2

Browse files
authored
Update System.Net.WebHeaderCollection docs (#4642)
1 parent 79896b0 commit 38b0dc2

File tree

2 files changed

+63
-12
lines changed

2 files changed

+63
-12
lines changed

xml/System.Net/HttpListenerResponse.xml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -159,7 +159,7 @@
159159
-or-
160160

161161
<paramref name="name" /> or <paramref name="value" /> contains invalid characters.</exception>
162-
<exception cref="T:System.ArgumentOutOfRangeException">The length of <paramref name="value" /> is greater than 65,535 characters.</exception>
162+
<exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of <paramref name="value" /> is greater than 65,535 characters.</exception>
163163
<altmember cref="T:System.Net.HttpListener" />
164164
<altmember cref="T:System.Net.HttpListenerContext" />
165165
<altmember cref="T:System.Net.HttpListenerRequest" />
@@ -283,7 +283,7 @@
283283
-or-
284284

285285
<paramref name="name" /> or <paramref name="value" /> contains invalid characters.</exception>
286-
<exception cref="T:System.ArgumentOutOfRangeException">The length of <paramref name="value" /> is greater than 65,535 characters.</exception>
286+
<exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of <paramref name="value" /> is greater than 65,535 characters.</exception>
287287
<altmember cref="T:System.Net.HttpListener" />
288288
<altmember cref="T:System.Net.HttpListenerContext" />
289289
<altmember cref="T:System.Net.HttpListenerRequest" />

xml/System.Net/WebHeaderCollection.xml

Lines changed: 61 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -290,6 +290,11 @@
290290
[!code-csharp[WebHeaderCollection_Add#1](~/samples/snippets/csharp/VS_Snippets_Remoting/WebHeaderCollection_Add/CS/webheadercollection_add.cs#1)]
291291
[!code-vb[WebHeaderCollection_Add#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_Add/VB/webheadercollection_add.vb#1)]
292292
293+
> [!NOTE]
294+
> The length of the *value* portion of `header`, that is, the string after the colon (:), is validated only in .NET Framework and .NET Core versions 2.0 - 3.1.
295+
> - On all applicable .NET Framework versions: A <xref:System.Net.WebHeaderCollection> instance that's returned by the <xref:System.Net.HttpListenerResponse.Headers%2A> property will throw an <xref:System.ArgumentOutOfRangeException> if the length of the *value* portion of `header` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a *value* of any length.
296+
> - On .NET Core versions through version 3.1: A <xref:System.Net.WebHeaderCollection> instance used with any header of type <xref:System.Net.HttpResponseHeader> will throw an <xref:System.ArgumentOutOfRangeException> if the length of the *value* portion of `header` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a *value* of any length.
297+
> - On .NET 5.0 and later versions: <xref:System.Net.WebHeaderCollection> accepts a *value* of any length.
293298
]]></format>
294299
</remarks>
295300
<exception cref="T:System.ArgumentNullException">
@@ -310,7 +315,7 @@
310315
-or-
311316

312317
The value part of <paramref name="header" /> contains invalid characters.</exception>
313-
<exception cref="T:System.ArgumentOutOfRangeException">The length the string after the colon (:) is greater than 65535.</exception>
318+
<exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of the string after the colon (:) is greater than 65535.</exception>
314319
</Docs>
315320
</Member>
316321
<Member MemberName="Add">
@@ -364,9 +369,14 @@
364369
365370
If the specified header is already present, `value` is added to the comma-separated list of values associated with the header.
366371
372+
> [!NOTE]
373+
> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1.
374+
> - On all applicable .NET Framework versions: A <xref:System.Net.WebHeaderCollection> instance that's returned by the <xref:System.Net.HttpListenerResponse.Headers%2A> property will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
375+
> - On .NET Core versions through version 3.1: A <xref:System.Net.WebHeaderCollection> instance used with any header of type <xref:System.Net.HttpResponseHeader> will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
376+
> - On .NET 5.0 and later versions: <xref:System.Net.WebHeaderCollection> accepts a `value` of any length.
367377
]]></format>
368378
</remarks>
369-
<exception cref="T:System.ArgumentOutOfRangeException">The length of <paramref name="value" /> is greater than 65535.</exception>
379+
<exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of <paramref name="value" /> is greater than 65535.</exception>
370380
<exception cref="T:System.InvalidOperationException">This <see cref="T:System.Net.WebHeaderCollection" /> instance does not allow instances of <see cref="T:System.Net.HttpRequestHeader" />.</exception>
371381
</Docs>
372382
</Member>
@@ -421,9 +431,14 @@
421431
422432
If the specified header is already present, `value` is added to the comma-separated list of values associated with the header.
423433
434+
> [!NOTE]
435+
> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1.
436+
> - On all applicable .NET Framework versions: A <xref:System.Net.WebHeaderCollection> instance that's returned by the <xref:System.Net.HttpListenerResponse.Headers%2A> property will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
437+
> - On .NET Core versions through version 3.1: A <xref:System.Net.WebHeaderCollection> instance used with any header of type <xref:System.Net.HttpResponseHeader> will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
438+
> - On .NET 5.0 and later versions: <xref:System.Net.WebHeaderCollection> accepts a `value` of any length.
424439
]]></format>
425440
</remarks>
426-
<exception cref="T:System.ArgumentOutOfRangeException">The length of <paramref name="value" /> is greater than 65535.</exception>
441+
<exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of <paramref name="value" /> is greater than 65535.</exception>
427442
<exception cref="T:System.InvalidOperationException">This <see cref="T:System.Net.WebHeaderCollection" /> instance does not allow instances of <see cref="T:System.Net.HttpResponseHeader" />.</exception>
428443
</Docs>
429444
</Member>
@@ -489,6 +504,11 @@
489504
[!code-csharp[WebHeaderCollection_Add#1](~/samples/snippets/csharp/VS_Snippets_Remoting/WebHeaderCollection_Add/CS/webheadercollection_add.cs#1)]
490505
[!code-vb[WebHeaderCollection_Add#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_Add/VB/webheadercollection_add.vb#1)]
491506
507+
> [!NOTE]
508+
> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1.
509+
> - On all applicable .NET Framework versions: A <xref:System.Net.WebHeaderCollection> instance that's returned by the <xref:System.Net.HttpListenerResponse.Headers%2A> property will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
510+
> - On .NET Core versions through version 3.1: A <xref:System.Net.WebHeaderCollection> instance used with any header of type <xref:System.Net.HttpResponseHeader> will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
511+
> - On .NET 5.0 and later versions: <xref:System.Net.WebHeaderCollection> accepts a `value` of any length.
492512
]]></format>
493513
</remarks>
494514
<exception cref="T:System.ArgumentException">
@@ -501,7 +521,7 @@
501521
-or-
502522

503523
<paramref name="value" /> contains invalid characters.</exception>
504-
<exception cref="T:System.ArgumentOutOfRangeException">The length of <paramref name="value" /> is greater than 65535.</exception>
524+
<exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of <paramref name="value" /> is greater than 65535.</exception>
505525
</Docs>
506526
</Member>
507527
<Member MemberName="AddWithoutValidate">
@@ -555,6 +575,11 @@
555575
## Remarks
556576
The <xref:System.Net.WebHeaderCollection.AddWithoutValidate%2A> method adds a header to the collection without checking whether the header is on the restricted header list.
557577
578+
> [!NOTE]
579+
> The length of `headerValue` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1.
580+
> - On all applicable .NET Framework versions: A <xref:System.Net.WebHeaderCollection> instance that's returned by the <xref:System.Net.HttpListenerResponse.Headers%2A> property will throw an <xref:System.ArgumentOutOfRangeException> if the length of `headerValue` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `headerValue` of any length.
581+
> - On .NET Core versions through version 3.1: A <xref:System.Net.WebHeaderCollection> instance used with any header of type <xref:System.Net.HttpResponseHeader> will throw an <xref:System.ArgumentOutOfRangeException> if the length of `headerValue` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `headerValue` of any length.
582+
> - On .NET 5.0 and later versions: <xref:System.Net.WebHeaderCollection> accepts a `headerValue` of any length.
558583
]]></format>
559584
</remarks>
560585
<exception cref="T:System.ArgumentException">
@@ -564,7 +589,7 @@
564589

565590
<paramref name="headerValue" /> contains invalid characters.</exception>
566591
<exception cref="T:System.ArgumentOutOfRangeException">
567-
<paramref name="headerName" /> is not <see langword="null" /> and the length of <paramref name="headerValue" /> is too long (greater than 65,535 characters).</exception>
592+
.NET Framework and .NET Core only: <paramref name="headerName" /> is not <see langword="null" /> and the length of <paramref name="headerValue" /> is too long (greater than 65,535 characters).</exception>
568593
<block subset="none" type="overrides">
569594
<para>Use the <see cref="M:System.Net.WebHeaderCollection.AddWithoutValidate(System.String,System.String)" /> method to add headers that are normally exposed through properties.</para>
570595
</block>
@@ -1453,8 +1478,19 @@
14531478
<param name="header">The response header value.</param>
14541479
<summary>Gets or sets the specified response header.</summary>
14551480
<value>A <see cref="T:System.String" /> instance containing the specified header.</value>
1456-
<remarks>To be added.</remarks>
1457-
<exception cref="T:System.ArgumentOutOfRangeException">The length of <paramref name="value" /> is greater than 65535.</exception>
1481+
<remarks>
1482+
<format type="text/markdown"><![CDATA[
1483+
1484+
## Remarks
1485+
1486+
> [!NOTE]
1487+
> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1.
1488+
> - On all applicable .NET Framework versions: A <xref:System.Net.WebHeaderCollection> instance that's returned by the <xref:System.Net.HttpListenerResponse.Headers%2A> property will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
1489+
> - On .NET Core versions through version 3.1: A <xref:System.Net.WebHeaderCollection> instance used with any header of type <xref:System.Net.HttpResponseHeader> will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
1490+
> - On .NET 5.0 and later versions: <xref:System.Net.WebHeaderCollection> accepts a `value` of any length.
1491+
]]></format>
1492+
</remarks>
1493+
<exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of <paramref name="value" /> is greater than 65535.</exception>
14581494
<exception cref="T:System.InvalidOperationException">This <see cref="T:System.Net.WebHeaderCollection" /> instance does not allow instances of <see cref="T:System.Net.HttpResponseHeader" />.</exception>
14591495
</Docs>
14601496
</Member>
@@ -1837,9 +1873,14 @@
18371873
18381874
If the header specified in `header` is already present, `value` replaces the existing value.
18391875
1876+
> [!NOTE]
1877+
> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1.
1878+
> - On all applicable .NET Framework versions: A <xref:System.Net.WebHeaderCollection> instance that's returned by the <xref:System.Net.HttpListenerResponse.Headers%2A> property will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
1879+
> - On .NET Core versions through version 3.1: A <xref:System.Net.WebHeaderCollection> instance used with any header of type <xref:System.Net.HttpResponseHeader> will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
1880+
> - On .NET 5.0 and later versions: <xref:System.Net.WebHeaderCollection> accepts a `value` of any length.
18401881
]]></format>
18411882
</remarks>
1842-
<exception cref="T:System.ArgumentOutOfRangeException">The length of <paramref name="value" /> is greater than 65535.</exception>
1883+
<exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of <paramref name="value" /> is greater than 65535.</exception>
18431884
<exception cref="T:System.InvalidOperationException">This <see cref="T:System.Net.WebHeaderCollection" /> instance does not allow instances of <see cref="T:System.Net.HttpRequestHeader" />.</exception>
18441885
</Docs>
18451886
</Member>
@@ -1894,9 +1935,14 @@
18941935
18951936
If the header specified in `header` is already present, `value` replaces the existing value.
18961937
1938+
> [!NOTE]
1939+
> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1.
1940+
> - On all applicable .NET Framework versions: A <xref:System.Net.WebHeaderCollection> instance that's returned by the <xref:System.Net.HttpListenerResponse.Headers%2A> property will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
1941+
> - On .NET Core versions through version 3.1: A <xref:System.Net.WebHeaderCollection> instance used with any header of type <xref:System.Net.HttpResponseHeader> will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
1942+
> - On .NET 5.0 and later versions: <xref:System.Net.WebHeaderCollection> accepts a `value` of any length.
18971943
]]></format>
18981944
</remarks>
1899-
<exception cref="T:System.ArgumentOutOfRangeException">The length of <paramref name="value" /> is greater than 65535.</exception>
1945+
<exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of <paramref name="value" /> is greater than 65535.</exception>
19001946
<exception cref="T:System.InvalidOperationException">This <see cref="T:System.Net.WebHeaderCollection" /> instance does not allow instances of <see cref="T:System.Net.HttpResponseHeader" />.</exception>
19011947
</Docs>
19021948
</Member>
@@ -1962,11 +2008,16 @@
19622008
[!code-csharp[WebHeaderCollection_Set#1](~/samples/snippets/csharp/VS_Snippets_Remoting/WebHeaderCollection_Set/CS/webheadercollection_set.cs#1)]
19632009
[!code-vb[WebHeaderCollection_Set#1](~/samples/snippets/visualbasic/VS_Snippets_Remoting/WebHeaderCollection_Set/VB/webheadercollection_set.vb#1)]
19642010
2011+
> [!NOTE]
2012+
> The length of `value` is validated only in .NET Framework and .NET Core versions 2.0 - 3.1.
2013+
> - On all applicable .NET Framework versions: A <xref:System.Net.WebHeaderCollection> instance that's returned by the <xref:System.Net.HttpListenerResponse.Headers%2A> property will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
2014+
> - On .NET Core versions through version 3.1: A <xref:System.Net.WebHeaderCollection> instance used with any header of type <xref:System.Net.HttpResponseHeader> will throw an <xref:System.ArgumentOutOfRangeException> if the length of `value` is greater than 65535. All other <xref:System.Net.WebHeaderCollection> instances accept a `value` of any length.
2015+
> - On .NET 5.0 and later versions: <xref:System.Net.WebHeaderCollection> accepts a `value` of any length.
19652016
]]></format>
19662017
</remarks>
19672018
<exception cref="T:System.ArgumentNullException">
19682019
<paramref name="name" /> is <see langword="null" /> or <see cref="F:System.String.Empty" />.</exception>
1969-
<exception cref="T:System.ArgumentOutOfRangeException">The length of <paramref name="value" /> is greater than 65535.</exception>
2020+
<exception cref="T:System.ArgumentOutOfRangeException">.NET Framework and .NET Core versions 2.0 - 3.1 only: The length of <paramref name="value" /> is greater than 65535.</exception>
19702021
<exception cref="T:System.ArgumentException">
19712022
<paramref name="name" /> is a restricted header.
19722023

0 commit comments

Comments
 (0)