C# Academy · Lektion

Asp.Versioning konfigurieren

Richten Sie die Versionierung in ASP.NET Core ein.

Asp.Versioning konfigurieren ist eine kostenlose C# Academy-Lektion auf CoddyKit. Dies ist Lektion 2 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des C# Academy-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der C# Academy-Kurs umfasst insgesamt 4 Lektionen.

Das Asp.Versioning-Paket

Die API-Versionierung für ASP.NET Core ist in den von der Community gepflegten Asp.Versioning-Paketen enthalten (dem Nachfolger von Microsoft.AspNetCore.Mvc.Versioning).

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

AddApiVersioning

Registrieren Sie die Versionierung mit AddApiVersioning. Die Optionen steuern die Standardversion und den Umgang mit fehlenden Versionen.

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

ReportApiVersions

ReportApiVersions = true fügt den Antwort-Header api-supported-versions und api-deprecated-versions hinzu, damit Clients verfügbare Versionen erkennen können.

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

Den Version Reader auswählen

ApiVersionReader legt fest, aus welcher Quelle die Version gelesen wird. UrlSegmentApiVersionReader liest sie aus dem Routenpfad.

options.ApiVersionReader = new UrlSegmentApiVersionReader();

Reader kombinieren

Akzeptieren Sie die Version gleichzeitig aus mehreren Quellen mit ApiVersionReader.Combine.

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

API Explorer hinzufügen

Fügen Sie AddApiExplorer in die Aufrufkette ein, damit die Versionierung in OpenAPI integriert wird. Die Formatzeichenfolge steuert, wie die Namen der Versionsgruppen aussehen.

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

Einen Controller versionieren

Versehen Sie einen Controller mit [ApiVersion] und fügen Sie den Versionsplatzhalter in die Routenvorlage ein.

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

Eine zweite Version

Ein separater Controller stellt v2 über dieselbe Routenvorlage bereit. Das Segment {version:apiVersion} leitet Anfragen an den richtigen Controller weiter.

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

Mehrere Versionen auf einem Controller

Ein einzelner Controller kann mehrere Versionen bereitstellen, indem einzelne Aktionen mit [MapToApiVersion] zugeordnet werden.

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

Eine Version als veraltet markieren

Markieren Sie eine Version als veraltet, um auf ihr Auslaufdatum hinzuweisen, während sie weiterhin funktioniert.

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

Minimale APIs versionieren

Minimale APIs verwenden einen Versionssatz, der mit NewApiVersionSet erstellt wird. Anschließend weisen Sie den Endpunkten Versionen zu.

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

Kurzprüfung

Bestätigen Sie, wofür AddApiExplorer verwendet wird.

Zusammenfassung

Sie haben Asp.Versioning konfiguriert:

AddApiVersioning legt die Standardversion und die Berichterstellung fest.
ApiVersionReader.Combine liest Versionen aus URL, Header oder Abfrageparameter.
[ApiVersion] und {version:apiVersion} leiten Anfragen weiter; [MapToApiVersion] ordnet Aktionen bestimmten Versionen zu.
Minimale APIs verwenden einen Versionssatz.

Als Nächstes: OpenAPI-Dokumente generieren.

Häufig gestellte Fragen

Ist die Lektion „Asp.Versioning konfigurieren“ kostenlos?

Ja — der vollständige Text von „Asp.Versioning konfigurieren“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des C# Academy-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der C# Academy-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Asp.Versioning konfigurieren“?

Richten Sie die Versionierung in ASP.NET Core ein. Du übst C# Academy mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um C# Academy zu starten?

Keine Vorkenntnisse erforderlich. C# Academy auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 2 von 4.

Wie lange dauert die Lektion „Asp.Versioning konfigurieren“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser C# Academy-Lektion Code schreiben und ausführen?

Ja. Jede C# Academy-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

← Zurück zu C# Academy