Add generic host documentation

Close #180
natemcmaster · Dec 4, 2018 · 9dd8d80 · 9dd8d80
1 parent 67986e7
commit 9dd8d80
Show file tree

Hide file tree

Showing 10 changed files with 104 additions and 26 deletions.
diff --git a/docs/docs/advanced/dependency-injection.md b/docs/docs/advanced/dependency-injection.md
@@ -56,19 +56,4 @@ Below is the full source code for the custom services example. Notice that insta
 
 ## Using Generic Host
 
-[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:
-
-[!code-csharp[](../../samples/dependency-injection/generic-host/Program.cs?name=Program&range=26-26)]
-
-Then you can configure your features:
-
-[!code-csharp[](../../samples/dependency-injection/generic-host/Program.cs?name=Program&range=27-34)]
-
-And finally, run your program:
-
-[!code-csharp[](../../samples/dependency-injection/generic-host/Program.cs?name=Program&range=35-35)]
-
-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.
-
-[!code-csharp[](../../samples/dependency-injection/custom/Program.cs?name=Program&highlight=32-32)]
-
+See <xref:generic-host> for details on using Generic Host and dependency injection.
diff --git a/docs/docs/advanced/generic-host.md b/docs/docs/advanced/generic-host.md
@@ -0,0 +1,39 @@
+---
+uid: generic-host
+---
+# Using Generic Host
+
+The McMaster.Extensions.Hosting.CommandLine package provides support for integrating command line parsing with
+.NET's [generic host](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/host/generic-host).
+
+## Get started
+
+To get started, install the `McMaster.Extensions.Hosting.CommandLine` package.
+The main usage for generic host is `RunCommandLineApplicationAsync<TApp>(args)`, where `TApp` is a class
+which will be bound to command line arguments and options using attributes and `CommandLineApplication.Execute<T>`.
+
+### Sample
+
+This minimal sample shows how to take advantage of generic host features, such as `IHostingEnvironment`,
+as well as command line parsing options with this library.
+
+[!code-csharp[](../../samples/generic-host/Program.cs)]
+
+## Dependency injection
+
+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:
+
+[!code-csharp[](../../samples/dependency-injection/generic-host/Program.cs?name=Program&range=26-26)]
+
+Then you can configure your features:
+
+[!code-csharp[](../../samples/dependency-injection/generic-host/Program.cs?name=Program&range=27-34)]
+
+And finally, run your program:
+
+[!code-csharp[](../../samples/dependency-injection/generic-host/Program.cs?name=Program&range=35-35)]
+
+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.
+
+[!code-csharp[](../../samples/dependency-injection/custom/Program.cs?name=Program&highlight=32-32)]
+
diff --git a/docs/docs/arguments.md b/docs/docs/arguments.md
@@ -104,7 +104,7 @@ public class Program
 
 ### [Using Builder API](#tab/using-builder-api)
 
-To enable this, See @McMaster.Extensions.CommandLineUtils.CommandArgument.MultipleValues must be set to true,
+To enable this, @McMaster.Extensions.CommandLineUtils.CommandArgument.MultipleValues must be set to true,
 and the argument must be the last one specified.
 
 ```c#
@@ -171,4 +171,6 @@ to include all values. See @McMaster.Extensions.CommandLineUtils.Conventions.Rem
 
 ### [Using Builder API](#tab/using-builder-api)
 
+When `throwOnUnexpctedArg` is set to false,
+
 [!code-csharp[Program](../samples/passthru-args/builder-api/Program.cs)]
diff --git a/docs/samples/dependency-injection/generic-host/GenericHost.csproj b/docs/samples/dependency-injection/generic-host/GenericHost.csproj
@@ -7,7 +7,6 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\CommandLineUtils\McMaster.Extensions.CommandLineUtils.csproj" />
     <ProjectReference Include="..\..\..\..\src\Hosting.CommandLine\McMaster.Extensions.Hosting.CommandLine.csproj" />
   </ItemGroup>
 

diff --git a/docs/samples/dependency-injection/generic-host/Program.cs b/docs/samples/dependency-injection/generic-host/Program.cs
@@ -1,11 +1,11 @@
-using McMaster.Extensions.CommandLineUtils;
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using McMaster.Extensions.CommandLineUtils;
 using McMaster.Extensions.Hosting.CommandLine;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Logging;
-using System;
-using System.Threading;
-using System.Threading.Tasks;
 
 namespace CustomServices
 {

diff --git a/docs/samples/generic-host/GenericHost.csproj b/docs/samples/generic-host/GenericHost.csproj
@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>netcoreapp2.1</TargetFramework>
+    <LangVersion>7.3</LangVersion>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Hosting.CommandLine\McMaster.Extensions.Hosting.CommandLine.csproj" />
+  </ItemGroup>
+
+</Project>
diff --git a/docs/samples/generic-host/Program.cs b/docs/samples/generic-host/Program.cs
@@ -0,0 +1,26 @@
+using System;
+using System.Threading.Tasks;
+using McMaster.Extensions.CommandLineUtils;
+using Microsoft.Extensions.Hosting;
+
+class Program
+{
+    static Task<int> Main(string[] args)
+        => new HostBuilder()
+        .RunCommandLineApplicationAsync<Program>(args);
+
+    [Option]
+    public int Port { get; } = 8080;
+
+    private IHostingEnvironment _env;
+
+    public Program(IHostingEnvironment env)
+    {
+        _env = env;
+    }
+
+    private void OnExecute()
+    {
+        Console.WriteLine($"Starting on port {Port}, env = {_env.EnvironmentName}");
+    }
+}
diff --git a/docs/samples/passthru-args/attributes/Program.cs b/docs/samples/passthru-args/attributes/Program.cs
@@ -34,11 +34,11 @@ private void OnExecute()
 
         if (Milliseconds)
         {
-            Console.WriteLine($"Time = {timer.Elapsed.TotalMilliseconds:F} ms");
+            Console.WriteLine($"Time = {timer.Elapsed.TotalMilliseconds} ms");
         }
         else
         {
-            Console.WriteLine($"Time = {timer.Elapsed.TotalSeconds:F}s");
+            Console.WriteLine($"Time = {timer.Elapsed.TotalSeconds}s");
         }
     }
 }
diff --git a/docs/samples/passthru-args/builder-api/Program.cs b/docs/samples/passthru-args/builder-api/Program.cs
@@ -35,11 +35,11 @@ public static int Main(string[] args)
 
             if (showMilliseconds.HasValue())
             {
-                Console.WriteLine($"Time = {timer.Elapsed.TotalMilliseconds:F} ms");
+                Console.WriteLine($"Time = {timer.Elapsed.TotalMilliseconds} ms");
             }
             else
             {
-                Console.WriteLine($"Time = {timer.Elapsed.TotalSeconds:F}s");
+                Console.WriteLine($"Time = {timer.Elapsed.TotalSeconds}s");
             }
         });
 

diff --git a/docs/samples/samples.sln b/docs/samples/samples.sln
@@ -51,6 +51,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "BuilderApiPassThru", "passt
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "AttributesPassThru", "passthru-args\attributes\AttributesPassThru.csproj", "{1EE15348-5FF4-4988-AEA4-3E267ED4C288}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GenericHost", "generic-host\GenericHost.csproj", "{A85A6B2B-924F-48CE-8606-04B704A467D9}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -292,6 +294,18 @@ Global
 		{1EE15348-5FF4-4988-AEA4-3E267ED4C288}.Release|x64.Build.0 = Release|Any CPU
 		{1EE15348-5FF4-4988-AEA4-3E267ED4C288}.Release|x86.ActiveCfg = Release|Any CPU
 		{1EE15348-5FF4-4988-AEA4-3E267ED4C288}.Release|x86.Build.0 = Release|Any CPU
+		{A85A6B2B-924F-48CE-8606-04B704A467D9}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{A85A6B2B-924F-48CE-8606-04B704A467D9}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{A85A6B2B-924F-48CE-8606-04B704A467D9}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{A85A6B2B-924F-48CE-8606-04B704A467D9}.Debug|x64.Build.0 = Debug|Any CPU
+		{A85A6B2B-924F-48CE-8606-04B704A467D9}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{A85A6B2B-924F-48CE-8606-04B704A467D9}.Debug|x86.Build.0 = Debug|Any CPU
+		{A85A6B2B-924F-48CE-8606-04B704A467D9}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{A85A6B2B-924F-48CE-8606-04B704A467D9}.Release|Any CPU.Build.0 = Release|Any CPU
+		{A85A6B2B-924F-48CE-8606-04B704A467D9}.Release|x64.ActiveCfg = Release|Any CPU
+		{A85A6B2B-924F-48CE-8606-04B704A467D9}.Release|x64.Build.0 = Release|Any CPU
+		{A85A6B2B-924F-48CE-8606-04B704A467D9}.Release|x86.ActiveCfg = Release|Any CPU
+		{A85A6B2B-924F-48CE-8606-04B704A467D9}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{3D6570C6-11DC-40E7-9C96-8936D23C606A} = {E03982B3-80F2-4D55-9501-378EACE93E5B}