ASP.NET Core 10.0의 새로운 기능

이 문서에서는 ASP.NET Core 10.0의 가장 중요한 변경 내용과 관련 설명서에 대한 링크를 강조 표시합니다.

이 문서는 새 미리 보기 릴리스를 사용할 수 있게 됨에 따라 업데이트됩니다. 이 페이지가 업데이트될 때까지 Asp.Net Core 공지 페이지를 참조하세요.

Blazor

이 섹션에서는 Blazor대한 새로운 기능에 대해 설명합니다.

QuickGrid RowClass 매개 변수

새 RowClass 매개 변수를 사용하여 행 항목에 따라 표의 행에 스타일시트 클래스를 적용합니다. 다음 예제에서는 각 행에서 GetRowCssClass 메서드를 호출하여 행 항목에 따라 스타일시트 클래스를 조건부로 적용합니다.

<QuickGrid ... RowClass="GetRowCssClass">
    ...
</QuickGrid>

@code {
    private string GetRowCssClass(MyGridItem item) =>
        item.IsArchived ? "row-archived" : null;
}

자세한 내용은 ASP.NET Core Blazor 'QuickGrid' 구성 요소참조하세요.

Blazor 스크립트를 정적 웹 자산으로

.NET의 이전 릴리스에서 Blazor 스크립트는 ASP.NET Core 공유 프레임워크의 포함된 리소스에서 제공됩니다. .NET 10 이상에서 Blazor 스크립트는 자동 압축 및 지문을 사용하는 정적 웹 자산으로 제공됩니다.

자세한 내용은 다음 리소스를 참조하세요.

• ASP.NET Core Blazor 프로젝트 구조
• ASP.NET Core Blazor 정적 파일

경로 템플릿 강조 표시

이제 [Route] 특성 경로 구문 강조 표시를 지원하여 경로 템플릿의 구조를 시각화합니다.

카운터 값에 대한 경로 특성의 강조 표시된 구문을 보여 줍니다.

NavigateTo 더 이상 동일한 페이지 탐색을 위해 위쪽으로 스크롤하지 않습니다.

이전에는 NavigationManager.NavigateTo 동일한 페이지 탐색을 위해 페이지 맨 위로 스크롤했습니다. 이 동작은 .NET 10에서 변경되어 동일한 페이지로 이동할 때 브라우저가 더 이상 페이지 맨 위로 스크롤되지 않도록 합니다. 즉, 쿼리 문자열 또는 조각 변경과 같이 현재 페이지의 주소를 업데이트할 때 뷰포트가 더 이상 다시 설정되지 않습니다.

Blazor Web App 프로젝트 템플릿에 추가된 다시 연결 UI 구성 요소

이제 Blazor Web App 프로젝트 템플릿에는 클라이언트가 서버에 대한 WebSocket 연결을 끊을 때 다시 연결 UI에 대한 개발자 제어를 개선하기 위해 정렬된 스타일시트 및 JavaScript 파일을 비롯한 ReconnectModal 구성 요소가 포함됩니다. 구성 요소는 스타일을 프로그래밍 방식으로 삽입하지 않으므로 style-src 정책에 대해 더 엄격한 CSP(콘텐츠 보안 정책) 설정을 준수합니다. 이전 릴리스에서는 CSP 위반을 일으킬 수 있는 방식으로 프레임워크에서 기본 다시 연결 UI를 만들었습니다. 기본 다시 연결 UI는 앱이 프로젝트 템플릿의 ReconnectModal 구성 요소 또는 유사한 사용자 지정 구성 요소를 사용하는 등 다시 연결 UI를 정의하지 않는 경우에도 대체(fallback)로 사용됩니다.

새로운 다시 연결 UI 기능:

• 다시 연결 UI 요소에서 특정 CSS 클래스를 설정하여 다시 연결 상태를 나타내는 것 외에도 다시 연결 상태 변경을 위해 새 components-reconnect-state-changed 이벤트가 디스패치됩니다.
• 코드는 CSS 클래스와 새 이벤트 둘 다에서 나타내는 새 다시 연결 상태 "retrying"로 다시 연결 프로세스의 단계를 더 잘 구분할 수 있습니다.

