[HTTP] Example for WinHttpHandler.ServerCertificateValidationCallback (#11463)

* Improve example for ServerCertificateValidationCallback

* Update snippets/csharp/System.Net.Http/WinHttpHandler/program.cs

Co-authored-by: Anton Firszov <[email protected]>

* Update xml/System.Net.Http/WinHttpHandler.xml

Co-authored-by: Genevieve Warren <[email protected]>

* Fixed sample

* Change description with changed example

---------

Co-authored-by: Anton Firszov <[email protected]>
Co-authored-by: Genevieve Warren <[email protected]>

Author: 3 people

snippets/csharp/System.Net.Http/WinHttpHandler/Project.csproj

@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Library</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="System.Net.Http.WinHttpHandler" Version="9.0.6" />
+  </ItemGroup>
+
+</Project>

snippets/csharp/System.Net.Http/WinHttpHandler/program.cs

@@ -0,0 +1,29 @@
+using System;
+using System.Net;
+using System.Net.Http;
+using System.Net.Security;
+
+class WinHttpHandler_SecureExample
+{
+    static void Main()
+    {
+        if (!OperatingSystem.IsWindows())
+        {
+            Console.WriteLine("This example requires Windows.");
+            return;
+        }
+        // <Snippet1>
+        var handler = new WinHttpHandler();
+        handler.ServerCertificateValidationCallback = (httpRequestMessage, certificate, chain, sslPolicyErrors) =>
+        {
+            if (sslPolicyErrors == SslPolicyErrors.None)
+            {
+                // TODO: Implement additional custom certificate validation logic here.
+                return true;
+            }
+            // Do not allow this client to communicate with unauthenticated servers.
+            return false;
+        };
+        // </Snippet1>
+    }
+}

xml/System.Net.Http/WinHttpHandler.xml

@@ -740,13 +740,20 @@ When this property is set to `true`, all HTTP redirect responses from the server
       </ReturnValue>
       <Docs>
         <summary>Gets or sets a callback method to validate the server certificate. This callback is part of the SSL handshake.</summary>
-        <value>The callback should return <see langword="true" /> if the server certificate is considered valid and the request should be sent. Otherwise, return <see langword="false" />.</value>
+        <value>The callback should return <see langword="true" /> if the server certificate is considered valid and the request should be sent. Otherwise, returns <see langword="false" />.</value>
         <remarks>
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
  The default value is `null`. If this property is `null`, the server certificate is validated using standard well-known certificate authorities.
 
+ The delegate's `sslPolicyErrors` argument contains any certificate errors returned by SSPI while authenticating the server. The <xref:System.Boolean> value returned by this delegate determines whether the authentication is allowed to succeed.
+
+## Examples
+
+The following code example implements the callback. If there are validation errors, this method returns `false` preventing communication with the unauthenticated server. Otherwise, it allows for additional validation and return `true` if the certificate is valid.
+
+ :::code language="csharp" source="~/snippets/csharp/System.Net.Http/WinHttpHandler/program.cs" id="Snippet1":::
  ]]></format>
         </remarks>
       </Docs>