diff --git a/aspnetcore/blazor/components/class-libraries-and-static-server-side-rendering.md b/aspnetcore/blazor/components/class-libraries-and-static-server-side-rendering.md index d963215e51f6..32673c24c7c0 100644 --- a/aspnetcore/blazor/components/class-libraries-and-static-server-side-rendering.md +++ b/aspnetcore/blazor/components/class-libraries-and-static-server-side-rendering.md @@ -10,11 +10,7 @@ uid: blazor/components/class-libraries-with-static-ssr --- # ASP.NET Core Razor class libraries (RCLs) with static server-side rendering (static SSR) - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] This article provides guidance for component library authors considering support for static server-side rendering (static SSR). diff --git a/aspnetcore/blazor/components/integration.md b/aspnetcore/blazor/components/integration.md index 3f26a167faab..be74fa2b5a29 100644 --- a/aspnetcore/blazor/components/integration.md +++ b/aspnetcore/blazor/components/integration.md @@ -10,11 +10,7 @@ uid: blazor/components/integration --- # Integrate ASP.NET Core Razor components into ASP.NET Core apps - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] This article explains Razor component integration scenarios for ASP.NET Core apps. diff --git a/aspnetcore/blazor/components/prerender.md b/aspnetcore/blazor/components/prerender.md index 0fd1a17e7d5c..bb154215020c 100644 --- a/aspnetcore/blazor/components/prerender.md +++ b/aspnetcore/blazor/components/prerender.md @@ -10,11 +10,7 @@ uid: blazor/components/prerender --- # Prerender ASP.NET Core Razor components - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] The [`QuickGrid`](xref:Microsoft.AspNetCore.Components.QuickGrid) component is a Razor component for quickly and efficiently displaying data in tabular form. `QuickGrid` provides a simple and convenient data grid component for common grid rendering scenarios and serves as a reference architecture and performance baseline for building data grid components. `QuickGrid` is highly optimized and uses advanced techniques to achieve optimal rendering performance. diff --git a/aspnetcore/blazor/components/render-components-outside-of-aspnetcore.md b/aspnetcore/blazor/components/render-components-outside-of-aspnetcore.md index 5c64ced5955d..b1217fb8a8d3 100644 --- a/aspnetcore/blazor/components/render-components-outside-of-aspnetcore.md +++ b/aspnetcore/blazor/components/render-components-outside-of-aspnetcore.md @@ -10,11 +10,7 @@ uid: blazor/components/render-outside-of-aspnetcore --- # Render Razor components outside of ASP.NET Core - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] Razor components can be rendered outside of the context of an HTTP request. You can render Razor components as HTML directly to a string or stream independently of the ASP.NET Core hosting environment. This is convenient for scenarios where you want to generate HTML fragments, such as for generating email content, generating static site content, or for building a content templating engine. diff --git a/aspnetcore/blazor/components/render-modes.md b/aspnetcore/blazor/components/render-modes.md index 61e3a8afd2c1..e412321ec8f5 100644 --- a/aspnetcore/blazor/components/render-modes.md +++ b/aspnetcore/blazor/components/render-modes.md @@ -10,11 +10,7 @@ uid: blazor/components/render-modes --- # ASP.NET Core Blazor render modes - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] This article explains control of Razor component rendering in Blazor Web Apps, either at compile time or runtime. @@ -230,7 +226,30 @@ The Connecting to the assistant...