자세한 내용은 ASP.NET Core BlazorSignalR 지침을 참조하세요.

NavLinkMatch.All 사용할 때 쿼리 문자열 및 조각 무시

이제 NavLink 구성 요소는 NavLinkMatch.All 매개 변수에 Match 값을 사용할 때 쿼리 문자열 및 조각을 무시합니다. 즉, URL 경로가 일치하지만 쿼리 문자열 또는 조각이 변경되는 경우 링크는 active 클래스를 유지합니다. 원래 동작으로 되돌리려면 스위치를 Microsoft.AspNetCore.Components.Routing.NavLink.EnableMatchAllForQueryStringAndFragmentAppContext 다음으로 true설정합니다.

ShouldMatch 메서드를 NavLink에서 재정의하여 일치하는 동작을 사용자 지정할 수도 있습니다.

public class CustomNavLink : NavLink
{
    protected override bool ShouldMatch(string currentUriAbsolute)
    {
        // Custom matching logic
    }
}

자세한 내용은 ASP.NET Core Blazor 라우팅 및 탐색을 참조하세요.

열 옵션을 닫기 QuickGrid

이제 새 QuickGrid 메서드를 사용하여 CloseColumnOptionsAsync 열 옵션 UI를 닫을 수 있습니다.

다음 예제에서는 CloseColumnOptionsAsync 메서드를 사용하여 제목 필터가 적용되는 즉시 열 옵션 UI를 닫습니다.

<QuickGrid @ref="movieGrid" Items="movies">
    <PropertyColumn Property="@(m => m.Title)" Title="Title">
        <ColumnOptions>
            <input type="search" @bind="titleFilter" placeholder="Filter by title" 
                @bind:after="@(() => movieGrid.CloseColumnOptionsAsync())" />
        </ColumnOptions>
    </PropertyColumn>
    <PropertyColumn Property="@(m => m.Genre)" Title="Genre" />
    <PropertyColumn Property="@(m => m.ReleaseYear)" Title="Release Year" />
</QuickGrid>

@code {
    private QuickGrid<Movie>? movieGrid;
    private string titleFilter = string.Empty;
    private IQueryable<Movie> movies = new List<Movie> { ... }.AsQueryable();
    private IQueryable<Movie> filteredMovies => 
        movies.Where(m => m.Title!.Contains(titleFilter));
}

응답 스트리밍이 옵트인되고 옵트아웃하는 방법

이전 Blazor 릴리스에서는 요청에 대한 HttpClient 응답 스트리밍이 옵트인되었습니다. 이제 응답 스트리밍은 기본적으로 사용하도록 설정됩니다.

이는 HttpResponseMessage.Content의 HttpContent.ReadAsStreamAsync 호출이 response.Content.ReadAsStreamAsync()에 대해 더 이상 MemoryStream가 아닌 BrowserHttpReadStream를 반환하기 때문에 호환성을 손상하는 변경 사항입니다. BrowserHttpReadStream 는 와 같은 Stream.Read(Span<Byte>)동기 작업을 지원하지 않습니다. 코드에서 동기 작업을 사용하는 경우, 응답 스트리밍을 선택 해제하거나 Stream를 MemoryStream로 직접 복사할 수 있습니다.

응답 스트리밍을 전역적으로 옵트아웃하려면 환경 변수 DOTNET_WASM_ENABLE_STREAMING_RESPONSE 를 false 설정하거나 0설정합니다.

개별 요청에 대한 응답 스트리밍을 옵트아웃하려면, 다음 예제에서 SetBrowserResponseStreamingEnabled의 false에 대해 HttpRequestMessage을(를) requestMessage로 설정하십시오.

requestMessage.SetBrowserResponseStreamingEnabled(false);

자세한 내용을 보려면 Fetch API 요청 옵션(웹 API 호출 문서)을 HttpClient및HttpRequestMessage 참조하세요.

클라이언트 측 디바이스 핑거프린팅

