Swashbuckle.aspnetcore: Upgrade from 5.0.0-rc2 to 5.0.0-rc3-preview build error

[fuzzzerd]

Forgive me if there's a different/better place to post this. I upgraded from v5.0.0-rc2 to v5.0.0-rc3-preview (myget) and I'm now getting a build error:

C:\Users[user].nuget\packages\microsoft.extensions.apidescription.server\0.3.0-preview7.19365.7\build\Microsoft.Extensions.ApiDescription.Server.targets(41,5): error MSB3073: The command "dotnet "C:\Users[user].nuget\packages\microsoft.extensions.apidescription.server\0.3.0-preview7.19365.7\build\/../tools/dotnet-getdocument.dll" --assembly "C:\Source[my-project]src[my-project]\bin\Debug\netcoreapp2.1[my-project].dll" --file-list "obj[my-project].OpenApiFiles.cache" --framework ".NETCoreApp,Version=v2.1" --output "obj" --project "[my-project]" --assets-file "C:\Source[my-project]src[my-project]\obj\project.assets.json" --platform "AnyCPU" " exited with code 7. [C:\Source[my-project]src[my-project][my-project].csproj]

Seems that there is some new dependency in rc3 that I'm not setup/configured to handle.

Wanted to put this out there in case documentation needs to be updated or if its a legitimate problem.

[CTGControls]

I have 2 projects both where getting this error then for no reason, that I can find one of them started working. A side note this always happens if the "obj[my-project].OpenApiFiles.cache" file is missing.

Severity Code Description Project File Line Suppression State
Error MSB3073 The command "dotnet "C:\Users\CTGControls.nuget\packages\microsoft.extensions.apidescription.server\0.3.0-preview7.19365.7\build\/../tools/dotnet-getdocument.dll" --assembly "C:\Users\CTGControls\source\repos\CTGControls\APISSi\bin\Debug\netcoreapp3.0\APISSi.dll" --file-list "obj\API.OpenApiFiles.cache" --framework ".NETCoreApp,Version=v3.0" --output "obj" --project "API" --assets-file "C:\Users\CTGControls\source\repos\CTGControls\APISSi\obj\project.assets.json" --platform "x86" " exited with code 2. APISSi C:\Users\CTGCntrols.nuget\packages\microsoft.extensions.apidescription.server\0.3.0-preview7.19365.7\build\Microsoft.Extensions.ApiDescription.Server.targets 41

There is a preview 8 of microsoft.extensions.apidescription.server on nuget. Maybe that fixes the problem!

The reason I am using the myget version is I had the bug in this issue: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/1185

[Ibro]

There is a preview 8 of microsoft.extensions.apidescription.server on nuget. Maybe that fixes the problem!

This didn't work for me.

Did you guys manage to find any way to mitigate this?

I am using ASP.NET Core on .NET Core 3 Preview 8.

[fuzzzerd]

I'm using netcoreapp2.1 and I had to roll back to 5.0.0-rc2.

[CTGControls]

It's really strange because I have two API projects in the same solution that use Swashbuckle.AspNetCore. One the first one started working out of the blue, and don't know why!!!! The other project, I have not been able to get working, so I switched it back to rc2 and it works. Before I switched I spent hours comparing the two projects file by file to try figuring out what's causing a problem. I see a deference that fixes the bad project. I'll try to do some more detective work if I get some free time early next week.

[Ibro]

Sadly, we can't revert and this is a blocker for us. :(

@domaindrivendev, do you have any idea when the rc3 is going to be released? Thanks.

[dnelly]

Sadly, we can't revert and this is a blocker for us. :(

@domaindrivendev, do you have any idea when the rc3 is going to be released? Thanks.

Yes, same question here. I had to roll the rc version back because my company won't let me go to production with it.

[domaindrivendev]

@dougbu - I need your assistance on this it appears to be related to the IDocumentProvider changes that you added to Swashbuckle to support new SDK tools. But, it's causing issues with the latest preview build of Swashbuckle.

[dougbu]

