Skip to content

Commit 9d217fa

Browse files
NikolayPianikovNikolayPianikov
committed
Add comments
1 parent 28cdd7a commit 9d217fa

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

48 files changed

+1078
-169
lines changed

‎CSharpInteractive.HostApi/DotNetCommands.cs‎

Lines changed: 94 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,29 @@ namespace HostApi;
1010
/// You specify the path to an application .dll file to run the application. To run the application means to find and execute the entry point, which in the case of console apps is the Main method. For example, dotnet myapp.dll runs the myapp application.
1111
/// </p>
1212
/// <br/><a href="https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet">.NET CLI command</a><br/>
13+
/// <example>
14+
///<code>
15+
/// // Adds the namespace "HostApi" to use .NET build API
16+
/// using HostApi;
17+
///
18+
/// // Creates a new console project, running a command like: "dotnet new console -n MyApp --force"
19+
/// new DotNetNew()
20+
/// .WithTemplateName("console")
21+
/// .WithName("MyApp")
22+
/// .WithForce(true)
23+
/// .Build().EnsureSuccess();
24+
///
25+
/// var tempDirectory = Path.Combine(Path.GetTempPath(), Path.GetRandomFileName());
26+
/// new DotNetPublish()
27+
/// .WithWorkingDirectory("MyApp")
28+
/// .WithOutput(tempDirectory)
29+
/// .Build().EnsureSuccess();
30+
///
31+
/// new DotNet()
32+
/// .WithPathToApplication(Path.Combine(tempDirectory, "MyApp.dll"))
33+
/// .Run().EnsureSuccess();
34+
///</code>
35+
/// </example>
1336
/// </summary>
1437
/// <param name="Args">Specifies the set of command line arguments to use when starting the tool.</param>
1538
/// <param name="Vars">Specifies the set of environment variables that apply to this process and its child processes.</param>
@@ -94,6 +117,29 @@ public IStartInfo GetStartInfo(IHost host)
94117
/// You specify the path to an application .dll file to run the application. To run the application means to find and execute the entry point, which in the case of console apps is the Main method. For example, dotnet myapp.dll runs the myapp application.
95118
/// </p>
96119
/// <br/><a href="https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet">.NET CLI command</a><br/>
120+
/// <example>
121+
///<code>
122+
/// // Adds the namespace "HostApi" to use .NET build API
123+
/// using HostApi;
124+
///
125+
/// // Creates a new console project, running a command like: "dotnet new console -n MyApp --force"
126+
/// new DotNetNew()
127+
/// .WithTemplateName("console")
128+
/// .WithName("MyApp")
129+
/// .WithForce(true)
130+
/// .Build().EnsureSuccess();
131+
///
132+
/// var tempDirectory = Path.Combine(Path.GetTempPath(), Path.GetRandomFileName());
133+
/// new DotNetPublish()
134+
/// .WithWorkingDirectory("MyApp")
135+
/// .WithOutput(tempDirectory)
136+
/// .Build().EnsureSuccess();
137+
///
138+
/// new DotNetExec()
139+
/// .WithPathToApplication(Path.Combine(tempDirectory, "MyApp.dll"))
140+
/// .Run().EnsureSuccess();
141+
///</code>
142+
/// </example>
97143
/// </summary>
98144
/// <param name="Args">Specifies the set of command line arguments to use when starting the tool.</param>
99145
/// <param name="Vars">Specifies the set of environment variables that apply to this process and its child processes.</param>
@@ -614,16 +660,37 @@ public IStartInfo GetStartInfo(IHost host)
614660
/// <p>
615661
/// 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.
616662
/// </p>
663+
/// <br/><a href="https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-build">.NET CLI command</a><br/>
617664
/// <example>
618-
/// <code>
619-
/// var configuration = Props.Get("configuration", "Release");
665+
///<code>
666+
/// // Adds the namespace "HostApi" to use .NET build API
667+
/// using HostApi;
620668
///
621-
///
622-
/// new DotNetBuild().WithConfiguration(configuration)
669+
/// // Creates a new library project, running a command like: "dotnet new classlib -n MyLib --force"
670+
/// new DotNetNew()
671+
/// .WithTemplateName("xunit")
672+
/// .WithName("MyLib")
673+
/// .WithForce(true)
623674
/// .Build().EnsureSuccess();
624-
/// </code>
675+
///
676+
/// // Builds the library project, running a command like: "dotnet build" from the directory "MyLib"
677+
/// var messages = new List&lt;BuildMessage&gt;();
678+
/// var result = new DotNetBuild()
679+
/// .WithWorkingDirectory("MyLib")
680+
/// .Build(message =&gt; messages.Add(message)).EnsureSuccess();
681+
///
682+
/// // The "result" variable provides details about a build
683+
/// messages.Count.ShouldBeGreaterThan(0, result.ToString());
684+
/// result.Errors.Any(message =&gt; message.State == BuildMessageState.StdError).ShouldBeFalse();
685+
/// result.ExitCode.ShouldBe(0);
686+
///
687+
/// // Runs tests in docker
688+
/// result = new DotNetTest()
689+
/// .WithWorkingDirectory("MyLib")
690+
/// .Build()
691+
/// .EnsureSuccess();
692+
///</code>
625693
/// </example>
626-
/// <br/><a href="https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-build">.NET CLI command</a><br/>
627694
/// </summary>
628695
/// <param name="Args">Specifies the set of command line arguments to use when starting the tool.</param>
629696
/// <param name="Vars">Specifies the set of environment variables that apply to this process and its child processes.</param>
@@ -3772,20 +3839,34 @@ public IStartInfo GetStartInfo(IHost host)
37723839
/// <p>
37733840
/// 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.
37743841
/// </p>
3842+
/// <br/><a href="https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-run">.NET CLI command</a><br/>
37753843
/// <example>
3776-
/// <code>
3777-
/// new DotNetNew()
3844+
///<code>
3845+
/// // Adds the namespace "HostApi" to use .NET build API
3846+
/// using HostApi;
3847+
///
3848+
/// // Creates a new console project, running a command like: "dotnet new console -n MyApp --force"
3849+
/// var result = new DotNetNew()
37783850
/// .WithTemplateName("console")
37793851
/// .WithName("MyApp")
37803852
/// .WithForce(true)
3781-
/// .Run().EnsureSuccess();
3853+
/// .Build().EnsureSuccess();
37823854
///
3855+
/// result.ExitCode.ShouldBe(0);
37833856
///
3784-
/// new DotNetRun().WithWorkingDirectory("MyApp")
3785-
/// .Build().EnsureSuccess();
3786-
/// </code>
3857+
/// // Runs the console project using a command like: "dotnet run" from the directory "MyApp"
3858+
/// var stdOut = new List&lt;string&gt;();
3859+
/// result = new DotNetRun()
3860+
/// .WithWorkingDirectory("MyApp")
3861+
/// .Build(message =&gt; stdOut.Add(message.Text))
3862+
/// .EnsureSuccess();
3863+
///
3864+
/// result.ExitCode.ShouldBe(0);
3865+
///
3866+
/// // Checks StdOut
3867+
/// stdOut.ShouldBe(new[] {"Hello, World!"});
3868+
///</code>
37873869
/// </example>
3788-
/// <br/><a href="https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-run">.NET CLI command</a><br/>
37893870
/// </summary>
37903871
/// <param name="Args">Specifies the set of command line arguments to use when starting the tool.</param>
37913872
/// <param name="Vars">Specifies the set of environment variables that apply to this process and its child processes.</param>

‎CSharpInteractive.HostApi/DotNetCommands.tt‎

Lines changed: 34 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<#@ import namespace="System.Linq" #>
2-
<#@ import namespace="System.Linq" #>
3-
<#@ import namespace="System.Linq" #>
42
<#@ import namespace="System.Collections.Generic" #>
3+
<#@ import namespace="System.IO" #>
4+
<#@ import namespace="System.Xml" #>
55
// ReSharper disable UnusedMember.Global
66
// ReSharper disable InconsistentNaming
77
namespace HostApi;
@@ -17,7 +17,7 @@ using Internal;
1717

1818
string CreateCliRef(string command) =>
1919
$"<br/><a href=\"https://learn.microsoft.com/en-us/dotnet/core/tools/{command}\">.NET CLI command</a><br/>";
20-
20+
2121
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 };
2222
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 };
2323
var propsArg = new Arg("Props", "--property", "IEnumerable<(string name, string value)>", "MSBuild options for setting properties.") { IsCollection = true };
@@ -85,7 +85,7 @@ using Internal;
8585
new Arg("ListRuntimes", "--list-runtimes", "bool?", "Prints out a list of the installed .NET runtimes. An x86 version of the SDK lists only x86 runtimes, and an x64 version of the SDK lists only x64 runtimes."),
8686
new Arg("ListSdks", "--list-sdks", "bool?", "Prints out a list of the installed .NET SDKs.")
8787
]
88-
),
88+
) { Example = "DotNetScenario.cs.md" },
8989
new(
9090
"DotNetExec",
9191
"Executes a dotnet application.",
@@ -106,7 +106,7 @@ using Internal;
106106
new Arg("RuntimeConfig", "--runtimeconfig", "string", "Path to a runtimeconfig.json file. A runtimeconfig.json file contains run-time settings and is typically named &lt;applicationname&gt;.runtimeconfig.json."),
107107
diagnosticsArg
108108
]
109-
),
109+
) { Example = "DotNetExecScenario.cs.md" },
110110
new(
111111
"DotNetAddPackage",
112112
"Adds or updates a package reference in a project file.",
@@ -229,15 +229,6 @@ using Internal;
229229
paraStart,
230230
"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.",
231231
paraFinish,
232-
exampleStart,
233-
codeStart,
234-
"var configuration = Props.Get(\"configuration\", \"Release\");",
235-
"",
236-
"",
237-
"new DotNetBuild().WithConfiguration(configuration)",
238-
" .Build().EnsureSuccess();",
239-
codeFinish,
240-
exampleFinish,
241232
CreateCliRef("dotnet-build")
242233
],
243234
["build", "$Project"],
@@ -267,7 +258,7 @@ using Internal;
267258
diagnosticsArg
268259
],
269260
CommandTypes.Build
270-
),
261+
) { Example = "DotNetBuildScenario.cs.md" },
271262
new(
272263
"DotNetBuildServerShutdown",
273264
"Shuts down build servers that are started from dotnet.",
@@ -1088,19 +1079,6 @@ using Internal;
10881079
paraStart,
10891080
"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.",
10901081
paraFinish,
1091-
exampleStart,
1092-
codeStart,
1093-
"new DotNetNew()",
1094-
" .WithTemplateName(\"console\")",
1095-
" .WithName(\"MyApp\")",
1096-
" .WithForce(true)",
1097-
" .Run().EnsureSuccess();",
1098-
"",
1099-
"",
1100-
"new DotNetRun().WithWorkingDirectory(\"MyApp\")",
1101-
" .Build().EnsureSuccess();",
1102-
codeFinish,
1103-
exampleFinish,
11041082
CreateCliRef("dotnet-run")
11051083
],
11061084
["run"],
@@ -1122,7 +1100,7 @@ using Internal;
11221100
verbosityArg,
11231101
diagnosticsArg
11241102
]
1125-
),
1103+
) { Example = "DotNetRunScenario.cs.md" },
11261104
new(
11271105
"DotNetSdkCheck",
11281106
"Lists the latest available version of the .NET SDK and .NET Runtime, for each feature band.",
@@ -1636,6 +1614,32 @@ using Internal;
16361614
/// <#= comment #>
16371615
<#
16381616
}
1617+
1618+
if (!string.IsNullOrWhiteSpace(command.Example))
1619+
{
1620+
var exampleLines = File.ReadAllLines(Path.Combine("..", "CSharpInteractive.Tests", "UsageScenarios", command.Example));
1621+
if (exampleLines.Length > 0)
1622+
{
1623+
#>
1624+
/// <#= exampleStart #>
1625+
///<#= codeStart #>
1626+
<#
1627+
var doc = new XmlDocument();
1628+
foreach (var exampleLine in exampleLines.Select(i => i.TrimEnd()))
1629+
{
1630+
var node = doc.CreateElement("root");
1631+
node.InnerText = exampleLine;
1632+
var line = node.InnerXml;
1633+
#>
1634+
/// <#= line #>
1635+
<#
1636+
}
1637+
#>
1638+
///<#= codeFinish #>
1639+
/// <#= exampleFinish #>
1640+
<#
1641+
}
1642+
}
16391643
#>
16401644
/// </summary>
16411645
/// <param name="Args">Specifies the set of command line arguments to use when starting the tool.</param>
@@ -1869,5 +1873,6 @@ public partial record <#= command.Name #>(
18691873
public Arg[] Args { get; } = Args;
18701874
public CommandTypes CommandTypes { get; } = CommandTypes;
18711875
public string[] AdditionalArgs { get; } = AdditionalArgs;
1876+
public string Example { get; set; } = "";
18721877
}
18731878
#>

0 commit comments

Comments
 (0)