Skip to content

Commit 9dd8d80

Browse files
natemcmasternatemcmaster
committed
Add generic host documentation
Close #180
1 parent 67986e7 commit 9dd8d80

File tree

10 files changed

+104
-26
lines changed

10 files changed

+104
-26
lines changed

‎docs/docs/advanced/dependency-injection.md‎

Lines changed: 1 addition & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -56,19 +56,4 @@ Below is the full source code for the custom services example. Notice that insta
5656

5757
## Using Generic Host
5858

59-
[Generic host](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/host/generic-host?view=aspnetcore-2.1) integration allows you to use the most current DI configuration approach indicated by the aspnet project. The basic approach starts by creating the builder:
60-
61-
[!code-csharp[](../../samples/dependency-injection/generic-host/Program.cs?name=Program&range=26-26)]
62-
63-
Then you can configure your features:
64-
65-
[!code-csharp[](../../samples/dependency-injection/generic-host/Program.cs?name=Program&range=27-34)]
66-
67-
And finally, run your program:
68-
69-
[!code-csharp[](../../samples/dependency-injection/generic-host/Program.cs?name=Program&range=35-35)]
70-
71-
Below is the full source code for the generic host services example. Notice that instance of `IGreeter` will be injected into the `Program` constructor thanks to the dependency injection.
72-
73-
[!code-csharp[](../../samples/dependency-injection/custom/Program.cs?name=Program&highlight=32-32)]
74-
59+
See <xref:generic-host> for details on using Generic Host and dependency injection.

‎docs/docs/advanced/generic-host.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
uid: generic-host
3+
---
4+
# Using Generic Host
5+
6+
The McMaster.Extensions.Hosting.CommandLine package provides support for integrating command line parsing with
7+
.NET's [generic host](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/host/generic-host).
8+
9+
## Get started
10+
11+
To get started, install the `McMaster.Extensions.Hosting.CommandLine` package.
12+
The main usage for generic host is `RunCommandLineApplicationAsync<TApp>(args)`, where `TApp` is a class
13+
which will be bound to command line arguments and options using attributes and `CommandLineApplication.Execute<T>`.
14+
15+
### Sample
16+
17+
This minimal sample shows how to take advantage of generic host features, such as `IHostingEnvironment`,
18+
as well as command line parsing options with this library.
19+
20+
[!code-csharp[](../../samples/generic-host/Program.cs)]
21+
22+
## Dependency injection
23+
24+
Generic host integration allows you to use the most current DI configuration approach indicated by the aspnet project. The basic approach starts by creating the builder:
25+
26+
[!code-csharp[](../../samples/dependency-injection/generic-host/Program.cs?name=Program&range=26-26)]
27+
28+
Then you can configure your features:
29+
30+
[!code-csharp[](../../samples/dependency-injection/generic-host/Program.cs?name=Program&range=27-34)]
31+
32+
And finally, run your program:
33+
34+
[!code-csharp[](../../samples/dependency-injection/generic-host/Program.cs?name=Program&range=35-35)]
35+
36+
Below is the full source code for the generic host services example. Notice that instance of `IGreeter` will be injected into the `Program` constructor thanks to the dependency injection.
37+
38+
[!code-csharp[](../../samples/dependency-injection/custom/Program.cs?name=Program&highlight=32-32)]
39+

‎docs/docs/arguments.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ public class Program
104104

105105
### [Using Builder API](#tab/using-builder-api)
106106

107-
To enable this, See @McMaster.Extensions.CommandLineUtils.CommandArgument.MultipleValues must be set to true,
107+
To enable this, @McMaster.Extensions.CommandLineUtils.CommandArgument.MultipleValues must be set to true,
108108
and the argument must be the last one specified.
109109

