Merge pull request #456 from dotnet-maestro-bot/merge/release/2.2-to-…

…master

[automated] Merge branch 'release/2.2' => 'master'

build/dependencies.props

@@ -16,6 +16,7 @@
     <MicrosoftEntityFrameworkCoreInMemoryPackageVersion>3.0.0-alpha1-10173</MicrosoftEntityFrameworkCoreInMemoryPackageVersion>
     <MicrosoftEntityFrameworkCoreRelationalPackageVersion>3.0.0-alpha1-10173</MicrosoftEntityFrameworkCoreRelationalPackageVersion>
     <MicrosoftEntityFrameworkCoreSqlServerPackageVersion>3.0.0-alpha1-10173</MicrosoftEntityFrameworkCoreSqlServerPackageVersion>
+    <MicrosoftExtensionsConfigurationCommandLinePackageVersion>3.0.0-alpha1-10173</MicrosoftExtensionsConfigurationCommandLinePackageVersion>
     <MicrosoftExtensionsDependencyInjectionAbstractionsPackageVersion>3.0.0-alpha1-10173</MicrosoftExtensionsDependencyInjectionAbstractionsPackageVersion>
     <MicrosoftExtensionsDependencyInjectionPackageVersion>3.0.0-alpha1-10173</MicrosoftExtensionsDependencyInjectionPackageVersion>
     <MicrosoftExtensionsDiagnosticAdapterPackageVersion>3.0.0-alpha1-10173</MicrosoftExtensionsDiagnosticAdapterPackageVersion>

samples/HealthChecksSample/BasicStartup.cs

@@ -0,0 +1,35 @@
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace HealthChecksSample
+{
+    // Pass in `--scenario basic` at the command line to run this sample.
+    public class BasicStartup
+    {
+        public void ConfigureServices(IServiceCollection services)
+        {
+            // Registers required services for health checks
+            services.AddHealthChecks();
+        }
+
+        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
+        {
+            // This will register the health checks middleware at the URL /health.
+            // 
+            // By default health checks will return a 200 with 'Healthy'.
+            // - No health checks are registered by default, the app is healthy if it is reachable
+            // - The default response writer writes the HealthCheckStatus as text/plain content
+            //
+            // This is the simplest way to use health checks, it is suitable for systems
+            // that want to check for 'liveness' of an application.
+            app.UseHealthChecks("/health");
+
+            app.Run(async (context) =>
+            {
+                await context.Response.WriteAsync("Go to /health to see the health status");
+            });
+        }
+    }
+}

samples/HealthChecksSample/CustomWriterStartup.cs