작년에 .NET 9가 릴리스되면서 정적 자산의 서버 쪽 지문 기능이 도입되었습니다. 이 릴리스에는 맵 정적 자산 라우팅 엔드포인트 규칙(MapStaticAssets), ImportMap 구성 요소, 그리고 ComponentBase.Assets 속성을 통해 지문이 포함된 JavaScript 모듈을 해결할 수 있는 기능이 포함되었습니다.Blazor Web App@Assets["..."] .NET 10의 경우 독립 실행형 Blazor WebAssembly 앱에 대한 JavaScript 모듈의 클라이언트 쪽 지문을 옵트인할 수 있습니다.

빌드/게시하는 동안, 독립 실행형 Blazor WebAssembly 앱에서 프레임워크는 빌드 중에 계산된 값으로 index.html의 자리 표시자를 대체하여 정적 자산을 고유하게 식별합니다. 지문 정보는 스크립트 파일 이름에 blazor.webassembly.js 삽입됩니다.

지문 기능을 채택하려면 파일에서 wwwwoot/index.html 다음을 변경해야 합니다. 독립 실행형 Blazor WebAssembly 프로젝트 템플릿은 향후 미리 보기 릴리스에 이러한 변경 내용을 포함하도록 업데이트됩니다.

<head>
    ...
+   <script type="importmap"></script>
</head>

<body>
    ...
-   <script src="_framework/blazor.webassembly.js"></script>
+   <script src="_framework/blazor.webassembly#[.{fingerprint}].js"></script>
</body>

</html>

프로젝트 파일(.csproj)에 속성을 추가하고, <WriteImportMapToHtml>을(를) true로 설정합니다.

<Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
+   <WriteImportMapToHtml>true</WriteImportMapToHtml>
  </PropertyGroup>
</Project>

독립 실행형 Blazor WebAssembly 앱에서 추가 JS 모듈의 지문을 지정하려면 앱의 프로젝트 파일(.csproj)에서 <StaticWebAssetFingerprintPattern> 속성을 사용하세요.

다음 예제에서는 앱에서 개발자가 제공한 모든 파일에 지문이 추가됩니다 .mjs .

<StaticWebAssetFingerprintPattern Include="JSModule" Pattern="*.mjs" 
  Expression="#[.{fingerprint}]!" />

파일은 자동으로 가져오기 맵에 배치됩니다.

• Blazor Web App CSR에 대해 자동으로.
• 이전 지침에 따라 독립 실행형 Blazor WebAssembly 앱에서 모듈 지문 기능을 활성화할 경우

JavaScript interop에 대한 가져오기에서 지문 파일을 해결하기 위해 브라우저가 가져오기 맵을 사용합니다.

독립 실행형 Blazor WebAssembly 앱에서 환경 설정

이 Properties/launchSettings.json 파일은 독립 실행형 앱의 환경을 제어하는 데 더 이상 사용되지 않습니다 Blazor WebAssembly .

.NET 10부터 앱의 프로젝트 파일(.csproj)에서 <WasmApplicationEnvironmentName> 속성을 사용하여 환경을 설정합니다.

다음 예제에서는 앱의 환경을 다음으로 Staging설정합니다.

<WasmApplicationEnvironmentName>Staging</WasmApplicationEnvironmentName>

기본 환경은 다음과 같습니다.

• Development 빌드용입니다.
• Production 게시용입니다.

부팅 구성 파일 이름 변경

부팅 구성 파일의 이름이 blazor.boot.json에서 dotnet.boot.js로 변경되고 있습니다. 이 이름 변경은 다음과 같이 파일과 직접 상호 작용하는 개발자에게만 영향을 줍니다.

• ASP.NET Core Blazor WebAssembly .NET 번들 캐싱 및 무결성 검사 실패의 지침에 따라 문제 해결 무결성 PowerShell 스크립트를 사용하여 게시된 자산에 대한 파일 무결성을 확인합니다.
• Host의 지침에 따라 기본 웹실 파일 형식을 사용하지 않는 경우 DLL 파일의 파일 이름 확장명을 변경하고 ASP.NET CoreBlazor WebAssembly를 배포합니다.

구성 요소 및 서비스에서 상태를 유지하기 위한 선언적 모델

