Add CMake File API support to Microsoft.DotNet.CMake.Sdk

[Copilot]

Implementation Plan: CMake File API Integration

• Research and understand CMake File API format
  • Understand File API request/response structure
  • Understand codemodel object format
  • Understand how to map CMakeLists.txt to output artifacts
• Create new build tasks project for CMake File API operations
  • Add C# tasks to Microsoft.DotNet.CMake.Sdk project
  • Add task to generate File API request before configure
  • Add task to parse File API response and extract output paths
• Update CMake SDK targets to generate File API request
  • Add File API request generation before Configure target
  • Ensure request is created in correct location
• Update ProjectReference.targets to use File API response
  • Use File API response for artifact detection
  • Remove legacy fallback logic per review feedback
  • Copy output files based on File API response
• Test the implementation
  • Create test CMake project to verify functionality
  • Verify files are copied correctly
  • Confirm File API is being used
• Address PR review feedback
  • Use client stateless query file with client name
  • Remove backward compatibility fallback logic
  • Define C# object models for File API structures
  • Add error/warning logging as requested
  • Condition System.Text.Json to .NET Framework only
  • Remove unreferenced CopyNativeProjectBinaries target
  • Derive tasks from BuildTask instead of Task
  • Use LINQ for configuration and directory lookup
  • Seal all model types and add CMake File API documentation
  • Remove redundant VSWhereVersion property

Summary

Successfully implemented CMake File API integration for the Microsoft.DotNet.CMake.Sdk package and addressed all PR review feedback.

Changes Made:

1. New C# Tasks: Created two MSBuild tasks:

   • CreateCMakeFileApiQuery: Generates File API client stateless query before CMake configure
   • GetCMakeArtifactsFromFileApi: Parses File API response to locate build artifacts

2. C# Object Models: Created strongly-typed models in CMakeFileApiModels.cs for JSON deserialization

   • All types are sealed for performance
   • Comprehensive documentation with links to CMake File API specification

3. Updated CMake SDK: Modified Microsoft.DotNet.CMake.Sdk.csproj to build C# tasks alongside SDK files

4. Updated Targets:

   • Added CreateFileApiQuery target that runs before Configure
   • Updated ProjectReference.targets to use File API exclusively (removed fallback logic)
   • Added proper error/warning logging for missing configurations, directories, and artifacts
   • Removed unreferenced legacy CopyNativeProjectBinaries target
   • Removed redundant VSWhereVersion property (already defined by Arcade SDK)

5. Code Quality:

   • Tasks derive from BuildTask for consistency with other Arcade build tasks
   • Used LINQ for cleaner configuration and directory lookups
   • All model types sealed with proper documentation

Benefits:

• Eliminates hard-coded assumptions about CMake generator types
• Works correctly with any CMake generator (VS, Ninja, Unix Makefiles, etc.)
• More accurate artifact detection based on actual CMake build output
• Provides clear error messages when File API data is missing
• Cleaner codebase with legacy code removed and modern LINQ patterns
• Well-documented with references to official CMake specifications

Original prompt

Today, the CMake SDK (Microsoft.DotNet.CMake.Sdk) uses built-in knowledge of different kinds of generators (multi-configuration vs single-configuration, VS vs non-VS) to determine where the artifacts for a given CMakeLists.txt file within the CMake tree will build its output artifacts.

Recently, CMake as introduced the CMake File API. The File API provides a mechanism through the "codemodel" object and its subobjects to determine exactly where output files for a given CMakeLists.txt will end up for a given configuration.

Update the CMake SDK to generate a CMake File API request before running the configure step.

Then update the ProjectReference.targets logic to locate the output build items based on the CMake File API response.

If you need to introduce any C# tasks, you can follow the model of other build task libraries in this repository for how to hook up the C# project (Microsoft.DotNet.Build.Tasks.Installers for example).

Generally, the output should work as follows:

1. The user defines an MSBuild project that uses the CMake SDK to run the CMake configure and build for the whole tree.
2. The CMake SDK will create the File API request and run configure and build.
3. In another project, the user defines a CMakeProjectReference. This project reference points to a CMakeLists.txt file and a project that uses the CMake SDK.
4. The targets in ProjectReference.targets should discover the output files that correspond to the source directory the CMakeLists.txt is in (pulled from a file API response).
5. The targets should add the files such that they are copied the same way items are copied to the output directory.

Your change should not make any changes to the bringup script or the compiler search script.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[jkoritzinsky]

Please address

[jkoritzinsky]

@copilot please address the above comments

[Copilot]

@copilot please address the above comments

All review feedback has been addressed in commit d5a1e0c:

• Created client stateless query file with client name "Microsoft.DotNet.CMake.Sdk"
• Removed old fallback logic - File API is now required
• Defined C# object models for File API JSON structures
• Added error logging when configuration not found
• Added error logging when source directory not found
• Added warning logging when no artifacts found
• Conditioned System.Text.Json package reference to .NET Framework TFM only

The implementation has been tested and verified to work correctly.

[jkoritzinsky]

@copilot please address this feedback

[jkoritzinsky]

@copilot please address this feedback

[Copilot]

@copilot please address this feedback

Done in commit ad3848c. Removed the unreferenced CopyNativeProjectBinaries target that was left over from the old logic.

[Copilot]

@copilot please address this feedback

All feedback addressed in commit {short_hash}:

• Tasks now derive from BuildTask instead of Task
• Used LINQ FirstOrDefault for configuration and directory lookups
• Updated Log method calls to use BuildTask's API

[jkoritzinsky]

This is blocked on getting a newer CMake that has a new enough file API implementation rolled out on the Windows machines so we don't break our WinForms users.

Validated locally that this works for the WinForms use case.

[akoeplinger]

do we really need this? VSWhereVersion should always be defined by arcade SDK's DefaultVersions.props

[jkoritzinsky]

@copilot remove this VSWhereVersion property.

[Copilot]

Done in commit {short_hash}. Removed the redundant VSWhereVersion property since it's already defined by Arcade SDK's DefaultVersions.props.

[jkoritzinsky]

Blocked on #16233.

[akoeplinger]

Blocked on #16233.

This links to this PR 😄 is it still blocked or good to go?

[jkoritzinsky]

I messed up the copy, dang it. It's blocked on an update to the helix machines (need a newer CMake for WinForms) which isn't in yet.