Using Dispose to unhook Blazor event handlers (#17339)

Author: guardrex

aspnetcore/blazor/forms-validation.md

@@ -5,7 +5,7 @@ description: Learn how to use forms and field validation scenarios in Blazor.
 monikerRange: '>= aspnetcore-3.1'
 ms.author: riande
 ms.custom: mvc
-ms.date: 12/18/2019
+ms.date: 03/17/2020
 no-loc: [Blazor, SignalR]
 uid: blazor/forms-validation
 ---
@@ -452,8 +452,11 @@ To enable and disable the submit button based on form validation:
 
 * Use the form's `EditContext` to assign the model when the component is initialized.
 * Validate the form in the context's `OnFieldChanged` callback to enable and disable the submit button.
+* Unhook the event handler in the `Dispose` method. For more information, see <xref:blazor/lifecycle#component-disposal-with-idisposable>.
 
 ```razor
+@implements IDisposable
+
 <EditForm EditContext="@_editContext">
     <DataAnnotationsValidator />
     <ValidationSummary />
@@ -471,12 +474,18 @@ To enable and disable the submit button based on form validation:
     protected override void OnInitialized()
     {
         _editContext = new EditContext(_starship);
+        _editContext.OnFieldChanged += HandleFieldChanged;
+    }
 
-        _editContext.OnFieldChanged += (_, __) =>
-        {
-            _formInvalid = !_editContext.Validate();
-            StateHasChanged();
-        };
+    private void HandleFieldChanged(object sender, FieldChangedEventArgs e)
+    {
+        _formInvalid = !_editContext.Validate();
+        StateHasChanged();
+    }
+
+    public void Dispose()
+    {
+        _editContext.OnFieldChanged -= HandleFieldChanged;
     }
 }
 ```

aspnetcore/blazor/lifecycle.md

@@ -5,7 +5,7 @@ description: Learn how to use Razor component lifecycle methods in ASP.NET Core
 monikerRange: '>= aspnetcore-3.1'
 ms.author: riande
 ms.custom: mvc
-ms.date: 12/18/2019
+ms.date: 03/17/2020
 no-loc: [Blazor, SignalR]
 uid: blazor/lifecycle
 ---
@@ -48,6 +48,8 @@ To prevent developer code in `OnInitializedAsync` from running twice, see the [S
 
 While a Blazor Server app is prerendering, certain actions, such as calling into JavaScript, aren't possible because a connection with the browser hasn't been established. Components may need to render differently when prerendered. For more information, see the [Detect when the app is prerendering](#detect-when-the-app-is-prerendering) section.
 
+If any event handlers are set up, unhook them on disposal. For more information, see the [Component disposal with IDisposable](#component-disposal-with-idisposable) section.
+
 ### Before parameters are set
 
 <xref:Microsoft.AspNetCore.Components.ComponentBase.SetParametersAsync*> sets parameters supplied by the component's parent in the render tree:
@@ -67,6 +69,8 @@ The default implementation of `SetParametersAsync` sets the value of each proper
 
 If `base.SetParametersAync` isn't invoked, the custom code can interpret the incoming parameters value in any way required. For example, there's no requirement to assign the incoming parameters to the properties on the class.
 
+If any event handlers are set up, unhook them on disposal. For more information, see the [Component disposal with IDisposable](#component-disposal-with-idisposable) section.
+
 ### After parameters are set
 
 <xref:Microsoft.AspNetCore.Components.ComponentBase.OnParametersSetAsync*> and <xref:Microsoft.AspNetCore.Components.ComponentBase.OnParametersSet*> are called:
@@ -93,6 +97,8 @@ protected override void OnParametersSet()
 }
 ```
 
+If any event handlers are set up, unhook them on disposal. For more information, see the [Component disposal with IDisposable](#component-disposal-with-idisposable) section.
+
 ### After component render
 
 <xref:Microsoft.AspNetCore.Components.ComponentBase.OnAfterRenderAsync*> and <xref:Microsoft.AspNetCore.Components.ComponentBase.OnAfterRender*> are called after a component has finished rendering. Element and component references are populated at this point. Use this stage to perform additional initialization steps using the rendered content, such as activating third-party JavaScript libraries that operate on the rendered DOM elements.
@@ -129,6 +135,8 @@ protected override void OnAfterRender(bool firstRender)
 
 `OnAfterRender` and `OnAfterRenderAsync` *aren't called when prerendering on the server.*
 
+If any event handlers are set up, unhook them on disposal. For more information, see the [Component disposal with IDisposable](#component-disposal-with-idisposable) section.
+
 ### Suppress UI refreshing
 
 Override <xref:Microsoft.AspNetCore.Components.ComponentBase.ShouldRender*> to suppress UI refreshing. If the implementation returns `true`, the UI is refreshed:
@@ -181,6 +189,16 @@ If a component implements <xref:System.IDisposable>, the [Dispose method](/dotne
 > [!NOTE]
 > Calling <xref:Microsoft.AspNetCore.Components.ComponentBase.StateHasChanged*> in `Dispose` isn't supported. `StateHasChanged` might be invoked as part of tearing down the renderer, so requesting UI updates at that point isn't supported.
 
+Unsubscribe event handlers from .NET events. The following [Blazor form](xref:blazor/forms-validation) examples show how to unhook an event handler in the `Dispose` method:
+
+* Private field and lambda approach
+
+  [!code-razor[](lifecycle/samples_snapshot/3.x/event-handler-disposal-1.razor?highlight=23,28)]
+
+* Private method approach
+
+  [!code-razor[](lifecycle/samples_snapshot/3.x/event-handler-disposal-2.razor?highlight=16,26)]
+
 ## Handle errors
 
 For information on handling errors during lifecycle method execution, see <xref:blazor/handle-errors#lifecycle-methods>.

aspnetcore/blazor/lifecycle/samples_snapshot/3.x/event-handler-disposal-1.razor

@@ -0,0 +1,30 @@
+@implements IDisposable
+
+<EditForm EditContext="@_editContext">
+
+    ...
+
+    <button type="submit" disabled="@_formInvalid">Submit</button>
+</EditForm>
+
+@code {
+    ...
+    private EventHandler<FieldChangedEventArgs> _fieldChanged;
+
+    protected override void OnInitialized()
+    {
+        _editContext = new EditContext(...);
+
+        _fieldChanged = (_, __) =>
+        {
+            ...
+        };
+
+        _editContext.OnFieldChanged += _fieldChanged;
+    }
+
+    public void Dispose()
+    {
+        _editContext.OnFieldChanged -= _fieldChanged;
+    }
+}

aspnetcore/blazor/lifecycle/samples_snapshot/3.x/event-handler-disposal-2.razor

@@ -0,0 +1,28 @@
+@implements IDisposable
+
+<EditForm EditContext="@_editContext">
+
+    ...
+
+    <button type="submit" disabled="@_formInvalid">Submit</button>
+</EditForm>
+
+@code {
+    ...
+
+    protected override void OnInitialized()
+    {
+        _editContext = new EditContext(...);
+        _editContext.OnFieldChanged += HandleFieldChanged;
+    }
+
+    private void HandleFieldChanged(object sender, FieldChangedEventArgs e)
+    {
+        ...
+    }
+
+    public void Dispose()
+    {
+        _editContext.OnFieldChanged -= HandleFieldChanged;
+    }
+}

aspnetcore/blazor/routing.md

@@ -5,7 +5,7 @@ description: Learn how to route requests in apps and about the NavLink component
 monikerRange: '>= aspnetcore-3.1'
 ms.author: riande
 ms.custom: mvc
-ms.date: 12/18/2019
+ms.date: 03/17/2020
 no-loc: [Blazor, SignalR]
 uid: blazor/routing
 ---
@@ -190,16 +190,16 @@ The following HTML markup is rendered:
 
 ## URI and navigation state helpers
 
-Use `Microsoft.AspNetCore.Components.NavigationManager` to work with URIs and navigation in C# code. `NavigationManager` provides the event and methods shown in the following table.
+Use <xref:Microsoft.AspNetCore.Components.NavigationManager> to work with URIs and navigation in C# code. `NavigationManager` provides the event and methods shown in the following table.
 
 | Member | Description |
 | ------ | ----------- |
-| `Uri` | Gets the current absolute URI. |
-| `BaseUri` | Gets the base URI (with a trailing slash) that can be prepended to relative URI paths to produce an absolute URI. Typically, `BaseUri` corresponds to the `href` attribute on the document's `<base>` element in *wwwroot/index.html* (Blazor WebAssembly) or *Pages/_Host.cshtml* (Blazor Server). |
-| `NavigateTo` | Navigates to the specified URI. If `forceLoad` is `true`:<ul><li>Client-side routing is bypassed.</li><li>The browser is forced to load the new page from the server, whether or not the URI is normally handled by the client-side router.</li></ul> |
-| `LocationChanged` | An event that fires when the navigation location has changed. |
-| `ToAbsoluteUri` | Converts a relative URI into an absolute URI. |
-| `ToBaseRelativePath` | Given a base URI (for example, a URI previously returned by `GetBaseUri`), converts an absolute URI into a URI relative to the base URI prefix. |
+| Uri | Gets the current absolute URI. |
+| BaseUri | Gets the base URI (with a trailing slash) that can be prepended to relative URI paths to produce an absolute URI. Typically, `BaseUri` corresponds to the `href` attribute on the document's `<base>` element in *wwwroot/index.html* (Blazor WebAssembly) or *Pages/_Host.cshtml* (Blazor Server). |
+| NavigateTo | Navigates to the specified URI. If `forceLoad` is `true`:<ul><li>Client-side routing is bypassed.</li><li>The browser is forced to load the new page from the server, whether or not the URI is normally handled by the client-side router.</li></ul> |
+| LocationChanged | An event that fires when the navigation location has changed. |
+| ToAbsoluteUri | Converts a relative URI into an absolute URI. |
+| <span style="word-break:normal;word-wrap:normal">ToBaseRelativePath</span> | Given a base URI (for example, a URI previously returned by `GetBaseUri`), converts an absolute URI into a URI relative to the base URI prefix. |
 
 The following component navigates to the app's `Counter` component when the button is selected:
 
@@ -220,3 +220,34 @@ The following component navigates to the app's `Counter` component when the butt
     }
 }
 ```
+
+The following component handles a location changed event. The `HandleLocationChanged` method is unhooked when `Dispose` is called by the framework. Unhooking the method permits garbage collection of the component.
+
+```razor
+@implement IDisposable
+@inject NavigationManager NavigationManager
+
+...
+
+protected override void OnInitialized()
+{
+    NavigationManager.LocationChanged += HandleLocationChanged;
+}
+
+private void HandleLocationChanged(object sender, LocationChangedEventArgs e)
+{
+    ...
+}
+
+public void Dispose()
+{
+    NavigationManager.LocationChanged -= HandleLocationChanged;
+}
+```
+
+<xref:Microsoft.AspNetCore.Components.Routing.LocationChangedEventArgs> provides the following information about the event:
+
+* <xref:Microsoft.AspNetCore.Components.Routing.LocationChangedEventArgs.Location> &ndash; The URL of the new location.
+* <xref:Microsoft.AspNetCore.Components.Routing.LocationChangedEventArgs.IsNavigationIntercepted> &ndash; If `true`, Blazor intercepted the navigation from the browser. If `false`, [NavigationManager.NavigateTo](xref:Microsoft.AspNetCore.Components.NavigationManager.NavigateTo%2A) caused the navigation to occur.
+
+For more information on component disposal, see <xref:blazor/lifecycle#component-disposal-with-idisposable>.