Merge pull request #35485 from dotnet/main

guardrex · web-flow · commit ea3e1ad748c7 · 2025-05-17T14:59:16.000-04:00
diff --git a/aspnetcore/blazor/host-and-deploy/webassembly/azure-static-web-apps.md b/aspnetcore/blazor/host-and-deploy/webassembly/azure-static-web-apps.md
@@ -30,10 +30,8 @@ To deploy from Visual Studio, create a publish profile for Azure Static Web Apps
 
 After the publish profile is created, deploy the app to the Azure Static Web Apps instance using the publish profile by selecting the **Publish** button.
 
-## Deploy from Visual Studio Code
+## GitHub deployment scenarios
 
-To deploy from Visual Studio Code, see [Quickstart: Build your first static site with Azure Static Web Apps](/azure/static-web-apps/getting-started?tabs=blazor).
-
-## Deploy from GitHub
-
-To deploy from a GitHub repository, see [Tutorial: Building a static web app with Blazor in Azure Static Web Apps](/azure/static-web-apps/deploy-blazor).
+* Visual Studio Code: [Quickstart: Build your first static site with Azure Static Web Apps](/azure/static-web-apps/getting-started?tabs=blazor)
+* .NET CLI: [Deploy Blazor websites to the cloud with Azure Static Web Apps (Video)](/shows/deploy-websites-to-the-cloud-with-azure-static-web-apps/deploy-blazor-websites-to-the-cloud-with-azure-static-web-apps)
+* Deploy from GitHub: [Tutorial: Building a static web app with Blazor in Azure Static Web Apps](/azure/static-web-apps/deploy-blazor)
diff --git a/aspnetcore/blazor/security/blazor-web-app-with-oidc.md b/aspnetcore/blazor/security/blazor-web-app-with-oidc.md
@@ -15,14 +15,14 @@ zone_pivot_groups: blazor-web-app-oidc-specification
 
 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)).
 
