Add comments

Author: NikolayPianikov

CSharpInteractive.HostApi/DotNetCommands.cs

@@ -1,7 +1,7 @@
 <#@ import namespace="System.Linq" #>
-<#@ import namespace="System.Linq" #>
-<#@ import namespace="System.Linq" #>
 <#@ import namespace="System.Collections.Generic" #>
+<#@ import namespace="System.IO" #>
+<#@ import namespace="System.Xml" #>
 // ReSharper disable UnusedMember.Global
 // ReSharper disable InconsistentNaming
 namespace HostApi;
@@ -17,7 +17,7 @@ using Internal;
 
     string CreateCliRef(string command) => 
         $"<br/><a href=\"https://learn.microsoft.com/en-us/dotnet/core/tools/{command}\">.NET CLI command</a><br/>";
-
+    
     var projectArg = new Arg("Project", "", "string", "The project or solution file to operate on. If not specified, the command searches the current directory for one. If more than one solution or project is found, an error is thrown.") { IsProject = true };
     var solutionArg = new Arg("Solution", "", "string", "The solution file to use. If this argument is omitted, the command searches the current directory for one. If it finds no solution file or multiple solution files, the command fails.") { IsProject = true };
     var propsArg = new Arg("Props", "--property", "IEnumerable<(string name, string value)>", "MSBuild options for setting properties.") { IsCollection = true };
@@ -229,15 +229,6 @@ using Internal;
                 paraStart,
                 "For executable projects targeting .NET Core 3.0 and later, library dependencies are copied to the output folder. This means that if there isn't any other publish-specific logic (such as Web projects have), the build output should be deployable.",
                 paraFinish,
-                exampleStart,
-                codeStart,
-                "var configuration = Props.Get(\"configuration\", \"Release\");",
-                "",
-                "",
-                "new DotNetBuild().WithConfiguration(configuration)",
-                "    .Build().EnsureSuccess();",
-                codeFinish,
-                exampleFinish,
                 CreateCliRef("dotnet-build")
             ],
             ["build", "$Project"],
@@ -1088,19 +1079,6 @@ using Internal;
                 paraStart,
                 "To run the application, the dotnet run command resolves the dependencies of the application that are outside of the shared runtime from the NuGet cache. Because it uses cached dependencies, it's not recommended to use dotnet run to run applications in production. Instead, create a deployment using the dotnet publish command and deploy the published output.",
                 paraFinish,
-                exampleStart,
-                codeStart,
-                "new DotNetNew()",
-                "    .WithTemplateName(\"console\")",
-                "    .WithName(\"MyApp\")",
-                "    .WithForce(true)",
-                "    .Run().EnsureSuccess();",
-                "",
-                "",
-                "new DotNetRun().WithWorkingDirectory(\"MyApp\")",
-                "    .Build().EnsureSuccess();",
-                codeFinish,
-                exampleFinish,
                 CreateCliRef("dotnet-run")
             ],
             ["run"],
@@ -1636,6 +1614,33 @@ using Internal;
 /// <#= comment #>
 <#
         }
+
+        var exampleFile = Path.Combine("..", "CSharpInteractive.Tests", "UsageScenarios", "Comments", $"{command.Name}Scenario.txt");
+        if (File.Exists(exampleFile))
+        {
+            var exampleLines = File.ReadAllLines(exampleFile);
+            if (exampleLines.Length > 0)
+            {
+#>
+/// <#= exampleStart #>
+///<#= codeStart #>
+<#
+                var doc = new XmlDocument();
+                foreach (var exampleLine in exampleLines.Select(i => i.TrimEnd()))
+                {
+                    var node = doc.CreateElement("root");
+                    node.InnerText = exampleLine;
+                    var line = node.InnerXml;
+#>
+/// <#= line #>
+<#
+                }
+#>
+///<#= codeFinish #>
+/// <#= exampleFinish #>
+<#
+            }
+        }
 #>
 /// </summary>
 /// <param name="Args">Specifies the set of command line arguments to use when starting the tool.</param>

CSharpInteractive.HostApi/DotNetCommands.tt

