Add Framework SourceType for static web assets

[javiercn]

Add Framework SourceType for Static Web Assets

Summary

This PR adds a new Framework source type to the Static Web Assets (SWA) pipeline. Assets marked as Framework in a NuGet package are "adopted" by each consuming library: copied from the package cache to a project-local intermediate directory and transformed so the pipeline treats them as local Discovered assets owned by the consuming project.

The feature has two halves:

1. Pack side: GenerateStaticWebAssetsPropsFile evaluates a $(StaticWebAssetFrameworkPattern) glob against each asset's RelativePath and emits matching assets with SourceType="Framework" instead of the default "Package".
2. Consume side: UpdatePackageStaticWebAssets identifies Framework assets, materializes them to a project-local path, transforms their metadata to match the consuming project, and remaps associated endpoints.

Motivation

When multiple Root-mode libraries reference the same NuGet package containing static web assets, the consuming project receives duplicate asset definitions with different SourceId values — one per referencing library. The pipeline treats these as conflicting claims to the same RelativePath, producing "Duplicate Asset" build errors even though they point to the same physical file.

The primary scenario is Blazor's blazor.web.js — multiple libraries depend on a common package (Assets.Internal) containing the same framework file. Without this feature, the consuming project fails with a conflict because it receives definitions for the same file via multiple library references with different SourceIds.

Goals

• Define and implement the "Framework" asset concept. Support a category of static web assets that originate from NuGet packages but are materialized into the consuming project's intermediate output, effectively becoming local artifacts during the build.
• Resolve conflicts for shared framework dependencies. Prevent build failures when multiple libraries depend on the same framework assets by copying them to a canonical location and unifying their definition.
• Transform asset identity and ownership. Modify metadata of Framework assets to reassign ownership to the consuming project (SourceType→Discovered, SourceId→$(PackageId), BasePath→$(StaticWebAssetBasePath), AssetMode→CurrentProject).
• Enable packaging and distribution via NuGet. Allow library authors to mark assets as Framework using $(StaticWebAssetFrameworkPattern) glob at pack time.

---

Design Overview

The design introduces a new Framework source type that flows through two distinct pipeline stages — pack and consume — touching three existing primitives with no new tasks or targets required.

Component Diagram

graph TD
    subgraph "Pack Time (Library)"
        A["ComputeReferenceStaticWebAssetItems"] --> B["GenerateStaticWebAssetsPropsFile"]
        FP["$(StaticWebAssetFrameworkPattern)"] -.-> B
        B --> |"SourceType=Framework for glob matches"| C[".nupkg props file"]
    end

    subgraph "Consume Time (Consumer Project)"
        D["NuGet restore imports .props"] --> E["StaticWebAsset items<br/>(SourceType=Framework)"]
        E --> F["UpdatePackageStaticWebAssets"]
        F --> |"Materialize + Transform"| G["Adopted assets<br/>(SourceType=Discovered,<br/>AssetMode=CurrentProject)"]
        F --> |"Remap AssetFile"| H["Updated StaticWebAssetEndpoints"]
        G --> I["Rest of SWA pipeline"]
        H --> I
    end

    subgraph "StaticWebAsset.cs"
        J["SourceTypes.Framework"]
        K["IsFramework()"]
        L["Validate() accepts Framework"]
        M["ComputeTargetPath suppresses BasePath"]
    end

    C -.-> D
    J -.-> F
    K -.-> F

Loading

Modified Primitives

StaticWebAsset (Tasks/Data/StaticWebAsset.cs)

Register Framework as a valid source type. Add type-check helpers. Update path computation to suppress BasePath for Framework assets (same behavior as Discovered/Computed). Update validation to accept Framework.

  public static class SourceTypes
  {
      public const string Discovered = nameof(Discovered);
      public const string Computed = nameof(Computed);
      public const string Project = nameof(Project);
      public const string Package = nameof(Package);
+     public const string Framework = nameof(Framework);

      public static bool IsPackage(string sourceType);
+     public static bool IsFramework(string sourceType);
  }

