Add file-based program API for use by IDE #48749

jjonescz · 2025-04-28T13:15:58Z

No description provided.

Copilot

Pull Request Overview

This pull request adds a new file-based program API intended for IDE integration by introducing a new run-api command, updating parser and project conversion logic, and expanding test coverage.

Introduces new tests for API behavior and diagnostic responses in RunFileTests.
Refactors VirtualProjectBuildingCommand to use static helpers and updated error reporting.
Updates TestCommand and SdkCommandSpec to support standard input redirection and adds the run-api command to the parser.

Reviewed Changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
test/dotnet.Tests/CommandTests/Run/RunFileTests.cs	Added tests for API functionality and diagnostics for file-based programs.
test/dotnet.Tests/CommandTests/Project/Convert/DotnetProjectConvertTests.cs	Updated project conversion calls to use revised directive methods.
test/Microsoft.NET.TestFramework/Commands/TestCommand.cs	Added support for redirecting standard input in tests.
test/Microsoft.NET.TestFramework/Commands/SdkCommandSpec.cs	Updated ProcessStartInfo configuration for standard input redirection.
src/Cli/dotnet/Parser.cs	Integrated the new run-api command into the parser.
src/Cli/dotnet/Commands/Run/VirtualProjectBuildingCommand.cs	Refactored methods to use static helpers and improved error reporting with a diagnostics builder.
src/Cli/dotnet/Commands/Run/Api/RunApiCommandParser.cs and RunApiCommand.cs	Added a new API command for handling file-based program inputs and outputs.
src/Cli/dotnet/Commands/Project/Convert/ProjectConvertCommand.cs	Updated project conversion to call the revised directive methods correctly.

RikkiGibson

LGTM. It would be good to provide a self contained sample usage of the CLI--just a simple case which shows, say, running the command from CLI, piping in some data, and getting a result out on the other end, which would indicate the expected schema of the command.

RikkiGibson · 2025-04-28T22:09:42Z

src/Cli/dotnet/Commands/Run/Api/RunApiCommand.cs