@@ -34,16 +34,19 @@
   - [Build a project](#build-a-project)
   - [Build a project using MSBuild](#build-a-project-using-msbuild)
   - [Clean a project](#clean-a-project)
+  - [Execute a dotnet application](#execute-a-dotnet-application)
   - [Pack a project](#pack-a-project)
   - [Publish a project](#publish-a-project)
   - [Restore a project](#restore-a-project)
   - [Restore local tools](#restore-local-tools)
   - [Run a custom .NET command](#run-a-custom-.net-command)
+  - [Run a dotnet application](#run-a-dotnet-application)
   - [Run a project](#run-a-project)
   - [Run tests under dotCover](#run-tests-under-dotcover)
   - [Test a project](#test-a-project)
   - [Test a project using the MSBuild VSTest target](#test-a-project-using-the-msbuild-vstest-target)
   - [Test an assembly](#test-an-assembly)
+  - [Run C# script](#run-c#-script)
   - [Shuts down build servers](#shuts-down-build-servers)
 - TeamCity API
   - [TeamCity integration via service messages](#teamcity-integration-via-service-messages)
@@ -411,8 +414,6 @@ int? exitCode = new CommandLine("cmd", "/c", "TIMEOUT", "/T", "120")
     .Run(default, TimeSpan.FromMilliseconds(1))
     .EnsureSuccess()
     .ExitCode;
-
-exitCode.HasValue.ShouldBeFalse();
 ```
 
 
@@ -447,10 +448,6 @@ var result = dockerRun
     .Build()
     .EnsureSuccess();
 
-// The "result" variable provides details about a build
-result.Errors.Any(message => message.State == BuildMessageState.StdError).ShouldBeFalse();
-result.ExitCode.ShouldBe(0);
-
 string ToAbsoluteLinuxPath(string path) =>
     "/" + path.Replace(":", "").Replace('\\', '/');
 ```
@@ -493,11 +490,13 @@ new DotNetNew()
     .Build().EnsureSuccess();
 
 // Builds the library project, running a command like: "dotnet build" from the directory "MyLib"
+var messages = new List<BuildMessage>();
 var result = new DotNetBuild()
     .WithWorkingDirectory("MyLib")
-    .Build().EnsureSuccess();
+    .Build(message => messages.Add(message)).EnsureSuccess();
 
 // The "result" variable provides details about a build
+messages.Count.ShouldBeGreaterThan(0, result.ToString());
 result.Errors.Any(message => message.State == BuildMessageState.StdError).ShouldBeFalse();
 result.ExitCode.ShouldBe(0);
 
@@ -506,10 +505,6 @@ result = new DotNetTest()
     .WithWorkingDirectory("MyLib")
     .Build()
     .EnsureSuccess();
-
-result.ExitCode.ShouldBe(0);
-result.Summary.Tests.ShouldBe(1);
-result.Tests.Count(test => test.State == TestState.Finished).ShouldBe(1);
 ```
 
 
@@ -568,6 +563,34 @@ version.ShouldNotBeNull();
 
 
 
+### Execute a dotnet application
+
+
+
+``` CSharp
+// Adds the namespace "HostApi" to use .NET build API
+using HostApi;
+
+// Creates a new console project, running a command like: "dotnet new console -n MyApp --force"
+new DotNetNew()
+    .WithTemplateName("console")
+    .WithName("MyApp")
+    .WithForce(true)
+    .Build().EnsureSuccess();
+
+var tempDirectory = Path.Combine(Path.GetTempPath(), Path.GetRandomFileName());
+new DotNetPublish()
+    .WithWorkingDirectory("MyApp")
+    .WithOutput(tempDirectory)
+    .Build().EnsureSuccess();
+
+new DotNetExec()
+    .WithPathToApplication(Path.Combine(tempDirectory, "MyApp.dll"))
+    .Run().EnsureSuccess();
+```
+
+
+
 ### Test a project using the MSBuild VSTest target
 
 
@@ -621,8 +644,6 @@ result = new DotNetPack()
     .WithWorkingDirectory("MyLib")
     .AddProps(("version", "1.2.3"))
     .Build().EnsureSuccess();
-
-result.ExitCode.ShouldBe(0);
 ```
 
 
@@ -650,8 +671,6 @@ result = new DotNetPublish()
     .WithWorkingDirectory("MyLib")
     .WithFramework("net8.0")
     .Build().EnsureSuccess();
-
-result.ExitCode.ShouldBe(0);
 ```
 
 
@@ -677,8 +696,6 @@ result.ExitCode.ShouldBe(0);
 result = new DotNetRestore()
     .WithWorkingDirectory("MyLib")
     .Build().EnsureSuccess();
-
-result.ExitCode.ShouldBe(0);
 ```
 
 
@@ -702,7 +719,8 @@ result.ExitCode.ShouldBe(0);
 
 // Runs the console project using a command like: "dotnet run" from the directory "MyApp"
 var stdOut = new List<string>();
-result = new DotNetRun().WithWorkingDirectory("MyApp")
+result = new DotNetRun()
+    .WithWorkingDirectory("MyApp")
     .Build(message => stdOut.Add(message.Text))
     .EnsureSuccess();
 
@@ -714,6 +732,34 @@ stdOut.ShouldBe(new[] {"Hello, World!"});
 
 
 
+### Run a dotnet application
+
+
+
+``` CSharp
+// Adds the namespace "HostApi" to use .NET build API
+using HostApi;
+
+// Creates a new console project, running a command like: "dotnet new console -n MyApp --force"
+new DotNetNew()
+    .WithTemplateName("console")
+    .WithName("MyApp")
+    .WithForce(true)
+    .Build().EnsureSuccess();
+
+var tempDirectory = Path.Combine(Path.GetTempPath(), Path.GetRandomFileName());
+new DotNetPublish()
+    .WithWorkingDirectory("MyApp")
+    .WithOutput(tempDirectory)
+    .Build().EnsureSuccess();
+
+new DotNet()
+    .WithPathToApplication(Path.Combine(tempDirectory, "MyApp.dll"))
+    .Run().EnsureSuccess();
+```
+
+
+
 ### Test a project
 
 
@@ -738,9 +784,9 @@ result = new DotNetTest()
     .EnsureSuccess();
 
 // The "result" variable provides details about a build
-result.ExitCode.ShouldBe(0);
-result.Summary.Tests.ShouldBe(1);
-result.Tests.Count(test => test.State == TestState.Finished).ShouldBe(1);
+result.ExitCode.ShouldBe(0, result.ToString());
+result.Summary.Tests.ShouldBe(1, result.ToString());
+result.Tests.Count(test => test.State == TestState.Finished).ShouldBe(1, result.ToString());
 ```
 
 
@@ -792,8 +838,8 @@ var result = testUnderDotCover
     .Build().EnsureSuccess();
 
 // The "result" variable provides details about a build
-result.ExitCode.ShouldBe(0);
-result.Tests.Count(i => i.State == TestState.Finished).ShouldBe(1);
+result.ExitCode.ShouldBe(0, result.ToString());
+result.Tests.Count(i => i.State == TestState.Finished).ShouldBe(1, result.ToString());
 
 // Generates a HTML code coverage report.
 new DotNetCustom("dotCover", "report", $"--source={dotCoverSnapshot}", $"--output={dotCoverReport}", "--reportType=HTML")
@@ -847,7 +893,7 @@ var result = new DotNetNew()
     .WithForce(true)
     .Build().EnsureSuccess();
 
-result.ExitCode.ShouldBe(0);
+result.ExitCode.ShouldBe(0, result.ToString());
 
 // Builds the test project, running a command like: "dotnet build -c Release" from the directory "MyTests"
 result = new DotNetBuild()
@@ -856,7 +902,7 @@ result = new DotNetBuild()
     .WithOutput("MyOutput")
     .Build().EnsureSuccess();
 
-result.ExitCode.ShouldBe(0);
+result.ExitCode.ShouldBe(0, result.ToString());
 
 // Runs tests via a command like: "dotnet vstest" from the directory "MyTests"
 result = new VSTest()
@@ -865,9 +911,9 @@ result = new VSTest()
     .Build().EnsureSuccess();
 
 // The "result" variable provides details about a build
-result.ExitCode.ShouldBe(0);
-result.Summary.Tests.ShouldBe(1);
-result.Tests.Count(test => test.State == TestState.Finished).ShouldBe(1);
+result.ExitCode.ShouldBe(0, result.ToString());
+result.Summary.Tests.ShouldBe(1, result.ToString());
+result.Tests.Count(test => test.State == TestState.Finished).ShouldBe(1, result.ToString());
 ```
 
 
@@ -887,7 +933,7 @@ var result = new DotNetNew()
     .WithForce(true)
     .Build().EnsureSuccess();
 
-result.ExitCode.ShouldBe(0);
+result.ExitCode.ShouldBe(0, result.ToString());
 
 // Builds the library project, running a command like: "dotnet msbuild /t:Build -restore /p:configuration=Release -verbosity=detailed" from the directory "MyLib"
 result = new MSBuild()
@@ -899,8 +945,8 @@ result = new MSBuild()
     .Build().EnsureSuccess();
 
 // The "result" variable provides details about a build
-result.Errors.Any(message => message.State == BuildMessageState.StdError).ShouldBeFalse();
-result.ExitCode.ShouldBe(0);
+result.Errors.Any(message => message.State == BuildMessageState.StdError).ShouldBeFalse(result.ToString());
+result.ExitCode.ShouldBe(0, result.ToString());
 ```
 
 
@@ -921,6 +967,32 @@ new DotNetBuildServerShutdown()
 
 
 
+### Run C# script
+
+
+
+``` CSharp
+// Adds the namespace "HostApi" to use .NET build API
+using HostApi;
+
+var script = Path.GetTempFileName();
+File.WriteAllText(script, "Console.WriteLine($\"Hello, {Args[0]}!\");");
+
+var stdOut = new List<string>();
+var result = new DotNetCsi()
+    .WithScript(script)
+    .AddArgs("World")
+    .Build(message => stdOut.Add(message.Text))
+    .EnsureSuccess();
+
+result.ExitCode.ShouldBe(0);
+
+// Checks StdOut
+stdOut.Contains("Hello, World!").ShouldBeTrue(result.ToString());
+```
+
+
+
 ### TeamCity integration via service messages
 
 For more details how to use TeamCity service message API please see [this](https://github.com/JetBrains/TeamCity.ServiceMessages) page. Instead of creating a root message writer like in the following example: