`MapStaticAssets()` should be a viable alternative to `UseStaticFiles()`

[Atulin]

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe the problem.

1. I'm trying to serve non-standard files, like .avif and .epub

   With .UseStaticFiles() it's very easy to do:

   var extensionsProvider = new FileExtensionContentTypeProvider();
   extensionsProvider.Mappings.Add(".bar", "foo/bar");
   app.UseStaticFiles(new StaticFileOptions
   {
   	ContentTypeProvider = extensionsProvider,
   });

   With .MapStaticAssets() it's not possible, as far as I can tell.

2. I'm trying to add ZStandard compression.

   With .UseStaticFiles() it's fairly easy to do, for example using code yoinked from here:

   services.AddResponseCompression(options => {
   		options.Providers.Add<ZstdCompressionProvider>();
   		options.Providers.Add<BrotliCompressionProvider>();
   		options.Providers.Add<GzipCompressionProvider>();
   	})
   	.Configure<ZstdCompressionProvider.Options>(o => o.CompressionLevel = CompressionLevel.Optimal);

   With .MapStaticAssets() it's not possible, as far as I can tell.

3. I'm trying to serve service workers, which might require a Service-Worker-Allowed response header.

   With .UseStaticFiles() it's pretty trivial as well:

   app.UseStaticFiles(new StaticFileOptions
   {
   	OnPrepareResponse = ctx => {
   	 	if (ctx.File.Name.Contains("worker")
    	 	{
    	 	 	ctx.Context.Response.Headers.Append("Service-Worker-Allowed", "/");
    	 	}
   	},
   });

   With .MapStaticAssets() it's not possible, as far as I can tell.

Describe the solution you'd like

Since .MapStaticAssets() works on build-time, adding customization options is tricky. I see two ways to go about it:

1. Some basic customization can probably be achieved via some settings file or .csproj properties. For example, appsettings.jsoncould get a section like

   {
       "ConfigureStaticFiles": {
           "ContentTypes": {
               ".foo": "foo/bar",
               ".avif": "image/avif"
           },
           "ExtraHeaders": {
               "**/*.worker.js": {
                   "Service-Worker-Allowed": "/"
               }
           }
       }
   }

   which could then be read on build-time, and the settings could be used in the generated manifest as they are.

   Any more advanced settings like custom compression algorithms (forementioned ZStandard) would not be easy to achieve this way. We'd have to encroach on a weird DSL territory, specifying the compression class as a JSON string or something. That said, for completness' sake, let's say it could look like this:

   {
       "ConfigureStaticFiles": {
           "FileCompression": [
               "MyProject.Infrastructure.ZStandardCompressor",
               "brotli",
               "gzip"
           ]   
       }
   }

   With the compressor being defined by some IFileCompressor interface, like

   interface IFileCompressor
   {
       byte[] Compress(byte[] file);
   }

2. Precompression should be done on startup or first access, not build time.

   Compressing all files on startup could increase startup times a fair bit, but compressing them on first access should be fine. First time the browser requests a script.js file with gz encoding, the middleware (.UseStaticFiles() perhaps?) could cache the compressed response in a script.js.gz file and just serve that next time it is requested.

   That way, any more advanced config could be defined not unlike it is being defined now. The only difference would be that it doesn't run on every request.

[javiercn]

@Atulin thanks for contacting us.

MapStaticAssets is meant to complement and not replace UseStaticFiles. All the things that you are asking for should be possible:

I'm trying to serve non-standard files, like .avif and .epub

<ItemGroup> 
  <StaticWebAssetContentTypeMapping Include="image/avif" Pattern="*.avif" />
  <StaticWebAssetContentTypeMapping Include="application/epub+zip" Pattern="*.epub" /> 
</ItemGroup>

I'm trying to add ZStandard compression.

You can do so, even though I would argue is a bit tricky with the current implementation. You'd have to do something like https://github.com/dotnet/sdk/blob/main/src/StaticWebAssetsSdk/Targets/Microsoft.NET.Sdk.StaticWebAssets.Compression.targets

This is an area of improvement where we would want to allow people plugging in other compression formats without having to do extra work. (today, you'd have to generate your assets after negotiation has happened, define the endpoints and reconciliate with the existing endpoints, but it should be possible).

I'm trying to serve service workers, which might require a Service-Worker-Allowed response header.

This should be doable (in fact we use these ourselves)

  <ItemGroup>
    <!-- Define the operation: Append a response header -->
    <_EndpointOperations Include="Append">
      <UpdateTarget>Header</UpdateTarget>
      <Name>Service-Worker-Allowed</Name>
      <Value>$(ServiceWorkerAllowedValue)</Value>
    </_EndpointOperations>
    <_EndpointsToUpdate Include="@(StaticWebAssetEndpoint)" Condition="%(Route) == 'service-worker.js" />
  </ItemGroup>

  <!-- Run after endpoints are computed, but before the manifest is written -->
  <Target Name="AddServiceWorkerAllowedHeader"
          BeforeTargets="GenerateStaticWebAssetsManifest">
    <UpdateStaticWebAssetEndpoints
        EndpointsToUpdate="@(_EndpointsToUpdate)"
        Operations="@(_EndpointOperations)">
      <Output TaskParameter="UpdatedEndpoints" ItemName="_UpdatedEndpoints" />
    </UpdateStaticWebAssetEndpoints>

    <!-- Replace original endpoints with the updated ones -->
    <ItemGroup>
      <StaticWebAssetEndpoint Remove="@(_UpdatedEndpoints)" />
      <StaticWebAssetEndpoint Include="@(_UpdatedEndpoints)" />
    </ItemGroup>
  </Target>

You can also do this with a convention (which allows you to change whatever you want from the response)

app.MapStaticAssets().Add(endpointBuilder =>
{
    if (endpointBuilder is RouteEndpointBuilder routeBuilder &&
        routeBuilder.Route == "service-worker.js"
        routeBuilder.RequestDelegate is { } next)
    {
        routeBuilder.RequestDelegate = async context =>
        {
            // Add the header before invoking the static asset invoker.
            context.Response.Headers.Append("Service-Worker-Allowed", "/");
            await next(context);
        };
    }
});

Precompression should be done on startup or first access, not build time.

We disagree on this point. Compression for static files should be done at Build time, at most runtime, and for that there's already UseResponseCompression.

Compression at build time is able to use more aggressive compression settings and shaves between 20-30% extra bytes from the payload.

[Atulin]

Damn, 400+ lines of XML to add a compression algorithm

Glad to see that adding custom file types is possible! Is it documented anywhere, though? I tried searching for how to do it on my own, but came up with no results at all.

Also happy that custom headers can be added as well, even more so since it can be done with actual proper code instead of bunch of random XML DSL.

Compression for static files should be done at Build time

Generally, I agree. Not sure how easy will it be to add custom compression algorithms (and similar more advanced features) while having all of that be done at build time. Unless with some MSBuild tasks distributed via Nuget or something, that can then be set in the .csproj.

[javiercn]

@Atulin I sent you the relevant pieces so that you could take a look at how we do it.

One of the goals of moving all these processes to compile time is that we can add things in the future (like zstd support) without requiring the runtime to provide support for it (for the runtime it's just a file and an endpoint, nothing more) and that it can be done through packages and libraries.

That said, the compression support is not fully fleshed/generalized and in some spots will likely assume gzip and brotli only, but I don't think it would be terrible for us to generalize things a bit to plug in an additional step.

The tasks that would need to be updated would be
https://github.com/dotnet/sdk/blob/a2a859893da48dccb8c9ea3d145225ae90d37bd6/src/StaticWebAssetsSdk/Tasks/Compression/ResolveCompressedAssets.cs#L11

Then you would also hook some target like
https://github.com/dotnet/sdk/blob/main/src/StaticWebAssetsSdk/Targets/Microsoft.NET.Sdk.StaticWebAssets.Compression.targets#L388-L409

and that should for the most part work, I think.

All those things can be packed into a nuget package (your zstd tool, and so on).

Glad to see that adding custom file types is possible! Is it documented anywhere, though? I tried searching for how to do it on my own, but came up with no results at all.

We are working on improving the docs in this area, especially for public facing settings like this. At the same time, we want to limit he surface we expose, since that limits our ability to make changes/updates in the future.

Also happy that custom headers can be added as well, even more so since it can be done with actual proper code instead of bunch of random XML DSL.

In the end, everything ends up being an endpoint, so even when for example a content-type is not mapped (which will be application/octet-stream) you can change it at app startup time.

The DSL approach is the only feasible way to do it at build time, since we can't write any code, but it's something that is not meant for the end users and more for the framework/library authors. All our webassembly support is wired up that way with 0 runtime support to support it. With the goal being the two can evolve independently as needed.

[javiercn]

I've filed #63217 to track interest for the zstd support as a separate piece. If you are interested in contributing an improvement in this area, we would be open to discuss it.

I don't think we would ship zstd support in box until .NET Core itself has support for it, but we would definitely consider improvements to the existing infrastructure to minimize the MSBuild required for third parties to wire this up.

(Although to be perfectly honest, I think we would want the support for this baked in at some point in time).

[dotnet-policy-service]

This issue has been resolved and has not had any activity for 1 day. It will be closed for housekeeping purposes.

See our Issue Management Policies for more information.