Add support for file-based apps to the XPlat CLI

[jjonescz]

Bug

Resolves NuGet/Home#14390.

Description

Adds a way for XPlat CLI commands to work on virtual projects (the projects backing file-based apps) in addition to physical projects.

The dotnet CLI can invoke the NuGet CLI in-process and provide an IVirtualProjectBuilder that handles creating/saving the virtual project XML. Companion SDK-side PR: dotnet/sdk#53535

Key Changes

• New IVirtualProjectBuilder interface: Defines the contract between the SDK and NuGet for handling file-based apps: validating entry point paths, creating ProjectRootElement from virtual projects, and saving modifications back.
• MSBuildAPIUtility refactored: this is where the IVirtualProjectBuilder is used to load the virtual project for file-based apps.
• Program class made public with a new Run(string[] args, IVirtualProjectBuilder) entry point for in-process invocation from the dotnet CLI. Similarly extended the other WhyCommand and NuGetCommands entry points.
• All relevant commands updated: add package, remove package, list package, package update, and nuget why now accept and propagate IVirtualProjectBuilder to MSBuildAPIUtility.
  • package update and nuget why help texts are visible directly from dotnet CLI, so updated those too to match other dotnet CLI commands:
    • Added --file option (companion to the pre-existing --project) to package update. E.g., dotnet run has an analogous pair of options.
    • Extended nuget why argument to accept FILE in addition to PROJECT | SOLUTION. E.g., dotnet build has an analogous argument.

Tests

• New integration tests for all commands with file-based apps in Dotnet.Integration.Test.
• Unit tests in NuGet.XPlat.FuncTest: either new or extended existing with a parameter (bool fileBasedApp).

PR Checklist

• Meaningful title, helpful description and a linked NuGet/Home issue
• Added tests
• Link to an issue or pull request to update docs if this PR changes settings, environment variables, new feature, etc.

[Copilot]

Pull request overview

Adds a mechanism for NuGet XPlat CLI commands to operate on virtual projects (file-based apps) by supplying project XML via a --project-content-file option, enabling commands to evaluate and edit project state without a physical .csproj file.

Changes:

• Introduces --project-content-file across multiple XPlat commands (why/list/add/remove/package update) and wires it through args/IO layers.
• Updates MSBuild evaluation/saving to support reading project XML from an external file while preserving an expected project path.
• Adds/updates integration and unit tests to cover file-based app scenarios for why/list/add/remove/update.

Reviewed changes

