Update the "What's new in ASP.NET Core 10.0" for .NET 10 Preview 1

[danroth27]

Description

Update the "What's new in ASP.NET Core 10.0" for .NET 10 Preview 1

Page URL

https://learn.microsoft.com/en-us/aspnet/core/release-notes/aspnetcore-10.0?view=aspnetcore-10.0

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/release-notes/aspnetcore-10.0.md

Document ID

4e75ad25-2c3f-b28e-6a91-ac79a9c683b6

Article author

@Rick-Anderson

Metadata

• ID: 4e75ad25-2c3f-b28e-6a91-ac79a9c683b6
• Service: aspnet-core
• Sub-service: release-notes

Related Issues

---

Associated WorkItem - 368778

[mikekistler]

OpenAPI 3.1 support

dotnet/aspnetcore#59480
dotnet/aspnetcore#60002

ASP.NET Core has added support for generating OpenAPI version 3.1 documents in .NET 10.
Despite the minor version bump, OpenAPI 3.1 is a significant update to the OpenAPI specification,
in particular with full support for JSON Schema draft 2020-12.

Some of the changes you will see in the generated OpenAPI document include:

• Nullable types will no longer have the nullable: true property in the schema, and instead will have a type keyword whose value is an array that includes null as one of the types.

With this feature, the default OpenAPI version for generated documents will be 3.1, but you can easily change this
by explicitly setting the OpenApiVersion property of the OpenApiOptions in the configureOptions delegate
parameter of AddOpenApi.

builder.Services.AddOpenApi(options =>
{
    // Specify the OpenAPI version to use.
    options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0;
});

If you are generating the OpenAPI document at build time, you can select the OpenAPI version by setting the --openapi-version in the OpenApiGenerateDocumentsOptions MSBuild item.

    <!-- Configure build-time OpenAPI generation to produce an OpenAPI 3.0 document. -->
    <OpenApiGenerateDocumentsOptions>--openapi-version OpenApi3_0</OpenApiGenerateDocumentsOptions>

Breaking changes

Support for OpenAPI 3.1 requires an update to the underlying OpenAPI.NET library to a new major version, 2.0.
This new version has some breaking changes from the previous version, and this may impact your applications
if you have any document, operation, or schema transformers.
Perhaps the most significant change is that the OpenApiAny class has been dropped in favor of using JsonNode directly.
If your transformers use OpenApiAny, you will need to update them to use JsonNode instead.
For example, a schema transformer to add an example in .NET 9 might look like this:

    options.AddSchemaTransformer((schema, context, cancellationToken) =>
    {
        if (context.JsonTypeInfo.Type == typeof(WeatherForecast))
        {
            schema.Example = new OpenApiObject
            {
                ["date"] = new OpenApiString(DateTime.Now.AddDays(1).ToString("yyyy-MM-dd")),
                ["temperatureC"] = new OpenApiInteger(0),
                ["temperatureF"] = new OpenApiInteger(32),
                ["summary"] = new OpenApiString("Bracing"),
            };
        }
        return Task.CompletedTask;
    });

In .NET 10 the transformer to do the same task will look like this:

    options.AddSchemaTransformer((schema, context, cancellationToken) =>
    {
        if (context.JsonTypeInfo.Type == typeof(WeatherForecast))
        {
            schema.Example = new JsonObject
            {
                ["date"] = DateTime.Now.AddDays(1).ToString("yyyy-MM-dd"),
                ["temperatureC"] = 0,
                ["temperatureF"] = 32,
                ["summary"] = "Bracing",
            };
        }
        return Task.CompletedTask;
    });

Note that these changes will be necessary even if you congfigure the OpenAPI version to 3.0.

[mikekistler]

OpenAPI in Yaml

dotnet/aspnetcore#58616

ASP.NET now supports serving the generated OpenAPI document in YAML format.
YAML can be more concise than JSON, eliminating curly braces and quotation marks when these can be inferred.
YAML also supports multi-line strings, which can be useful for long descriptions.

To configure your application to serve the generated OpenAPI document in YAML format,
specify the endpoint in the MapOpenApi call with a ".yaml" or ".yml" suffix, as shown in this example:

app.MapOpenApi("/openapi/{documentName}.yaml");

Support for YAML is currently only available for the the OpenAPI served from the OpenAPI endpoint.
Support for generating OpenAPI documents in YAML format at build time will be added in a future preview.

[mikekistler]

Response description on ProducesResponseType

dotnet/aspnetcore#58193

The ProducesAttribute, ProducesResponseTypeAttribute, and ProducesDefaultResponseType attributes now accept an optional string parameter, Description, that will set the description of the response. Here's an example:

[HttpGet(Name = "GetWeatherForecast")]
[ProducesResponseType<IEnumerable<WeatherForecast>>(StatusCodes.Status200OK, Description = "The weather forecast for the next 5 days.")]
public IEnumerable<WeatherForecast> Get()
{

And the generated OpenAPI will be

        "responses": {
          "200": {
            "description": "The weather forecast for the next 5 days.",
            "content": {

Community contribution! 🙏

[mikekistler]

Better support for testing apps with top-level statements

dotnet/aspnetcore#58199
dotnet/aspnetcore#58482

.NET 10 now has better support for testing apps that use top-level statements.
Previously developers had to manually add public partial class Program to the
Program.cs file so that the test project could reference the Program class.
This is because the top-level statement feature in C# 9 generated a Program class
that was declared as internal.

In .NET 10, a source generator is used to generate the public partial class Program
declaration if the programmer did not declare it explicitly. In addition, an analyzer
was added to detect when public partial class Program is declared explicitly and
advise the developer to remove it.

[guardrex]

Blazor coverage thus far

• New QuickGrid RowClass parameter
• Blazor script is served as a static web asset with automatic compression and fingerprinting

Cross-links ...

• Live WN coverage
• Blazor .NET 10 Tracking Issue

[danroth27]

Route syntax highlighting for Blazor RouteAttribute

The RouteAttribute in Blazor now supports route syntax highlighting to help visualize the structure of the route template.

Thank you @IEvangelist for this contribution!

[danroth27]

@captainsafia @mikekistler Looks like this API was added months ago, but is only now being released with .NET 10.

Detect if URL is local using RedirectHttpResult.IsLocalUrl

Use the new RedirectHttpResult.IsLocalUrl(url) helper method to detect if a URL is local. A URL is considered local if it does not have the host or authority part and it has an absolute path. This method is useful for validating URLs before redirecting to them to prevent open redirection attacks.

if (RedirectHttpResult.IsLocalUrl(url))
{
    return Results.LocalRedirect(url);
}

Thank you @martincostello for this contribution!

[wadepickett]

@danroth27, I don't see any draft info for SignalR in the comments here yet or for a couple others that have sections reserved in the draft. Should I look somewhere else, or will it be dropped here in the comments for those as well? I just wanted to make sure I wasn't missing it somehow, thanks.

[danroth27]

@danroth27, I don't see any draft info for SignalR in the comments here yet or for a couple others that have sections reserved in the draft. Should I look somewhere else, or will it be dropped here in the comments for those as well? I just wanted to make sure I wasn't missing it somehow, thanks.

@wadepickett Everything new in Preview 1 is covered in the existing comments. That may mean some of the sections in the What's New draft may not have content yet.

You can also see the merged ASP.NET Core release notes for .NET 10 Preview 1 here: dotnet/core#9740