Auto-generate ILLink.Substitutions.xml to Remove F# Metadata Resources

🎯 Problem Statement

F# assemblies contain embedded metadata resources (signature and optimization data) that significantly increase assembly size during .NET trimming scenarios. These resources, while useful for F# development tools and cross-assembly optimizations, are unnecessary in final trimmed applications and can add substantial bloat to the final binary.

The F# compiler generates multiple embedded resources with names like:

• FSharpSignatureData.{AssemblyName} /FSharpSignatureDataB.{AssemblyName}
• FSharpOptimizationData.{AssemblyName} /FSharpOptimizationDataB.{AssemblyName}
• Compressed variants of the above
• FSharpSignatureInfo.{AssemblyName} /FSharpOptimizationInfo.{AssemblyName}

Previously, developers had to manually createILLink.Substitutions.xml files to remove these resources during trimming, which was error-prone and required maintenance when assembly names changed.

🤖 Development Journey & Human Collaboration

This implementation was initially attempted by GitHub Copilot coding agent, but required significant human intervention to complete successfully:

Copilot's Contributions:

• ✅ Created the basic MSBuild task structure inGenerateILLinkSubstitutions.fs
• ✅ Implemented XML generation logic for ILLink substitution format
• ✅ Added MSBuild target integration inMicrosoft.FSharp.NetSdk.targets
• ✅ Created test project structure

Human Intervention Required:

• 🔧Fixed build errors: Copilot introduced syntax errors ([<o>] instead of[<Output>]) that caused compilation failures
• 🔧Corrected resource embedding: The generated XML file wasn't being properly embedded as a resource - required fixing target timing and MSBuild integration
• 🔧Enhanced test infrastructure: Improved the test validation script to properly report actual vs expected file sizes for easier maintenance
• 🔧Build system expertise: Ensured the test project correctly uses locally-built F# tools rather than SDK-shipped versions

This highlights both the potential and current limitations of AI coding agents - while Copilot could handle the core implementation patterns, it required human expertise for build system integration, debugging compilation errors, and ensuring proper MSBuild target execution order.

🔧 Technical Implementation

Core Components

1. MSBuild Task (GenerateILLinkSubstitutions.fs)

typeGenerateILLinkSubstitutions()=inherit Task()[<Required>]member valAssemblyName=""with get, set[<Output>]member valGeneratedItems=[||]: ITaskItem[]with get, set

The task systematically generates all F# metadata resource combinations:

• Signature/Optimization ×Data/DataB ×Compressed/Uncompressed variants
• PlusInfo variants for both signature and optimization data

2. Build Integration (Microsoft.FSharp.NetSdk.targets)

<TargetName="GenerateFSharpILLinkSubstitutions"BeforeTargets="AssignTargetPaths">  <GenerateILLinkSubstitutionsAssemblyName="$(AssemblyName)"IntermediateOutputPath="$(IntermediateOutputPath)">    <OutputTaskParameter="GeneratedItems"ItemName="EmbeddedResource" />  </GenerateILLinkSubstitutions></Target>

3. Generated Output Example

<?xml version="1.0" encoding="utf-8"?><linker>  <assemblyfullname="MyProject">    <resourcename="FSharpSignatureData.MyProject"action="remove"></resource>    <resourcename="FSharpOptimizationData.MyProject"action="remove"></resource><!-- ... all other variants ...-->  </assembly></linker>

Key Technical Decisions

• Automatic Generation: No manual maintenance required - assembly name is injected automatically
• Embedded Resource: The substitution file is embedded directly in the assembly, following .NET conventions
• Build Timing: Runs beforeAssignTargetPaths to ensure proper MSBuild item processing
• Comprehensive Coverage: Handles all current and historical F# metadata resource patterns

🧪 Testing & Validation

Added comprehensive test coverage intests/AheadOfTime/Trimming/FSharpMetadataResource_Trimming_Test/:

• Integration Test: Verifies the MSBuild task runs correctly during compilation
• Size Validation: Confirms trimmed assemblies are actually smaller (validates that resources are removed)
• Build System Test: Ensures locally-built F# tools are used rather than SDK versions

Enhanced the test infrastructure (check.ps1) to provide better feedback when assembly sizes change, making maintenance easier for future developers.

📊 Impact & Benefits

• Zero Configuration: Works automatically for all F# projects with trimming enabled
• Significant Size Reduction: Removes potentially large metadata resources from final binaries
• Maintenance-Free: No manual XML file creation or updates required
• Backward Compatible: Doesn't affect existing projects or development workflows

🔗 Related Issues

Fixes#18591

This PR demonstrates the collaborative potential between AI coding agents and human developers - where AI can handle routine implementation patterns while humans provide the critical expertise for build systems, debugging, and ensuring production-quality integration.