+} +else +{ + ... +} +``` + +Disable a button until a component is interactive: + +```razor + +``` + +Disable a form during prerendering and enable the form when the component is interactive: ```razor @@ -260,7 +279,7 @@ Components use these properties to render content depending on their location or } ``` -The next example shows how to render markup to support performing a regular HTML action if the component is statically rendered: +Render markup to support performing a regular HTML action if the component is statically rendered: ```razor @if (AssignedRenderMode is null) diff --git a/aspnetcore/blazor/components/sections.md b/aspnetcore/blazor/components/sections.md index 51ce9416b44a..5206fbd93666 100644 --- a/aspnetcore/blazor/components/sections.md +++ b/aspnetcore/blazor/components/sections.md @@ -10,11 +10,7 @@ uid: blazor/components/sections --- # ASP.NET Core Blazor sections - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] This article explains how to control the content in a Razor component from a child Razor component. diff --git a/aspnetcore/blazor/fundamentals/signalr.md b/aspnetcore/blazor/fundamentals/signalr.md index 5ed800690d18..151e764a0a87 100644 --- a/aspnetcore/blazor/fundamentals/signalr.md +++ b/aspnetcore/blazor/fundamentals/signalr.md @@ -491,11 +491,39 @@ In the `Program` file, call . :::moniker range=">= aspnetcore-8.0" -To customize the UI, define a single element with an `id` of `components-reconnect-modal`. The following example places the element in the `App` component. +To customize the UI, define a single element with an `id` of `components-reconnect-modal` in the `` element content. The following example places the element in the `App` component. `App.razor`: @@ -503,7 +531,7 @@ To customize the UI, define a single element with an `id` of `components-reconne :::moniker range=">= aspnetcore-7.0 < aspnetcore-8.0" -To customize the UI, define a single element with an `id` of `components-reconnect-modal`. The following example places the element in the host page. +To customize the UI, define a single element with an `id` of `components-reconnect-modal` in the `` element content. The following example places the element in the host page. `Pages/_Host.cshtml`: @@ -511,7 +539,7 @@ To customize the UI, define a single element with an `id` of `components-reconne :::moniker range=">= aspnetcore-6.0 < aspnetcore-7.0" -To customize the UI, define a single element with an `id` of `components-reconnect-modal`. The following example places the element in the layout page. +To customize the UI, define a single element with an `id` of `components-reconnect-modal` in the `` element content. The following example places the element in the layout page. `Pages/_Layout.cshtml`: @@ -519,7 +547,7 @@ To customize the UI, define a single element with an `id` of `components-reconne :::moniker range="< aspnetcore-6.0" -To customize the UI, define a single element with an `id` of `components-reconnect-modal`. The following example places the element in the host page. +To customize the UI, define a single element with an `id` of `components-reconnect-modal` in the `` element content. The following example places the element in the host page. `Pages/_Host.cshtml`: @@ -527,7 +555,7 @@ To customize the UI, define a single element with an `id` of `components-reconne ```cshtml
- There was a problem with the connection! + Connection lost.
Attempting to reconnect...
``` @@ -557,6 +585,15 @@ Add the following CSS styles to the site's stylesheet. #components-reconnect-modal.components-reconnect-failed, #components-reconnect-modal.components-reconnect-rejected { display: block; + background-color: white; + padding: 2rem; + border-radius: 0.5rem; + text-align: center; + box-shadow: 0 3px 6px 2px rgba(0, 0, 0, 0.3); + margin: 50px 50px; + position: fixed; + top: 0; + z-index: 10001; } ``` @@ -581,7 +618,7 @@ Customize the delay before the reconnection UI appears by setting the `transitio :::moniker-end -:::moniker range="< aspnetcore-8.0" +:::moniker range=">= aspnetcore-5.0 < aspnetcore-8.0" `wwwroot/css/site.css`: @@ -606,11 +643,9 @@ To display the current reconnect attempt, define an element with an `id` of `com ``` -When the custom reconnect modal appears, it renders content similar to the following based on the preceding code: +When the custom reconnect modal appears, it renders the following content with a reconnection attempt counter: -```html -There was a problem with the connection! (Current reconnect attempt: 3 / 8) -``` +> :::no-loc text="There was a problem with the connection! (Current reconnect attempt: 1 / 8)"::: :::moniker-end diff --git a/aspnetcore/blazor/fundamentals/signalr/_static/reconnection-ui-80-or-earlier.png b/aspnetcore/blazor/fundamentals/signalr/_static/reconnection-ui-80-or-earlier.png new file mode 100644 index 000000000000..ff7e64fc6144 Binary files /dev/null and b/aspnetcore/blazor/fundamentals/signalr/_static/reconnection-ui-80-or-earlier.png differ diff --git a/aspnetcore/blazor/fundamentals/signalr/_static/reconnection-ui-90-or-later.png b/aspnetcore/blazor/fundamentals/signalr/_static/reconnection-ui-90-or-later.png new file mode 100644 index 000000000000..a08404aa2fdc Binary files /dev/null and b/aspnetcore/blazor/fundamentals/signalr/_static/reconnection-ui-90-or-later.png differ diff --git a/aspnetcore/blazor/fundamentals/signalr/_static/retry-ui-80-or-earlier.png b/aspnetcore/blazor/fundamentals/signalr/_static/retry-ui-80-or-earlier.png new file mode 100644 index 000000000000..cf4b924024fc Binary files /dev/null and b/aspnetcore/blazor/fundamentals/signalr/_static/retry-ui-80-or-earlier.png differ diff --git a/aspnetcore/blazor/fundamentals/signalr/_static/retry-ui-90-or-later.png b/aspnetcore/blazor/fundamentals/signalr/_static/retry-ui-90-or-later.png new file mode 100644 index 000000000000..59a2d775a4c7 Binary files /dev/null and b/aspnetcore/blazor/fundamentals/signalr/_static/retry-ui-90-or-later.png differ diff --git a/aspnetcore/blazor/hybrid/troubleshoot.md b/aspnetcore/blazor/hybrid/troubleshoot.md index 0bbcd11e1b1c..85de7a18f5c0 100644 --- a/aspnetcore/blazor/hybrid/troubleshoot.md +++ b/aspnetcore/blazor/hybrid/troubleshoot.md @@ -10,11 +10,7 @@ uid: blazor/hybrid/troubleshoot --- # Troubleshoot ASP.NET Core Blazor Hybrid - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] has built-in logging that can help you diagnose problems in your Blazor Hybrid app. diff --git a/aspnetcore/blazor/hybrid/tutorials/maui-blazor-web-app.md b/aspnetcore/blazor/hybrid/tutorials/maui-blazor-web-app.md index 24079ade0b7d..d27cbd51beba 100644 --- a/aspnetcore/blazor/hybrid/tutorials/maui-blazor-web-app.md +++ b/aspnetcore/blazor/hybrid/tutorials/maui-blazor-web-app.md @@ -10,6 +10,8 @@ uid: blazor/hybrid/tutorials/maui-blazor-web-app --- # Build a .NET MAUI Blazor Hybrid app with a Blazor Web App +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] + This article shows you how to build a .NET MAUI Blazor Hybrid app with a Blazor Web App that uses a shared user interface via a Razor class library (RCL). ## Prerequisites and preliminary steps diff --git a/aspnetcore/blazor/javascript-interoperability/static-server-rendering.md b/aspnetcore/blazor/javascript-interoperability/static-server-rendering.md index 62f9baf36a23..9213318c4a28 100644 --- a/aspnetcore/blazor/javascript-interoperability/static-server-rendering.md +++ b/aspnetcore/blazor/javascript-interoperability/static-server-rendering.md @@ -10,11 +10,7 @@ uid: blazor/js-interop/ssr --- # ASP.NET Core Blazor JavaScript with static server-side rendering (static SSR) - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] This article explains how to load JavaScript (JS) in a Blazor Web App with static server-side rendering (static SSR) and [enhanced navigation](xref:blazor/fundamentals/routing#enhanced-navigation-and-form-handling). diff --git a/aspnetcore/blazor/security/blazor-web-app-with-oidc.md b/aspnetcore/blazor/security/blazor-web-app-with-oidc.md index d8a483d84e53..9234319c0240 100644 --- a/aspnetcore/blazor/security/blazor-web-app-with-oidc.md +++ b/aspnetcore/blazor/security/blazor-web-app-with-oidc.md @@ -11,11 +11,7 @@ zone_pivot_groups: blazor-web-app-oidc-specification --- # Secure an ASP.NET Core Blazor Web App with OpenID Connect (OIDC) - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] This article describes how to secure a Blazor Web App with [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works/) using a sample app in the [`dotnet/blazor-samples` GitHub repository (.NET 8 or later)](https://github.com/dotnet/blazor-samples) ([how to download](xref:blazor/fundamentals/index#sample-apps)). diff --git a/aspnetcore/blazor/security/server/account-confirmation-and-password-recovery.md b/aspnetcore/blazor/security/server/account-confirmation-and-password-recovery.md index 568b3d64e619..00b5301384d7 100644 --- a/aspnetcore/blazor/security/server/account-confirmation-and-password-recovery.md +++ b/aspnetcore/blazor/security/server/account-confirmation-and-password-recovery.md @@ -9,6 +9,8 @@ uid: blazor/security/server/account-confirmation-and-password-recovery --- # Account confirmation and password recovery in ASP.NET Core Blazor +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] + This article explains how to configure an ASP.NET Core Blazor Web App with email confirmation and password recovery. ## Namespace diff --git a/aspnetcore/blazor/security/server/qrcodes-for-authenticator-apps.md b/aspnetcore/blazor/security/server/qrcodes-for-authenticator-apps.md index 8e63126a14c5..33b495535c71 100644 --- a/aspnetcore/blazor/security/server/qrcodes-for-authenticator-apps.md +++ b/aspnetcore/blazor/security/server/qrcodes-for-authenticator-apps.md @@ -9,6 +9,8 @@ uid: blazor/security/server/qrcodes-for-authenticator-apps --- # Enable QR code generation for TOTP authenticator apps in an ASP.NET Core Blazor Web App +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] + This article explains how to configure an ASP.NET Core Blazor Web App with QR code generation for TOTP authenticator apps. For an introduction to two-factor authentication (2FA) with authenticator apps using a Time-based One-time Password Algorithm (TOTP), see . diff --git a/aspnetcore/blazor/security/server/static-server-side-rendering.md b/aspnetcore/blazor/security/server/static-server-side-rendering.md index aae18ca506f6..5425a21a4841 100644 --- a/aspnetcore/blazor/security/server/static-server-side-rendering.md +++ b/aspnetcore/blazor/security/server/static-server-side-rendering.md @@ -10,11 +10,7 @@ uid: blazor/security/server/static-server-side-rendering --- # Threat mitigation guidance for ASP.NET Core Blazor static server-side rendering - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] This article explains the security considerations that developers should take into account when developing Blazor Web Apps with static server-side rendering. diff --git a/aspnetcore/blazor/security/webassembly/microsoft-entra-id-groups-and-roles.md b/aspnetcore/blazor/security/webassembly/microsoft-entra-id-groups-and-roles.md index 42140e821e42..5c2edd4c9b01 100644 --- a/aspnetcore/blazor/security/webassembly/microsoft-entra-id-groups-and-roles.md +++ b/aspnetcore/blazor/security/webassembly/microsoft-entra-id-groups-and-roles.md @@ -10,11 +10,7 @@ uid: blazor/security/webassembly/meid-groups-roles --- # Microsoft Entra (ME-ID) groups, Administrator Roles, and App Roles - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] This article explains how to configure Blazor WebAssembly to use Microsoft Entra ID (ME-ID) groups and roles. diff --git a/aspnetcore/blazor/security/webassembly/standalone-with-identity.md b/aspnetcore/blazor/security/webassembly/standalone-with-identity.md index 27a24a5c3134..039ddd0989cf 100644 --- a/aspnetcore/blazor/security/webassembly/standalone-with-identity.md +++ b/aspnetcore/blazor/security/webassembly/standalone-with-identity.md @@ -10,11 +10,7 @@ uid: blazor/security/webassembly/standalone-with-identity --- # Secure ASP.NET Core Blazor WebAssembly with ASP.NET Core Identity - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] Standalone Blazor WebAssembly apps can be secured with ASP.NET Core Identity by following the guidance in this article. diff --git a/aspnetcore/blazor/tutorials/movie-database-app/index.md b/aspnetcore/blazor/tutorials/movie-database-app/index.md index ce8f277a6271..7e442bd521b8 100644 --- a/aspnetcore/blazor/tutorials/movie-database-app/index.md +++ b/aspnetcore/blazor/tutorials/movie-database-app/index.md @@ -10,11 +10,7 @@ uid: blazor/tutorials/movie-database-app/index --- # Build a Blazor movie database app (Overview) - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] This tutorial explains the basics of building a Blazor Web App with a database, Entity Framework (EF) Core, and user interactivity. diff --git a/aspnetcore/blazor/tutorials/movie-database-app/part-1.md b/aspnetcore/blazor/tutorials/movie-database-app/part-1.md index 591dedf6ac40..785cc3611872 100644 --- a/aspnetcore/blazor/tutorials/movie-database-app/part-1.md +++ b/aspnetcore/blazor/tutorials/movie-database-app/part-1.md @@ -11,11 +11,7 @@ zone_pivot_groups: tooling --- # Build a Blazor movie database app (Part 1 - Create a Blazor Web App) - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] This article is the first part of the Blazor movie database app tutorial that teaches you the basics of building an ASP.NET Core Blazor Web App with features to manage a movie database. diff --git a/aspnetcore/blazor/tutorials/movie-database-app/part-2.md b/aspnetcore/blazor/tutorials/movie-database-app/part-2.md index bf928dd347db..28c463234a08 100644 --- a/aspnetcore/blazor/tutorials/movie-database-app/part-2.md +++ b/aspnetcore/blazor/tutorials/movie-database-app/part-2.md @@ -11,11 +11,7 @@ zone_pivot_groups: tooling --- # Build a Blazor movie database app (Part 2 - Add and scaffold a model) - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] This article is the second part of the Blazor movie database app tutorial that teaches you the basics of building an ASP.NET Core Blazor Web App with features to manage a movie database. diff --git a/aspnetcore/blazor/tutorials/movie-database-app/part-3.md b/aspnetcore/blazor/tutorials/movie-database-app/part-3.md index 3c2a2128448e..d3caa7123df3 100644 --- a/aspnetcore/blazor/tutorials/movie-database-app/part-3.md +++ b/aspnetcore/blazor/tutorials/movie-database-app/part-3.md @@ -11,11 +11,7 @@ zone_pivot_groups: tooling --- # Build a Blazor movie database app (Part 3 - Learn about Razor components) - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] This article is the third part of the Blazor movie database app tutorial that teaches you the basics of building an ASP.NET Core Blazor Web App with features to manage a movie database. diff --git a/aspnetcore/blazor/tutorials/movie-database-app/part-4.md b/aspnetcore/blazor/tutorials/movie-database-app/part-4.md index 786d8137a4cc..1624688f2abc 100644 --- a/aspnetcore/blazor/tutorials/movie-database-app/part-4.md +++ b/aspnetcore/blazor/tutorials/movie-database-app/part-4.md @@ -11,11 +11,7 @@ zone_pivot_groups: tooling --- # Build a Blazor movie database app (Part 4 - Work with a database) - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] This article is the fourth part of the Blazor movie database app tutorial that teaches you the basics of building an ASP.NET Core Blazor Web App with features to manage a movie database. diff --git a/aspnetcore/blazor/tutorials/movie-database-app/part-5.md b/aspnetcore/blazor/tutorials/movie-database-app/part-5.md index 4adfca722b0e..1f4e6ad6565e 100644 --- a/aspnetcore/blazor/tutorials/movie-database-app/part-5.md +++ b/aspnetcore/blazor/tutorials/movie-database-app/part-5.md @@ -11,11 +11,7 @@ zone_pivot_groups: tooling --- # Build a Blazor movie database app (Part 5 - Add validation) - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] This article is the fifth part of the Blazor movie database app tutorial that teaches you the basics of building an ASP.NET Core Blazor Web App with features to manage a movie database. diff --git a/aspnetcore/blazor/tutorials/movie-database-app/part-6.md b/aspnetcore/blazor/tutorials/movie-database-app/part-6.md index bdb4ada8949a..1b9bb7cc88e9 100644 --- a/aspnetcore/blazor/tutorials/movie-database-app/part-6.md +++ b/aspnetcore/blazor/tutorials/movie-database-app/part-6.md @@ -11,11 +11,7 @@ zone_pivot_groups: tooling --- # Build a Blazor movie database app (Part 6 - Add search) - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] This article is the sixth part of the Blazor movie database app tutorial that teaches you the basics of building an ASP.NET Core Blazor Web App with features to manage a movie database. diff --git a/aspnetcore/blazor/tutorials/movie-database-app/part-7.md b/aspnetcore/blazor/tutorials/movie-database-app/part-7.md index 02d313dd032a..4beff2eaab38 100644 --- a/aspnetcore/blazor/tutorials/movie-database-app/part-7.md +++ b/aspnetcore/blazor/tutorials/movie-database-app/part-7.md @@ -11,11 +11,7 @@ zone_pivot_groups: tooling --- # Build a Blazor movie database app (Part 7 - Add a new field) - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] This article is the seventh part of the Blazor movie database app tutorial that teaches you the basics of building an ASP.NET Core Blazor Web App with features to manage a movie database. diff --git a/aspnetcore/blazor/tutorials/movie-database-app/part-8.md b/aspnetcore/blazor/tutorials/movie-database-app/part-8.md index fe73f9c6899c..9c1968bc0c2d 100644 --- a/aspnetcore/blazor/tutorials/movie-database-app/part-8.md +++ b/aspnetcore/blazor/tutorials/movie-database-app/part-8.md @@ -11,11 +11,7 @@ zone_pivot_groups: tooling --- # Build a Blazor movie database app (Part 8 - Add interactivity) - +[!INCLUDE[](~/includes/not-latest-version-without-not-supported-content.md)] This article is the eighth part of the Blazor movie database app tutorial that teaches you the basics of building an ASP.NET Core Blazor Web App with features to manage a movie database. diff --git a/aspnetcore/diagnostics/asp0028.md b/aspnetcore/diagnostics/asp0028.md new file mode 100644 index 000000000000..99a03bce9e8d --- /dev/null +++ b/aspnetcore/diagnostics/asp0028.md @@ -0,0 +1,66 @@ +--- +title: "ASP0028: ## Analyzer to suggest using IPAddress.IPv6Any instead of IPAddress.Any if applicable" +ms.date: 11/11/2024 +description: "Learn about analysis rule ASP0028: Consider using IPAddress.IPv6Any instead of IPAddress.Any" +author: deaglegross +monikerRange: '>= aspnetcore-10.0' +ms.author: deaglegross +uid: diagnostics/asp0028 +--- +# ASP0028: Consider using `IPAddress.IPv6Any` instead of `IPAddress.Any` + +| | Value | +| - | - | +| **Rule ID** | ASP0028 | +| **Category** | Usage | +| **Fix is breaking or non-breaking** | Non-breaking | + +## Cause + +On the server machine that supports IPv6, listening to `Any`, rather than `IPv6Any` will either not work or be slower than necessary, because of the [underlying System types implementation](https://github.com/dotnet/runtime/issues/82404). + +At the moment of current article publishing, in case of HTTP/1.x or HTTP/2.0 a name like `localhost` will resolve to `[::1]`, which won't be accepted by the server, forcing a retry with `127.0.0.1` (i.e. failed attempt before each connection). + +This usage will be reported with a diagnostic message: +```csharp +.UseKestrel().ConfigureKestrel(options => +{ + options.Listen(IPAddress.Any, ...); +}) +``` + +## Rule description + +The recommended way is to setup Kestrel to listen on `IPv6Any`. + +## How to fix violations + +For the reported code +```csharp +.UseKestrel().ConfigureKestrel(options => +{ + options.Listen(IPAddress.Any, ...); +}) +``` + +One can either explicitly change usage to `IPv6Any`: +```csharp +.UseKestrel().ConfigureKestrel(options => +{ + options.Listen(IPAddress.IPv6Any, ...); +}) +``` + +or use another invocation - `options.ListenAnyIP()` without specifying any argument explicitly: +```csharp +.UseKestrel().ConfigureKestrel(options => +{ + options.ListenAnyIP(...); +}) +``` + +## When to suppress warnings + +The severity level of this diagnostic is Information. You can suppress warnings if your intention is to disable `IPv6` usage completely on the server. + +You can disable IPv6 either system-wide, or for .NET only via the [AppCtx switch or environment variable](https://devblogs.microsoft.com/dotnet/dotnet-6-networking-improvements/#an-option-to-globally-disable-ipv6) diff --git a/aspnetcore/fundamentals/index.md b/aspnetcore/fundamentals/index.md index 515d419359f5..164a5df16670 100644 --- a/aspnetcore/fundamentals/index.md +++ b/aspnetcore/fundamentals/index.md @@ -12,7 +12,7 @@ uid: fundamentals/index [!INCLUDE[](~/includes/not-latest-version.md)] -:::moniker range=">= aspnetcore-8.0" +:::moniker range=">= aspnetcore-9.0" This article provides an overview of the fundamentals for building ASP.NET Core apps, including dependency injection (DI), configuration, middleware, and more. @@ -232,3 +232,4 @@ For more information, see . :::moniker-end [!INCLUDE[](~/fundamentals/index/includes/index3-7.md)] +[!INCLUDE[](~/fundamentals/index/includes/index8.md)] diff --git a/aspnetcore/fundamentals/index/includes/index8.md b/aspnetcore/fundamentals/index/includes/index8.md new file mode 100644 index 000000000000..30a71cf07228 --- /dev/null +++ b/aspnetcore/fundamentals/index/includes/index8.md @@ -0,0 +1,218 @@ +:::moniker range="= aspnetcore-8.0" + +This article provides an overview of the fundamentals for building ASP.NET Core apps, including dependency injection (DI), configuration, middleware, and more. + +For Blazor fundamentals guidance, which adds to or supersedes the guidance in this node, see . + +## Program.cs + +ASP.NET Core apps created with the web templates contain the application startup code in the `Program.cs` file. The `Program.cs` file is where: + +* Services required by the app are configured. +* The app's request handling pipeline is defined as a series of [middleware components](xref:fundamentals/middleware/index). + +The following app startup code supports: + +* [Razor Pages](xref:tutorials/razor-pages/razor-pages-start) +* [MVC controllers with views](xref:tutorials/first-mvc-app/start-mvc) +* [Web API with controllers](xref:tutorials/first-web-api) +* [Minimal web APIs](xref:tutorials/min-web-api) + +[!code-csharp[](~/fundamentals/startup/6.0_samples/WebAll/Program.cs?name=snippet)] + +## Dependency injection (services) + +ASP.NET Core includes [dependency injection (DI)](xref:fundamentals/dependency-injection) that makes configured services available throughout an app. Services are added to the DI container with [WebApplicationBuilder.Services](xref:Microsoft.AspNetCore.Builder.WebApplicationBuilder.Services), `builder.Services` in the preceding code. When the is instantiated, many [framework-provided services](xref:fundamentals/dependency-injection#framework-provided-services) are added. `builder` is a `WebApplicationBuilder` in the following code: + +[!code-csharp[](~/fundamentals/startup/6.0_samples/WebAll/Program.cs?name=snippet2&highlight=1)] + +In the preceding highlighted code, `builder` has configuration, logging, and [many other services](xref:fundamentals/dependency-injection#framework-provided-services) added to the DI container. + +The following code adds Razor Pages, MVC controllers with views, and a custom to the DI container: + +[!code-csharp[](~/fundamentals/index/samples/6.0/RazorPagesMovie/Program.cs?name=snippet2&highlight=6-10)] + +Services are typically resolved from DI using constructor injection. The DI framework provides an instance of this service at runtime. + +The following code uses constructor injection to resolve the database context and logger from DI: + +[!code-csharp[](~/fundamentals/index/samples/6.0/RazorPagesMovie/Pages/Movies/Index.cshtml.cs?name=snippet&highlight=3-10, 16-17)] + +## Middleware + +The request handling pipeline is composed as a series of middleware components. Each component performs operations on an [`HttpContext`](xref:fundamentals/httpcontext) and either invokes the next middleware in the pipeline or terminates the request. + +By convention, a middleware component is added to the pipeline by invoking a `Use{Feature}` extension method. Middleware added to the app is highlighted in the following code: + +[!code-csharp[](~/fundamentals/startup/6.0_samples/WebAll/Program.cs?name=snippet&highlight=12-19)] + +For more information, see . + +## Host + +On startup, an ASP.NET Core app builds a *host*. The host encapsulates all of the app's resources, such as: + +* An HTTP server implementation +* Middleware components +* Logging +* Dependency injection (DI) services +* Configuration + +There are three different hosts capable of running an ASP.NET Core app: + +* [ASP.NET Core WebApplication](xref:fundamentals/minimal-apis/webapplication), also known as the [Minimal Host](xref:migration/50-to-60#new-hosting-model) +* [.NET Generic Host](xref:fundamentals/host/generic-host) combined with ASP.NET Core's +* [ASP.NET Core WebHost](xref:fundamentals/host/web-host) + +The ASP.NET Core and types are recommended and used in all the ASP.NET Core templates. `WebApplication` behaves similarly to the .NET Generic Host and exposes many of the same interfaces but requires less callbacks to configure. The ASP.NET Core is available only for backward compatibility. + +The following example instantiates a `WebApplication`: + +[!code-csharp[](~/fundamentals/startup/6.0_samples/WebAll/Program.cs?name=snippet2&highlight=7)] + +The [WebApplicationBuilder.Build](xref:Microsoft.AspNetCore.Builder.WebApplicationBuilder.Build%2A) method configures a host with a set of default options, such as: + +* Use [Kestrel](#servers) as the web server and enable IIS integration. +* Load [configuration](xref:fundamentals/configuration/index) from `appsettings.json`, environment variables, command line arguments, and other configuration sources. +* Send logging output to the console and debug providers. + +### Non-web scenarios + +The Generic Host allows other types of apps to use cross-cutting framework extensions, such as logging, dependency injection (DI), configuration, and app lifetime management. For more information, see and . + +## Servers + +An ASP.NET Core app uses an HTTP server implementation to listen for HTTP requests. The server surfaces requests to the app as a set of [request features](xref:fundamentals/request-features) composed into an `HttpContext`. + +# [Windows](#tab/windows) + +ASP.NET Core provides the following server implementations: + +* *Kestrel* is a cross-platform web server. Kestrel is often run in a reverse proxy configuration using [IIS](https://www.iis.net/). In ASP.NET Core 2.0 or later, Kestrel can be run as a public-facing edge server exposed directly to the Internet. +* *IIS HTTP Server* is a server for Windows that uses IIS. With this server, the ASP.NET Core app and IIS run in the same process. +* *HTTP.sys* is a server for Windows that isn't used with IIS. + +# [macOS](#tab/macos) + +ASP.NET Core provides the *Kestrel* cross-platform server implementation. In ASP.NET Core 2.0 or later, Kestrel can run as a public-facing edge server exposed directly to the Internet. Kestrel is often run in a reverse proxy configuration with [Nginx](https://nginx.org) or [Apache](https://httpd.apache.org/). + +# [Linux](#tab/linux) + +ASP.NET Core provides the *Kestrel* cross-platform server implementation. In ASP.NET Core 2.0 or later, Kestrel can run as a public-facing edge server exposed directly to the Internet. Kestrel is often run in a reverse proxy configuration with [Nginx](https://nginx.org) or [Apache](https://httpd.apache.org/). + +--- + +For more information, see . + +## Configuration + +ASP.NET Core provides a [configuration](xref:fundamentals/configuration/index) framework that gets settings as name-value pairs from an ordered set of configuration providers. Built-in configuration providers are available for a variety of sources, such as `.json` files, `.xml` files, environment variables, and command-line arguments. Write custom configuration providers to support other sources. + +By [default](xref:fundamentals/configuration/index#default), ASP.NET Core apps are configured to read from `appsettings.json`, environment variables, the command line, and more. When the app's configuration is loaded, values from environment variables override values from `appsettings.json`. + +For managing confidential configuration data such as passwords, .NET Core provides the [Secret Manager](xref:security/app-secrets#secret-manager). For production secrets, we recommend [Azure Key Vault](xref:security/key-vault-configuration). + +For more information, see . + +## Environments + +Execution environments, such as `Development`, `Staging`, and `Production`, are available in ASP.NET Core. Specify the environment an app is running in by setting the `ASPNETCORE_ENVIRONMENT` environment variable. ASP.NET Core reads that environment variable at app startup and stores the value in an `IWebHostEnvironment` implementation. This implementation is available anywhere in an app via dependency injection (DI). + +The following example configures the exception handler and [HTTP Strict Transport Security Protocol (HSTS)](xref:security/enforcing-ssl#http-strict-transport-security-protocol-hsts) middleware when ***not*** running in the `Development` environment: + +[!code-csharp[](~/fundamentals/startup/6.0_samples/WebAll/Program.cs?name=snippet&highlight=10-14)] + +For more information, see . + +## Logging + +ASP.NET Core supports a logging API that works with a variety of built-in and third-party logging providers. Available providers include: + +* Console +* Debug +* Event Tracing on Windows +* Windows Event Log +* TraceSource +* Azure App Service +* Azure Application Insights + +To create logs, resolve an service from dependency injection (DI) and call logging methods such as . For example: + +[!code-csharp[](~/fundamentals/index/samples/6.0/RazorPagesMovie/Pages/Movies/Index.cshtml.cs?name=snippet&highlight=3-10, 16-17)] + +For more information, see . + +## Routing + +A *route* is a URL pattern that is mapped to a handler. The handler is typically a Razor page, an action method in an MVC controller, or a middleware. ASP.NET Core routing gives you control over the URLs used by your app. + +The following code, generated by the ASP.NET Core web application template, calls : + +[!code-csharp[](~/fundamentals/startup/6.0_samples/WebAll/Program.cs?name=snippet4&highlight=17)] + +For more information, see . + +## Error handling + +ASP.NET Core has built-in features for handling errors, such as: + +* A developer exception page +* Custom error pages +* Static status code pages +* Startup exception handling + +For more information, see . + +## Make HTTP requests + +An implementation of `IHttpClientFactory` is available for creating `HttpClient` instances. The factory: + +* Provides a central location for naming and configuring logical `HttpClient` instances. For example, register and configure a *github* client for accessing GitHub. Register and configure a default client for other purposes. +* Supports registration and chaining of multiple delegating handlers to build an outgoing request middleware pipeline. This pattern is similar to ASP.NET Core's inbound middleware pipeline. The pattern provides a mechanism to manage cross-cutting concerns for HTTP requests, including caching, error handling, serialization, and logging. +* Integrates with *Polly*, a popular third-party library for transient fault handling. +* Manages the pooling and lifetime of underlying `HttpClientHandler` instances to avoid common DNS problems that occur when managing `HttpClient` lifetimes manually. +* Adds a configurable logging experience via for all requests sent through clients created by the factory. + +For more information, see . + +## Content root + +The content root is the base path for: + +* The executable hosting the app (*.exe*). +* Compiled assemblies that make up the app (*.dll*). +* Content files used by the app, such as: + * Razor files (`.cshtml`, `.razor`) + * Configuration files (`.json`, `.xml`) + * Data files (`.db`) +* The [Web root](#web-root), typically the *wwwroot* folder. + +During development, the content root defaults to the project's root directory. This directory is also the base path for both the app's content files and the [Web root](#web-root). Specify a different content root by setting its path when [building the host](#host). For more information, see [Content root](xref:fundamentals/host/generic-host#contentroot). + +## Web root + +The web root is the base path for public, static resource files, such as: + +* Stylesheets (`.css`) +* JavaScript (`.js`) +* Images (`.png`, `.jpg`) + +By default, static files are served only from the web root directory and its sub-directories. The web root path defaults to *{content root}/wwwroot*. Specify a different web root by setting its path when [building the host](#host). For more information, see [Web root](xref:fundamentals/host/generic-host#webroot). + +Prevent publishing files in *wwwroot* with the [\ project item](/visualstudio/msbuild/common-msbuild-project-items#content) in the project file. The following example prevents publishing content in *wwwroot/local* and its sub-directories: + +```xml + + + +``` + +In Razor `.cshtml` files, `~/` points to the web root. A path beginning with `~/` is referred to as a *virtual path*. + +For more information, see . + +## Additional resources + +* [WebApplicationBuilder source code](https://github.com/dotnet/aspnetcore/blob/v6.0.1/src/DefaultBuilder/src/WebApplicationBuilder.cs) + +:::moniker-end diff --git a/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md b/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md index d047c39d3d08..a6f8187b716c 100644 --- a/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md +++ b/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md @@ -29,7 +29,7 @@ Install the `Microsoft.AspNetCore.OpenApi` package: Run the following command from the **Package Manager Console**: ```powershell - Install-Package Microsoft.AspNetCore.OpenApi -IncludePrerelease + Install-Package Microsoft.AspNetCore.OpenApi ``` ### [.NET CLI](#tab/net-cli) @@ -37,7 +37,7 @@ Run the following command from the **Package Manager Console**: Run the following command: ```dotnetcli -dotnet add package Microsoft.AspNetCore.OpenApi --prerelease +dotnet add package Microsoft.AspNetCore.OpenApi ``` --- @@ -133,7 +133,7 @@ To add support for generating OpenAPI documents at build time, install the `Micr Run the following command from the **Package Manager Console**: ```powershell - Install-Package Microsoft.Extensions.ApiDescription.Server -IncludePrerelease + Install-Package Microsoft.Extensions.ApiDescription.Server ``` ### [.NET CLI](#tab/net-cli) @@ -141,7 +141,7 @@ Run the following command from the **Package Manager Console**: Run the following command in the directory that contains the project file: ```dotnetcli -dotnet add package Microsoft.Extensions.ApiDescription.Server --prerelease +dotnet add package Microsoft.Extensions.ApiDescription.Server ``` --- diff --git a/aspnetcore/includes/not-latest-version-without-not-supported-content.md b/aspnetcore/includes/not-latest-version-without-not-supported-content.md new file mode 100644 index 000000000000..a7f3e4d4a3a7 --- /dev/null +++ b/aspnetcore/includes/not-latest-version-without-not-supported-content.md @@ -0,0 +1,29 @@ +:::moniker range="< aspnetcore-9.0" +> [!NOTE] +> This isn't the latest version of this article. For the current release, see the [.NET 9 version of this article](?view=aspnetcore-9.0&preserve-view=true). +:::moniker-end + +:::moniker range="> aspnetcore-9.0" +> [!IMPORTANT] +> This information relates to a pre-release product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. +> +> For the current release, see the [.NET 9 version of this article](?view=aspnetcore-9.0&preserve-view=true). +:::moniker-end + + diff --git a/aspnetcore/includes/not-latest-version.md b/aspnetcore/includes/not-latest-version.md index ca1f12faf3e4..1eccb5a2b614 100644 --- a/aspnetcore/includes/not-latest-version.md +++ b/aspnetcore/includes/not-latest-version.md @@ -15,9 +15,20 @@ :::moniker-end diff --git a/aspnetcore/log-mon/metrics/metrics.md b/aspnetcore/log-mon/metrics/metrics.md index 2f8cacf28652..f438b55439a1 100644 --- a/aspnetcore/log-mon/metrics/metrics.md +++ b/aspnetcore/log-mon/metrics/metrics.md @@ -90,6 +90,7 @@ For more information, see [dotnet-counters](/dotnet/core/diagnostics/dotnet-coun ## Enrich the ASP.NET Core request metric ASP.NET Core has many built-in metrics. The `http.server.request.duration` metric: + * Records the duration of HTTP requests on the server. * Captures request information in tags, such as the matched route and response status code. @@ -106,7 +107,29 @@ The proceeding example: * The tag allows requests to be categorized by marketing medium type, which could be useful when analyzing web app traffic. > [!NOTE] -> Follow the [multi-dimensional metrics](/dotnet/core/diagnostics/metrics-instrumentation#multi-dimensional-metrics) best practices when enriching with custom tags. Too many tags, or tags with an unbound range cause a large combination of tags. Collection tools have a limit on how many combinations they support for a counter and may start filtering results out to avoid excessive memory usage. +> Follow the [multi-dimensional metrics](/dotnet/core/diagnostics/metrics-instrumentation#multi-dimensional-metrics) best practices when enriching with custom tags. Tags that are too numerous or have an unbound range create many tag combinations, resulting in high dimensions. Collection tools have limits on supported dimensions for a counter and may filter results to prevent excessive memory use. + +:::moniker range=">= aspnetcore-9.0" + +## Opt-out of HTTP metrics on certain endpoints and requests + +Opting out of recording metrics is beneficial for endpoints frequently called by automated systems, such as health checks. Recording metrics for these requests is generally unnecessary. Unwanted telemetry uses resources to collect and store, and can distort results displayed in a telemetry dashboard. + +HTTP requests to an endpoint can be excluded from metrics by adding metadata, with either the [DisableHttpMetrics](xref:Microsoft.AspNetCore.Http.DisableHttpMetricsAttribute) attribute or the [DisableHttpMetrics](xref:Microsoft.AspNetCore.Builder.HttpMetricsEndpointConventionBuilderExtensions.DisableHttpMetrics``1(``0)) method: + +* Add the [DisableHttpMetrics](xref:Microsoft.AspNetCore.Http.DisableHttpMetricsAttribute) attribute to the Web API controller, SignalR hub or gRPC service. +* Call [DisableHttpMetrics](xref:Microsoft.AspNetCore.Builder.HttpMetricsEndpointConventionBuilderExtensions.DisableHttpMetrics``1(``0)) when mapping endpoints in app startup: + +:::code language="csharp" source="~/log-mon/metrics/metrics/samples/DisableMetrics/Program.cs" id="snippet_1" highlight="5"::: + +Alternatively, the property has been added for: + +* Advanced scenarios where a request doesn't map to an endpoint. +* Dynamically disabling metrics collection for specific HTTP requests. + +:::code language="csharp" source="~/log-mon/metrics/metrics/samples/DisableMetrics/Program.cs" id="snippet_2"::: + +:::moniker-end ## Create custom metrics diff --git a/aspnetcore/log-mon/metrics/metrics/samples/DisableMetrics/DisableMetrics.csproj b/aspnetcore/log-mon/metrics/metrics/samples/DisableMetrics/DisableMetrics.csproj new file mode 100644 index 000000000000..6568b3dcfb4b --- /dev/null +++ b/aspnetcore/log-mon/metrics/metrics/samples/DisableMetrics/DisableMetrics.csproj @@ -0,0 +1,9 @@ + + + + net9.0 + enable + enable + + + diff --git a/aspnetcore/log-mon/metrics/metrics/samples/DisableMetrics/Program.cs b/aspnetcore/log-mon/metrics/metrics/samples/DisableMetrics/Program.cs new file mode 100644 index 000000000000..cb94e4c6506f --- /dev/null +++ b/aspnetcore/log-mon/metrics/metrics/samples/DisableMetrics/Program.cs @@ -0,0 +1,36 @@ +#define SECOND // FIRST SECOND +#if NEVER +#elif FIRST +// +var builder = WebApplication.CreateBuilder(args); +builder.Services.AddHealthChecks(); + +var app = builder.Build(); +app.MapHealthChecks("/healthz").DisableHttpMetrics(); +app.Run(); +// +#elif SECOND +using Microsoft.AspNetCore.Http.Features; + +var builder = WebApplication.CreateBuilder(args); +var app = builder.Build(); + +app.MapGet("/", () => "Hello World!"); + +// +// Middleware that conditionally opts-out HTTP requests. +app.Use(async (context, next) => +{ + var metricsFeature = context.Features.Get(); + if (metricsFeature != null && + context.Request.Headers.ContainsKey("x-disable-metrics")) + { + metricsFeature.MetricsDisabled = true; + } + + await next(context); +}); +// + +app.Run(); +#endif diff --git a/aspnetcore/signalr/dotnet-client.md b/aspnetcore/signalr/dotnet-client.md index 111e0c335909..fec34200767d 100644 --- a/aspnetcore/signalr/dotnet-client.md +++ b/aspnetcore/signalr/dotnet-client.md @@ -139,7 +139,7 @@ connection.Closed += error => In order to configure a custom number of reconnect attempts before disconnecting or change the reconnect timing, `WithAutomaticReconnect` accepts an array of numbers representing the delay in milliseconds to wait before starting each reconnect attempt. ```csharp -HubConnection connection= new HubConnectionBuilder() +HubConnection connection = new HubConnectionBuilder() .WithUrl(new Uri("http://127.0.0.1:5000/chathub")) .WithAutomaticReconnect(new[] { TimeSpan.Zero, TimeSpan.Zero, TimeSpan.FromSeconds(10) }) .Build(); @@ -231,7 +231,7 @@ The `InvokeAsync` method returns a `Task` which completes when the server method The `SendAsync` method returns a `Task` which completes when the message has been sent to the server. No return value is provided since this `Task` doesn't wait until the server method completes. Any exceptions thrown on the client while sending the message produce a faulted `Task`. Use `await` and `try...catch` syntax to handle send errors. > [!NOTE] -> Calling hub methods from a client is only supported when using the Azure SignalR Service in *Default* mode. For more information, see [Frequently Asked Questions (azure-signalr GitHub repository)](https://github.com/Azure/azure-signalr/blob/dev/docs/faq.md#what-is-the-meaning-of-service-mode-defaultserverlessclassic-how-can-i-choose). +> Calling hub methods from a client is only supported when using the Azure SignalR Service in *Default* mode. For more information, see [Frequently Asked Questions](/azure/azure-signalr/signalr-resource-faq). ## Call client methods from hub diff --git a/aspnetcore/signalr/dotnet-client/sample/SignalRChat/Hubs/ChatHub.cs b/aspnetcore/signalr/dotnet-client/sample/SignalRChat/Hubs/ChatHub.cs index 33129ec3944b..e37bba9dfcbf 100644 --- a/aspnetcore/signalr/dotnet-client/sample/SignalRChat/Hubs/ChatHub.cs +++ b/aspnetcore/signalr/dotnet-client/sample/SignalRChat/Hubs/ChatHub.cs @@ -8,7 +8,7 @@ public class ChatHub : Hub #region snippet_SendMessage public async Task SendMessage(string user, string message) { - await Clients.All.SendAsync("ReceiveMessage", user,message); + await Clients.All.SendAsync("ReceiveMessage", user, message); } #endregion }