이제 특성을 사용하여 [SupplyParameterFromPersistentComponentState] 구성 요소 및 서비스에서 유지할 상태를 선언적으로 지정할 수 있습니다. 이 특성이 있는 속성은 미리 렌더링하는 동안 서비스를 사용하여 PersistentComponentState 자동으로 유지됩니다. 구성 요소가 대화형으로 렌더링되거나 서비스가 인스턴스화될 때 상태가 검색됩니다.

이전 Blazor 릴리스에서는 다음 예제와 같이 서비스를 사용하여 PersistentComponentState 미리 렌더링하는 동안 구성 요소 상태를 유지하는 데 상당한 양의 코드가 포함되었습니다.

@page "/movies"
@implements IDisposable
@inject IMovieService MovieService
@inject PersistentComponentState ApplicationState

@if (MoviesList == null)
{
    <p><em>Loading...</em></p>
}
else
{
    <QuickGrid Items="MoviesList.AsQueryable()">
        ...
    </QuickGrid>
}

@code {
    public List<Movie>? MoviesList { get; set; }
    private PersistingComponentStateSubscription? persistingSubscription;

    protected override async Task OnInitializedAsync()
    {
        if (!ApplicationState.TryTakeFromJson<List<Movie>>(nameof(MoviesList), 
            out var movies))
        {
            MoviesList = await MovieService.GetMoviesAsync();
        }
        else
        {
            MoviesList = movies;
        }

        persistingSubscription = ApplicationState.RegisterOnPersisting(() =>
        {
            ApplicationState.PersistAsJson(nameof(MoviesList), MoviesList);
            return Task.CompletedTask;
        });
    }

    public void Dispose() => persistingSubscription?.Dispose();
}

이제 새 선언적 모델을 사용하여 이 코드를 간소화할 수 있습니다.

@page "/movies"
@inject IMovieService MovieService

@if (MoviesList == null)
{
    <p><em>Loading...</em></p>
}
else
{
    <QuickGrid Items="MoviesList.AsQueryable()">
        ...
    </QuickGrid>
}

@code {
    [SupplyParameterFromPersistentComponentState]
    public List<Movie>? MoviesList { get; set; }

    protected override async Task OnInitializedAsync()
    {
        MoviesList ??= await MovieService.GetMoviesAsync();
    }
}