-:::moniker-range=">= aspnetcore-9.0"
+:::zone pivot="non-bff-pattern"
+
+:::moniker range=">= aspnetcore-9.0"
 
 For Microsoft Entra ID or Azure AD B2C, you can use <xref:Microsoft.Identity.Web.AppBuilderExtension.AddMicrosoftIdentityWebApp%2A> from [Microsoft Identity Web](/entra/msal/dotnet/microsoft-identity-web/) ([`Microsoft.Identity.Web` NuGet package](https://www.nuget.org/packages/Microsoft.Identity.Web), [API documentation](<xref:Microsoft.Identity.Web?displayProperty=fullName>)), which adds both the OIDC and Cookie authentication handlers with the appropriate defaults. The sample app and the guidance in this article don't use Microsoft Identity Web. The guidance demonstrates how to configure the OIDC handler *manually* for any OIDC provider. For more information on implementing Microsoft Identity Web, see <xref:blazor/security/blazor-web-app-entra>.
 
 :::moniker-end
 
-:::zone pivot="non-bff-pattern"
-
 This version of the article covers implementing OIDC without adopting the [Backend for Frontend (BFF) pattern](/azure/architecture/patterns/backends-for-frontends) with an app that adopts global Interactive Auto rendering (server and `.Client` projects). The BFF pattern is useful for making authenticated requests to external services. Change the article version selector to **BFF pattern** if the app's specification calls for adopting the BFF pattern.
 
 The following specification is adopted:
@@ -377,6 +377,12 @@ The sample app only provides a user name and email for display purposes.
 
 :::zone pivot="non-bff-pattern-server"
 
+:::moniker range=">= aspnetcore-9.0"
+
+For Microsoft Entra ID or Azure AD B2C, you can use <xref:Microsoft.Identity.Web.AppBuilderExtension.AddMicrosoftIdentityWebApp%2A> from [Microsoft Identity Web](/entra/msal/dotnet/microsoft-identity-web/) ([`Microsoft.Identity.Web` NuGet package](https://www.nuget.org/packages/Microsoft.Identity.Web), [API documentation](<xref:Microsoft.Identity.Web?displayProperty=fullName>)), which adds both the OIDC and Cookie authentication handlers with the appropriate defaults. The sample app and the guidance in this article don't use Microsoft Identity Web. The guidance demonstrates how to configure the OIDC handler *manually* for any OIDC provider. For more information on implementing Microsoft Identity Web, see <xref:blazor/security/blazor-web-app-entra>.
+
+:::moniker-end
+
 This version of the article covers implementing OIDC without adopting the [Backend for Frontend (BFF) pattern](/azure/architecture/patterns/backends-for-frontends) with an app that adopts global Interactive Server rendering (single project). The BFF pattern is useful for making authenticated requests to external services. Change the article version selector to **BFF pattern** if the app's specification calls for adopting the BFF pattern with global Interactive Auto rendering.
 
 The following specification is adopted:
@@ -720,6 +726,12 @@ oidcOptions.TokenValidationParameters.IssuerValidator = microsoftIssuerValidator
 
 :::zone pivot="bff-pattern"
 
+:::moniker range=">= aspnetcore-9.0"
+
+For Microsoft Entra ID or Azure AD B2C, you can use <xref:Microsoft.Identity.Web.AppBuilderExtension.AddMicrosoftIdentityWebApp%2A> from [Microsoft Identity Web](/entra/msal/dotnet/microsoft-identity-web/) ([`Microsoft.Identity.Web` NuGet package](https://www.nuget.org/packages/Microsoft.Identity.Web), [API documentation](<xref:Microsoft.Identity.Web?displayProperty=fullName>)), which adds both the OIDC and Cookie authentication handlers with the appropriate defaults. The sample app and the guidance in this article don't use Microsoft Identity Web. The guidance demonstrates how to configure the OIDC handler *manually* for any OIDC provider. For more information on implementing Microsoft Identity Web, see <xref:blazor/security/blazor-web-app-entra>.
+
+:::moniker-end
+
 This version of the article covers implementing OIDC with the [Backend for Frontend (BFF) pattern](/azure/architecture/patterns/backends-for-frontends). If the app's specification doesn't call for adopting the BFF pattern, change the article version selector to **Non-BFF pattern (Interactive Auto)** (Interactive Auto rendering) or **Non-BFF pattern (Interactive Server)** (Interactive Server rendering).
 
 ## Prerequisites
diff --git a/aspnetcore/fundamentals/openapi/customize-openapi.md b/aspnetcore/fundamentals/openapi/customize-openapi.md
@@ -5,7 +5,7 @@ description: Learn how to customize OpenAPI documents in an ASP.NET Core app
 ms.author: safia
 monikerRange: '>= aspnetcore-9.0'
 ms.custom: mvc
-ms.date: 10/26/2024
+ms.date: 05/15/2025
 uid: fundamentals/openapi/customize-openapi
 ---
 # Customize OpenAPI documents
@@ -44,18 +44,18 @@ Transformers can be registered onto the document by calling the <xref:Microsoft.
 
 ### Execution order for transformers
 
-Transformers are executed as follows:
+Transformers execute in the following order:  
 
-* Schema transformers are executed when a schema is registered to the document. Schema transformers are executed in the order in which they were added.
-All schemas are added to the document before any operation processing occurs, so all schema transformers are executed before any operation transformers.
-* Operation transformers are executed when an operation is added to the document. Operation transformers are executed in the order in which they were added.
-All operations are added to the document before any document transformers are executed.
-* Document transformers are executed when the document is generated. This is the final pass over the document, and all operations and schemas have been add by this point.
-* When an app is configured to generate multiple OpenAPI documents, transformers are executed for each document independently.
+* Schema transformers execute when a schema is registered to the document. They execute in the order they're added.
+All schemas are added to the document before any operation processing occurs, so schema transformers execute before operation transformers.
+* Operation transformers execute when an operation is added to the document. They execute in the order they're added.
+All operations are added to the document before any document transformers execute.
+* Document transformers execute when the document is generated. This is the final pass over the document, and all operations and schemas are added by this point.
+* When an app is configured to generate multiple OpenAPI documents, transformers execute for each document independently.
 
 For example, in the following snippet:
 * `SchemaTransformer2` is executed and has access to the modifications made by `SchemaTransformer1`.
-* Both `OperationTransformer1` and `OperationTransformer2` have access to the modifications made by both schema transformers for the types involved in the operation they are called to process.
+* Both `OperationTransformer1` and `OperationTransformer2` have access to the modifications made by both schema transformers for the types involved in the operation they're called to process.
 * `OperationTransformer2` is executed after `OperationTransformer1`, so it has access to the modifications made by `OperationTransformer1`.
 * Both `DocumentTransformer1` and `DocumentTransformer2` are executed after all operations and schemas have been added to the document, so they have access to all modifications made by the operation and schema transformers.
 * `DocumentTransformer2` is executed after `DocumentTransformer1`, so it has access to the modifications made by `DocumentTransformer1`.
@@ -119,6 +119,22 @@ For example, the following schema transformer sets the `format` of decimal types
 
 [!code-csharp[](~/fundamentals/openapi/samples/10.x/WebMinOpenApi/Program.cs?name=snippet_schematransformer1)]
 
+## Support for generating OpenApiSchemas in transformers
+<!-- https://github.com/dotnet/aspnetcore/pull/61050 -->
+
+Developers can generate a schema for a C# type using the same logic as ASP.NET Core OpenAPI document generation and add it to the OpenAPI document. The schema can then be referenced from elsewhere in the OpenAPI document. This capability is available starting with .NET 10.
+
+The context passed to document, operation, and schema transformers includes a new `GetOrCreateSchemaAsync` method that can be used to generate a schema for a type.
+This method also has an optional `ApiParameterDescription` parameter to specify additional metadata for the generated schema.
+
+To support adding the schema to the OpenAPI document, a `Document` property has been added to the Operation and Schema transformer contexts. This allows any transformer to add a schema to the OpenAPI document using the document's `AddComponent` method.
+
+### Example
+
+To use this feature in a document, operation, or schema transformer, create the schema using the `GetOrCreateSchemaAsync` method provided in the context and add it to the OpenAPI document using the document's `AddComponent` method.
+
+:::code language="csharp" source="~/fundamentals/openapi/samples/10.x/WebAppOpenAPI10/Program.cs" id="snippet_Generate_OpenApiSchemas_for_type" highlight="6-7":::
+
 ## Customize schema reuse
 
 After all transformers have been applied, the framework makes a pass over the document to transfer certain schemas
@@ -145,7 +161,7 @@ that uses the name of the type, but you can replace it with your own implementat
 As a simple example of this customization, you might choose to always inline enum schemas.
 This is done by setting <xref:Microsoft.AspNetCore.OpenApi.OpenApiOptions.CreateSchemaReferenceId> to a delegate
 that returns null for enum types, and otherwise returns the value from the default implementation.
-The following code shows how to do this:
+The following code demonstrates this:
 
 ```csharp
 builder.Services.AddOpenApi(options =>
diff --git a/aspnetcore/fundamentals/openapi/samples/10.x/WebAppOpenAPI10/Controllers/WeatherForecastController.cs b/aspnetcore/fundamentals/openapi/samples/10.x/WebAppOpenAPI10/Controllers/WeatherForecastController.cs
@@ -0,0 +1,26 @@
+using Microsoft.AspNetCore.Mvc;
+
+namespace WebAppOpenAPI10.Controllers
+{
+    [ApiController]
+    [Route("[controller]")]
+    public class WeatherForecastController : ControllerBase
+    {
+        private static readonly string[] Summaries =
+        [
+            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
+        ];
+
+        [HttpGet(Name = "GetWeatherForecast")]
+        public IEnumerable<WeatherForecast> Get()
+        {
+            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
+            {
+                Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
+                TemperatureC = Random.Shared.Next(-20, 55),
+                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
+            })
+            .ToArray();
+        }
+    }
+}
diff --git a/aspnetcore/fundamentals/openapi/samples/10.x/WebAppOpenAPI10/Program.cs b/aspnetcore/fundamentals/openapi/samples/10.x/WebAppOpenAPI10/Program.cs
@@ -0,0 +1,83 @@
+#define SCHEMA_IN_TRANSFORMER_EXAMPLE     //YAML_EXAMPLE   //SCHEMA_IN_TRANSFORMER_EXAMPLE
+#if YAML_EXAMPLE
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Add services to the container.
+builder.Services.AddControllers();
+// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
+// <snippet_DefaultOpenApiVersion>
+builder.Services.AddOpenApi(options =>
+{
+    options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_1;
+});
+// </snippet_DefaultOpenApiVersion>
+
+var app = builder.Build();
+
+// Configure the HTTP request pipeline.
+// <snippet_ConfigOpenApiYAML>
+if (app.Environment.IsDevelopment())
+{
+    app.MapOpenApi("/openapi/{documentName}.yaml");
+}
+// </snippet_ConfigOpenApiYAML>
+
+app.UseHttpsRedirection();
+
+app.UseAuthorization();
+
+app.MapControllers();
+
+app.Run();
+
+#elif SCHEMA_IN_TRANSFORMER_EXAMPLE
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Add services to the container.
+builder.Services.AddControllers();
+// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
+// <snippet_Generate_OpenApiSchemas_for_type>
+builder.Services.AddOpenApi(options =>
+{
+    options.AddOperationTransformer(async (operation, context, cancellationToken) =>
+    {
+        // Generate schema for error responses
+        var errorSchema = await context.GetOrCreateSchemaAsync(typeof(ProblemDetails), null, cancellationToken);
+        context.Document?.AddComponent("Error", errorSchema);
+
+        operation.Responses ??= new OpenApiResponses();
+        // Add a "4XX" response to the operation with the newly created schema
+        operation.Responses["4XX"] = new OpenApiResponse
+        {
+            Description = "Bad Request",
+            Content = new Dictionary<string, OpenApiMediaType>
+            {
+                ["application/problem+json"] = new OpenApiMediaType
+                {
+                    Schema = new OpenApiSchemaReference("Error", context.Document)
+                }
+            }
+        };
+    });
+});
+// </snippet_Generate_OpenApiSchemas_for_type>
+
+var app = builder.Build();
+
+// Configure the HTTP request pipeline.
+if (app.Environment.IsDevelopment())
+{
+    app.MapOpenApi("/openapi/{documentName}.yaml");
+}
+
+app.UseHttpsRedirection();
+
+app.UseAuthorization();
+
+app.MapControllers();
+
+app.Run();
+
+#endif
diff --git a/aspnetcore/fundamentals/openapi/samples/10.x/WebAppOpenAPI10/TransformerJsonNode.cs b/aspnetcore/fundamentals/openapi/samples/10.x/WebAppOpenAPI10/TransformerJsonNode.cs
@@ -0,0 +1,19 @@
+options.AddSchemaTransformer((schema, context, cancellationToken) =>
+{
+    if (context.JsonTypeInfo.Type == typeof(WeatherForecast))
+    {
+-       schema.Example = new OpenApiObject
++       schema.Example = new JsonObject
+        {
+-           ["date"] = new OpenApiString(DateTime.Now.AddDays(1).ToString("yyyy-MM-dd")),
++           ["date"] = DateTime.Now.AddDays(1).ToString("yyyy-MM-dd"),
+-           ["temperatureC"] = new OpenApiInteger(0),
++           ["temperatureC"] = 0,
+-           ["temperatureF"] = new OpenApiInteger(32),
++           ["temperatureF"] = 32,
+-           ["summary"] = new OpenApiString("Bracing"),
++           ["summary"] = "Bracing",
+        };
+    }
+    return Task.CompletedTask;
+});
diff --git a/aspnetcore/fundamentals/openapi/samples/10.x/WebAppOpenAPI10/WeatherForecast.cs b/aspnetcore/fundamentals/openapi/samples/10.x/WebAppOpenAPI10/WeatherForecast.cs
@@ -0,0 +1,13 @@
+namespace WebAppOpenAPI10
+{
+    public class WeatherForecast
+    {
+        public DateOnly Date { get; set; }
+
+        public int TemperatureC { get; set; }
+
+        public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
+
+        public string? Summary { get; set; }
+    }
+}
diff --git a/aspnetcore/fundamentals/openapi/samples/10.x/WebAppOpenAPI10/WebAppOpenAPI10.csproj b/aspnetcore/fundamentals/openapi/samples/10.x/WebAppOpenAPI10/WebAppOpenAPI10.csproj
@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+	<!-- <snippet_ConfigBuildTimeOpenApiDocVersion> -->
+	<PropertyGroup>
+		<TargetFramework>net10.0</TargetFramework>
+		<Nullable>enable</Nullable>
+		<ImplicitUsings>enable</ImplicitUsings>
+		<OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
+		<!-- Configure build-time OpenAPI generation to produce an OpenAPI 3.1 document. -->
+		<OpenApiGenerateDocumentsOptions>--openapi-version OpenApi3_1</OpenApiGenerateDocumentsOptions>
+	</PropertyGroup>
+	<!-- </snippet_ConfigBuildTimeOpenApiDocVersion> -->
+
+	<ItemGroup>
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0-preview.4.24272.1" />
+    </ItemGroup>
+
+</Project>
diff --git a/aspnetcore/fundamentals/openapi/samples/10.x/WebAppOpenAPI10/WebAppOpenAPI10.http b/aspnetcore/fundamentals/openapi/samples/10.x/WebAppOpenAPI10/WebAppOpenAPI10.http
@@ -0,0 +1,6 @@
+@WebAppOpenAPI10_HostAddress = http://localhost:5077
+
+GET {{WebAppOpenAPI10_HostAddress}}/weatherforecast/
+Accept: application/json
+
+###
diff --git a/aspnetcore/fundamentals/openapi/samples/10.x/WebAppOpenAPI10/appsettings.Development.json b/aspnetcore/fundamentals/openapi/samples/10.x/WebAppOpenAPI10/appsettings.Development.json
@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}
diff --git a/aspnetcore/fundamentals/openapi/samples/10.x/WebAppOpenAPI10/appsettings.json b/aspnetcore/fundamentals/openapi/samples/10.x/WebAppOpenAPI10/appsettings.json
@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*"
+}
diff --git a/aspnetcore/release-notes/aspnetcore-10/includes/blazor.md b/aspnetcore/release-notes/aspnetcore-10/includes/blazor.md
@@ -1,3 +1,15 @@
+### New and updated Blazor Web App security samples
+
+We've added and updated Blazor Web App security samples cross-linked in the following articles:
+
+* <xref:blazor/security/blazor-web-app-oidc>
+* <xref:blazor/security/blazor-web-app-entra>
+* <xref:blazor/security/blazor-web-app-windows-authentication>
+
+All of our OIDC and Entra sample solutions now include a separate web API project (`MinimalApiJwt`) to demonstrate how to configure and call an external web API securely. Calling web APIs is demonstrated with a token handler and named HTTP client for an OIDC identity provider or Microsoft Identity Web packages/API for Microsoft Entra ID.
+
+The sample solutions are configured in C# code in their `Program` files. To configure the solutions from app settings files (for example, `appsettings.json`) see the ***new*** *Supply configuration with the JSON configuration provider (app settings)* section of the OIDC or Entra articles.
+
 ### QuickGrid `RowClass` parameter
 
 Apply a stylesheet class to a row of the grid based on the row item using the new `RowClass` parameter. In the following example, the `GetRowCssClass` method is called on each row to conditionally apply a stylesheet class based on the row item:
