Add docs for IDE0306 (#45507)

gewarren · web-flow · commit d561264661c8 · 2025-03-26T08:33:12.000-07:00
diff --git a/docs/fundamentals/code-analysis/style-rules/ide0300.md b/docs/fundamentals/code-analysis/style-rules/ide0300.md
@@ -38,7 +38,7 @@ Options specify the behavior that you want the rule to enforce. For information
 |                          | `false` &#124; `never`                    | Disables the rule.                    |
 | **Default option value** | `true` in .NET 8<br />`when_types_loosely_match` in .NET 9 and later versions |                                       |
 
-<sup>\*</sup>The code fix when this option is used might change the semantics of your code. For example, if you had `IEnumerable<int> x = new int[] { 1, 2, 3 };`, then in the original code, an array is produced. But in the new code (`IEnumerable<int> x = [1, 2, 3];`), an internal compiler-synthesized type is produced instead. You can observe this difference if you use an `is` check or a cast.
+<sup>\*</sup>When this option is used, the code fix might change the semantics of your code. For example, if you had `IEnumerable<int> x = new int[] { 1, 2, 3 };`, then in the original code, an array is produced. But in the new code (`IEnumerable<int> x = [1, 2, 3];`), an internal compiler-synthesized type is produced instead. You can observe this difference if you use an `is` check or a cast.
 
 ## Example
 
diff --git a/docs/fundamentals/code-analysis/style-rules/ide0301.md b/docs/fundamentals/code-analysis/style-rules/ide0301.md
@@ -38,7 +38,7 @@ Options specify the behavior that you want the rule to enforce. For information
 |                          | `false` &#124; `never`                    | Disables the rule.                    |
 | **Default option value** | `true` in .NET 8<br />`when_types_loosely_match` in .NET 9 and later versions |                                   |
 
-<sup>\*</sup>The code fix when this option is used might change the semantics of your code.
+<sup>\*</sup>When this option is used, the code fix might change the semantics of your code.
 
 ## Example
 
diff --git a/docs/fundamentals/code-analysis/style-rules/ide0303.md b/docs/fundamentals/code-analysis/style-rules/ide0303.md
@@ -43,7 +43,7 @@ Options specify the behavior that you want the rule to enforce. For information
 |                          | `false` &#124; `never`                    | Disables the rule.                    |
 | **Default option value** | `true` in .NET 8<br />`when_types_loosely_match` in .NET 9 and later versions |                                   |
 
-<sup>\*</sup>The code fix when this option is used might change the semantics of your code.
+<sup>\*</sup>When this option is used, the code fix might change the semantics of your code.
 
 ## Example
 
diff --git a/docs/fundamentals/code-analysis/style-rules/ide0304.md b/docs/fundamentals/code-analysis/style-rules/ide0304.md
@@ -41,7 +41,7 @@ Options specify the behavior that you want the rule to enforce. For information
 |                          | `false` &#124; `never`                    | Disables the rule.                    |
 | **Default option value** | `true` in .NET 8<br />`when_types_loosely_match` in .NET 9 and later versions |                                   |
 
-<sup>\*</sup>The code fix when this option is used might change the semantics of your code.
+<sup>\*</sup>When this option is used, the code fix might change the semantics of your code.
 
 ## Example
 
diff --git a/docs/fundamentals/code-analysis/style-rules/ide0305.md b/docs/fundamentals/code-analysis/style-rules/ide0305.md
@@ -38,7 +38,7 @@ Options specify the behavior that you want the rule to enforce. For information
 |                          | `false` &#124; `never`                    | Disables the rule.                    |
 | **Default option value** | `true` in .NET 8<br />`when_types_loosely_match` in .NET 9 and later versions |                                   |
 
-<sup>\*</sup>The code fix when this option is used might change the semantics of your code.
+<sup>\*</sup>When this option is used, the code fix might change the semantics of your code.
 
 ## Example
 
diff --git a/docs/fundamentals/code-analysis/style-rules/ide0306.md b/docs/fundamentals/code-analysis/style-rules/ide0306.md
@@ -0,0 +1,88 @@
+---
+title: "IDE0306: Use collection expression for new"
+description: "Learn about code analysis rule IDE0306: Use collection expression for new"
+ms.date: 03/25/2025
+f1_keywords:
+- IDE0306
+helpviewer_keywords:
+- IDE0306
+dev_langs:
+- CSharp
+---
+# Use collection expression for new (IDE0306)
+
+| Property                 | Value                                         |
+|--------------------------|-----------------------------------------------|
+| **Rule ID**              | IDE0306                                       |
+| **Title**                | Use collection expression for new             |
+| **Category**             | Style                                         |
+| **Subcategory**          | Language rules (expression-level preferences) |
+| **Applicable languages** | C# 12+                                        |
+| **Options**              | `dotnet_style_prefer_collection_expression`   |
+
+## Overview
+
+This rule flags places where a [collection expression](../../../csharp/language-reference/operators/collection-expressions.md) with a spread element (`..`) could be used to initialize a list instead of `new`. For example, this rule offers to simplify code like `new List<...>(x)` into the collection expression form (`[.. x]`).
+
+## Options
+
+Options specify the behavior that you want the rule to enforce. For information about configuring options, see [Option format](language-rules.md#option-format).
+
+### dotnet_style_prefer_collection_expression
+
+| Property                 | Value                                     | Description                           |
+|--------------------------|-------------------------------------------|---------------------------------------|
+| **Option name**          | dotnet_style_prefer_collection_expression |                                       |
+| **Option values**        | `true` &#124; `when_types_exactly_match`  | Prefer to use collection expressions only when types match exactly, for example, `List<int> m1 = new List<int>(new[] { 1, 2, 3 });`. |
+|                          | `when_types_loosely_match`<sup>\*</sup>   | Prefer to use collection expressions even when types match loosely, for example, `IEnumerable<int> m1 = new List<int>(new[] { 1, 2, 3 });`. The targeted type must match the type on the right-hand side or be one of the following types: <xref:System.Collections.Generic.IEnumerable%601>, <xref:System.Collections.Generic.ICollection%601>, <xref:System.Collections.Generic.IList%601>, <xref:System.Collections.Generic.IReadOnlyCollection%601>, <xref:System.Collections.Generic.IReadOnlyList%601>. |
+|                          | `false` &#124; `never`                    | Disables the rule.                    |
+| **Default option value** | `when_types_loosely_match`                |                                       |
+
+<sup>\*</sup>When this option is used, the code fix might change the semantics of your code.
+
+## Example
+
+```csharp
+// Code with violation.
+List<int> l1 = new List<int>(Enumerable.Range(1, 10));
+List<int> m1 = new List<int>(new[] { 1, 2, 3 });
+
+// Fixed code.
+List<int> l1 = [.. Enumerable.Range(1, 10)];
+List<int> m1 = [.. new[] { 1, 2, 3 }];
+```
+
+## Suppress a warning
+
+If you want to suppress only a single violation, add preprocessor directives to your source file to disable and then re-enable the rule.
+
+```csharp
+#pragma warning disable IDE0306
+// The code that's violating the rule is on this line.
+#pragma warning restore IDE0306
+```
+
+To disable the rule for a file, folder, or project, set its severity to `none` in the [configuration file](../configuration-files.md).
+
+```ini
+[*.{cs,vb}]
+dotnet_diagnostic.IDE0306.severity = none
+```
+
+To disable all of the code-style rules, set the severity for the category `Style` to `none` in the [configuration file](../configuration-files.md).
+
+```ini
+[*.{cs,vb}]
+dotnet_analyzer_diagnostic.category-Style.severity = none
+```
+
+For more information, see [How to suppress code analysis warnings](../suppress-warnings.md).
+
+## See also
+
+- [Use collection expression for array (IDE0300)](ide0300.md)
+- [Use collection expression for empty (IDE0301)](ide0301.md)
+- [Use collection expression for stackalloc (IDE0302)](ide0302.md)
+- [Use collection expression for `Create()` (IDE0303)](ide0303.md)
+- [Use collection expression for builder (IDE0304)](ide0304.md)
+- [Use collection expression for fluent (IDE0305)](ide0305.md)
diff --git a/docs/fundamentals/code-analysis/style-rules/index.md b/docs/fundamentals/code-analysis/style-rules/index.md
@@ -1,7 +1,7 @@
 ---
 title: Code-style rules overview
 description: Learn about the different .NET code-style rules and categories.
-ms.date: 12/11/2023
+ms.date: 03/25/2025
 author: gewarren
 ms.author: gewarren
 ---
@@ -140,6 +140,7 @@ The following table list all the code-style rules by ID and [options](../code-st
 > | [IDE0303](ide0303.md) | Use collection expression for `Create()` | [dotnet_style_prefer_collection_expression](ide0303.md#dotnet_style_prefer_collection_expression) |
 > | [IDE0304](ide0304.md) | Use collection expression for builder | [dotnet_style_prefer_collection_expression](ide0304.md#dotnet_style_prefer_collection_expression) |
 > | [IDE0305](ide0305.md) | Use collection expression for fluent | [dotnet_style_prefer_collection_expression](ide0305.md#dotnet_style_prefer_collection_expression) |
+> | [IDE0306](ide0306.md) | Use collection expression for new | [dotnet_style_prefer_collection_expression](ide0306.md#dotnet_style_prefer_collection_expression) |
 > | [IDE0320](ide0320.md) | Make anonymous function `static` | [csharp_prefer_static_anonymous_function](ide0320.md#csharp_prefer_static_anonymous_function) |
 > | [IDE0330](ide0330.md) | Prefer 'System.Threading.Lock' | [csharp_prefer_system_threading_lock](ide0330.md#csharp_prefer_system_threading_lock) |
 > | [IDE1005](ide1005.md) | Use conditional delegate call | [csharp_style_conditional_delegate_call](ide1005.md#csharp_style_conditional_delegate_call) |
diff --git a/docs/fundamentals/code-analysis/style-rules/language-rules.md b/docs/fundamentals/code-analysis/style-rules/language-rules.md
@@ -1,7 +1,7 @@
 ---
 title: Code-style language and unnecessary code rules
 description: Learn about the different code-style rules for using C# and Visual Basic language constructs and for finding unnecessary code.
-ms.date: 11/08/2024
+ms.date: 03/25/2025
 helpviewer_keywords:
 - language code style rules [EditorConfig]
 - language rules
@@ -168,6 +168,7 @@ C# style rules:
 - [Use collection expression for `Create()` (IDE0303)](ide0303.md)
 - [Use collection expression for builder (IDE0304](ide0304.md)
 - [Use collection expression for fluent (IDE0305)](ide0305.md)
+- [Use collection expression for new (IDE0306)](ide0306.md)
 
 Visual Basic style rules:
 
diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml
@@ -1669,6 +1669,8 @@ items:
                     href: ../../fundamentals/code-analysis/style-rules/ide0304.md
                   - name: IDE0305
                     href: ../../fundamentals/code-analysis/style-rules/ide0305.md
+                  - name: IDE0306
+                    href: ../../fundamentals/code-analysis/style-rules/ide0306.md
                   - name: IDE0320
                     href: ../../fundamentals/code-analysis/style-rules/ide0320.md
                   - name: IDE0330
