Challenges in using WebApplication.CreateEmptyBuilder

[kikaragyozov]

Having the ability to create an empty builder is amazing, but if my use-case is rather simple - I have to alter the way configuration is loaded into an ASP.NET Core project, for example due to encryption being involved, which basically means using AddJsonStream instead of the default - I'm left with a dozen of questions.

What must I call to achieve the same behavior I was previously getting with the default builder minus X?

I'm left to my own devises, having to scrape what code was added in PRs like #47797 and having to inspect code like HostingBuilderExtensions and other parts here and there, leading to a chaotic experience and definitely missing something somewhere between the lines.

There also appears to be zero official documentation regarding proper usage of CreateEmptyBuilder, or what features it still supports out of the box. The closest thing to a documentation regarding the features set, could be seen in #48811

For example, currently, I'm unsure if I am to do

builder.Services.AddLogging(logging =>
        {
            logging.AddConfiguration(configuration.GetSection("Logging"));
            logging.AddConsole();

            logging.Configure(options =>
            {
                options.ActivityTrackingOptions =
                    ActivityTrackingOptions.SpanId |
                    ActivityTrackingOptions.TraceId |
                    ActivityTrackingOptions.ParentId;
            });
        });

versus a simple

            builder.Logging
                .AddConfiguration(builder.Configuration.GetSection("Logging"))
                .AddConsole();

There's also no guarantee that in doing this approach, I'll always get the same expected behavior, as the code for the default behavior can change with time, which would render the one I copied to try and "mimic" it invalid.

[mkArtakMSFT]

@eerhardt given that you've worked on some of this relatively recently, would you be open to documenting these two new APIs so that questions like these are addressed in docs?

[eerhardt]

We have the differences between the 3 APIs documented here:

https://review.learn.microsoft.com/en-us/aspnet/core/fundamentals/native-aot?view=aspnetcore-9.0&branch=main#createslimbuilder-vs-createbuilder

Which links out to https://andrewlock.net/exploring-the-dotnet-8-preview-comparing-createbuilder-to-the-new-createslimbuilder-method/, another great piece of information.

Having the ability to create an empty builder is amazing, but if my use-case is rather simple - I have to alter the way configuration is loaded into an ASP.NET Core project, for example due to encryption being involved, which basically means using AddJsonStream instead of the default - I'm left with a dozen of questions.
What must I call to achieve the same behavior I was previously getting with the default builder minus X?

I'm not sure starting from "empty" is the best route in your case. If you want mostly the default behavior, minus one thing, it would be better to take the route of removing that one thing. In your case it sounds like you want to remove a configuration source from the ConfigurationManager. You can do this by calling builder.Configuration.Sources.Remove to remove the one you don't want, and then add what you want back in.

[kikaragyozov]

We have the differences between the 3 APIs documented here:

https://review.learn.microsoft.com/en-us/aspnet/core/fundamentals/native-aot?view=aspnetcore-9.0&branch=main#createslimbuilder-vs-createbuilder

Which links out to https://andrewlock.net/exploring-the-dotnet-8-preview-comparing-createbuilder-to-the-new-createslimbuilder-method/, another great piece of information.

Having the ability to create an empty builder is amazing, but if my use-case is rather simple - I have to alter the way configuration is loaded into an ASP.NET Core project, for example due to encryption being involved, which basically means using AddJsonStream instead of the default - I'm left with a dozen of questions.
What must I call to achieve the same behavior I was previously getting with the default builder minus X?

I'm not sure starting from "empty" is the best route in your case. If you want mostly the default behavior, minus one thing, it would be better to take the route of removing that one thing. In your case it sounds like you want to remove a configuration source from the ConfigurationManager. You can do this by calling builder.Configuration.Sources.Remove to remove the one you don't want, and then add what you want back in.

Sadly the default builder immediately throws an exception in my case, as the file it adds named "appsettings.json" is encrypted and is not a valid json when it attempts to add it. I'm aware that I can rename the file to avoid this, but it's a hack and a weird way to go around it.

All of the materials you linked I've read, but I still find that information lacking. The information is outlined in an implicit way, i.e you have to derive what actually the default builder does, based on what the slim builder does not support, and based on what it still supports. It's also not in its own section but hidden under "Native AOT" section.

As for any examples of using the empty builder correctly - none exist in the MSFT.

In the meantime, could someone please showcase how one would correctly create an identical default builder manually, when starting from an empty one?

[davidfowl]

Sadly the default builder immediately throws an exception in my case, as the file it adds named "appsettings.json" is encrypted and is not a valid json when it attempts to add it. I'm aware that I can rename the file to avoid this, but it's a hack and a weird way to go around it.

Why not fix that problem by renaming the file to something else that doesn't conflict with what the builder expects (and most of the configuration system...)?

[kikaragyozov]

Sadly the default builder immediately throws an exception in my case, as the file it adds named "appsettings.json" is encrypted and is not a valid json when it attempts to add it. I'm aware that I can rename the file to avoid this, but it's a hack and a weird way to go around it.

Why not fix that problem by renaming the file to something else that doesn't conflict with what the builder expects (and most of the configuration system...)?

Aren't you just avoiding the problem if you do end up doing that?

The appsettings.json file is a valid json configuration file which in some cases is encrypted while in others its not. The perfect place to address this, is when creating a builder, no?

Otherwise, you're going out of your way to solve the problem around the problematic component, which if you repeat that for every similar situation you're in, you get a big code smell. All of this just seems awfully weird, when supposedly you could do this easily via the empty builder, but it's not easy. That's the issue.

[davidfowl]

If it were me, I would rename the file and write a configuration provider that handled encrypted configuration and add it to the existing system.

I think your ask is valid but it's the hardest way to solve this problem that seems easy to work around (and a better approach in my opinion).

[Kumima]

Any chance to provide a code snippet that configures the EmptyBuilder into SlimBuilder and DefaultBuilder?

[koustubhmoharir]

It seems like it is not currently possible to start with an empty builder and add the full functionality of the slim / default builders. Reading and stepping through the code reveals some internal / private classes / methods with significant functionality such as the GenericWebHostBuilder. It would be great if the implementation of the slim / default builders started from the empty builder. This would validate that the empty builder is really usable if full control is desired. If the code were to follow this pattern, no additional documentation would be necessary, as people with the motivation to do the hard work of starting from an empty builder would easily be able to adapt the code.