Merge main into live

.github/copilot-instructions.md

@@ -0,0 +1,17 @@
+Code comments should end with a period.
+
+When you add a code snippet to the XML remarks of an API, add the code as a separate code file (.cs file) and not as an inline (```) code block. Also add a .csproj file to compile the code if one doesn't already exist in the snippet folder.
+
+Don't use the word "may". Use "might" to indicate possibility or "can" to indicate permission.
+
+There should always be a comma before a clause that begins with "which".
+
+Use a conversational tone with contractions.
+
+Be concise.
+
+Break up long sentences.
+
+Use the present tense for instructions and descriptions. For example, "The method returns a value" instead of "The method will return a value."
+
+Use the Oxford comma in lists of three or more items.

snippets/csharp/System.Globalization/CultureInfo/DisplayName/getcultures.cs

@@ -32,7 +32,6 @@ CULTURE ISO ISO WIN DISPLAYNAME                              ENGLISHNAME
 ar      ar  ara ARA Arabic                                   Arabic
 bg      bg  bul BGR Bulgarian                                Bulgarian
 ca      ca  cat CAT Catalan                                  Catalan
-zh-Hans zh  zho CHS Chinese (Simplified)                     Chinese (Simplified)
 cs      cs  ces CSY Czech                                    Czech
 da      da  dan DAN Danish                                   Danish
 de      de  deu DEU German                                   German
@@ -41,9 +40,10 @@ en      en  eng ENU English                                  English
 es      es  spa ESP Spanish                                  Spanish
 fi      fi  fin FIN Finnish                                  Finnish
 zh      zh  zho CHS Chinese                                  Chinese
-zh-Hant zh  zho CHT Chinese (Traditional)                    Chinese (Traditional)
-zh-CHS  zh  zho CHS Chinese (Simplified) Legacy              Chinese (Simplified) Legacy
-zh-CHT  zh  zho CHT Chinese (Traditional) Legacy             Chinese (Traditional) Legacy
+zh-Hans zh  zho CHS Chinese (Simplified)                     Chinese (Simplified)
+zh-Hant zh  zho ZHH Chinese (Traditional)                    Chinese (Traditional)
+
+Note: zh-Hant returns ZHH when using ICU (default). When NLS mode is enabled, it returns CHT.
 
 */
 // </snippet1>

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>
+    }
+}

snippets/csharp/System.Security.Cryptography.X509Certificates/X509Chain/Overview/chainelements-ordering.cs

@@ -0,0 +1,25 @@
+using System;
+using System.Security.Cryptography.X509Certificates;
+
+public class ChainElementsOrdering
+{
+    public static void DemonstrateChainElementsOrdering(X509Certificate2 certificate)
+    {
+//<SNIPPET6>
+        using var chain = new X509Chain();
+        chain.Build(certificate);
+
+        // chain.ChainElements[0] is the leaf (end-entity) certificate
+        // chain.ChainElements[^1] is the root (trust anchor) certificate
+
+        Console.WriteLine("Certificate chain from leaf to root:");
+        for (int i = 0; i < chain.ChainElements.Count; i++)
+        {
+            var cert = chain.ChainElements[i].Certificate;
+            var role = i == 0 ? "Leaf" : 
+                       i == chain.ChainElements.Count - 1 ? "Root" : "Intermediate";
+            Console.WriteLine($"[{i}] {role}: {cert.Subject}");
+        }
+//</SNIPPET6>
+    }
+}

snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CultureInfo.GetCultures/VB/getcultures.vb

@@ -29,7 +29,6 @@ Module Module1
 'ar      ar  ara ARA Arabic                                   Arabic                                  
 'bg      bg  bul BGR Bulgarian                                Bulgarian                               
 'ca      ca  cat CAT Catalan                                  Catalan                                 
-'zh-Hans zh  zho CHS Chinese (Simplified)                     Chinese (Simplified)                    
 'cs      cs  ces CSY Czech                                    Czech                                   
 'da      da  dan DAN Danish                                   Danish                                  
 'de      de  deu DEU German                                   German                                  
@@ -38,9 +37,10 @@ Module Module1
 'es      es  spa ESP Spanish                                  Spanish                                 
 'fi      fi  fin FIN Finnish                                  Finnish                                 
 'zh      zh  zho CHS Chinese                                  Chinese                                 
-'zh-Hant zh  zho CHT Chinese (Traditional)                    Chinese (Traditional)                   
-'zh-CHS  zh  zho CHS Chinese (Simplified) Legacy              Chinese (Simplified) Legacy             
-'zh-CHT  zh  zho CHT Chinese (Traditional) Legacy             Chinese (Traditional) Legacy            
+'zh-Hans zh  zho CHS Chinese (Simplified)                     Chinese (Simplified)                    
+'zh-Hant zh  zho ZHH Chinese (Traditional)                    Chinese (Traditional)                           
+'
+'Note: zh-Hant returns ZHH when using ICU (default). When NLS mode is enabled, it returns CHT.
 
 End Module
 ' </snippet1>

xml/System.Buffers.Text/Base64Url.xml

@@ -27,7 +27,7 @@
   <Interfaces />
   <Docs>
     <summary>Converts between binary data and URL-safe ASCII encoded text that's represented in Base64Url characters.</summary>
-    <remarks>To be added.</remarks>
+    <remarks>Base64Url encoding uses the same alphabet as standard Base64 encoding, except that the characters '+' and '/' are replaced with '-' and '_' respectively to make the output URL-safe.</remarks>
   </Docs>
   <Members>
     <Member MemberName="DecodeFromChars">
@@ -373,7 +373,7 @@
         <param name="source">The input span which contains binary data that needs to be encoded.</param>
         <summary>Encodes the span of binary data into unicode ASCII chars represented as Base64Url.</summary>
         <returns>A char array which contains the result of the operation, i.e. the ASCII chars in Base64Url.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
       </Docs>
     </Member>
     <Member MemberName="EncodeToChars">
@@ -406,7 +406,7 @@
         <param name="destination">The output span which contains the result of the operation, i.e. the ASCII chars in Base64Url.</param>
         <summary>Encodes the span of binary data into Unicode ASCII chars represented as Base64Url.</summary>
         <returns>The number of bytes written into the destination span. This can be used to slice the output for subsequent calls, if necessary.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
         <exception cref="T:System.ArgumentException">The buffer in <paramref name="destination" /> is too small to hold the encoded output.</exception>
       </Docs>
     </Member>
@@ -449,7 +449,7 @@
         </param>
         <summary>Encodes the span of binary data into unicode ASCII chars represented as Base64Url.</summary>
         <returns>One of the enumeration values that indicates the success or failure of the operation.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
       </Docs>
     </Member>
     <Member MemberName="EncodeToString">
@@ -486,7 +486,7 @@
         <param name="source">The input span that contains binary data that needs to be encoded.</param>
         <summary>Encodes the span of binary data into Unicode string represented as Base64Url ASCII chars.</summary>
         <returns>A string that contains the result of the operation, i.e. the ASCII string in Base64Url.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
       </Docs>
     </Member>
     <Member MemberName="EncodeToUtf8">
@@ -523,7 +523,7 @@
         <param name="source">The input span which contains binary data that needs to be encoded.</param>
         <summary>Encodes the span of binary data into UTF-8 encoded text represented as Base64Url.</summary>
         <returns>The output byte array which contains the result of the operation, i.e. the UTF-8 encoded text in Base64Url.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
       </Docs>
     </Member>
     <Member MemberName="EncodeToUtf8">
@@ -556,7 +556,7 @@
         <param name="destination">The output span which contains the result of the operation, i.e. the UTF-8 encoded text in Base64Url.</param>
         <summary>Encodes the span of binary data into UTF-8 encoded text represented as Base64Url.</summary>
         <returns>The number of bytes written into the destination span. This can be used to slice the output for subsequent calls, if necessary.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
         <exception cref="T:System.ArgumentException">The buffer in <paramref name="destination" /> is too small to hold the encoded output.</exception>
       </Docs>
     </Member>
@@ -599,7 +599,7 @@
         </param>
         <summary>Encodes the span of binary data into UTF-8 encoded text represented as Base64Url.</summary>
         <returns>One of the enumeration values that indicates the success or failure of the operation.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
       </Docs>
     </Member>
     <Member MemberName="GetEncodedLength">
@@ -926,7 +926,7 @@
         <summary>Encodes the span of binary data into Unicode ASCII chars represented as Base64Url.</summary>
         <returns>
           <see langword="true" /> if chars encoded successfully; <see langword="false" /> if <paramref name="destination" /> is too small.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
       </Docs>
     </Member>
     <Member MemberName="TryEncodeToUtf8">
@@ -962,7 +962,7 @@
         <summary>Encodes the span of binary data into UTF-8 encoded chars represented as Base64Url.</summary>
         <returns>
           <see langword="true" /> if bytes encoded successfully; <see langword="false" /> if <paramref name="destination" /> is too small.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
       </Docs>
     </Member>
     <Member MemberName="TryEncodeToUtf8InPlace">
@@ -1007,7 +1007,7 @@
         </summary>
         <returns>
           <see langword="true" /> if bytes encoded successfully; <see langword="false" /> if <paramref name="buffer" /> is too small to fit the result.</returns>
-        <remarks>This implementation of the base64url encoding omits the optional padding characters.</remarks>
+        <remarks>This implementation of the Base64Url encoding omits the optional padding characters. The encoding uses '-' and '_' instead of the '+' and '/' characters used in standard Base64 encoding.</remarks>
       </Docs>
     </Member>
   </Members>

xml/System.Diagnostics/DebuggerDisplayAttribute.xml

@@ -212,7 +212,7 @@ class MyTable
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- The value can contain curly braces ({ and }). Text within a pair of braces is evaluated as the name of a field, property, or method.
+The value can contain curly braces ({ and }). Text within a pair of braces is evaluated as the name of a field, property, or method. You can also use format specifiers within the braces to control how values are displayed. For information about debugger format specifiers, see [Format Specifiers in C#](/visualstudio/debugger/format-specifiers-in-csharp).
 
 
 
@@ -377,7 +377,14 @@ class MyTable
       <Docs>
         <summary>Gets or sets the string to display in the type column of the debugger variable windows.</summary>
         <value>The string to display in the type column of the debugger variable windows.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+The value can contain curly braces ({ and }). Text within a pair of braces is evaluated as the name of a field, property, or method. You can also use format specifiers within the braces to control how values are displayed. For information about debugger format specifiers, see [Format Specifiers in C#](/visualstudio/debugger/format-specifiers-in-csharp).
+
+]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="Value">
@@ -432,9 +439,11 @@ class MyTable
           <format type="text/markdown"><![CDATA[
 
 ## Remarks
- This property contains the string passed in by the `value` parameter of the constructor.
+This property contains the string passed in by the `value` parameter of the constructor.
 
- ]]></format>
+The value can contain curly braces ({ and }). Text within a pair of braces is evaluated as the name of a field, property, or method. You can also use format specifiers within the braces to control how values are displayed. For information about debugger format specifiers, see [Format Specifiers in C#](/visualstudio/debugger/format-specifiers-in-csharp).
+
+]]></format>
         </remarks>
       </Docs>
     </Member>

xml/System.Globalization/CultureInfo.xml

@@ -3378,7 +3378,7 @@ The following code example shows that CultureInfo.Clone also clones the <xref:Sy
  The following code example displays several properties of the neutral cultures.
 
 > [!NOTE]
-> The example displays the older `zh-CHS` and `zh-CHT` culture names with the 0x0004 and 0x7C04 culture identifiers, respectively. However, your Windows Vista applications should use the `zh-Hans` name instead of zh-CHS and the `zh-Hant` name instead of zh-CHT. The `zh-Hans` and `zh-Hant` names represent the current standard, and should be used unless you have a reason for using the older names.
+> The `zh-Hans` and `zh-Hant` names represent the current standard for Chinese cultures. Older applications might reference the legacy `zh-CHS` and `zh-CHT` culture names, but these should be replaced with `zh-Hans` and `zh-Hant` respectively in modern applications.
 
  :::code language="csharp" source="~/snippets/csharp/System.Globalization/CultureInfo/DisplayName/getcultures.cs" id="Snippet1":::
  :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CultureInfo.GetCultures/VB/getcultures.vb" id="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>

xml/System.Net/IPAddress.xml

@@ -2721,10 +2721,10 @@ The scope identifier is &gt; 0x00000000FFFFFFFF</exception>
         <Parameter Name="provider" Type="System.IFormatProvider" Index="1" FrameworkAlternate="net-10.0" />
       </Parameters>
       <Docs>
-        <param name="utf8Text">To be added.</param>
-        <param name="provider">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="utf8Text">The span of UTF-8 characters to parse.</param>
+        <param name="provider">An object that provides culture-specific formatting information about <paramref name="utf8Text" />.</param>
+        <summary>Parses a span of UTF-8 characters into a value.</summary>
+        <returns>The result of parsing <paramref name="utf8Text" />.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>