110110
```c#
@@ -171,4 +171,6 @@ to include all values. See @McMaster.Extensions.CommandLineUtils.Conventions.Rem
171171
172172
### [Using Builder API](#tab/using-builder-api)
173173
174+
When `throwOnUnexpctedArg` is set to false,
175+
174176
[!code-csharp[Program](../samples/passthru-args/builder-api/Program.cs)]

‎docs/samples/dependency-injection/generic-host/GenericHost.csproj‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@
77
</PropertyGroup>
88

99
<ItemGroup>
10-
<ProjectReference Include="..\..\..\..\src\CommandLineUtils\McMaster.Extensions.CommandLineUtils.csproj" />
1110
<ProjectReference Include="..\..\..\..\src\Hosting.CommandLine\McMaster.Extensions.Hosting.CommandLine.csproj" />
1211
</ItemGroup>
1312

‎docs/samples/dependency-injection/generic-host/Program.cs‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
using McMaster.Extensions.CommandLineUtils;
1+
using System;
2+
using System.Threading;
3+
using System.Threading.Tasks;
4+
using McMaster.Extensions.CommandLineUtils;
25
using McMaster.Extensions.Hosting.CommandLine;
36
using Microsoft.Extensions.DependencyInjection;
47
using Microsoft.Extensions.Hosting;
58
using Microsoft.Extensions.Logging;
6-
using System;
7-
using System.Threading;
8-
using System.Threading.Tasks;
99

1010
namespace CustomServices
1111
{

‎docs/samples/generic-host/GenericHost.csproj‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<OutputType>Exe</OutputType>
5+
<TargetFramework>netcoreapp2.1</TargetFramework>
6+
<LangVersion>7.3</LangVersion>
7+
</PropertyGroup>
8+
9+
<ItemGroup>
10+
<ProjectReference Include="..\..\..\src\Hosting.CommandLine\McMaster.Extensions.Hosting.CommandLine.csproj" />
11+
</ItemGroup>
12+
13+
</Project>

‎docs/samples/generic-host/Program.cs‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
using System;
2+
using System.Threading.Tasks;
3+
using McMaster.Extensions.CommandLineUtils;
4+
using Microsoft.Extensions.Hosting;
5+
6+
class Program
7+
{
8+
static Task<int> Main(string[] args)
9+
=> new HostBuilder()
10+
.RunCommandLineApplicationAsync<Program>(args);
11+
12+
[Option]
13+
public int Port { get; } = 8080;
14+
15+
private IHostingEnvironment _env;
16+
17+
public Program(IHostingEnvironment env)
18+
{
19+
_env = env;
20+
}
21+
22+
private void OnExecute()
23+
{
24+
Console.WriteLine($"Starting on port {Port}, env = {_env.EnvironmentName}");
25+
}
26+
}

‎docs/samples/passthru-args/attributes/Program.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,11 +34,11 @@ private void OnExecute()
3434

3535
if (Milliseconds)
3636
{
37-
Console.WriteLine($"Time = {timer.Elapsed.TotalMilliseconds:F} ms");
37+
Console.WriteLine($"Time = {timer.Elapsed.TotalMilliseconds} ms");
3838
}
3939
else
4040
{
41-
Console.WriteLine($"Time = {timer.Elapsed.TotalSeconds:F}s");
41+
Console.WriteLine($"Time = {timer.Elapsed.TotalSeconds}s");
4242
}
4343
}
4444
}

‎docs/samples/passthru-args/builder-api/Program.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,11 +35,11 @@ public static int Main(string[] args)
3535

3636
if (showMilliseconds.HasValue())
3737
{
38-
Console.WriteLine($"Time = {timer.Elapsed.TotalMilliseconds:F} ms");
38+
Console.WriteLine($"Time = {timer.Elapsed.TotalMilliseconds} ms");
3939
}
4040
else
4141
{
42-
Console.WriteLine($"Time = {timer.Elapsed.TotalSeconds:F}s");
42+
Console.WriteLine($"Time = {timer.Elapsed.TotalSeconds}s");
4343
}
4444
});
4545

‎docs/samples/samples.sln‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "BuilderApiPassThru", "passt
5151
EndProject
5252
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AttributesPassThru", "passthru-args\attributes\AttributesPassThru.csproj", "{1EE15348-5FF4-4988-AEA4-3E267ED4C288}"
5353
EndProject
54+
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GenericHost", "generic-host\GenericHost.csproj", "{A85A6B2B-924F-48CE-8606-04B704A467D9}"
55+
EndProject
5456
Global
5557
GlobalSection(SolutionConfigurationPlatforms) = preSolution
5658
Debug|Any CPU = Debug|Any CPU
@@ -292,6 +294,18 @@ Global
292294
{1EE15348-5FF4-4988-AEA4-3E267ED4C288}.Release|x64.Build.0 = Release|Any CPU
293295
{1EE15348-5FF4-4988-AEA4-3E267ED4C288}.Release|x86.ActiveCfg = Release|Any CPU
294296
{1EE15348-5FF4-4988-AEA4-3E267ED4C288}.Release|x86.Build.0 = Release|Any CPU
297+
{A85A6B2B-924F-48CE-8606-04B704A467D9}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
298+
{A85A6B2B-924F-48CE-8606-04B704A467D9}.Debug|Any CPU.Build.0 = Debug|Any CPU
299+
{A85A6B2B-924F-48CE-8606-04B704A467D9}.Debug|x64.ActiveCfg = Debug|Any CPU
300+
{A85A6B2B-924F-48CE-8606-04B704A467D9}.Debug|x64.Build.0 = Debug|Any CPU
301+
{A85A6B2B-924F-48CE-8606-04B704A467D9}.Debug|x86.ActiveCfg = Debug|Any CPU
302+
{A85A6B2B-924F-48CE-8606-04B704A467D9}.Debug|x86.Build.0 = Debug|Any CPU
303+
{A85A6B2B-924F-48CE-8606-04B704A467D9}.Release|Any CPU.ActiveCfg = Release|Any CPU
304+
{A85A6B2B-924F-48CE-8606-04B704A467D9}.Release|Any CPU.Build.0 = Release|Any CPU
305+
{A85A6B2B-924F-48CE-8606-04B704A467D9}.Release|x64.ActiveCfg = Release|Any CPU
306+
{A85A6B2B-924F-48CE-8606-04B704A467D9}.Release|x64.Build.0 = Release|Any CPU
307+
{A85A6B2B-924F-48CE-8606-04B704A467D9}.Release|x86.ActiveCfg = Release|Any CPU
308+
{A85A6B2B-924F-48CE-8606-04B704A467D9}.Release|x86.Build.0 = Release|Any CPU
295309
EndGlobalSection
296310
GlobalSection(NestedProjects) = preSolution
297311
{3D6570C6-11DC-40E7-9C96-8936D23C606A} = {E03982B3-80F2-4D55-9501-378EACE93E5B}

0 commit comments

Comments
 (0)