자세한 내용은 Prerender ASP.NET Core Razor 구성 요소를 참조하세요. 언제든지 변경될 수 있는 추가 API 구현 정보는 [Blazor] 구성 요소 및 서비스 상태를 선언적으로 유지하는 지원(dotnet/aspnetcore #60634)에서 사용할 수 있습니다.

Blazor Hybrid

이 섹션에서는 Blazor Hybrid대한 새로운 기능에 대해 설명합니다.

새로운 .NET MAUIBlazor Hybrid에는 Blazor Web App 및 ASP.NET Core Identity 문서와 샘플이 포함되어 있습니다.

ASP.NET Core .NET MAUI를 사용하여 Blazor Hybrid,Identity 및 웹 애플리케이션에 대한 새 기사 및 샘플 앱이 추가되었습니다.

자세한 내용은 다음 리소스를 참조하세요.

• ASP.NET Core .NET MAUIBlazor HybridIdentity를 사용한 웹 애플리케이션
• MauiBlazorWebIdentity 샘플 앱(dotnet/blazor-samples GitHub 리포지토리)

SignalR

이 섹션에서는 SignalR대한 새로운 기능에 대해 설명합니다.

최소 API

이 섹션에서는 최소 API에 대한 새로운 기능에 대해 설명합니다.

폼 제출 시 빈 문자열을 nullable 타입에 대해 null로 처리

최소 API에서 복합 개체와 함께 [FromForm] 특성을 사용하는 경우, 양식 게시물의 빈 문자열 값은 구문 분석 실패를 유발하지 않고 이제 null로 변환됩니다. 이 동작은 최소 API에서 복잡한 개체와 연결되지 않은 양식 게시물에 대한 처리 논리와 일치합니다.

using Microsoft.AspNetCore.Http;

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapPost("/todo", ([FromForm] Todo todo) => TypedResults.Ok(todo));

app.Run();

public class Todo
{
  public int Id { get; set; }
  public DateOnly? DueDate { get; set; } // Empty strings map to `null`
  public string Title { get; set; }
  public bool IsCompleted { get; set; }
}

이 변화에 기여해 주신 @nvmkpk 감사합니다!

최소 API의 유효성 검사 지원

이제 최소 API의 유효성 검사 지원을 사용할 수 있습니다. 이 기능을 사용하면 API 엔드포인트로 전송된 데이터의 유효성 검사를 요청할 수 있습니다. 유효성 검사를 사용하도록 설정하면 ASP.NET Core 런타임에서 다음 사항에 정의된 유효성 검사를 수행할 수 있습니다.

• 쿼리
• 헤더
• 요청 메시지 본문

유효성 검사는 네임스페이스의 특성을 DataAnnotations 사용하여 정의됩니다. 개발자는 다음을 통해 유효성 검사 시스템의 동작을 사용자 지정합니다.

• 사용자 지정 [Validation] 특성 구현 만들기
• IValidatableObject 복잡한 유효성 검사 논리에 대한 인터페이스 구현

유효성 검사에 실패하면 런타임은 유효성 검사 오류에 대한 세부 정보가 포함된 400 잘못된 요청 응답을 반환합니다.

최소 API에 대한 기본 제공 유효성 검사 지원 사용

애플리케이션의 서비스 컨테이너에 필요한 서비스를 등록하기 위해 확장 메서드를 호출 AddValidation 하여 최소 API에 대한 기본 제공 유효성 검사 지원을 사용하도록 설정합니다.

builder.Services.AddValidation();

구현은 최소 API 처리기 또는 최소 API 처리기에 정의된 형식의 기본 클래스인 형식을 자동으로 검색합니다. 엔드포인트 필터는 이러한 형식에 대한 유효성 검사를 수행하고 각 엔드포인트에 대해 추가됩니다.

다음 예제와 같이 확장 메서드를 사용하여 특정 엔드포인트에 DisableValidation 대해 유효성 검사를 사용하지 않도록 설정할 수 있습니다.

app.MapPost("/products",
    ([EvenNumber(ErrorMessage = "Product ID must be even")] int productId, [Required] string name)
        => TypedResults.Ok(productId))
    .DisableValidation();

Server-Sent 이벤트에 대한 지원 (SSE)

이제 ASP.NET Core는 TypedResults.ServerSentEvents API를 사용하여 ServerSentEvents 결과 반환을 지원합니다. 이 기능은 최소 API 및 컨트롤러 기반 앱 모두에서 지원됩니다.

Server-Sent 이벤트는 서버가 단일 HTTP 연결을 통해 클라이언트에 이벤트 메시지 스트림을 보낼 수 있도록 하는 서버 푸시 기술입니다. .NET에서 이벤트 메시지는 이벤트 형식, ID 및 형식T의 데이터 페이로드를 포함할 수 있는 개체로 SseItem<T> 표시됩니다.

TypedResults 클래스에는 결과를 반환하는 데 사용할 수 있는 ServerSentEvents라는 새 정적 메서드가 ServerSentEvents 있습니다. 이 메서드의 첫 번째 매개 변수는 클라이언트로 보낼 이벤트 메시지의 스트림을 나타내는 매개 변수입니다 IAsyncEnumerable<SseItem<T>> .

다음 예제에서는 API를 TypedResults.ServerSentEvents 사용하여 심박수 이벤트의 스트림을 클라이언트에 JSON 개체로 반환하는 방법을 보여 줍니다.

app.MapGet("/json-item", (CancellationToken cancellationToken) =>
{
    async IAsyncEnumerable<HeartRateRecord> GetHeartRate(
        [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        while (!cancellationToken.IsCancellationRequested)
        {
            var heartRate = Random.Shared.Next(60, 100);
            yield return HeartRateRecord.Create(heartRate);
            await Task.Delay(2000, cancellationToken);
        }
    }

    return TypedResults.ServerSentEvents(GetHeartRate(cancellationToken),
                                                  eventType: "heartRate");
});

자세한 내용은 다음을 참조하세요.

• Server-Sent 이벤트 on MDN.
• API를 사용하여 TypedResults.ServerSentEvents 심박수 이벤트의 스트림을 문자열로 반환하고 JSON ServerSentEvents개체를 클라이언트에 반환하는 최소 API 샘플 앱입니다.
• API를 TypedResults.ServerSentEvents 사용하여 심박수 이벤트의 스트림을 문자열로 반환하고 JSON ServerSentEvents개체를 클라이언트에 반환하는 컨트롤러 API 샘플 앱입니다.

OpenAPI

이 섹션에서는 OpenAPI의 새로운 기능에 대해 설명합니다.

OpenAPI 3.1 지원

ASP.NET Core는 .NET 10에서 OpenAPI 버전 3.1 문서를 생성하기 위한 지원을 추가했습니다. 소 버전 업데이트임에도 불구하고, OpenAPI 3.1은 특히 JSON 스키마 초안 2020-12에 대한 완전한 지원을 통해 OpenAPI 사양에 대한 중요한 업데이트입니다.

생성된 OpenAPI 문서에 표시되는 변경 내용 중 일부는 다음과 같습니다.

• Nullable 형식에는 스키마에 nullable: true 속성이 더 이상 없습니다.
• nullable: true 속성 대신, 값이 배열로 표현되어 있으며 그 배열에는 type를 포함하는 null 키워드가 있습니다.

이 기능을 사용하면 생성된 문서에 대한 기본 OpenAPI 버전이3.1. AddOpenApi 대리자 매개 변수에서 configureOptionsOpenApiVersion 속성을 명시적으로 설정하여 버전을 변경할 수 있습니다.

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

빌드 시 OpenAPI 문서를 생성할 때 --openapi-version MSBuild 항목에서 OpenApiGenerateDocumentsOptions 설정하여 OpenAPI 버전을 선택할 수 있습니다.

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

OpenAPI 3.1 지원은 주로 PR를 통해 추가되었습니다.

OpenAPI 3.1 호환성에 영향을 미치는 변경 사항

OpenAPI 3.1을 지원하려면 기본 OpenAPI.NET 라이브러리를 새 주 버전인 2.0으로 업데이트해야 합니다. 이 새 버전에는 이전 버전과 비교하여 호환성에 중대한 영향을 미치는 변경 내용이 있습니다. 주요 변경 사항은 문서, 운영, 또는 스키마 변환기가 있는 경우 앱에 영향을 미칠 수 있습니다.

가장 중요한 변경 사항 중 하나는 OpenApiAny 클래스가 JsonNode 직접 사용하기 위해 삭제되었다는 것입니다. OpenApiAny 사용하는 변환기는 JsonNode사용하도록 업데이트해야 합니다. .NET 9에서 .NET 10으로 업그레이드된 스키마 변환기의 변경 내역은 다음과 같습니다.

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;
});

