القائمة
Use when adding API versioning or managing multiple API versions in a .NET project.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when designing gRPC services, proto files, or adding gRPC-Web or JSON transcoding.
Use when writing async code, propagating CancellationTokens, or fixing async/await pitfalls.
Use when applying or enforcing C# coding style — namespaces, sealed classes, var usage, XML docs.
Use when applying modern C# idioms — records, pattern matching, primary constructors, collection expressions.
Use when registering services, choosing lifetimes, or implementing DI patterns like decorator or keyed services.
Use when selecting or implementing design patterns in C# — factory, builder, strategy, decorator, or mediator.
| name | versioning |
| description | Use when adding API versioning or managing multiple API versions in a .NET project. |
| metadata | {"category":"api","agent":"api-designer"} |
| when_to_use | When configuring API versioning strategies or sunset policies |
/api/v1/orders) is the most common and recommended// Program.cs
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
options.ApiVersionReader = new UrlSegmentApiVersionReader();
})
.AddApiExplorer(options =>
{
options.GroupNameFormat = "'v'VVV";
options.SubstituteApiVersionInUrl = true;
});
[ApiController]
[Route("api/v{version:apiVersion}/orders")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public sealed class OrdersController(ISender sender) : ControllerBase
{
[HttpGet]
[MapToApiVersion("1.0")]
public async Task<ActionResult<List<OrderV1Response>>> GetOrdersV1(
CancellationToken ct)
{
var result = await sender.Send(new ListOrdersV1Query(), ct);
return Ok(result);
}
[HttpGet]
[MapToApiVersion("2.0")]
public async Task<ActionResult<PagedList<OrderV2Response>>> GetOrdersV2(
[FromQuery] OrderFilter filter, CancellationToken ct)
{
var result = await sender.Send(new ListOrdersV2Query(filter), ct);
return Ok(result);
}
}
// Or separate controllers per version
[ApiController]
[Route("api/v{version:apiVersion}/orders")]
[ApiVersion("1.0", Deprecated = true)]
public sealed class OrdersV1Controller : ControllerBase { }
[ApiController]
[Route("api/v{version:apiVersion}/orders")]
[ApiVersion("2.0")]
public sealed class OrdersV2Controller : ControllerBase { }
var versionSet = app.NewApiVersionSet()
.HasApiVersion(new ApiVersion(1, 0))
.HasApiVersion(new ApiVersion(2, 0))
.ReportApiVersions()
.Build();
var v1 = app.MapGroup("/api/v{version:apiVersion}")
.WithApiVersionSet(versionSet);
v1.MapGet("/orders", GetOrdersV1)
.MapToApiVersion(new ApiVersion(1, 0));
v1.MapGet("/orders", GetOrdersV2)
.MapToApiVersion(new ApiVersion(2, 0));
builder.Services.AddApiVersioning(options =>
{
options.ApiVersionReader = new HeaderApiVersionReader("X-Api-Version");
});
// Client sends: X-Api-Version: 2.0
builder.Services.AddApiVersioning(options =>
{
options.ApiVersionReader = new QueryStringApiVersionReader("api-version");
});
// Client requests: /api/orders?api-version=2.0
builder.Services.AddApiVersioning(options =>
{
options.ApiVersionReader = ApiVersionReader.Combine(
new UrlSegmentApiVersionReader(),
new HeaderApiVersionReader("X-Api-Version"),
new QueryStringApiVersionReader("api-version"));
});
builder.Services.AddApiVersioning(options =>
{
options.Policies.Sunset(1.0)
.Effective(new DateTimeOffset(2025, 6, 1, 0, 0, 0, TimeSpan.Zero))
.Link("https://docs.{Company}.com/api/migration-guide")
.Title("v1 to v2 Migration Guide")
.Type("text/html");
});
// Response header: Sunset: Sat, 01 Jun 2025 00:00:00 GMT
// Response header: Link: <https://docs.{Company}.com/api/migration-guide>; ...
builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");
// Each document at /openapi/v1.json and /openapi/v2.json
app.MapOpenApi();
Asp.Versioning package reference in .csprojAddApiVersioning in Program.cs[ApiVersion] attributes on controllersv{version:apiVersion} in route templatesAsp.Versioning.Http (minimal API) or Asp.Versioning.Mvc.ApiExplorer (controllers)AddApiVersioning with default version and reader[ApiVersion] to existing controllers (start with "1.0")| Strategy | Pros | Cons | Use When |
|---|---|---|---|
| URL segment | Visible, cacheable, simple | Version in URL | Default choice |
| Header | Clean URLs | Hidden, harder to test | Internal APIs |
| Query string | Easy to add | Pollutes query params | Legacy compat |