From d26b3974c9d1ab07da801123a1adc308587edafb Mon Sep 17 00:00:00 2001 From: ManickaP <mapichov@microsoft.com> Date: Wed, 8 Jan 2025 16:39:12 +0100 Subject: [PATCH] Moved details from blogpost --- xml/System.Net/ServicePoint.xml | 463 ++++++++++++------------ xml/System.Net/ServicePointManager.xml | 473 +++++++++++++------------ 2 files changed, 493 insertions(+), 443 deletions(-) diff --git a/xml/System.Net/ServicePoint.xml b/xml/System.Net/ServicePoint.xml index 732897b19c8..63619c1a4d5 100644 --- a/xml/System.Net/ServicePoint.xml +++ b/xml/System.Net/ServicePoint.xml @@ -52,31 +52,31 @@ <Docs> <summary>Provides connection management for HTTP connections.</summary> <remarks> - <format type="text/markdown"><] - The <xref:System.Net.ServicePoint> class handles connections to an Internet resource based on the host information passed in the resource's Uniform Resource Identifier (URI). The initial connection to the resource determines the information that the <xref:System.Net.ServicePoint> object maintains, which is then shared by all subsequent requests to that resource. - - <xref:System.Net.ServicePoint> objects are managed by the <xref:System.Net.ServicePointManager> class and are created, if necessary, by the <xref:System.Net.ServicePointManager.FindServicePoint%2A?displayProperty=nameWithType> method. <xref:System.Net.ServicePoint> objects are never created directly but are always created and managed by the <xref:System.Net.ServicePointManager> class. The maximum number of <xref:System.Net.ServicePoint> objects that can be created is set by the <xref:System.Net.ServicePointManager.MaxServicePoints?displayProperty=nameWithType> property. - - Each <xref:System.Net.ServicePoint> object maintains its connection to an Internet resource until it has been idle longer than the time specified in the <xref:System.Net.ServicePoint.MaxIdleTime> property. When a <xref:System.Net.ServicePoint> exceeds the <xref:System.Net.ServicePoint.MaxIdleTime> value, it can be recycled to another connection. The default value of <xref:System.Net.ServicePoint.MaxIdleTime> is set by the <xref:System.Net.ServicePointManager.MaxServicePointIdleTime?displayProperty=nameWithType> property. - - When the <xref:System.Net.ServicePoint.ConnectionLeaseTimeout> property is set to a value other than -1, and after the specified time elapses, an active <xref:System.Net.ServicePoint> connection is closed after it services the next request. This is useful for applications that do not require active connections that are opened indefinitely, as they are by default. - + The <xref:System.Net.ServicePoint> class handles connections to an Internet resource based on the host information passed in the resource's Uniform Resource Identifier (URI). The initial connection to the resource determines the information that the <xref:System.Net.ServicePoint> object maintains, which is then shared by all subsequent requests to that resource. + + <xref:System.Net.ServicePoint> objects are managed by the <xref:System.Net.ServicePointManager> class and are created, if necessary, by the <xref:System.Net.ServicePointManager.FindServicePoint%2A?displayProperty=nameWithType> method. <xref:System.Net.ServicePoint> objects are never created directly but are always created and managed by the <xref:System.Net.ServicePointManager> class. The maximum number of <xref:System.Net.ServicePoint> objects that can be created is set by the <xref:System.Net.ServicePointManager.MaxServicePoints?displayProperty=nameWithType> property. + + Each <xref:System.Net.ServicePoint> object maintains its connection to an Internet resource until it has been idle longer than the time specified in the <xref:System.Net.ServicePoint.MaxIdleTime> property. When a <xref:System.Net.ServicePoint> exceeds the <xref:System.Net.ServicePoint.MaxIdleTime> value, it can be recycled to another connection. The default value of <xref:System.Net.ServicePoint.MaxIdleTime> is set by the <xref:System.Net.ServicePointManager.MaxServicePointIdleTime?displayProperty=nameWithType> property. + + When the <xref:System.Net.ServicePoint.ConnectionLeaseTimeout> property is set to a value other than -1, and after the specified time elapses, an active <xref:System.Net.ServicePoint> connection is closed after it services the next request. This is useful for applications that do not require active connections that are opened indefinitely, as they are by default. + > [!NOTE] > In high load conditions, some applications may run out of free threads in the ThreadPool, which may lead to poor system performance (such as high and variable transaction times). - -## Examples - The following code example creates a <xref:System.Net.ServicePoint> object that connects to the URI `www.contoso.com`. - + +## Examples + The following code example creates a <xref:System.Net.ServicePoint> object that connects to the URI `www.contoso.com`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet1"::: + ]]></format> </remarks> </Docs> @@ -122,15 +122,15 @@ <summary>Gets the Uniform Resource Identifier (URI) of the server that this <see cref="T:System.Net.ServicePoint" /> object connects to.</summary> <value>An instance of the <see cref="T:System.Uri" /> class that contains the URI of the Internet server that this <see cref="T:System.Net.ServicePoint" /> object connects to.</value> <remarks> - <format type="text/markdown"><![CDATA[ - -## Examples - The following code example displays the value of this property. - + <format type="text/markdown"><![CDATA[ + +## Examples + The following code example displays the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet2"::: + ]]></format> </remarks> <exception cref="T:System.NotSupportedException">The <see cref="T:System.Net.ServicePoint" /> is in host mode.</exception> @@ -187,14 +187,17 @@ <summary>Specifies the delegate to associate a local <see cref="T:System.Net.IPEndPoint" /> with a <see cref="T:System.Net.ServicePoint" />.</summary> <value>A delegate that forces a <see cref="T:System.Net.ServicePoint" /> to use a particular local Internet Protocol (IP) address and port number. The default value is <see langword="null" />.</value> <remarks> - <format type="text/markdown"><] - Some load balancing techniques require a client to use a specific local IP address and port number, rather than <xref:System.Net.IPAddress.Any?displayProperty=nameWithType> (or <xref:System.Net.IPAddress.IPv6Any?displayProperty=nameWithType> for Internet Protocol Version 6) and an ephemeral port. Your <xref:System.Net.ServicePoint.BindIPEndPointDelegate> can satisfy this requirement. - + Some load balancing techniques require a client to use a specific local IP address and port number, rather than <xref:System.Net.IPAddress.Any?displayProperty=nameWithType> (or <xref:System.Net.IPAddress.IPv6Any?displayProperty=nameWithType> for Internet Protocol Version 6) and an ephemeral port. Your <xref:System.Net.ServicePoint.BindIPEndPointDelegate> can satisfy this requirement. + +> [!NOTE] +> On modern .NET, <xref:System.Net.HttpWebRequest> uses <xref:System.Net.Http.SocketsHttpHandler.ConnectCallback> to bind the underlying socket to the endpoint from this delegate. + ]]></format> </remarks> </Docs> @@ -247,24 +250,24 @@ <summary>Gets the certificate received for this <see cref="T:System.Net.ServicePoint" /> object.</summary> <value>An instance of the <see cref="T:System.Security.Cryptography.X509Certificates.X509Certificate" /> class that contains the security certificate received for this <see cref="T:System.Net.ServicePoint" /> object.</value> <remarks> - <format type="text/markdown"><] -Although a <xref:System.Net.ServicePoint> object can make multiple connections to an Internet resource, it can maintain only one certificate. +Although a <xref:System.Net.ServicePoint> object can make multiple connections to an Internet resource, it can maintain only one certificate. > [!NOTE] -> In .NET Core and .NET 5+, the <xref:System.Net.ServicePoint.Certificate> property always returns null. To access the server certificate, use <xref:System.Net.Http.HttpClientHandler.ServerCertificateCustomValidationCallback%2A>. +> On modern .NET, returns the remote certificate retrieved via <xref:System.Net.Security.SslClientAuthenticationOptions.RemoteCertificateValidationCallback> on <xref:System.Net.Http.SocketsHttpHandler.SslOptions>. + +## Examples + The following code example displays the value of this property. -## Examples - The following code example displays the value of this property. - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet5"::: + ]]></format> </remarks> </Docs> @@ -317,15 +320,19 @@ Although a <xref:System.Net.ServicePoint> object can make multiple connections t <summary>Gets the last client certificate sent to the server.</summary> <value>An <see cref="T:System.Security.Cryptography.X509Certificates.X509Certificate" /> object that contains the public values of the last client certificate sent to the server.</value> <remarks> - <format type="text/markdown"><![CDATA[ - -## Examples - The following code example displays the value of this property. - + <format type="text/markdown"><![CDATA[ +## Remarks + +> [!NOTE] +> On modern .NET, this property is not implemented. + +## Examples + The following code example displays the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet5"::: + ]]></format> </remarks> </Docs> @@ -374,14 +381,14 @@ Although a <xref:System.Net.ServicePoint> object can make multiple connections t <summary>Removes the specified connection group from this <see cref="T:System.Net.ServicePoint" /> object.</summary> <returns>A <see cref="T:System.Boolean" /> value that indicates whether the connection group was closed.</returns> <remarks> - <format type="text/markdown"><] - Connection groups associate a set of requests with a particular connection or set of connections. This method removes and closes all connections that belong to the specified connection group. - + Connection groups associate a set of requests with a particular connection or set of connections. This method removes and closes all connections that belong to the specified connection group. + ]]></format> </remarks> </Docs> @@ -432,29 +439,32 @@ Although a <xref:System.Net.ServicePoint> object can make multiple connections t <summary>Gets or sets the number of milliseconds after which an active <see cref="T:System.Net.ServicePoint" /> connection is closed.</summary> <value>A <see cref="T:System.Int32" /> that specifies the number of milliseconds that an active <see cref="T:System.Net.ServicePoint" /> connection remains open. The default is -1, which allows an active <see cref="T:System.Net.ServicePoint" /> connection to stay connected indefinitely. Set this property to 0 to force <see cref="T:System.Net.ServicePoint" /> connections to close after servicing a request.</value> <remarks> - <format type="text/markdown"><] - You can use this property to ensure that a <xref:System.Net.ServicePoint> object's active connections do not remain open indefinitely. This property is intended for scenarios where connections should be dropped and reestablished periodically, such as load balancing scenarios. - - By default, when <xref:System.Net.HttpWebRequest.KeepAlive> is `true` for a request, the <xref:System.Net.ServicePoint.MaxIdleTime> property sets the time-out for closing <xref:System.Net.ServicePoint> connections due to inactivity. If the <xref:System.Net.ServicePoint> has active connections, <xref:System.Net.ServicePoint.MaxIdleTime> has no effect and the connections remain open indefinitely. - - When the <xref:System.Net.ServicePoint.ConnectionLeaseTimeout> property is set to a value other than -1, and after the specified time elapses, an active <xref:System.Net.ServicePoint> connection is closed after servicing a request by setting <xref:System.Net.HttpWebRequest.KeepAlive> to `false` in that request. - - Setting this value affects all connections managed by the <xref:System.Net.ServicePoint> object. - - - -## Examples - The following code example sets the value of this property. - + You can use this property to ensure that a <xref:System.Net.ServicePoint> object's active connections do not remain open indefinitely. This property is intended for scenarios where connections should be dropped and reestablished periodically, such as load balancing scenarios. + + By default, when <xref:System.Net.HttpWebRequest.KeepAlive> is `true` for a request, the <xref:System.Net.ServicePoint.MaxIdleTime> property sets the time-out for closing <xref:System.Net.ServicePoint> connections due to inactivity. If the <xref:System.Net.ServicePoint> has active connections, <xref:System.Net.ServicePoint.MaxIdleTime> has no effect and the connections remain open indefinitely. + + When the <xref:System.Net.ServicePoint.ConnectionLeaseTimeout> property is set to a value other than -1, and after the specified time elapses, an active <xref:System.Net.ServicePoint> connection is closed after servicing a request by setting <xref:System.Net.HttpWebRequest.KeepAlive> to `false` in that request. + + Setting this value affects all connections managed by the <xref:System.Net.ServicePoint> object. + + +> [!NOTE] +> On modern .NET, this property maps to <xref:System.Net.Http.SocketsHttpHandler.PooledConnectionLifetime>. However, handlers are not being reused between requests so it doesn't have any meaningful impact. + + +## Examples + The following code example sets the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLServicePoint/CPP/nclservicepoint.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/ServicePoint/ConnectionLeaseTimeout/nclservicepoint.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLServicePoint/VB/nclservicepoint.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLServicePoint/VB/nclservicepoint.vb" id="Snippet1"::: + ]]></format> </remarks> <exception cref="T:System.ArgumentOutOfRangeException">The value specified for a set operation is a negative number less than -1.</exception> @@ -504,23 +514,25 @@ Although a <xref:System.Net.ServicePoint> object can make multiple connections t <summary>Gets or sets the maximum number of connections allowed on this <see cref="T:System.Net.ServicePoint" /> object.</summary> <value>The maximum number of connections allowed on this <see cref="T:System.Net.ServicePoint" /> object.</value> <remarks> - <format type="text/markdown"><] - The <xref:System.Net.ServicePoint.ConnectionLimit> property sets the maximum number of connections that the <xref:System.Net.ServicePoint> object can make to an Internet resource. The value of the <xref:System.Net.ServicePoint.ConnectionLimit> property is set to the value of the <xref:System.Net.ServicePointManager.DefaultConnectionLimit?displayProperty=nameWithType> property when the <xref:System.Net.ServicePoint> object is created; subsequent changes to <xref:System.Net.ServicePointManager.DefaultConnectionLimit> have no effect on existing <xref:System.Net.ServicePoint> objects. - - - -## Examples - The following code example uses the <xref:System.Net.ServicePoint.ConnectionLimit> property to check the maximum number of connections that the <xref:System.Net.ServicePoint> object can make to the specified Uniform Resource Identifier (URI). - + The <xref:System.Net.ServicePoint.ConnectionLimit> property sets the maximum number of connections that the <xref:System.Net.ServicePoint> object can make to an Internet resource. The value of the <xref:System.Net.ServicePoint.ConnectionLimit> property is set to the value of the <xref:System.Net.ServicePointManager.DefaultConnectionLimit?displayProperty=nameWithType> property when the <xref:System.Net.ServicePoint> object is created; subsequent changes to <xref:System.Net.ServicePointManager.DefaultConnectionLimit> have no effect on existing <xref:System.Net.ServicePoint> objects. + +> [!NOTE] +> On modern .NET, this property maps to <xref:System.Net.Http.SocketsHttpHandler.MaxConnectionsPerServer>. However, handlers are not being reused between requests so it doesn't have any meaningful impact. + + +## Examples + The following code example uses the <xref:System.Net.ServicePoint.ConnectionLimit> property to check the maximum number of connections that the <xref:System.Net.ServicePoint> object can make to the specified Uniform Resource Identifier (URI). + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet4"::: + ]]></format> </remarks> <exception cref="T:System.ArgumentOutOfRangeException">The connection limit is equal to or less than 0.</exception> @@ -574,23 +586,23 @@ Although a <xref:System.Net.ServicePoint> object can make multiple connections t <summary>Gets the connection name.</summary> <value>A <see cref="T:System.String" /> that represents the connection name.</value> <remarks> - <format type="text/markdown"><] - If the <xref:System.Net.ServicePoint> object was constructed by calling a <xref:System.Net.ServicePointManager.FindServicePoint%2A> overload with a <xref:System.Uri> argument, then the <xref:System.Net.ServicePoint.ConnectionName> property represents the <xref:System.Uri.Scheme> property of the <xref:System.Uri> object used. - - If the <xref:System.Net.ServicePoint> object was constructed from a network host and port, the <xref:System.Net.ServicePoint.ConnectionName> property contains a string that represents the host and the network port. If the <xref:System.Net.ServicePoint.ConnectionName> property is set when constructed from a host and port, only <xref:System.Net.WebRequest> objects with the same <xref:System.Net.WebRequest.ConnectionGroupName> value can use this <xref:System.Net.ServicePoint> object. - - - -## Examples + If the <xref:System.Net.ServicePoint> object was constructed by calling a <xref:System.Net.ServicePointManager.FindServicePoint%2A> overload with a <xref:System.Uri> argument, then the <xref:System.Net.ServicePoint.ConnectionName> property represents the <xref:System.Uri.Scheme> property of the <xref:System.Uri> object used. + + If the <xref:System.Net.ServicePoint> object was constructed from a network host and port, the <xref:System.Net.ServicePoint.ConnectionName> property contains a string that represents the host and the network port. If the <xref:System.Net.ServicePoint.ConnectionName> property is set when constructed from a host and port, only <xref:System.Net.WebRequest> objects with the same <xref:System.Net.WebRequest.ConnectionGroupName> value can use this <xref:System.Net.ServicePoint> object. + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet4"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet4"::: + ]]></format> </remarks> <related type="Article" href="/dotnet/framework/network-programming/connection-grouping">Connection Grouping</related> @@ -637,22 +649,24 @@ Although a <xref:System.Net.ServicePoint> object can make multiple connections t <summary>Gets the number of open connections associated with this <see cref="T:System.Net.ServicePoint" /> object.</summary> <value>The number of open connections associated with this <see cref="T:System.Net.ServicePoint" /> object.</value> <remarks> - <format type="text/markdown"><] - The <xref:System.Net.ServicePoint.CurrentConnections> property contains the number of open Internet connections associated with this <xref:System.Net.ServicePoint> object. The value of <xref:System.Net.ServicePoint.CurrentConnections> cannot exceed that of <xref:System.Net.ServicePoint.ConnectionLimit>. - - -## Examples - The following code example uses the <xref:System.Net.ServicePoint.CurrentConnections> property to determine the number of open Internet connections associated with this <xref:System.Net.ServicePoint> object. - + The <xref:System.Net.ServicePoint.CurrentConnections> property contains the number of open Internet connections associated with this <xref:System.Net.ServicePoint> object. The value of <xref:System.Net.ServicePoint.CurrentConnections> cannot exceed that of <xref:System.Net.ServicePoint.ConnectionLimit>. + +> [!NOTE] +> On modern .NET, this property is not implemented. + +## Examples + The following code example uses the <xref:System.Net.ServicePoint.CurrentConnections> property to determine the number of open Internet connections associated with this <xref:System.Net.ServicePoint> object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet2"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet2"::: + ]]></format> </remarks> </Docs> @@ -709,31 +723,32 @@ Although a <xref:System.Net.ServicePoint> object can make multiple connections t <value> <see langword="true" /> to expect 100-Continue responses for <see langword="POST" /> requests; otherwise, <see langword="false" />. The default value is <see langword="true" />.</value> <remarks> - <format type="text/markdown"><] - When this property is set to `true`, client requests that use the `POST` method expect to receive a 100-Continue response from the server to indicate that the client should send the data to be posted. This mechanism allows clients to avoid sending large amounts of data over the network when the server, based on the request headers, intends to reject the request. - - For example, assume the <xref:System.Net.ServicePoint.Expect100Continue> property is `false`. When the request is sent to the server, it includes the data. If, after reading the request headers, the server requires authentication and sends a 401 response, the client must resend the data with proper authentication headers. - - If the <xref:System.Net.ServicePoint.Expect100Continue> property is `true`, the request headers are sent to the server. If the server has not rejected the request, it sends a 100-Continue response signaling that the data can be transmitted. If, as in the preceding example, the server requires authentication, it sends the 401 response and the client has not unnecessarily transmitted the data. - - Changing the value of this property does not affect existing connections. Only new connections created after the change are affected. - - The Expect 100-Continue behavior is fully described in IETF RFC 2616 Section 10.1.1. - - - -## Examples - The following code example displays the value of this property. - + When this property is set to `true`, client requests that use the `POST` method expect to receive a 100-Continue response from the server to indicate that the client should send the data to be posted. This mechanism allows clients to avoid sending large amounts of data over the network when the server, based on the request headers, intends to reject the request. + + For example, assume the <xref:System.Net.ServicePoint.Expect100Continue> property is `false`. When the request is sent to the server, it includes the data. If, after reading the request headers, the server requires authentication and sends a 401 response, the client must resend the data with proper authentication headers. + + If the <xref:System.Net.ServicePoint.Expect100Continue> property is `true`, the request headers are sent to the server. If the server has not rejected the request, it sends a 100-Continue response signaling that the data can be transmitted. If, as in the preceding example, the server requires authentication, it sends the 401 response and the client has not unnecessarily transmitted the data. + + Changing the value of this property does not affect existing connections. Only new connections created after the change are affected. + + The Expect 100-Continue behavior is fully described in IETF RFC 2616 Section 10.1.1. + +> [!NOTE] +> On modern .NET, this property sets <xref:System.Net.Http.Headers.HttpRequestHeaders.ExpectContinue> on the <xref:System.Net.Http.HttpRequestMessage>. + +## Examples + The following code example displays the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet9"::: + ]]></format> </remarks> </Docs> @@ -769,7 +784,7 @@ Although a <xref:System.Net.ServicePoint> object can make multiple connections t <remarks> <format type="text/markdown"><] @@ -826,22 +841,22 @@ The `GetHashCode` method returns a hash code of this instance. This value can be <summary>Gets the date and time that the <see cref="T:System.Net.ServicePoint" /> object was last connected to a host.</summary> <value>A <see cref="T:System.DateTime" /> object that contains the date and time at which the <see cref="T:System.Net.ServicePoint" /> object was last connected.</value> <remarks> - <format type="text/markdown"><] - The <xref:System.Net.ServicePoint.IdleSince> property records the last date and time at which a service point was disconnected from a host. When the difference between the current time and <xref:System.Net.ServicePoint.IdleSince> exceeds the value of <xref:System.Net.ServicePoint.MaxIdleTime>, the <xref:System.Net.ServicePoint> object is available for recycling to another connection. - - -## Examples - The following code example uses the <xref:System.Net.ServicePoint.IdleSince> property to set and retrieve the date and time that the <xref:System.Net.ServicePoint> object was last connected to a host. - + The <xref:System.Net.ServicePoint.IdleSince> property records the last date and time at which a service point was disconnected from a host. When the difference between the current time and <xref:System.Net.ServicePoint.IdleSince> exceeds the value of <xref:System.Net.ServicePoint.MaxIdleTime>, the <xref:System.Net.ServicePoint> object is available for recycling to another connection. + + +## Examples + The following code example uses the <xref:System.Net.ServicePoint.IdleSince> property to set and retrieve the date and time that the <xref:System.Net.ServicePoint> object was last connected to a host. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet3"::: + ]]></format> </remarks> </Docs> @@ -887,27 +902,28 @@ The `GetHashCode` method returns a hash code of this instance. This value can be <summary>Gets or sets the amount of time a connection associated with the <see cref="T:System.Net.ServicePoint" /> object can remain idle before the connection is closed.</summary> <value>The length of time, in milliseconds, that a connection associated with the <see cref="T:System.Net.ServicePoint" /> object can remain idle before it is closed and reused for another connection.</value> <remarks> - <format type="text/markdown"><] - You can set <xref:System.Net.ServicePoint.MaxIdleTime> to <xref:System.Threading.Timeout.Infinite?displayProperty=nameWithType> to indicate that a connection associated with the <xref:System.Net.ServicePoint> object should never time out. - - The default value of the <xref:System.Net.ServicePoint.MaxIdleTime> property is the value of the <xref:System.Net.ServicePointManager.MaxServicePointIdleTime?displayProperty=nameWithType> property when the <xref:System.Net.ServicePoint> object is created. Subsequent changes to the <xref:System.Net.ServicePointManager.MaxServicePointIdleTime> property have no effect on existing <xref:System.Net.ServicePoint> objects. - - When the <xref:System.Net.ServicePoint.MaxIdleTime> for a connection associated with a <xref:System.Net.ServicePoint> is exceeded, the connection remains open until the application tries to use the connection. At that time, the Framework closes the connection and creates a new connection to the remote host. - - - -## Examples - The following code example uses the <xref:System.Net.ServicePoint.MaxIdleTime> property to set and retrieve the <xref:System.Net.ServicePoint> idle time. - + You can set <xref:System.Net.ServicePoint.MaxIdleTime> to <xref:System.Threading.Timeout.Infinite?displayProperty=nameWithType> to indicate that a connection associated with the <xref:System.Net.ServicePoint> object should never time out. + + The default value of the <xref:System.Net.ServicePoint.MaxIdleTime> property is the value of the <xref:System.Net.ServicePointManager.MaxServicePointIdleTime?displayProperty=nameWithType> property when the <xref:System.Net.ServicePoint> object is created. Subsequent changes to the <xref:System.Net.ServicePointManager.MaxServicePointIdleTime> property have no effect on existing <xref:System.Net.ServicePoint> objects. + + When the <xref:System.Net.ServicePoint.MaxIdleTime> for a connection associated with a <xref:System.Net.ServicePoint> is exceeded, the connection remains open until the application tries to use the connection. At that time, the Framework closes the connection and creates a new connection to the remote host. + +> [!NOTE] +> On modern .NET, this property maps to <xref:System.Net.Http.SocketsHttpHandler.PooledConnectionIdleTimeout>. However, handlers are not being reused between requests so it doesn't have any meaningful impact. + +## Examples + The following code example uses the <xref:System.Net.ServicePoint.MaxIdleTime> property to set and retrieve the <xref:System.Net.ServicePoint> idle time. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet3"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet3"::: + ]]></format> </remarks> <exception cref="T:System.ArgumentOutOfRangeException"> @@ -955,22 +971,24 @@ The `GetHashCode` method returns a hash code of this instance. This value can be <summary>Gets the version of the HTTP protocol that the <see cref="T:System.Net.ServicePoint" /> object uses.</summary> <value>A <see cref="T:System.Version" /> object that contains the HTTP protocol version that the <see cref="T:System.Net.ServicePoint" /> object uses.</value> <remarks> - <format type="text/markdown"><] - The HTTP protocol versions are HTTP/1.0 and HTTP/1.1. - - -## Examples - The following code example displays the value of this property. - + The HTTP protocol versions are HTTP/1.0 and HTTP/1.1. + +> [!NOTE] +> On modern .NET, this property returns <xref:System.Net.HttpWebRequest.ProtocolVersion>. + +## Examples + The following code example displays the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet5"::: + ]]></format> </remarks> </Docs> @@ -1021,22 +1039,24 @@ The `GetHashCode` method returns a hash code of this instance. This value can be <summary>Gets or sets the size of the receiving buffer for the socket used by this <see cref="T:System.Net.ServicePoint" />.</summary> <value>A <see cref="T:System.Int32" /> that contains the size, in bytes, of the receive buffer. The default is 8192.</value> <remarks> - <format type="text/markdown"><] - For additional information, see <xref:System.Net.Sockets.Socket.ReceiveBufferSize>. - - -## Examples - The following code example sets the value of this property. - + For additional information, see <xref:System.Net.Sockets.Socket.ReceiveBufferSize>. + +> [!NOTE] +> On modern .NET, <xref:System.Net.HttpWebRequest> uses <xref:System.Net.Http.SocketsHttpHandler.ConnectCallback> to set <xref:System.Net.Sockets.Socket.ReceiveBufferSize> to the value of this property. + +## Examples + The following code example sets the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/NCLServicePoint/CPP/nclservicepoint.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/ServicePoint/ConnectionLeaseTimeout/nclservicepoint.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLServicePoint/VB/nclservicepoint.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/NCLServicePoint/VB/nclservicepoint.vb" id="Snippet1"::: + ]]></format> </remarks> <exception cref="T:System.ArgumentOutOfRangeException">The value specified for a set operation is greater than <see cref="F:System.Int32.MaxValue">Int32.MaxValue</see>.</exception> @@ -1084,31 +1104,34 @@ The `GetHashCode` method returns a hash code of this instance. This value can be <Parameter Name="keepAliveInterval" Type="System.Int32" Index="2" FrameworkAlternate="net-5.0;net-6.0;net-7.0;net-8.0;net-9.0;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1;netstandard-2.0;netstandard-2.1" /> </Parameters> <Docs> - <param name="enabled">If set to true, then the TCP keep-alive option on a TCP connection will be enabled using the specified <paramref name="keepAliveTime" /> and <paramref name="keepAliveInterval" /> values. - - If set to false, then the TCP keep-alive option is disabled and the remaining parameters are ignored. - + <param name="enabled">If set to true, then the TCP keep-alive option on a TCP connection will be enabled using the specified <paramref name="keepAliveTime" /> and <paramref name="keepAliveInterval" /> values. + + If set to false, then the TCP keep-alive option is disabled and the remaining parameters are ignored. + The default value is false.</param> - <param name="keepAliveTime">Specifies the timeout, in milliseconds, with no activity until the first keep-alive packet is sent. - + <param name="keepAliveTime">Specifies the timeout, in milliseconds, with no activity until the first keep-alive packet is sent. + The value must be greater than 0. If a value of less than or equal to zero is passed an <see cref="T:System.ArgumentOutOfRangeException" /> is thrown.</param> - <param name="keepAliveInterval">Specifies the interval, in milliseconds, between when successive keep-alive packets are sent if no acknowledgement is received. - + <param name="keepAliveInterval">Specifies the interval, in milliseconds, between when successive keep-alive packets are sent if no acknowledgement is received. + The value must be greater than 0. If a value of less than or equal to zero is passed an <see cref="T:System.ArgumentOutOfRangeException" /> is thrown.</param> <summary>Enables or disables the keep-alive option on a TCP connection.</summary> <remarks> - <format type="text/markdown"><] - An application can request that a TCP/IP provider enable the use of keep-alive packets on a TCP connection. The default is that the use of keep-alive packets on a TCP connection is disabled. - - The default settings when a TCP socket is initialized sets the keep-alive timeout to 2 hours and the keep-alive interval to 1 second. The `keepAliveTime` parameter specifies the timeout, in milliseconds, with no activity until the first keep-alive packet is sent. The `keepAliveInterval` parameter specifies the interval, in milliseconds, between when successive keep-alive packets are sent if no acknowledgement is received. The number of keep-alive probes cannot be changed and is set to 10. - - If a TCP connection is dropped as the result of keep-alives, a <xref:System.Net.Sockets.SocketError> of <xref:System.Net.Sockets.SocketError.NetworkReset> is returned to any calls in progress on the socket, and any subsequent calls will fail with a <xref:System.Net.Sockets.SocketError> of <xref:System.Net.Sockets.SocketError.NotConnected>. - + An application can request that a TCP/IP provider enable the use of keep-alive packets on a TCP connection. The default is that the use of keep-alive packets on a TCP connection is disabled. + + The default settings when a TCP socket is initialized sets the keep-alive timeout to 2 hours and the keep-alive interval to 1 second. The `keepAliveTime` parameter specifies the timeout, in milliseconds, with no activity until the first keep-alive packet is sent. The `keepAliveInterval` parameter specifies the interval, in milliseconds, between when successive keep-alive packets are sent if no acknowledgement is received. The number of keep-alive probes cannot be changed and is set to 10. + + If a TCP connection is dropped as the result of keep-alives, a <xref:System.Net.Sockets.SocketError> of <xref:System.Net.Sockets.SocketError.NetworkReset> is returned to any calls in progress on the socket, and any subsequent calls will fail with a <xref:System.Net.Sockets.SocketError> of <xref:System.Net.Sockets.SocketError.NotConnected>. + +> [!NOTE] +> On modern .NET, <xref:System.Net.HttpWebRequest> uses <xref:System.Net.Http.SocketsHttpHandler.ConnectCallback> to set TCP keep alive options on the underlying socket to the values provided to this method. + ]]></format> </remarks> <exception cref="T:System.ArgumentOutOfRangeException">The value specified for <paramref name="keepAliveTime" /> or <paramref name="keepAliveInterval" /> parameter is less than or equal to 0.</exception> @@ -1156,25 +1179,26 @@ The `GetHashCode` method returns a hash code of this instance. This value can be <value> <see langword="true" /> if the <see cref="T:System.Net.ServicePoint" /> object supports pipelined connections; otherwise, <see langword="false" />.</value> <remarks> - <format type="text/markdown"><] - Pipelining allows clients to send multiple requests across a persistent connection without waiting for each response from the server. The server sends the responses in the same order as the requests were received. - - Pipelining is described in detail in IETF RFC 2616 section 8.1.2.2. - - - -## Examples - The following code example displays the value of this property. - + Pipelining allows clients to send multiple requests across a persistent connection without waiting for each response from the server. The server sends the responses in the same order as the requests were received. + + Pipelining is described in detail in IETF RFC 2616 section 8.1.2.2. + +> [!NOTE] +> On modern .NET, this property is not implemented. + +## Examples + The following code example displays the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet5"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet5"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet5"::: + ]]></format> </remarks> </Docs> @@ -1231,27 +1255,28 @@ The `GetHashCode` method returns a hash code of this instance. This value can be <value> <see langword="true" /> to use the Nagle algorithm; otherwise, <see langword="false" />. The default value is <see langword="true" />.</value> <remarks> - <format type="text/markdown"><] - The Nagle algorithm is used to buffer small packets of data and transmit them as a single packet. This process, referred to as "nagling," is widely used because it reduces the number of packets transmitted and lowers the overhead per packet. - - Changing the value of this property does not affect existing connections. Only new connections created after the change are affected. - - The Nagle algorithm is fully described in IETF RFC 896. - - - -## Examples - The following code example displays the value of this property. - + The Nagle algorithm is used to buffer small packets of data and transmit them as a single packet. This process, referred to as "nagling," is widely used because it reduces the number of packets transmitted and lowers the overhead per packet. + + Changing the value of this property does not affect existing connections. Only new connections created after the change are affected. + + The Nagle algorithm is fully described in IETF RFC 896. + +> [!NOTE] +> On modern .NET, <xref:System.Net.HttpWebRequest> uses <xref:System.Net.Http.SocketsHttpHandler.ConnectCallback> to set <xref:System.Net.Sockets.Socket.NoDelay> to the opposite value than this property. + +## Examples + The following code example displays the value of this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet9"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet9"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet9"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet9"::: + ]]></format> </remarks> </Docs> diff --git a/xml/System.Net/ServicePointManager.xml b/xml/System.Net/ServicePointManager.xml index b50b2a6133f..83e54548277 100644 --- a/xml/System.Net/ServicePointManager.xml +++ b/xml/System.Net/ServicePointManager.xml @@ -56,27 +56,27 @@ <Docs> <summary>Manages the collection of <see cref="T:System.Net.ServicePoint" /> objects.</summary> <remarks> - <format type="text/markdown">< explains how to modify your code so that the new behavior is disabled. - + <format type="text/markdown">< explains how to modify your code so that the new behavior is disabled. + > [!IMPORTANT] -> We don't recommend that you use the `ServicePointManager` class for new development. Instead, use the <xref:System.Net.Http.HttpClient?displayProperty=nameWithType> class. - -## Examples - The following code example creates a <xref:System.Net.ServicePoint> object for connections to the URI `www.contoso.com`. - +> We don't recommend that you use the `ServicePointManager` class for new development. Instead, use the <xref:System.Net.Http.HttpClient?displayProperty=nameWithType> class. + +## Examples + The following code example creates a <xref:System.Net.ServicePoint> object for connections to the URI `www.contoso.com`. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic ServicePoint Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/ServicePointManager/Overview/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic ServicePoint Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic ServicePoint Example/VB/source.vb" id="Snippet1"::: + ]]></format> </remarks> <altmember cref="T:System.Net.ServicePoint" /> @@ -123,22 +123,21 @@ <summary>Gets or sets policy for server certificates.</summary> <value>An object that implements the <see cref="T:System.Net.ICertificatePolicy" /> interface.</value> <remarks> - <format type="text/markdown"><![CDATA[ - -## Remarks - When the <xref:System.Net.ServicePointManager.CertificatePolicy%2A> property is set to an <xref:System.Net.ICertificatePolicy> interface object, the <xref:System.Net.ServicePointManager> object uses the certificate policy defined in that instance instead of the default certificate policy. - - The default certificate policy allows valid certificates and valid certificates that have expired. - - - -## Examples - The following code example shows how to catch a certificate policy exception for a custom certificate policy. It assumes that the certificate policy object has been defined, that the Uniform Resource Identifier (URI) for the Web resource is contained in the variable `myUri`, and that there is a method named `ProcessResponse` that performs the work of the application. - + <format type="text/markdown"><![CDATA[ + +## Remarks + When the <xref:System.Net.ServicePointManager.CertificatePolicy%2A> property is set to an <xref:System.Net.ICertificatePolicy> interface object, the <xref:System.Net.ServicePointManager> object uses the certificate policy defined in that instance instead of the default certificate policy. + + The default certificate policy allows valid certificates and valid certificates that have expired. + + +## Examples + The following code example shows how to catch a certificate policy exception for a custom certificate policy. It assumes that the certificate policy object has been defined, that the Uniform Resource Identifier (URI) for the Web resource is contained in the variable `myUri`, and that there is a method named `ProcessResponse` that performs the work of the application. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/Classic ServicePointManager.CertificatePolicy Example/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/ServicePointManager/CertificatePolicy/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic ServicePointManager.CertificatePolicy Example/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/Classic ServicePointManager.CertificatePolicy Example/VB/source.vb" id="Snippet1"::: + ]]></format> </remarks> <altmember cref="T:System.Net.ServicePoint" /> @@ -187,20 +186,21 @@ <value> <see langword="true" /> if the certificate revocation list is checked; otherwise, <see langword="false" />.</value> <remarks> - <format type="text/markdown"><![CDATA[ - -## Remarks - When the <xref:System.Net.ServicePointManager.CheckCertificateRevocationList%2A> is `true`, the certificate is checked against the certificate authority revocation list, as part of the certificate validation process. Its default value is `false`. - - - -## Examples - The following code example sets this property. - + <format type="text/markdown"><![CDATA[ + +## Remarks + When the <xref:System.Net.ServicePointManager.CheckCertificateRevocationList%2A> is `true`, the certificate is checked against the certificate authority revocation list, as part of the certificate validation process. Its default value is `false`. + +> [!NOTE] +> On modern .NET, this property maps to <xref:System.Net.Security.SslClientAuthenticationOptions.CertificateRevocationCheckMode> on <xref:System.Net.Http.SocketsHttpHandler.SslOptions>. + +## Examples + The following code example sets this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet10"::: + ]]></format> </remarks> <altmember cref="T:System.Net.ServicePoint" /> @@ -254,25 +254,26 @@ <summary>Gets or sets the maximum number of concurrent connections allowed by a <see cref="T:System.Net.ServicePoint" /> object.</summary> <value>The maximum number of concurrent connections allowed by a <see cref="T:System.Net.ServicePoint" /> object. The default connection limit is 10 for ASP.NET hosted applications and 2 for all others. When an app is running as an ASP.NET host, it is not possible to alter the value of this property through the config file if the autoConfig property is set to <see langword="true" />. However, you can change the value programmatically when the autoConfig property is <see langword="true" />. Set your preferred value once, when the AppDomain loads.</value> <remarks> - <format type="text/markdown"><![CDATA[ - -## Remarks - The <xref:System.Net.ServicePointManager.DefaultConnectionLimit%2A> property sets the default maximum number of concurrent connections that the <xref:System.Net.ServicePointManager> object assigns to the <xref:System.Net.ServicePoint.ConnectionLimit%2A> property when creating <xref:System.Net.ServicePoint> objects. - - Changing the <xref:System.Net.ServicePointManager.DefaultConnectionLimit%2A> property has no effect on existing <xref:System.Net.ServicePoint> objects; it affects only <xref:System.Net.ServicePoint> objects that are initialized after the change. If the value of this property has not been set either directly or through configuration, the value defaults to the constant <xref:System.Net.ServicePointManager.DefaultPersistentConnectionLimit>. - + <format type="text/markdown"><![CDATA[ + +## Remarks + The <xref:System.Net.ServicePointManager.DefaultConnectionLimit%2A> property sets the default maximum number of concurrent connections that the <xref:System.Net.ServicePointManager> object assigns to the <xref:System.Net.ServicePoint.ConnectionLimit%2A> property when creating <xref:System.Net.ServicePoint> objects. + + Changing the <xref:System.Net.ServicePointManager.DefaultConnectionLimit%2A> property has no effect on existing <xref:System.Net.ServicePoint> objects; it affects only <xref:System.Net.ServicePoint> objects that are initialized after the change. If the value of this property has not been set either directly or through configuration, the value defaults to the constant <xref:System.Net.ServicePointManager.DefaultPersistentConnectionLimit>. + > [!NOTE] > Any changes to the <xref:System.Net.ServicePointManager.DefaultConnectionLimit%2A> property affect both HTTP 1.0 and HTTP 1.1 connections. It is not possible to separately alter the connection limit for HTTP 1.0 and HTTP 1.1 protocols. - - - -## Examples - The following code example sets this property. - + +> [!NOTE] +> On modern .NET, this property maps to <xref:System.Net.Http.SocketsHttpHandler.MaxConnectionsPerServer> unless overridden by <xref:System.Net.ServicePoint.ConnectionLimit>. However, handlers are not being reused between requests so it doesn't have any meaningful impact. + +## Examples + The following code example sets this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet10"::: + ]]></format> </remarks> <exception cref="T:System.ArgumentOutOfRangeException"> @@ -365,15 +366,15 @@ <Docs> <summary>The default number of persistent connections (2) allowed on a <see cref="T:System.Net.ServicePoint" /> object connected to an HTTP/1.1 or later server. This field is constant and is used to initialize the <see cref="P:System.Net.ServicePointManager.DefaultConnectionLimit" /> property if the value of the <see cref="P:System.Net.ServicePointManager.DefaultConnectionLimit" /> property has not been set either directly or through configuration.</summary> <remarks> - <format type="text/markdown"><![CDATA[ - -## Examples - The following code example sets the <xref:System.Net.ServicePointManager.DefaultConnectionLimit%2A> property using this field. - + <format type="text/markdown"><![CDATA[ + +## Examples + The following code example sets the <xref:System.Net.ServicePointManager.DefaultConnectionLimit%2A> property using this field. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet10"::: + ]]></format> </remarks> </Docs> @@ -418,15 +419,19 @@ <summary>Gets or sets a value that indicates how long a Domain Name Service (DNS) resolution is considered valid.</summary> <value>The time-out value, in milliseconds. A value of -1 indicates an infinite time-out period. The default value is 120,000 milliseconds (two minutes).</value> <remarks> - <format type="text/markdown"><![CDATA[ - -## Examples - The following code example sets this property. - + <format type="text/markdown"><![CDATA[ +## Remarks + +> [!NOTE] +> On modern .NET, this property is not implemented. + +## Examples + The following code example sets this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePointWhidbey/cpp/servicepoint.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/ServicePointManager/DnsRefreshTimeout/servicepoint.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePointWhidbey/VB/servicepoint.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePointWhidbey/VB/servicepoint.vb" id="Snippet1"::: + ]]></format> </remarks> <altmember cref="T:System.Net.ServicePoint" /> @@ -473,20 +478,21 @@ <value> <see langword="false" /> if a DNS resolution always returns the first IP address for a particular host; otherwise <see langword="true" />. The default is <see langword="false" />.</value> <remarks> - <format type="text/markdown"><![CDATA[ - -## Remarks - When more than one IP address is associated with a host name, a DNS resolution normally returns only the first IP address. If you set this property to `true`, then subsequent DNS resolutions will cycle through all available IP addresses for a particular host. This option is useful when a service uses DNS as a load balancing mechanism between servers or server clusters. - - - -## Examples - The following code example sets this property. - + <format type="text/markdown"><![CDATA[ + +## Remarks + When more than one IP address is associated with a host name, a DNS resolution normally returns only the first IP address. If you set this property to `true`, then subsequent DNS resolutions will cycle through all available IP addresses for a particular host. This option is useful when a service uses DNS as a load balancing mechanism between servers or server clusters. + +> [!NOTE] +> On modern .NET, this property is not implemented. + +## Examples + The following code example sets this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePointWhidbey/cpp/servicepoint.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Net/ServicePointManager/DnsRefreshTimeout/servicepoint.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePointWhidbey/VB/servicepoint.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePointWhidbey/VB/servicepoint.vb" id="Snippet1"::: + ]]></format> </remarks> <altmember cref="T:System.Net.ServicePoint" /> @@ -537,13 +543,16 @@ <summary>Gets the <see cref="T:System.Net.Security.EncryptionPolicy" /> for this <see cref="T:System.Net.ServicePointManager" /> instance.</summary> <value>The encryption policy to use for this <see cref="T:System.Net.ServicePointManager" /> instance.</value> <remarks> - <format type="text/markdown"><![CDATA[ - -## Remarks - If a value is not specified in the configuration file, the <xref:System.Net.ServicePointManager.EncryptionPolicy%2A> property defaults to <xref:System.Net.Security.EncryptionPolicy.RequireEncryption?displayProperty=nameWithType>. This is applied to an SSL/TLS session on this <xref:System.Net.ServicePointManager> instance. - - The use of the Null cipher is required when the encryption policy is set to <xref:System.Net.Security.EncryptionPolicy.NoEncryption?displayProperty=nameWithType>. - + <format type="text/markdown"><![CDATA[ + +## Remarks + If a value is not specified in the configuration file, the <xref:System.Net.ServicePointManager.EncryptionPolicy%2A> property defaults to <xref:System.Net.Security.EncryptionPolicy.RequireEncryption?displayProperty=nameWithType>. This is applied to an SSL/TLS session on this <xref:System.Net.ServicePointManager> instance. + + The use of the Null cipher is required when the encryption policy is set to <xref:System.Net.Security.EncryptionPolicy.NoEncryption?displayProperty=nameWithType>. + +> [!NOTE] +> On modern .NET, this property is not implemented. + ]]></format> </remarks> <altmember cref="T:System.Net.ServicePoint" /> @@ -594,30 +603,31 @@ <value> <see langword="true" /> to enable 100-Continue behavior. The default value is <see langword="true" />.</value> <remarks> - <format type="text/markdown"><![CDATA[ - -## Remarks - When this property is set to `true`, 100-Continue behavior is used. Client requests that use the `PUT` and `POST` methods will add an Expect header to the request if the <xref:System.Net.ServicePointManager.Expect100Continue%2A> property is `true` and <xref:System.Net.HttpWebRequest.ContentLength%2A> property is greater than zero or the <xref:System.Net.HttpWebRequest.SendChunked%2A> property is true. The client will expect to receive a 100-Continue response from the server to indicate that the client should send the data to be posted. This mechanism allows clients to avoid sending large amounts of data over the network when the server, based on the request headers, intends to reject the request. - - For example, assume the <xref:System.Net.ServicePointManager.Expect100Continue%2A> property is `false`. When the request is sent to the server, it includes the data. If, after reading the request headers, the server requires authentication and must send a 401 response, the client must resend the data with proper authentication headers. - - If this property is `true`, the request headers are sent to the server. If the server has not rejected the request, it sends a 100-Continue response signaling that the data can be transmitted. If, as in the preceding example, the server requires authentication, it sends the 401 response and the client has not unnecessarily transmitted the data. - - Changing the value of this property does not affect existing <xref:System.Net.ServicePoint> objects. Only new <xref:System.Net.ServicePoint> objects created after the change are affected. - - The 100-Continue behavior is not used for HTTP 1.0 requests even if this property is set to `true`. - - The Expect 100-Continue behavior is fully described in IETF RFC 2616 Section 10.1.1. - - - -## Examples - The following code example sets this property. - + <format type="text/markdown"><![CDATA[ + +## Remarks + When this property is set to `true`, 100-Continue behavior is used. Client requests that use the `PUT` and `POST` methods will add an Expect header to the request if the <xref:System.Net.ServicePointManager.Expect100Continue%2A> property is `true` and <xref:System.Net.HttpWebRequest.ContentLength%2A> property is greater than zero or the <xref:System.Net.HttpWebRequest.SendChunked%2A> property is true. The client will expect to receive a 100-Continue response from the server to indicate that the client should send the data to be posted. This mechanism allows clients to avoid sending large amounts of data over the network when the server, based on the request headers, intends to reject the request. + + For example, assume the <xref:System.Net.ServicePointManager.Expect100Continue%2A> property is `false`. When the request is sent to the server, it includes the data. If, after reading the request headers, the server requires authentication and must send a 401 response, the client must resend the data with proper authentication headers. + + If this property is `true`, the request headers are sent to the server. If the server has not rejected the request, it sends a 100-Continue response signaling that the data can be transmitted. If, as in the preceding example, the server requires authentication, it sends the 401 response and the client has not unnecessarily transmitted the data. + + Changing the value of this property does not affect existing <xref:System.Net.ServicePoint> objects. Only new <xref:System.Net.ServicePoint> objects created after the change are affected. + + The 100-Continue behavior is not used for HTTP 1.0 requests even if this property is set to `true`. + + The Expect 100-Continue behavior is fully described in IETF RFC 2616 Section 10.1.1. + +> [!NOTE] +> On modern .NET, this property sets <xref:System.Net.Http.Headers.HttpRequestHeaders.ExpectContinue> on the <xref:System.Net.Http.HttpRequestMessage> unless overridden by <xref:System.Net.ServicePoint.Expect100Continue>. + +## Examples + The following code example sets this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet10"::: + ]]></format> </remarks> <altmember cref="T:System.Net.ServicePoint" /> @@ -688,11 +698,11 @@ <summary>Finds an existing <see cref="T:System.Net.ServicePoint" /> object or creates a new <see cref="T:System.Net.ServicePoint" /> object to manage communications with the specified <see cref="T:System.Uri" /> object.</summary> <returns>The <see cref="T:System.Net.ServicePoint" /> object that manages communications for the request.</returns> <remarks> - <format type="text/markdown"><![CDATA[ - -## Remarks - The <xref:System.Net.ServicePointManager.FindServicePoint%2A> method returns the <xref:System.Net.ServicePoint> object associated with the specified Internet host name. If no <xref:System.Net.ServicePoint> object exists for that host, the <xref:System.Net.ServicePointManager> object creates one. - + <format type="text/markdown"><![CDATA[ + +## Remarks + The <xref:System.Net.ServicePointManager.FindServicePoint%2A> method returns the <xref:System.Net.ServicePoint> object associated with the specified Internet host name. If no <xref:System.Net.ServicePoint> object exists for that host, the <xref:System.Net.ServicePointManager> object creates one. + ]]></format> </remarks> <exception cref="T:System.ArgumentNullException"> @@ -762,20 +772,20 @@ <summary>Finds an existing <see cref="T:System.Net.ServicePoint" /> object or creates a new <see cref="T:System.Net.ServicePoint" /> object to manage communications with the specified Uniform Resource Identifier (URI).</summary> <returns>The <see cref="T:System.Net.ServicePoint" /> object that manages communications for the request.</returns> <remarks> - <format type="text/markdown"><![CDATA[ - -## Remarks - The <xref:System.Net.ServicePointManager.FindServicePoint%2A> method returns the <xref:System.Net.ServicePoint> object associated with the specified Internet host name. If no <xref:System.Net.ServicePoint> object exists for that host, the <xref:System.Net.ServicePointManager> object creates one. - - - -## Examples - The following code example demonstrates calling this method to access a <xref:System.Net.ServicePoint> object. - + <format type="text/markdown"><![CDATA[ + +## Remarks + The <xref:System.Net.ServicePointManager.FindServicePoint%2A> method returns the <xref:System.Net.ServicePoint> object associated with the specified Internet host name. If no <xref:System.Net.ServicePoint> object exists for that host, the <xref:System.Net.ServicePointManager> object creates one. + + + +## Examples + The following code example demonstrates calling this method to access a <xref:System.Net.ServicePoint> object. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet7"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet7"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet7"::: + ]]></format> </remarks> <exception cref="T:System.UriFormatException">The URI specified in <paramref name="uriString" /> is invalid.</exception> @@ -845,11 +855,11 @@ <summary>Finds an existing <see cref="T:System.Net.ServicePoint" /> object or creates a new <see cref="T:System.Net.ServicePoint" /> object to manage communications with the specified <see cref="T:System.Uri" /> object.</summary> <returns>The <see cref="T:System.Net.ServicePoint" /> object that manages communications for the request.</returns> <remarks> - <format type="text/markdown"><![CDATA[ - -## Remarks - The <xref:System.Net.ServicePointManager.FindServicePoint%2A> method returns the <xref:System.Net.ServicePoint> object associated with the specified Internet host name. If no <xref:System.Net.ServicePoint> object exists for that host, the <xref:System.Net.ServicePointManager> object creates one. - + <format type="text/markdown"><![CDATA[ + +## Remarks + The <xref:System.Net.ServicePointManager.FindServicePoint%2A> method returns the <xref:System.Net.ServicePoint> object associated with the specified Internet host name. If no <xref:System.Net.ServicePoint> object exists for that host, the <xref:System.Net.ServicePointManager> object creates one. + ]]></format> </remarks> <exception cref="T:System.ArgumentNullException"> @@ -899,22 +909,23 @@ <summary>Gets or sets the maximum idle time of a <see cref="T:System.Net.ServicePoint" /> object.</summary> <value>The maximum idle time, in milliseconds, of a <see cref="T:System.Net.ServicePoint" /> object. The default value is 100,000 milliseconds (100 seconds).</value> <remarks> - <format type="text/markdown"><![CDATA[ - -## Remarks - The <xref:System.Net.ServicePointManager.MaxServicePointIdleTime%2A> property sets the maximum idle time that the <xref:System.Net.ServicePointManager> object assigns to the <xref:System.Net.ServicePoint.MaxIdleTime%2A> property when creating <xref:System.Net.ServicePoint> objects. Changes to this value affect only <xref:System.Net.ServicePoint> objects that are initialized after the value is changed. - - After a <xref:System.Net.ServicePoint> object has been idle for the time specified in <xref:System.Net.ServicePoint.MaxIdleTime%2A>, it is eligible for garbage collection. A <xref:System.Net.ServicePoint> object is idle when the list of connections associated with the <xref:System.Net.ServicePoint> object is empty. - - - -## Examples - The following code example sets this property. - + <format type="text/markdown"><![CDATA[ + +## Remarks + The <xref:System.Net.ServicePointManager.MaxServicePointIdleTime%2A> property sets the maximum idle time that the <xref:System.Net.ServicePointManager> object assigns to the <xref:System.Net.ServicePoint.MaxIdleTime%2A> property when creating <xref:System.Net.ServicePoint> objects. Changes to this value affect only <xref:System.Net.ServicePoint> objects that are initialized after the value is changed. + + After a <xref:System.Net.ServicePoint> object has been idle for the time specified in <xref:System.Net.ServicePoint.MaxIdleTime%2A>, it is eligible for garbage collection. A <xref:System.Net.ServicePoint> object is idle when the list of connections associated with the <xref:System.Net.ServicePoint> object is empty. + +> [!NOTE] +> On modern .NET, this property maps to <xref:System.Net.Http.SocketsHttpHandler.PooledConnectionIdleTimeout> unless overridden by <xref:System.Net.ServicePoint.MaxIdleTime>. However, handlers are not being reused between requests so it doesn't have any meaningful impact. + +## Examples + The following code example sets this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet8"::: + ]]></format> </remarks> <exception cref="T:System.ArgumentOutOfRangeException"> @@ -970,20 +981,21 @@ <summary>Gets or sets the maximum number of <see cref="T:System.Net.ServicePoint" /> objects to maintain at any time.</summary> <value>The maximum number of <see cref="T:System.Net.ServicePoint" /> objects to maintain. The default value is 0, which means there is no limit to the number of <see cref="T:System.Net.ServicePoint" /> objects.</value> <remarks> - <format type="text/markdown"><![CDATA[ - -## Remarks - When you reduce the <xref:System.Net.ServicePointManager.MaxServicePoints%2A> property below the number of <xref:System.Net.ServicePoint> objects currently in existence, the <xref:System.Net.ServicePointManager> deletes the <xref:System.Net.ServicePoint> objects with the longest idle times. If the number of <xref:System.Net.ServicePoint> objects with active connections is greater than the value of <xref:System.Net.ServicePointManager.MaxServicePoints%2A>, the <xref:System.Net.ServicePointManager> object deletes the <xref:System.Net.ServicePoint> objects as they become idle. - - - -## Examples - The following code example sets this property. - + <format type="text/markdown"><![CDATA[ + +## Remarks + When you reduce the <xref:System.Net.ServicePointManager.MaxServicePoints%2A> property below the number of <xref:System.Net.ServicePoint> objects currently in existence, the <xref:System.Net.ServicePointManager> deletes the <xref:System.Net.ServicePoint> objects with the longest idle times. If the number of <xref:System.Net.ServicePoint> objects with active connections is greater than the value of <xref:System.Net.ServicePointManager.MaxServicePoints%2A>, the <xref:System.Net.ServicePointManager> object deletes the <xref:System.Net.ServicePoint> objects as they become idle. + +> [!NOTE] +> On modern .NET, this property is not implemented. + +## Examples + The following code example sets this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet8"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet8"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet8"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet8"::: + ]]></format> </remarks> <exception cref="T:System.ArgumentOutOfRangeException"> @@ -1031,11 +1043,14 @@ <summary>Setting this property value to <see langword="true" /> causes all outbound TCP connections from HttpWebRequest to use the native socket option SO_REUSE_UNICASTPORT on the socket. This causes the underlying outgoing ports to be shared. This is useful for scenarios where a large number of outgoing connections are made in a short time, and the app risks running out of ports.</summary> <value>Returns <see cref="T:System.Boolean" />.</value> <remarks> - <format type="text/markdown"><![CDATA[ - -## Remarks - The default value is `false`. - + <format type="text/markdown"><![CDATA[ + +## Remarks + The default value is `false`. + +> [!NOTE] +> On modern .NET, this property is not implemented. + ]]></format> </remarks> </Docs> @@ -1087,21 +1102,24 @@ <summary>Gets or sets the security protocol used by the <see cref="T:System.Net.ServicePoint" /> objects managed by the <see cref="T:System.Net.ServicePointManager" /> object.</summary> <value>One of the values defined in the <see cref="T:System.Net.SecurityProtocolType" /> enumeration.</value> <remarks> - <format type="text/markdown"><. - -For versions of the .NET Framework through the .NET Framework 4.6.2, no default value is listed for this property. The security landscape changes constantly, and default protocols and protection levels are changed over time in order to avoid known weaknesses. Defaults vary depending on individual machine configuration, installed software, and applied patches. - - Your code should never implicitly depend on using a particular protection level, or on the assumption that a given security level is used by default. If your app depends on the use of a particular security level, you must explicitly specify that level and then check to be sure that it is actually in use on the established connection. Further, your code should be designed to be robust in the face of changes to which protocols are supported, as such changes are often made with little advance notice in order to mitigate emerging threats. - - The .NET Framework 4.6 includes a new security feature that blocks insecure cipher and hashing algorithms for connections. Applications using TLS/SSL through APIs such as HttpClient, HttpWebRequest, FTPClient, SmtpClient, SslStream, etc. and targeting .NET Framework 4.6 get the more-secure behavior by default. - - Developers may want to opt out of this behavior in order to maintain interoperability with their existing SSL3 services OR TLS w/ RC4 services. [This article](https://support.microsoft.com/kb/3069494) explains how to modify your code so that the new behavior is disabled. - + +For versions of the .NET Framework through the .NET Framework 4.6.2, no default value is listed for this property. The security landscape changes constantly, and default protocols and protection levels are changed over time in order to avoid known weaknesses. Defaults vary depending on individual machine configuration, installed software, and applied patches. + + Your code should never implicitly depend on using a particular protection level, or on the assumption that a given security level is used by default. If your app depends on the use of a particular security level, you must explicitly specify that level and then check to be sure that it is actually in use on the established connection. Further, your code should be designed to be robust in the face of changes to which protocols are supported, as such changes are often made with little advance notice in order to mitigate emerging threats. + + The .NET Framework 4.6 includes a new security feature that blocks insecure cipher and hashing algorithms for connections. Applications using TLS/SSL through APIs such as HttpClient, HttpWebRequest, FTPClient, SmtpClient, SslStream, etc. and targeting .NET Framework 4.6 get the more-secure behavior by default. + + Developers may want to opt out of this behavior in order to maintain interoperability with their existing SSL3 services OR TLS w/ RC4 services. [This article](https://support.microsoft.com/kb/3069494) explains how to modify your code so that the new behavior is disabled. + +> [!NOTE] +> On modern .NET, this property maps to <xref:System.Net.Security.SslClientAuthenticationOptions.EnabledSslProtocols> on <xref:System.Net.Http.SocketsHttpHandler.SslOptions>. + ]]></format> </remarks> <exception cref="T:System.NotSupportedException">The value specified to set the property is not a valid <see cref="T:System.Net.SecurityProtocolType" /> enumeration value.</exception> @@ -1156,17 +1174,20 @@ For versions of the .NET Framework through the .NET Framework 4.6.2, no default <summary>Gets or sets the callback to validate a server certificate.</summary> <value>A <see cref="T:System.Net.Security.RemoteCertificateValidationCallback" />. The default value is <see langword="null" />.</value> <remarks> - <format type="text/markdown"><![CDATA[ - -## Remarks -An application can set the <xref:System.Net.ServicePointManager.ServerCertificateValidationCallback%2A> property to a method to use for custom validation by the client of the server certificate. When doing custom validation, the `sender` parameter passed to the <xref:System.Net.Security.RemoteCertificateValidationCallback> can be a host string name or an object derived from <xref:System.Net.WebRequest> (<xref:System.Net.HttpWebRequest>, for example) depending on the <xref:System.Net.ServicePointManager.CertificatePolicy%2A> property. - -When custom validation is not used, the certificate name is compared with the host name used to create the request. For example, if <xref:System.Net.WebRequest.Create%28System.String%29> was passed a parameter of `"https://www.contoso.com/default.html"`, the default behavior is for the client to check the certificate against `www.contoso.com`. - -Despite being a multicast delegate, only the value returned from the last-executed event handler is considered authoritative. -In other words, you can attach multiple delegates, and they all get a callback from <xref:System.Net.ServicePointManager.ServerCertificateValidationCallback%2A>. + <format type="text/markdown"><![CDATA[ + +## Remarks +An application can set the <xref:System.Net.ServicePointManager.ServerCertificateValidationCallback%2A> property to a method to use for custom validation by the client of the server certificate. When doing custom validation, the `sender` parameter passed to the <xref:System.Net.Security.RemoteCertificateValidationCallback> can be a host string name or an object derived from <xref:System.Net.WebRequest> (<xref:System.Net.HttpWebRequest>, for example) depending on the <xref:System.Net.ServicePointManager.CertificatePolicy%2A> property. + +When custom validation is not used, the certificate name is compared with the host name used to create the request. For example, if <xref:System.Net.WebRequest.Create%28System.String%29> was passed a parameter of `"https://www.contoso.com/default.html"`, the default behavior is for the client to check the certificate against `www.contoso.com`. + +Despite being a multicast delegate, only the value returned from the last-executed event handler is considered authoritative. +In other words, you can attach multiple delegates, and they all get a callback from <xref:System.Net.ServicePointManager.ServerCertificateValidationCallback%2A>. Each callback returns a value that indicates whether the certificate is accepted or not; however, only the value from the last delegate is respected. - + +> [!NOTE] +> On modern .NET, this property maps to <xref:System.Net.Security.SslClientAuthenticationOptions.RemoteCertificateValidationCallback> on <xref:System.Net.Http.SocketsHttpHandler.SslOptions>. + ]]></format> </remarks> <altmember cref="T:System.Net.ServicePoint" /> @@ -1215,28 +1236,31 @@ Each callback returns a value that indicates whether the certificate is accepted <Parameter Name="keepAliveInterval" Type="System.Int32" Index="2" FrameworkAlternate="net-5.0;net-6.0;net-7.0;net-8.0;net-9.0;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1;netstandard-2.0;netstandard-2.1" /> </Parameters> <Docs> - <param name="enabled">If set to true, then the TCP keep-alive option on a TCP connection will be enabled using the specified <paramref name="keepAliveTime" /> and <paramref name="keepAliveInterval" /> values. - - If set to false, then the TCP keep-alive option is disabled and the remaining parameters are ignored. - + <param name="enabled">If set to true, then the TCP keep-alive option on a TCP connection will be enabled using the specified <paramref name="keepAliveTime" /> and <paramref name="keepAliveInterval" /> values. + + If set to false, then the TCP keep-alive option is disabled and the remaining parameters are ignored. + The default value is false.</param> - <param name="keepAliveTime">Specifies the timeout, in milliseconds, with no activity until the first keep-alive packet is sent. - + <param name="keepAliveTime">Specifies the timeout, in milliseconds, with no activity until the first keep-alive packet is sent. + The value must be greater than 0. If a value of less than or equal to zero is passed an <see cref="T:System.ArgumentOutOfRangeException" /> is thrown.</param> - <param name="keepAliveInterval">Specifies the interval, in milliseconds, between when successive keep-alive packets are sent if no acknowledgement is received. - + <param name="keepAliveInterval">Specifies the interval, in milliseconds, between when successive keep-alive packets are sent if no acknowledgement is received. + The value must be greater than 0. If a value of less than or equal to zero is passed an <see cref="T:System.ArgumentOutOfRangeException" /> is thrown.</param> <summary>Enables or disables the keep-alive option on a TCP connection.</summary> <remarks> - <format type="text/markdown"><![CDATA[ - -## Remarks - An application can request that a TCP/IP provider enable the use of keep-alive packets on a TCP connection. The default is that the use of keep-alive packets on a TCP connection is disabled. - - The default settings when a TCP socket is initialized sets the keep-alive timeout to 2 hours and the keep-alive interval to 1 second. The `keepAliveTime` parameter specifies the timeout, in milliseconds, with no activity until the first keep-alive packet is sent. The `keepAliveInterval` parameter specifies the interval, in milliseconds, between when successive keep-alive packets are sent if no acknowledgement is received. The number of keep-alive probes cannot be changed and is set to 10. - - If a TCP connection is dropped as the result of keep-alives, a <xref:System.Net.Sockets.SocketError> of <xref:System.Net.Sockets.SocketError.NetworkReset> is returned to any calls in progress on the socket, and any subsequent calls will fail with a <xref:System.Net.Sockets.SocketError> of <xref:System.Net.Sockets.SocketError.NotConnected>. - + <format type="text/markdown"><![CDATA[ + +## Remarks + An application can request that a TCP/IP provider enable the use of keep-alive packets on a TCP connection. The default is that the use of keep-alive packets on a TCP connection is disabled. + + The default settings when a TCP socket is initialized sets the keep-alive timeout to 2 hours and the keep-alive interval to 1 second. The `keepAliveTime` parameter specifies the timeout, in milliseconds, with no activity until the first keep-alive packet is sent. The `keepAliveInterval` parameter specifies the interval, in milliseconds, between when successive keep-alive packets are sent if no acknowledgement is received. The number of keep-alive probes cannot be changed and is set to 10. + + If a TCP connection is dropped as the result of keep-alives, a <xref:System.Net.Sockets.SocketError> of <xref:System.Net.Sockets.SocketError.NetworkReset> is returned to any calls in progress on the socket, and any subsequent calls will fail with a <xref:System.Net.Sockets.SocketError> of <xref:System.Net.Sockets.SocketError.NotConnected>. + +> [!NOTE] +> On modern .NET, <xref:System.Net.HttpWebRequest> uses <xref:System.Net.Http.SocketsHttpHandler.ConnectCallback> to set TCP keep alive options on the underlying socket to the values provided to this method. + ]]></format> </remarks> <exception cref="T:System.ArgumentOutOfRangeException">The value specified for <paramref name="keepAliveTime" /> or <paramref name="keepAliveInterval" /> parameter is less than or equal to 0.</exception> @@ -1285,24 +1309,25 @@ Each callback returns a value that indicates whether the certificate is accepted <value> <see langword="true" /> to use the Nagle algorithm; otherwise, <see langword="false" />. The default value is <see langword="true" />.</value> <remarks> - <format type="text/markdown"><![CDATA[ - -## Remarks - The Nagle algorithm is used to reduce network traffic by buffering small packets of data and transmitting them as a single packet. This process is also referred to as "nagling"; it is widely used because it reduces the number of packets transmitted and lowers the overhead per packet. - - Changing the value of this property does not affect existing <xref:System.Net.ServicePoint> objects. Only new service points created after the change are affected. - - The Nagle algorithm is fully described in IETF RFC 896. - - - -## Examples - The following code example sets this property. - + <format type="text/markdown"><![CDATA[ + +## Remarks + The Nagle algorithm is used to reduce network traffic by buffering small packets of data and transmitting them as a single packet. This process is also referred to as "nagling"; it is widely used because it reduces the number of packets transmitted and lowers the overhead per packet. + + Changing the value of this property does not affect existing <xref:System.Net.ServicePoint> objects. Only new service points created after the change are affected. + + The Nagle algorithm is fully described in IETF RFC 896. + +> [!NOTE] +> On modern .NET, <xref:System.Net.HttpWebRequest> uses <xref:System.Net.Http.SocketsHttpHandler.ConnectCallback> to set <xref:System.Net.Sockets.Socket.NoDelay> to the opposite value than this property. + +## Examples + The following code example sets this property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_Remoting/System.Net.ServicePoint/CPP/servicepoint.cpp" id="Snippet10"::: :::code language="csharp" source="~/snippets/csharp/System.Net/HttpWebRequest/ServicePoint/servicepoint.cs" id="Snippet10"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet10"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_Remoting/System.Net.ServicePoint/VB/servicepoint.vb" id="Snippet10"::: + ]]></format> </remarks> <altmember cref="T:System.Net.ServicePoint" />