• Validate(): Adds case SourceTypes.Framework: break; arm.
• ComputeTargetPath() / CreatePathString(): Condition that suppresses BasePath changes from IsDiscovered() || IsComputed() to IsDiscovered() || IsComputed() || IsFramework().

UpdatePackageStaticWebAssets (Tasks/UpdatePackageStaticWebAssets.cs)

Extend the existing task to identify, materialize, and transform Framework assets. Add endpoint remapping.

  public class UpdatePackageStaticWebAssets : Task
  {
      [Required]
      public ITaskItem[] Assets { get; set; }

+     public string IntermediateOutputPath { get; set; }
+     public string ProjectPackageId { get; set; }
+     public string ProjectBasePath { get; set; }
+     public ITaskItem[] Endpoints { get; set; }

      [Output]
      public ITaskItem[] UpdatedAssets { get; set; }
      [Output]
      public ITaskItem[] OriginalAssets { get; set; }

+     [Output]
+     public ITaskItem[] RemappedEndpoints { get; set; }
+     [Output]
+     public ITaskItem[] OriginalRemappedEndpoints { get; set; }
  }

For each Framework asset, Execute():

1. Materializes the file from package cache to {IntermediateOutputPath}fx/{OriginalSourceId}/{RelativePath} with timestamp-based incremental copy.
2. Transforms metadata: Identity → materialized path, SourceType → Discovered, SourceId → $(PackageId), BasePath → $(StaticWebAssetBasePath), AssetMode → CurrentProject.
3. Remaps endpoints: Groups endpoints by route (Identity), updates AssetFile for any endpoint referencing a materialized asset's old identity (group-based to handle MSBuild's Remove-by-ItemSpec semantics).

GenerateStaticWebAssetsPropsFile (Tasks/GenerateStaticWebAssetsPropsFile.cs)

Add FrameworkPattern input. Evaluate each asset's RelativePath against the glob using StaticWebAssetGlobMatcher and emit matching assets with SourceType="Framework" in the output XML.

  public class GenerateStaticWebAssetsPropsFile : Task
  {
+     public string FrameworkPattern { get; set; }
  }

Target Changes

UpdateExistingPackageStaticWebAssets (Microsoft.NET.Sdk.StaticWebAssets.targets): Pass new parameters, capture endpoint remapping outputs, apply remove/add for remapped endpoints.

  <UpdatePackageStaticWebAssets
-   Assets="@(StaticWebAsset)">
+   Assets="@(StaticWebAsset)"
+   Endpoints="@(StaticWebAssetEndpoint)"
+   IntermediateOutputPath="$(_StaticWebAssetsIntermediateOutputPath)"
+   ProjectPackageId="$(PackageId)"
+   ProjectBasePath="$(StaticWebAssetBasePath)">
    <Output TaskParameter="UpdatedAssets" ItemName="_UpdatedPackageAssets" />
    <Output TaskParameter="OriginalAssets" ItemName="_OriginalPackageAssets" />
+   <Output TaskParameter="RemappedEndpoints" ItemName="_RemappedFrameworkEndpoints" />
+   <Output TaskParameter="OriginalRemappedEndpoints" ItemName="_OriginalRemappedEndpoints" />
  </UpdatePackageStaticWebAssets>

GenerateStaticWebAssetsPackFiles (Microsoft.NET.Sdk.StaticWebAssets.Pack.targets): Pass $(StaticWebAssetFrameworkPattern) to GenerateStaticWebAssetsPropsFile.

  <GenerateStaticWebAssetsPropsFile
    StaticWebAssets="@(_PackStaticWebAssets)"
-   TargetPropsFilePath="$(_GeneratedStaticWebAssetsPropsFile)" />
+   TargetPropsFilePath="$(_GeneratedStaticWebAssetsPropsFile)"
+   FrameworkPattern="$(StaticWebAssetFrameworkPattern)" />

