Add documentation for CA1877: Collapse consecutive Path.Combine/Path.Join operations (#49638)

Author: Copilot

docs/fundamentals/code-analysis/quality-rules/ca1877.md

@@ -0,0 +1,80 @@
+---
+title: "CA1877: Use 'Path.Combine' or 'Path.Join' overloads (code analysis)"
+description: "Learn about code analysis rule CA1877: Use 'Path.Combine' or 'Path.Join' overloads"
+ms.date: 11/05/2025
+ms.topic: reference
+f1_keywords:
+  - CA1877
+  - UsePathCombineOrPathJoinAnalyzer
+helpviewer_keywords:
+  - CA1877
+dev_langs:
+  - CSharp
+  - VB
+ai-usage: ai-generated
+---
+
+# CA1877: Use 'Path.Combine' or 'Path.Join' overloads
+
+| Property                            | Value                                  |
+|-------------------------------------|----------------------------------------|
+| **Rule ID**                         | CA1877                                 |
+| **Title**                           | Use `Path.Combine` or `Path.Join` overloads |
+| **Category**                        | [Performance](performance-warnings.md) |
+| **Fix is breaking or non-breaking** | Non-breaking                           |
+| **Enabled by default in .NET 10**   | As suggestion                          |
+
+## Cause
+
+Multiple consecutive <xref:System.IO.Path.Combine%2A?displayProperty=nameWithType> or <xref:System.IO.Path.Join%2A?displayProperty=nameWithType> operations are used to build a path.
+
+## Rule description
+
+When you use multiple consecutive `Path.Combine` or `Path.Join` operations, it's more efficient to use an overload that accepts multiple path segments. This approach reduces the number of allocations and function calls, improving performance. Both methods provide overloads that accept multiple parameters, allowing you to collapse consecutive operations into a single call.
+
+## How to fix violations
+
+Replace consecutive `Path.Combine` or `Path.Join` operations with a single call using an overload that accepts all path segments.
+
+A *code fix* that automatically performs this transformation is available.
+
+## Example
+
+The following code snippet shows a violation of CA1877:
+
+:::code language="csharp" source="./snippets/csharp/all-rules/CA1877.cs" id="Violation":::
+:::code language="vb" source="./snippets/vb/all-rules/CA1877.vb" id="Violation":::
+
+The following code snippet fixes the violation:
+
+:::code language="csharp" source="./snippets/csharp/all-rules/CA1877.cs" id="Fix":::
+:::code language="vb" source="./snippets/vb/all-rules/CA1877.vb" id="Fix":::
+
+## When to suppress warnings
+
+It's safe to suppress a warning from this rule if performance isn't a concern.
+
+## Suppress a warning
+
+If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule.
+
+```csharp
+#pragma warning disable CA1877
+// The code that's violating the rule is on this line.
+#pragma warning restore CA1877
+```
+
+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.CA1877.severity = none
+```
+
+For more information, see [How to suppress code analysis warnings](../suppress-warnings.md).
+
+## See also
+
+- [Performance rules](performance-warnings.md)
+- <xref:System.IO.Path.Combine%2A?displayProperty=nameWithType>
+- <xref:System.IO.Path.Join%2A?displayProperty=nameWithType>

docs/fundamentals/code-analysis/quality-rules/index.md

@@ -176,6 +176,7 @@ The following table lists code quality analysis rules.
 > | [CA1873: Avoid potentially expensive logging](ca1873.md) | In many situations, logging is disabled or set to a log level that results in an unnecessary evaluation for logging arguments. |
 > | [CA1874: Use `Regex.IsMatch`](ca1874.md) | `Regex.IsMatch` is simpler and faster than `Regex.Match(...).Success`. |
 > | [CA1875: Use `Regex.Count`](ca1875.md) | `Regex.Count` is simpler and faster than `Regex.Matches(...).Count`. |
+> | [CA1877: Use 'Path.Combine' or 'Path.Join' overloads](ca1877.md) | When multiple `Path.Combine` or `Path.Join` operations are nested, they can be collapsed into a single operation for better performance and readability. |
 > | [CA2000: Dispose objects before losing scope](ca2000.md) | Because an exceptional event might occur that will prevent the finalizer of an object from running, the object should be explicitly disposed before all references to it are out of scope. |
 > | [CA2002: Do not lock on objects with weak identity](ca2002.md) |An object is said to have a weak identity when it can be directly accessed across application domain boundaries. A thread that tries to acquire a lock on an object that has a weak identity can be blocked by a second thread in a different application domain that has a lock on the same object. |
 > | [CA2007: Do not directly await a Task](ca2007.md) | An asynchronous method [awaits](../../../csharp/language-reference/operators/await.md) a <xref:System.Threading.Tasks.Task> directly. When an asynchronous method awaits a <xref:System.Threading.Tasks.Task> directly, continuation occurs in the same thread that created the task. This behavior can be costly in terms of performance and can result in a deadlock on the UI thread. Consider calling <xref:System.Threading.Tasks.Task.ConfigureAwait(System.Boolean)?displayProperty=nameWithType> to signal your intention for continuation. |

docs/fundamentals/code-analysis/quality-rules/performance-warnings.md

@@ -83,3 +83,4 @@ Performance rules support high-performance libraries and applications.
 | [CA1873: Avoid potentially expensive logging](ca1873.md) | When logging methods are called, their arguments are evaluated regardless of whether the logging level is enabled. This can result in expensive operations being executed even when the log message won't be written. For better performance, guard expensive logging calls with a check to <xref:Microsoft.Extensions.Logging.ILogger.IsEnabled%2A> or use the `LoggerMessage` pattern. |
 | [CA1874: Use 'Regex.IsMatch'](ca1874.md) | <xref:System.Text.RegularExpressions.Regex.IsMatch*?displayProperty=nameWithType> is simpler and faster than `Regex.Match(...).Success`. |
 | [CA1875: Use 'Regex.Count'](ca1875.md) | <xref:System.Text.RegularExpressions.Regex.Count*?displayProperty=nameWithType> is simpler and faster than `Regex.Matches(...).Count`. |
+| [CA1877: Use 'Path.Combine' or 'Path.Join' overloads](ca1877.md) | Multiple consecutive <xref:System.IO.Path.Combine%2A?displayProperty=nameWithType> or <xref:System.IO.Path.Join%2A?displayProperty=nameWithType> operations can be collapsed into a single call using overloads that accept multiple path segments. |

docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca1877.cs

@@ -0,0 +1,36 @@
+using System.IO;
+
+class ViolationExample
+{
+    // <Violation>
+    public string GetFilePath(string folder, string subfolder, string filename)
+    {
+        // Violation.
+        string temp = Path.Combine(folder, subfolder);
+        return Path.Combine(temp, filename);
+    }
+
+    public string GetLogPath(string baseDir, string date, string category)
+    {
+        // Violation.
+        return Path.Join(Path.Join(baseDir, date), category);
+    }
+    // </Violation>
+}
+
+class FixExample
+{
+    // <Fix>
+    public string GetFilePath(string folder, string subfolder, string filename)
+    {
+        // No violation.
+        return Path.Combine(folder, subfolder, filename);
+    }
+
+    public string GetLogPath(string baseDir, string date, string category)
+    {
+        // No violation.
+        return Path.Join(baseDir, date, category);
+    }
+    // </Fix>
+}

docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca1877.vb

@@ -0,0 +1,31 @@
+Imports System.IO
+
+Class ViolationExample
+    ' <Violation>
+    Public Function GetFilePath(folder As String, subfolder As String, filename As String) As String
+        ' Violation.
+        Dim temp As String = Path.Combine(folder, subfolder)
+        Return Path.Combine(temp, filename)
+    End Function
+
+    Public Function GetLogPath(baseDir As String, [date] As String, category As String) As String
+        ' Violation.
+        Return Path.Join(Path.Join(baseDir, [date]), category)
+    End Function
+    ' </Violation>
+End Class
+
+Class FixExample
+    ' <Fix>
+    Public Function GetFilePath(folder As String, subfolder As String, filename As String) As String
+        ' No violation.
+        Return Path.Combine(folder, subfolder, filename)
+    End Function
+
+    Public Function GetLogPath(baseDir As String, [date] As String, category As String) As String
+        ' No violation.
+        Return Path.Join(baseDir, [date], category)
+    End Function
+    ' </Fix>
+End Class
+

docs/navigate/tools-diagnostics/toc.yml

@@ -3287,6 +3287,8 @@ items:
                     href: ../../fundamentals/code-analysis/quality-rules/ca1874.md
                   - name: CA1875
                     href: ../../fundamentals/code-analysis/quality-rules/ca1875.md
+                  - name: CA1877
+                    href: ../../fundamentals/code-analysis/quality-rules/ca1877.md
               - name: SingleFile rules
                 items:
                   - name: Overview