diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000000..683b79f69d9 --- /dev/null +++ b/.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. diff --git a/snippets/csharp/System.Globalization/CultureInfo/DisplayName/getcultures.cs b/snippets/csharp/System.Globalization/CultureInfo/DisplayName/getcultures.cs index 8dbea378b36..9379c6bbbc4 100644 --- a/snippets/csharp/System.Globalization/CultureInfo/DisplayName/getcultures.cs +++ b/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. */ // diff --git a/snippets/csharp/System.Net.Http/WinHttpHandler/Project.csproj b/snippets/csharp/System.Net.Http/WinHttpHandler/Project.csproj new file mode 100644 index 00000000000..c99f5065527 --- /dev/null +++ b/snippets/csharp/System.Net.Http/WinHttpHandler/Project.csproj @@ -0,0 +1,12 @@ + + + + Library + net9.0 + + + + + + + \ No newline at end of file diff --git a/snippets/csharp/System.Net.Http/WinHttpHandler/program.cs b/snippets/csharp/System.Net.Http/WinHttpHandler/program.cs new file mode 100644 index 00000000000..47d739424ca --- /dev/null +++ b/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; + } + // + 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; + }; + // + } +} diff --git a/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Chain/Overview/chainelements-ordering.cs b/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Chain/Overview/chainelements-ordering.cs new file mode 100644 index 00000000000..8e0071a11e4 --- /dev/null +++ b/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) + { +// + 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}"); + } +// + } +} \ No newline at end of file diff --git a/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CultureInfo.GetCultures/VB/getcultures.vb b/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CultureInfo.GetCultures/VB/getcultures.vb index c2e2d571fd7..3b4c6c22f38 100644 --- a/snippets/visualbasic/VS_Snippets_CLR_System/system.Globalization.CultureInfo.GetCultures/VB/getcultures.vb +++ b/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 ' diff --git a/xml/System.Buffers.Text/Base64Url.xml b/xml/System.Buffers.Text/Base64Url.xml index 5f70c246fb9..e215cd16231 100644 --- a/xml/System.Buffers.Text/Base64Url.xml +++ b/xml/System.Buffers.Text/Base64Url.xml @@ -27,7 +27,7 @@ Converts between binary data and URL-safe ASCII encoded text that's represented in Base64Url characters. - To be added. + 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. @@ -373,7 +373,7 @@ The input span which contains binary data that needs to be encoded. Encodes the span of binary data into unicode ASCII chars represented as Base64Url. A char array which contains the result of the operation, i.e. the ASCII chars in Base64Url. - This implementation of the base64url encoding omits the optional padding characters. + 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. @@ -406,7 +406,7 @@ The output span which contains the result of the operation, i.e. the ASCII chars in Base64Url. Encodes the span of binary data into Unicode ASCII chars represented as Base64Url. The number of bytes written into the destination span. This can be used to slice the output for subsequent calls, if necessary. - This implementation of the base64url encoding omits the optional padding characters. + 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. The buffer in is too small to hold the encoded output. @@ -449,7 +449,7 @@ Encodes the span of binary data into unicode ASCII chars represented as Base64Url. One of the enumeration values that indicates the success or failure of the operation. - This implementation of the base64url encoding omits the optional padding characters. + 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. @@ -486,7 +486,7 @@ The input span that contains binary data that needs to be encoded. Encodes the span of binary data into Unicode string represented as Base64Url ASCII chars. A string that contains the result of the operation, i.e. the ASCII string in Base64Url. - This implementation of the base64url encoding omits the optional padding characters. + 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. @@ -523,7 +523,7 @@ The input span which contains binary data that needs to be encoded. Encodes the span of binary data into UTF-8 encoded text represented as Base64Url. The output byte array which contains the result of the operation, i.e. the UTF-8 encoded text in Base64Url. - This implementation of the base64url encoding omits the optional padding characters. + 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. @@ -556,7 +556,7 @@ The output span which contains the result of the operation, i.e. the UTF-8 encoded text in Base64Url. Encodes the span of binary data into UTF-8 encoded text represented as Base64Url. The number of bytes written into the destination span. This can be used to slice the output for subsequent calls, if necessary. - This implementation of the base64url encoding omits the optional padding characters. + 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. The buffer in is too small to hold the encoded output. @@ -599,7 +599,7 @@ Encodes the span of binary data into UTF-8 encoded text represented as Base64Url. One of the enumeration values that indicates the success or failure of the operation. - This implementation of the base64url encoding omits the optional padding characters. + 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. @@ -926,7 +926,7 @@ Encodes the span of binary data into Unicode ASCII chars represented as Base64Url. if chars encoded successfully; if is too small. - This implementation of the base64url encoding omits the optional padding characters. + 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. @@ -962,7 +962,7 @@ Encodes the span of binary data into UTF-8 encoded chars represented as Base64Url. if bytes encoded successfully; if is too small. - This implementation of the base64url encoding omits the optional padding characters. + 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. @@ -1007,7 +1007,7 @@ if bytes encoded successfully; if is too small to fit the result. - This implementation of the base64url encoding omits the optional padding characters. + 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. diff --git a/xml/System.Diagnostics/DebuggerDisplayAttribute.xml b/xml/System.Diagnostics/DebuggerDisplayAttribute.xml index 199078b9bb8..abffb2f1703 100644 --- a/xml/System.Diagnostics/DebuggerDisplayAttribute.xml +++ b/xml/System.Diagnostics/DebuggerDisplayAttribute.xml @@ -212,7 +212,7 @@ class MyTable Gets or sets the string to display in the type column of the debugger variable windows. The string to display in the type column of the debugger variable windows. - To be added. + + + @@ -432,9 +439,11 @@ class MyTable +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). + +]]> diff --git a/xml/System.Globalization/CultureInfo.xml b/xml/System.Globalization/CultureInfo.xml index b438608fc5f..8dc23575fda 100644 --- a/xml/System.Globalization/CultureInfo.xml +++ b/xml/System.Globalization/CultureInfo.xml @@ -3378,7 +3378,7 @@ The following code example shows that CultureInfo.Clone also clones the [!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"::: diff --git a/xml/System.Net.Http/WinHttpHandler.xml b/xml/System.Net.Http/WinHttpHandler.xml index 13d3f0dfc25..6f311881e4c 100644 --- a/xml/System.Net.Http/WinHttpHandler.xml +++ b/xml/System.Net.Http/WinHttpHandler.xml @@ -740,13 +740,20 @@ When this property is set to `true`, all HTTP redirect responses from the server Gets or sets a callback method to validate the server certificate. This callback is part of the SSL handshake. - The callback should return if the server certificate is considered valid and the request should be sent. Otherwise, return . + The callback should return if the server certificate is considered valid and the request should be sent. Otherwise, returns . 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"::: ]]> diff --git a/xml/System.Net/IPAddress.xml b/xml/System.Net/IPAddress.xml index d5a2fc31892..817e73e22e8 100644 --- a/xml/System.Net/IPAddress.xml +++ b/xml/System.Net/IPAddress.xml @@ -2721,10 +2721,10 @@ The scope identifier is > 0x00000000FFFFFFFF - To be added. - To be added. - To be added. - To be added. + The span of UTF-8 characters to parse. + An object that provides culture-specific formatting information about . + Parses a span of UTF-8 characters into a value. + The result of parsing . To be added. diff --git a/xml/System.Net/IPNetwork.xml b/xml/System.Net/IPNetwork.xml index 1f35931338e..22dc3281225 100644 --- a/xml/System.Net/IPNetwork.xml +++ b/xml/System.Net/IPNetwork.xml @@ -678,10 +678,10 @@ - To be added. - To be added. - To be added. - To be added. + The span of UTF-8 characters to parse. + An object that provides culture-specific formatting information about . + Parses a span of UTF-8 characters into a value. + The result of parsing . To be added. diff --git a/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml b/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml index 676251844af..0d6e23e2cda 100644 --- a/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml +++ b/xml/System.Security.Cryptography.X509Certificates/X509Certificate.xml @@ -3308,8 +3308,8 @@ The output of this method is equivalent to the output of the - Returns the serial number of the X.509v3 certificate as a little-endian hexadecimal string . - The serial number of the X.509 certificate as a little-endian hexadecimal string. + Returns the serial number of the X.509v3 certificate as a big-endian hexadecimal string. + The serial number of the X.509 certificate as a big-endian hexadecimal string. object, an structure, and an extra information string. - + The `ChainElements` collection is ordered from the end-entity (leaf) certificate at index 0, through any intermediate certificates, to the trust anchor (root certificate) at the final index. This ordering is consistent across all platforms. ## Examples +The following code example demonstrates the ordering of chain elements: + +:::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Chain/Overview/chainelements-ordering.cs" id="Snippet6"::: + The following code example opens the current user's personal certificate store, allows you to select a certificate, then writes certificate and certificate chain information to the console. The output depends on the certificate you select. :::code language="csharp" source="~/snippets/csharp/System.Security.Cryptography.X509Certificates/X509Chain/Overview/x509chaintest.cs" id="Snippet4"::: diff --git a/xml/System.Text.Json/Utf8JsonWriter.xml b/xml/System.Text.Json/Utf8JsonWriter.xml index dba64dd07f6..b7de000ea3e 100644 --- a/xml/System.Text.Json/Utf8JsonWriter.xml +++ b/xml/System.Text.Json/Utf8JsonWriter.xml @@ -781,8 +781,8 @@ The bytes are encoded before writing. - The binary data to be written as a Base64 encoded JSON string element of a JSON array. - Writes the raw bytes value as a Base64 encoded JSON string as an element of a JSON array. + The binary data to be written as a Base64 encoded JSON string. + Writes the raw bytes value as a Base64 encoded JSON string. - The value to be written as a JSON literal true or false as an element of a JSON array. - Writes a value (as a JSON literal true or false) as an element of a JSON array. + The value to be written as a JSON literal true or false. + Writes a value (as a JSON literal true or false). To be added. Validation is enabled, and the operation would result in writing invalid JSON. @@ -1381,7 +1381,7 @@ The property name should already be escaped when the instance of - Writes the JSON literal null as an element of a JSON array. + Writes the JSON literal null. To be added. Validation is enabled, and the operation would result in writing invalid JSON. @@ -2720,8 +2720,8 @@ The property name should already be escaped when the instance of - The value to be written as a JSON number as an element of a JSON array. - Writes a value (as a JSON number) as an element of a JSON array. + The value to be written as a JSON number. + Writes a value (as a JSON number). value using the default - The value to be written as a JSON number as an element of a JSON array. - Writes a value (as a JSON number) as an element of a JSON array. + The value to be written as a JSON number. + Writes a value (as a JSON number). value using the default - The value to be written as a JSON number as an element of a JSON array. - Writes an value (as a JSON number) as an element of a JSON array. + The value to be written as a JSON number. + Writes an value (as a JSON number). value using the default - The value to be written as a JSON number as an element of a JSON array. - Writes an value (as a JSON number) as an element of a JSON array. + The value to be written as a JSON number. + Writes an value (as a JSON number). value using the default - The value to be written as a JSON number as an element of a JSON array. - Writes a value (as a JSON number) as an element of a JSON array. + The value to be written as a JSON number. + Writes a value (as a JSON number). value using the default - The value to be written as a JSON number as an element of a JSON array. - Writes a value (as a JSON number) as an element of a JSON array. + The value to be written as a JSON number. + Writes a value (as a JSON number). value using the default - The value to be written as a JSON number as an element of a JSON array. - Writes a value (as a JSON number) as an element of a JSON array. + The value to be written as a JSON number. + Writes a value (as a JSON number). - The value to be written as a JSON string as an element of a JSON array. - Writes a value (as a JSON string) as an element of a JSON array. + The value to be written as a JSON string. + Writes a value (as a JSON string). - The value to be written as a JSON string as an element of a JSON array. - Writes a value (as a JSON string) as an element of a JSON array. + The value to be written as a JSON string. + Writes a value (as a JSON string). using the ISO 8601-1 extende - The value to be written as a JSON string as an element of a JSON array. - Writes a value (as a JSON string) as an element of a JSON array. + The value to be written as a JSON string. + Writes a value (as a JSON string). value using the default - The UTF-8 encoded value to be written as a JSON string element of a JSON array. - Writes a UTF-8 text value (as a JSON string) as an element of a JSON array. + The UTF-8 encoded value to be written as a JSON string. + Writes a UTF-8 text value (as a JSON string). - The UTF-16 encoded value to be written as a UTF-8 transcoded JSON string element of a JSON array. - Writes a UTF-16 text value (as a JSON string) as an element of a JSON array. + The UTF-16 encoded value to be written as a UTF-8 transcoded JSON string. + Writes a UTF-16 text value (as a JSON string). - The UTF-16 encoded value to be written as a UTF-8 transcoded JSON string element of a JSON array. - Writes a string text value (as a JSON string) as an element of a JSON array. + The UTF-16 encoded value to be written as a UTF-8 transcoded JSON string. + Writes a string text value (as a JSON string). - The JSON encoded value to be written as a UTF-8 transcoded JSON string element of a JSON array. - Writes the pre-encoded text value (as a JSON string) as an element of a JSON array. + The JSON encoded value to be written as a UTF-8 transcoded JSON string. + Writes the pre-encoded text value (as a JSON string). method returns a string containing the leftmost portion of the URI string, ending with the portion specified by `part`. +> [!IMPORTANT] +> The method performs Unicode character encoding and normalization as part of its processing. It is not a simple string manipulation method. The returned string may differ from the original URI string due to this encoding behavior. + +The method is equivalent to calling with the appropriate flags. For example: +- `GetLeftPart(UriPartial.Authority)` is equivalent to `GetComponents(UriComponents.Scheme | UriComponents.UserInfo | UriComponents.Host | UriComponents.Port, UriFormat.UriEscaped)` + includes delimiters in the following cases: - includes the scheme delimiter.