Add tip for interpolated string parsing (#48946)

* Add tip for interpolated string parsing

Fixes #43758

Add an include file with a tip that explains how Visual Studio and the C# Dev Kit interpret raw string literals and provides syntax coloring or potential fixes when the literal doesn't represent valid syntax for the chosen format.

Add that include file in articles that provide information on raw string literals.

Perform an edit pass and freshness pass on impacted articles.

* Update docs/csharp/includes/raw-string-parsing.md

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

* Update docs/csharp/includes/raw-string-parsing.md

---------

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

Author: BillWagner

docs/csharp/includes/raw-string-parsing.md

@@ -0,0 +1,19 @@
+---
+author: BillWagner
+ms.author: wiwagn
+ms.topic: include
+ms.date: 10/07/2025
+---
+> [!TIP]
+> Visual Studio and the C# Dev Kit provide some validation and syntax highlighting when raw string literals contain JSON data or regular expressions.
+>
+> The tools parse the text. If the tools have confidence that the text represents JSON or a regular expression, the editor provides syntax coloring.
+>
+> You can improve that experience by adding a comment above the declaration indicating the format:
+>
+> - `// lang=json` indicates the raw string literal represents JSON data.
+> - `// lang=regex` indicates the raw string literal represents a regular expression.
+>
+> When a raw string literal is used as an argument where the parameter uses the <xref:System.Diagnostics.CodeAnalysis.StringSyntaxAttribute?displayProperty=fullName> to indicate a format, these tools validate the raw string literal for some of the format types. Both JSON and regex are supported.
+>
+> For some formats, the comment or the attribute enables code suggestions offer fixes for string literals based on the format.

docs/csharp/language-reference/builtin-types/reference-types.md

@@ -1,7 +1,7 @@
 ---
 title: "Built-in reference types"
 description: "Learn about reference types that have C# keywords you can use to declare them."
-ms.date: 08/16/2022
+ms.date: 10/07/2025
 f1_keywords: 
   - "object_CSharpKeyword"
   - "object"
@@ -28,7 +28,7 @@ C# has many built-in reference types. They have keywords or operators that are s
 
 ## The object type
 
-The `object` type is an alias for <xref:System.Object?displayProperty=nameWithType> in .NET. In the unified type system of C#, all types, predefined and user-defined, reference types and value types, inherit directly or indirectly from <xref:System.Object?displayProperty=nameWithType>. You can assign values of any type (except `ref struct`, see [ref struct](ref-struct.md)) to variables of type `object`. Any `object` variable can be assigned to its default value using the literal `null`. When a variable of a value type is converted to object, it's said to be *boxed*. When a variable of type `object` is converted to a value type, it's said to be *unboxed*. For more information, see [Boxing and Unboxing](../../programming-guide/types/boxing-and-unboxing.md).
+The `object` type is an alias for <xref:System.Object?displayProperty=nameWithType> in .NET. In the unified type system of C#, all types, predefined and user-defined, reference types and value types, inherit directly or indirectly from <xref:System.Object?displayProperty=nameWithType>. You can assign values of any type (except `ref struct`, see [ref struct](ref-struct.md)) to variables of type `object`. Any `object` variable can be assigned to its default value using the literal `null`. When a variable of a value type is converted to object, it's *boxed*. When a variable of type `object` is converted to a value type, it's *unboxed*. For more information, see [Boxing and Unboxing](../../programming-guide/types/boxing-and-unboxing.md).
 
 ## The string type
 
@@ -55,7 +55,7 @@ string a = "good " + "morning";
 
 The preceding code creates a string object that contains "good morning".
 
-Strings are *immutable*--the contents of a string object can't be changed after the object is created. For example, when you write this code, the compiler actually creates a new string object to hold the new sequence of characters, and that new object is assigned to `b`. The memory that had been allocated for `b` (when it contained the string "h") is then eligible for garbage collection.
+Strings are *immutable*--the contents of a string object can't be changed after the object is created. For example, when you write this code, the compiler actually creates a new string object to hold the new sequence of characters, and that new object is assigned to `b`. The memory allocated for `b` (when it contained the string "h") is then eligible for garbage collection.
 
 ```csharp
 string b = "h";
@@ -137,6 +137,8 @@ var json= """
     """;
 ```
 
+[!INCLUDE[raw-string-tip](../../includes/raw-string-parsing.md)]
+
 The compiler issues an error if any of the text lines extend to the left of the closing quote sequence. The opening and closing quote sequences can be on the same line, providing the string literal neither starts nor ends with a quote character:
 
 ```csharp
@@ -221,12 +223,12 @@ Action<string> stringAction = str => {};
 Action<object> objectAction = obj => {};
 
 // Valid due to implicit reference conversion of
-// objectAction to Action<string>, but may fail
+// objectAction to Action<string>, but might fail
 // at run time.
 Action<string> combination = stringAction + objectAction;
 ```
 
-You can create a delegate with the correct runtime type by creating a new delegate object. The following example demonstrates how this workaround may be applied to the preceding example.
+You can create a delegate with the correct runtime type by creating a new delegate object. The following example demonstrates how this workaround might be applied to the preceding example.
 
 ```csharp
 Action<string> stringAction = str => {};

docs/csharp/language-reference/tokens/index.md

@@ -1,7 +1,7 @@
 ---
 description: "Special Characters - C# Reference"
 title: "Special Characters"
-ms.date: 02/14/2017
+ms.date: 10/07/2025
 f1_keywords: 
   - "cs.special characters"
   - "@$_CSharpKeyword"
@@ -11,7 +11,6 @@ helpviewer_keywords:
   - "Visual C#, special characters"
   - "@ character (C#)"
   - "$ character (C#)"
-ms.assetid: 4c5c0539-2e37-40b7-91ce-75af5aabd3f9
 ---
 
 # C# Special Characters

docs/csharp/language-reference/tokens/interpolated.md

@@ -1,7 +1,7 @@
 ---
 title: "$ - string interpolation - format string output"
 description: String interpolation using the `$` token provides a more readable and convenient syntax to format string output than traditional string composite formatting.
-ms.date: 11/22/2024
+ms.date: 10/07/2025
 f1_keywords:
     - "$_CSharpKeyword"
     - "$"
@@ -60,6 +60,8 @@ To embed `{` and `}` characters in the result string, start an interpolated raw
 
 In the preceding example, an interpolated raw string literal starts with two `$` characters. You need to put every interpolation expression between double braces (`{{` and `}}`). A single brace is embedded into a result string. If you need to embed repeated `{` or `}` characters into a result string, use an appropriately greater number of `$` characters to designate an interpolated raw string literal. If the string literal has more repeated braces than the number of `$` characters, the `{` and `}` characters are grouped from inside to outside. In the preceding example, the literal `The point {{{X}}, {{Y}}}` interprets `{{X}}` and `{{Y}}` as interpolated expressions. The outer `{` and `}` are included verbatim in the output string.
 
+[!INCLUDE[raw-string-tip](../../includes/raw-string-parsing.md)]
+
 ## Special characters
 
 To include a brace, "{" or "}", in the text produced by an interpolated string, use two braces, "{{" or "}}". For more information, see the [Escaping braces](../../../standard/base-types/composite-formatting.md#escaping-braces) section of the [Composite formatting](../../../standard/base-types/composite-formatting.md) article.

docs/csharp/language-reference/tokens/raw-string.md

@@ -3,7 +3,7 @@ description: "Raw string literals can contain any arbitrary text without the nee
 title: "Raw string literals - \"\"\""
 f1_keywords:
   - "RawStringLiteral_CSharpKeyword"
-ms.date: 12/08/2022
+ms.date: 10/07/2025
 ---
 # Raw string literal text - `"""` in string literals
 
@@ -21,10 +21,12 @@ The following rules govern the interpretation of a multi-line raw string literal
 - Any whitespace to the left of the closing quotes is removed from all lines of the raw string literal.
 - Any whitespace following the opening quotes on the same line is ignored.
 - Whitespace only lines following the opening quote are included in the string literal.
-- If a whitespace precedes the end delimiter on the same line, the exact number and kind of whitespace characters (for example, spaces vs. tabs) must exist at the beginning of each content line. Specifically, a space does not match a horizontal tab, and vice versa.
+- If a whitespace precedes the end delimiter on the same line, the exact number and kind of whitespace characters (for example, spaces vs. tabs) must exist at the beginning of each content line. Specifically, a space doesn't match a horizontal tab, and vice versa.
 - The newline before the closing quotes isn't included in the literal string.
 
-You may need to create a raw string literal that has three or more consecutive double-quote characters. Raw string literals can start and end with a sequence of at least three double-quote characters. When your string literal contains three consecutive double-quotes, you start and end the raw string literal with four double quote characters:
+[!INCLUDE[raw-string-tip](../../includes/raw-string-parsing.md)]
+
+You might need to create a raw string literal that has three or more consecutive double-quote characters. Raw string literals can start and end with a sequence of at least three double-quote characters. When your string literal contains three consecutive double-quotes, you start and end the raw string literal with four double quote characters:
 
 :::code language="csharp" source="./snippets/raw-string-literal.cs" id="MoarQuotes":::
 

docs/csharp/programming-guide/strings/index.md

@@ -1,11 +1,10 @@
 ---
 title: "Strings"
 description: Learn about strings in C# programming. See information on declaring and initializing strings, the immutability of string objects, and string escape sequences.
-ms.date: 11/22/2024
+ms.date: 10/07/2025
 helpviewer_keywords:
   - "C# language, strings"
   - "strings [C#]"
-ms.assetid: 21580405-cb25-4541-89d5-037846a38b07
 ---
 # Strings and string literals
 
@@ -27,11 +26,11 @@ Initialize a string with the <xref:System.String.Empty> constant value to create
 
 ## Immutability of strings
 
-String objects are *immutable*: they can't be changed after they're created. All of the <xref:System.String> methods and C# operators that appear to modify a string actually return the results in a new string object. In the following example, when the contents of `s1` and `s2` are concatenated to form a single string, the two original strings are unmodified. The `+=` operator creates a new string that contains the combined contents. That new object is assigned to the variable `s1`, and the original object that was assigned to `s1` is released for garbage collection because no other variable holds a reference to it.
+String objects are *immutable*: they can't be changed after they're created. All of the <xref:System.String> methods and C# operators that appear to modify a string actually return the results in a new string object. In the following example, when the contents of `s1` and `s2` are concatenated to form a single string, the two original strings are unmodified. The `+=` operator creates a new string that contains the combined contents. That new object is assigned to the variable `s1`, and the original object assigned to `s1` is released for garbage collection because no other variable holds a reference to it.
 
 :::code language="csharp" source="./snippets/Declarations.cs" id="StringImmutability":::
 
-Because a string "modification" is actually a new string creation, you must use caution when you create references to strings. If you create a reference to a string, and then "modify" the original string, the reference continues to point to the original object instead of the new object that was created when the string was modified. The following code illustrates this behavior:
+Because a string "modification" is actually a new string creation, you must use caution when you create references to strings. If you create a reference to a string, and then "modify" the original string, the reference continues to point to the original object. The original object doesn't reflect the new object that was created when the string was modified. The following code illustrates this behavior:
 
 :::code language="csharp" source="./snippets/Declarations.cs" id="ModifyIsCopy":::
 
@@ -74,6 +73,8 @@ You should consider raw string literals when you're generating text that include
 
 :::code language="csharp" source="./snippets/StringLiterals.cs" id="JSONString":::
 
+[!INCLUDE[raw-string-tip](../../includes/raw-string-parsing.md)]
+
 ### String escape sequences
 
 | Escape sequence | Character name                   | Unicode encoding                                       |
@@ -95,10 +96,10 @@ You should consider raw string literals when you're generating text that include
 | `\x`            |Unicode escape sequence similar to "\u" except with variable length|`\xH[H][H][H]` (range: 0 - FFFF; example: `\x00E7` or `\x0E7` or `\xE7` = "ç")|
 
 > [!WARNING]
-> When using the `\x` escape sequence and specifying less than 4 hex digits, if the characters that immediately follow the escape sequence are valid hex digits (i.e. 0-9, A-F, and a-f), they will be interpreted as being part of the escape sequence. For example, `\xA1` produces "&#161;", which is code point U+00A1. However, if the next character is "A" or "a", then the escape sequence will instead be interpreted as being `\xA1A` and produce "&#x0A1A;", which is code point U+0A1A. In such cases, specifying all 4 hex digits (for example, `\x00A1`) prevents any possible misinterpretation.
+> When you use the `\x` escape sequence and specifying less than 4 hex digits, if the characters that immediately follow the escape sequence are valid hex digits (such as 0-9, A-F, and a-f), they're interpreted as being part of the escape sequence. For example, `\xA1` produces "&#161;", which is code point U+00A1. However, if the next character is "A" or "a", then the escape sequence will instead be interpreted as being `\xA1A` and produce "&#x0A1A;", which is code point U+0A1A. In such cases, specifying all 4 hex digits (for example, `\x00A1`) prevents any possible misinterpretation.
 
 > [!NOTE]
-> At compile time, verbatim and raw strings are converted to ordinary strings with all the same escape sequences. Therefore, if you view a verbatim or raw string in the debugger watch window, you will see the escape characters that were added by the compiler, not the verbatim or raw version from your source code. For example, the verbatim string `@"C:\files.txt"` will appear in the watch window as `"C:\\files.txt"`.
+> At compile time, verbatim and raw strings are converted to ordinary strings with all the same escape sequences. Therefore, if you view a verbatim or raw string in the debugger watch window, you see the escape characters added by the compiler, not the verbatim, or raw version from your source code. For example, the verbatim string `@"C:\files.txt"` appears in the watch window as `"C:\\files.txt"`.
 
 ## Format strings
 
@@ -146,7 +147,7 @@ You can use array notation with an index value to acquire read-only access to in
 
 :::code language="csharp" source="./snippets/StringCharacters.cs" id="ReverseChars":::
 
-If the <xref:System.String> methods don't provide the functionality that you must have to modify individual characters in a string, you can use a <xref:System.Text.StringBuilder> object to modify the individual chars "in-place," and then create a new string to store the results by using the <xref:System.Text.StringBuilder> methods. In the following example, assume that you must modify the original string in a particular way and then store the results for future use:
+For more extensive string manipulation, you can use a <xref:System.Text.StringBuilder> object to modify the individual chars "in-place." Then create a new string to store the results by using the <xref:System.Text.StringBuilder> methods. In the following example, assume that you must modify the original string in a particular way and then store the results for future use:
 
 :::code language="csharp" source="./snippets/StringCharacters.cs" id="AccessChars":::