swagger-codegen contains a template-driven engine to generate documentation, API clients and server stubs in different languages by parsing your OpenAPI / Swagger definition.
PR #4955 added support for .NET Standard 1.3 as targetFramework=v5.0. This version refers to the PCL Version. This is unintuitive for a number of reasons. First, dnx core 5.0 was a version of .NET Core which coincided with .NET Framework 4.5.1. Second, the targetFramework is meant to refer to .NET Standard 1.3, which supports more than just the latest and greatest. Lastly (for me, at least), there's no clear indication that .NET Framework won't have an actual future version of 5.0.
Swagger-codegen version
current master
Swagger declaration file content or url
Command line used for generation
Steps to reproduce
Related issues
Suggest a Fix
I like the suggestion @Gronsak made in his PR. Referring to the .NET Standard table:
Might I suggest reworking how the target framework is selected by adding a level of abstraction?
Instead of setting the target framework property directly a better option may be to have a property for choosing what kind of project you would like to output and a separete one for choosing the VS version targeted.
I would suggest going with the same alias as Microsoft defines here: .NET Standard Library
Platform Name
Alias
.NET Standard
netstandard
1.0
1.1
1.2
1.3
1.4
1.5
1.6
2.0
.NET Core
netcoreapp
→
→
→
→
→
→
1.0
2.0
.NET Framework
net
→
4.5
4.5.1
4.6
4.6.1
4.6.2
vNext
4.6.1
Mono/Xamarin Platforms
→
→
→
→
→
→
→
vNext
Universal Windows Platform
uap
→
→
→
→
10.0
→
→
vNext
Windows
win
→
8.0
8.1
Windows Phone
wpa
→
→
8.1
Windows Phone Silverlight
wp
8.0
> That would mean that to generate what is now defined as targetFramework: v3.5 you would instead input net3.5 and to make a net standard 1.3 project you would put in netstandard1.3.
You could then put in all the right values in targetFramework and targetFrameworkNuget for the targeted version of the project file.
Since I apparently forgot to do so back in May I just thought I'd say that I don't really have anything to add to my previous suggestion, abstracting stuff really seems like the best option to deal with Microsoft's shenanigans.
It also gives us an easy way of supporting different versions of Visual Studio project/solution files when necessary.
Indeed the current naming of the code generators is really confusing. It took me quite a while to figure out which version I needed.
csharp-dotnet2 generates actually C# code for .NET Core v2.0. Note that the the product is named .NET Core and is currently at version 2.0 and that v2.1 is in preview. Putting the 2 in the code generators name really makes no sense.
It makes much more sense for a .NET developer to name that generator csharp-dotnet-core or even better csharp-dotnet-std and to add a targetStandard option with v2.0 as current version. This way the .NET Core code generator should be (or become) .NET Standard 2.0 compatible.
Please noted that the good old csharp generator targets the .NET Framework up till v4.5. As @jimschubert mentioned .Net Framework v5.0 doesn't exist. It was the working version for what would become .NET Core. I guess the v5.0 option generates .NET Core 1.x compatible code, but I could understand it wrong. So it makes sense if that would be added to the new generator with the right targetStandard version.
I know that the various .NET naming can be very confusing in itself. Framework, Core, Standard are all different things. But please follow those naming and don't add none existing.
Very short summary:
Framework is the old Windows targeted .NET (till v4.7). Is not going away.
Also noted that C# 2 (what I see in various issues) actually refers to v2.0 of the C# language and in itself is not related to the .NET Framework or .NET Core. The current version of the C# compiler (roslyn) is at v7.2
The reason one generator is csharp-dotnet2 is because this is ".NET Framework 2.0". Microsoft's naming decisions and now the confusingly similar .NET Core 2.x are difficult to adjust to because renaming generators is a major breaking change.
To make matters worse, that value is meant to refer to the language. In all of these cases, that's csharp. We now also include other generator types (client, server, docs), and at some point there was a decision to encode generator type into the cli's "language" option.
To support the many levels required by Microsoft's versioning, we would need multiple levels of shared templates (version, Framework, generator type, platform, .net standard support, etc.) Much of this stuff from .NET 3.x to 4.x is relatively similar.
I think it's probably a good idea to create a separate .NET Core generator. There will be redundant templates, but I think it would remove some confusion.
Also, the version 5 option is PCL 5.0, and doesn't really have anything to do with the other options. I'm not even entirely sure it generates a truly PCL compatible project file, and I'd have to track down the original implementor of that addition to understand the use case.
The reason one generator is csharp-dotnet2 is because this is ".NET Framework 2.0".
See the confusion ;-)
Microsoft's naming decisions and now the confusingly similar .NET Core 2.x are difficult to adjust to because renaming generators is a major breaking change.
As I see it, it is all about naming the current csharp implementation (that works quite well).
But maybe just adding an extra option to the config.json named targetStandard will just do the trick. It should be either targetStandard or targetFramework, never both. And when people use the targetFramework = v5.0 interpret it as targetStandard = 1.3 and show a large deprecation warning.
Also, the version 5 option is PCL 5.0, and doesn't really have anything to do with the other options.
That would speak in favor of the targetStandard option
I'm not even entirely sure it generates a truly PCL compatible project file
I have disabled generating the .csproj file, because it doesn't work in my .Net Core 2 program, just like I don't use the generated .sln file.
PS. Unfortunately I don't "speak" Java, so I can't really contribute.
Starting with a .NET Standard / .NET Core 2.1 project with Swagger Codegen, I also got confused with the dotnet2: I figured out quickly it was .NET Framework 2 and not .NET Core 2 as I initially hoped.
The current aspnetcore generates the server stub for .NET Core 2.0, while csharp generates the .NET Framework 4.5 client.
It will makes more sense to generate indeed .NET Standard 2.x code for both server AND client:
Put most code (e.g. from client and model namespaces) into this .NET Std lib
let only the api and controllers namespace in either .NET Core 2.1 or .NET Framework 4.6.1 calling project (looking as recent Microsoft announcement, it seems the future is .NET Core only anyway).
update dependencies with newest nuget package.
It is necessary to maintain an aspnetcore 1.x code generation?
It may be wise to have a look at Microsoft Support policy:
https://www.microsoft.com/net/platform/support-policy
.NET Core 1.x will get out of support in mid 2019, 2.0 is out already!
Thus, all new development should be targeting .NET Core 2.1 which is at least supported until August 2021 (LTS).
And the last announcements from Microsoft regarding .NET Framework 4.8 and .NET Core 3.0 clearly emphasized the .NET Framework remains stable and all new effort will be put in .NET Core only.
Any updated thoughts on this @jimschubert ? At this stage, should be .NET Standard 2.0 - and with .NET 5 around the corner I think the recommended approach for widely used libraries is multi-targeting for both .NET Standard 2.0 and .NET 5
Supporting .NET Standard 2.0 gives you the most reach while supporting .NET 5 ensures you can leverage the latest platform features
Description
PR #4955 added support for .NET Standard 1.3 as
targetFramework=v5.0. This version refers to the PCL Version. This is unintuitive for a number of reasons. First, dnx core 5.0 was a version of .NET Core which coincided with .NET Framework 4.5.1. Second, the targetFramework is meant to refer to .NET Standard 1.3, which supports more than just the latest and greatest. Lastly (for me, at least), there's no clear indication that .NET Framework won't have an actual future version of 5.0.Swagger-codegen version
current master
Swagger declaration file content or url
Command line used for generation
Steps to reproduce
Related issues
Suggest a Fix
I like the suggestion @Gronsak made in his PR. Referring to the .NET Standard table:
Might I suggest reworking how the target framework is selected by adding a level of abstraction?
Instead of setting the target framework property directly a better option may be to have a property for choosing what kind of project you would like to output and a separete one for choosing the VS version targeted.
I would suggest going with the same alias as Microsoft defines here: .NET Standard Library
Since I apparently forgot to do so back in May I just thought I'd say that I don't really have anything to add to my previous suggestion, abstracting stuff really seems like the best option to deal with Microsoft's shenanigans. It also gives us an easy way of supporting different versions of Visual Studio project/solution files when necessary.
Indeed the current naming of the code generators is really confusing. It took me quite a while to figure out which version I needed.
csharp-dotnet2generates actuallyC# code for .NET Core v2.0. Note that the the product is named.NET Coreand is currently at version2.0and that v2.1 is in preview. Putting the2in the code generators name really makes no sense.It makes much more sense for a .NET developer to name that generator
csharp-dotnet-coreor even bettercsharp-dotnet-stdand to add atargetStandardoption withv2.0as current version. This way the .NET Core code generator should be (or become) .NET Standard 2.0 compatible.Please noted that the good old
csharpgenerator targets the .NET Framework up till v4.5. As @jimschubert mentioned .Net Framework v5.0 doesn't exist. It was the working version for what would become .NET Core. I guess thev5.0option generates .NET Core 1.x compatible code, but I could understand it wrong. So it makes sense if that would be added to the new generator with the righttargetStandardversion.I know that the various .NET naming can be very confusing in itself. Framework, Core, Standard are all different things. But please follow those naming and don't add none existing.
Very short summary:
Also noted that C# 2 (what I see in various issues) actually refers to v2.0 of the C# language and in itself is not related to the .NET Framework or .NET Core. The current version of the C# compiler (roslyn) is at v7.2
@ffes That's some good feedback.
The reason one generator is
csharp-dotnet2is because this is ".NET Framework 2.0". Microsoft's naming decisions and now the confusingly similar .NET Core 2.x are difficult to adjust to because renaming generators is a major breaking change.To make matters worse, that value is meant to refer to the language. In all of these cases, that's
csharp. We now also include other generator types (client, server, docs), and at some point there was a decision to encode generator type into the cli's "language" option.To support the many levels required by Microsoft's versioning, we would need multiple levels of shared templates (version, Framework, generator type, platform, .net standard support, etc.) Much of this stuff from .NET 3.x to 4.x is relatively similar.
I think it's probably a good idea to create a separate .NET Core generator. There will be redundant templates, but I think it would remove some confusion.
Also, the version 5 option is PCL 5.0, and doesn't really have anything to do with the other options. I'm not even entirely sure it generates a truly PCL compatible project file, and I'd have to track down the original implementor of that addition to understand the use case.
See the confusion ;-)
As I see it, it is all about naming the current
csharpimplementation (that works quite well).But maybe just adding an extra option to the
config.jsonnamedtargetStandardwill just do the trick. It should be eithertargetStandardortargetFramework, never both. And when people use thetargetFramework = v5.0interpret it astargetStandard = 1.3and show a large deprecation warning.That would speak in favor of the
targetStandardoptionI have disabled generating the .csproj file, because it doesn't work in my .Net Core 2 program, just like I don't use the generated .sln file.
PS. Unfortunately I don't "speak" Java, so I can't really contribute.
Starting with a .NET Standard / .NET Core 2.1 project with Swagger Codegen, I also got confused with the dotnet2: I figured out quickly it was .NET Framework 2 and not .NET Core 2 as I initially hoped.
The current aspnetcore generates the server stub for .NET Core 2.0, while csharp generates the .NET Framework 4.5 client. It will makes more sense to generate indeed .NET Standard 2.x code for both server AND client:
It is necessary to maintain an aspnetcore 1.x code generation? It may be wise to have a look at Microsoft Support policy: https://www.microsoft.com/net/platform/support-policy .NET Core 1.x will get out of support in mid 2019, 2.0 is out already! Thus, all new development should be targeting .NET Core 2.1 which is at least supported until August 2021 (LTS). And the last announcements from Microsoft regarding .NET Framework 4.8 and .NET Core 3.0 clearly emphasized the .NET Framework remains stable and all new effort will be put in .NET Core only.
Any updated thoughts on this @jimschubert ? At this stage, should be .NET Standard 2.0 - and with .NET 5 around the corner I think the recommended approach for widely used libraries is multi-targeting for both .NET Standard 2.0 and .NET 5
Supporting .NET Standard 2.0 gives you the most reach while supporting .NET 5 ensures you can leverage the latest platform features