diff --git a/xml/System.Net/ServicePoint.xml b/xml/System.Net/ServicePoint.xml index 732897b19c8..b88eb87159d 100644 --- a/xml/System.Net/ServicePoint.xml +++ b/xml/System.Net/ServicePoint.xml @@ -52,31 +52,31 @@ Provides connection management for HTTP connections. - 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 object maintains, which is then shared by all subsequent requests to that resource. - - objects are managed by the class and are created, if necessary, by the method. objects are never created directly but are always created and managed by the class. The maximum number of objects that can be created is set by the property. - - Each object maintains its connection to an Internet resource until it has been idle longer than the time specified in the property. When a exceeds the value, it can be recycled to another connection. The default value of is set by the property. - - When the property is set to a value other than -1, and after the specified time elapses, an active 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 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 object maintains, which is then shared by all subsequent requests to that resource. + + objects are managed by the class and are created, if necessary, by the method. objects are never created directly but are always created and managed by the class. The maximum number of objects that can be created is set by the property. + + Each object maintains its connection to an Internet resource until it has been idle longer than the time specified in the property. When a exceeds the value, it can be recycled to another connection. The default value of is set by the property. + + When the property is set to a value other than -1, and after the specified time elapses, an active 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 object that connects to the URI `www.contoso.com`. - + +## Examples + The following code example creates a 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"::: + ]]> @@ -122,15 +122,15 @@ Gets the Uniform Resource Identifier (URI) of the server that this object connects to. An instance of the class that contains the URI of the Internet server that this object connects to. - The is in host mode. @@ -187,14 +187,17 @@ Specifies the delegate to associate a local with a . A delegate that forces a to use a particular local Internet Protocol (IP) address and port number. The default value is . - (or for Internet Protocol Version 6) and an ephemeral port. Your can satisfy this requirement. - + Some load balancing techniques require a client to use a specific local IP address and port number, rather than (or for Internet Protocol Version 6) and an ephemeral port. Your can satisfy this requirement. + +> [!NOTE] +, uses to bind the underlying socket to the endpoint from this delegate. + ]]> @@ -247,24 +250,24 @@ Gets the certificate received for this object. An instance of the class that contains the security certificate received for this object. - object can make multiple connections to an Internet resource, it can maintain only one certificate. +Although a object can make multiple connections to an Internet resource, it can maintain only one certificate. > [!NOTE] -> In .NET Core and .NET 5+, the property always returns null. To access the server certificate, use . +> On modern .NET, returns remote certificate retrieved via on . + +## 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"::: + ]]> @@ -317,15 +320,19 @@ Although a object can make multiple connections t Gets the last client certificate sent to the server. An object that contains the public values of the last client certificate sent to the server. - [!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"::: + ]]> @@ -374,14 +381,14 @@ Although a object can make multiple connections t Removes the specified connection group from this object. A value that indicates whether the connection group was closed. - @@ -432,29 +439,32 @@ Although a object can make multiple connections t Gets or sets the number of milliseconds after which an active connection is closed. A that specifies the number of milliseconds that an active connection remains open. The default is -1, which allows an active connection to stay connected indefinitely. Set this property to 0 to force connections to close after servicing a request. - 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 is `true` for a request, the property sets the time-out for closing connections due to inactivity. If the has active connections, has no effect and the connections remain open indefinitely. - - When the property is set to a value other than -1, and after the specified time elapses, an active connection is closed after servicing a request by setting to `false` in that request. - - Setting this value affects all connections managed by the object. - - - -## Examples - The following code example sets the value of this property. - + You can use this property to ensure that a 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 is `true` for a request, the property sets the time-out for closing connections due to inactivity. If the has active connections, has no effect and the connections remain open indefinitely. + + When the property is set to a value other than -1, and after the specified time elapses, an active connection is closed after servicing a request by setting to `false` in that request. + + Setting this value affects all connections managed by the object. + + +> [!NOTE] +> On modern .NET, this property maps to . 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"::: + ]]> The value specified for a set operation is a negative number less than -1. @@ -504,23 +514,25 @@ Although a object can make multiple connections t Gets or sets the maximum number of connections allowed on this object. The maximum number of connections allowed on this object. - property sets the maximum number of connections that the object can make to an Internet resource. The value of the property is set to the value of the property when the object is created; subsequent changes to have no effect on existing objects. - - - -## Examples - The following code example uses the property to check the maximum number of connections that the object can make to the specified Uniform Resource Identifier (URI). - + The property sets the maximum number of connections that the object can make to an Internet resource. The value of the property is set to the value of the property when the object is created; subsequent changes to have no effect on existing objects. + +> [!NOTE] +> On modern .NET, this property maps to . However, handlers are not being reused between requests so it doesn't have any meaningful impact. + + +## Examples + The following code example uses the property to check the maximum number of connections that the 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"::: + ]]> The connection limit is equal to or less than 0. @@ -574,23 +586,23 @@ Although a object can make multiple connections t Gets the connection name. A that represents the connection name. - object was constructed by calling a overload with a argument, then the property represents the property of the object used. - - If the object was constructed from a network host and port, the property contains a string that represents the host and the network port. If the property is set when constructed from a host and port, only objects with the same value can use this object. - - - -## Examples + If the object was constructed by calling a overload with a argument, then the property represents the property of the object used. + + If the object was constructed from a network host and port, the property contains a string that represents the host and the network port. If the property is set when constructed from a host and port, only objects with the same value can use this 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"::: + ]]> Connection Grouping @@ -637,22 +649,24 @@ Although a object can make multiple connections t Gets the number of open connections associated with this object. The number of open connections associated with this object. - property contains the number of open Internet connections associated with this object. The value of cannot exceed that of . - - -## Examples - The following code example uses the property to determine the number of open Internet connections associated with this object. - + The property contains the number of open Internet connections associated with this object. The value of cannot exceed that of . + +> [!NOTE] +> On modern .NET, this property is not implemented. + +## Examples + The following code example uses the property to determine the number of open Internet connections associated with this 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"::: + ]]> @@ -709,31 +723,32 @@ Although a object can make multiple connections t to expect 100-Continue responses for requests; otherwise, . The default value is . - 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 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 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 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 on the . + +## 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"::: + ]]> @@ -769,7 +784,7 @@ Although a object can make multiple connections t Gets the date and time that the object was last connected to a host. A object that contains the date and time at which the object was last connected. - 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 exceeds the value of , the object is available for recycling to another connection. - - -## Examples - The following code example uses the property to set and retrieve the date and time that the object was last connected to a host. - + The 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 exceeds the value of , the object is available for recycling to another connection. + + +## Examples + The following code example uses the property to set and retrieve the date and time that the 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"::: + ]]> @@ -887,27 +902,28 @@ The `GetHashCode` method returns a hash code of this instance. This value can be Gets or sets the amount of time a connection associated with the object can remain idle before the connection is closed. The length of time, in milliseconds, that a connection associated with the object can remain idle before it is closed and reused for another connection. - to to indicate that a connection associated with the object should never time out. - - The default value of the property is the value of the property when the object is created. Subsequent changes to the property have no effect on existing objects. - - When the for a connection associated with a 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 property to set and retrieve the idle time. - + You can set to to indicate that a connection associated with the object should never time out. + + The default value of the property is the value of the property when the object is created. Subsequent changes to the property have no effect on existing objects. + + When the for a connection associated with a 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 . However, handlers are not being reused between requests so it doesn't have any meaningful impact. + +## Examples + The following code example uses the property to set and retrieve the 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"::: + ]]> @@ -955,22 +971,24 @@ The `GetHashCode` method returns a hash code of this instance. This value can be Gets the version of the HTTP protocol that the object uses. A object that contains the HTTP protocol version that the object uses. - [!NOTE] +> On modern .NET, this property returns . + +## 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"::: + ]]> @@ -1021,22 +1039,24 @@ The `GetHashCode` method returns a hash code of this instance. This value can be Gets or sets the size of the receiving buffer for the socket used by this . A that contains the size, in bytes, of the receive buffer. The default is 8192. - . - - -## Examples - The following code example sets the value of this property. - + For additional information, see . + +> [!NOTE] +> On modern .NET, uses to set 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"::: + ]]> The value specified for a set operation is greater than Int32.MaxValue. @@ -1084,31 +1104,34 @@ The `GetHashCode` method returns a hash code of this instance. This value can be - If set to true, then the TCP keep-alive option on a TCP connection will be enabled using the specified and values. - - If set to false, then the TCP keep-alive option is disabled and the remaining parameters are ignored. - + If set to true, then the TCP keep-alive option on a TCP connection will be enabled using the specified and values. + + If set to false, then the TCP keep-alive option is disabled and the remaining parameters are ignored. + The default value is false. - Specifies the timeout, in milliseconds, with no activity until the first keep-alive packet is sent. - + 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 is thrown. - Specifies the interval, in milliseconds, between when successive keep-alive packets are sent if no acknowledgement is received. - + 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 is thrown. Enables or disables the keep-alive option on a TCP connection. - of is returned to any calls in progress on the socket, and any subsequent calls will fail with a of . - + 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 of is returned to any calls in progress on the socket, and any subsequent calls will fail with a of . + +> [!NOTE] +> On modern .NET, uses to set TCP keep alive options on the underlying socket to the values provided to this method. + ]]> The value specified for or parameter is less than or equal to 0. @@ -1156,25 +1179,26 @@ The `GetHashCode` method returns a hash code of this instance. This value can be if the object supports pipelined connections; otherwise, . - [!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"::: + ]]> @@ -1231,27 +1255,28 @@ The `GetHashCode` method returns a hash code of this instance. This value can be to use the Nagle algorithm; otherwise, . The default value is . - [!NOTE] +> On modern .NET, uses to set 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"::: + ]]> diff --git a/xml/System.Net/ServicePointManager.xml b/xml/System.Net/ServicePointManager.xml index b50b2a6133f..1aeb636a468 100644 --- a/xml/System.Net/ServicePointManager.xml +++ b/xml/System.Net/ServicePointManager.xml @@ -56,27 +56,27 @@ Manages the collection of objects. - is a static class used to create, maintain, and delete instances of the class. - - When an application requests a connection to an Internet resource Uniform Resource Identifier (URI) through the object, the returns a object that contains connection information for the host and scheme identified by the URI. If there is an existing object for that host and scheme, the object returns the existing object; otherwise, the object creates a new object. - - 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 , , , , , 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. - + is a static class used to create, maintain, and delete instances of the class. + + When an application requests a connection to an Internet resource Uniform Resource Identifier (URI) through the object, the returns a object that contains connection information for the host and scheme identified by the URI. If there is an existing object for that host and scheme, the object returns the existing object; otherwise, the object creates a new object. + + 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 , , , , , 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. + > [!IMPORTANT] -> We don't recommend that you use the `ServicePointManager` class for new development. Instead, use the class. - -## Examples - The following code example creates a 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 class. + +## Examples + The following code example creates a 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"::: + ]]> @@ -123,22 +123,21 @@ Gets or sets policy for server certificates. An object that implements the interface. - property is set to an interface object, the 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. - + property is set to an interface object, the 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"::: + ]]> @@ -187,20 +186,21 @@ if the certificate revocation list is checked; otherwise, . - 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. - + 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 on . + +## 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"::: + ]]> @@ -254,25 +254,26 @@ Gets or sets the maximum number of concurrent connections allowed by a object. The maximum number of concurrent connections allowed by a 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 . However, you can change the value programmatically when the autoConfig property is . Set your preferred value once, when the AppDomain loads. - property sets the default maximum number of concurrent connections that the object assigns to the property when creating objects. - - Changing the property has no effect on existing objects; it affects only 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 . - + property sets the default maximum number of concurrent connections that the object assigns to the property when creating objects. + + Changing the property has no effect on existing objects; it affects only 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 . + > [!NOTE] > Any changes to the 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 unless overridden by . 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"::: + ]]> @@ -365,15 +366,15 @@ The default number of persistent connections (2) allowed on a object connected to an HTTP/1.1 or later server. This field is constant and is used to initialize the property if the value of the property has not been set either directly or through configuration. - property using this field. - + 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"::: + ]]> @@ -418,15 +419,19 @@ Gets or sets a value that indicates how long a Domain Name Service (DNS) resolution is considered valid. 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). - [!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"::: + ]]> @@ -473,20 +478,21 @@ if a DNS resolution always returns the first IP address for a particular host; otherwise . The default is . - [!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"::: + ]]> @@ -537,13 +543,16 @@ Gets the for this instance. The encryption policy to use for this instance. - property defaults to . This is applied to an SSL/TLS session on this instance. - - The use of the Null cipher is required when the encryption policy is set to . - + property defaults to . This is applied to an SSL/TLS session on this instance. + + The use of the Null cipher is required when the encryption policy is set to . + +> [!NOTE] +> On modern .NET, this property is not implemented. + ]]> @@ -594,30 +603,31 @@ to enable 100-Continue behavior. The default value is . - property is `true` and property is greater than zero or the 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 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 objects. Only new 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. - + property is `true` and property is greater than zero or the 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 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 objects. Only new 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 on the unless overridden by . + +## 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"::: + ]]> @@ -688,11 +698,11 @@ Finds an existing object or creates a new object to manage communications with the specified object. The object that manages communications for the request. - method returns the object associated with the specified Internet host name. If no object exists for that host, the object creates one. - + method returns the object associated with the specified Internet host name. If no object exists for that host, the object creates one. + ]]> @@ -762,20 +772,20 @@ Finds an existing object or creates a new object to manage communications with the specified Uniform Resource Identifier (URI). The object that manages communications for the request. - method returns the object associated with the specified Internet host name. If no object exists for that host, the object creates one. - - - -## Examples - The following code example demonstrates calling this method to access a object. - + method returns the object associated with the specified Internet host name. If no object exists for that host, the object creates one. + + + +## Examples + The following code example demonstrates calling this method to access a 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"::: + ]]> The URI specified in is invalid. @@ -845,11 +855,11 @@ Finds an existing object or creates a new object to manage communications with the specified object. The object that manages communications for the request. - method returns the object associated with the specified Internet host name. If no object exists for that host, the object creates one. - + method returns the object associated with the specified Internet host name. If no object exists for that host, the object creates one. + ]]> @@ -899,22 +909,23 @@ Gets or sets the maximum idle time of a object. The maximum idle time, in milliseconds, of a object. The default value is 100,000 milliseconds (100 seconds). - property sets the maximum idle time that the object assigns to the property when creating objects. Changes to this value affect only objects that are initialized after the value is changed. - - After a object has been idle for the time specified in , it is eligible for garbage collection. A object is idle when the list of connections associated with the object is empty. - - - -## Examples - The following code example sets this property. - + property sets the maximum idle time that the object assigns to the property when creating objects. Changes to this value affect only objects that are initialized after the value is changed. + + After a object has been idle for the time specified in , it is eligible for garbage collection. A object is idle when the list of connections associated with the object is empty. + +> [!NOTE] +> On modern .NET, this property maps to unless overridden by . 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"::: + ]]> @@ -970,20 +981,21 @@ Gets or sets the maximum number of objects to maintain at any time. The maximum number of objects to maintain. The default value is 0, which means there is no limit to the number of objects. - property below the number of objects currently in existence, the deletes the objects with the longest idle times. If the number of objects with active connections is greater than the value of , the object deletes the objects as they become idle. - - - -## Examples - The following code example sets this property. - + property below the number of objects currently in existence, the deletes the objects with the longest idle times. If the number of objects with active connections is greater than the value of , the object deletes the 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"::: + ]]> @@ -1031,11 +1043,14 @@ Setting this property value to 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. Returns . - [!NOTE] +> On modern .NET, this property is not implemented. + ]]> @@ -1087,21 +1102,24 @@ Gets or sets the security protocol used by the objects managed by the object. One of the values defined in the enumeration. - . This allows .NET Framework networking APIs based on (such as FTP, HTTP, and SMTP) to inherit the default security protocols from the operating system or from any custom configurations performed by a system administrator. For information about which SSL/TLS protocols are enabled by default on each version of the Windows operating system, see [Protocols in TLS/SSL (Schannel SSP)](/windows/win32/secauthn/protocols-in-tls-ssl--schannel-ssp-). - -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 on . + ]]> The value specified to set the property is not a valid enumeration value. @@ -1156,17 +1174,20 @@ For versions of the .NET Framework through the .NET Framework 4.6.2, no default Gets or sets the callback to validate a server certificate. A . The default value is . - 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 can be a host string name or an object derived from (, for example) depending on the property. - -When custom validation is not used, the certificate name is compared with the host name used to create the request. For example, if 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 . + 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 can be a host string name or an object derived from (, for example) depending on the property. + +When custom validation is not used, the certificate name is compared with the host name used to create the request. For example, if 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 . 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 on . + ]]> @@ -1215,28 +1236,31 @@ Each callback returns a value that indicates whether the certificate is accepted - If set to true, then the TCP keep-alive option on a TCP connection will be enabled using the specified and values. - - If set to false, then the TCP keep-alive option is disabled and the remaining parameters are ignored. - + If set to true, then the TCP keep-alive option on a TCP connection will be enabled using the specified and values. + + If set to false, then the TCP keep-alive option is disabled and the remaining parameters are ignored. + The default value is false. - Specifies the timeout, in milliseconds, with no activity until the first keep-alive packet is sent. - + 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 is thrown. - Specifies the interval, in milliseconds, between when successive keep-alive packets are sent if no acknowledgement is received. - + 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 is thrown. Enables or disables the keep-alive option on a TCP connection. - of is returned to any calls in progress on the socket, and any subsequent calls will fail with a of . - + of is returned to any calls in progress on the socket, and any subsequent calls will fail with a of . + +> [!NOTE] +> On modern .NET, uses to set TCP keep alive options on the underlying socket to the values provided to this method. + ]]> The value specified for or parameter is less than or equal to 0. @@ -1285,24 +1309,25 @@ Each callback returns a value that indicates whether the certificate is accepted to use the Nagle algorithm; otherwise, . The default value is . - 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. - + 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, uses to set 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"::: + ]]>