@@ -0,0 +1,67 @@
+using System.Linq;
+using System.Threading.Tasks;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Diagnostics.HealthChecks;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+
+namespace HealthChecksSample
+{
+    // Pass in `--scenario writer` at the command line to run this sample.
+    public class CustomWriterStartup
+    {
+        public void ConfigureServices(IServiceCollection services)
+        {
+            // Registers required services for health checks
+            services.AddHealthChecks();
+
+            // This is an example of registering a custom health check as a service.
+            // All IHealthCheck services will be available to the health check service and
+            // middleware.
+            //
+            // We recommend registering all health checks as Singleton services.
+            services.AddSingleton<IHealthCheck, GCInfoHealthCheck>();
+        }
+
+        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
+        {
+            // This will register the health checks middleware at the URL /health
+            // 
+            // This example overrides the HealthCheckResponseWriter to write the health
+            // check result in a totally custom way.
+            app.UseHealthChecks("/health", new HealthCheckOptions()
+            {
+                // This custom writer formats the detailed status as an HTML table.
+                ResponseWriter = WriteResponse,
+            });
+
+            app.Run(async (context) =>
+            {
+                await context.Response.WriteAsync("Go to /health to see the health status");
+            });
+        }
+
+        private static Task WriteResponse(HttpContext httpContext, CompositeHealthCheckResult result)
+        {
+            httpContext.Response.ContentType = "text/html";
+            return httpContext.Response.WriteAsync($@"
+<html>
+  <body>
+    <h1>
+      Everything is {result.Status}
+    </h1>
+    <table>
+      <thead>
+        <tr><td>Name</td><td>Status</td></tr>
+      </thead>
+      <tbody>
+        {string.Join("", result.Results.Select(kvp => $"<tr><td>{kvp.Key}</td><td>{kvp.Value.Status}</td></tr>"))}
+      </tbody>
+    </table>
+  </body>
+</html>");
+        }
+    }
+}

samples/HealthChecksSample/DetailedStatusStartup.cs

@@ -0,0 +1,68 @@
+using System;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Diagnostics.HealthChecks;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+
+namespace HealthChecksSample
+{
+    // Pass in `--scenario detailed` at the command line to run this sample.
+    public class DetailedStatusStartup
+    {
+        public void ConfigureServices(IServiceCollection services)
+        {
+            // Registers required services for health checks
+            services
+                .AddHealthChecks()
+
+                // Registers a custom health check, in this case it will execute an
+                // inline delegate.
+                .AddCheck("GC Info", () =>
+                {
+                    // This example will report degraded status if the application is using
+                    // more than 1gb of memory.
+                    //
+                    // Additionally we include some GC info in the reported diagnostics.
+                    var allocated = GC.GetTotalMemory(forceFullCollection: false);
+                    var data = new Dictionary<string, object>()
+                    {
+                        { "Allocated", allocated },
+                        { "Gen0Collections", GC.CollectionCount(0) },
+                        { "Gen1Collections", GC.CollectionCount(1) },
+                        { "Gen2Collections", GC.CollectionCount(2) },
+                    };
+
+                    // Report degraded status if the allocated memory is >= 1gb (in bytes)
+                    var status = allocated >= 1024 * 1024 * 1024 ? HealthCheckStatus.Degraded : HealthCheckStatus.Healthy;
+
+                    return Task.FromResult(new HealthCheckResult(
+                        status, 
+                        exception: null,
+                        description: "reports degraded status if allocated bytes >= 1gb",
+                        data: data));
+                });
+        }
+
+        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
+        {
+            // This will register the health checks middleware at the URL /health
+            // 
+            // This example overrides the ResponseWriter to include a detailed
+            // status as JSON. Use this response writer (or create your own) to include
+            // detailed diagnostic information for use by a monitoring system.
+            app.UseHealthChecks("/health", new HealthCheckOptions()
+            {
+                ResponseWriter = HealthCheckResponseWriters.WriteDetailedJson,
+            });
+
+            app.Run(async (context) =>
+            {
+                await context.Response.WriteAsync("Go to /health to see the health status");
+            });
+        }
+    }
+}

samples/HealthChecksSample/GCInfoHealthCheck.cs

@@ -0,0 +1,41 @@
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+
+namespace HealthChecksSample
+{
+    // This is an example of a custom health check that implements IHealthCheck.
+    // This is the same core logic as the DetailedStatusStartup example.
+    // See CustomWriterStartup to see how this is registered.
+    public class GCInfoHealthCheck : IHealthCheck
+    {
+        public string Name { get; } = "GCInfo";
+
+        public Task<HealthCheckResult> CheckHealthAsync(CancellationToken cancellationToken = default(CancellationToken))
+        {
+            // This example will report degraded status if the application is using
+            // more than 1gb of memory.
+            //
+            // Additionally we include some GC info in the reported diagnostics.
+            var allocated = GC.GetTotalMemory(forceFullCollection: false);
+            var data = new Dictionary<string, object>()
+            {
+                { "Allocated", allocated },
+                { "Gen0Collections", GC.CollectionCount(0) },
+                { "Gen1Collections", GC.CollectionCount(1) },
+                { "Gen2Collections", GC.CollectionCount(2) },
+            };
+
+            // Report degraded status if the allocated memory is >= 1gb (in bytes)
+            var status = allocated >= 1024 * 1024 * 1024 ? HealthCheckStatus.Degraded : HealthCheckStatus.Healthy;
+
+            return Task.FromResult(new HealthCheckResult(
+                status,
+                exception: null,
+                description: "reports degraded status if allocated bytes >= 1gb",
+                data: data));
+        }
+    }
+}

samples/HealthChecksSample/HealthChecksSample.csproj

@@ -1,10 +1,13 @@
-<Project Sdk="Microsoft.NET.Sdk.Web">
+<Project Sdk="Microsoft.NET.Sdk.Web">
 
   <PropertyGroup>
-    <TargetFramework>netcoreapp2.0</TargetFramework>
+    <!-- Used in our tests -->
+    <TargetFrameworks Condition="'$(OS)' == 'Windows_NT'">netcoreapp2.0;net461</TargetFrameworks>
+    <TargetFrameworks Condition="'$(TargetFrameworks)'==''">netcoreapp2.0</TargetFrameworks>
   </PropertyGroup>
 
   <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration.CommandLine" Version="$(MicrosoftExtensionsConfigurationCommandLinePackageVersion)" />
     <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="$(MicrosoftExtensionsLoggingConsolePackageVersion)" />
     <PackageReference Include="Microsoft.AspNetCore.Server.Kestrel" Version="$(MicrosoftAspNetCoreServerKestrelPackageVersion)" />
     <PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="$(MicrosoftAspNetCoreStaticFilesPackageVersion)" />

samples/HealthChecksSample/LivenessProbeStartup.cs

@@ -0,0 +1,80 @@
+using System;
+using System.Threading.Tasks;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Diagnostics.HealthChecks;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Diagnostics.HealthChecks;
+
+namespace HealthChecksSample
+{
+    // Pass in `--scenario liveness` at the command line to run this sample.
+    public class LivenessProbeStartup
+    {
+        public void ConfigureServices(IServiceCollection services)
+        {
+            // Registers required services for health checks
+            services
+                .AddHealthChecks()
+                .AddCheck("identity", () => Task.FromResult(HealthCheckResult.Healthy()))
+                .AddCheck(new SlowDependencyHealthCheck());
+        }
+
+        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
+        {
+            // This will register the health checks middleware twice:
+            // - at /health/ready for 'readiness'
+            // - at /health/live for 'liveness'
+            //
+            // Using a separate liveness and readiness check is useful in an environment like Kubernetes
+            // when an application needs to do significant work before accepting requests. Using separate
+            // checks allows the orchestrator to distinguish whether the application is functioning but 
+            // not yet ready or if the application has failed to start.
+            //
+            // For instance the liveness check will do a quick set of checks to determine if the process
+            // is functioning correctly.
+            //
+            // The readiness check might do a set of more expensive or time-consuming checks to determine
+            // if all other resources are responding.
+            //
+            // See https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/ for
+            // more details about readiness and liveness probes in Kubernetes.
+            //
+            // In this example, the liveness check will us an 'identity' check that always returns healthy.
+            //
+            // In this example, the readiness check will run all registered checks, include a check with an 
+            // long initialization time (15 seconds).
+
+
+            // The readiness check uses all of the registered health checks (default)
+            app.UseHealthChecks("/health/ready", new HealthCheckOptions()
+            {
+                // This sample is using detailed status to make more apparent which checks are being run - any
+                // output format will work with liveness and readiness checks.
+                ResponseWriter = HealthCheckResponseWriters.WriteDetailedJson,
+            });
+
+            // The liveness check uses an 'identity' health check that always returns healty
+            app.UseHealthChecks("/health/live", new HealthCheckOptions()
+            {
+                // Filters the set of health checks run by this middleware
+                HealthCheckNames =
+                {
+                    "identity",
+                },
+
+                // This sample is using detailed status to make more apparent which checks are being run - any
+                // output format will work with liveness and readiness checks.
+                ResponseWriter = HealthCheckResponseWriters.WriteDetailedJson,
+            });
+
+            app.Run(async (context) =>
+            {
+                await context.Response.WriteAsync("Go to /health/ready to see the readiness status");
+                await context.Response.WriteAsync(Environment.NewLine);
+                await context.Response.WriteAsync("Go to /health/live to see the liveness status");
+            });
+        }
+    }
+}

samples/HealthChecksSample/Program.cs

@@ -1,23 +1,55 @@
+using System;
+using System.Collections.Generic;
 using Microsoft.AspNetCore.Hosting;
+using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.Logging;
 
 namespace HealthChecksSample
 {
     public class Program
     {
+        private static readonly Dictionary<string, Type> _scenarios;
+
+        static Program()
+        {
+            _scenarios = new Dictionary<string, Type>(StringComparer.OrdinalIgnoreCase)
+            {
+                { "", typeof(BasicStartup) },
+                { "basic", typeof(BasicStartup) },
+                { "detailed", typeof(DetailedStatusStartup) },
+                { "writer", typeof(CustomWriterStartup) },
+                { "liveness", typeof(LivenessProbeStartup) },
+            };
+        }
+
         public static void Main(string[] args)
         {
             BuildWebHost(args).Run();
         }
 
-        public static IWebHost BuildWebHost(string[] args) =>
-            new WebHostBuilder()
+        public static IWebHost BuildWebHost(string[] args)
+        {
+            var config = new ConfigurationBuilder()
+                .AddEnvironmentVariables(prefix: "ASPNETCORE_")
+                .AddCommandLine(args)
+                .Build();
+
+            var scenario = config["scenario"] ?? string.Empty;
+            if (!_scenarios.TryGetValue(scenario, out var startupType))
+            {
+                startupType = typeof(BasicStartup);
+            }
+
+            return new WebHostBuilder()
+                .UseConfiguration(config)
                 .ConfigureLogging(builder =>
                 {
                     builder.AddConsole();
                 })
                 .UseKestrel()
-                .UseStartup<Startup>()
+                .UseStartup(startupType)
                 .Build();
+        }
+
     }
 }