Document additional diagnostics (#23610)

* Document additional diagnostics * Apply suggestions from code review Co-authored-by: Rick Anderson <[email protected]> * Apply suggestions from code review Co-authored-by: Rick Anderson <[email protected]> * Apply suggestions from code review Co-authored-by: Kirk Larkin <[email protected]> * Apply suggestions from code review Co-authored-by: Kirk Larkin <[email protected]> Co-authored-by: Rick Anderson <[email protected]> Co-authored-by: Kirk Larkin <[email protected]>
dotnet · Oct 25, 2021 · fc0f4c7 · fc0f4c7
1 parent dba052e
commit fc0f4c7
Show file tree

Hide file tree

Showing 5 changed files with 169 additions and 2 deletions.
diff --git a/aspnetcore/diagnostics/code-analysis.md b/aspnetcore/diagnostics/code-analysis.md
@@ -1,7 +1,7 @@
 ---
 title: Code analysis in ASP.NET Core apps
 author: rick-anderson
-description: Learn about source code analysis in ASP.NET Core 
+description: Learn about source code analysis in ASP.NET Core
 monikerRange: '>= aspnetcore-3.1'
 ms.author: riande
 ms.date: 10/15/2021
@@ -19,3 +19,6 @@ uid: diagnostics/code-analysis
 | [ASP0007](xref:diagnostics/asp0007) | Non-breaking |Route parameter and argument optionality is mismatched |
 | [MVC1000](xref:diagnostics/mvc1000) | Non-breaking | Use of IHtmlHelper.Partial should be avoided |
 | [MVC1001](xref:diagnostics/mvc1001) | Non-breaking | Filters cannot be applied to page handler methods |
+| [MVC1002](xref:diagnostics/mvc1002) | Non-breaking | Route attributes cannot be applied to page handler methods |
+| [MVC1003](xref:diagnostics/mvc1003) | Non-breaking | Route attributes cannot be applied to page models |
+| [MVC1004](xref:diagnostics/mvc1004) | Non-breaking | Rename model bound parameter |
diff --git a/aspnetcore/diagnostics/mvc1001.md b/aspnetcore/diagnostics/mvc1001.md
@@ -23,9 +23,25 @@ An attribute implementing <xref:Microsoft.AspNetCore.Mvc.Filters.IFilterMetadata
 
 Razor Page handler methods are selected after MVC filter exeuction has started, and consequently cannot contribute filters to execute. Applying a filter to a Razor Page handler is unsupported and always incorrect.
 
+```csharp
+public class IndexModel : PageModel
+{
+    [MyFilter]
+    public IActionResult OnGet() => Page();
+}
+```
+
 ## How to fix violations
 
-Remove the filter from the handler and apply it to a page. If a filter has to be applied to a specific handler, consider using multiple Razor Pages.
+Remove the filter from the handler and apply it to the page model. If a filter has to be applied to a specific handler, consider using multiple Razor Pages.
+
+```csharp
+[MyFilter]
+public class IndexModel : PageModel
+{
+    public IActionResult OnGet() => Page();
+}
+```
 
 ## When to suppress warnings
 

diff --git a/aspnetcore/diagnostics/mvc1002.md b/aspnetcore/diagnostics/mvc1002.md
@@ -0,0 +1,40 @@
+---
+title: "MVC1002: Route attribute cannot be applied to page handler methods"
+description: "Learn about analysis rule MVC1002: Route attribute cannot be applied to page handler methods"
+author: pranavkm
+monikerRange: '>= aspnetcore-3.1'
+ms.author: riande
+ms.date: 10/22/2021
+no-loc: [Home, Privacy, Kestrel, appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR]
+uid: diagnostics/mvc1002
+---
+# MVC1002: Route attribute cannot be applied to page handler methods
+
+| | Value |
+|-|-|
+| **Rule ID** |MVC1002|
+| **Fix is breaking or non-breaking** |Non-breaking|
+
+## Cause
+
+An attribute implementing <xref:Microsoft.AspNetCore.Mvc.Routing.IRouteTemplateProvider> was applied to a Razor Page handler method.
+
+### Rule description
+
+Razor Page handler methods are selected after routing is completed, and consequently cannot contribute a route. Applying a route attribute such as `HttpGet` or `HttpPost` to a Razor Page handler is not supported.
+
+```csharp
+public class IndexModel : PageModel
+{
+    [HttpGet("/my-url")]
+    public IActionResult OnGet() => Page();
+}
+```
+
+## How to fix violations
+
+Remove the route attribute from the handler. Routes can be specified for a Razor Page using an `@page` directive or by using conventions. For more information, see [custom routes in Razor Pages](<xref:razor-pages/index#custom-routes>).
+
+## When to suppress warnings
+
+Don't suppress warnings from this rule.
diff --git a/aspnetcore/diagnostics/mvc1003.md b/aspnetcore/diagnostics/mvc1003.md
@@ -0,0 +1,40 @@
+---
+title: "MVC1003: Route attributes cannot be applied to page models"
+description: "Learn about analysis rule MVC1003: Route attributes cannot be applied to page models"
+author: pranavkm
+monikerRange: '>= aspnetcore-3.1'
+ms.author: riande
+ms.date: 10/22/2021
+no-loc: [Home, Privacy, Kestrel, appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR]
+uid: diagnostics/mvc1003
+---
+# MVC1003: Route attributes cannot be applied to page models
+
+| | Value |
+|-|-|
+| **Rule ID** |MVC1003|
+| **Fix is breaking or non-breaking** |Non-breaking|
+
+## Cause
+
+An attribute implementing <xref:Microsoft.AspNetCore.Mvc.Routing.IRouteTemplateProvider> was applied to a Razor Page model.
+
+### Rule description
+
+Razor Page models are identified after routing is completed, and consequently cannot contribute a route. Applying a route attribute such as `Route` to a Razor Page model is not supported.
+
+```csharp
+[Route("/my-page-route")]
+public class IndexModel : PageModel
+{
+    public IActionResult OnGet() => Page();
+}
+```
+
+## How to fix violations
+
+Remove the route attribute from the page model. Routes can be specified for a Razor Page using an `@page` directive or by using conventions. For more information, see [custom routes in Razor Pages](<xref:razor-pages/index#custom-routes>).
+
+## When to suppress warnings
+
+Don't suppress warnings from this rule.
diff --git a/aspnetcore/diagnostics/mvc1004.md b/aspnetcore/diagnostics/mvc1004.md
@@ -0,0 +1,68 @@
+---
+title: "MVC1004: Rename model bound parameter"
+description: "Learn about analysis rule MVC1004: Rename model bound parameter"
+author: pranavkm
+monikerRange: '>= aspnetcore-3.1'
+ms.author: riande
+ms.date: 10/22/2021
+no-loc: [Home, Privacy, Kestrel, appsettings.json, "ASP.NET Core Identity", cookie, Cookie, Blazor, "Blazor Server", "Blazor WebAssembly", "Identity", "Let's Encrypt", Razor, SignalR]
+uid: diagnostics/mvc1004
+---
+# MVC1004: Rename model bound parameter
+
+| | Value |
+|-|-|
+| **Rule ID** |MVC1004|
+| **Fix is breaking or non-breaking** |Breaking|
+
+## Cause
+
+A model bound parameter has the same name as one of its properties.
+
+### Rule description
+
+Model binding a complex parameter with a property that has the same name may result in unexpected binding behavior. Consider renaming the parameter, or using a binding attribute to specify a different name.
+
+Consider the following code:
+
+```csharp
+public class HomeController : Controller
+{
+    public IActionResult Get(SearchModel search)
+    {
+        ...
+    }
+}
+
+public class SearcModel
+{
+    public string Search { get; set; }
+}
+```
+
+In this model, the parameter and its property are both named `Search`, which results in model binding attempting to bind the property as `search.Search`. Naming a parameter and its property the same prevents binding to a value without a prefix such as a query that looks like `?search=MySearchTerm`.
+
+## How to fix violations
+
+* Rename the parameter if its prefix is not used during binding:
+```csharp
+public IActionResult Get(SearchModel model)
+{
+    ...
+}
+```
+
+Renaming a parameter on a public type could be considered a breaking change since it changes a library's public API surface.
+
+* If this is problematic, consider using a model binding attribute such as `Bind` to specify the model binding prefix:
+
+```csharp
+public IActionResult Get([Bind(Prefix = "")] SearchModel search)
+{
+    ...
+}
+```
+
+## When to suppress warnings
+
+Warnings can be suppressed if you intend to use the parameter name as a prefix during model binding.