이러한 변경은 OpenAPI 버전을 3.0으로 구성하는 경우에만 필요합니다.

Yaml의 OpenAPI

이제 ASP.NET 생성된 OpenAPI 문서를 YAML 형식으로 제공합니다. YAML은 JSON보다 간결할 수 있으므로 유추할 수 있을 때 중괄호와 따옴표를 제거합니다. YAML은 긴 설명에 유용할 수 있는 여러 줄 문자열도 지원합니다.

생성된 OpenAPI 문서를 YAML 형식으로 제공하도록 앱을 구성하려면 다음 예제와 같이 ".yaml" 또는 ".yml" 접미사를 사용하여 MapOpenApi 호출의 엔드포인트를 지정합니다.

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

지원 대상:

• YAML은 현재 OpenAPI 엔드포인트에서 제공되는 OpenAPI에만 사용할 수 있습니다.
• 빌드 시 YAML 형식으로 OpenAPI 문서를 생성하는 작업이 향후 미리 보기에 추가됩니다.

생성된 OpenAPI 문서를 YAML 형식으로 제공하는 지원을 추가한 이 PR 참조하세요.

ProducesResponseType에 대한 응답 설명

ProducesAttribute, ProducesResponseTypeAttribute및 ProducesDefaultResponseType 특성은 이제 응답에 대한 설명을 설정하는 선택적 문자열 매개 변수 Description허용합니다. 예제는 다음과 같습니다.

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

