C# Academy · Lekcja

Konfigurowanie Asp.Versioning

Skonfiguruj wersjonowanie w ASP.NET Core.

Konfigurowanie Asp.Versioning to bezpłatna lekcja C# Academy na CoddyKit. To lekcja 2 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej C# Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs C# Academy zawiera 4 lekcji w sumie.

Pakiet Asp.Versioning

Wersjonowanie API w ASP.NET Core jest dostępne w utrzymywanych przez społeczność pakietach Asp.Versioning (następcy Microsoft.AspNetCore.Mvc.Versioning).

dotnet add package Asp.Versioning.Mvc
dotnet add package Asp.Versioning.Mvc.ApiExplorer

AddApiVersioning

Wersjonowanie rejestruje się za pomocą AddApiVersioning. Opcje określają wersję domyślną oraz sposób obsługi brakujących wersji.

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
});

ReportApiVersions

ReportApiVersions = true dodaje nagłówki odpowiedzi api-supported-versions i api-deprecated-versions, dzięki czemu klienci mogą wykryć dostępne wersje.

// Response headers:
// api-supported-versions: 1.0, 2.0
// api-deprecated-versions: 1.0

Wybór czytnika wersji

ApiVersionReader decyduje, skąd odczytywana jest wersja. UrlSegmentApiVersionReader odczytuje ją ze ścieżki trasy.

options.ApiVersionReader = new UrlSegmentApiVersionReader();

Łączenie czytników

Wersję można akceptować jednocześnie z kilku miejsc za pomocą ApiVersionReader.Combine.

options.ApiVersionReader = ApiVersionReader.Combine(
    new UrlSegmentApiVersionReader(),
    new HeaderApiVersionReader("X-Api-Version"),
    new QueryStringApiVersionReader("api-version"));

Dodawanie API Explorer

Należy dodać AddApiExplorer, aby wersjonowanie integrowało się z OpenAPI. Ciąg formatujący określa wygląd nazw grup wersji.

builder.Services
    .AddApiVersioning(options => { /* ... */ })
    .AddApiExplorer(options =>
    {
        options.GroupNameFormat = "'v'VVV";
        options.SubstituteApiVersionInUrl = true;
    });

Wersjonowanie kontrolera

Kontroler należy oznaczyć atrybutem [ApiVersion], a w szablonie trasy umieścić symbol zastępczy wersji.

[ApiVersion(1.0)]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok(new { version = "1.0" });
}

Druga wersja

Oddzielny kontroler obsługuje wersję v2 w tym samym szablonie trasy. Segment {version:apiVersion} kieruje żądania do właściwego kontrolera.

[ApiVersion(2.0)]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() =>
        Ok(new { version = "2.0", extra = true });
}

Wiele wersji w jednym kontrolerze

Pojedynczy kontroler może obsługiwać kilka wersji, mapując poszczególne akcje za pomocą [MapToApiVersion].

[ApiVersion(1.0)]
[ApiVersion(2.0)]
[Route("api/v{version:apiVersion}/orders")]
public class OrdersController : ControllerBase
{
    [HttpGet, MapToApiVersion(1.0)]
    public IActionResult GetV1() => Ok("v1");

    [HttpGet, MapToApiVersion(2.0)]
    public IActionResult GetV2() => Ok("v2");
}

Wycofywanie wersji

Wersję można oznaczyć jako wycofywaną, aby poinformować o zakończeniu jej wsparcia, jednocześnie zachowując jej działanie.

[ApiVersion(1.0, Deprecated = true)]
[ApiVersion(2.0)]
[Route("api/v{version:apiVersion}/products")]
public class ProductsController : ControllerBase { }

Wersjonowanie Minimal APIs

Minimal APIs korzystają z zestawu wersji utworzonego za pomocą NewApiVersionSet, a następnie przypisują wersje do poszczególnych endpointów.

var versionSet = app.NewApiVersionSet()
    .HasApiVersion(new ApiVersion(1, 0))
    .HasApiVersion(new ApiVersion(2, 0))
    .Build();

app.MapGet("/api/v{version:apiVersion}/ping", () => "pong")
   .WithApiVersionSet(versionSet)
   .MapToApiVersion(2.0);

Szybkie sprawdzenie

Należy upewnić się, do czego służy AddApiExplorer.

Podsumowanie

Skonfigurowano Asp.Versioning:

AddApiVersioning ustawia domyślną wersję i raportowanie.
ApiVersionReader.Combine odczytuje wersje z adresu URL, nagłówka lub parametrów zapytania.
[ApiVersion] i {version:apiVersion} kierują żądania, a [MapToApiVersion] wskazuje konkretne akcje.
Minimal APIs korzystają z zestawu wersji.

Następnie: generowanie dokumentów OpenAPI.

Często zadawane pytania

Czy lekcja „Konfigurowanie Asp.Versioning” jest bezpłatna?

Tak — pełny tekst „Konfigurowanie Asp.Versioning” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu C# Academy, przejdź na CoddyKit PRO. Kurs C# Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Konfigurowanie Asp.Versioning”?

Skonfiguruj wersjonowanie w ASP.NET Core. Ćwiczysz C# Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć C# Academy?

Nie wymagamy żadnego doświadczenia. C# Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 2 z 4.

Ile czasu zajmuje lekcja „Konfigurowanie Asp.Versioning”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji C# Academy?

Tak. Każda lekcja C# Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

← Powrót do C# Academy