Swashbuckle.aspnetcore: CLI compatability issues

[domaindrivendev]

Currently, the CLI tool only targets netcoreapp2.1 and as a result, that version of the framework MUST be installed to run the tool. However, if the tool is updated to target netcoreapp2.1 and netcoreapp3.0, then additional compatibility issues are observed. The problematic combinations and current status are listed below, where "Tool framework" refers to the framework version used to run the tool and "App target context" is the framework (netcoreapp2.1 etc.) and platform (x86, c64 etc.) targetted by the Swashbuckle-enabled application:

Tool framework | App target context | Supported? | Resolution
----------------- | --------------------------- | ------- | -------
netcoreapp2.1 | netcoreapp2.1 | ✔️ |
netcoreapp2.1 | netcoreapp3.0 | ✔️ |
netcoreapp2.1 | netcoreapp3.0 / x86 | ❌ | Update docs - tool needs to run in compatible context
netcoreapp3.0 | netcoreapp2.1 | ❌ | Update docs - tool nees to run in compatible context
netcoreapp3.0 | netcoreapp3.0 | ❌ | Add netcoreapp3.0 target
netcoreapp3.0 | netcoreapp3.0 / x86 | ❌ | Update docs - tool needs to run in compatible context
netcoreapp3.1 | netcoreapp2.1 | ❌ | Update docs - tool nees to run in compatible context
netcoreapp3.1 | netcoreapp3.0 | ❌ | Add netcoreapp3.0 target
netcoreapp3.1 | netcoreapp3.0 / x86 | ❌ | Update docs - tool nees to run in compatible context
netcoreapp3.1 | netcoreapp3.1 | ❌ | Add netcoreapp3.0 target

[domaindrivendev]

On the back of d8c4fcef1b94f259890b8b133f130dc6128db341, which adds netcoreapp3.0 as an additional target for the CLI project, here's the updated status wrt compatibility:

SDK | App target context | Status
----- | ----------------------- | ------
2.1 | netcoreapp2.1 | ✔️
2.1 | netcoreapp2.1 / x86 | ❌ (not supported)
2.1 | netcoreapp3.0 | ✔️
2.1 | netcoreapp3.1 | ✔️
3.0 | netcoreapp2.1 | ❌ (need to use 2.1 SDK)
3.0 | netcoreapp3.0 | ✔️
3.0 | netcoreapp3.0 / x86 | ❌ (need to use x86 SDK)
3.0 / x86 | netcoreapp3.0 / x86 | ✔️
3.0 | netcoreapp3.1 | ✔️
3.1 | netcoreapp2.1 | ❌ (need to use 2.1 SDK)
3.1 | netcoreapp3.0 | ✔️
3.1 | netcoreapp3.1 | ✔️
3.1 | netcoreapp3.1 / x86 | ❌ (need to use x64 SDK)
3.1 / x86 | netcoreapp3.1 / x86 | ✔️

The cases that don't work are edge cases and have very reasonable workarounds. So, I'm going to update the docs to provide some guidance around SDK/app compatibility when using the tool, and will close this issue once that's done

[domaindrivendev]

See updated docs - https://github.com/domaindrivendev/Swashbuckle.AspNetCore#swashbuckleaspnetcorecli

[cslovell]

I followed the instructions on a clean install with no other dotnet SDKs and still got errors.

PS C:\Users\UserName\Repos\hello-world\web\api> dotnet --version
3.1.301

PS C:\Users\UserName\Repos\hello-world\web\api> dotnet --list-sdks
3.1.301 [C:\Program Files\dotnet\sdk]

PS C:\Users\UserName\Repos\hello-world\web\api> dotnet --list-runtimes
Microsoft.AspNetCore.App 3.1.5 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.NETCore.App 3.1.5 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.WindowsDesktop.App 3.1.5 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]