생성된 OpenAPI는 다음과 같습니다.

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

커뮤니티 기여 by 샌더 텐 브링크🙏

OpenAPI 문서에 XML 문서 주석 채우기

ASP.NET Core OpenAPI 문서 생성에는 이제 OpenAPI 문서의 메서드, 클래스 및 멤버 정의에 대한 XML 문서 주석의 메타데이터가 포함됩니다. 이 기능을 사용하려면 프로젝트 파일에서 XML 문서 주석을 사용하도록 설정해야 합니다. 프로젝트 파일에 다음 속성을 추가하여 이 작업을 수행할 수 있습니다.

  <PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>

빌드 시 OpenAPI 패키지는 원본 생성기를 활용하여 현재 애플리케이션 어셈블리 및 프로젝트 참조에서 XML 주석을 검색하고 소스 코드를 내보내 OpenAPI 문서 변환기를 통해 문서에 삽입합니다.

C# 빌드 프로세스는 람다 설명에 배치된 XML 문서 주석을 캡처하지 않으므로 XML 문서 주석을 사용하여 최소 API 엔드포인트에 메타데이터를 추가하려면 엔드포인트 처리기를 메서드로 정의하고 메서드에 XML 문서 주석을 배치한 다음 MapXXX 메서드에서 해당 메서드를 참조해야 합니다. 예를 들어 XML 문서 주석을 사용하여 원래 람다 식으로 정의된 최소 API 엔드포인트에 메타데이터를 추가하려면 다음을 수행합니다.

app.MapGet("/hello", (string name) =>$"Hello, {name}!");

메서드를 참조하도록 MapGet 호출을 변경합니다.

app.MapGet("/hello", Hello);

XML 문서 주석을 사용하여 Hello 메서드를 정의합니다.

static partial class Program
{
    /// <summary>
    /// Sends a greeting.
    /// </summary>
    /// <remarks>
    /// Greeting a person by their name.
    /// </remarks>
    /// <param name="name">The name of the person to greet.</param>
    /// <returns>A greeting.</returns>
    public static string Hello(string name)
    {
        return $"Hello, {name}!";
    }
}

이전 예제에서 Hello 메서드는 Program 클래스에 추가되지만 프로젝트의 모든 클래스에 추가할 수 있습니다.

이전 예제에서는 <summary>, <remarks>및 <param> XML 문서 주석을 보여 줍니다. 지원되는 모든 태그를 포함하여 XML 문서 주석에 대한 자세한 내용은 C# 설명서를 참조하세요.

핵심 기능은 원본 생성기를 통해 제공되므로 프로젝트 파일에 다음 MSBuild를 추가하여 사용하지 않도록 설정할 수 있습니다.

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0-preview.2.*" GeneratePathProperty="true" />
</ItemGroup>

<Target Name="DisableCompileTimeOpenApiXmlGenerator" BeforeTargets="CoreCompile">
  <ItemGroup>
    <Analyzer Remove="$(PkgMicrosoft_AspNetCore_OpenApi)/analyzers/dotnet/cs/Microsoft.AspNetCore.OpenApi.SourceGenerators.dll" />
  </ItemGroup>
</Target>

AdditionalFiles 속성에 포함된 원본 생성기 프로세스 XML 파일입니다. 속성을 추가(또는 제거)하려면 원천이 다음과 같이 속성을 수정합니다.

<Target Name="AddXmlSources" BeforeTargets="CoreCompile">
  <ItemGroup>
    <AdditionalFiles Include="$(PkgSome_Package)/lib/net10.0/Some.Package.xml" />
  </ItemGroup>
</Target>

OpenAPI.NET v2.0.0-preview7로 업그레이드

ASP.NET Core OpenAPI 문서 생성에 사용되는 OpenAPI.NET 라이브러리가 v2.0.0-preview7로 업그레이드되었습니다. 이 버전에는 몇 가지 주요 변경 내용을 소개하는 동시에 다양한 버그 수정 및 개선 사항이 포함되어 있습니다. 호환성이 깨지는 변경 사항은 문서, 작업 또는 스키마 변환기를 사용하는 사용자에게만 영향을 줍니다. 이 반복의 주요 변경 내용은 다음과 같습니다.

