From d724966ce4e10c832c0793694c29ec1d4decbd6e Mon Sep 17 00:00:00 2001 From: Pranav K Date: Thu, 28 Oct 2021 16:40:35 -0700 Subject: [PATCH] Docs for blazor diagnostics (#23678) * Docs for blazor diagnostics --- aspnetcore/diagnostics/bl0001.md | 58 +++++++++++++++++++++++++ aspnetcore/diagnostics/bl0002.md | 51 ++++++++++++++++++++++ aspnetcore/diagnostics/bl0003.md | 47 ++++++++++++++++++++ aspnetcore/diagnostics/bl0004.md | 49 +++++++++++++++++++++ aspnetcore/diagnostics/bl0005.md | 33 ++++++++++++++ aspnetcore/diagnostics/bl0006.md | 33 ++++++++++++++ aspnetcore/diagnostics/code-analysis.md | 8 +++- 7 files changed, 278 insertions(+), 1 deletion(-) create mode 100644 aspnetcore/diagnostics/bl0001.md create mode 100644 aspnetcore/diagnostics/bl0002.md create mode 100644 aspnetcore/diagnostics/bl0003.md create mode 100644 aspnetcore/diagnostics/bl0004.md create mode 100644 aspnetcore/diagnostics/bl0005.md create mode 100644 aspnetcore/diagnostics/bl0006.md diff --git a/aspnetcore/diagnostics/bl0001.md b/aspnetcore/diagnostics/bl0001.md new file mode 100644 index 0000000000..e512019c18 --- /dev/null +++ b/aspnetcore/diagnostics/bl0001.md @@ -0,0 +1,58 @@ +--- +title: "BL0001: Component parameter should have public setters" +description: "Learn about analysis rule BL0001: Component parameter should have public setters" +author: pranavkm +monikerRange: '>= aspnetcore-3.1' +ms.author: riande +ms.date: 10/21/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/bl0001 +--- +# BL0001: Component parameter should have public setters + +| | Value | +|-|-| +| **Rule ID** |BL0001| +| **Category** |Usage| +| **Fix is breaking or non-breaking** |Breaking| + +## Cause + +A property on a type deriving from annotated with [`[Parameter]`](xref:Microsoft.AspNetCore.Components.ParameterAttribute) has a missing or non-public setters. + +## Rule description + +Component parameters are required to have publicly accessible setters to allow the framework to assign values. All of the parameter declarations in the following example result in this diagnostic. + + +```razor +@code +{ + [Parameter] int Parameter1 { get; set; } + + [Parameter] public int Parameter2 { get; } + + [Parameter] public int Parameter3 { get; private set; } +} +``` + +## How to fix violations + +* Make the property and its setter public. + +```razor +@code +{ + [Parameter] public int Parameter1 { get; set; } + + [Parameter] public int Parameter2 { get; set; } + + [Parameter] public int Parameter3 { get; set; } +} +``` + +* If making the property non-public is not possible, consider [implementing `SetParametersAsync` manually](). + +## When to suppress warnings + +Do not suppress a warning from this rule. diff --git a/aspnetcore/diagnostics/bl0002.md b/aspnetcore/diagnostics/bl0002.md new file mode 100644 index 0000000000..3043b01579 --- /dev/null +++ b/aspnetcore/diagnostics/bl0002.md @@ -0,0 +1,51 @@ +--- +title: "BL0002: Component has multiple CaptureUnmatchedValues parameters" +description: "Learn about analysis rule BL0002: Component has multiple CaptureUnmatchedValues parameters" +author: pranavkm +monikerRange: '>= aspnetcore-3.1' +ms.author: riande +ms.date: 10/21/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/bl0002 +--- +# BL0002: Component has multiple CaptureUnmatchedValues parameters + +| | Value | +|-|-| +| **Rule ID** |BL0002| +| **Category** |Usage| +| **Fix is breaking or non-breaking** |Non-breaking| + +## Cause + +More than one parameter on a type deriving from is annotated with `CaptureUnmatchedValues = true`. + +## Rule description + +For a component, exactly one parameter is expected to have the set to `true`. + +```razor +@code +{ + [Parameter(CaptureUnmatchedValues = true)] public Dictionary Parameter1 { get; set; } + + [Parameter(CaptureUnmatchedValues = true)] public Dictionary Parameter2 { get; set; } +} +``` + +## How to fix violations + +Limit a single parameter to have `CaptureUnmatchedValues` set. + +```razor +@code +{ + [Parameter(CaptureUnmatchedValues = true)] public Dictionary Parameter1 { get; set; } + + [Parameter] public Dictionary Parameter2 { get; set; } +} +``` + +## When to suppress warnings + +Do not suppress a warning from this rule. diff --git a/aspnetcore/diagnostics/bl0003.md b/aspnetcore/diagnostics/bl0003.md new file mode 100644 index 0000000000..b8ae668b78 --- /dev/null +++ b/aspnetcore/diagnostics/bl0003.md @@ -0,0 +1,47 @@ +--- +title: "BL0003: Component parameter with CaptureUnmatchedValues has the wrong type" +description: "Learn about analysis rule BL0003: Component parameter with CaptureUnmatchedValues has the wrong type" +author: pranavkm +monikerRange: '>= aspnetcore-3.1' +ms.author: riande +ms.date: 10/21/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/bl0003 +--- +# BL0003: Component parameter with CaptureUnmatchedValues has the wrong type + +| | Value | +|-|-| +| **Rule ID** |BL0003| +| **Category** |Usage| +| **Fix is breaking or non-breaking** |Breaking| + +## Cause + +A parameter on a type deriving from annotated with `= true` is not assignable from `Dictionary` + +## Rule description + +Parameters annotated with `CaptureUnmatchedValues = true` must be able to receive a `Dictionary` value. + +```razor +@code +{ + [Parameter(CaptureUnmatchedValues = true)] public IDictionary Attributes { get; set; } +} +``` + +## How to fix violations + +Change the type of the parameter to either `IDictionary` or `Dictionary` + +```razor +@code +{ + [Parameter(CaptureUnmatchedValues = true)] public IDictionary Attributes { get; set; } +} +``` + +## When to suppress warnings + +Do not suppress a warning from this rule. diff --git a/aspnetcore/diagnostics/bl0004.md b/aspnetcore/diagnostics/bl0004.md new file mode 100644 index 0000000000..4ba2cd3efe --- /dev/null +++ b/aspnetcore/diagnostics/bl0004.md @@ -0,0 +1,49 @@ +--- +title: "BL0004: Component parameter should be public" +description: "Learn about analysis rule BL0004: Component parameter should be public" +author: pranavkm +monikerRange: '>= aspnetcore-3.1' +ms.author: riande +ms.date: 10/21/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/bl0004 +--- +# BL0004: Component parameter should be public + +| | Value | +|-|-| +| **Rule ID** |BL0004| +| **Category** |Usage| +| **Fix is breaking or non-breaking** |Breaking| + +## Cause + +A property on a type deriving from annotated with [`[Parameter]`](xref:Microsoft.AspNetCore.Components.ParameterAttribute) is not public. + +## Rule description + +Component parameters are required to be public and must have a public setter. + +```razor +@code +{ + [Parameter] int Parameter1 { get; set; } +} +``` + +## How to fix violations + +* Make the property and its setter public. + +```razor +@code +{ + [Parameter] public int Parameter1 { get; set; } +} +``` + +* If making the property non-public is not possible, consider [implementing `SetParametersAsync` manually](). + +## When to suppress warnings + +Do not suppress a warning from this rule. diff --git a/aspnetcore/diagnostics/bl0005.md b/aspnetcore/diagnostics/bl0005.md new file mode 100644 index 0000000000..3aea870770 --- /dev/null +++ b/aspnetcore/diagnostics/bl0005.md @@ -0,0 +1,33 @@ +--- +title: "BL0005: Component parameter should not be set outside of its component" +description: "Learn about analysis rule BL0005: Component parameter should not be set outside of its component" +author: pranavkm +monikerRange: '>= aspnetcore-3.1' +ms.author: riande +ms.date: 10/21/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/bl0005 +--- +# BL0005: Component parameter should not be set outside of its component + +| | Value | +|-|-| +| **Rule ID** |BL0005| +| **Category** |Usage| +| **Fix is breaking or non-breaking** |Non-breaking| + +## Cause + +A property on a type deriving from annotated with [`[Parameter]`](xref:Microsoft.AspNetCore.Components.ParameterAttribute) is being assigned to from outside the component. + +## Rule description + +Component parameters should be assigned to as part of the component initialization or as part of `SetParametersAsync`. Assigning a value to a parameter from an external source results in the value being overwritten the next time the component renders. + +## How to fix violations + +Consider using a distinct property to receive values from other components. Additional code can then be written to decide which of the two values to use in the component. + +## When to suppress warnings + +Do not suppress a warning from this rule. diff --git a/aspnetcore/diagnostics/bl0006.md b/aspnetcore/diagnostics/bl0006.md new file mode 100644 index 0000000000..38aeaa767a --- /dev/null +++ b/aspnetcore/diagnostics/bl0006.md @@ -0,0 +1,33 @@ +--- +title: "BL0006: Do not use RenderTree types" +description: "Learn about analysis rule BL0006: Do not use RenderTree types" +author: pranavkm +monikerRange: '>= aspnetcore-3.1' +ms.author: riande +ms.date: 10/21/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/bl0006 +--- +# BL0006: Do not use RenderTree types + +| | Value | +|-|-| +| **Rule ID** |BL0006| +| **Category** |Usage| +| **Fix is breaking or non-breaking** |Non-breaking| + +## Cause + +A reference to a type in the was found. + +## Rule description + +Types in the `Microsoft.AspNetCore.Components.RenderTree` namespace are part of Blazor's implementation detail and are subject to breaking changes. Using these types is not recommended in user code. + +## How to fix violations + +Remove the reference to the type. + +## When to suppress warnings + +It is safe to suppress this rule if using this type is essential. Note that this these are subject to breaking changes between major releases. diff --git a/aspnetcore/diagnostics/code-analysis.md b/aspnetcore/diagnostics/code-analysis.md index ca32ce26b0..4ac88fbc5a 100644 --- a/aspnetcore/diagnostics/code-analysis.md +++ b/aspnetcore/diagnostics/code-analysis.md @@ -18,7 +18,13 @@ uid: diagnostics/code-analysis | [ASP0001](xref:diagnostics/asp0001) | Non-breaking | Authorization middleware is incorrectly configured | | [ASP0004](xref:diagnostics/asp0004) | Non-breaking | Do not use action results with route handlers | | [ASP0005](xref:diagnostics/asp0005) | Non-breaking | Do not place attribute on method called by route handler lambda | -| [ASP0007](xref:diagnostics/asp0007) | Non-breaking |Route parameter and argument optionality is mismatched | +| [ASP0007](xref:diagnostics/asp0007) | Non-breaking | Route parameter and argument optionality is mismatched | +| [BL0001](xref:diagnostics/bl0001) | Breaking | Component parameter should have public setters | +| [BL0002](xref:diagnostics/bl0002) | Non-breaking | Component has multiple CaptureUnmatchedValues parameters | +| [BL0003](xref:diagnostics/bl0003) | Breaking | Component parameter with CaptureUnmatchedValues has the wrong type | +| [BL0004](xref:diagnostics/bl0004) | Breaking | Component parameter should be public | +| [BL0005](xref:diagnostics/bl0005) | Non-breaking | Component parameter should not be set outside of its component | +| [BL0006](xref:diagnostics/bl0006) | Non-breaking | Do not use RenderTree types | | [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 |