PS C:\Users\UserName\Repos\hello-world\web\api> dotnet swagger tofile --help
It was not possible to find any compatible framework version
The framework 'Microsoft.NETCore.App', version '2.1.0' was not found.
  - The following frameworks were found:
      3.1.5 at [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]

You can resolve the problem by installing the specified framework and/or SDK.

The specified framework can be found at:
  - https://aka.ms/dotnet-core-applaunch?framework=Microsoft.NETCore.App&framework_version=2.1.0&arch=x64&rid=win10-x64
PS C:\Users\UserName\Repos\hello-world\web\api>

Installing .NET SDK & Runtimes 2.1 fixed this:

PS C:\Users\UserName\Repos\hello-world\web\api> dotnet --list-sdks
2.1.807 [C:\Program Files\dotnet\sdk]
3.1.301 [C:\Program Files\dotnet\sdk]
PS C:\Users\UserName\Repos\hello-world\web\api> dotnet --list-runtimes
Microsoft.AspNetCore.All 2.1.19 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.All]
Microsoft.AspNetCore.App 2.1.19 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.AspNetCore.App 3.1.5 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
Microsoft.NETCore.App 2.1.19 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.NETCore.App 3.1.5 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
Microsoft.WindowsDesktop.App 3.1.5 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
PS C:\Users\UserName\Repos\hello-world\web\api> dotnet swagger tofile --help
Usage: dotnet swagger tofile [options] [startupassembly] [swaggerdoc]

startupassembly:
  relative path to the application's startup assembly

swaggerdoc:
  name of the swagger doc you want to retrieve, as configured in your startup class

options:
  --output:  relative path where the Swagger will be output, defaults to stdout
  --host:  a specific host to include in the Swagger output
  --basepath:  a specific basePath to include in the Swagger output
  --serializeasv2:  output Swagger in the V2 format rather than V3
  --yaml:  exports swagger in a yaml format

PS C:\Users\UserName\Repos\hello-world\web\api>

[domaindrivendev]

Ah - I was possibly a little overeager updating the instructions as they won’t be fully applicable until the next release goes out

[regul4rj0hn]

Hey @domaindrivendev thanks a lot for your work, our team loves the CLI. I think that we've followed you in that hasty update and now we are getting the It was not possible to find any compatible framework version error as we are targeting 3.1 on our APIs. Any target dates for the next NuGet release or preview? I'd be happy test.
Thanks!

[SSanjeevi]

Am also having same question - when in Nuget it will be available?

[domaindrivendev]

Just released 5.5.0, should be available now on Nuget.org

[SSanjeevi]

whether it wont be used for dotnetcore 3.1 - its saying not compatible.

[BlackRider97]

Not working on .Net core 3.1 See this image
Swashbuckle.AspNetCore.Cli 5.5.1

[domaindrivendev]

Are you installing as a .NET Tool or via Nuget? Sounds like you might be trying to install with Nuget which is incorrect

[regul4rj0hn]

If it helps you, the tools restore has been working perfectly for my team on 3.1.301 on fresh environments since you released 5.5.0.
Thanks.

[felschr]

I'm hitting thie issue again after upgrading to the .NET 5.0 SDK:

It was not possible to find any compatible framework version
The framework 'Microsoft.AspNetCore.App', version '3.0.0' was not found.
  - The following frameworks were found:
      5.0.0 at [/nix/store/7il5xs2aa7b7pgmi3xzgii31yhn7ysdl-dotnet-core-combined/shared/Microsoft.AspNetCore.App]

You can resolve the problem by installing the specified framework and/or SDK.

For now I have to install the .NET Core 3.1 SDK as well for it to work.

[sfoutrier]

It looks like the good old fashioned DOTNET_ROLL_FORWARD_ON_NO_CANDIDATE_FX=2 seems to works again.
(doing more tests from my side)

See: https://github.com/dotnet/core-setup/blob/master/Documentation/design-docs/multilevel-sharedfx-lookup.md