---

Scenarios

Scenario 1: Packaging Framework Assets

A library author sets <StaticWebAssetFrameworkPattern>**/*.js</StaticWebAssetFrameworkPattern> in its project file. During GenerateStaticWebAssetsPackFiles, GenerateStaticWebAssetsPropsFile receives the glob via FrameworkPattern, builds a StaticWebAssetGlobMatcher, and evaluates each asset's RelativePath. Matching .js files are emitted with SourceType="Framework" in the generated props file; non-matching files retain SourceType="Package". The physical package layout is unchanged.

Scenario 2: Consuming Framework Assets

After NuGet restore, the package's .props chain defines StaticWebAsset items with SourceType="Framework". When UpdateExistingPackageStaticWebAssets runs (first in ResolveCoreStaticWebAssets), UpdatePackageStaticWebAssets materializes each Framework asset to $(_StaticWebAssetsIntermediateOutputPath)fx/{OriginalSourceId}/{RelativePath}, transforms metadata (SourceType→Discovered, SourceId→$(PackageId), BasePath→$(StaticWebAssetBasePath), AssetMode→CurrentProject), and remaps associated endpoints. Downstream targets see ordinary local Discovered assets.

Scenario 3: Shared Framework Dependency

Two Root-mode libraries (LibraryA, LibraryB) both reference the same package (Assets.Internal) containing Framework assets. Each library independently materializes the framework files and transforms them with their own SourceId and BasePath. Both libraries set distinct StaticWebAssetBasePath values, so the materialized assets resolve to different target paths (_content/LibraryA/js/framework.js and _content/LibraryB/js/framework.js). When a consuming project receives these via project references, no duplicate asset error occurs because the paths do not collide.

---

Key Design Decisions

Decision	Choice	Rationale
Extend existing task vs. new task	Extend UpdatePackageStaticWebAssets	Both Package and Framework assets originate from NuGet. Processing together avoids second iteration, keeps target chain unchanged.
Transformed SourceType	Discovered	Most accurate characterization — materialized file is a real file on disk. Avoids downstream changes.
AssetMode after transformation	CurrentProject	In Root mode, CurrentProject assets flow through references. In Default mode, prevents leaking to references — each project materializes its own copy.
Glob classification point	At GenerateStaticWebAssetsPropsFile	Framework/Package is an output-only concern. Input assets stay Discovered/Computed. Mirrors how Package works today.
Endpoint remapping strategy	Grouped by route Identity	MSBuild Remove operates on ItemSpec (route). Grouping ensures all endpoints in a route group are processed together, preventing orphans.
Fingerprint/integrity handling	Preserve from FromV1TaskItem	File.Copy produces byte-identical content. Recomputing adds unnecessary I/O.

Error Handling

No custom error handling for framework asset resolution. Standard I/O exceptions propagate if source files don't exist. Two packages cannot conflict at the same materialization path because the original package ID is included (fx/{SourceId}/{RelativePath}). Existing SWA duplicate asset detection handles same-target-path conflicts. Zero glob matches is a no-op.

Testing

• Unit tests for GenerateStaticWebAssetsPropsFile glob matching (Framework vs. Package classification)
• Unit tests for UpdatePackageStaticWebAssets framework asset materialization and metadata transformation
• Unit tests for endpoint remapping (single endpoint, multiple endpoints per route, mixed Framework/Package)
• Integration tests for shared framework dependency scenario (two Root-mode libraries, same package)
• Integration tests for packaging and consuming framework assets end-to-end

[dotnet-policy-service]

Thanks for your PR, @@javiercn.
To learn about the PR process and branching schedule of this repo, please take a look at the SDK PR Guide.

[Copilot]

Pull request overview

Adds a new Framework SourceType to the Static Web Assets (SWA) pipeline so selected package assets can be “adopted” (materialized into a project-local intermediate location and transformed to behave like local discovered assets), reducing duplicate-asset conflicts when shared framework files flow through multiple references.

Changes:

• Pack-time: GenerateStaticWebAssetsPropsFile classifies assets matching $(StaticWebAssetFrameworkPattern) as SourceType=Framework in generated props.
• Consume-time: UpdatePackageStaticWebAssets materializes Framework assets into obj/.../staticwebassets/fx/..., transforms metadata to Discovered/CurrentProject, and remaps endpoints.
• Pipeline support: StaticWebAsset recognizes Framework as a valid source type and updates target-path logic; targets/tests updated to exercise end-to-end behavior.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
test/TestAssets/TestProjects/FrameworkAssetsSample/FrameworkAssetsLib/wwwroot/js/framework.js	Adds sample JS asset intended to be packed as Framework.
test/TestAssets/TestProjects/FrameworkAssetsSample/FrameworkAssetsLib/wwwroot/css/site.css	Adds sample CSS asset intended to remain Package.
test/TestAssets/TestProjects/FrameworkAssetsSample/FrameworkAssetsLib/FrameworkAssetsLib.csproj	New test library that sets StaticWebAssetFrameworkPattern.
test/TestAssets/TestProjects/FrameworkAssetsSample/FrameworkAssetsConsumer/Program.cs	Minimal consumer app entry point for integration scenario.
test/TestAssets/TestProjects/FrameworkAssetsSample/FrameworkAssetsConsumer/FrameworkAssetsConsumer.csproj	Consumer project that references packed library and validates isolation setup.
test/Microsoft.NET.Sdk.StaticWebAssets.Tests/StaticWebAssets/UpdatePackageStaticWebAssetsTest.cs	New unit tests for framework-asset materialization + endpoint remap behavior.
test/Microsoft.NET.Sdk.StaticWebAssets.Tests/StaticWebAssets/GenerateStaticWebAssetsPropsFileTest.cs	Adds tests for pack-time FrameworkPattern classification.
test/Microsoft.NET.Sdk.StaticWebAssets.Tests/FrameworkAssetsIntegrationTest.cs	New integration tests covering pack + consume + incrementality.
src/StaticWebAssetsSdk/Tasks/UpdatePackageStaticWebAssets.cs	Implements framework-asset materialization, metadata transform, and endpoint remapping.
src/StaticWebAssetsSdk/Tasks/GenerateStaticWebAssetsPropsFile.cs	Adds FrameworkPattern matching to emit SourceType=Framework.
src/StaticWebAssetsSdk/Tasks/Data/StaticWebAsset.cs	Registers Framework source type and updates validation/path computation.
src/StaticWebAssetsSdk/Targets/Microsoft.NET.Sdk.StaticWebAssets.targets	Wires new task parameters + endpoint remove/add remapping into SWA targets.
src/StaticWebAssetsSdk/Targets/Microsoft.NET.Sdk.StaticWebAssets.Pack.targets	Passes $(StaticWebAssetFrameworkPattern) into pack props generation.

[maraf]

Looks good to me & my copilot 👍

[lewing]

I've created dotnet/runtime#125329 which depends on this PR. It uses the Framework SourceType convention to fix the duplicate Identity crash in multi-WASM-client solutions (caused by dotnet/runtime#124125).

What the runtime PR does: In Browser.targets, pass-through files (JS, maps, ICU, native wasm) are materialized to obj/fx/{PackageId}/ and registered with SourceType="Framework" via a second DefineStaticWebAssets call. WebCil-converted files remain SourceType="Computed". This gives each project unique Identity values while following the Framework materialization pattern.

Testing: Validated build + publish with multi-client projects, WebCil disabled, incremental rebuild, and aspnetcore Components.TestServer (3 WASM clients) — all passing.

The runtime change is minimal (single file, ~50 lines added to Browser.targets) and only needs the Framework SourceType to be recognized by the SDK tasks.