• 작업 및 매개 변수와 같은 OpenAPI 문서 내의 엔터티는 인터페이스로 입력됩니다. 엔터티의 인라인 및 참조된 변형에 대한 명확한 구현이 있습니다. 예를 들어, IOpenApiSchema는 인라인된 OpenApiSchema일 수도 있고 문서의 다른 위치에 정의된 스키마를 가리키는 OpenApiSchemaReference일 수도 있습니다.
• Nullable 속성이 OpenApiSchema 형식에서 제거되었습니다. 형식이 nullable인지 확인하려면 OpenApiSchema.Type 속성이 JsonSchemaType.Null설정하는지 평가합니다.

ASP.NET Core 웹 API(네이티브 AOT) 템플릿에 추가된 Microsoft.AspNetCore.OpenApi

이제 ASP.NET Core Web API(네이티브 AOT) 프로젝트 템플릿(짧은 이름webapiaot)에는 기본적으로 패키지를 사용하는 Microsoft.AspNetCore.OpenApi OpenAPI 문서 생성에 대한 지원이 포함됩니다. 이 지원은 새 프로젝트를 만들 때 플래그를 --no-openapi 사용하여 사용하지 않도록 설정됩니다.

@sander1095의 커뮤니티 기여입니다. 이 기여 주셔서 감사합니다!

인증 및 권한 부여

이 섹션에서는 인증 및 권한 부여를 위한 새로운 기능에 대해 설명합니다.

인증 및 권한 부여 메트릭

ASP.NET Core의 특정 인증 및 권한 부여 이벤트에 대한 메트릭이 추가되었습니다. 이 변경으로 이제 다음 이벤트에 대한 메트릭을 가져올 수 있습니다.

• 인증:
  • 인증된 요청 기간
  • 도전 횟수
  • 카운트 금지
  • 로그인 수
  • 로그아웃 횟수
• 권한 부여:
  • 권한 부여가 필요한 요청 수

다음 이미지는 Aspire 대시보드에서 인증된 요청 기간 메트릭의 예를 보여줍니다.

자세한 내용은 ASP.NET 핵심 권한 부여 및 인증 메트릭을 참조하세요.

기타

이 섹션에서는 ASP.NET Core 10.0의 기타 새로운 기능에 대해 설명합니다.

최상위 문을 사용한 앱 테스트에 대한 지원 향상

.NET 10은 이제 최상위 문을 사용하는 앱을 테스트하는 데 더 나은 지원을 제공합니다. 이전에 개발자는 테스트 프로젝트에서 public partial class Program참조할 수 있도록 Program.cs 파일에 Program class 수동으로 추가해야 했습니다. C# 9의 최상위 문 기능이 public partial class Program으로 선언된 Program class을 생성했기 때문에 이 필요했습니다.

.NET 10에서는 프로그래머가 명시적으로 선언하지 않은 경우 원본 생성기 사용하여 public partial class Program 선언을 생성합니다. 또한 public partial class Program 명시적으로 선언된 시기를 감지하고 개발자에게 제거하도록 권고하기 위해 분석기가 추가되었습니다.

이 기능에 기여한 PR은 다음과 같습니다.

• PR 58199
• PR 58482

RedirectHttpResult.IsLocalUrl 사용하여 URL이 로컬인지 감지

새 RedirectHttpResult.IsLocalUrl(url) 도우미 메서드를 사용하여 URL이 로컬인지 검색합니다. URL은 다음이 true인 경우 로컬로 간주됩니다.

• 호스트 또는 권한 섹션이 없습니다.
• 절대 경로가있습니다.

가상 경로를 사용하는 URL도 로컬입니다.

IsLocalUrl URL로 리디렉션하기 전에 유효성을 검사하여 오픈 리디렉션 공격을 방지하는 데 유용합니다.

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

이 기여에 @martincostello 감사합니다!

관련 콘텐츠