From e1453ed21ecc8a1dab3503199a7a343fbdef3671 Mon Sep 17 00:00:00 2001 From: Steve Molloy Date: Thu, 23 Jul 2026 11:35:50 -0700 Subject: [PATCH 1/3] Clarify ISerializable applies to formatters, not XmlSerializer (#12897) Fixes #9658 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 40a09be5-c644-4e7e-9262-c7bb073feba3 --- xml/System.Runtime.Serialization/ISerializable.xml | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/xml/System.Runtime.Serialization/ISerializable.xml b/xml/System.Runtime.Serialization/ISerializable.xml index 6c295b25c40..d02bd0526c1 100644 --- a/xml/System.Runtime.Serialization/ISerializable.xml +++ b/xml/System.Runtime.Serialization/ISerializable.xml @@ -48,12 +48,12 @@ - Allows an object to control its own serialization and deserialization through binary and XML serialization. + Allows an object to control its own serialization and deserialization during formatter-based (binary and SOAP) serialization. . If a class needs to control its binary or XML serialization process, it can implement the interface. The calls the at serialization time and populates the supplied with all the data required to represent the object. The creates a with the type of the object in the graph. Objects that need to send proxies for themselves can use the and methods on to change the transmitted information. + Any class that might be serialized by a formatter, such as or `SoapFormatter`, must be marked with the . If a class needs to control this formatter-based serialization process, it can implement the interface. The calls the at serialization time and populates the supplied with all the data required to represent the object. The creates a with the type of the object in the graph. Objects that need to send proxies for themselves can use the and methods on to change the transmitted information. In the case of class inheritance, it is possible to serialize a class that derives from a base class that implements . In this case, the derived class should call the base class implementation of inside its implementation of . Otherwise, the data from the base class will not be serialized. @@ -69,6 +69,9 @@ For more information about serialization of classes that extend , see . For more information about implementing , see [Custom Serialization](/dotnet/standard/serialization/custom-serialization). +> [!IMPORTANT] +> This interface applies only to formatter-based serialization, such as with and `SoapFormatter`. Here, *XML serialization* refers to the SOAP format produced by `SoapFormatter`, not to . ignores . To control how a type is serialized by , implement instead. + > [!NOTE] > This interface does not apply to JSON serialization using . @@ -77,6 +80,7 @@ Implement this interface to allow an object to take part in its own serialization and deserialization. + XML and SOAP Serialization Custom serialization From 580db72514574d9b5ad026921451d191e6c98dcb Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 23 Jul 2026 11:52:49 -0700 Subject: [PATCH 2/3] Revise README for .NET 8 and Framework references (#12899) Updated README to include .NET 8 and .NET Framework API reference. --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b9400709646..ed4591d264a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # .NET API Reference Docs -This repository contains documentation for the .NET API reference. We track all work for this repository using [GitHub issues](https://github.com/dotnet/dotnet-api-docs/issues). The documentation for APIs is built from the text and code snippets in this repo, and from the samples in the [dotnet/samples](https://github.com/dotnet/samples) repository. +This repository contains documentation for the .NET API reference for .NET 8+ and package-provided APIs. We track all work for this repository using [GitHub issues](https://github.com/dotnet/dotnet-api-docs/issues). The documentation for APIs is built from the text and code snippets in this repo, and from the samples in the [dotnet/samples](https://github.com/dotnet/samples) repository. + +For .NET Framework API reference, see the [dotnet/dotnetfw-api-docs](https://github.com/dotnet/dotnetfw-api-docs) repository. The repository for conceptual .NET documentation is the [dotnet/docs repository](https://github.com/dotnet/docs). From 41f3098c4e8c525f8aae25ab3ded236a5461fada Mon Sep 17 00:00:00 2001 From: Tanner Gooding Date: Fri, 24 Jul 2026 09:14:08 -0700 Subject: [PATCH 3/3] Port missing .NET 8.0 System API docs from dotnet/runtime#88563 (#12901) * Port missing .NET 8.0 System API docs from dotnet/runtime#88563 Fill in the remaining `To be added.` documentation placeholders for the .NET 8.0 System APIs tracked by dotnet/runtime#88563, matching the wording of already-documented sibling members in each file. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * Address review feedback: clarify Guid.TryWriteBytes destination and fix BinaryData.WithMediaType summary grammar Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- xml/System/BinaryData.xml | 4 +- xml/System/Boolean.xml | 22 ++++++----- xml/System/ConsoleKey.xml | 2 +- xml/System/ConsoleModifiers.xml | 2 +- xml/System/DateTimeOffset.xml | 2 +- xml/System/Enum.xml | 4 +- xml/System/Guid.xml | 39 +++++++++++-------- xml/System/MemoryExtensions.xml | 68 +++++++++++++++++---------------- xml/System/OperatingSystem.xml | 3 +- xml/System/String.xml | 22 ++++++----- xml/System/TimeProvider.xml | 4 +- xml/System/TimeSpan.xml | 2 +- xml/System/TimeZoneInfo.xml | 2 +- 13 files changed, 96 insertions(+), 80 deletions(-) diff --git a/xml/System/BinaryData.xml b/xml/System/BinaryData.xml index 6f7edfc0897..6c32068d2fe 100644 --- a/xml/System/BinaryData.xml +++ b/xml/System/BinaryData.xml @@ -1290,9 +1290,9 @@ No special treatment is given to the contents of the data. It is merely decoded - To be added. + The MIME type of this data, for example, . - Creates a instance by wrapping the same data and changed to value. + Creates a instance by wrapping the same data and changing the to . A wrapper over the same data with specified . To be added. diff --git a/xml/System/Boolean.xml b/xml/System/Boolean.xml index 1a4300507b4..6e930cda849 100644 --- a/xml/System/Boolean.xml +++ b/xml/System/Boolean.xml @@ -1586,11 +1586,12 @@ This member is an explicit interface member implementation. It can be used only - To be added. - To be added. - To be added. - To be added. - To be added. + The string to parse. + An object that provides culture-specific formatting information about . + When this method returns, contains the result of successfully parsing , or an undefined value on failure. + Tries to parse a string into a value. + + if was successfully parsed; otherwise, . To be added. @@ -1657,11 +1658,12 @@ This member is an explicit interface member implementation. It can be used only - To be added. - To be added. - To be added. - To be added. - To be added. + The span of characters to parse. + An object that provides culture-specific formatting information about . + When this method returns, contains the result of successfully parsing , or an undefined value on failure. + Tries to parse a span of characters into a value. + + if was successfully parsed; otherwise, . To be added. diff --git a/xml/System/ConsoleKey.xml b/xml/System/ConsoleKey.xml index 47b4fac05a5..037cae87cd2 100644 --- a/xml/System/ConsoleKey.xml +++ b/xml/System/ConsoleKey.xml @@ -3005,7 +3005,7 @@ 0 - To be added. + No key was pressed. diff --git a/xml/System/ConsoleModifiers.xml b/xml/System/ConsoleModifiers.xml index 36d60976f25..e7759fca186 100644 --- a/xml/System/ConsoleModifiers.xml +++ b/xml/System/ConsoleModifiers.xml @@ -159,7 +159,7 @@ 0 - To be added. + No modifier key. diff --git a/xml/System/DateTimeOffset.xml b/xml/System/DateTimeOffset.xml index 008717f9e55..e9762101a4c 100644 --- a/xml/System/DateTimeOffset.xml +++ b/xml/System/DateTimeOffset.xml @@ -5857,7 +5857,7 @@ Me.ToUtcDateTime().ToFileTime() The span in which to write this instance's value formatted as a span of bytes. When this method returns, contains the number of bytes that were written in . A span containing the characters that represent a standard or custom format string that defines the acceptable format for . - To be added. + An optional object that supplies culture-specific formatting information for . Tries to format the value of the current instance as UTF-8 into the provided span of bytes. if the formatting was successful; otherwise, . diff --git a/xml/System/Enum.xml b/xml/System/Enum.xml index f73d0c367a1..e285669b06c 100644 --- a/xml/System/Enum.xml +++ b/xml/System/Enum.xml @@ -3493,8 +3493,8 @@ The following example demonstrates using an enumeration to represent named value - To be added. - To be added. + The type of the enumeration. + The enumeration value to format. The span into which to write the instance's value formatted as a span of characters. When this method returns, contains the number of characters that were written in . A span containing the character that represents the standard format string that defines the acceptable format of destination. This value can be empty, or "g", "d", "f", or "x". diff --git a/xml/System/Guid.xml b/xml/System/Guid.xml index 0d83feaf929..6acd7f6057b 100644 --- a/xml/System/Guid.xml +++ b/xml/System/Guid.xml @@ -289,10 +289,13 @@ - To be added. - To be added. - To be added. + A 16-element read-only span containing the bytes with which to initialize the GUID. + + to interpret as big-endian; to interpret it as little-endian. + Initializes a new instance of the structure by using the value represented by the specified read-only span of bytes and the specified endianness. To be added. + + is not 16 bytes long. @@ -1888,9 +1891,10 @@ The method requires the read-only character span - To be added. - To be added. - To be added. + + to write the bytes in big-endian byte order; to write them in little-endian byte order. + Returns a 16-element byte array that contains the value of this instance, using the specified endianness. + A 16-element byte array. To be added. @@ -2134,11 +2138,12 @@ The method requires the read-only character span - To be added. - To be added. - To be added. - To be added. - To be added. + The span in which to write the GUID as a span of UTF-8 bytes. + When this method returns, contains the number of bytes written into . + A read-only span containing the character representing one of the following specifiers that indicates the exact format to use when interpreting the current GUID instance: "N", "D", "B", "P", or "X". + Tries to format the current GUID instance as UTF-8 into the provided span of bytes. + + if the formatting operation was successful; otherwise. To be added. @@ -2656,11 +2661,13 @@ The method requires the read-only character span - To be added. - To be added. - To be added. - To be added. - To be added. + The span in which to write the GUID as a span of bytes. + + to write the bytes in big-endian byte order; to write them in little-endian byte order. + When this method returns, contains the number of bytes written into . + Tries to write the current GUID instance into a span of bytes, using the specified endianness. + + if the GUID is successfully written to the specified span; otherwise. To be added. diff --git a/xml/System/MemoryExtensions.xml b/xml/System/MemoryExtensions.xml index 385076642d1..fff5a954fd4 100644 --- a/xml/System/MemoryExtensions.xml +++ b/xml/System/MemoryExtensions.xml @@ -799,7 +799,7 @@ Returns `default` when `text` is `null`. The target string. The index at which to begin this slice. Creates a new over a portion of the target string from a specified position to the end of the string. - To be added. + The read-only span representation of the string. To be added. is less than 0 or greater than .Length. @@ -885,7 +885,7 @@ Returns `default` when `text` is `null`. The target string. The range that has start and end indexes to use for slicing the string. Creates a new over a portion of a target string using the range start and end indexes. - To be added. + The read-only span representation of the string. To be added. is . @@ -2532,7 +2532,7 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The set of values to search for. Searches for an occurrence of any of the specified . @@ -2588,7 +2588,7 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The set of values to search for. Searches for an occurrence of any of the specified . @@ -2650,11 +2650,12 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The set of values to search for. Searches for an occurrence of any of the specified and returns if found. If not found, returns . - To be added. + + if found. If not found, returns . To be added. @@ -2712,11 +2713,12 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The set of values to search for. Searches for an occurrence of any of the specified and returns if found. If not found, returns . - To be added. + + if found. If not found, returns . To be added. @@ -2825,7 +2827,7 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The first value to search for. The second value to search for. @@ -2888,12 +2890,13 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The first value to search for. The second value to search for. Searches for an occurrence of or , and returns if found. If not found, returns . - To be added. + + if found. If not found, returns . To be added. @@ -3006,7 +3009,7 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The first value to search for. The second value to search for. @@ -3071,7 +3074,7 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The first value to search for. The second value to search for. @@ -3197,7 +3200,7 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The set of values to exclude from the search. Searches the specified span for any value other than the specified . @@ -3253,7 +3256,7 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The set of values to exclude from the search. Searches the specified span for any value other than the specified . @@ -3309,7 +3312,7 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The value to exclude from the search. Searches the specified span for any value other than the specified . @@ -3371,7 +3374,7 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The set of values to exclude from the search. Searches the specified span for any value other than the specified . @@ -3434,7 +3437,7 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The set of values to exclude from the search. Searches the specified span for any value other than the specified . @@ -3497,7 +3500,7 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The value to exclude from the search. Searches the specified span for any value other than the specified . @@ -3672,7 +3675,7 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The first value to exclude from the search. The second value to exclude from the search. @@ -3735,7 +3738,7 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The first value to exclude from the search. The second value to exclude from the search. @@ -3855,7 +3858,7 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The first value to exclude from the search. The second value to exclude from the search. @@ -3920,7 +3923,7 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The first value to exclude from the search. The second value to exclude from the search. @@ -4047,7 +4050,7 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The lower bound, inclusive, of the excluded range. The upper bound, inclusive, of the excluded range. @@ -4110,7 +4113,7 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The lower bound, inclusive, of the excluded range. The upper bound, inclusive, of the excluded range. @@ -4174,7 +4177,7 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The lower bound, inclusive, of the range for which to search. The upper bound, inclusive, of the range for which to search. @@ -4237,12 +4240,13 @@ Returns `default` when `array` is `null`. - To be added. + The type of the elements in the span. The span to search. The lower bound, inclusive, of the range for which to search. The upper bound, inclusive, of the range for which to search. Searches for any value in the range between and , inclusive, and returns if found. If not found, returns . - To be added. + + if found. If not found, returns . To be added. @@ -6005,7 +6009,7 @@ Invalid sequences will be represented in the enumeration by - To be added. + The type of the elements in the span. The span to search. The set of values to search for. Searches for the first index of any of the specified values. @@ -6122,7 +6126,7 @@ Invalid sequences will be represented in the enumeration by - To be added. + The type of the elements in the span. The span to search. The set of values to search for. Searches for the first index of any of the specified values. @@ -8239,7 +8243,7 @@ Invalid sequences will be represented in the enumeration by - To be added. + The type of the elements in the span. The span to search. The set of values to search for. Searches for the last index of any of the specified values. @@ -8356,7 +8360,7 @@ Invalid sequences will be represented in the enumeration by - To be added. + The type of the elements in the span. The span to search. The set of values to search for. Searches for the last index of any of the specified values. diff --git a/xml/System/OperatingSystem.xml b/xml/System/OperatingSystem.xml index a48726ea4ec..621464c1801 100644 --- a/xml/System/OperatingSystem.xml +++ b/xml/System/OperatingSystem.xml @@ -858,7 +858,8 @@ Indicates whether the current application is running as WASI. - To be added. + + if the current application is running as WASI; otherwise. To be added. diff --git a/xml/System/String.xml b/xml/System/String.xml index 03379d01abd..12f6cced7d0 100644 --- a/xml/System/String.xml +++ b/xml/System/String.xml @@ -14498,11 +14498,12 @@ This member is an explicit interface member implementation. It can be used only - To be added. - To be added. - To be added. - To be added. - To be added. + The string to parse. + An object that provides culture-specific formatting information about . + When this method returns, contains the result of successfully parsing , or an undefined value on failure. + Tries to parse a string into a value. + + if was successfully parsed; otherwise, . To be added. @@ -14576,11 +14577,12 @@ This member is an explicit interface member implementation. It can be used only - To be added. - To be added. - To be added. - To be added. - To be added. + The span of characters to parse. + An object that provides culture-specific formatting information about . + When this method returns, contains the result of successfully parsing , or an undefined value on failure. + Tries to parse a span of characters into a value. + + if was successfully parsed; otherwise, . To be added. diff --git a/xml/System/TimeProvider.xml b/xml/System/TimeProvider.xml index 3684a831cdc..f5c1803abd3 100644 --- a/xml/System/TimeProvider.xml +++ b/xml/System/TimeProvider.xml @@ -277,7 +277,7 @@ Gets a value that is set to the current date and time according to this 's notion of time based on , with the offset set to the 's offset from Coordinated Universal Time (UTC). - To be added. + A value that is set to the current date and time in the local time zone, according to this provider's notion of time. To be added. @@ -357,7 +357,7 @@ Coordinated Universal Time (UTC) date and time and whose offset is Zero, all according to this 's notion of time. - To be added. + A value that is set to the current Coordinated Universal Time (UTC) date and time, according to this provider's notion of time. The default implementation returns . diff --git a/xml/System/TimeSpan.xml b/xml/System/TimeSpan.xml index e3b117d2f70..b0d1c83181f 100644 --- a/xml/System/TimeSpan.xml +++ b/xml/System/TimeSpan.xml @@ -5579,7 +5579,7 @@ The property represents whole and fracti The span in which to write this instance's value formatted as a span of bytes. When this method returns, contains the number of bytes that were written in . A span containing the characters that represent a standard or custom format string that defines the acceptable format for . - To be added. + An optional object that supplies culture-specific formatting information for . Tries to format the value of the current instance as UTF-8 into the provided span of bytes. if the formatting was successful; otherwise, . diff --git a/xml/System/TimeZoneInfo.xml b/xml/System/TimeZoneInfo.xml index af8a38d8b66..f74bf92a0a8 100644 --- a/xml/System/TimeZoneInfo.xml +++ b/xml/System/TimeZoneInfo.xml @@ -2132,7 +2132,7 @@ The following example uses the If , The collection returned may not necessarily be sorted. Returns a containing all valid TimeZone's from the local machine. This method does *not* throw TimeZoneNotFoundException or InvalidTimeZoneException. - To be added. + A read-only collection of objects. By setting the skipSorting parameter to , the method will attempt to avoid sorting the returned collection. This option can be beneficial when the caller does not require a sorted list and aims to enhance the performance.