Copilot reviewed 41 out of 42 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
test/NuGet.Core.Tests/NuGet.CommandLine.Xplat.Tests/MSBuildAPIUtilityTests.cs	Updates tests to use SaveableProject wrapper when updating props via MSBuild API utility.
test/NuGet.Core.FuncTests/NuGet.XPlat.FuncTest/NuGet.XPlat.FuncTest.csproj	Adds InternalsVisibleTo for Dotnet.Integration.Test to reuse internal test helpers.
test/NuGet.Core.FuncTests/NuGet.XPlat.FuncTest/ListPackageTests.cs	Adjusts assertion for added field in ListPackageArgs.
test/NuGet.Core.FuncTests/Dotnet.Integration.Test/DotnetWhyTests.cs	Adds integration test covering why against a file-based app using --project-content-file.
test/NuGet.Core.FuncTests/Dotnet.Integration.Test/DotnetRemovePackageTests.cs	Adds integration test covering remove for file-based apps using --project-content-file.
test/NuGet.Core.FuncTests/Dotnet.Integration.Test/DotnetPackageUpdateTests.cs	Adds integration test covering package update for file-based apps using --project-content-file.
test/NuGet.Core.FuncTests/Dotnet.Integration.Test/DotnetListPackageTests.cs	Adds integration test covering list package for file-based apps using --project-content-file.
test/NuGet.Core.FuncTests/Dotnet.Integration.Test/DotnetIntegrationTestFixture.cs	Adds stdin support to dotnet runner and helper to fetch virtual project XML via run-api; registers MSBuild path.
test/NuGet.Core.FuncTests/Dotnet.Integration.Test/DotnetAddPackageTests.cs	Adds integration test covering add package for file-based apps using --project-content-file.
src/NuGet.Core/NuGet.CommandLine.XPlat/Utility/MSBuildAPIUtility.cs	Adds SaveableProject wrapper and project-content-file support for loading/saving and package reference operations.
src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Why/WhyCommand.cs	Adds --project-content-file option and adjusts path handling for virtual projects.
src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Why/WhyCommandArgs.cs	Adds ProjectContentFile to why command args.
src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Why/WhyCommandRunner.cs	Uses project-content-file path mode for validation and assets discovery.
src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/PackageReferenceCommands/AddPackageReferenceCommand.cs	Adds --project-content-file and adjusts project path handling for file-based apps.
src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/PackageReferenceCommands/AddPackageReferenceCommandRunner.cs	Plumbs ProjectContentFile through to MSBuild update operations.
src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/PackageReferenceCommands/RemovePackageReferenceCommand.cs	Adds --project-content-file and relaxes project extension validation for virtual projects.
src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/PackageReferenceCommands/RemovePackageReferenceCommandRunner.cs	Plumbs ProjectContentFile through to MSBuild remove operation.
src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/PackageReferenceCommands/PackageReferenceArgs.cs	Adds ProjectContentFile to package reference command args.
src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/PackageReferenceCommands/ListPackage/ListPackageCommand.cs	Adds --project-content-file, updates renderer construction to use provided writers.
src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/PackageReferenceCommands/ListPackage/ListPackageCommandRunner.cs	Skips file-existence checks when project content is provided and loads project via content file.
src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/PackageReferenceCommands/ListPackage/ListPackageArgs.cs	Adds ProjectContentFile; fixes spacing in reported params string.
src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Package/Update/PackageUpdateCommand.cs	Adds --project-content-file option and stores original entrypoint path for file-based apps.
src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Package/Update/PackageUpdateArgs.cs	Adds ProjectContentFile and OriginalProject fields for virtual projects.
src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Package/Update/PackageUpdateCommandRunner.cs	Uses original entrypoint path for DGSpec generation and passes content file when updating references.
src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Package/Update/PackageUpdateIO.cs	Updates DGSpec generation to use dotnet build and adds optional project-content-file plumbing.
src/NuGet.Core/NuGet.CommandLine.XPlat/Commands/Package/Update/IPackageUpdateIO.cs	Extends interface to accept optional project content file in DGSpec/update operations.
src/NuGet.Core/NuGet.CommandLine.XPlat/Strings.resx	Adds localized description for --project-content-file.
src/NuGet.Core/NuGet.CommandLine.XPlat/Strings.Designer.cs	Adds strongly-typed resource accessor for Pkg_ProjectContentFileDescription.
src/NuGet.Core/NuGet.CommandLine.XPlat/GlobalSuppressions.cs	Updates suppression target signature for ListPackageCommand.GetOutputType(...).
src/NuGet.Core/NuGet.CommandLine.XPlat/xlf/Strings.zh-Hant.xlf	Adds new trans-unit for Pkg_ProjectContentFileDescription.
src/NuGet.Core/NuGet.CommandLine.XPlat/xlf/Strings.zh-Hans.xlf	Adds new trans-unit for Pkg_ProjectContentFileDescription.
src/NuGet.Core/NuGet.CommandLine.XPlat/xlf/Strings.tr.xlf	Adds new trans-unit for Pkg_ProjectContentFileDescription.
src/NuGet.Core/NuGet.CommandLine.XPlat/xlf/Strings.ru.xlf	Adds new trans-unit for Pkg_ProjectContentFileDescription.
src/NuGet.Core/NuGet.CommandLine.XPlat/xlf/Strings.pt-BR.xlf	Adds new trans-unit for Pkg_ProjectContentFileDescription.
src/NuGet.Core/NuGet.CommandLine.XPlat/xlf/Strings.pl.xlf	Adds new trans-unit for Pkg_ProjectContentFileDescription.
src/NuGet.Core/NuGet.CommandLine.XPlat/xlf/Strings.ko.xlf	Adds new trans-unit for Pkg_ProjectContentFileDescription.
src/NuGet.Core/NuGet.CommandLine.XPlat/xlf/Strings.ja.xlf	Adds new trans-unit for Pkg_ProjectContentFileDescription.
src/NuGet.Core/NuGet.CommandLine.XPlat/xlf/Strings.it.xlf	Adds new trans-unit for Pkg_ProjectContentFileDescription.
src/NuGet.Core/NuGet.CommandLine.XPlat/xlf/Strings.fr.xlf	Adds new trans-unit for Pkg_ProjectContentFileDescription.
src/NuGet.Core/NuGet.CommandLine.XPlat/xlf/Strings.es.xlf	Adds new trans-unit for Pkg_ProjectContentFileDescription.
src/NuGet.Core/NuGet.CommandLine.XPlat/xlf/Strings.de.xlf	Adds new trans-unit for Pkg_ProjectContentFileDescription.
src/NuGet.Core/NuGet.CommandLine.XPlat/xlf/Strings.cs.xlf	Adds new trans-unit for Pkg_ProjectContentFileDescription.

Files not reviewed (1)

• src/NuGet.Core/NuGet.CommandLine.XPlat/Strings.Designer.cs: Language not supported

[jjonescz]

@nkolev92 @Nigusu-Allehu for another look, thanks

[jjonescz]

Thanks @nkolev92, feel free to merge this when you're ready.

I will open a follow up PR to remove the optional parameter of MSBuildAPIUtility from #7169 (comment)

Other follow ups should have their own issues.

[nkolev92]

@jjonescz I want to merge this after the build completes and there are some follow-ups we discussed, please address them in a follow-up, that way we don't have to rereview things.

[nkolev92]

We said the same thing lol. :D