diff --git a/aspnetcore/client-side/spa/intro.md b/aspnetcore/client-side/spa/intro.md index c672548fdd99..68197f45e158 100644 --- a/aspnetcore/client-side/spa/intro.md +++ b/aspnetcore/client-side/spa/intro.md @@ -1,11 +1,13 @@ --- -title: Overview of Single Page Apps (SPAs) in ASP.NET Core +title: Overview of Single Page Apps (SPAs) - ASP.NET Core author: wadepickett ms.author: wpickett monikerRange: '>= aspnetcore-6.0' -description: Overview of Single Page Apps (SPAs) in ASP.NET Core -ms.date: 09/12/2023 +description: Learn how to get started with Single Page Apps (SPAs) in ASP.NET Core and find links to tutorials for detailed procedures. +ms.date: 04/24/2026 uid: spa/intro + +# customer intent: As an ASP.NET developer, I want to get an overview of SPAs in ASP.NET Core, so I can determine the appropriate tutorial to create apps. --- # Overview of Single Page Apps (SPAs) in ASP.NET Core @@ -27,6 +29,10 @@ For more information, see [JavaScript and TypeScript in Visual Studio](/visualst [!INCLUDE [spa-templates-new-vs-old](../../includes/spa-templates-new-vs-old.md)] +## Related content + +- [Developing Single Page Apps](/aspnet/core/client-side/spa/intro?view=aspnetcore-7.0&preserve-view=true#developing-single-page-apps) + ::: moniker-end [!INCLUDE[](~/client-side/spa/includes/intro6-7.md)] diff --git a/aspnetcore/client-side/spa/react.md b/aspnetcore/client-side/spa/react.md index 15b8d337d855..4a90738456f8 100644 --- a/aspnetcore/client-side/spa/react.md +++ b/aspnetcore/client-side/spa/react.md @@ -5,8 +5,10 @@ description: Learn how to get started with the ASP.NET Core Single Page Applicat monikerRange: '>= aspnetcore-3.1' ms.author: wpickett ms.custom: mvc -ms.date: 09/08/2023 +ms.date: 04/24/2026 uid: spa/react + +# customer intent: As an ASP.NET developer, I want to get started with the SPA project template for React and CRA, so I can use React and create apps. --- # Use React with ASP.NET Core @@ -24,6 +26,10 @@ For more information, see [JavaScript and TypeScript in Visual Studio](/visualst [!INCLUDE [spa-templates-new-vs-old](../../includes/spa-templates-new-vs-old.md)] +## Related content + +- [Overview of Single Page Apps (SPAs) in ASP.NET Core](./intro.md) + :::moniker-end [!INCLUDE[](~/client-side/spa/includes/react3-7.md)] diff --git a/aspnetcore/fundamentals/servers/yarp/config-files.md b/aspnetcore/fundamentals/servers/yarp/config-files.md index 9e1cd45533fd..852476a401f5 100644 --- a/aspnetcore/fundamentals/servers/yarp/config-files.md +++ b/aspnetcore/fundamentals/servers/yarp/config-files.md @@ -1,22 +1,26 @@ --- uid: fundamentals/servers/yarp/config-files title: YARP Configuration Files -description: YARP Configuration Files +description: Explore how to work with YARP configuration files, examine the file structure and properties, define routes, clusters, and sources, and load proxy configuration. author: wadepickett ms.author: wpickett -ms.date: 2/6/2025 +ms.date: 04/24/2026 ms.topic: concept-article content_well_notification: AI-contribution ai-usage: ai-assisted ---- +# customer intent: As an ASP.NET developer, I want to get started with the YARP library, so I can learn how customize the modules. +--- # YARP Configuration Files -## Introduction -The reverse proxy can load configuration for routes and clusters from files using the IConfiguration abstraction from Microsoft.Extensions. The examples given here use JSON, but any IConfiguration source should work. The configuration will also be updated without restarting the proxy if the source file changes. +The reverse proxy can load configuration for routes and clusters from files by using the [IConfiguration](/dotnet/api/microsoft.extensions.configuration.iconfiguration) abstraction from Microsoft.Extensions. + +This article provides example proxy configuration for YARP. Although the configuration example uses JSON, any `IConfiguration` source should work. Also, the configuration updates without restarting the proxy when the source file changes. + +## Load the proxy configuration + +To load the proxy configuration from the `IConfiguration` instance, add the following code in the _Program.cs_ file: -## Loading Configuration -To load the proxy configuration from IConfiguration add the following code in Program.cs: ```csharp using Microsoft.AspNetCore.Builder; using Microsoft.Extensions.DependencyInjection; @@ -35,19 +39,26 @@ app.MapReverseProxy(); app.Run(); ``` -**Note**: For details about middleware ordering see [here](/aspnet/core/fundamentals/middleware/#middleware-order). -Configuration can be modified during the load sequence using [Configuration Filters](xref:fundamentals/servers/yarp/config-filters). +> [!NOTE] +> For details about middleware ordering, see [ASP.NET Core Middleware > Middleware order](/aspnet/core/fundamentals/middleware/#middleware-order). + +Configuration can be modified during the load sequence by using [YARP configuration filters](xref:fundamentals/servers/yarp/config-filters). + +## Load from multiple configuration sources + +Starting in version 1.1, YARP supports loading the proxy configuration from multiple sources. You can call the `LoadFromConfig` method multiple times and reference different `IConfiguration` sections. You can also combine the call with a different config source, such as InMemory. Routes can reference clusters from other sources. -## Multiple Configuration Sources -As of 1.1, YARP supports loading the proxy configuration from multiple sources. LoadFromConfig may be called multiple times referencing different IConfiguration sections or may be combine with a different config source like InMemory. Routes can reference clusters from other sources. Note merging partial config from different sources for a given route or cluster is not supported. +> [!NOTE] +> Merging partial config from different sources for a given route or cluster isn't supported. ```csharp services.AddReverseProxy() .LoadFromConfig(Configuration.GetSection("ReverseProxy1")) .LoadFromConfig(Configuration.GetSection("ReverseProxy2")); ``` -or +Another example: + ```csharp services.AddReverseProxy() @@ -55,13 +66,14 @@ services.AddReverseProxy() .LoadFromConfig(Configuration.GetSection("ReverseProxy")); ``` -## Configuration contract -File-based configuration is dynamically mapped to the types in [Yarp.ReverseProxy.Configuration](xref:Yarp.ReverseProxy.Configuration) namespace by an [IProxyConfigProvider](xref:Yarp.ReverseProxy.Configuration.IProxyConfigProvider) implementation converts at application start and each time the configuration changes. +## Review the configuration contract + +File-based configuration is dynamically mapped to the types in the [Yarp.ReverseProxy.Configuration](xref:Yarp.ReverseProxy.Configuration) namespace by an [IProxyConfigProvider](xref:Yarp.ReverseProxy.Configuration.IProxyConfigProvider) implementation. The contract converts at application start and each time the configuration changes. -## Configuration Structure -The configuration consists of a named section that you specified above via `Configuration.GetSection("ReverseProxy")`, and contains subsections for routes and clusters. +## Examine the configuration structure + +The configuration consists of a named section and subsections for routes and clusters. In the previous example, the named section is `Configuration.GetSection("ReverseProxy")`. -Example: ```json { "ReverseProxy": { @@ -87,29 +99,35 @@ Example: } ``` -### Routes +### Define configuration routes + +The `Routes` section is an unordered collection of route matches and their associated configuration. -The routes section is an unordered collection of route matches and their associated configuration. A route requires at least the following fields: +Each route requires at least the following fields: -* RouteId - a unique name -* ClusterId - refers to the name of an entry in the clusters section. -* Match - contains either a Hosts array or a Path pattern string. Path is an ASP.NET Core route template that can be defined as [explained here](/aspnet/core/fundamentals/routing#route-templates). +* `RouteId`: A unique name for the route. +* `ClusterId`: The name of an entry in the `Clusters` section. +* `Match`: Either a `Hosts` array or a `Path` pattern string. You can define the path by using [Routing in ASP.NET Core > Route templates](/aspnet/core/fundamentals/routing#route-templates). -Route matching is based on the most specific routes having highest precedence as described [here](/aspnet/core/fundamentals/routing#url-matching). Explicit ordering can be achieved using the `order` field, with lower values taking higher priority. +Route matching is based on the most specific routes having highest precedence, as described in [URL matching](/aspnet/core/fundamentals/routing#url-matching). Explicit ordering can be achieved by using the `order` field, where lower values take higher priority. -[Headers](xref:fundamentals/servers/yarp/header-routing), [Authorization](xref:fundamentals/servers/yarp/authn-authz), [CORS](xref:fundamentals/servers/yarp/cors), and other route based policies can be configured on each route entry. For additional fields see [RouteConfig](xref:Yarp.ReverseProxy.Configuration.RouteConfig). +[YARP headers](xref:fundamentals/servers/yarp/header-routing), [authentication and authorization](xref:fundamentals/servers/yarp/authn-authz), [cross-origin requests (CORS)](xref:fundamentals/servers/yarp/cors), and other route-based policies can be configured on each route entry. For other fields, see the [RouteConfig](xref:Yarp.ReverseProxy.Configuration.RouteConfig) reference. -The proxy will apply the given matching criteria and policies, and then pass off the request to the specified cluster. +The proxy applies the given matching criteria and policies, and passes off the request to the specified cluster. -### Clusters -The clusters section is an unordered collection of named clusters. A cluster primarily contains a collection of named destinations and their addresses, any of which is considered capable of handling requests for a given route. The proxy will process the request according to the route and cluster configuration in order to select a destination. +### Define configuration clusters -For additional fields see [ClusterConfig](xref:Yarp.ReverseProxy.Configuration.ClusterConfig). +The `Clusters` section is an unordered collection of named clusters. A cluster primarily contains a collection of named destinations and their addresses, any of which is considered capable of handling requests for a given route. The proxy processes the request according to the route and cluster configuration to select a destination. + +For other fields, see the [ClusterConfig](xref:Yarp.ReverseProxy.Configuration.ClusterConfig) reference. + +## Review all config properties + +The following JSON example shows all properties available for the YARP proxy configuration. -## All config properties ```json { - // Base URLs the server listens on, must be configured independently of the routes below + // Base URLs the server listens on, must be configured independently of the routes defined below "Urls": "http://localhost:5000;https://localhost:5001", "Logging": { "LogLevel": { @@ -121,39 +139,39 @@ For additional fields see [ClusterConfig](xref:Yarp.ReverseProxy.Configuration.C } }, "ReverseProxy": { - // Routes tell the proxy which requests to forward + // Routes inform the proxy which requests to forward "Routes": { "minimumroute" : { - // Matches anything and routes it to www.example.com + // Matches anything and routes to www.example.com "ClusterId": "minimumcluster", "Match": { "Path": "{**catch-all}" } }, "allrouteprops" : { - // matches /something/* and routes to "allclusterprops" - "ClusterId": "allclusterprops", // Name of one of the clusters + // Matches /something/* and routes to "allclusterprops" + "ClusterId": "allclusterprops", // Name of a cluster "Order" : 100, // Lower numbers have higher precedence "MaxRequestBodySize" : 1000000, // In bytes. An optional override of the server's limit (30MB default). Set to -1 to disable. "AuthorizationPolicy" : "Anonymous", // Name of the policy or "Default", "Anonymous" "CorsPolicy" : "Default", // Name of the CorsPolicy to apply to this route or "Default", "Disable" "Match": { - "Path": "/something/{**remainder}", // The path to match using ASP.NET syntax. - "Hosts" : [ "www.aaaaa.com", "www.bbbbb.com"], // The host names to match, unspecified is any - "Methods" : [ "GET", "PUT" ], // The HTTP methods that match, uspecified is all - "Headers": [ // The headers to match, unspecified is any + "Path": "/something/{**remainder}", // Path to match by using ASP.NET syntax + "Hosts" : [ "www.aaaaa.com", "www.bbbbb.com"], // Host names to match, unspecified is any + "Methods" : [ "GET", "PUT" ], // HTTP methods that match, unspecified is all + "Headers": [ // Headers to match, unspecified is any { "Name": "MyCustomHeader", // Name of the header - "Values": [ "value1", "value2", "another value" ], // Matches are against any of these values - "Mode": "ExactHeader", // or "HeaderPrefix", "Exists" , "Contains", "NotContains", "NotExists" + "Values": [ "value1", "value2", "another value" ], // Match any of these values + "Mode": "ExactHeader", // Or, match "HeaderPrefix", "Exists" , "Contains", "NotContains", "NotExists" "IsCaseSensitive": true } ], - "QueryParameters": [ // The query parameters to match, unspecified is any + "QueryParameters": [ // Query parameters to match, unspecified is any { "Name": "MyQueryParameter", // Name of the query parameter - "Values": [ "value1", "value2", "another value" ], // Matches are against any of these values - "Mode": "Exact", // or "Prefix", "Exists" , "Contains", "NotContains" + "Values": [ "value1", "value2", "another value" ], // Match any of these values + "Mode": "Exact", // Or, match "Prefix", "Exists" , "Contains", "NotContains" "IsCaseSensitive": true } ] @@ -185,20 +203,20 @@ For additional fields see [ClusterConfig](xref:Yarp.ReverseProxy.Configuration.C }, "another_destination": { "Address": "https://10.20.30.40", - "Health" : "https://10.20.30.40:12345/test" // override for active health checks + "Health" : "https://10.20.30.40:12345/test" // Override for active health checks } }, "LoadBalancingPolicy" : "PowerOfTwoChoices", // Alternatively "FirstAlphabetical", "Random", "RoundRobin", "LeastRequests" "SessionAffinity": { - "Enabled": true, // Defaults to 'false' + "Enabled": true, // Default is 'false' "Policy": "Cookie", // Default, alternatively "CustomHeader" - "FailurePolicy": "Redistribute", // default, Alternatively "Return503Error" + "FailurePolicy": "Redistribute", // Default, alternatively "Return503Error" "Settings" : { - "CustomHeaderName": "MySessionHeaderName" // Defaults to 'X-Yarp-Proxy-Affinity` + "CustomHeaderName": "MySessionHeaderName" // Default is 'X-Yarp-Proxy-Affinity` } }, "HealthCheck": { - "Active": { // Makes API calls to validate the health. + "Active": { // Makes API calls to validate the health "Enabled": "true", "Interval": "00:00:10", "Timeout": "00:00:10", @@ -207,7 +225,7 @@ For additional fields see [ClusterConfig](xref:Yarp.ReverseProxy.Configuration.C "Query": "?foo=bar" }, "Passive": { // Disables destinations based on HTTP response codes - "Enabled": true, // Defaults to false + "Enabled": true, // Default is false "Policy" : "TransportFailureRateHealthPolicy", // Required "ReactivationPeriod" : "00:00:10" // 10s } @@ -236,4 +254,7 @@ For additional fields see [ClusterConfig](xref:Yarp.ReverseProxy.Configuration.C } ``` -For more information see [logging configuration](diagnosing-yarp-issues.md#logging) and [HTTP client configuration](xref:fundamentals/servers/yarp/http-client-config). +## Related content + +- [Logging configuration](diagnosing-yarp-issues.md#logging) +- [HTTP client configuration](xref:fundamentals/servers/yarp/http-client-config) \ No newline at end of file diff --git a/aspnetcore/fundamentals/servers/yarp/getting-started.md b/aspnetcore/fundamentals/servers/yarp/getting-started.md index 358158aa7f9a..a310f7c6f0ad 100644 --- a/aspnetcore/fundamentals/servers/yarp/getting-started.md +++ b/aspnetcore/fundamentals/servers/yarp/getting-started.md @@ -1,39 +1,42 @@ --- uid: fundamentals/servers/yarp/getting-started -title: YARP Getting Started with YARP -description: YARP Getting Started with YARP +title: Get Started with YARP +description: Get started with the YARP library that provides core proxy functionality, customize library modules, and create a project that uses the YARP package. author: wadepickett ms.author: wpickett -ms.date: 3/6/2025 +ms.date: 04/24/2026 ms.topic: concept-article content_well_notification: AI-contribution ai-usage: ai-assisted + +# customer intent: As an ASP.NET developer, I want to get started with the YARP library, so I can learn how to customize the modules for my project. --- -# Getting started with YARP +# Get started with YARP -YARP is designed as a library that provides the core proxy functionality, which you can customize by adding or replacing modules. YARP is currently provided as a NuGet package and code samples. We plan on providing a project template and prebuilt executable (`.exe`) in the future. +YARP is designed as a .NET library that provides core proxy functionality. You can customize the library by adding or replacing modules. YARP is currently provided as a NuGet package and code samples, but a project template and prebuilt executable (`.exe`) are planned for the future. -YARP is implemented on top of .NET infrastructure and is usable on Windows, Linux or MacOS. Develop apps with the SDK and your favorite editor, [Microsoft Visual Studio](https://visualstudio.microsoft.com/vs/) or [Visual Studio Code](https://code.visualstudio.com/). +YARP is implemented on top of .NET infrastructure and is usable on Windows, Linux, or macOS. You can develop apps with the .NET SDK and your favorite editor: [Microsoft Visual Studio](https://visualstudio.microsoft.com/vs/) or [Visual Studio Code](https://code.visualstudio.com/). -YARP 2.3.0 supports .NET 8 or later. +YARP 2.3.0 supports .NET 8 or later. You can download the .NET SDK from https://dotnet.microsoft.com/download/dotnet/. -You can download the .NET SDK from https://dotnet.microsoft.com/download/dotnet/. +This article describes how to create a basic ASP.NET Core app that uses the YARP library. ## Create a new project -A complete version of the project built using the steps below can be found at [Basic YARP Sample](https://github.com/microsoft/reverse-proxy/tree/release/latest/samples/BasicYarpSample). - -Start by creating an empty ASP.NET Core application using the command line: +Start by creating an empty ASP.NET Core app from the command line: ```dotnetcli dotnet new web -n MyProxy ``` -Alternatively, create a new ASP.NET Core web application in Visual Studio 2022, choosing "Empty" for the project template. +Or, build a new ASP.NET Core web app in Visual Studio 2022 by selecting **Empty** for the project template. + +> [!NOTE] +> For the complete version of the project implemented in this article, download the [Basic YARP Sample](https://github.com/dotnet/yarp/tree/release/latest/samples/BasicYarpSample) on GitHub. -## Add the package reference +## Add the YARP package reference -Add a package reference for [`Yarp.ReverseProxy`](https://www.nuget.org/packages/Yarp.ReverseProxy), version 2.3.0 or later. +Add a package reference for [Yarp.ReverseProxy](https://www.nuget.org/packages/Yarp.ReverseProxy) version 2.3.0 or later. ```dotnetcli dotnet add package Yarp.ReverseProxy @@ -41,9 +44,9 @@ dotnet add package Yarp.ReverseProxy [!INCLUDE[](~/includes/package-reference.md)] -## Add the YARP Middleware +## Add the YARP middleware -Update the `Program` file to use the YARP Middleware: +Update the _Program.cs_ file to use the YARP middleware: ```csharp var builder = WebApplication.CreateBuilder(args); @@ -54,15 +57,15 @@ app.MapReverseProxy(); app.Run(); ``` -## Configuration +## Customize the YARP configuration -The configuration for YARP is defined in the `appsettings.json` file. For more information, see . +The configuration for YARP is defined in the _appsettings.json_ file. For more information, see [YARP configuration files](xref:fundamentals/servers/yarp/config-files). -The configuration can also be provided programmatically. For more information, see . +You can also specify the configuration programmatically. For more information, see [YARP extensibility: Configuration providers](xref:fundamentals/servers/yarp/config-providers). -Learn more about the available configuration options by looking at and . +To learn more about the available configuration options, see the and reference articles. - ```json +```json { "Logging": { "LogLevel": { @@ -94,8 +97,16 @@ Learn more about the available configuration options by looking at ` command. + +- **Visual Studio**: Start the app by selecting **Run** on the main menubar. -When using the .NET CLI, use `dotnet run` within the sample's directory or `dotnet run --project `. +## Related content -In Visual Studio, start the app by clicking the **Run** button. +- [Basic YARP sample on GitHub](https://github.com/dotnet/yarp/tree/release/latest/samples/BasicYarpSample) +- [YARP Configuration Files](xref:fundamentals/servers/yarp/config-files) +- [YARP extensibility: Configuration providers](xref:fundamentals/servers/yarp/config-providers) \ No newline at end of file diff --git a/aspnetcore/fundamentals/servers/yarp/header-routing.md b/aspnetcore/fundamentals/servers/yarp/header-routing.md index 5c55702bbf97..b93610596f60 100644 --- a/aspnetcore/fundamentals/servers/yarp/header-routing.md +++ b/aspnetcore/fundamentals/servers/yarp/header-routing.md @@ -24,7 +24,7 @@ The default route match precedence order is 4. headers 5. query parameters - That means a route which specifies methods and no headers will match before a route which specifies headers and no methods. This can be overridden by setting the `Order` property on a route (see example in [config properties](config-files.md#all-config-properties)). + That means a route which specifies methods and no headers will match before a route which specifies headers and no methods. This can be overridden by setting the `Order` property on a route (see example in [config properties](config-files.md#review-all-config-properties)). ## Configuration diff --git a/aspnetcore/fundamentals/servers/yarp/https-tls.md b/aspnetcore/fundamentals/servers/yarp/https-tls.md index 4a8f18f9a62c..f7b886dd9f73 100644 --- a/aspnetcore/fundamentals/servers/yarp/https-tls.md +++ b/aspnetcore/fundamentals/servers/yarp/https-tls.md @@ -32,7 +32,7 @@ Kestrel supports intercepting incoming connections before the TLS handshake. YAR ## Configuring outgoing connections -To enable TLS encryption when communicating with a destination specify the destination address as `https` like `"https://destinationHost"`. See the [configuration docs](config-files.md#configuration-structure) for examples. +To enable TLS encryption when communicating with a destination specify the destination address as `https` like `"https://destinationHost"`. See the [configuration docs](config-files.md#examine-the-configuration-structure) for examples. The host name specified in the destination address will be used for the TLS handshake by default, including SNI and server certificate validation. If proxying the [original host header](xref:fundamentals/servers/yarp/transforms#requestheaderoriginalhost) is enabled, that value will be used for the TLS handshake instead. If a custom host value needs to be used then use the [RequestHeader](xref:fundamentals/servers/yarp/transforms#requestheader) transform to set the host header. diff --git a/aspnetcore/fundamentals/startup.md b/aspnetcore/fundamentals/startup.md index c0baebb104f9..19a1cbc5d834 100644 --- a/aspnetcore/fundamentals/startup.md +++ b/aspnetcore/fundamentals/startup.md @@ -1,12 +1,14 @@ --- -title: App startup in ASP.NET Core +title: App Startup in ASP.NET Core author: wadepickett description: Learn how the Startup class in ASP.NET Core configures services and the app's request pipeline. monikerRange: '>= aspnetcore-3.1' ms.author: wpickett ms.custom: mvc -ms.date: 12/12/2024 +ms.date: 04/24/2026 uid: fundamentals/startup + +# customer intent: As an ASP.NET developer, I want to explore the Startup class in ASP.NET Core, so I can configure services and the request pipeline for my apps. --- # App startup in ASP.NET Core @@ -16,13 +18,13 @@ By [Rick Anderson](https://twitter.com/RickAndMSFT) :::moniker range=">= aspnetcore-7.0" -ASP.NET Core apps created with the web templates contain the application startup code in the `Program.cs` file. +ASP.NET Core apps created with the web templates contain the application startup code in the _Program.cs_ file. -For Blazor startup guidance, which adds to or supersedes the guidance in this article, see . +For Blazor startup guidance, which adds to or supersedes the guidance in this article, see [ASP.NET Core Blazor startup](xref:blazor/fundamentals/startup). The following app startup code supports several app types: -* [Blazor Web Apps](xref:blazor/index) +* [Blazor web apps](xref:blazor/index#build-a-full-stack-web-app-with-blazor) * [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) @@ -30,18 +32,19 @@ The following app startup code supports several app types: [!code-csharp[](~/fundamentals/startup/9.0_samples/WebAll/Program.cs?name=snippet)] -Apps that use can measure the startup time to understand and optimize startup performance. The [`ServerReady`](https://source.dot.net/#Microsoft.AspNetCore.Hosting/Internal/HostingEventSource.cs,76) event in represents the point where the server is ready to respond to requests. +Apps that use the can measure the startup time to understand and optimize startup performance. The [ServerReady](https://source.dot.net/#Microsoft.AspNetCore.Hosting/Internal/HostingEventSource.cs,76) event in the represents the point where the server is ready to respond to requests. - + ## Extend Startup with startup filters Use : * To configure middleware at the beginning or end of an app's middleware pipeline without an explicit call to `Use{Middleware}`. Use `IStartupFilter` to add defaults to the beginning of the pipeline without explicitly registering the default middleware. `IStartupFilter` allows a different component to call `Use{Middleware}` on behalf of the app author. + * To create a pipeline of `Configure` methods. [IStartupFilter.Configure](xref:Microsoft.AspNetCore.Hosting.IStartupFilter.Configure%2A) can set a middleware to run before or after middleware added by libraries. -An `IStartupFilter` implementation implements , which receives and returns an `Action`. An defines a class to configure an app's request pipeline. For more information, see [Create a middleware pipeline with IApplicationBuilder](xref:fundamentals/middleware/index#create-a-middleware-pipeline-with-iapplicationbuilder). +An `IStartupFilter` instance implements the method, which receives and returns an `Action`. An defines a class to configure an app's request pipeline. For more information, see [Create a middleware pipeline with IApplicationBuilder](xref:fundamentals/middleware/index#create-a-middleware-pipeline-with-iapplicationbuilder). Each `IStartupFilter` implementation can add one or more middlewares in the request pipeline. The filters are invoked in the order they were added to the service container. Filters can add middleware before or after passing control to the next filter, thus they append to the beginning or end of the app pipeline. @@ -53,7 +56,7 @@ The `RequestSetOptionsMiddleware` is configured in the `RequestSetOptionsStartup [!code-csharp[](~/fundamentals/startup/7/WebStartup/Middleware/RequestSetOptionsStartupFilter.cs?name=snippet1&highlight=7)] -The `IStartupFilter` implementation is registered in `Program.cs`: +The `IStartupFilter` implementation is registered in the _Program.cs_ file: [!code-csharp[](~/fundamentals/startup/7/WebStartup/Program.cs?highlight=6-7)] @@ -64,26 +67,33 @@ When a query string parameter for `option` is provided, the middleware processes Middleware execution order is set by the order of `IStartupFilter` registrations: * Multiple `IStartupFilter` implementations might interact with the same objects. If ordering is important, order their `IStartupFilter` service registrations to match the order that their middlewares should run. + * Libraries can add middleware with one or more `IStartupFilter` implementations that run before or after other app middleware registered with `IStartupFilter`. To invoke an `IStartupFilter` middleware before a middleware added by a library's `IStartupFilter`: * Position the service registration before the library is added to the service container. + * To invoke afterward, position the service registration after the library is added. -You can't extend the ASP.NET Core app when you override `Configure`. For more information, see [this GitHub issue](https://github.com/dotnet/aspnetcore/issues/45372). +You can't extend the ASP.NET Core app when you override `Configure`. For more information, see [GitHub /dotnet/aspnetcore/issues #45372](https://github.com/dotnet/aspnetcore/issues/45372). ## Add configuration at startup from an external assembly -An implementation allows adding enhancements to an app at startup from an external assembly outside of the app's `Program.cs` file. For more information, see . +An implementation allows adding enhancements to an app at startup from an external assembly outside of the application _Program.cs_ file. For more information, see [Use hosting startup assemblies in ASP.NET Core](xref:fundamentals/configuration/platform-specific-configuration). ## Startup, ConfigureServices, and Configure For information on using the and methods with the minimal hosting model, see: * [Use Startup with the minimal hosting model](xref:migration/50-to-60#smhm) -* The [.NET 5 version of this article](?view=aspnetcore-5.0&preserve-view=true#the-startup-class): +* [The Startup Class (.NET 5 version of this article)](?view=aspnetcore-5.0&preserve-view=true#the-startup-class): * [The ConfigureServices method](?view=aspnetcore-5.0&preserve-view=true#the-configureservices-method) * [The Configure method](?view=aspnetcore-5.0&preserve-view=true#the-configure-method) +## Related content + +- [ASP.NET Core fundamentals overview](./index.md) +- [Configuration in ASP.NET Core](./configuration/index.md) + :::moniker-end [!INCLUDE[](~/fundamentals/startup/includes/startup56.md)] diff --git a/aspnetcore/grpc/basics.md b/aspnetcore/grpc/basics.md index 34d85ff7ae86..cecb69d70d20 100644 --- a/aspnetcore/grpc/basics.md +++ b/aspnetcore/grpc/basics.md @@ -1,39 +1,44 @@ --- -title: gRPC services with C# +title: gRPC Services with C# author: jamesnk -description: Learn the basic concepts when writing gRPC services with C#. +description: Learn the basic concepts for writing gRPC services with C# in ASP.NET Core. monikerRange: '>= aspnetcore-3.0' ms.author: wpickett -ms.date: 05/08/2023 +ms.date: 04/24/2026 uid: grpc/basics + +# customer intent: As an ASP.NET developer, I want to explore the basic concepts for working with gRPC services with C\# in ASP.NET Core, so I can write gRPC apps. --- # gRPC services with C\# [!INCLUDE[](~/includes/not-latest-version.md)] :::moniker range=">= aspnetcore-6.0" -This document outlines the concepts needed to write [gRPC](https://grpc.io/docs/guides/) apps in C#. The topics covered here apply to both [C-core](https://grpc.io/blog/grpc-stacks)-based and ASP.NET Core-based gRPC apps. -## proto file +This article provides an overview of the concepts required to write [gRPC](https://grpc.io/docs/guides/) apps in C#. The information presented applies to both [C-core](https://grpc.io/blog/grpc-stacks)-based and ASP.NET Core-based gRPC apps. -gRPC uses a contract-first approach to API development. Protocol buffers (protobuf) are used as the Interface Definition Language (IDL) by default. The `.proto` file contains: +## Review the .proto file + +gRPC uses a contract-first approach to API development. Protocol buffers (protobuf) are used as the Interface Definition Language (IDL) by default. The _.proto_ file contains: * The definition of the gRPC service. * The messages sent between clients and servers. -For more information on the syntax of protobuf files, see . +For more information on the syntax of protobuf files, see [Create Protobuf messages for .NET apps](xref:grpc/protobuf). -For example, consider the *greet.proto* file used in [Get started with gRPC service](xref:tutorials/grpc/grpc-start): +Consider the _greet.proto_ file used in the tutorial, [Create a gRPC client and server in ASP.NET Core](xref:tutorials/grpc/grpc-start)s: -* Defines a `Greeter` service. +* The file defines a `Greeter` service. * The `Greeter` service defines a `SayHello` call. -* `SayHello` sends a `HelloRequest` message and receives a `HelloReply` message: +* The `SayHello` call sends a `HelloRequest` message and receives a `HelloReply` message. + +The file contains the following code: [!code-protobuf[](~/tutorials/grpc/grpc-start/sample/sample6/GrpcGreeter/Protos/greet.proto)] -## Add a `.proto` file to a C\# app +## Add a .proto file to a C\# app -The `.proto` file is included in a project by adding it to the `` item group: +The _.proto_ file is included in a project by adding it to the `` item group: [!code-xml[](~/tutorials/grpc/grpc-start/sample/sample6/GrpcGreeter/GrpcGreeter.csproj?highlight=2&range=10-12)] @@ -44,49 +49,52 @@ By default, a `` reference generates a concrete client and a service b * `Client` * `None` -## C# Tooling support for `.proto` files +## C# tooling support for .proto files -The tooling package [Grpc.Tools](https://www.nuget.org/packages/Grpc.Tools/) is required to generate the C# assets from `.proto` files. The generated assets (files): +The tooling package [Grpc.Tools](https://www.nuget.org/packages/Grpc.Tools/) is required to generate the C# assets from _.proto_ files. -* Are generated on an as-needed basis each time the project is built. -* Aren't added to the project or checked into source control. -* Are a build artifact contained in the *obj* directory. +The generated assets (files) have the following characteristics: -This package is required by both the server and client projects. The `Grpc.AspNetCore` metapackage includes a reference to `Grpc.Tools`. Server projects can add `Grpc.AspNetCore` using the Package Manager in Visual Studio or by adding a `` to the project file: +* They're generated on an as-needed basis each time the project is built. +* They aren't added to the project or checked into source control. +* They're a build artifact contained in the _obj_ directory. + +Both the server and client projects require this package. The `Grpc.AspNetCore` metapackage includes a reference to `Grpc.Tools`. Server projects can add `Grpc.AspNetCore` by using the Package Manager in Visual Studio or by adding a `` to the project file: [!code-xml[](~/tutorials/grpc/grpc-start/sample/sample6/GrpcGreeter/GrpcGreeter.csproj?highlight=1&range=15)] -Client projects should directly reference `Grpc.Tools` alongside the other packages required to use the gRPC client. The tooling package isn't required at runtime, so the dependency is marked with `PrivateAssets="All"`: +Client projects should directly reference `Grpc.Tools` alongside the other packages required to use the gRPC client. The tooling package isn't required at runtime, so the dependency is marked with the `PrivateAssets="All"` setting: [!code-xml[](~/tutorials/grpc/grpc-start/sample/sample6/GrpcGreeterClient/GrpcGreeterClient.csproj?highlight=3&range=11-16)] ## Generated C# assets -The tooling package generates the C# types representing the messages defined in the included `.proto` files. +The tooling package generates the C# types representing the messages defined in the included _.proto_ files. -For server-side assets, an abstract service base type is generated. The base type contains the definitions of all the gRPC calls contained in the `.proto` file. Create a concrete service implementation that derives from this base type and implements the logic for the gRPC calls. For the `greet.proto`, the example described previously, an abstract `GreeterBase` type that contains a virtual `SayHello` method is generated. A concrete implementation `GreeterService` overrides the method and implements the logic handling the gRPC call. +For server-side assets, an abstract service base type is generated. The base type contains the definitions of all the gRPC calls contained in the _.proto_ file. Create a concrete service implementation that derives from this base type and implements the logic for the gRPC calls. For the _greet.proto_ file used in a [previous example](#review-the-proto-file), an abstract `GreeterBase` type that contains a virtual `SayHello` method is generated. A concrete implementation `GreeterService` overrides the method and implements the logic handling the gRPC call. [!code-csharp[](~/tutorials/grpc/grpc-start/sample/sample6/GrpcGreeter/Services/GreeterService.cs?name=snippet)] -For client-side assets, a concrete client type is generated. The gRPC calls in the `.proto` file are translated into methods on the concrete type, which can be called. For the `greet.proto`, the example described previously, a concrete `GreeterClient` type is generated. Call `GreeterClient.SayHelloAsync` to initiate a gRPC call to the server. +For client-side assets, a concrete client type is generated. The gRPC calls in the _.proto_ file are translated into methods on the concrete type, which can be called. For the _greet.proto_ file used in a [previous example](#review-the-proto-file), a concrete `GreeterClient` type is generated. Call `GreeterClient.SayHelloAsync` to initiate a gRPC call to the server. [!code-csharp[](~/tutorials/grpc/grpc-start/sample/sample6/GrpcGreeterClient/Program.cs?name=snippet)] -By default, server and client assets are generated for each `.proto` file included in the `` item group. To ensure only the server assets are generated in a server project, the `GrpcServices` attribute is set to `Server`. +By default, server and client assets are generated for each _.proto_ file included in the `` item group. To ensure only the server assets are generated in a server project, the `GrpcServices` attribute is set to `Server`. [!code-xml[](~/tutorials/grpc/grpc-start/sample/sample6/GrpcGreeter/GrpcGreeter.csproj?highlight=2&range=10-12)] Similarly, the attribute is set to `Client` in client projects. -## Additional resources +## Related content + +* [Overview for gRPC on .NET](xref:grpc/index) +* [Create a .NET gRPC client and server in ASP.NET Core](xref:tutorials/grpc/grpc-start) +* [Call gRPC services with the .NET client](xref:grpc/client) -* -* -* -* :::moniker-end :::moniker range=">= aspnetcore-3.0 < aspnetcore-6.0" + This document outlines the concepts needed to write [gRPC](https://grpc.io/docs/guides/) apps in C#. The topics covered here apply to both [C-core](https://grpc.io/blog/grpc-stacks)-based and ASP.NET Core-based gRPC apps. ## proto file @@ -153,10 +161,11 @@ By default, server and client assets are generated for each `.proto` file includ Similarly, the attribute is set to `Client` in client projects. -## Additional resources +## Related content * * * * + :::moniker-end diff --git a/aspnetcore/grpc/index.md b/aspnetcore/grpc/index.md index f26f4b949ee9..bf7ba59ccef4 100644 --- a/aspnetcore/grpc/index.md +++ b/aspnetcore/grpc/index.md @@ -4,8 +4,10 @@ author: jamesnk description: Learn about gRPC services with Kestrel server and the ASP.NET Core stack. monikerRange: '>= aspnetcore-3.0' ms.author: wpickett -ms.date: 01/24/2024 +ms.date: 04/24/2026 uid: grpc/index + +# customer intent: As an ASP.NET developer, I want to explore gRPC services with Kestrel server and the ASP.NET Core stack, so I can use gRPC in my project. --- # Overview for gRPC on .NET @@ -18,20 +20,22 @@ By [James Newton-King](https://twitter.com/jamesnk) [gRPC](https://grpc.io) is a language agnostic, high-performance Remote Procedure Call (RPC) framework. The main benefits of gRPC are: + * Modern, high-performance, lightweight RPC framework. -* Contract-first API development, using Protocol Buffers by default, allowing for language agnostic implementations. -* Tooling available for many languages to generate strongly-typed servers and clients. +* Contract-first API development that uses Protocol Buffers by default that allows for language agnostic implementations. +* Tooling available for many languages to generate strongly typed servers and clients. * Supports client, server, and bi-directional streaming calls. * Reduced network usage with Protobuf binary serialization. These benefits make gRPC ideal for: + * Lightweight microservices where efficiency is critical. * Polyglot systems where multiple languages are required for development. * Point-to-point real-time services that need to handle streaming requests or responses. -## C# Tooling support for `.proto` files +## C# tooling support for .proto files -gRPC uses a contract-first approach to API development. Services and messages are defined in `.proto` files: +gRPC uses a contract-first approach to API development. Services and messages are defined in _.proto_ files: ```protobuf syntax = "proto3"; @@ -49,10 +53,10 @@ message HelloReply { } ``` -.NET types for services, clients, and messages are automatically generated by including `.proto` files in a project: +.NET types for services, clients, and messages are automatically generated by including _.proto_ files in a project: -* Add a package reference to [Grpc.Tools](https://www.nuget.org/packages/Grpc.Tools/) package. -* Add `.proto` files to the `` item group. +* Add a package reference to the [Grpc.Tools](https://www.nuget.org/packages/Grpc.Tools/) package. +* Add _.proto_ files to the `` item group. ```xml @@ -60,7 +64,7 @@ message HelloReply { ``` -For more information on gRPC tooling support, see . +For more information on gRPC tooling support, see [gRPC services with C#](xref:grpc/basics). ## gRPC services on ASP.NET Core @@ -95,7 +99,6 @@ public class GreeterService(ILogger logger) : Greeter.GreeterBas ``` :::moniker-end - :::moniker range=">= aspnetcore-6.0 < aspnetcore-10.0" ```csharp @@ -125,17 +128,17 @@ public class GreeterService : Greeter.GreeterBase :::moniker range=">= aspnetcore-6.0" -`GreeterService` inherits from the `GreeterBase` type, which is generated from the `Greeter` service in the `.proto` file. The service is made accessible to clients in `Program.cs`: +`GreeterService` inherits from the `GreeterBase` type, which is generated from the `Greeter` service in the _.proto_ file. The service is made accessible to clients in the _Program.cs_ file: ```csharp app.MapGrpcService(); ``` -To learn more about gRPC services on ASP.NET Core, see . +To learn more, see [gRPC services with ASP.NET Core](xref:grpc/aspnetcore). -## Call gRPC services with a .NET client +## gRPC service calls with a .NET client -gRPC clients are concrete client types that are [generated from `.proto` files](xref:grpc/basics#generated-c-assets). The concrete gRPC client has methods that translate to the gRPC service in the `.proto` file. +gRPC clients are concrete client types that are [generated from .proto files](xref:grpc/basics#generated-c-assets). The concrete gRPC client has methods that translate to the gRPC service in the _.proto_ file. ```csharp var channel = GrpcChannel.ForAddress("https://localhost:5001"); @@ -147,17 +150,15 @@ var response = await client.SayHelloAsync( Console.WriteLine(response.Message); ``` -A gRPC client is created using a channel, which represents a long-lived connection to a gRPC service. A channel can be created using `GrpcChannel.ForAddress`. +A gRPC client is created by using a channel, which represents a long-lived connection to a gRPC service. A channel can be created by using `GrpcChannel.ForAddress`. -For more information on creating clients, and calling different service methods, see . +For more information on creating clients, and calling different service methods, see [Call gRPC services with the .NET client](xref:grpc/client). -## Additional resources +## Related content -* -* -* -* -* +* [gRPC services with ASP.NET Core](xref:grpc/aspnetcore) +* [gRPC client factory integration in .NET](xref:grpc/clientfactory) +* [Create a .NET gRPC client and server in ASP.NET Core](xref:tutorials/grpc/grpc-start) :::moniker-end @@ -168,7 +169,7 @@ For more information on creating clients, and calling different service methods, The main benefits of gRPC are: * Modern, high-performance, lightweight RPC framework. * Contract-first API development, using Protocol Buffers by default, allowing for language agnostic implementations. -* Tooling available for many languages to generate strongly-typed servers and clients. +* Tooling available for many languages to generate strongly typed servers and clients. * Supports client, server, and bi-directional streaming calls. * Reduced network usage with Protobuf binary serialization. @@ -273,7 +274,7 @@ A gRPC client is created using a channel, which represents a long-lived connecti For more information on creating clients, and calling different service methods, see . -## Additional resources +## Related content * * diff --git a/aspnetcore/includes/spa-templates-new-vs-old.md b/aspnetcore/includes/spa-templates-new-vs-old.md index b8724e681d12..0e37a2f9f654 100644 --- a/aspnetcore/includes/spa-templates-new-vs-old.md +++ b/aspnetcore/includes/spa-templates-new-vs-old.md @@ -12,13 +12,13 @@ The Visual Studio templates for building ASP.NET Core apps with a JavaScript or * Clean project separation for the frontend and backend. * Stay up-to-date with the latest frontend framework versions. -* Integrate with the latest frontend framework command-line tooling, such as [Vite](https://vitejs.dev/). -* Templates for both JavaScript & TypeScript (only TypeScript for Angular). +* Integrate with the latest frontend framework command-line tooling, such as [Vite](https://vite.dev/). +* Templates for both JavaScript and TypeScript (only TypeScript for Angular). * Rich JavaScript and TypeScript code editing experience. * Integrate JavaScript build tools with the .NET build. * npm dependency management UI. * Compatible with Visual Studio Code debugging and launch configuration. -* Run frontend unit tests in [Test Explorer](/visualstudio/test/run-unit-tests-with-test-explorer) using JavaScript test frameworks. +* Run frontend unit tests in [Test Explorer](/visualstudio/test/run-unit-tests-with-test-explorer) by using JavaScript test frameworks. ## Legacy ASP.NET Core SPA templates