diff --git a/docs/experimental-features.md b/docs/experimental-features.md index 32cb5103291..533d2292cf1 100644 --- a/docs/experimental-features.md +++ b/docs/experimental-features.md @@ -47,8 +47,5 @@ Should be enabled in tandem with `assertions` experimental feature flag for expe ### `publish-provider` CLI Command Command that allows the publishing of providers to container registries. For more information, see [Using the Publish Provider Command](./experimental/publish-provider-command.md). -### `jsonrpc` CLI Command -Command that launches the CLI in a JSONRPC server mode. Useful for invoking the CLI programatically to consume structured output, and to avoid cold-start delays when compiling multiple files. For more information, see [Using the JSONRPC Command](./experimental/jsonrpc-command.md). - ### Deployment Pane The Deployment Pane is a UI panel in VSCode that allows you to connect to your Azure subscription and execute validate, deploy & whatif operations and get instant feedback without leaving the editor. For more information, see [Using the Deployment Pane](./experimental/deploy-ui.md). diff --git a/src/Bicep.Cli.IntegrationTests/JsonRpcCommandTests.cs b/src/Bicep.Cli.IntegrationTests/JsonRpcCommandTests.cs index 0e667c2d0fe..8a5082336a7 100644 --- a/src/Bicep.Cli.IntegrationTests/JsonRpcCommandTests.cs +++ b/src/Bicep.Cli.IntegrationTests/JsonRpcCommandTests.cs @@ -32,7 +32,7 @@ await Task.WhenAll( { var result = await Bicep(registerAction, cts.Token, "jsonrpc", "--pipe", pipeName); result.ExitCode.Should().Be(0); - result.Stderr.Should().EqualIgnoringNewlines("WARNING: The 'jsonrpc' CLI command group is an experimental feature. Experimental features should be enabled for testing purposes only, as there are no guarantees about the quality or stability of these features. Do not enable these settings for any production usage, or your production environment may be subject to breaking.\n"); + result.Stderr.Should().Be(""); result.Stdout.Should().Be(""); }), Task.Run(async () => diff --git a/src/Bicep.Cli/Commands/JsonRpcCommand.cs b/src/Bicep.Cli/Commands/JsonRpcCommand.cs index 85b826ec595..abb86f90be9 100644 --- a/src/Bicep.Cli/Commands/JsonRpcCommand.cs +++ b/src/Bicep.Cli/Commands/JsonRpcCommand.cs @@ -26,8 +26,6 @@ public JsonRpcCommand(BicepCompiler compiler, IOContext io) public async Task RunAsync(JsonRpcArguments args, CancellationToken cancellationToken) { - await io.Error.WriteLineAsync("WARNING: The 'jsonrpc' CLI command group is an experimental feature. Experimental features should be enabled for testing purposes only, as there are no guarantees about the quality or stability of these features. Do not enable these settings for any production usage, or your production environment may be subject to breaking."); - if (args.Pipe is { } pipeName) { if (pipeName.StartsWith(@"\\.\pipe\")) diff --git a/src/Bicep.Cli/Commands/RootCommand.cs b/src/Bicep.Cli/Commands/RootCommand.cs index ac743117d47..a0cd964d5d5 100644 --- a/src/Bicep.Cli/Commands/RootCommand.cs +++ b/src/Bicep.Cli/Commands/RootCommand.cs @@ -227,6 +227,18 @@ bicep build-params params.bicepparam --outfile otherParams.json bicep build-params params.bicepparam --no-restore bicep build-params params.bicepparam --diagnostics-format sarif + {exeName} jsonrpc [options] + Runs a JSONRPC server for interacting with Bicep programatically. + + Options: + --pipe Runs the JSONRPC server using a named pipe. + --socket Runs the JSONRPC server on a specific port. + --stdio Runs the JSONRPC server over stdin/stdout. + + Examples: + bicep jsonrpc --pipe /path/to/pipe.sock + bicep jsonrpc --stdio + "; // this newline is intentional io.Output.Write(output); diff --git a/src/Bicep.Cli/Rpc/CliJsonRpcServer.cs b/src/Bicep.Cli/Rpc/CliJsonRpcServer.cs index 879e03a4e07..c6da811f873 100644 --- a/src/Bicep.Cli/Rpc/CliJsonRpcServer.cs +++ b/src/Bicep.Cli/Rpc/CliJsonRpcServer.cs @@ -36,6 +36,7 @@ public CliJsonRpcServer(BicepCompiler compiler) this.compiler = compiler; } + /// public async Task Version(VersionRequest request, CancellationToken cancellationToken) { await Task.Yield(); @@ -44,6 +45,7 @@ public async Task Version(VersionRequest request, CancellationT ThisAssembly.AssemblyInformationalVersion.Split('+')[0]); } + /// public async Task Compile(CompileRequest request, CancellationToken cancellationToken) { var model = await GetSemanticModel(compiler, request.Path); @@ -58,6 +60,7 @@ public async Task Compile(CompileRequest request, CancellationT return new(success, diagnostics, success ? writer.ToString() : null); } + /// public async Task CompileParams(CompileParamsRequest request, CancellationToken cancellationToken) { var model = await GetSemanticModel(compiler, request.Path); @@ -81,6 +84,7 @@ public async Task CompileParams(CompileParamsRequest requ paramsResult.TemplateSpecId); } + /// public async Task GetFileReferences(GetFileReferencesRequest request, CancellationToken cancellationToken) { var model = await GetSemanticModel(compiler, request.Path); @@ -101,6 +105,7 @@ public async Task GetFileReferences(GetFileReferences [.. fileUris.Select(x => x.LocalPath).OrderBy(x => x)]); } + /// public async Task GetMetadata(GetMetadataRequest request, CancellationToken cancellationToken) { var model = await GetSemanticModel(compiler, request.Path); diff --git a/src/Bicep.Cli/Rpc/ICliJsonRpcProtocol.cs b/src/Bicep.Cli/Rpc/ICliJsonRpcProtocol.cs index 65068889eed..f92f6daf524 100644 --- a/src/Bicep.Cli/Rpc/ICliJsonRpcProtocol.cs +++ b/src/Bicep.Cli/Rpc/ICliJsonRpcProtocol.cs @@ -101,23 +101,47 @@ public record Edge( string Target); } +/// +/// The definition for the Bicep CLI JSONRPC interface. +/// +/// +/// As of Bicep 0.29, this interface is no longer "experimental". Please consider carefully whether you are making a change that may break backwards compatibility. +/// public interface ICliJsonRpcProtocol { + /// + /// Returns the version of the Bicep CLI. + /// [JsonRpcMethod("bicep/version", UseSingleObjectParameterDeserialization = true)] Task Version(VersionRequest request, CancellationToken cancellationToken); + /// + /// Compiles a specified .bicep file. + /// [JsonRpcMethod("bicep/compile", UseSingleObjectParameterDeserialization = true)] Task Compile(CompileRequest request, CancellationToken cancellationToken); + /// + /// Compiles a specified .bicepparam file. + /// [JsonRpcMethod("bicep/compileParams", UseSingleObjectParameterDeserialization = true)] Task CompileParams(CompileParamsRequest request, CancellationToken cancellationToken); + /// + /// Returns metadata about a specified .bicep file. + /// [JsonRpcMethod("bicep/getMetadata", UseSingleObjectParameterDeserialization = true)] Task GetMetadata(GetMetadataRequest request, CancellationToken cancellationToken); + /// + /// Returns the deployment graph for a specified .bicep file. + /// [JsonRpcMethod("bicep/getDeploymentGraph", UseSingleObjectParameterDeserialization = true)] Task GetDeploymentGraph(GetDeploymentGraphRequest request, CancellationToken cancellationToken); + /// + /// Gets the full list of file paths that are referenced by a compilation. Useful to determine a set of files to watch for changes. + /// [JsonRpcMethod("bicep/getFileReferences", UseSingleObjectParameterDeserialization = true)] Task GetFileReferences(GetFileReferencesRequest request, CancellationToken cancellationToken); }