Comments (7)
This is intentional and by design. The new approach was outlined in the roadmap 2 years ago. The full gambit is:
services.AddApiVersioning() // Core API Versioning services with support for Minimal APIs
.AddMvc() // API version-aware extensions for MVC Core
.AddApiExplorer() // API version-aware API Explorer extensions
.AddOData() // API versioning extensions for OData
.AddODataApiExplorer(); // API version-aware API Explorer extensions for OData
Existing users have been thrown off a bit because AddMvc
wasn't necessary in the past, but that's because Minimal APIs didn't exist nor were supported.
Only some DI extensions are directly chainable. As you've even shown above, IServiceCollection.AddMvc
doesn't return IServiceCollection
, it returns IMvcBuilder
. AddMvcCore
returns IMvcCoreBuilder
. IApiVersioningBuilder
works in a similar fashion. All of these builders provide IServiceCollection Services { get; }
.
If you wanted to make one big chain, you still can with:
builder.Services.AddApiVersioning().AddMvc().Services.AddSwaggerGen();
There were several motivations behind this change:
- Remove temporal registration issues; for example: calling
services.AddVersionedApiExplorer()
beforeservices.AddApiVersioning()
- Use simpler names:
services.AddApiVersioning().AddApiExplorer()
vsservices.AddVersionedApiExplorer()
- Centralize all things related to API Versioning against the
IApiVersioningBuilder
- Enable extenders to hook into the builder pipeline with their own customizations and services
In addition to the roadmap, this information has been conveyed in:
- Release notes
- The wiki
- All example projects
I've gone to great lengths to try and make it concise, but still obvious. There are only two scenarios that seem to consistently hang people up:
- Forgetting to call
IApiVersioningBuilder.AddMvc
with controllers, which I don't have a better solution for - Thinking that
.AddMvc
adds the full MVC stack versus MVC Core (which is silly for APIs so I thought it was obvious; in hindsight perhapsAddMvcCore
would have been better)
The convention for adding services, even via a builder, is with the AddXXX
prefix. You can see that even IApiVersioningBuilder.AddApiExplorer has to call through to IServicesCollection.AddMvcCore → IMvcCoreBuilder →
IMvcCoreBuilder.AddApiExplorer.
At this point, I'm not really inclined to change things. There hasn't been an outcry from the community. I'm still willing to entertain the idea however. I will leave the issue open and if there is a significant upvote, I'll consider it. Aliases are nice, but they also have the risk of causing confusion and changing them will result in a breaking change - at some point (there's no point in having both - forever).
from aspnet-api-versioning.
Yep, I get the surprise and there was no great way to fully advertise that. Behavioral changes always concern me the most because they are the least obvious and hardest to find. Unfortunately, they aren't always fully avoidable.
It's been 2+ years, so I could update the announcement banner to reflect a migration notice and like to the appropriate wiki topic instead of just an announcement. Would that have - perhaps - made things slightly more obvious? That's pretty quick and easy change.
from aspnet-api-versioning.
I guess so.
But you know the curse of knowledge. :-) It's always hard to predict how those who are unaware can be surprised:-)
from aspnet-api-versioning.
Then I'd propose to emphasize in wiki and examples that these methods are not the standard one from the framework.
from aspnet-api-versioning.
In the wiki, there is already the text:
.AddMvc(); // ← brings in MVC Core; unnecessary for Minimal APIs
There's even an entire page dedicated to migration that convers all of the changes that came in 6.0
that should help people moving from Microsoft.AspNetCore.Mvc.Versioning
to Asp.Versioning.Mvc
.
Perhaps more text in the examples. The examples are setup to boil things down to just the bare minimum API Versioning configuration with comments and options highlighted for the common knobs that someone might want to turn. The example itself is kind of the documentation. IMHO, it should be obvious that everything shown is working and required. Turning a knob is one thing, but removing a knob, such as removing the call to .AddMvc()
, should be expected to break things.
The simplified setup for WebApplication
removes the necessity for AddMvcCore
and AddMvc
. That should also be a signal that it's different. It would probably be more obvious if they were still side-by-side:
builder.Services.AddMvcCore();
builder.Services.AddApiVersioning().AddMvc();
This is actually the case with OData, which requires:
builder.Services.AddOData();
builder.Services.AddApiVersioning().AddAddOData();
from aspnet-api-versioning.
Let me explain how it was for me.
The last time I used your package was before minimal APIs.
For minimal APIs to work you also do not need to call standard AddMvc()
or AddMvcCore()
. So when I read that comment, my thought was: "Thank you, I know." 😂
My code was:
services.AddMvc().AddApplicationPart(...);
Then I added versioning:
services.AddMvc().AddApplicationPart(...);
services.AddApiVersioning();
MVC added? Check.
Versioning added? Check.
;-)
from aspnet-api-versioning.
POLA is part of every decision. Unfortunately, it's just not always easy to advertise changes.
from aspnet-api-versioning.
Related Issues (20)
- ASP.NET Web API versioning Migrate from QueryStringApiVersionReader to UrlSegmentApiVersionReader HOT 2
- only the 5.1.0 version of Microsoft.AspNetCore.Mvc.Versioning is deprecated HOT 3
- Problem with describing reponse codes in minimal api HOT 3
- Cannot run APIs with different controller names with same ControllerName attribute after migration HOT 6
- Different options in `ApiVersioningOptions.cs` between .NET Framework and .NET Core packages HOT 2
- WithOpenApi() ignore Api versioning readers HOT 4
- .net 8 support HOT 7
- Breaking changes when migrating to OData8 + new versioning HOT 10
- odata/$metadata returns 404 when all controllers are decorated with ApiVersionNeutralAttribute HOT 3
- AddVersionedApiExplorer not working in Asp.Versioning HOT 5
- VersionedApiDescriptionProvider does not set the correct SunsetPolicy to ApiDescription instances HOT 1
- Using ApiExplorerSettingsAttribute together with ApiVersionAttribute produces unexpected number of ApiVersionDescriptions HOT 5
- Asp.Net Core WebApi - AWS ECS Cluster Authentication failure HOT 2
- [Versioned Clients][API Notifications] Fails to read new versions when available HOT 2
- Swashbuckle documentation inconsistent with examples HOT 2
- AssumeDefaultVersionWhenUnspecified does not work correctly if ApiVersionNeutral is used in the controller HOT 2
- swagger.json file not found after update HOT 9
- My API is not displaying all the versions. HOT 4
- Improve docs for HeaderApiVersionReader
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from aspnet-api-versioning.