+{
+    public override int Execute()
+    {
+        for (string line; (line = Console.ReadLine()) != null;)


I haven't seen this kind of pattern before, is this a norm for apps which communicate using json over stdio? To essentially put each message on its own line?

JSON separated by newlines seemed simple and straightforward, but feel free to suggest alternatives (especially what IDE would like to communicate with). I guess JSON-RPC is more standard, but likely needs more code / libraries. Instead of stdio we could also use named pipes like compiler server does.

I don't have particular concerns about the current solution, just trying to make sure I understand the design. Thanks!

I'd definitely consider JSON-RPC as it is a standard for this kind of stuff.

When I did the out-of-proc build host stuff, I implemented my own RPC via single-line as well. That said, it's a bit unclear to me why we're needing multiple lines like this.

That said, it's a bit unclear to me why we're needing multiple lines like this.

If you expect IDE is going to make only one-off requests (i.e., run new dotnet run-api process for each project separately), we can definitely simplify this.

If there are no preferences, should we proceed with the current state for starters? If needed, we can change the API later (the run-api command is hidden, so I think we are free to change it).

I personally have no concerns about the current state. I don't see any reason the command shouldn't handle sequenced requests and responses, even if IDE doesn't make use of that capability.

If we found that spinning a new subprocess to make a project, each time #:s are edited or under other various "relatively infrequent" conditions (as compared to updates of ordinary source code), is problematic, then we could start keeping the subprocess alive for some period of time, and making use of this queueing capability.

I'd definitely consider JSON-RPC as it is a standard for this kind of stuff.

@MiYanni Does this comment mean you want me to switch to json-rpc before merging this? There would be some questions like if we want a full compliance with the standard, then we probably need some library (which also means ship a new DLL along the sdk, and likely a new DLL load on the IDE side). Or we can implement this manually like Jason did for out-of-proc (@jasonmalinowski, can you point me to your implementation?). But perhaps we can follow up later since this is an internal API between SDK and IDE (and will need changing anyway for multi file support)

https://github.com/dotnet/roslyn/blob/main/src/Workspaces/MSBuild/BuildHost/Rpc/RpcServer.cs

RikkiGibson · 2025-04-28T22:16:32Z

src/Cli/dotnet/Commands/Run/Api/RunApiCommand.cs

+    public sealed class GetProject : RunApiInput
+    {
+        public string? ArtifactsPath { get; init; }
+        public required string EntryPointFileFullPath { get; init; }


This represents the primary bit of information that IDE must provide, right? This means that IDE must come up with a solution for searching, from a loose file that was opened, to find a "nearest relevant entry point", cracking the files as we go, and pass that in to dotnet cli. I think that's something we can do, just making sure of the expectation.

This API is for single-file currently, so it should be simple - just pass the current file as the EntryPointFileFullPath.

For multi-file scenarios, I agree you would need to do the search you describe. The API will then also take the list of files to exclude (i.e., the other entry points). The implementation can automatically discover the other .cs files to include (which it needs to read for directives) based on the entry point or we can pass them to the API if that would be better for perf (since the IDE might have already discovered them via its more efficient file watchers).

Btw, it might be useful if the IDE checks SDK's version to determine whether run-api is present and whether it supports single-file or multi-file scenarios (and perhaps more in the future) - so the IDE can give better error messages when the SDK being used is not in sync with the features implemented in the IDE.

We could also introduce some run-api call like "GetCapabilities" that the IDE could use (and for SDKs that don't contain run-api command at all, presumably the IDE could detect that from the error message SDK produces when trying to run dotnet run-api).

Maybe a version stamp in requests/responses would give us enough expressiveness here? That would be a bit like SymbolKey.FormatVersion.

it might be useful if the IDE checks SDK's version to determine whether run-api is present

If we have to do things like that, then I'd expect we have some API call we do for "get entry point discovery algorithm" or something, rather than an explicit check on the SDK version directly, especially if we try something experimentally and then have to roll it back in the SDK for a few weeks or something.

(and consider if/when we ever have a situation where the user's repo might opt them into some other behavior)

test/dotnet.Tests/CommandTests/Run/RunFileTests.cs

RikkiGibson · 2025-04-29T17:30:30Z

test/dotnet.Tests/CommandTests/Run/RunFileTests.cs

+                    """)}},"Diagnostics":
+                [{"Location":{
+                "Path":{{ToJson(programPath)}},
+                "Span":{"Start":{"Line":0,"Character":0},"End":{"Line":1,"Character":0}{{nop}}}{{nop}}},


Oh, is this nop breaking-up the }s in order to keep distinct which ones are ending an interpolation and which ones are part of the content?

The nop is to avoid compiler errors due to the closing brackets }} inside an interpolated string $$""". (the errors are redundant IMO, the interpolated string could be compiled just fine even though it contains unmatched }}.) See also the doc comment at the nop constant.

Example:

var s1 = $$"""{"x":{{1}},"y":{"z":2}}"""; // error on the last }} var s2 = $$$"""{"x":{{{1}}},"y":{"z":2}}"""; // ok but interpolation holes need soo many brackets (even more when the JSON is more nested) const string nop = ""; var s3 = $$"""{"x":{{1}},"y":{"z":2}{{nop}}}"""; // workaround (we can keep the number of `$$` constant wrt nesting of the JSON)

RikkiGibson · 2025-04-30T17:10:06Z

src/Cli/dotnet/Commands/Run/Api/RunApiCommand.cs

+    /// (e.g., show an error message when an incompatible SDK version is being used).
+    /// </summary>
+    [JsonPropertyOrder(-1)]
+    public int Version { get; } = 1;


It might also make sense for caller to pass in the "version" of the API they are using, implying the set of behaviors they expect, and the run-api command can reject the request in a well-defined way if it's not "compatible" with that version.

Actually, it looks like this property is on the base type? So the caller can always just read the version that comes out. It would be good to verify that this property is present in an error case. No need for caller to pass in the version.

jjonescz · 2025-05-02T10:53:51Z

@chsienki @MiYanni for reviews, thanks

MiYanni

I just recreated this issue as it relates to output from the CLI. JSON will be one of the bespoke formats.

MiYanni · 2025-05-02T20:37:55Z

src/Cli/dotnet/Commands/Run/Api/RunApiCommand.cs

+{
+    public override int Execute()
+    {
+        for (string line; (line = Console.ReadLine()) != null;)


I'd definitely consider JSON-RPC as it is a standard for this kind of stuff.

RikkiGibson · 2025-05-07T21:14:29Z

@MiYanni for review

MiYanni

Current design is fine. My comment about JSON-RPC is generally for if the implementation grows, it is definitely something that should be considered. But I'm not going to halt merging this on doing all that work.

RikkiGibson · 2025-05-12T17:10:17Z

I'd like to keep an eye out for a nightly SDK which has this included.

jasonmalinowski

Apologies I didn't have a chance to leave comments prior to this merging -- and worse off the few I had written I forgot to post.

jasonmalinowski · 2025-05-03T00:01:57Z

src/Cli/dotnet/Commands/Run/Api/RunApiCommandParser.cs

+    {
+        Command command = new("run-api")
+        {
+            Hidden = true,


Is there precedent for other commands like this? Rather than having a new command can we/should we hide this behind just an --api flag on dotnet run?

I'm not an expert on dotnet.exe CLI, but I think hiding this under dotnet run --api means all the other dotnet run flags can still be passed and we would need to manually check and error on them, e.g., dotnet run --no-restore --api and so on.

jasonmalinowski · 2025-05-16T00:37:03Z

src/Cli/dotnet/Commands/Run/Api/RunApiCommand.cs

+    /// When the API shape or behavior changes, this should be incremented so the callers (IDEs) can act accordingly
+    /// (e.g., show an error message when an incompatible SDK version is being used).


I would expect that the version number isn't stated here -- we've already had to assume the shape of the output to even read this! Maybe we need to do a few more things:

The version number could stated outside of the first JSON payload (maybe just on a line of it's own), simply because by the time we're reading this value we've already more or less had to assume the JSON output format to a certain extent. This would be critical if/when we have to break the communication format more generally (i.e. we need to switch to MessagePack because this payload is getting too big to use.)

The invocation of the API command from the IDE includes as an input switch the max supported version. That way if we're in a situation where you need to ship a breaking change in the SDK to fix an issue, you can still potentially return an older version for a downlevel client until clients catch up. I recognize the SDK doesn't want to be supporting downlevel clients forever, but it could still at least be useful where if we have to ship a break in Preview n, you can drop the support in Preivew (n+1), but for that few week window while the preview is being built and folks have a mismatch of client versions, we can still negotiate a version that works.

jasonmalinowski · 2025-05-16T00:45:23Z

src/Cli/dotnet/Commands/Run/Api/RunApiCommand.cs

+{
+    public override int Execute()
+    {
+        for (string? line; (line = Console.ReadLine()) != null;)


If you haven't already created one, add a test for non-ASCII stuff being included in the stream. One "fun" discovery we had when making our own JSON protocol similar to this for the MSBuildWorkspace build host stuff was that the console code page might gets screwed up in funny ways and mangle stuff. Since we're (currently) using Newtonsoft.Json our hack was just:

https://github.com/dotnet/roslyn/blob/0d6bd9de68dc7e15165dffc8934fe2f473b2c171/src/Workspaces/MSBuild/BuildHost/Rpc/Contracts/JsonSettings.cs#L25-L27

Not sure if you have a similar option here.

jasonmalinowski · 2025-05-16T00:47:31Z

src/Cli/dotnet/Commands/Run/Api/RunApiCommand.cs

+            }
+            catch (Exception ex)
+            {
+                Respond(new RunApiOutput.Error { Message = ex.Message, Details = ex.ToString() });


Just establishing the contract -- should we also be listening to stderr as well?

should we also be listening to stderr as well?

You mean from the IDE? I think you should, although the code inside this try/catch will report all its errors as stdout json message, other code above this (like command-line parsing) might not.

jasonmalinowski · 2025-05-16T00:48:34Z

src/Cli/dotnet/Commands/Run/Api/RunApiCommand.cs

+    }
+}
+
+[JsonDerivedType(typeof(GetProject), nameof(GetProject))]


Do we want to specify a TypeDescriminator here so it's very clear we're not using the class name (which might get renamed) as the actual API contract?

jasonmalinowski · 2025-05-16T00:55:38Z

src/Cli/dotnet/Commands/Run/Api/RunApiCommand.cs

+[JsonDerivedType(typeof(Error), nameof(Error))]
+[JsonDerivedType(typeof(Project), nameof(Project))]


Same potential comment as earlier: let's have explicit type discriminators here rather than implicitly encoding a type name.

jasonmalinowski · 2025-05-16T01:02:56Z

src/Cli/dotnet/Commands/Run/VirtualProjectBuildingCommand.cs

+                    errors.Add(new SimpleDiagnostic
+                    {
+                        Location = sourceFile.GetFileLinePositionSpan(trivia.Span),
+                        Message = string.Format(CliCommandStrings.CannotConvertDirective, location),


Which language is this being localized in? I wonder if we'll need to pass something along to give you a hint.

jasonmalinowski · 2025-05-16T01:04:44Z

src/Cli/dotnet/Commands/Run/Api/RunApiCommand.cs

+
+    public sealed class GetProject : RunApiInput
+    {
+        public string? ArtifactsPath { get; init; }


What it does mean for us to pass this in? I would have imagined you were returning it?

Yes, this is optional, the SDK normally computes it, but you can overwrite it which is useful for tests. I will add a clarifying comment.

jasonmalinowski · 2025-05-16T01:05:55Z

src/Cli/dotnet/Commands/Run/VirtualProjectBuildingCommand.cs

@@ -967,6 +1009,27 @@ private Package() { }
    }
 }

+internal sealed class SimpleDiagnostic


Do we need some sort of error/warning concept?

Not right now, we can always add a severity property later, that shouldn't break compatibility

jasonmalinowski · 2025-05-16T01:08:53Z

test/dotnet.Tests/CommandTests/Run/RunFileTests.cs

+                "Path":{{ToJson(programPath)}},
+                "Span":{"Start":{"Line":1,"Character":0},"End":{"Line":1,"Character":30}{{nop}}}{{nop}}},
+                "Message":{{ToJson(string.Format(CliCommandStrings.CannotConvertDirective, $"{programPath}:2"))}}}]}
+                """.ReplaceLineEndings(""));


The JSON output is always on a single line?

Add file-based program API for use by IDE

6862110

jjonescz added the Area-run-file Items related to the "dotnet run <file>" effort label Apr 28, 2025

jjonescz requested a review from a team April 28, 2025 13:15

jjonescz marked this pull request as ready for review April 28, 2025 14:39

Copilot AI review requested due to automatic review settings April 28, 2025 14:39

Copilot AI reviewed Apr 28, 2025

View reviewed changes

RikkiGibson self-assigned this Apr 28, 2025

RikkiGibson approved these changes Apr 28, 2025

View reviewed changes

jjonescz added 2 commits April 29, 2025 11:25

Ensure we serialize only the necessary parts of location

77a88a4

Make baselines in tests more self-contained

230df16

RikkiGibson reviewed Apr 29, 2025

View reviewed changes

RikkiGibson approved these changes Apr 29, 2025

View reviewed changes

jjonescz added 2 commits April 30, 2025 11:15

Add API version number

c4366b8

Merge branch 'main' into sprint-api-cli

cf75161

RikkiGibson reviewed Apr 30, 2025

View reviewed changes

Test errors

0942d1c

RikkiGibson approved these changes Apr 30, 2025

View reviewed changes

chsienki approved these changes May 2, 2025

View reviewed changes

MiYanni reviewed May 2, 2025

View reviewed changes

jjonescz requested a review from MiYanni May 6, 2025 08:32

MiYanni approved these changes May 9, 2025

View reviewed changes

jjonescz added 2 commits May 12, 2025 10:50

Merge branch 'main' into sprint-api-cli

a3bb383

Fix nullability

ce44e0e

jjonescz merged commit bf4223b into dotnet:main May 12, 2025
30 checks passed

jjonescz deleted the sprint-api-cli branch May 12, 2025 14:17

jjonescz mentioned this pull request May 12, 2025

Add file-based program API for use by debugger #48905

Merged

jasonmalinowski reviewed May 16, 2025

View reviewed changes

RikkiGibson mentioned this pull request May 16, 2025

Adopt dotnet run-api in language server dotnet/roslyn#78618

Open

		/// When the API shape or behavior changes, this should be incremented so the callers (IDEs) can act accordingly
		/// (e.g., show an error message when an incompatible SDK version is being used).

		[JsonDerivedType(typeof(Error), nameof(Error))]
		[JsonDerivedType(typeof(Project), nameof(Project))]

Add file-based program API for use by IDE #48749

Add file-based program API for use by IDE #48749

Uh oh!

Conversation

jjonescz commented Apr 28, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

RikkiGibson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jjonescz May 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jjonescz Apr 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jjonescz Apr 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RikkiGibson Apr 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jjonescz commented May 2, 2025

Uh oh!

MiYanni left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RikkiGibson commented May 7, 2025

Uh oh!

MiYanni left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

RikkiGibson commented May 12, 2025

Uh oh!

jasonmalinowski left a comment

Choose a reason for hiding this comment

jjonescz May 8, 2025 •

edited

Loading

jjonescz Apr 29, 2025 •

edited

Loading

jjonescz Apr 29, 2025 •

edited

Loading

RikkiGibson Apr 30, 2025 •

edited

Loading