Add XML roundtripping documentation for carriage return entities (#47034)

* Initial plan

* Add XML roundtripping section with carriage return entity documentation

Co-authored-by: BillWagner <[email protected]>

* Move code samples to snippet files and fix raw string literal format

Co-authored-by: BillWagner <[email protected]>

* Fix code samples to compile in documentation environment and update target framework to net9.0

Co-authored-by: BillWagner <[email protected]>

* Restructure code samples to use single Program class with Example methods and fix target framework

Co-authored-by: BillWagner <[email protected]>

* Add snippet tags to filter displayed code sections

Co-authored-by: BillWagner <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: BillWagner <[email protected]>

Author: Copilot

docs/standard/linq/preserve-white-space-serializing.md

@@ -25,3 +25,31 @@ The following methods in the <xref:System.Xml.Linq.XElement> and <xref:System.Xm
 If the method doesn't take <xref:System.Xml.Linq.SaveOptions> as an argument, then the method will format (indent) the serialized XML. In this case, all insignificant white space in the XML tree is discarded.
 
 If the method does take <xref:System.Xml.Linq.SaveOptions> as an argument, then you can specify that the method not format (indent) the serialized XML. In this case, all white space in the XML tree is preserved.
+
+## Roundtripping XML with carriage return entities
+
+The whitespace preservation discussed in this article is different from XML roundtripping. When XML contains carriage return entities (`&#xD;`), LINQ to XML's standard serialization might not preserve them in a way that allows perfect roundtripping.
+
+Consider the following example XML that contains carriage return entities:
+
+```xml
+<x xml:space="preserve">a&#xD;
+b
+c&#xD;</x>
+```
+
+When you parse this XML with `XDocument.Parse()`, the root element's value becomes `"a\r\nb\nc\r"`. However, if you reserialize it using LINQ to XML methods, the carriage returns are not entitized:
+
+:::code language="csharp" source="snippets/preserve-white-space-serializing/RoundtrippingProblem.cs" Id="XmlRoundTrip":::
+
+The values are different: the original was `"a\r\nb\nc\r"` but after roundtripping it becomes `"a\nb\nc\n"`.
+
+### Solution: Use XmlWriter with NewLineHandling.Entitize
+
+To achieve true XML roundtripping that preserves carriage return entities, use <xref:System.Xml.XmlWriter> with <xref:System.Xml.XmlWriterSettings.NewLineHandling> set to <xref:System.Xml.NewLineHandling.Entitize>:
+
+:::code language="csharp" source="snippets/preserve-white-space-serializing/RoundtrippingSolution.cs" Id="XmlRoundTripFix":::
+
+When you need to preserve carriage return entities for XML roundtripping, use <xref:System.Xml.XmlWriter> with the appropriate <xref:System.Xml.XmlWriterSettings> instead of LINQ to XML's built-in serialization methods.
+
+For more information about <xref:System.Xml.XmlWriter> and its settings, see <xref:System.Xml.XmlWriter?displayProperty=fullName>.

docs/standard/linq/snippets/preserve-white-space-serializing/RoundtrippingProblem.cs

@@ -0,0 +1,46 @@
+using System;
+using System.Linq;
+using System.Xml.Linq;
+
+class Program
+{
+    static void Main()
+    {
+        Console.WriteLine("XML Roundtripping Examples");
+        Console.WriteLine("==========================");
+        
+        Console.WriteLine("\n1. Roundtripping Problem:");
+        RoundtrippingProblem.Example();
+        
+        Console.WriteLine("\n2. Roundtripping Solution:");
+        RoundtrippingSolution.Example();
+    }
+}
+
+public static class RoundtrippingProblem
+{
+    public static void Example()
+    {
+        // <XmlRoundTrip>
+        string xmlWithCR = """
+            <x xml:space="preserve">a&#xD;
+            b
+            c&#xD;</x>
+            """;
+
+        XDocument doc = XDocument.Parse(xmlWithCR);
+        Console.WriteLine($"Original parsed value: {string.Join("", doc.Root!.Value.Select(c => c == '\r' ? "\\r" : c == '\n' ? "\\n" : c.ToString()))}");
+        // Output: a\r\nb\nc\r
+
+        string reserialized = doc.ToString(SaveOptions.DisableFormatting);
+        Console.WriteLine($"Reserialized XML: {reserialized}");
+        // Output: <x xml:space="preserve">a
+        // b
+        // c</x>
+
+        XDocument reparsed = XDocument.Parse(reserialized);
+        Console.WriteLine($"Reparsed value: {string.Join("", reparsed.Root!.Value.Select(c => c == '\r' ? "\\r" : c == '\n' ? "\\n" : c.ToString()))}");
+        // Output: a\nb\nc\n
+        // </XmlRoundTrip>
+    }
+}

docs/standard/linq/snippets/preserve-white-space-serializing/RoundtrippingSolution.cs

@@ -0,0 +1,46 @@
+using System;
+using System.IO;
+using System.Xml;
+using System.Xml.Linq;
+
+public static class RoundtrippingSolution
+{
+    public static void Example()
+    {
+        // <XmlRoundTripFix>
+        string xmlWithCR = """
+            <x xml:space="preserve">a&#xD;
+            b
+            c&#xD;</x>
+            """;
+
+        XDocument doc = XDocument.Parse(xmlWithCR);
+
+        // Create XmlWriter settings with NewLineHandling.Entitize
+        XmlWriterSettings settings = new XmlWriterSettings
+        {
+            NewLineHandling = NewLineHandling.Entitize,
+            OmitXmlDeclaration = true
+        };
+
+        // Serialize using XmlWriter
+        using StringWriter stringWriter = new StringWriter();
+        using (XmlWriter writer = XmlWriter.Create(stringWriter, settings))
+        {
+            doc.WriteTo(writer);
+        }
+
+        string roundtrippedXml = stringWriter.ToString();
+        Console.WriteLine($"Roundtripped XML: {roundtrippedXml}");
+        // Output: <x xml:space="preserve">a&#xD;
+        // b
+        // c&#xD;</x>
+
+        // Verify roundtripping preserves the original value
+        XDocument roundtrippedDoc = XDocument.Parse(roundtrippedXml);
+        bool valuesMatch = doc.Root!.Value == roundtrippedDoc.Root!.Value;
+        Console.WriteLine($"Values match after roundtripping: {valuesMatch}");
+        // </XmlRoundTripFix>
+        // Output: True
+    }
+}

docs/standard/linq/snippets/preserve-white-space-serializing/preserve-white-space-serializing.csproj

@@ -0,0 +1,10 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+</Project>