We could in the future handle Exceptions the IDocumentProvider hits as build warnings -- at least optionally. (That won't help if warn-as-error is enabled in your build.) Fortunately @domaindrivendev told me offline that the NRE root cause has been fixed.

In the meantime, two suggestions:

1. The preview 9 version of Microsoft.Extensions.ApiDescription.Server makes the exact errors and stack traces more obvious. Adding a direct dependency on that package (upgrading from the preview 7 version Swashbuckle.AspNetCore references) using NuGet or editing your project to include the following may help diagnose the issues:
   xml <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="3.0.0-preview9.19423.4"> <PrivateAssets>all</PrivateAssets> <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets> </PackageReference>
2. If the generated document isn't needed or you can't address the errors, disable the feature by placing the following in your project file:
   xml <PropertyGroup> <OpenApiGenerateDocuments>false</OpenApiGenerateDocuments> </PropertyGroup>
   or
   xml <PropertyGroup> <OpenApiGenerateDocumentsOnBuild>false</OpenApiGenerateDocumentsOnBuild> </PropertyGroup>
   The first disables the feature entirely. The second leaves it possible to call the GenerateOpenApiDocuments target when you wish.

[zhangpengchen]

For me, I have a piece of code related to the production environment.

.ConfigureAppConfiguration((hostingContext, configBuilder) => {
    if (hostingContext.HostingEnvironment.IsProduction()) {
        var config = configBuilder.Build();
        configBuilder.AddAzureKeyVault(
            $"https://{config["AzureKeyVault:Name"]}.vault.azure.net/",
            new PrefixKeyVaultSecretManager("API"));
    }
})

It was executed by Microsoft.Extensions.ApiDescription.Tool of course it will results an error, those are runtime variables I don't have during the build.

[fuzzzerd]

@dougbu forgive me if this is a silly question, but wouldn't disabling the generation of the documents defeat the purpose of using Swashbuckle? The main use is to generate a swagger.json document. Perhaps I don't understand how this all works and these are different documents I'm not using?

[dougbu]

wouldn't disabling the generation of the documents defeat the purpose of using Swashbuckle?

It would defeat the purpose of using Swashbuckle if these options controlled the entire Swashbuckle feature set. Instead, $(OpenApiGenerateDocuments) controls an add-on feature about writing documents to disk and $(OpenApiGenerateDocumentsOnBuild) controls an option within that feature to automatically wire writing those documents when builds complete.

[fuzzzerd]

Thanks. That makes sense. I was confused about what flags control which behavior, though I guess that comes with the territory of pre-release. Thanks for the information. I'll wait for the final release version and then see what that brings in terms of upgrading my project.

[arynaq]

For me, I have a piece of code related to the production environment.

.ConfigureAppConfiguration((hostingContext, configBuilder) => {
    if (hostingContext.HostingEnvironment.IsProduction()) {
        var config = configBuilder.Build();
        configBuilder.AddAzureKeyVault(
            $"https://{config["AzureKeyVault:Name"]}.vault.azure.net/",
            new PrefixKeyVaultSecretManager("API"));
    }
})

It was executed by Microsoft.Extensions.ApiDescription.Tool of course it will results an error, those are runtime variables I don't have during the build.

Exact same issue here, the dll will not launch through the tool if it has runtime dependencies it cannot find, I too have a keyvault config binding during startup..

[dougbu]

I suspect either

1. your launchSettings.json file doesn't contain the usual IsDevelopment settings
   json "environmentVariables": { "ASPNETCORE_ENVIRONMENT": "Development" }
2. the way the tool loads your app isn't loading launchSettings.json.

If that's you're hitting (2), I recommend either adding ASPNETCORE_ENVIRONMENT to your environment or (if you don't need the generated JSON file) using <OpenApiGenerateDocumentsOnBuild>false</OpenApiGenerateDocumentsOnBuild>.

@ryanbrandenburg please check w/ the EF team to see how they handle development / production choices in dotnet ef. The doc generation tool likely needs to do something similar.