6.0.0 Preview 1 #811
Replies: 9 comments 35 replies
-
|
Changelog has incorrect url :) Same for other url, like examples link |
Beta Was this translation helpful? Give feedback.
-
|
Thank you for pointing that out. This is the first time I'm using a discussion with a release. Apparently, GitHub just copies the entire markdown, verbatim, to the discussion. I had checked the links before posting the release. The relative links are different from the discussion than the release. Good to know for the future. I have fixed the links here. They should work now. |
Beta Was this translation helpful? Give feedback.
-
|
I'm curious about this change:
Can someone elaborate on the history behind this? Is this now not a Microsoft project/product anymore? |
Beta Was this translation helpful? Give feedback.
-
Beta Was this translation helpful? Give feedback.
-
|
TL;DR. The short, short version. This project isn't nor ever was run by the ASP.NET team. The "Microsoft" here was me and I'm no longer at Microsoft. There has never been a team; it's just me. Ultimately, the powers that be decided it was best to transfer the project out of the If it was purely lift and shift or I could have gotten this work done earlier (say 18 months ago), then the package identifiers and namespaces could have remained. I fought hard to get ownership of the existing packages so that I can service them for the community (it took months). When I thought it wouldn't happen and I started considering new features and new packages, using new namespaces seemed to be the direction to go. I think it would have been very confusing to mix and match package names or namespaces. I even considered starting over in a new repo, but think that would be equally confusing. I know there will be some pain during this transition. I've felt the pain as much as anyone. I could have washed my hands of it and walked away, but love the community that has been built around the project. Any fundamental changes to naming, packages, and branding should happen now so it never happens again. Even using
|
Beta Was this translation helpful? Give feedback.
-
|
The clarifications are much appreciated @Lonli-Lokli and @commonsensesoftware . I'm glad you decided to keep pushing this one @commonsensesoftware since I imagine it could've very easily died instead. |
Beta Was this translation helpful? Give feedback.
-
|
I've tried to integrate it with my project
|
Beta Was this translation helpful? Give feedback.
-
|
@Lonli-Lokli, you did the correct thing. For the API Explorer with Minimal APIs you have the correct package. It's honestly kind of strange because Minimal APIs only require Microsoft.AspNetCore.Routing, but any use of the API Explorer requires Microsoft.AspNetCore.Mvc.Core and Microsoft.AspNetCore.Mvc.ApiExplorer. It's of little consequence to consumers, but it is kind of weird (IMO) for library authors trying to keep their dependencies clean. The new setup is
I understand the importance of api.MapGet("/weatherforecast", (int id) => new WeatherForecast())
.Produces(response => response.Body<WeatherForecast>())
.HasApiVersion(1.0);I'm not one to just make you figure it out. I've added a new Minimal OpenAPI Example that shows how to put everything together. This should have parity with the existing OpenAPI Example. All of these changes are available in Preview 2, which you can pick up from Asp.Versioning.Mvc.ApiExplorer/6.0.0-preview.2. Give that a try and let me know if there are any issues or remaining gaps. |
Beta Was this translation helpful? Give feedback.
-
|
Just in case somebody will need it, native support for IFormFile/IFormFileCollection binding in minimal API will be available only in .net 7 (dotnet/aspnetcore#34303) but adding unused IFormFile to minimal API request will add this parameter to Swagger |
Beta Was this translation helpful? Give feedback.
-
|
@Lonli-Lokli and @julealgon, I accept your challenge (to show it in OpenAPI). 😉 I will try to put together a working example to share this week. I'll probably eventually throw it into official set of examples. I've used this approach many times, just not with OpenAPI. It'd be nice to get it into official MS docs. Let's start with a working example and work backward. |
Beta Was this translation helpful? Give feedback.
-
|
Ok, the following is a working example. It is pretty unnatural for it work with regular 'ol controller actions. Making it work with Minimal APIs isn't horrible, but it doesn't work the way that it should IMHO. It is a PITA to make it work with Swashbuckle, but it can be done. It's not 100% clear if Swashbuckle is unable to do the right thing because the core API Explorer doesn't provide the correct metadata or whether Swashbuckle simply doesn't do the right thing. OpenAPI (and hence Swagger) most definitely support plain 'ol file uploads as noted in the spec. It also supports multiple file uploads as noted here; specifically, Minimal APIapp.MapPost(
"/api/orders/import",
async (
HttpRequest request,
[FromHeader( Name = "Content-Disposition" )] string contentDisposition,
CancellationToken cancellationToken ) =>
{
var source = request.Body;
var name = GetFileName( contentDisposition );
var userProfile = Environment.GetFolderPath( Environment.SpecialFolder.UserProfile );
var path = Path.Combine( userProfile, "Downloads", name.ToString() );
using var destination = new FileStream( path, FileMode.Create );
await source.CopyToAsync( destination, cancellationToken );
await destination.FlushAsync( cancellationToken );
var scheme = request.Scheme;
var host = request.Host;
var location = new Uri( $"{scheme}{Uri.SchemeDelimiter}{host}/api/orders/42" );
return Results.Created( location, default );
static string GetFileName( string header )
{
if ( !ContentDispositionHeaderValue.TryParse( header, out var contentDisposition ) )
{
return Guid.NewGuid().ToString( "n" ) + ".pdf";
}
var name = contentDisposition.FileName.HasValue ?
contentDisposition.FileName.Value :
( contentDisposition.Name.HasValue ?
contentDisposition.Name.Value :
Guid.NewGuid().ToString( "n" ) );
if ( !name.EndsWith( ".pdf", StringComparison.OrdinalIgnoreCase ) )
{
name += ".pdf";
}
return name;
}
} )
.Accepts<Stream>( "application/pdf" )
.Produces( 201 );OpenAPI Integration with SwashbuckleThis will fix-up file upload APIs so that the Swagger UI will show a file picker. sealed class FileFilter : IOperationFilter
{
public void Apply( OpenApiOperation operation, OperationFilterContext context )
{
if ( operation.RequestBody is OpenApiRequestBody body &&
context.ApiDescription.HttpMethod is string httpMethod &&
( httpMethod == "POST" || httpMethod == "PUT" || httpMethod == "PATCH" ) )
{
var consumes = context.ApiDescription.SupportedRequestFormats;
var keys = consumes.Count == 0 ?
body.Content.Keys.ToArray() :
consumes.Where( c => c.Formatter is null ).Select( c => c.MediaType ).ToArray();
for ( var i = 0; i < keys.Length; i++ )
{
var key = keys[i];
body.Required = true;
body.Content.Remove( key );
body.Content.Add( key, new() { Schema = new() { Type = "string", Format = "binary" } } );
}
}
}
}This will set things up the way you'd expect:
I'm going to file an issue with the ASP.NET team. |
Beta Was this translation helpful? Give feedback.
-
|
Your reply reminded me of how poor .NET's "support" for multipart requests currently is @commonsensesoftware . I had a requirement to "upload a file in one part and post a json in another" and this is basically unsupported.... I wish there was native content-negotiation support with multipart requests in ASPNET... would make things so much more intuitive. |
Beta Was this translation helpful? Give feedback.
-
|
It certainly leaves something to be desired. The fact that there is any support for it all is a relief; otherwise, it would probably be TH;DT (Too Hard; Didn't Try). It is definitely possible to achieve your scenario. I have no idea if or how that would manifest in the Swagger UI. I guess each part would allow "one of" types of content? What you cannot do, intrinsically, is use There are likely some other ways this capability can be achieved. Supporting heterogenous payloads in a single request is definitely a use case for |
Beta Was this translation helpful? Give feedback.
-
|
It wasn't really expected, but this sidebar really fanned out into something meaningful. I opened #41426 and it looks like it will actually be addressed in |
Beta Was this translation helpful? Give feedback.
-
|
Is there any way to make OData work with Minimal API, ie without Controllers? With OpenApi as well |
Beta Was this translation helpful? Give feedback.
-
|
To the best of my knowledge, currently - no. I didn't find any open issues on the topic. I don't believe it will be a tremendous amount of work, but there are certain limitations in the design of Minimal APIs that are holding it up. A good example is model binding. Even for API Versioning, you cannot declare I don't expect any, and certainly not significant, changes for the API Explorer for OData. There weren't a huge number of changes to make it work without OData. I would expect that OData support will add a ton more work. I haven't tried it, but mixing vanilla Minimal APIs with OData controllers should work, including for the API Explorer. If you happen to test it out, I'd love to hear your experience. |
Beta Was this translation helpful? Give feedback.
-
|
I think you are right - EnableQuery extending ActionFilterAttribute, which will not work for Minimal API. Does it make sense to open new one, and if yes what is the correct repository for that? |
Beta Was this translation helpful? Give feedback.
-
|
This is where I would start: https://github.com/OData/AspNetCoreOData/issues |
Beta Was this translation helpful? Give feedback.
-
|
Why did you choose instead of |
Beta Was this translation helpful? Give feedback.
-
|
Wow, I like new version. it has much less boilerplate |
Beta Was this translation helpful? Give feedback.
-
|
It's better, but I still don't like that you have to build something external, attach it, and then potentially keep building. The Minimal API builder API only seems to really consider adding metadata to an endpoint. For API Versioning, I feel developers may add one or more pieces of versioning metadata to an endpoint. To that end, extending the intrinsic builders is not very easy. For 6.0, I'm fine with staying in alignment with the confines of what's expected. The |
Beta Was this translation helpful? Give feedback.
-
You could split the arguments into 2 calls using a fluent interface. This allows you to have the compiler infer one part while specifying the other explicitly using generic types for both values. |
Beta Was this translation helpful? Give feedback.
-
|
@julealgon That's basically how it worked. The problem was how do you turn one logical operation into two just for the sake of naming? If the first method isn't called Ultimately, this issue is mute and irrelevant. Preview 3 will see it revert to the intrinsic implementation. 😃 The feedback has been heard and incorporated. |
Beta Was this translation helpful? Give feedback.
-
|
One note that previous implementation was closer to the group in terms of .NET7 - It had an ability to create simplifid approach became |
Beta Was this translation helpful? Give feedback.
-
|
Can you add\rewrite example for OpenApi with C# records? It's not always possible to find the correct way for specifying new way of Required attribute with new typs, so extending example will be a great help NEW: OLD |
Beta Was this translation helpful? Give feedback.
-
|
I'm not wholly opposed this idea, but I try not to go too far off into the weeds for things that aren't specific to API versioning. Many of these variants are subjective and opinionated. OpenAPI, for example, is not a specific objective of API Versioning, but the API Explorer is. The examples simply show how to put all the pieces together in a meaningful way (because, honestly, it's very common). If you're interested in expanding the examples in a PR, I'd be willing to accept it. That doesn't mean that's the only way it will ever be added, but - admittedly - adding this won't be at the top my list. I certainly can appreciate the lack-luster of some of the public examples out there and I try to create examples that represent what people would typically want to do. I have a future task to lift the wiki out into a full website. Including or linking to additional examples is something I'm considering as part of that. |
Beta Was this translation helpful? Give feedback.
-
|
Really great work! Do you have an ETA for 6.0.0 official release? |
Beta Was this translation helpful? Give feedback.
-
|
There's a couple of issues that have been reported that need to flush out, but that won't take long. The main issue/blocker is code signing. I have the issue open with DNF. I'll ping them again today. If I don't gain traction, I'll advertise to the community to light a 🔥 . 😉 |
Beta Was this translation helpful? Give feedback.
-
|
@commonsensesoftware Could you share the latest status of official release? And do you know if there is any known gap between 6.0.0 preview and Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer 5.0.0? |
Beta Was this translation helpful? Give feedback.
-
|
I'm still waiting on code signing. I've been trying to wrap it up through the back and official channels to no avail. I don't know that it will make any difference, but the DNF code signing onboarding task is here. Comments from the community might drive awareness and trigger action, but - honestly - IDK. I can't think of any specific gaps unless you uncovered something. If you see or know of something, please share. 6.0.0 will naturally have more features along with all the other enhancements. The 5.1 release will contain fixes within the previous libraries and packages. |
Beta Was this translation helpful? Give feedback.
-
|
How can I add custom route string for methods? |
Beta Was this translation helpful? Give feedback.
-
|
In my project, there is a nested structure for EDM model. The code works fine with OData 8. The startup configuration is like: The controller is like: How can I make it work with "Asp.Versioning.OData"? |
Beta Was this translation helpful? Give feedback.
-
|
The overall approach for versioning with OData hasn't changed all that much. The fundamentals are the same, but the configuration points are a little different to have parity with the changes to OData itself. API Versioning support for OData encourages, but does not require, you to use The setup should look something like: // OData does NOT (and cannot) support multiple EDMs per route prefix.
// calls to AddRouteComponents here are ignored. Defining the query options
// here are used as a 'template' for all versioned EDMs
services.AddOData(options => options.Expand().Select().Filter().OrderBy().Count().SetMaxTop(10));
services.AddApiVersioning()
.AddOData(options =>
{
// options.ModelBuilderFactory defaults to new ODataConventionModelBuilder().EnableLowerCamelCase()
// default callback instead of IModelConfiguration. this is called with a new ODataModelBuilder created from
// options.ModelBuilderFactory for every API version and registered route prefix
options.ModelBuilder.DefaultModelConfiguration = (builder, apiVersion, routePrefix) =>
{
builder.Singleton<VirtualEndpoint>("virtualEndpoint");
};
options.AddRouteComponents("api/hello/odata");
}); |
Beta Was this translation helpful? Give feedback.
-
|
That works, thank you! @commonsensesoftware |
Beta Was this translation helpful? Give feedback.
-
|
@commonsensesoftware Can I achieve this by using |
Beta Was this translation helpful? Give feedback.
-
|
Sure. public class VirtualEndpointConfiguration : IModelConfiguration
{
public void Apply( ODataModelBuilder builder, ApiVersion apiVersion, string? routePrefix )
{
builder.Singleton<VirtualEndpoint>("virtualEndpoint");
}
}The setup then just becomes: services.AddOData(options => options.Expand().Select().Filter().OrderBy().Count().SetMaxTop(10));
services.AddApiVersioning().AddOData(options => options.AddRouteComponents("api/hello/odata")); |
Beta Was this translation helpful? Give feedback.
-
This is the first preview release, which includes support for .NET 6.0. Be sure to follow the announcement for more background and the roadmap for in-depth review of the release.
The wiki has not been updated, but it's a work in progress. While the wiki has been useful and informative, it is reaching the limits of what is possible. Consideration is being made to lift the current wiki into a fully-fledged documentation website. All of the examples have been updated and include new examples such as Minimal APIs. This is currently the best place to start and review how things have changed.
Features
services.AddHttpClient("test").AddApiVersion(1.0)ILoggerASP.NET Core
Enhancements
All Platforms
Span<T>, noRegex, fewer allocations, etc)ApiVersionand related attributes now allowsdouble(ex:new ApiVersion(1.0),[ApiVersion(1.0)])ApiVersion.Statusnow allows.(ex:2.0-beta.1,2022-04-01-preview.1)ApiVersion.Parseis supplanted byIApiVersionParserviaApiVersionParser.DefaultApiVersionpossible (ex: you can add, parse, and format a patch or revision version component if you really want it)404,405, and415are now properly returned in accordance with configured versioning methods without requiring additional configuration or customizationNamespaceParserNamespaceParser.Defaultfor the same old out-of-the-box implementation.NET 6.0
ApiVersionsupportsISpanFormattableASP.NET Web API
UrlHelper.WithoutApiVersion()extension (useful when generating links from versioned to version-neutral routes)ASP.NET Core
IUrlHelper.WithoutApiVersion()extension (useful when generating links from versioned to version-neutral endpoints)Fixes
All of the open issues that could be fixed, have been fixed in this release. These will listed in the forthcoming 5.1 release, but it includes 65+ issues. I will accept reported issues and backport them to 5.1 if they are applicable.
Breaking Changes
This release is essentially a reset and rewrite so many things will be broken from
5.x. The most obvious issues will be new packages. Here is the mapping of old packages to new packages:The second obvious big change will be different namespaces. All previous
Microsoft.*namespaces are nowAsp.Versioning.*. If you are a library author that targets multiple platforms, this should make things easier going forward; it certainly made it easier in the project itself. Extension methods continue to use the same namespace as the type they correspond to.Significant individual changes:
IApiVersionReader.Readnow returnsIReadOnlyList<string>instead ofstring?IReportApiVersions.Reportnow accepts the entire response instead of just headersIErrorResponseProviderno longer exists; it is supplanted byIProblemDetailsFactoryand Problem Details (RFC 7807)ApiVersionMetadatatype:GetApiVersionModel(ApiVersionMapping) → GetApiVersionMetadata()GetApiVersionModel() → ApiVersionMetadata.Map(ApiVersionMapping.Explicit)MappingTo(ApiVersion) → ApiVersionMetadata.MappingTo(ApiVersion)IsMappedTo(ApiVersion) → ApiVersionMetadata.IsMappedTo(ApiVersion)Routing behavior has changed to more accurately return
404,405, or415when appropriate.400is still returned in known, invalid requests such as an unspecified API version when required.For ASP.NET Core, the setup is now a fluent interface of chained configuration options:
Future Release
The following are features and enhancements still under consideration before the final release:
Feedback
I want to hear your feedback. What do you like? What do you not like? I want to give the community a chance to play with the latest bits and provide any final thoughts before committing to the final release. Now would be the time for any other name changes or other significant refactoring that could cause additional disruption going forward.
Administrative
TL;DR
5.xpatchesThis discussion was created from the release 6.0.0 Preview 1.
Beta Was this translation helpful? Give feedback.
All reactions