[API Proposal]: The Bundler API should allow for pre-computing the lists of included and excluded files in the bundle

[baronfel]

Background and motivation

Bundle Generation in the .NET SDK uses the GenerateBundle Task to call the Bundler hosting APIs.

These APIs are great for one-shot bundle generation, but there's a bug in the SDK targets here around incrementality because of the side-effecting nature of these APIs. This was raised by a user in github.com/dotnet/sdk/issues/52151, and it comes down to the fact that Bundle generation returns Items that weren't included as a side-effect, but when the Target is considered up to date no Tasks are run, so we don't know which files to copy that weren't part of the bundle.

To properly support incrementality, we need to be able to pre-compute the included/excluded files that would be in a given bundle given a set of inputs and associated bundling options. Knowing these lists lets us properly ensure that in all cases, files that are excluded from the bundle will be copied to the relevant output directory.

API Proposal

Something along the lines of

public class Bundler
{
  public BundleContents PrecomputeBundleContents(IReadOnlyList<FileSpec> fileSpecs);
}

public class BundleContents
{
  public IReadOnlyList<FileSpec> IncludedInBundle { get; }
  public IReadOnlyList<FileSpec> ExcludedFromBundle { get; }
}

would be enough. As a bonus, GenerateBundle might be able to have an overload that did zero filtering/validation if passed some kind of pre-validated input set.

API Usage

In our pre-compute Target, we'd have a MSBuild Task that would

• create the Bundler instance
• provide the full input file set to the new filtering method

Then, the 'PrepareFilesToBundle' step would

• use the results of that input file set filtering to construct a pre-filtered list of inputs for proper bundling
• use the results of that input file set filtering to ensure that non-bundled files are copied to the relevant output directory

And finally the actual bundle-generation Target would treat the list of actual bundle inputs as its incrementality inputs to tie everything all together nicely.

Alternative Designs

No response

Risks

No response

[teo-tsirpanis]

These APIs are internal and not shipped to consumers; I don't think an API review would be needed here.

[dotnet-policy-service]

Tagging subscribers to this area: @agocke, @jeffschwMSFT, @elinor-fung
See info in area-owners.md if you want to be subscribed.