dotnet-getdocument issues in .NET7

[Wtiben]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

We're currently on .NET6 and trying to migrate to .NET7. We're making use of <OpenApiGenerateDocumentsOnBuild/> and <OpenApiProjectReference/>. The implementation of GetDocument.Insider has changed in .NET7 (#43701) to start all IHostedService implementations and allow for all DI configuration to be executed. As pointed out by bachratyg this implementation might be handy for some cases, but is also completely undesirable for others. For example, we're using a IHostedService implementation to make a call to a microservice in the same solution at startup, which is now impossible to do. We're also validating the presence of certain configuration entries at startup e.g:
if (string.IsNullOrEmpty(config.GetConnectionString("database"))) { throw new Exception(); }. This now fails because these are defined in our docker-compose.yml file.

I'm not sure if there's a one-size-fits-all solution to this problem but it would at least be nice to have the option to revert back to the previous behaviour.

Expected Behavior

The project builds succesfully and generates an openapi document without invoking a bunch of application code.

Steps To Reproduce

A .csproj:

<Project Sdk="Microsoft.NET.Sdk.Web">
	<PropertyGroup>
		<TargetFramework>net7.0</TargetFramework>
		<OpenApiGenerateDocumentsOnBuild>true</OpenApiGenerateDocumentsOnBuild>
		<ImplicitUsings>enable</ImplicitUsings>
	</PropertyGroup>

	<ItemGroup>
		<PackageReference Include="Swashbuckle.AspNetCore" Version="6.2.3" />
		<PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="7.0.0" PrivateAssets="all" />
	</ItemGroup>
</Project>

Example scenarios:

• Register an IHostedService implementation that executes some logic which is impossible to do at build time. For example making a call to a microservice in the same solution.
• Validate the presence of a configuration entry which is defined outside of appsettings.json (e.g. user secrets or docker-compose.yml). For example:

var builder = WebApplication.CreateBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("Database");

if (string.IsNullOrEmpty(connectionString))
{
    throw new Exception();
}

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

The project now fails to build.

Exceptions (if any)

No response

.NET Version

7

Anything else?

Related:

• Microsoft.Extensions.ApiDescription.Server ignores minimal API endpoints #43391
• Update dotnet-getdocument to support minimal APIs #43701

[captainsafia]

Thanks for filing this issue! Referencing #43395 alongside here as well.

I'm not sure if there's a one-size-fits-all solution to this problem but it would at least be nice to have the option to revert back to the previous behaviour.

Unfortunately, I don't think a revert to the previous behavior is a valid option here. AFAIK, the previous behavior doesn't work with the new builder in .NET 6. Do you currently have a working scenario in .NET 6?

Will noodle on this a bit more and add notes...

[davidfowl]

Validate the presence of a configuration entry which is defined outside of appsettings.json (e.g. user secrets or docker-compose.yml). For example:

This should still work if it's in user secrets. If the application is missing required configuration in development then it never ran to begin with, right?

Register an IHostedService implementation that executes some logic which is impossible to do at build time. For example making a call to a microservice in the same solution.

Yes, this one isn't ever going to work. I think we could do something here, like never run hosted services in this mode.

[Wtiben]

Unfortunately, I don't think a revert to the previous behavior is a valid option here. AFAIK, the previous behavior doesn't work with the new builder in .NET 6. Do you currently have a working scenario in .NET 6?

We currently have a solution with a couple of projects using <OpenApiGenerateDocumentsOnBuild>true</OpenApiGenerateDocumentsOnBuild>, other projects referencing them with <OpenApiProjectReference Include="RelativePath"> and all of them using .NET6' WebApplication and top level statements. So far it's been working fine and we haven't ran into issues.

This should still work if it's in user secrets. If the application is missing required configuration in development then it never ran to begin with, right?

The only way to get it to build this way is with an explicit call to Configuration.AddUserSecrets<Program>(). Since dotnet-getdocument isn't running the application with ASPNETCORE_ENVIRONMENT=Development, user secrets aren't being added to the WebApplication's default configuration and thus the build fails.
During local development this isn't too much of an issue as we can just add a call to AddUserSecrets(), but it would still fail in CI environments as there are no user secrets available (same goes for any other external configuration sources).

At its core i think its very problematic to have application startup code be invoked at all, as there's always gonna be stuff which isn't possible/available at build time.

[captainsafia]

and all of them using .NET6' WebApplication and top level statements. So far it's been working fine and we haven't ran into issues.

Interesting...We did backport the fix to the .NET 6 SDK. I assume you're on the latest patch?

At its core i think its very problematic to have application startup code be invoked at all, as there's always gonna be stuff which isn't possible/available at build time.

There's a chance we maybe able to avoid this if we statically analyzed the application to determine the OpenApiDocument. For context, the reason we need to run the application in order to generate the OpenApi document is to be able to populate an accurate description of all the routes in an application.

Thanks for contacting us.

We're moving this issue to the .NET 8 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s).
If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues.
To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[davidfowl]

The application code always ran, even in .NET < 6. The difference is it ran a different entry point which hopefully did less. Now with the new hosting model, there’s no second entry point we can use to get the service provider from various tools

[0xced]

I had the same issue (i.e. multiple IHostedService implementations running at build time) when I upgraded from Microsoft.Extensions.ApiDescription.Server version 6.0.10 to version 6.0.11.

My workaround detects when the entry point is being called by GetDocument.Insider and stops after building the app, which is enough for the OpenAPI generation to work.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();

if (Environment.GetCommandLineArgs().Any(e => e.Contains("GetDocument.Insider")))
{
    Console.WriteLine("Called by GetDocument.Insider in order to generate the OpenAPI definition at build time.");
    return;
}

app.UseSwagger();
app.UseSwaggerUI();
app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();

The behaviour becomes more like the previous version which was basically only calling the CreateHostBuilder method (through the HostFactoryResolver) to build the host.

[axelgenus]

@0xced gave me the inspiration to implement a different workaround (using Reflection) on the various ServiceCollectionExtensions classes we have in our shared libraries:

public static class ServiceCollectionExtensions
{
    private static readonly string EntryAssemblyName;

    static ServiceCollectionExtensions()
    {
        var assembly = Assembly.GetEntryAssembly();
        AssemblyName assemblyName = assembly?.GetName();

        EntryAssemblyName = assemblyName?.Name;
    }

    public static IServiceCollection AddWhatever(this IServiceCollection services)
    {
        if (EntryAssemblyName == @"GetDocument.Insider")
        {
            return services;
        }

        // [...]

        return services;
    }
}

[michaelrp]

We seem to have a similar issue in that a connection string is defined in appsettings.Development.json but not in appsettings.json. Version 6.0.7 works fine, but 7.0.0 fails when running dotnet build.