Pemeriksaan kesehatan di ASP.NET Core

ASP.NET Core menawarkan Middleware pemeriksaan kesehatan dan pustaka untuk melaporkan kesehatan komponen infrastruktur aplikasi.

Pemeriksaan kesehatan diekspos oleh aplikasi sebagai titik akhir HTTP. Titik akhir pemeriksaan kesehatan dapat dikonfigurasi untuk berbagai skenario pemantauan real-time:

• Pemeriksaan kesehatan dapat digunakan oleh orkestrator kontainer dan load balancer untuk memeriksa status aplikasi. Misalnya, orkestrator kontainer dapat merespons pemeriksaan kesehatan yang gagal dengan menghentikan penyebaran bergulir atau memulai ulang kontainer. Load balancer mungkin bereaksi terhadap aplikasi yang tidak sehat dengan merutekan lalu lintas dari instans yang gagal ke instans yang sehat.
• Penggunaan memori, disk, dan sumber daya server fisik lainnya dapat dipantau untuk status sehat.
• Pemeriksaan kesehatan dapat menguji dependensi aplikasi, seperti database dan titik akhir layanan eksternal, untuk mengonfirmasi ketersediaan dan fungsi normal.

Pemeriksaan kesehatan biasanya digunakan dengan layanan pemantauan eksternal atau orkestrator kontainer untuk memeriksa status aplikasi. Sebelum menambahkan pemeriksaan kesehatan ke aplikasi, putuskan sistem pemantauan mana yang akan digunakan. Sistem pemantauan menentukan jenis pemeriksaan kesehatan apa yang akan dibuat dan cara mengonfigurasi titik akhirnya.

Pemeriksaan kesehatan dasar

Untuk banyak aplikasi, konfigurasi pemeriksaan kesehatan dasar yang melaporkan ketersediaan aplikasi untuk memproses permintaan (liveness) cukup untuk menemukan status aplikasi.

Konfigurasi dasar mendaftarkan layanan pemeriksaan kesehatan dan memanggil Middleware Pemeriksaan Kesehatan untuk merespons di titik akhir URL dengan respons kesehatan. Secara default, tidak ada pemeriksaan kesehatan tertentu yang terdaftar untuk menguji dependensi atau subsistem tertentu. Aplikasi ini dianggap sehat jika dapat merespons di URL titik akhir kesehatan. Penulis respons default menulis HealthStatus sebagai respons teks biasa terhadap klien. adalah HealthStatus HealthStatus.Healthy, HealthStatus.Degraded, atau HealthStatus.Unhealthy.

Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Program.cs. Buat titik akhir pemeriksaan kesehatan dengan memanggil MapHealthChecks.

Contoh berikut membuat titik akhir pemeriksaan kesehatan di /healthz:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks();

var app = builder.Build();

app.MapHealthChecks("/healthz");

app.Run();

Buruh kapal HEALTHCHECK

Docker menawarkan arahan bawaan HEALTHCHECK yang dapat digunakan untuk memeriksa status aplikasi yang menggunakan konfigurasi pemeriksaan kesehatan dasar:

HEALTHCHECK CMD curl --fail http://localhost:5000/healthz || exit

Contoh sebelumnya menggunakan curl untuk membuat permintaan HTTP ke titik akhir pemeriksaan kesehatan di /healthz. curl tidak disertakan dalam gambar kontainer Linux .NET, tetapi dapat ditambahkan dengan menginstal paket yang diperlukan di Dockerfile. Kontainer yang menggunakan gambar berdasarkan Alpine Linux dapat menggunakan yang disertakan wget sebagai pengganti curl.

Membuat pemeriksaan kesehatan

Pemeriksaan kesehatan dibuat dengan menerapkan IHealthCheck antarmuka. Metode CheckHealthAsync mengembalikan HealthCheckResult yang menunjukkan kesehatan sebagai Healthy, , Degradedatau Unhealthy. Hasilnya ditulis sebagai respons teks biasa dengan kode status yang dapat dikonfigurasi. Konfigurasi dijelaskan di bagian Opsi pemeriksaan kesehatan. HealthCheckResult juga dapat mengembalikan pasangan kunci-nilai opsional.

Contoh berikut menunjukkan tata letak pemeriksaan kesehatan:

public class SampleHealthCheck : IHealthCheck
{
    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        var isHealthy = true;

        // ...

        if (isHealthy)
        {
            return Task.FromResult(
                HealthCheckResult.Healthy("A healthy result."));
        }

        return Task.FromResult(
            new HealthCheckResult(
                context.Registration.FailureStatus, "An unhealthy result."));
    }
}

Logika pemeriksaan kesehatan ditempatkan dalam CheckHealthAsync metode . Contoh sebelumnya menetapkan variabel dummy, , isHealthyke true. Jika nilai isHealthy diatur ke false, HealthCheckRegistration.FailureStatus status dikembalikan.

Jika CheckHealthAsync melempar pengecualian selama pemeriksaan, yang baru HealthReportEntry dikembalikan dengan HealthReportEntry.Status diatur ke FailureStatus. Status ini ditentukan oleh AddCheck (lihat bagian Daftarkan layanan pemeriksaan kesehatan) dan menyertakan pengecualian dalam yang menyebabkan kegagalan pemeriksaan. Description diatur ke pesan pengecualian.

Mendaftarkan layanan pemeriksaan kesehatan

Untuk mendaftarkan layanan pemeriksaan kesehatan, hubungi AddCheck di Program.cs:

builder.Services.AddHealthChecks()
    .AddCheck<SampleHealthCheck>("Sample");

Kelebihan AddCheck beban yang ditunjukkan dalam contoh berikut menetapkan status kegagalan (HealthStatus) untuk melaporkan saat pemeriksaan kesehatan melaporkan kegagalan. Jika status kegagalan diatur ke null (default), HealthStatus.Unhealthy dilaporkan. Kelebihan beban ini adalah skenario yang berguna untuk penulis pustaka, di mana status kegagalan yang ditunjukkan oleh pustaka diberlakukan oleh aplikasi ketika kegagalan pemeriksaan kesehatan terjadi jika implementasi pemeriksaan kesehatan mematuhi pengaturan.

Tag dapat digunakan untuk memfilter pemeriksaan kesehatan. Tag dijelaskan di bagian Filter pemeriksaan kesehatan.

builder.Services.AddHealthChecks()
    .AddCheck<SampleHealthCheck>(
        "Sample",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "sample" });

AddCheck juga dapat menjalankan fungsi lambda. Dalam contoh berikut, pemeriksaan kesehatan selalu mengembalikan hasil yang sehat:

builder.Services.AddHealthChecks()
    .AddCheck("Sample", () => HealthCheckResult.Healthy("A healthy result."));

Panggil AddTypeActivatedCheck untuk meneruskan argumen ke implementasi pemeriksaan kesehatan. Dalam contoh berikut, pemeriksaan kesehatan yang diaktifkan jenis menerima bilangan bulat dan string dalam konstruktornya:

public class SampleHealthCheckWithArgs : IHealthCheck
{
    private readonly int _arg1;
    private readonly string _arg2;

    public SampleHealthCheckWithArgs(int arg1, string arg2)
        => (_arg1, _arg2) = (arg1, arg2);

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        // ...

        return Task.FromResult(HealthCheckResult.Healthy("A healthy result."));
    }
}

Untuk mendaftarkan pemeriksaan kesehatan sebelumnya, panggil AddTypeActivatedCheck dengan bilangan bulat dan string yang diteruskan sebagai argumen:

builder.Services.AddHealthChecks()
    .AddTypeActivatedCheck<SampleHealthCheckWithArgs>(
        "Sample",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "sample" },
        args: new object[] { 1, "Arg" });

Gunakan Perutean Pemeriksaan Kesehatan

Di Program.cs, panggil MapHealthChecks pembangun titik akhir dengan URL titik akhir atau jalur relatif:

app.MapHealthChecks("/healthz");

Memerlukan host

Panggil RequireHost untuk menentukan satu atau beberapa host yang diizinkan untuk titik akhir pemeriksaan kesehatan. Host harus Unicode daripada punycode dan dapat mencakup port. Jika koleksi tidak disediakan, host apa pun akan diterima:

app.MapHealthChecks("/healthz")
    .RequireHost("www.contoso.com:5001");

Untuk membatasi titik akhir pemeriksaan kesehatan untuk merespons hanya pada port tertentu, tentukan port dalam panggilan ke RequireHost. Pendekatan ini biasanya digunakan dalam lingkungan kontainer untuk mengekspos port untuk layanan pemantauan:

app.MapHealthChecks("/healthz")
    .RequireHost("*:5001");

Untuk mencegah klien yang tidak sah melakukan spoofing port, panggil RequireAuthorization:

app.MapHealthChecks("/healthz")
    .RequireHost("*:5001")
    .RequireAuthorization();

Untuk informasi selengkapnya, lihat Pencocokan host dalam rute dengan RequireHost.

Memerlukan otorisasi

Panggil RequireAuthorization untuk menjalankan Middleware Otorisasi pada titik akhir permintaan pemeriksaan kesehatan. Kelebihan RequireAuthorization beban menerima satu atau beberapa kebijakan otorisasi. Jika kebijakan tidak disediakan, kebijakan otorisasi default akan digunakan:

app.MapHealthChecks("/healthz")
    .RequireAuthorization();

Mengaktifkan Permintaan Lintas Asal (CORS)

Meskipun menjalankan pemeriksaan kesehatan secara manual dari browser bukanlah skenario umum, CORS Middleware dapat diaktifkan dengan memanggil RequireCors titik akhir pemeriksaan kesehatan. Kelebihan RequireCors beban menerima delegasi pembuat kebijakan CORS (CorsPolicyBuilder) atau nama kebijakan. Untuk informasi selengkapnya, lihat Mengaktifkan Permintaan Lintas Asal (CORS) di ASP.NET Core.

Opsi pemeriksaan kesehatan

HealthCheckOptions memberikan kesempatan untuk menyesuaikan perilaku pemeriksaan kesehatan:

• Memfilter pemeriksaan kesehatan
• Mengkustomisasi kode status HTTP
• Menyembunyikan header cache
• Sesuaikan output

Memfilter pemeriksaan kesehatan

Secara default, Middleware Pemeriksaan Kesehatan menjalankan semua pemeriksaan kesehatan terdaftar. Untuk menjalankan subset pemeriksaan kesehatan, berikan fungsi yang mengembalikan boolean ke Predicate opsi .

Contoh berikut memfilter pemeriksaan kesehatan sehingga hanya yang ditandai dengan sample eksekusi:

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    Predicate = healthCheck => healthCheck.Tags.Contains("sample")
});

Mengkustomisasi kode status HTTP

Gunakan ResultStatusCodes untuk menyesuaikan pemetaan status kesehatan ke kode status HTTP. Tugas berikut StatusCodes adalah nilai default yang digunakan oleh middleware. Ubah nilai kode status untuk memenuhi kebutuhan Anda:

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

Menyembunyikan header cache

AllowCachingResponses mengontrol apakah Middleware Pemeriksaan Kesehatan menambahkan header HTTP ke respons pemeriksaan untuk mencegah penembolokan respons. Jika nilainya ( false default), middleware mengatur atau mengambil Cache-Controlalih header , , Expiresdan Pragma untuk mencegah penembolokan respons. Jika nilainya adalah true, middleware tidak mengubah header cache respons:

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    AllowCachingResponses = true
});

Sesuaikan output

Untuk menyesuaikan output laporan pemeriksaan kesehatan, atur HealthCheckOptions.ResponseWriter properti ke delegasi yang menulis respons:

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    ResponseWriter = WriteResponse
});

Delegasi default menulis respons teks biasa minimal dengan nilai HealthReport.Statusstring . Delegasi kustom berikut menghasilkan respons JSON kustom menggunakan System.Text.Json:

private static Task WriteResponse(HttpContext context, HealthReport healthReport)
{
    context.Response.ContentType = "application/json; charset=utf-8";

    var options = new JsonWriterOptions { Indented = true };

    using var memoryStream = new MemoryStream();
    using (var jsonWriter = new Utf8JsonWriter(memoryStream, options))
    {
        jsonWriter.WriteStartObject();
        jsonWriter.WriteString("status", healthReport.Status.ToString());
        jsonWriter.WriteStartObject("results");

        foreach (var healthReportEntry in healthReport.Entries)
        {
            jsonWriter.WriteStartObject(healthReportEntry.Key);
            jsonWriter.WriteString("status",
                healthReportEntry.Value.Status.ToString());
            jsonWriter.WriteString("description",
                healthReportEntry.Value.Description);
            jsonWriter.WriteStartObject("data");

            foreach (var item in healthReportEntry.Value.Data)
            {
                jsonWriter.WritePropertyName(item.Key);

                JsonSerializer.Serialize(jsonWriter, item.Value,
                    item.Value?.GetType() ?? typeof(object));
            }

            jsonWriter.WriteEndObject();
            jsonWriter.WriteEndObject();
        }

        jsonWriter.WriteEndObject();
        jsonWriter.WriteEndObject();
    }

    return context.Response.WriteAsync(
        Encoding.UTF8.GetString(memoryStream.ToArray()));
}

API pemeriksaan kesehatan tidak menyediakan dukungan bawaan untuk format pengembalian JSON yang kompleks karena formatnya khusus untuk sistem pemantauan pilihan Anda. Sesuaikan respons dalam contoh sebelumnya sesuai kebutuhan. Untuk informasi selengkapnya tentang serialisasi JSON dengan System.Text.Json, lihat Cara membuat serialisasi dan deserialisasi JSON di .NET.

Pemeriksaan database

Pemeriksaan kesehatan dapat menentukan kueri database untuk dijalankan sebagai pengujian boolean untuk menunjukkan apakah database merespons secara normal.

AspNetCore.Diagnostics.HealthChecks, pustaka pemeriksaan kesehatan untuk aplikasi ASP.NET Core, menyertakan pemeriksaan kesehatan yang berjalan terhadap database SQL Server. AspNetCore.Diagnostics.HealthChecksSELECT 1 menjalankan kueri terhadap database untuk mengonfirmasi koneksi ke database sehat.

Untuk menggunakan pemeriksaan kesehatan SQL Server ini, sertakan referensi paket ke AspNetCore.HealthChecks.SqlServer paket NuGet. Contoh berikut mendaftarkan pemeriksaan kesehatan SQL Server:

var conStr = builder.Configuration.GetConnectionString("DefaultConnection");
if (string.IsNullOrEmpty(conStr))
{
    throw new InvalidOperationException(
                       "Could not find a connection string named 'DefaultConnection'.");
}
builder.Services.AddHealthChecks()
    .AddSqlServer(conStr);

Pemeriksaan Entity Framework Core DbContext

Pemeriksaan DbContext mengonfirmasi bahwa aplikasi dapat berkomunikasi dengan database yang dikonfigurasi untuk EF CoreDbContext. DbContext Pemeriksaan didukung di aplikasi yang:

• Gunakan Core Entity Framework (EF).
• Sertakan referensi paket ke Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore paket NuGet.

AddDbContextCheck mendaftarkan pemeriksaan kesehatan untuk DbContext. DbContext disediakan ke metode sebagai TContext. Kelebihan beban tersedia untuk mengonfigurasi status kegagalan, tag, dan kueri pengujian kustom.

Secara default:

• Metode DbContextHealthCheck panggilanEF CoreCanConnectAsync. Anda dapat menyesuaikan operasi apa yang dijalankan saat memeriksa kesehatan menggunakan AddDbContextCheck kelebihan beban metode.
• Nama pemeriksaan kesehatan adalah nama jenisnya TContext .

Contoh berikut mendaftarkan DbContext dan terkait DbContextHealthCheck:

builder.Services.AddDbContext<SampleDbContext>(options =>
    options.UseSqlServer(
        builder.Configuration.GetConnectionString("DefaultConnection")));

builder.Services.AddHealthChecks()
    .AddDbContextCheck<SampleDbContext>();

Pemeriksaan kesiapan dan keaktifan terpisah

Dalam beberapa skenario hosting, sepasang pemeriksaan kesehatan digunakan untuk membedakan dua status aplikasi:

• Kesiapan menunjukkan apakah aplikasi berjalan normal tetapi belum siap untuk menerima permintaan.
• Liveness menunjukkan apakah aplikasi mengalami crash dan harus dimulai ulang.

Pertimbangkan contoh berikut: Aplikasi harus mengunduh file konfigurasi besar sebelum siap memproses permintaan. Kami tidak ingin aplikasi dimulai ulang jika unduhan awal gagal karena aplikasi dapat mencoba lagi mengunduh file beberapa kali. Kami menggunakan pemeriksaan keaktifan untuk menggambarkan keaktifan proses, tidak ada pemeriksaan lain yang dijalankan. Kami juga ingin mencegah permintaan dikirim ke aplikasi sebelum pengunduhan file konfigurasi berhasil. Kami menggunakan pemeriksaan kesiapan untuk menunjukkan status "belum siap" sampai unduhan berhasil dan aplikasi siap menerima permintaan.

Tugas latar belakang berikut mensimulasikan proses startup yang memakan waktu sekitar 15 detik. Setelah selesai, tugas mengatur StartupHealthCheck.StartupCompleted properti ke true:

public class StartupBackgroundService : BackgroundService
{
    private readonly StartupHealthCheck _healthCheck;

    public StartupBackgroundService(StartupHealthCheck healthCheck)
        => _healthCheck = healthCheck;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // Simulate the effect of a long-running task.
        await Task.Delay(TimeSpan.FromSeconds(15), stoppingToken);

        _healthCheck.StartupCompleted = true;
    }
}

Laporan StartupHealthCheck penyelesaian tugas startup yang berjalan lama dan mengekspos StartupCompleted properti yang diatur oleh layanan latar belakang:

public class StartupHealthCheck : IHealthCheck
{
    private volatile bool _isReady;

    public bool StartupCompleted
    {
        get => _isReady;
        set => _isReady = value;
    }

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        if (StartupCompleted)
        {
            return Task.FromResult(HealthCheckResult.Healthy("The startup task has completed."));
        }

        return Task.FromResult(HealthCheckResult.Unhealthy("That startup task is still running."));
    }
}

Pemeriksaan kesehatan didaftarkan AddCheck bersama dengan layanan yang dihosting Program.cs . Karena layanan yang dihosting harus mengatur properti pada pemeriksaan kesehatan, pemeriksaan kesehatan juga terdaftar dalam kontainer layanan sebagai singleton:

builder.Services.AddHostedService<StartupBackgroundService>();
builder.Services.AddSingleton<StartupHealthCheck>();

builder.Services.AddHealthChecks()
    .AddCheck<StartupHealthCheck>(
        "Startup",
        tags: new[] { "ready" });

Untuk membuat dua titik akhir pemeriksaan kesehatan yang berbeda, panggil MapHealthChecks dua kali:

app.MapHealthChecks("/healthz/ready", new HealthCheckOptions
{
    Predicate = healthCheck => healthCheck.Tags.Contains("ready")
});

app.MapHealthChecks("/healthz/live", new HealthCheckOptions
{
    Predicate = _ => false
});

Contoh sebelumnya membuat titik akhir pemeriksaan kesehatan berikut:

• /healthz/ready untuk pemeriksaan kesiapan. Pemeriksaan kesiapan memfilter pemeriksaan kesehatan ke yang ditandai dengan ready.
• /healthz/live untuk pemeriksaan keaktivaan. Pemeriksaan keakuratan memfilter semua pemeriksaan kesehatan dengan kembali false ke HealthCheckOptions.Predicate delegasi. Untuk informasi selengkapnya tentang pemfilteran pemeriksaan kesehatan, lihat Memfilter pemeriksaan kesehatan di artikel ini.

Sebelum tugas startup selesai, /healthz/ready titik akhir melaporkan Unhealthy status. Setelah tugas startup selesai, titik akhir ini melaporkan Healthy status. Titik /healthz/live akhir mengecualikan semua pemeriksaan dan melaporkan Healthy status untuk semua panggilan.

Contoh Kubernetes

Menggunakan pemeriksaan kesiapan dan keaktifan terpisah berguna di lingkungan seperti Kubernetes. Di Kubernetes, aplikasi mungkin diperlukan untuk menjalankan pekerjaan startup yang memakan waktu sebelum menerima permintaan, seperti pengujian ketersediaan database yang mendasarinya. Menggunakan pemeriksaan terpisah memungkinkan orkestrator untuk membedakan apakah aplikasi berfungsi tetapi belum siap atau jika aplikasi gagal dimulai. Untuk informasi selengkapnya tentang pemeriksaan kesiapan dan keaktifan di Kubernetes, lihat Mengonfigurasi Pemeriksaan Keaktifan dan Kesiapan dalam dokumentasi Kubernetes.

Contoh berikut menunjukkan konfigurasi pemeriksaan kesiapan Kube:

spec:
  template:
  spec:
    readinessProbe:
      # an http probe
      httpGet:
        path: /healthz/ready
        port: 80
      # length of time to wait for a pod to initialize
      # after pod startup, before applying health checking
      initialDelaySeconds: 30
      timeoutSeconds: 1
    ports:
      - containerPort: 80

Mendistribusikan pustaka pemeriksaan kesehatan

Untuk mendistribusikan pemeriksaan kesehatan sebagai pustaka:

1. Tulis pemeriksaan kesehatan yang mengimplementasikan IHealthCheck antarmuka sebagai kelas mandiri. Kelas dapat mengandalkan injeksi dependensi (DI), aktivasi jenis, dan opsi bernama untuk mengakses data konfigurasi.

2. Tulis metode ekstensi dengan parameter yang dipanggil aplikasi yang mengonsumsi dalam metodenya Program.cs . Pertimbangkan contoh pemeriksaan kesehatan berikut, yang menerima arg1 dan arg2 sebagai parameter konstruktor:

   public SampleHealthCheckWithArgs(int arg1, string arg2)
       => (_arg1, _arg2) = (arg1, arg2);
   

   Tanda tangan sebelumnya menunjukkan bahwa pemeriksaan kesehatan memerlukan data kustom untuk memproses logika pemeriksaan kesehatan. Data diberikan kepada delegasi yang digunakan untuk membuat instans pemeriksaan kesehatan saat pemeriksaan kesehatan terdaftar dengan metode ekstensi. Dalam contoh berikut, pemanggil menentukan:

   • arg1: Titik data bilangan bulat untuk pemeriksaan kesehatan.
   • arg2: Argumen string untuk pemeriksaan kesehatan.
   • name: Nama pemeriksaan kesehatan opsional. Jika null, nilai default digunakan.
   • failureStatus: Opsional HealthStatus, yang dilaporkan untuk status kegagalan. Jika null, HealthStatus.Unhealthy digunakan.
   • tags: Kumpulan tag opsional IEnumerable<string> .

   public static class SampleHealthCheckBuilderExtensions
   {
       private const string DefaultName = "Sample";
   
       public static IHealthChecksBuilder AddSampleHealthCheck(
           this IHealthChecksBuilder healthChecksBuilder,
           int arg1,
           string arg2,
           string? name = null,
           HealthStatus? failureStatus = null,
           IEnumerable<string>? tags = default)
       {
           return healthChecksBuilder.Add(
               new HealthCheckRegistration(
                   name ?? DefaultName,
                   _ => new SampleHealthCheckWithArgs(arg1, arg2),
                   failureStatus,
                   tags));
       }
   }
   

Penerbit Pemeriksaan Kesehatan

IHealthCheckPublisher Ketika ditambahkan ke kontainer layanan, sistem pemeriksaan kesehatan secara berkala menjalankan pemeriksaan dan panggilan PublishAsync kesehatan Anda dengan hasilnya. Proses ini berguna dalam skenario sistem pemantauan kesehatan berbasis dorong yang mengharapkan setiap proses memanggil sistem pemantauan secara berkala untuk menentukan kesehatan.

HealthCheckPublisherOptions memungkinkan Anda untuk mengatur:

• Delay: Penundaan awal diterapkan setelah aplikasi dimulai sebelum menjalankan IHealthCheckPublisher instans. Penundaan diterapkan sekali saat startup dan tidak berlaku untuk perulangan nanti. Nilai defaultnya adalah lima detik.
• Period: Periode IHealthCheckPublisher eksekusi. Nilai {i>default
• Predicate: Jika Predicate ( null default), layanan penerbit pemeriksaan kesehatan menjalankan semua pemeriksaan kesehatan terdaftar. Untuk menjalankan subset pemeriksaan kesehatan, berikan fungsi yang memfilter serangkaian pemeriksaan. Predikat dievaluasi setiap periode.
• Timeout: Batas waktu untuk menjalankan pemeriksaan kesehatan untuk semua IHealthCheckPublisher instans. Gunakan InfiniteTimeSpan untuk mengeksekusi tanpa batas waktu. Nilai {i>default

Contoh berikut menunjukkan tata letak penerbit kesehatan:

public class SampleHealthCheckPublisher : IHealthCheckPublisher
{
    public Task PublishAsync(HealthReport report, CancellationToken cancellationToken)
    {
        if (report.Status == HealthStatus.Healthy)
        {
            // ...
        }
        else
        {
            // ...
        }

        return Task.CompletedTask;
    }
}

Kelas HealthCheckPublisherOptions menyediakan properti untuk mengonfigurasi perilaku penerbit pemeriksaan kesehatan.

Contoh berikut mendaftarkan penerbit pemeriksaan kesehatan sebagai singleton dan mengonfigurasi HealthCheckPublisherOptions:

builder.Services.Configure<HealthCheckPublisherOptions>(options =>
{
    options.Delay = TimeSpan.FromSeconds(2);
    options.Predicate = healthCheck => healthCheck.Tags.Contains("sample");
});

builder.Services.AddSingleton<IHealthCheckPublisher, SampleHealthCheckPublisher>();

AspNetCore.Diagnostics.HealthChecks:

• Termasuk penerbit untuk beberapa sistem, termasuk Application Insights.
• Tidak dikelola atau didukung oleh Microsoft.

Pemeriksaan Kesehatan Individu

Delay dan Period dapat diatur pada masing-masing HealthCheckRegistration secara individual. Ini berguna ketika Anda ingin menjalankan beberapa pemeriksaan kesehatan pada tingkat yang berbeda dari periode yang ditetapkan dalam HealthCheckPublisherOptions.

Kode berikut menetapkan Delay dan Period untuk SampleHealthCheck1:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks()
   .Add(new HealthCheckRegistration(
       name: "SampleHealthCheck1",
       instance: new SampleHealthCheck(),
       failureStatus: null,
       tags: null,
       timeout: default)
   {
       Delay = TimeSpan.FromSeconds(40),
       Period = TimeSpan.FromSeconds(30)
   });

var app = builder.Build();

app.MapHealthChecks("/healthz");

app.Run();

Injeksi Dependensi dan Pemeriksaan Kesehatan

Dimungkinkan untuk menggunakan injeksi dependensi untuk menggunakan instans tertentu Type di dalam kelas Pemeriksaan Kesehatan. Injeksi dependensi dapat berguna untuk menyuntikkan opsi atau konfigurasi global ke Pemeriksaan Kesehatan. Menggunakan injeksi dependensi bukanlah skenario umum untuk mengonfigurasi Pemeriksaan Kesehatan. Biasanya, setiap Pemeriksaan Kesehatan cukup spesifik untuk pengujian aktual dan dikonfigurasi menggunakan IHealthChecksBuilder metode ekstensi.

Contoh berikut menunjukkan sampel Pemeriksaan Kesehatan yang mengambil objek konfigurasi melalui injeksi dependensi:

public class SampleHealthCheckWithDI : IHealthCheck
{
    private readonly SampleHealthCheckWithDiConfig _config;

    public SampleHealthCheckWithDI(SampleHealthCheckWithDiConfig config)
        => _config = config;

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        var isHealthy = true;

        // use _config ...

        if (isHealthy)
        {
            return Task.FromResult(
                HealthCheckResult.Healthy("A healthy result."));
        }

        return Task.FromResult(
            new HealthCheckResult(
                context.Registration.FailureStatus, "An unhealthy result."));
    }
}

SampleHealthCheckWithDiConfig Pemeriksaan kesehatan dan perlu ditambahkan ke kontainer layanan :

builder.Services.AddSingleton<SampleHealthCheckWithDiConfig>(new SampleHealthCheckWithDiConfig
{
    BaseUriToCheck = new Uri("https://sample.contoso.com/api/")
});
builder.Services.AddHealthChecks()
    .AddCheck<SampleHealthCheckWithDI>(
        "With Dependency Injection",
        tags: new[] { "inject" });

UseHealthChecks vs. MapHealthChecks

Ada dua cara untuk membuat pemeriksaan kesehatan dapat diakses oleh penelepon:

• UseHealthChecks mendaftarkan middleware untuk menangani permintaan pemeriksaan kesehatan di alur middleware.
• MapHealthChecks mendaftarkan titik akhir pemeriksaan kesehatan. Titik akhir dicocokkan dan dijalankan bersama dengan titik akhir lain di aplikasi.

Keuntungan menggunakan MapHealthChecks lebih UseHealthChecks dari adalah kemampuan untuk menggunakan middleware sadar titik akhir, seperti otorisasi, dan untuk memiliki kontrol terperinci yang lebih besar atas kebijakan pencocokan. Keuntungan utama menggunakan UseHealthChecks over MapHealthChecks adalah mengontrol persis di mana pemeriksaan kesehatan berjalan di alur middleware.

UseHealthChecks:

• Mengakhiri alur saat permintaan cocok dengan titik akhir pemeriksaan kesehatan. Sirkuit pendek sering diinginkan karena menghindari pekerjaan yang tidak perlu, seperti pengelogan dan middleware lainnya.
• Terutama digunakan untuk mengonfigurasi middleware pemeriksaan kesehatan dalam alur.
• Dapat mencocokkan jalur apa pun pada port dengan null atau kosong PathString. Memungkinkan melakukan pemeriksaan kesehatan pada permintaan apa pun yang dibuat ke port yang ditentukan.
• Kode sumber

MapHealthChecks Memungkinkan:

• Mengakhiri alur ketika permintaan cocok dengan titik akhir pemeriksaan kesehatan, dengan memanggil ShortCircuit. Contohnya,app.MapHealthChecks("/healthz").ShortCircuit();. Untuk informasi selengkapnya, lihat Middleware sirkuit pendek setelah perutean.
• Memetakan rute atau titik akhir tertentu untuk pemeriksaan kesehatan.
• Kustomisasi URL atau jalur tempat titik akhir pemeriksaan kesehatan dapat diakses.
• Memetakan beberapa titik akhir pemeriksaan kesehatan dengan rute atau konfigurasi yang berbeda. Dukungan beberapa titik akhir:
  • Mengaktifkan titik akhir terpisah untuk berbagai jenis pemeriksaan kesehatan atau komponen.
  • Digunakan untuk membedakan antara berbagai aspek kesehatan aplikasi atau menerapkan konfigurasi tertentu ke subset pemeriksaan kesehatan.
• Kode sumber

Sumber Daya Tambahan:

• Melihat atau mengunduh kode sampel (cara mengunduh)

ASP.NET Core menawarkan Middleware pemeriksaan kesehatan dan pustaka untuk melaporkan kesehatan komponen infrastruktur aplikasi.

Pemeriksaan kesehatan diekspos oleh aplikasi sebagai titik akhir HTTP. Titik akhir pemeriksaan kesehatan dapat dikonfigurasi untuk berbagai skenario pemantauan real-time:

• Pemeriksaan kesehatan dapat digunakan oleh orkestrator kontainer dan load balancer untuk memeriksa status aplikasi. Misalnya, orkestrator kontainer dapat merespons pemeriksaan kesehatan yang gagal dengan menghentikan penyebaran bergulir atau memulai ulang kontainer. Load balancer mungkin bereaksi terhadap aplikasi yang tidak sehat dengan merutekan lalu lintas dari instans yang gagal ke instans yang sehat.
• Penggunaan memori, disk, dan sumber daya server fisik lainnya dapat dipantau untuk status sehat.
• Pemeriksaan kesehatan dapat menguji dependensi aplikasi, seperti database dan titik akhir layanan eksternal, untuk mengonfirmasi ketersediaan dan fungsi normal.

Melihat atau mengunduh kode sampel (cara mengunduh)

Aplikasi sampel menyertakan contoh skenario yang dijelaskan dalam artikel ini. Untuk menjalankan aplikasi sampel untuk skenario tertentu, gunakan perintah jalankan dotnet dari folder proyek dalam shell perintah. Lihat contoh file aplikasi README.md dan deskripsi skenario dalam artikel ini untuk detail tentang cara menggunakan aplikasi sampel.

Prasyarat

Pemeriksaan kesehatan biasanya digunakan dengan layanan pemantauan eksternal atau orkestrator kontainer untuk memeriksa status aplikasi. Sebelum menambahkan pemeriksaan kesehatan ke aplikasi, putuskan sistem pemantauan mana yang akan digunakan. Sistem pemantauan menentukan jenis pemeriksaan kesehatan apa yang akan dibuat dan cara mengonfigurasi titik akhirnya.

Paket Microsoft.AspNetCore.Diagnostics.HealthChecks ini dirujuk secara implisit untuk aplikasi ASP.NET Core. Untuk menjalankan pemeriksaan kesehatan menggunakan Entity Framework Core, tambahkan referensi ke Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore paket.

Aplikasi sampel menyediakan kode startup untuk menunjukkan pemeriksaan kesehatan untuk beberapa skenario. Skenario pemeriksaan database memeriksa kesehatan koneksi database menggunakan AspNetCore.Diagnostics.HealthChecks. Skenario pemeriksaan DbContext memeriksa database menggunakan EF CoreDbContext. Untuk menjelajahi skenario database, aplikasi sampel:

• Membuat database dan menyediakan string koneksi dalam appsettings.json file.
• Memiliki referensi paket berikut dalam file proyeknya:
  • AspNetCore.HealthChecks.SqlServer
  • Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore

Skenario pemeriksaan kesehatan lain menunjukkan cara memfilter pemeriksaan kesehatan ke port manajemen. Aplikasi sampel mengharuskan Anda membuat Properties/launchSettings.json file yang menyertakan URL manajemen dan port manajemen. Untuk informasi selengkapnya, lihat bagian Filter menurut port .

Pemeriksaan kesehatan dasar

Untuk banyak aplikasi, konfigurasi pemeriksaan kesehatan dasar yang melaporkan ketersediaan aplikasi untuk memproses permintaan (liveness) cukup untuk menemukan status aplikasi.

Konfigurasi dasar mendaftarkan layanan pemeriksaan kesehatan dan memanggil Middleware Pemeriksaan Kesehatan untuk merespons di titik akhir URL dengan respons kesehatan. Secara default, tidak ada pemeriksaan kesehatan tertentu yang terdaftar untuk menguji dependensi atau subsistem tertentu. Aplikasi ini dianggap sehat jika dapat merespons di URL titik akhir kesehatan. Penulis respons default menulis status (HealthStatus) sebagai respons teks biasa kembali ke klien, menunjukkan HealthStatus.Healthystatus , , HealthStatus.Degradedatau HealthStatus.Unhealthy .

Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Startup.ConfigureServices. Buat titik akhir pemeriksaan kesehatan dengan memanggil MapHealthChecks di Startup.Configure.

Di aplikasi sampel, titik akhir pemeriksaan kesehatan dibuat di /health (BasicStartup.cs):

public class BasicStartup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddHealthChecks();
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapHealthChecks("/health");
        });
    }
}

Untuk menjalankan skenario konfigurasi dasar menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:

dotnet run --scenario basic

Contoh Docker

Docker menawarkan arahan bawaan HEALTHCHECK yang dapat digunakan untuk memeriksa status aplikasi yang menggunakan konfigurasi pemeriksaan kesehatan dasar:

HEALTHCHECK CMD curl --fail http://localhost:5000/health || exit

Membuat pemeriksaan kesehatan

Pemeriksaan kesehatan dibuat dengan menerapkan IHealthCheck antarmuka. Metode CheckHealthAsync mengembalikan HealthCheckResult yang menunjukkan kesehatan sebagai Healthy, , Degradedatau Unhealthy. Hasilnya ditulis sebagai respons teks biasa dengan kode status yang dapat dikonfigurasi (konfigurasi dijelaskan di bagian Opsi pemeriksaan kesehatan). HealthCheckResult juga dapat mengembalikan pasangan kunci-nilai opsional.

Kelas berikut ExampleHealthCheck menunjukkan tata letak pemeriksaan kesehatan. Logika pemeriksaan kesehatan ditempatkan dalam CheckHealthAsync metode . Contoh berikut menetapkan variabel dummy, healthCheckResultHealthy, ke true. Jika nilai healthCheckResultHealthy diatur ke false, HealthCheckRegistration.FailureStatus status dikembalikan.

public class ExampleHealthCheck : IHealthCheck
{
    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default(CancellationToken))
    {
        var healthCheckResultHealthy = true;

        if (healthCheckResultHealthy)
        {
            return Task.FromResult(
                HealthCheckResult.Healthy("A healthy result."));
        }

        return Task.FromResult(
            new HealthCheckResult(context.Registration.FailureStatus, 
            "An unhealthy result."));
    }
}

Jika CheckHealthAsync melempar pengecualian selama pemeriksaan, yang baru HealthReportEntry dikembalikan dengan diatur ke FailureStatus, yang ditentukan oleh AddCheck (lihat bagian Daftarkan layanan pemeriksaan kesehatan) dan menyertakan pengecualian dalam yang awalnya HealthReportEntry.Status menyebabkan kegagalan pemeriksaan. Description diatur ke pesan pengecualian.

Mendaftarkan layanan pemeriksaan kesehatan

ExampleHealthCheck Jenis ditambahkan ke layanan pemeriksaan kesehatan dengan AddCheck di Startup.ConfigureServices:

services.AddHealthChecks()
    .AddCheck<ExampleHealthCheck>("example_health_check");

Kelebihan AddCheck beban yang ditunjukkan dalam contoh berikut menetapkan status kegagalan (HealthStatus) untuk melaporkan saat pemeriksaan kesehatan melaporkan kegagalan. Jika status kegagalan diatur ke null (default), HealthStatus.Unhealthy dilaporkan. Kelebihan beban ini adalah skenario yang berguna untuk penulis pustaka, di mana status kegagalan yang ditunjukkan oleh pustaka diberlakukan oleh aplikasi ketika kegagalan pemeriksaan kesehatan terjadi jika implementasi pemeriksaan kesehatan mematuhi pengaturan.

Tag dapat digunakan untuk memfilter pemeriksaan kesehatan (dijelaskan lebih lanjut di bagian Filter pemeriksaan kesehatan).

services.AddHealthChecks()
    .AddCheck<ExampleHealthCheck>(
        "example_health_check",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "example" });

AddCheck juga dapat menjalankan fungsi lambda. Dalam contoh berikut, nama pemeriksaan kesehatan ditentukan sebagai Example dan pemeriksaan selalu mengembalikan status sehat:

services.AddHealthChecks()
    .AddCheck("Example", () =>
        HealthCheckResult.Healthy("Example is OK!"), tags: new[] { "example" });

Panggil AddTypeActivatedCheck untuk meneruskan argumen ke implementasi pemeriksaan kesehatan. Dalam contoh berikut, TestHealthCheckWithArgs menerima bilangan bulat dan string untuk digunakan saat CheckHealthAsync dipanggil:

private class TestHealthCheckWithArgs : IHealthCheck
{
    public TestHealthCheckWithArgs(int i, string s)
    {
        I = i;
        S = s;
    }

    public int I { get; set; }

    public string S { get; set; }

    public Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context, 
        CancellationToken cancellationToken = default)
    {
        ...
    }
}

TestHealthCheckWithArgs terdaftar dengan memanggil dengan bilangan AddTypeActivatedCheck bulat dan string yang diteruskan ke implementasi:

services.AddHealthChecks()
    .AddTypeActivatedCheck<TestHealthCheckWithArgs>(
        "test", 
        failureStatus: HealthStatus.Degraded, 
        tags: new[] { "example" }, 
        args: new object[] { 5, "string" });

Gunakan Perutean Pemeriksaan Kesehatan

Di Startup.Configure, panggil MapHealthChecks pembangun titik akhir dengan URL titik akhir atau jalur relatif:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
});

Memerlukan host

Panggil RequireHost untuk menentukan satu atau beberapa host yang diizinkan untuk titik akhir pemeriksaan kesehatan. Host harus Unicode daripada punycode dan dapat mencakup port. Jika koleksi tidak disediakan, host apa pun akan diterima.

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health").RequireHost("www.contoso.com:5001");
});

Untuk informasi selengkapnya, lihat bagian Filter menurut port .

Memerlukan otorisasi

Panggil RequireAuthorization untuk menjalankan Middleware Otorisasi pada titik akhir permintaan pemeriksaan kesehatan. Kelebihan RequireAuthorization beban menerima satu atau beberapa kebijakan otorisasi. Jika kebijakan tidak disediakan, kebijakan otorisasi default digunakan.

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health").RequireAuthorization();
});

Mengaktifkan Permintaan Lintas Asal (CORS)

Meskipun menjalankan pemeriksaan kesehatan secara manual dari browser bukanlah skenario penggunaan umum, CORS Middleware dapat diaktifkan dengan memanggil RequireCors titik akhir pemeriksaan kesehatan. Kelebihan RequireCors beban menerima delegasi pembuat kebijakan CORS (CorsPolicyBuilder) atau nama kebijakan. Jika kebijakan tidak disediakan, kebijakan CORS default akan digunakan. Untuk informasi selengkapnya, lihat Mengaktifkan Permintaan Lintas Asal (CORS) di ASP.NET Core.

Opsi pemeriksaan kesehatan

HealthCheckOptions memberikan kesempatan untuk menyesuaikan perilaku pemeriksaan kesehatan:

• Memfilter pemeriksaan kesehatan
• Mengkustomisasi kode status HTTP
• Menyembunyikan header cache
• Sesuaikan output

Memfilter pemeriksaan kesehatan

Secara default, Middleware Pemeriksaan Kesehatan menjalankan semua pemeriksaan kesehatan terdaftar. Untuk menjalankan subset pemeriksaan kesehatan, berikan fungsi yang mengembalikan boolean ke Predicate opsi . Dalam contoh berikut, Bar pemeriksaan kesehatan difilter oleh tag -nya (bar_tag) dalam pernyataan kondisi fungsi, di mana true hanya dikembalikan jika properti pemeriksaan Tags kesehatan cocok foo_tag atau baz_tag:

Di Startup.ConfigureServices:

services.AddHealthChecks()
    .AddCheck("Foo", () =>
        HealthCheckResult.Healthy("Foo is OK!"), tags: new[] { "foo_tag" })
    .AddCheck("Bar", () =>
        HealthCheckResult.Unhealthy("Bar is unhealthy!"), tags: new[] { "bar_tag" })
    .AddCheck("Baz", () =>
        HealthCheckResult.Healthy("Baz is OK!"), tags: new[] { "baz_tag" });

Di Startup.Configure, Predicate filter pemeriksaan kesehatan 'Bar'. Hanya Foo dan Baz yang dijalankan:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("foo_tag") ||
            check.Tags.Contains("baz_tag")
    });
});

Mengkustomisasi kode status HTTP

Gunakan ResultStatusCodes untuk menyesuaikan pemetaan status kesehatan ke kode status HTTP. Tugas berikut StatusCodes adalah nilai default yang digunakan oleh middleware. Ubah nilai kode status untuk memenuhi kebutuhan Anda.

Di Startup.Configure:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        ResultStatusCodes =
        {
            [HealthStatus.Healthy] = StatusCodes.Status200OK,
            [HealthStatus.Degraded] = StatusCodes.Status200OK,
            [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
        }
    });
});

Menyembunyikan header cache

AllowCachingResponses mengontrol apakah Middleware Pemeriksaan Kesehatan menambahkan header HTTP ke respons pemeriksaan untuk mencegah penembolokan respons. Jika nilainya ( false default), middleware mengatur atau mengambil Cache-Controlalih header , , Expiresdan Pragma untuk mencegah penembolokan respons. Jika nilainya adalah true, middleware tidak mengubah header cache respons.

Di Startup.Configure:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        AllowCachingResponses = true
    });
});

Sesuaikan output

Di Startup.Configure, atur HealthCheckOptions.ResponseWriter opsi ke delegasi untuk menulis respons:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        ResponseWriter = WriteResponse
    });
});

Delegasi default menulis respons teks biasa minimal dengan nilai HealthReport.Statusstring . Delegasi kustom berikut menghasilkan respons JSON kustom.

Contoh pertama dari aplikasi sampel menunjukkan cara menggunakan System.Text.Json:

private static Task WriteResponse(HttpContext context, HealthReport result)
{
    context.Response.ContentType = "application/json; charset=utf-8";

    var options = new JsonWriterOptions
    {
        Indented = true
    };

    using (var stream = new MemoryStream())
    {
        using (var writer = new Utf8JsonWriter(stream, options))
        {
            writer.WriteStartObject();
            writer.WriteString("status", result.Status.ToString());
            writer.WriteStartObject("results");
            foreach (var entry in result.Entries)
            {
                writer.WriteStartObject(entry.Key);
                writer.WriteString("status", entry.Value.Status.ToString());
                writer.WriteString("description", entry.Value.Description);
                writer.WriteStartObject("data");
                foreach (var item in entry.Value.Data)
                {
                    writer.WritePropertyName(item.Key);
                    JsonSerializer.Serialize(
                        writer, item.Value, item.Value?.GetType() ??
                        typeof(object));
                }
                writer.WriteEndObject();
                writer.WriteEndObject();
            }
            writer.WriteEndObject();
            writer.WriteEndObject();
        }

        var json = Encoding.UTF8.GetString(stream.ToArray());

        return context.Response.WriteAsync(json);
    }
}

Contoh kedua menunjukkan cara menggunakan Newtonsoft.Json:

private static Task WriteResponse(HttpContext context, HealthReport result)
{
    context.Response.ContentType = "application/json";

    var json = new JObject(
        new JProperty("status", result.Status.ToString()),
        new JProperty("results", new JObject(result.Entries.Select(pair =>
            new JProperty(pair.Key, new JObject(
                new JProperty("status", pair.Value.Status.ToString()),
                new JProperty("description", pair.Value.Description),
                new JProperty("data", new JObject(pair.Value.Data.Select(
                    p => new JProperty(p.Key, p.Value))))))))));

    return context.Response.WriteAsync(
        json.ToString(Formatting.Indented));
}

Di aplikasi sampel, komentari SYSTEM_TEXT_JSON direktif praproscesor untuk CustomWriterStartup.cs mengaktifkan Newtonsoft.Json versi WriteResponse.

API pemeriksaan kesehatan tidak menyediakan dukungan bawaan untuk format pengembalian JSON yang kompleks karena formatnya khusus untuk sistem pemantauan pilihan Anda. Sesuaikan respons dalam contoh sebelumnya sesuai kebutuhan. Untuk informasi selengkapnya tentang serialisasi JSON dengan System.Text.Json, lihat Cara membuat serialisasi dan deserialisasi JSON di .NET.

Pemeriksaan database

Pemeriksaan kesehatan dapat menentukan kueri database untuk dijalankan sebagai pengujian boolean untuk menunjukkan apakah database merespons secara normal.

Aplikasi sampel menggunakan AspNetCore.Diagnostics.HealthChecks, pustaka pemeriksaan kesehatan untuk aplikasi ASP.NET Core, untuk menjalankan pemeriksaan kesehatan pada database SQL Server. AspNetCore.Diagnostics.HealthChecksSELECT 1 menjalankan kueri terhadap database untuk mengonfirmasi koneksi ke database sehat.

Sertakan referensi paket ke AspNetCore.HealthChecks.SqlServer.

Berikan string koneksi database yang valid dalam appsettings.json file aplikasi sampel. Aplikasi ini menggunakan database SQL Server bernama HealthCheckSample:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\MSSQLLocalDB;Database=HealthCheckSample;Trusted_Connection=True;MultipleActiveResultSets=true;ConnectRetryCount=0"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    },
    "Console": {
      "IncludeScopes": "true"
    }
  },
  "AllowedHosts": "*"
}

Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Startup.ConfigureServices. Aplikasi sampel memanggil AddSqlServer metode dengan string koneksi database (DbHealthStartup.cs):

services.AddHealthChecks()
    .AddSqlServer(Configuration["ConnectionStrings:DefaultConnection"]);

Titik akhir pemeriksaan kesehatan dibuat dengan memanggil MapHealthChecks di Startup.Configure:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
}

Untuk menjalankan skenario pemeriksaan database menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:

dotnet run --scenario db

Pemeriksaan Entity Framework Core DbContext

Pemeriksaan DbContext mengonfirmasi bahwa aplikasi dapat berkomunikasi dengan database yang dikonfigurasi untuk EF CoreDbContext. DbContext Pemeriksaan didukung di aplikasi yang:

• Gunakan Core Entity Framework (EF).
• Sertakan referensi paket ke Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore.

AddDbContextCheck<TContext> mendaftarkan pemeriksaan kesehatan untuk DbContext. DbContext disediakan sebagai untuk TContext metode . Kelebihan beban tersedia untuk mengonfigurasi status kegagalan, tag, dan kueri pengujian kustom.

Secara default:

• Metode DbContextHealthCheck panggilanEF CoreCanConnectAsync. Anda dapat menyesuaikan operasi apa yang dijalankan saat memeriksa kesehatan menggunakan AddDbContextCheck kelebihan beban metode.
• Nama pemeriksaan kesehatan adalah nama jenisnya TContext .

Dalam aplikasi sampel, AppDbContext disediakan untuk AddDbContextCheck dan didaftarkan sebagai layanan di Startup.ConfigureServices (DbContextHealthStartup.cs):

services.AddHealthChecks()
    .AddDbContextCheck<AppDbContext>();

services.AddDbContext<AppDbContext>(options =>
{
    options.UseSqlServer(
        Configuration["ConnectionStrings:DefaultConnection"]);
});

Titik akhir pemeriksaan kesehatan dibuat dengan memanggil MapHealthChecks di Startup.Configure:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
}

Untuk menjalankan DbContext skenario pemeriksaan menggunakan aplikasi sampel, konfirmasikan bahwa database yang ditentukan oleh string koneksi tidak ada di instans SQL Server. Jika database ada, hapus database tersebut.

Jalankan perintah berikut dari folder proyek dalam shell perintah:

dotnet run --scenario dbcontext

Setelah aplikasi berjalan, periksa status kesehatan dengan membuat permintaan ke /health titik akhir di browser. Database dan AppDbContext tidak ada, sehingga aplikasi memberikan respons berikut:

Unhealthy

Picu aplikasi sampel untuk membuat database. Buat permintaan ke /createdatabase. Aplikasi merespons:

Creating the database...
Done!
Navigate to /health to see the health status.

Buat permintaan ke /health titik akhir. Database dan konteks ada, sehingga aplikasi merespons:

Healthy

Picu aplikasi sampel untuk menghapus database. Buat permintaan ke /deletedatabase. Aplikasi merespons:

Deleting the database...
Done!
Navigate to /health to see the health status.

Buat permintaan ke /health titik akhir. Aplikasi ini memberikan respons yang tidak sehat:

Unhealthy

Pemeriksaan kesiapan dan keaktifan terpisah

Dalam beberapa skenario hosting, sepasang pemeriksaan kesehatan digunakan untuk membedakan dua status aplikasi:

• Kesiapan menunjukkan apakah aplikasi berjalan normal tetapi belum siap untuk menerima permintaan.
• Liveness menunjukkan apakah aplikasi mengalami crash dan harus dimulai ulang.

Pertimbangkan contoh berikut: Aplikasi harus mengunduh file konfigurasi besar sebelum siap memproses permintaan. Kami tidak ingin aplikasi dimulai ulang jika unduhan awal gagal karena aplikasi dapat mencoba lagi mengunduh file beberapa kali. Kami menggunakan pemeriksaan keaktifan untuk menggambarkan keaktifan proses, tidak ada pemeriksaan lain yang dijalankan. Kami juga ingin mencegah permintaan dikirim ke aplikasi sebelum pengunduhan file konfigurasi berhasil. Kami menggunakan pemeriksaan kesiapan untuk menunjukkan status "belum siap" sampai unduhan berhasil dan aplikasi siap menerima permintaan.

Aplikasi sampel berisi pemeriksaan kesehatan untuk melaporkan penyelesaian tugas startup yang berjalan lama di Layanan yang Dihosting. Mengekspos StartupHostedServiceHealthCheck properti, StartupTaskCompleted, bahwa layanan yang dihosting dapat diatur ke true ketika tugasnya yang berjalan lama selesai (StartupHostedServiceHealthCheck.cs):

public class StartupHostedServiceHealthCheck : IHealthCheck
{
    private volatile bool _startupTaskCompleted = false;

    public string Name => "slow_dependency_check";

    public bool StartupTaskCompleted
    {
        get => _startupTaskCompleted;
        set => _startupTaskCompleted = value;
    }

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default(CancellationToken))
    {
        if (StartupTaskCompleted)
        {
            return Task.FromResult(
                HealthCheckResult.Healthy("The startup task is finished."));
        }

        return Task.FromResult(
            HealthCheckResult.Unhealthy("The startup task is still running."));
    }
}

Tugas latar belakang yang berjalan lama dimulai oleh Layanan yang Dihosting (Services/StartupHostedService). Pada kesimpulan tugas, StartupHostedServiceHealthCheck.StartupTaskCompleted diatur ke true:

public class StartupHostedService : IHostedService, IDisposable
{
    private readonly int _delaySeconds = 15;
    private readonly ILogger _logger;
    private readonly StartupHostedServiceHealthCheck _startupHostedServiceHealthCheck;

    public StartupHostedService(ILogger<StartupHostedService> logger,
        StartupHostedServiceHealthCheck startupHostedServiceHealthCheck)
    {
        _logger = logger;
        _startupHostedServiceHealthCheck = startupHostedServiceHealthCheck;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("Startup Background Service is starting.");

        // Simulate the effect of a long-running startup task.
        Task.Run(async () =>
        {
            await Task.Delay(_delaySeconds * 1000);

            _startupHostedServiceHealthCheck.StartupTaskCompleted = true;

            _logger.LogInformation("Startup Background Service has started.");
        });

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("Startup Background Service is stopping.");

        return Task.CompletedTask;
    }

    public void Dispose()
    {
    }
}

Pemeriksaan kesehatan didaftarkan AddCheck bersama dengan layanan yang dihosting Startup.ConfigureServices . Karena layanan yang dihosting harus mengatur properti pada pemeriksaan kesehatan, pemeriksaan kesehatan juga terdaftar dalam kontainer layanan (LivenessProbeStartup.cs):

services.AddHostedService<StartupHostedService>();
services.AddSingleton<StartupHostedServiceHealthCheck>();

services.AddHealthChecks()
    .AddCheck<StartupHostedServiceHealthCheck>(
        "hosted_service_startup",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "ready" });

services.Configure<HealthCheckPublisherOptions>(options =>
{
    options.Delay = TimeSpan.FromSeconds(2);
    options.Predicate = (check) => check.Tags.Contains("ready");
});

services.AddSingleton<IHealthCheckPublisher, ReadinessPublisher>();

Titik akhir pemeriksaan kesehatan dibuat dengan memanggil MapHealthChecks di Startup.Configure. Di aplikasi sampel, titik akhir pemeriksaan kesehatan dibuat di:

• /health/ready untuk pemeriksaan kesiapan. Pemeriksaan kesiapan memfilter pemeriksaan kesehatan ke pemeriksaan kesehatan dengan ready tag.
• /health/live untuk pemeriksaan keaktivaan. Pemeriksaan keakuratan memfilter StartupHostedServiceHealthCheck dengan mengembalikan false ( HealthCheckOptions.Predicate untuk informasi selengkapnya, lihat Memfilter pemeriksaan kesehatan)

Dalam contoh kode berikut:

• Pemeriksaan kesiapan menggunakan semua pemeriksaan terdaftar dengan tag 'siap'.
• Mengecualikan Predicate semua pemeriksaan dan mengembalikan 200-Ok.

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health/ready", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("ready"),
    });

    endpoints.MapHealthChecks("/health/live", new HealthCheckOptions()
    {
        Predicate = (_) => false
    });
}

Untuk menjalankan skenario konfigurasi kesiapan/keaktifan menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:

dotnet run --scenario liveness

Di browser, kunjungi /health/ready beberapa kali hingga 15 detik berlalu. Laporan Unhealthy pemeriksaan kesehatan selama 15 detik pertama. Setelah 15 detik, titik akhir melaporkan Healthy, yang mencerminkan penyelesaian tugas yang berjalan lama oleh layanan yang dihosting.

Contoh ini juga membuat Penerbit Pemeriksaan Kesehatan (IHealthCheckPublisher implementasi) yang menjalankan pemeriksaan kesiapan pertama dengan penundaan dua detik. Untuk informasi selengkapnya, lihat bagian Penerbit Pemeriksaan Kesehatan.

Contoh Kubernetes

Menggunakan pemeriksaan kesiapan dan keaktifan terpisah berguna di lingkungan seperti Kubernetes. Di Kubernetes, aplikasi mungkin diperlukan untuk menjalankan pekerjaan startup yang memakan waktu sebelum menerima permintaan, seperti pengujian ketersediaan database yang mendasarinya. Menggunakan pemeriksaan terpisah memungkinkan orkestrator untuk membedakan apakah aplikasi berfungsi tetapi belum siap atau jika aplikasi gagal dimulai. Untuk informasi selengkapnya tentang pemeriksaan kesiapan dan keaktifan di Kubernetes, lihat Mengonfigurasi Pemeriksaan Keaktifan dan Kesiapan dalam dokumentasi Kubernetes.

Contoh berikut menunjukkan konfigurasi pemeriksaan kesiapan Kube:

spec:
  template:
  spec:
    readinessProbe:
      # an http probe
      httpGet:
        path: /health/ready
        port: 80
      # length of time to wait for a pod to initialize
      # after pod startup, before applying health checking
      initialDelaySeconds: 30
      timeoutSeconds: 1
    ports:
      - containerPort: 80

Pemeriksaan berbasis metrik dengan penulis respons kustom

Aplikasi sampel menunjukkan pemeriksaan kesehatan memori dengan penulis respons kustom.

MemoryHealthCheck melaporkan status terdegradasi jika aplikasi menggunakan lebih dari ambang memori tertentu (1 GB di aplikasi sampel). Termasuk HealthCheckResult informasi Pengumpul Sampah (GC) untuk aplikasi (MemoryHealthCheck.cs):

public class MemoryHealthCheck : IHealthCheck
{
    private readonly IOptionsMonitor<MemoryCheckOptions> _options;

    public MemoryHealthCheck(IOptionsMonitor<MemoryCheckOptions> options)
    {
        _options = options;
    }

    public string Name => "memory_check";

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default(CancellationToken))
    {
        var options = _options.Get(context.Registration.Name);

        // Include GC information in the reported diagnostics.
        var allocated = GC.GetTotalMemory(forceFullCollection: false);
        var data = new Dictionary<string, object>()
        {
            { "AllocatedBytes", allocated },
            { "Gen0Collections", GC.CollectionCount(0) },
            { "Gen1Collections", GC.CollectionCount(1) },
            { "Gen2Collections", GC.CollectionCount(2) },
        };
        var status = (allocated < options.Threshold) ?
            HealthStatus.Healthy : context.Registration.FailureStatus;

        return Task.FromResult(new HealthCheckResult(
            status,
            description: "Reports degraded status if allocated bytes " +
                $">= {options.Threshold} bytes.",
            exception: null,
            data: data));
    }
}

Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Startup.ConfigureServices. Alih-alih mengaktifkan pemeriksaan kesehatan dengan meneruskannya ke AddCheck, MemoryHealthCheck terdaftar sebagai layanan. Semua IHealthCheck layanan terdaftar tersedia untuk layanan pemeriksaan kesehatan dan middleware. Sebaiknya daftarkan layanan pemeriksaan kesehatan sebagai layanan Singleton.

Di CustomWriterStartup.cs aplikasi sampel:

services.AddHealthChecks()
    .AddMemoryHealthCheck("memory");

Titik akhir pemeriksaan kesehatan dibuat dengan memanggil MapHealthChecks di Startup.Configure. WriteResponse Delegasi diberikan ke ResponseWriter properti untuk menghasilkan respons JSON kustom saat pemeriksaan kesehatan dijalankan:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        ResponseWriter = WriteResponse
    });
}

Delegasi WriteResponse memformat CompositeHealthCheckResult ke dalam objek JSON dan menghasilkan output JSON untuk respons pemeriksaan kesehatan. Untuk informasi selengkapnya, lihat bagian Kustomisasi output .

Untuk menjalankan pemeriksaan berbasis metrik dengan output penulis respons kustom menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:

dotnet run --scenario writer

Filter menurut port

MapHealthChecks Panggil RequireHost dengan pola URL yang menentukan port untuk membatasi permintaan pemeriksaan kesehatan ke port yang ditentukan. Pendekatan ini biasanya digunakan dalam lingkungan kontainer untuk mengekspos port untuk layanan pemantauan.

Aplikasi sampel mengonfigurasi port menggunakan Penyedia Konfigurasi Variabel Lingkungan. Port diatur dalam file dan diteruskan launchSettings.json ke penyedia konfigurasi melalui variabel lingkungan. Anda juga harus mengonfigurasi server untuk mendengarkan permintaan pada port manajemen.

Untuk menggunakan aplikasi sampel untuk menunjukkan konfigurasi port manajemen, buat launchSettings.json file di Properties folder.

File berikut Properties/launchSettings.json dalam aplikasi sampel tidak disertakan dalam file proyek aplikasi sampel dan harus dibuat secara manual:

{
  "profiles": {
    "SampleApp": {
      "commandName": "Project",
      "commandLineArgs": "",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "ASPNETCORE_URLS": "http://localhost:5000/;http://localhost:5001/",
        "ASPNETCORE_MANAGEMENTPORT": "5001"
      },
      "applicationUrl": "http://localhost:5000/"
    }
  }
}

Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Startup.ConfigureServices. Buat titik akhir pemeriksaan kesehatan dengan memanggil MapHealthChecks di Startup.Configure.

Di aplikasi sampel, panggilan ke RequireHost pada titik akhir dalam Startup.Configure menentukan port manajemen dari konfigurasi:

endpoints.MapHealthChecks("/health")
    .RequireHost($"*:{Configuration["ManagementPort"]}");

Titik akhir dibuat di aplikasi sampel di Startup.Configure. Dalam contoh kode berikut:

• Pemeriksaan kesiapan menggunakan semua pemeriksaan terdaftar dengan tag 'siap'.
• Mengecualikan Predicate semua pemeriksaan dan mengembalikan 200-Ok.

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health/ready", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("ready"),
    });

    endpoints.MapHealthChecks("/health/live", new HealthCheckOptions()
    {
        Predicate = (_) => false
    });
}

return new HostBuilder()
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseKestrel()
            .ConfigureKestrel(serverOptions =>
            {
                serverOptions.ListenAnyIP(5001);
            })
            .UseStartup(startupType);
    })
    .Build();

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health").RequireHost("*:5001");
});

Untuk menjalankan skenario konfigurasi port manajemen menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:

dotnet run --scenario port

Mendistribusikan pustaka pemeriksaan kesehatan

Untuk mendistribusikan pemeriksaan kesehatan sebagai pustaka:

1. Tulis pemeriksaan kesehatan yang mengimplementasikan IHealthCheck antarmuka sebagai kelas mandiri. Kelas dapat mengandalkan injeksi dependensi (DI), aktivasi jenis, dan opsi bernama untuk mengakses data konfigurasi.

   Dalam logika pemeriksaan kesehatan :CheckHealthAsync

   • data1 dan data2 digunakan dalam metode untuk menjalankan logika pemeriksaan kesehatan probe.
   • AccessViolationException ditangani.

   AccessViolationException Ketika terjadi, FailureStatus dikembalikan dengan HealthCheckResult untuk memungkinkan pengguna mengonfigurasi status kegagalan pemeriksaan kesehatan.

   using System;
   using System.Threading;
   using System.Threading.Tasks;
   using Microsoft.Extensions.Diagnostics.HealthChecks;
   
   namespace SampleApp
   {
       public class ExampleHealthCheck : IHealthCheck
       {
           private readonly string _data1;
           private readonly int? _data2;
   
           public ExampleHealthCheck(string data1, int? data2)
           {
               _data1 = data1 ?? throw new ArgumentNullException(nameof(data1));
               _data2 = data2 ?? throw new ArgumentNullException(nameof(data2));
           }
   
           public async Task<HealthCheckResult> CheckHealthAsync(
               HealthCheckContext context, CancellationToken cancellationToken)
           {
               try
               {
                   return HealthCheckResult.Healthy();
               }
               catch (AccessViolationException ex)
               {
                   return new HealthCheckResult(
                       context.Registration.FailureStatus,
                       description: "An access violation occurred during the check.",
                       exception: ex,
                       data: null);
               }
           }
       }
   }
   

2. Tulis metode ekstensi dengan parameter yang dipanggil aplikasi yang mengonsumsi dalam metodenya Startup.Configure . Dalam contoh berikut, asumsikan tanda tangan metode pemeriksaan kesehatan berikut:

   ExampleHealthCheck(string, string, int )
   

   Tanda tangan sebelumnya menunjukkan bahwa ExampleHealthCheck memerlukan data tambahan untuk memproses logika pemeriksaan kesehatan. Data diberikan kepada delegasi yang digunakan untuk membuat instans pemeriksaan kesehatan saat pemeriksaan kesehatan terdaftar dengan metode ekstensi. Dalam contoh berikut, pemanggil menentukan opsional:

   • nama pemeriksaan kesehatan (name). Jika null, example_health_check digunakan.
   • titik data string untuk pemeriksaan kesehatan (data1).
   • titik data bilangan bulat untuk pemeriksaan kesehatan (data2). Jika null, 1 digunakan.
   • status kegagalan (HealthStatus). Default adalah null. Jika null, HealthStatus.Unhealthy dilaporkan untuk status kegagalan.
   • tag (IEnumerable<string>).

   using System.Collections.Generic;
   using Microsoft.Extensions.Diagnostics.HealthChecks;
   
   public static class ExampleHealthCheckBuilderExtensions
   {
       const string DefaultName = "example_health_check";
   
       public static IHealthChecksBuilder AddExampleHealthCheck(
           this IHealthChecksBuilder builder,
           string name = default,
           string data1,
           int data2 = 1,
           HealthStatus? failureStatus = default,
           IEnumerable<string> tags = default)
       {
           return builder.Add(new HealthCheckRegistration(
               name ?? DefaultName,
               sp => new ExampleHealthCheck(data1, data2),
               failureStatus,
               tags));
       }
   }
   

Penerbit Pemeriksaan Kesehatan

IHealthCheckPublisher Ketika ditambahkan ke kontainer layanan, sistem pemeriksaan kesehatan secara berkala menjalankan pemeriksaan dan panggilan PublishAsync kesehatan Anda dengan hasilnya. Ini berguna dalam skenario sistem pemantauan kesehatan berbasis dorong yang mengharapkan setiap proses memanggil sistem pemantauan secara berkala untuk menentukan kesehatan.

Antarmuka IHealthCheckPublisher memiliki satu metode:

Task PublishAsync(HealthReport report, CancellationToken cancellationToken);

HealthCheckPublisherOptions memungkinkan Anda mengatur:

• Delay: Penundaan awal diterapkan setelah aplikasi dimulai sebelum menjalankan IHealthCheckPublisher instans. Penundaan diterapkan sekali saat startup dan tidak berlaku untuk perulangan berikutnya. Nilai defaultnya adalah lima detik.
• Period: Periode IHealthCheckPublisher eksekusi. Nilai {i>default
• Predicate: Jika Predicate ( null default), layanan penerbit pemeriksaan kesehatan menjalankan semua pemeriksaan kesehatan terdaftar. Untuk menjalankan subset pemeriksaan kesehatan, berikan fungsi yang memfilter serangkaian pemeriksaan. Predikat dievaluasi setiap periode.
• Timeout: Batas waktu untuk menjalankan pemeriksaan kesehatan untuk semua IHealthCheckPublisher instans. Gunakan InfiniteTimeSpan untuk mengeksekusi tanpa batas waktu. Nilai {i>default

Dalam aplikasi sampel, ReadinessPublisher adalah IHealthCheckPublisher implementasi. Status pemeriksaan kesehatan dicatat untuk setiap pemeriksaan pada tingkat log:

• Informasi (LogInformation) jika status pemeriksaan kesehatan adalah Healthy.
• Kesalahan (LogError) jika statusnya adalah Degraded atau Unhealthy.

public class ReadinessPublisher : IHealthCheckPublisher
{
    private readonly ILogger _logger;

    public ReadinessPublisher(ILogger<ReadinessPublisher> logger)
    {
        _logger = logger;
    }

    // The following example is for demonstration purposes only. Health Checks
    // Middleware already logs health checks results. A real-world readiness
    // check in a production app might perform a set of more expensive or
    // time-consuming checks to determine if other resources are responding
    // properly.
    public Task PublishAsync(HealthReport report,
        CancellationToken cancellationToken)
    {
        if (report.Status == HealthStatus.Healthy)
        {
            _logger.LogInformation("{Timestamp} Readiness Probe Status: {Result}",
                DateTime.UtcNow, report.Status);
        }
        else
        {
            _logger.LogError("{Timestamp} Readiness Probe Status: {Result}",
                DateTime.UtcNow, report.Status);
        }

        cancellationToken.ThrowIfCancellationRequested();

        return Task.CompletedTask;
    }
}

Dalam contoh aplikasi LivenessProbeStartup sampel, StartupHostedService pemeriksaan kesiapan memiliki penundaan startup dua detik dan menjalankan pemeriksaan setiap 30 detik. Untuk mengaktifkan IHealthCheckPublisher implementasi, sampel mendaftar ReadinessPublisher sebagai layanan singleton dalam kontainer injeksi dependensi (DI):

services.AddHostedService<StartupHostedService>();
services.AddSingleton<StartupHostedServiceHealthCheck>();

services.AddHealthChecks()
    .AddCheck<StartupHostedServiceHealthCheck>(
        "hosted_service_startup",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "ready" });

services.Configure<HealthCheckPublisherOptions>(options =>
{
    options.Delay = TimeSpan.FromSeconds(2);
    options.Predicate = (check) => check.Tags.Contains("ready");
});

services.AddSingleton<IHealthCheckPublisher, ReadinessPublisher>();

Membatasi pemeriksaan kesehatan dengan MapWhen

Gunakan MapWhen untuk mencabangkan alur permintaan untuk titik akhir pemeriksaan kesehatan secara kondisional.

Dalam contoh berikut, MapWhen mencabangkan alur permintaan untuk mengaktifkan Middleware Pemeriksaan Kesehatan jika permintaan GET diterima untuk api/HealthCheck titik akhir:

app.MapWhen(
    context => context.Request.Method == HttpMethod.Get.Method && 
        context.Request.Path.StartsWith("/api/HealthCheck"),
    builder => builder.UseHealthChecks());

app.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
});

Untuk informasi lebih lanjut, lihat Middleware ASP.NET Core.

ASP.NET Core menawarkan Middleware pemeriksaan kesehatan dan pustaka untuk melaporkan kesehatan komponen infrastruktur aplikasi.

Pemeriksaan kesehatan diekspos oleh aplikasi sebagai titik akhir HTTP. Titik akhir pemeriksaan kesehatan dapat dikonfigurasi untuk berbagai skenario pemantauan real-time:

• Pemeriksaan kesehatan dapat digunakan oleh orkestrator kontainer dan load balancer untuk memeriksa status aplikasi. Misalnya, orkestrator kontainer dapat merespons pemeriksaan kesehatan yang gagal dengan menghentikan penyebaran bergulir atau memulai ulang kontainer. Load balancer mungkin bereaksi terhadap aplikasi yang tidak sehat dengan merutekan lalu lintas dari instans yang gagal ke instans yang sehat.
• Penggunaan memori, disk, dan sumber daya server fisik lainnya dapat dipantau untuk status sehat.
• Pemeriksaan kesehatan dapat menguji dependensi aplikasi, seperti database dan titik akhir layanan eksternal, untuk mengonfirmasi ketersediaan dan fungsi normal.

Melihat atau mengunduh kode sampel (cara mengunduh)

Aplikasi sampel menyertakan contoh skenario yang dijelaskan dalam artikel ini. Untuk menjalankan aplikasi sampel untuk skenario tertentu, gunakan perintah jalankan dotnet dari folder proyek dalam shell perintah. Lihat contoh file aplikasi README.md dan deskripsi skenario dalam artikel ini untuk detail tentang cara menggunakan aplikasi sampel.

Prasyarat

Pemeriksaan kesehatan biasanya digunakan dengan layanan pemantauan eksternal atau orkestrator kontainer untuk memeriksa status aplikasi. Sebelum menambahkan pemeriksaan kesehatan ke aplikasi, putuskan sistem pemantauan mana yang akan digunakan. Sistem pemantauan menentukan jenis pemeriksaan kesehatan apa yang akan dibuat dan cara mengonfigurasi titik akhirnya.

Paket Microsoft.AspNetCore.Diagnostics.HealthChecks ini dirujuk secara implisit untuk aplikasi ASP.NET Core. Untuk menjalankan pemeriksaan kesehatan menggunakan Entity Framework Core, tambahkan referensi paket ke Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore paket.

Aplikasi sampel menyediakan kode startup untuk menunjukkan pemeriksaan kesehatan untuk beberapa skenario. Skenario pemeriksaan database memeriksa kesehatan koneksi database menggunakan AspNetCore.Diagnostics.HealthChecks. Skenario pemeriksaan DbContext memeriksa database menggunakan EF CoreDbContext. Untuk menjelajahi skenario database, aplikasi sampel:

• Membuat database dan menyediakan string koneksi dalam appsettings.json file.
• Memiliki referensi paket berikut dalam file proyeknya:
  • AspNetCore.HealthChecks.SqlServer
  • Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore

Skenario pemeriksaan kesehatan lain menunjukkan cara memfilter pemeriksaan kesehatan ke port manajemen. Aplikasi sampel mengharuskan Anda membuat Properties/launchSettings.json file yang menyertakan URL manajemen dan port manajemen. Untuk informasi selengkapnya, lihat bagian Filter menurut port .

Pemeriksaan kesehatan dasar

Untuk banyak aplikasi, konfigurasi pemeriksaan kesehatan dasar yang melaporkan ketersediaan aplikasi untuk memproses permintaan (liveness) cukup untuk menemukan status aplikasi.

Konfigurasi dasar mendaftarkan layanan pemeriksaan kesehatan dan memanggil Middleware Pemeriksaan Kesehatan untuk merespons di titik akhir URL dengan respons kesehatan. Secara default, tidak ada pemeriksaan kesehatan tertentu yang terdaftar untuk menguji dependensi atau subsistem tertentu. Aplikasi ini dianggap sehat jika dapat merespons di URL titik akhir kesehatan. Penulis respons default menulis status (HealthStatus) sebagai respons teks biasa kembali ke klien, menunjukkan HealthStatus.Healthystatus , , HealthStatus.Degradedatau HealthStatus.Unhealthy .

Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Startup.ConfigureServices. Buat titik akhir pemeriksaan kesehatan dengan memanggil MapHealthChecks di Startup.Configure.

Di aplikasi sampel, titik akhir pemeriksaan kesehatan dibuat di /health (BasicStartup.cs):

public class BasicStartup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddHealthChecks();
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapHealthChecks("/health");
        });
    }
}

Untuk menjalankan skenario konfigurasi dasar menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:

dotnet run --scenario basic

Contoh Docker

Docker menawarkan arahan bawaan HEALTHCHECK yang dapat digunakan untuk memeriksa status aplikasi yang menggunakan konfigurasi pemeriksaan kesehatan dasar:

HEALTHCHECK CMD curl --fail http://localhost:5000/health || exit

Membuat pemeriksaan kesehatan

Pemeriksaan kesehatan dibuat dengan menerapkan IHealthCheck antarmuka. Metode CheckHealthAsync mengembalikan HealthCheckResult yang menunjukkan kesehatan sebagai Healthy, , Degradedatau Unhealthy. Hasilnya ditulis sebagai respons teks biasa dengan kode status yang dapat dikonfigurasi (konfigurasi dijelaskan di bagian Opsi pemeriksaan kesehatan). HealthCheckResult juga dapat mengembalikan pasangan kunci-nilai opsional.

Kelas berikut ExampleHealthCheck menunjukkan tata letak pemeriksaan kesehatan. Logika pemeriksaan kesehatan ditempatkan dalam CheckHealthAsync metode . Contoh berikut menetapkan variabel dummy, healthCheckResultHealthy, ke true. Jika nilai healthCheckResultHealthy diatur ke false, HealthCheckResult.Unhealthy status dikembalikan.

public class ExampleHealthCheck : IHealthCheck
{
    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default(CancellationToken))
    {
        var healthCheckResultHealthy = true;

        if (healthCheckResultHealthy)
        {
            return Task.FromResult(
                HealthCheckResult.Healthy("A healthy result."));
        }

        return Task.FromResult(
            HealthCheckResult.Unhealthy("An unhealthy result."));
    }
}

Mendaftarkan layanan pemeriksaan kesehatan

ExampleHealthCheck Jenis ditambahkan ke layanan pemeriksaan kesehatan dengan AddCheck di Startup.ConfigureServices:

services.AddHealthChecks()
    .AddCheck<ExampleHealthCheck>("example_health_check");

Kelebihan AddCheck beban yang ditunjukkan dalam contoh berikut menetapkan status kegagalan (HealthStatus) untuk melaporkan saat pemeriksaan kesehatan melaporkan kegagalan. Jika status kegagalan diatur ke null (default), HealthStatus.Unhealthy dilaporkan. Kelebihan beban ini adalah skenario yang berguna untuk penulis pustaka, di mana status kegagalan yang ditunjukkan oleh pustaka diberlakukan oleh aplikasi ketika kegagalan pemeriksaan kesehatan terjadi jika implementasi pemeriksaan kesehatan mematuhi pengaturan.

Tag dapat digunakan untuk memfilter pemeriksaan kesehatan (dijelaskan lebih lanjut di bagian Filter pemeriksaan kesehatan).

services.AddHealthChecks()
    .AddCheck<ExampleHealthCheck>(
        "example_health_check",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "example" });

AddCheck juga dapat menjalankan fungsi lambda. Dalam contoh berikut, nama pemeriksaan kesehatan ditentukan sebagai Example dan pemeriksaan selalu mengembalikan status sehat:

services.AddHealthChecks()
    .AddCheck("Example", () =>
        HealthCheckResult.Healthy("Example is OK!"), tags: new[] { "example" });

Panggil AddTypeActivatedCheck untuk meneruskan argumen ke implementasi pemeriksaan kesehatan. Dalam contoh berikut, TestHealthCheckWithArgs menerima bilangan bulat dan string untuk digunakan saat CheckHealthAsync dipanggil:

private class TestHealthCheckWithArgs : IHealthCheck
{
    public TestHealthCheckWithArgs(int i, string s)
    {
        I = i;
        S = s;
    }

    public int I { get; set; }

    public string S { get; set; }

    public Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context, 
        CancellationToken cancellationToken = default)
    {
        ...
    }
}

TestHealthCheckWithArgs terdaftar dengan memanggil dengan bilangan AddTypeActivatedCheck bulat dan string yang diteruskan ke implementasi:

services.AddHealthChecks()
    .AddTypeActivatedCheck<TestHealthCheckWithArgs>(
        "test", 
        failureStatus: HealthStatus.Degraded, 
        tags: new[] { "example" }, 
        args: new object[] { 5, "string" });

Gunakan Perutean Pemeriksaan Kesehatan

Di Startup.Configure, panggil MapHealthChecks pembangun titik akhir dengan URL titik akhir atau jalur relatif:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
});

Memerlukan host

Panggil RequireHost untuk menentukan satu atau beberapa host yang diizinkan untuk titik akhir pemeriksaan kesehatan. Host harus Unicode daripada punycode dan dapat mencakup port. Jika koleksi tidak disediakan, host apa pun akan diterima.

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health").RequireHost("www.contoso.com:5001");
});

Untuk informasi selengkapnya, lihat bagian Filter menurut port .

Memerlukan otorisasi

Panggil RequireAuthorization untuk menjalankan Middleware Otorisasi pada titik akhir permintaan pemeriksaan kesehatan. Kelebihan RequireAuthorization beban menerima satu atau beberapa kebijakan otorisasi. Jika kebijakan tidak disediakan, kebijakan otorisasi default digunakan.

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health").RequireAuthorization();
});

Mengaktifkan Permintaan Lintas Asal (CORS)

Meskipun menjalankan pemeriksaan kesehatan secara manual dari browser bukanlah skenario penggunaan umum, CORS Middleware dapat diaktifkan dengan memanggil RequireCors titik akhir pemeriksaan kesehatan. Kelebihan RequireCors beban menerima delegasi pembuat kebijakan CORS (CorsPolicyBuilder) atau nama kebijakan. Jika kebijakan tidak disediakan, kebijakan CORS default akan digunakan. Untuk informasi selengkapnya, lihat Mengaktifkan Permintaan Lintas Asal (CORS) di ASP.NET Core.

Opsi pemeriksaan kesehatan

HealthCheckOptions memberikan kesempatan untuk menyesuaikan perilaku pemeriksaan kesehatan:

• Memfilter pemeriksaan kesehatan
• Mengkustomisasi kode status HTTP
• Menyembunyikan header cache
• Sesuaikan output

Memfilter pemeriksaan kesehatan

Secara default, Middleware Pemeriksaan Kesehatan menjalankan semua pemeriksaan kesehatan terdaftar. Untuk menjalankan subset pemeriksaan kesehatan, berikan fungsi yang mengembalikan boolean ke Predicate opsi . Dalam contoh berikut, Bar pemeriksaan kesehatan difilter oleh tag -nya (bar_tag) dalam pernyataan kondisi fungsi, di mana true hanya dikembalikan jika properti pemeriksaan Tags kesehatan cocok foo_tag atau baz_tag:

Di Startup.ConfigureServices:

services.AddHealthChecks()
    .AddCheck("Foo", () =>
        HealthCheckResult.Healthy("Foo is OK!"), tags: new[] { "foo_tag" })
    .AddCheck("Bar", () =>
        HealthCheckResult.Unhealthy("Bar is unhealthy!"), tags: new[] { "bar_tag" })
    .AddCheck("Baz", () =>
        HealthCheckResult.Healthy("Baz is OK!"), tags: new[] { "baz_tag" });

Di Startup.Configure, Predicate filter pemeriksaan kesehatan 'Bar'. Hanya Foo dan Baz yang dijalankan:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("foo_tag") ||
            check.Tags.Contains("baz_tag")
    });
});

Mengkustomisasi kode status HTTP

Gunakan ResultStatusCodes untuk menyesuaikan pemetaan status kesehatan ke kode status HTTP. Tugas berikut StatusCodes adalah nilai default yang digunakan oleh middleware. Ubah nilai kode status untuk memenuhi kebutuhan Anda.

Di Startup.Configure:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        ResultStatusCodes =
        {
            [HealthStatus.Healthy] = StatusCodes.Status200OK,
            [HealthStatus.Degraded] = StatusCodes.Status200OK,
            [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
        }
    });
});

Menyembunyikan header cache

AllowCachingResponses mengontrol apakah Middleware Pemeriksaan Kesehatan menambahkan header HTTP ke respons pemeriksaan untuk mencegah penembolokan respons. Jika nilainya ( false default), middleware mengatur atau mengambil Cache-Controlalih header , , Expiresdan Pragma untuk mencegah penembolokan respons. Jika nilainya adalah true, middleware tidak mengubah header cache respons.

Di Startup.Configure:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        AllowCachingResponses = true
    });
});

Sesuaikan output

Di Startup.Configure, atur HealthCheckOptions.ResponseWriter opsi ke delegasi untuk menulis respons:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        ResponseWriter = WriteResponse
    });
});

Delegasi default menulis respons teks biasa minimal dengan nilai HealthReport.Statusstring . Delegasi kustom berikut menghasilkan respons JSON kustom.

Contoh pertama dari aplikasi sampel menunjukkan cara menggunakan System.Text.Json:

private static Task WriteResponse(HttpContext context, HealthReport result)
{
    context.Response.ContentType = "application/json; charset=utf-8";

    var options = new JsonWriterOptions
    {
        Indented = true
    };

    using (var stream = new MemoryStream())
    {
        using (var writer = new Utf8JsonWriter(stream, options))
        {
            writer.WriteStartObject();
            writer.WriteString("status", result.Status.ToString());
            writer.WriteStartObject("results");
            foreach (var entry in result.Entries)
            {
                writer.WriteStartObject(entry.Key);
                writer.WriteString("status", entry.Value.Status.ToString());
                writer.WriteString("description", entry.Value.Description);
                writer.WriteStartObject("data");
                foreach (var item in entry.Value.Data)
                {
                    writer.WritePropertyName(item.Key);
                    JsonSerializer.Serialize(
                        writer, item.Value, item.Value?.GetType() ??
                        typeof(object));
                }
                writer.WriteEndObject();
                writer.WriteEndObject();
            }
            writer.WriteEndObject();
            writer.WriteEndObject();
        }

        var json = Encoding.UTF8.GetString(stream.ToArray());

        return context.Response.WriteAsync(json);
    }
}

Contoh kedua menunjukkan cara menggunakan Newtonsoft.Json:

private static Task WriteResponse(HttpContext context, HealthReport result)
{
    context.Response.ContentType = "application/json";

    var json = new JObject(
        new JProperty("status", result.Status.ToString()),
        new JProperty("results", new JObject(result.Entries.Select(pair =>
            new JProperty(pair.Key, new JObject(
                new JProperty("status", pair.Value.Status.ToString()),
                new JProperty("description", pair.Value.Description),
                new JProperty("data", new JObject(pair.Value.Data.Select(
                    p => new JProperty(p.Key, p.Value))))))))));

    return context.Response.WriteAsync(
        json.ToString(Formatting.Indented));
}

Di aplikasi sampel, komentari SYSTEM_TEXT_JSON direktif praproscesor untuk CustomWriterStartup.cs mengaktifkan Newtonsoft.Json versi WriteResponse.

API pemeriksaan kesehatan tidak menyediakan dukungan bawaan untuk format pengembalian JSON yang kompleks karena formatnya khusus untuk sistem pemantauan pilihan Anda. Sesuaikan respons dalam contoh sebelumnya sesuai kebutuhan. Untuk informasi selengkapnya tentang serialisasi JSON dengan System.Text.Json, lihat Cara membuat serialisasi dan deserialisasi JSON di .NET.

Pemeriksaan database

Pemeriksaan kesehatan dapat menentukan kueri database untuk dijalankan sebagai pengujian boolean untuk menunjukkan apakah database merespons secara normal.

Aplikasi sampel menggunakan AspNetCore.Diagnostics.HealthChecks, pustaka pemeriksaan kesehatan untuk aplikasi ASP.NET Core, untuk menjalankan pemeriksaan kesehatan pada database SQL Server. AspNetCore.Diagnostics.HealthChecksSELECT 1 menjalankan kueri terhadap database untuk mengonfirmasi koneksi ke database sehat.

Sertakan referensi paket ke AspNetCore.HealthChecks.SqlServer.

Berikan string koneksi database yang valid dalam appsettings.json file aplikasi sampel. Aplikasi ini menggunakan database SQL Server bernama HealthCheckSample:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\MSSQLLocalDB;Database=HealthCheckSample;Trusted_Connection=True;MultipleActiveResultSets=true;ConnectRetryCount=0"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    },
    "Console": {
      "IncludeScopes": "true"
    }
  },
  "AllowedHosts": "*"
}

Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Startup.ConfigureServices. Aplikasi sampel memanggil AddSqlServer metode dengan string koneksi database (DbHealthStartup.cs):

services.AddHealthChecks()
    .AddSqlServer(Configuration["ConnectionStrings:DefaultConnection"]);

Titik akhir pemeriksaan kesehatan dibuat dengan memanggil MapHealthChecks di Startup.Configure:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
}

Untuk menjalankan skenario pemeriksaan database menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:

dotnet run --scenario db

Pemeriksaan Entity Framework Core DbContext

Pemeriksaan DbContext mengonfirmasi bahwa aplikasi dapat berkomunikasi dengan database yang dikonfigurasi untuk EF CoreDbContext. DbContext Pemeriksaan didukung di aplikasi yang:

• Gunakan Core Entity Framework (EF).
• Sertakan referensi paket ke Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore.

AddDbContextCheck<TContext> mendaftarkan pemeriksaan kesehatan untuk DbContext. DbContext disediakan sebagai untuk TContext metode . Kelebihan beban tersedia untuk mengonfigurasi status kegagalan, tag, dan kueri pengujian kustom.

Secara default:

• Metode DbContextHealthCheck panggilanEF CoreCanConnectAsync. Anda dapat menyesuaikan operasi apa yang dijalankan saat memeriksa kesehatan menggunakan AddDbContextCheck kelebihan beban metode.
• Nama pemeriksaan kesehatan adalah nama jenisnya TContext .

Dalam aplikasi sampel, AppDbContext disediakan untuk AddDbContextCheck dan didaftarkan sebagai layanan di Startup.ConfigureServices (DbContextHealthStartup.cs):

services.AddHealthChecks()
    .AddDbContextCheck<AppDbContext>();

services.AddDbContext<AppDbContext>(options =>
{
    options.UseSqlServer(
        Configuration["ConnectionStrings:DefaultConnection"]);
});

Titik akhir pemeriksaan kesehatan dibuat dengan memanggil MapHealthChecks di Startup.Configure:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
}

Untuk menjalankan DbContext skenario pemeriksaan menggunakan aplikasi sampel, konfirmasikan bahwa database yang ditentukan oleh string koneksi tidak ada di instans SQL Server. Jika database ada, hapus database tersebut.

Jalankan perintah berikut dari folder proyek dalam shell perintah:

dotnet run --scenario dbcontext

Setelah aplikasi berjalan, periksa status kesehatan dengan membuat permintaan ke /health titik akhir di browser. Database dan AppDbContext tidak ada, sehingga aplikasi memberikan respons berikut:

Unhealthy

Picu aplikasi sampel untuk membuat database. Buat permintaan ke /createdatabase. Aplikasi merespons:

Creating the database...
Done!
Navigate to /health to see the health status.

Buat permintaan ke /health titik akhir. Database dan konteks ada, sehingga aplikasi merespons:

Healthy

Picu aplikasi sampel untuk menghapus database. Buat permintaan ke /deletedatabase. Aplikasi merespons:

Deleting the database...
Done!
Navigate to /health to see the health status.

Buat permintaan ke /health titik akhir. Aplikasi ini memberikan respons yang tidak sehat:

Unhealthy

Pemeriksaan kesiapan dan keaktifan terpisah

Dalam beberapa skenario hosting, sepasang pemeriksaan kesehatan digunakan untuk membedakan dua status aplikasi:

• Kesiapan menunjukkan apakah aplikasi berjalan normal tetapi belum siap untuk menerima permintaan.
• Liveness menunjukkan apakah aplikasi mengalami crash dan harus dimulai ulang.

Pertimbangkan contoh berikut: Aplikasi harus mengunduh file konfigurasi besar sebelum siap memproses permintaan. Kami tidak ingin aplikasi dimulai ulang jika unduhan awal gagal karena aplikasi dapat mencoba lagi mengunduh file beberapa kali. Kami menggunakan pemeriksaan keaktifan untuk menggambarkan keaktifan proses, tidak ada pemeriksaan lain yang dijalankan. Kami juga ingin mencegah permintaan dikirim ke aplikasi sebelum pengunduhan file konfigurasi berhasil. Kami menggunakan pemeriksaan kesiapan untuk menunjukkan status "belum siap" sampai unduhan berhasil dan aplikasi siap menerima permintaan.

Aplikasi sampel berisi pemeriksaan kesehatan untuk melaporkan penyelesaian tugas startup yang berjalan lama di Layanan yang Dihosting. Mengekspos StartupHostedServiceHealthCheck properti, StartupTaskCompleted, bahwa layanan yang dihosting dapat diatur ke true ketika tugasnya yang berjalan lama selesai (StartupHostedServiceHealthCheck.cs):

public class StartupHostedServiceHealthCheck : IHealthCheck
{
    private volatile bool _startupTaskCompleted = false;

    public string Name => "slow_dependency_check";

    public bool StartupTaskCompleted
    {
        get => _startupTaskCompleted;
        set => _startupTaskCompleted = value;
    }

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default(CancellationToken))
    {
        if (StartupTaskCompleted)
        {
            return Task.FromResult(
                HealthCheckResult.Healthy("The startup task is finished."));
        }

        return Task.FromResult(
            HealthCheckResult.Unhealthy("The startup task is still running."));
    }
}

Tugas latar belakang yang berjalan lama dimulai oleh Layanan yang Dihosting (Services/StartupHostedService). Pada kesimpulan tugas, StartupHostedServiceHealthCheck.StartupTaskCompleted diatur ke true:

public class StartupHostedService : IHostedService, IDisposable
{
    private readonly int _delaySeconds = 15;
    private readonly ILogger _logger;
    private readonly StartupHostedServiceHealthCheck _startupHostedServiceHealthCheck;

    public StartupHostedService(ILogger<StartupHostedService> logger,
        StartupHostedServiceHealthCheck startupHostedServiceHealthCheck)
    {
        _logger = logger;
        _startupHostedServiceHealthCheck = startupHostedServiceHealthCheck;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("Startup Background Service is starting.");

        // Simulate the effect of a long-running startup task.
        Task.Run(async () =>
        {
            await Task.Delay(_delaySeconds * 1000);

            _startupHostedServiceHealthCheck.StartupTaskCompleted = true;

            _logger.LogInformation("Startup Background Service has started.");
        });

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("Startup Background Service is stopping.");

        return Task.CompletedTask;
    }

    public void Dispose()
    {
    }
}

Pemeriksaan kesehatan didaftarkan AddCheck bersama dengan layanan yang dihosting Startup.ConfigureServices . Karena layanan yang dihosting harus mengatur properti pada pemeriksaan kesehatan, pemeriksaan kesehatan juga terdaftar dalam kontainer layanan (LivenessProbeStartup.cs):

services.AddHostedService<StartupHostedService>();
services.AddSingleton<StartupHostedServiceHealthCheck>();

services.AddHealthChecks()
    .AddCheck<StartupHostedServiceHealthCheck>(
        "hosted_service_startup",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "ready" });

services.Configure<HealthCheckPublisherOptions>(options =>
{
    options.Delay = TimeSpan.FromSeconds(2);
    options.Predicate = (check) => check.Tags.Contains("ready");
});

services.AddSingleton<IHealthCheckPublisher, ReadinessPublisher>();

Titik akhir pemeriksaan kesehatan dibuat dengan memanggil MapHealthChecks di Startup.Configure. Di aplikasi sampel, titik akhir pemeriksaan kesehatan dibuat di:

• /health/ready untuk pemeriksaan kesiapan. Pemeriksaan kesiapan memfilter pemeriksaan kesehatan ke pemeriksaan kesehatan dengan ready tag.
• /health/live untuk pemeriksaan keaktivaan. Pemeriksaan keakuratan memfilter StartupHostedServiceHealthCheck dengan mengembalikan false ( HealthCheckOptions.Predicate untuk informasi selengkapnya, lihat Memfilter pemeriksaan kesehatan)

Dalam contoh kode berikut:

• Pemeriksaan kesiapan menggunakan semua pemeriksaan terdaftar dengan tag 'siap'.
• Mengecualikan Predicate semua pemeriksaan dan mengembalikan 200-Ok.

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health/ready", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("ready"),
    });

    endpoints.MapHealthChecks("/health/live", new HealthCheckOptions()
    {
        Predicate = (_) => false
    });
}

Untuk menjalankan skenario konfigurasi kesiapan/keaktifan menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:

dotnet run --scenario liveness

Di browser, kunjungi /health/ready beberapa kali hingga 15 detik berlalu. Laporan Unhealthy pemeriksaan kesehatan selama 15 detik pertama. Setelah 15 detik, titik akhir melaporkan Healthy, yang mencerminkan penyelesaian tugas yang berjalan lama oleh layanan yang dihosting.

Contoh ini juga membuat Penerbit Pemeriksaan Kesehatan (IHealthCheckPublisher implementasi) yang menjalankan pemeriksaan kesiapan pertama dengan penundaan dua detik. Untuk informasi selengkapnya, lihat bagian Penerbit Pemeriksaan Kesehatan.

Contoh Kubernetes

Menggunakan pemeriksaan kesiapan dan keaktifan terpisah berguna di lingkungan seperti Kubernetes. Di Kubernetes, aplikasi mungkin diperlukan untuk menjalankan pekerjaan startup yang memakan waktu sebelum menerima permintaan, seperti pengujian ketersediaan database yang mendasarinya. Menggunakan pemeriksaan terpisah memungkinkan orkestrator untuk membedakan apakah aplikasi berfungsi tetapi belum siap atau jika aplikasi gagal dimulai. Untuk informasi selengkapnya tentang pemeriksaan kesiapan dan keaktifan di Kubernetes, lihat Mengonfigurasi Pemeriksaan Keaktifan dan Kesiapan dalam dokumentasi Kubernetes.

Contoh berikut menunjukkan konfigurasi pemeriksaan kesiapan Kube:

spec:
  template:
  spec:
    readinessProbe:
      # an http probe
      httpGet:
        path: /health/ready
        port: 80
      # length of time to wait for a pod to initialize
      # after pod startup, before applying health checking
      initialDelaySeconds: 30
      timeoutSeconds: 1
    ports:
      - containerPort: 80

Pemeriksaan berbasis metrik dengan penulis respons kustom

Aplikasi sampel menunjukkan pemeriksaan kesehatan memori dengan penulis respons kustom.

MemoryHealthCheck melaporkan status terdegradasi jika aplikasi menggunakan lebih dari ambang memori tertentu (1 GB di aplikasi sampel). Termasuk HealthCheckResult informasi Pengumpul Sampah (GC) untuk aplikasi (MemoryHealthCheck.cs):

public class MemoryHealthCheck : IHealthCheck
{
    private readonly IOptionsMonitor<MemoryCheckOptions> _options;

    public MemoryHealthCheck(IOptionsMonitor<MemoryCheckOptions> options)
    {
        _options = options;
    }

    public string Name => "memory_check";

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default(CancellationToken))
    {
        var options = _options.Get(context.Registration.Name);

        // Include GC information in the reported diagnostics.
        var allocated = GC.GetTotalMemory(forceFullCollection: false);
        var data = new Dictionary<string, object>()
        {
            { "AllocatedBytes", allocated },
            { "Gen0Collections", GC.CollectionCount(0) },
            { "Gen1Collections", GC.CollectionCount(1) },
            { "Gen2Collections", GC.CollectionCount(2) },
        };
        var status = (allocated < options.Threshold) ?
            HealthStatus.Healthy : context.Registration.FailureStatus;

        return Task.FromResult(new HealthCheckResult(
            status,
            description: "Reports degraded status if allocated bytes " +
                $">= {options.Threshold} bytes.",
            exception: null,
            data: data));
    }
}

Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Startup.ConfigureServices. Alih-alih mengaktifkan pemeriksaan kesehatan dengan meneruskannya ke AddCheck, MemoryHealthCheck terdaftar sebagai layanan. Semua IHealthCheck layanan terdaftar tersedia untuk layanan pemeriksaan kesehatan dan middleware. Sebaiknya daftarkan layanan pemeriksaan kesehatan sebagai layanan Singleton.

Di CustomWriterStartup.cs aplikasi sampel:

services.AddHealthChecks()
    .AddMemoryHealthCheck("memory");

Titik akhir pemeriksaan kesehatan dibuat dengan memanggil MapHealthChecks di Startup.Configure. WriteResponse Delegasi diberikan ke ResponseWriter properti untuk menghasilkan respons JSON kustom saat pemeriksaan kesehatan dijalankan:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        ResponseWriter = WriteResponse
    });
}

Delegasi WriteResponse memformat CompositeHealthCheckResult ke dalam objek JSON dan menghasilkan output JSON untuk respons pemeriksaan kesehatan. Untuk informasi selengkapnya, lihat bagian Kustomisasi output .

Untuk menjalankan pemeriksaan berbasis metrik dengan output penulis respons kustom menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:

dotnet run --scenario writer

Filter menurut port

MapHealthChecks Panggil RequireHost dengan pola URL yang menentukan port untuk membatasi permintaan pemeriksaan kesehatan ke port yang ditentukan. Pendekatan ini biasanya digunakan dalam lingkungan kontainer untuk mengekspos port untuk layanan pemantauan.

Aplikasi sampel mengonfigurasi port menggunakan Penyedia Konfigurasi Variabel Lingkungan. Port diatur dalam file dan diteruskan launchSettings.json ke penyedia konfigurasi melalui variabel lingkungan. Anda juga harus mengonfigurasi server untuk mendengarkan permintaan pada port manajemen.

Untuk menggunakan aplikasi sampel untuk menunjukkan konfigurasi port manajemen, buat launchSettings.json file di Properties folder.

File berikut Properties/launchSettings.json dalam aplikasi sampel tidak disertakan dalam file proyek aplikasi sampel dan harus dibuat secara manual:

{
  "profiles": {
    "SampleApp": {
      "commandName": "Project",
      "commandLineArgs": "",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "ASPNETCORE_URLS": "http://localhost:5000/;http://localhost:5001/",
        "ASPNETCORE_MANAGEMENTPORT": "5001"
      },
      "applicationUrl": "http://localhost:5000/"
    }
  }
}

Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Startup.ConfigureServices. Buat titik akhir pemeriksaan kesehatan dengan memanggil MapHealthChecks di Startup.Configure.

Di aplikasi sampel, panggilan ke RequireHost pada titik akhir dalam Startup.Configure menentukan port manajemen dari konfigurasi:

endpoints.MapHealthChecks("/health")
    .RequireHost($"*:{Configuration["ManagementPort"]}");

Titik akhir dibuat di aplikasi sampel di Startup.Configure. Dalam contoh kode berikut:

• Pemeriksaan kesiapan menggunakan semua pemeriksaan terdaftar dengan tag 'siap'.
• Mengecualikan Predicate semua pemeriksaan dan mengembalikan 200-Ok.

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health/ready", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("ready"),
    });

    endpoints.MapHealthChecks("/health/live", new HealthCheckOptions()
    {
        Predicate = (_) => false
    });
}

return new HostBuilder()
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseKestrel()
            .ConfigureKestrel(serverOptions =>
            {
                serverOptions.ListenAnyIP(5001);
            })
            .UseStartup(startupType);
    })
    .Build();

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health").RequireHost("*:5001");
});

Untuk menjalankan skenario konfigurasi port manajemen menggunakan aplikasi sampel, jalankan perintah berikut dari folder proyek di shell perintah:

dotnet run --scenario port

Mendistribusikan pustaka pemeriksaan kesehatan

Untuk mendistribusikan pemeriksaan kesehatan sebagai pustaka:

1. Tulis pemeriksaan kesehatan yang mengimplementasikan IHealthCheck antarmuka sebagai kelas mandiri. Kelas dapat mengandalkan injeksi dependensi (DI), aktivasi jenis, dan opsi bernama untuk mengakses data konfigurasi.

   Dalam logika pemeriksaan kesehatan :CheckHealthAsync

   • data1 dan data2 digunakan dalam metode untuk menjalankan logika pemeriksaan kesehatan probe.
   • AccessViolationException ditangani.

   AccessViolationException Ketika terjadi, FailureStatus dikembalikan dengan HealthCheckResult untuk memungkinkan pengguna mengonfigurasi status kegagalan pemeriksaan kesehatan.

   using System;
   using System.Threading;
   using System.Threading.Tasks;
   using Microsoft.Extensions.Diagnostics.HealthChecks;
   
   namespace SampleApp
   {
       public class ExampleHealthCheck : IHealthCheck
       {
           private readonly string _data1;
           private readonly int? _data2;
   
           public ExampleHealthCheck(string data1, int? data2)
           {
               _data1 = data1 ?? throw new ArgumentNullException(nameof(data1));
               _data2 = data2 ?? throw new ArgumentNullException(nameof(data2));
           }
   
           public async Task<HealthCheckResult> CheckHealthAsync(
               HealthCheckContext context, CancellationToken cancellationToken)
           {
               try
               {
                   return HealthCheckResult.Healthy();
               }
               catch (AccessViolationException ex)
               {
                   return new HealthCheckResult(
                       context.Registration.FailureStatus,
                       description: "An access violation occurred during the check.",
                       exception: ex,
                       data: null);
               }
           }
       }
   }
   

2. Tulis metode ekstensi dengan parameter yang dipanggil aplikasi yang mengonsumsi dalam metodenya Startup.Configure . Dalam contoh berikut, asumsikan tanda tangan metode pemeriksaan kesehatan berikut:

   ExampleHealthCheck(string, string, int )
   

   Tanda tangan sebelumnya menunjukkan bahwa ExampleHealthCheck memerlukan data tambahan untuk memproses logika pemeriksaan kesehatan. Data diberikan kepada delegasi yang digunakan untuk membuat instans pemeriksaan kesehatan saat pemeriksaan kesehatan terdaftar dengan metode ekstensi. Dalam contoh berikut, pemanggil menentukan opsional:

   • nama pemeriksaan kesehatan (name). Jika null, example_health_check digunakan.
   • titik data string untuk pemeriksaan kesehatan (data1).
   • titik data bilangan bulat untuk pemeriksaan kesehatan (data2). Jika null, 1 digunakan.
   • status kegagalan (HealthStatus). Default adalah null. Jika null, HealthStatus.Unhealthy dilaporkan untuk status kegagalan.
   • tag (IEnumerable<string>).

   using System.Collections.Generic;
   using Microsoft.Extensions.Diagnostics.HealthChecks;
   
   public static class ExampleHealthCheckBuilderExtensions
   {
       const string DefaultName = "example_health_check";
   
       public static IHealthChecksBuilder AddExampleHealthCheck(
           this IHealthChecksBuilder builder,
           string name = default,
           string data1,
           int data2 = 1,
           HealthStatus? failureStatus = default,
           IEnumerable<string> tags = default)
       {
           return builder.Add(new HealthCheckRegistration(
               name ?? DefaultName,
               sp => new ExampleHealthCheck(data1, data2),
               failureStatus,
               tags));
       }
   }
   

Penerbit Pemeriksaan Kesehatan

IHealthCheckPublisher Ketika ditambahkan ke kontainer layanan, sistem pemeriksaan kesehatan secara berkala menjalankan pemeriksaan dan panggilan PublishAsync kesehatan Anda dengan hasilnya. Ini berguna dalam skenario sistem pemantauan kesehatan berbasis dorong yang mengharapkan setiap proses memanggil sistem pemantauan secara berkala untuk menentukan kesehatan.

Antarmuka IHealthCheckPublisher memiliki satu metode:

Task PublishAsync(HealthReport report, CancellationToken cancellationToken);

HealthCheckPublisherOptions memungkinkan Anda mengatur:

• Delay: Penundaan awal diterapkan setelah aplikasi dimulai sebelum menjalankan IHealthCheckPublisher instans. Penundaan diterapkan sekali saat startup dan tidak berlaku untuk perulangan berikutnya. Nilai defaultnya adalah lima detik.
• Period: Periode IHealthCheckPublisher eksekusi. Nilai {i>default
• Predicate: Jika Predicate ( null default), layanan penerbit pemeriksaan kesehatan menjalankan semua pemeriksaan kesehatan terdaftar. Untuk menjalankan subset pemeriksaan kesehatan, berikan fungsi yang memfilter serangkaian pemeriksaan. Predikat dievaluasi setiap periode.
• Timeout: Batas waktu untuk menjalankan pemeriksaan kesehatan untuk semua IHealthCheckPublisher instans. Gunakan InfiniteTimeSpan untuk mengeksekusi tanpa batas waktu. Nilai {i>default

Dalam aplikasi sampel, ReadinessPublisher adalah IHealthCheckPublisher implementasi. Status pemeriksaan kesehatan dicatat untuk setiap pemeriksaan pada tingkat log:

• Informasi (LogInformation) jika status pemeriksaan kesehatan adalah Healthy.
• Kesalahan (LogError) jika statusnya adalah Degraded atau Unhealthy.

public class ReadinessPublisher : IHealthCheckPublisher
{
    private readonly ILogger _logger;

    public ReadinessPublisher(ILogger<ReadinessPublisher> logger)
    {
        _logger = logger;
    }

    // The following example is for demonstration purposes only. Health Checks
    // Middleware already logs health checks results. A real-world readiness
    // check in a production app might perform a set of more expensive or
    // time-consuming checks to determine if other resources are responding
    // properly.
    public Task PublishAsync(HealthReport report,
        CancellationToken cancellationToken)
    {
        if (report.Status == HealthStatus.Healthy)
        {
            _logger.LogInformation("{Timestamp} Readiness Probe Status: {Result}",
                DateTime.UtcNow, report.Status);
        }
        else
        {
            _logger.LogError("{Timestamp} Readiness Probe Status: {Result}",
                DateTime.UtcNow, report.Status);
        }

        cancellationToken.ThrowIfCancellationRequested();

        return Task.CompletedTask;
    }
}

Dalam contoh aplikasi LivenessProbeStartup sampel, StartupHostedService pemeriksaan kesiapan memiliki penundaan startup dua detik dan menjalankan pemeriksaan setiap 30 detik. Untuk mengaktifkan IHealthCheckPublisher implementasi, sampel mendaftar ReadinessPublisher sebagai layanan singleton dalam kontainer injeksi dependensi (DI):

services.AddHostedService<StartupHostedService>();
services.AddSingleton<StartupHostedServiceHealthCheck>();

services.AddHealthChecks()
    .AddCheck<StartupHostedServiceHealthCheck>(
        "hosted_service_startup",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "ready" });

services.Configure<HealthCheckPublisherOptions>(options =>
{
    options.Delay = TimeSpan.FromSeconds(2);
    options.Predicate = (check) => check.Tags.Contains("ready");
});

services.AddSingleton<IHealthCheckPublisher, ReadinessPublisher>();

Membatasi pemeriksaan kesehatan dengan MapWhen

Gunakan MapWhen untuk mencabangkan alur permintaan untuk titik akhir pemeriksaan kesehatan secara kondisional.

Dalam contoh berikut, MapWhen mencabangkan alur permintaan untuk mengaktifkan Middleware Pemeriksaan Kesehatan jika permintaan GET diterima untuk api/HealthCheck titik akhir:

app.MapWhen(
    context => context.Request.Method == HttpMethod.Get.Method && 
        context.Request.Path.StartsWith("/api/HealthCheck"),
    builder => builder.UseHealthChecks());

app.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
});

Untuk informasi lebih lanjut, lihat Middleware ASP.NET Core.

ASP.NET Core menawarkan Middleware pemeriksaan kesehatan dan pustaka untuk melaporkan kesehatan komponen infrastruktur aplikasi.

Pemeriksaan kesehatan diekspos oleh aplikasi sebagai titik akhir HTTP. Titik akhir pemeriksaan kesehatan dapat dikonfigurasi untuk berbagai skenario pemantauan real-time:

• Pemeriksaan kesehatan dapat digunakan oleh orkestrator kontainer dan load balancer untuk memeriksa status aplikasi. Misalnya, orkestrator kontainer dapat merespons pemeriksaan kesehatan yang gagal dengan menghentikan penyebaran bergulir atau memulai ulang kontainer. Load balancer mungkin bereaksi terhadap aplikasi yang tidak sehat dengan merutekan lalu lintas dari instans yang gagal ke instans yang sehat.
• Penggunaan memori, disk, dan sumber daya server fisik lainnya dapat dipantau untuk status sehat.
• Pemeriksaan kesehatan dapat menguji dependensi aplikasi, seperti database dan titik akhir layanan eksternal, untuk mengonfirmasi ketersediaan dan fungsi normal.

Pemeriksaan kesehatan biasanya digunakan dengan layanan pemantauan eksternal atau orkestrator kontainer untuk memeriksa status aplikasi. Sebelum menambahkan pemeriksaan kesehatan ke aplikasi, putuskan sistem pemantauan mana yang akan digunakan. Sistem pemantauan menentukan jenis pemeriksaan kesehatan apa yang akan dibuat dan cara mengonfigurasi titik akhirnya.

Pemeriksaan kesehatan dasar

Untuk banyak aplikasi, konfigurasi pemeriksaan kesehatan dasar yang melaporkan ketersediaan aplikasi untuk memproses permintaan (liveness) cukup untuk menemukan status aplikasi.

Konfigurasi dasar mendaftarkan layanan pemeriksaan kesehatan dan memanggil Middleware Pemeriksaan Kesehatan untuk merespons di titik akhir URL dengan respons kesehatan. Secara default, tidak ada pemeriksaan kesehatan tertentu yang terdaftar untuk menguji dependensi atau subsistem tertentu. Aplikasi ini dianggap sehat jika dapat merespons di URL titik akhir kesehatan. Penulis respons default menulis HealthStatus sebagai respons teks biasa terhadap klien. adalah HealthStatus HealthStatus.Healthy, HealthStatus.Degraded, atau HealthStatus.Unhealthy.

Daftarkan layanan pemeriksaan kesehatan dengan AddHealthChecks di Program.cs. Buat titik akhir pemeriksaan kesehatan dengan memanggil MapHealthChecks.

Contoh berikut membuat titik akhir pemeriksaan kesehatan di /healthz:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks();

var app = builder.Build();

app.MapHealthChecks("/healthz");

app.Run();

Buruh kapal HEALTHCHECK

Docker menawarkan arahan bawaan HEALTHCHECK yang dapat digunakan untuk memeriksa status aplikasi yang menggunakan konfigurasi pemeriksaan kesehatan dasar:

HEALTHCHECK CMD curl --fail http://localhost:5000/healthz || exit

Contoh sebelumnya menggunakan curl untuk membuat permintaan HTTP ke titik akhir pemeriksaan kesehatan di /healthz. curl tidak disertakan dalam gambar kontainer Linux .NET, tetapi dapat ditambahkan dengan menginstal paket yang diperlukan di Dockerfile. Kontainer yang menggunakan gambar berdasarkan Alpine Linux dapat menggunakan yang disertakan wget sebagai pengganti curl.

Membuat pemeriksaan kesehatan

Pemeriksaan kesehatan dibuat dengan menerapkan IHealthCheck antarmuka. Metode CheckHealthAsync mengembalikan HealthCheckResult yang menunjukkan kesehatan sebagai Healthy, , Degradedatau Unhealthy. Hasilnya ditulis sebagai respons teks biasa dengan kode status yang dapat dikonfigurasi. Konfigurasi dijelaskan di bagian Opsi pemeriksaan kesehatan. HealthCheckResult juga dapat mengembalikan pasangan kunci-nilai opsional.

Contoh berikut menunjukkan tata letak pemeriksaan kesehatan:

public class SampleHealthCheck : IHealthCheck
{
    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        var isHealthy = true;

        // ...

        if (isHealthy)
        {
            return Task.FromResult(
                HealthCheckResult.Healthy("A healthy result."));
        }

        return Task.FromResult(
            new HealthCheckResult(
                context.Registration.FailureStatus, "An unhealthy result."));
    }
}

Logika pemeriksaan kesehatan ditempatkan dalam CheckHealthAsync metode . Contoh sebelumnya menetapkan variabel dummy, , isHealthyke true. Jika nilai isHealthy diatur ke false, HealthCheckRegistration.FailureStatus status dikembalikan.

Jika CheckHealthAsync melempar pengecualian selama pemeriksaan, yang baru HealthReportEntry dikembalikan dengan HealthReportEntry.Status diatur ke FailureStatus. Status ini ditentukan oleh AddCheck (lihat bagian Daftarkan layanan pemeriksaan kesehatan) dan menyertakan pengecualian dalam yang menyebabkan kegagalan pemeriksaan. Description diatur ke pesan pengecualian.

Mendaftarkan layanan pemeriksaan kesehatan

Untuk mendaftarkan layanan pemeriksaan kesehatan, hubungi AddCheck di Program.cs:

builder.Services.AddHealthChecks()
    .AddCheck<SampleHealthCheck>("Sample");

Kelebihan AddCheck beban yang ditunjukkan dalam contoh berikut menetapkan status kegagalan (HealthStatus) untuk melaporkan saat pemeriksaan kesehatan melaporkan kegagalan. Jika status kegagalan diatur ke null (default), HealthStatus.Unhealthy dilaporkan. Kelebihan beban ini adalah skenario yang berguna untuk penulis pustaka, di mana status kegagalan yang ditunjukkan oleh pustaka diberlakukan oleh aplikasi ketika kegagalan pemeriksaan kesehatan terjadi jika implementasi pemeriksaan kesehatan mematuhi pengaturan.

Tag dapat digunakan untuk memfilter pemeriksaan kesehatan. Tag dijelaskan di bagian Filter pemeriksaan kesehatan.

builder.Services.AddHealthChecks()
    .AddCheck<SampleHealthCheck>(
        "Sample",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "sample" });

AddCheck juga dapat menjalankan fungsi lambda. Dalam contoh berikut, pemeriksaan kesehatan selalu mengembalikan hasil yang sehat:

builder.Services.AddHealthChecks()
    .AddCheck("Sample", () => HealthCheckResult.Healthy("A healthy result."));

Panggil AddTypeActivatedCheck untuk meneruskan argumen ke implementasi pemeriksaan kesehatan. Dalam contoh berikut, pemeriksaan kesehatan yang diaktifkan jenis menerima bilangan bulat dan string dalam konstruktornya:

public class SampleHealthCheckWithArgs : IHealthCheck
{
    private readonly int _arg1;
    private readonly string _arg2;

    public SampleHealthCheckWithArgs(int arg1, string arg2)
        => (_arg1, _arg2) = (arg1, arg2);

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        // ...

        return Task.FromResult(HealthCheckResult.Healthy("A healthy result."));
    }
}

Untuk mendaftarkan pemeriksaan kesehatan sebelumnya, panggil AddTypeActivatedCheck dengan bilangan bulat dan string yang diteruskan sebagai argumen:

builder.Services.AddHealthChecks()
    .AddTypeActivatedCheck<SampleHealthCheckWithArgs>(
        "Sample",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "sample" },
        args: new object[] { 1, "Arg" });

Gunakan Perutean Pemeriksaan Kesehatan

Di Program.cs, panggil MapHealthChecks pembangun titik akhir dengan URL titik akhir atau jalur relatif:

app.MapHealthChecks("/healthz");

Memerlukan host

Panggil RequireHost untuk menentukan satu atau beberapa host yang diizinkan untuk titik akhir pemeriksaan kesehatan. Host harus Unicode daripada punycode dan dapat mencakup port. Jika koleksi tidak disediakan, host apa pun akan diterima:

app.MapHealthChecks("/healthz")
    .RequireHost("www.contoso.com:5001");

Untuk membatasi titik akhir pemeriksaan kesehatan untuk merespons hanya pada port tertentu, tentukan port dalam panggilan ke RequireHost. Pendekatan ini biasanya digunakan dalam lingkungan kontainer untuk mengekspos port untuk layanan pemantauan:

app.MapHealthChecks("/healthz")
    .RequireHost("*:5001");

Untuk mencegah klien yang tidak sah melakukan spoofing port, panggil RequireAuthorization:

app.MapHealthChecks("/healthz")
    .RequireHost("*:5001")
    .RequireAuthorization();

Untuk informasi selengkapnya, lihat Pencocokan host dalam rute dengan RequireHost.

Memerlukan otorisasi

Panggil RequireAuthorization untuk menjalankan Middleware Otorisasi pada titik akhir permintaan pemeriksaan kesehatan. Kelebihan RequireAuthorization beban menerima satu atau beberapa kebijakan otorisasi. Jika kebijakan tidak disediakan, kebijakan otorisasi default akan digunakan:

app.MapHealthChecks("/healthz")
    .RequireAuthorization();

Mengaktifkan Permintaan Lintas Asal (CORS)

Meskipun menjalankan pemeriksaan kesehatan secara manual dari browser bukanlah skenario umum, CORS Middleware dapat diaktifkan dengan memanggil RequireCors titik akhir pemeriksaan kesehatan. Kelebihan RequireCors beban menerima delegasi pembuat kebijakan CORS (CorsPolicyBuilder) atau nama kebijakan. Untuk informasi selengkapnya, lihat Mengaktifkan Permintaan Lintas Asal (CORS) di ASP.NET Core.

Opsi pemeriksaan kesehatan

HealthCheckOptions memberikan kesempatan untuk menyesuaikan perilaku pemeriksaan kesehatan:

• Memfilter pemeriksaan kesehatan
• Mengkustomisasi kode status HTTP
• Menyembunyikan header cache
• Sesuaikan output

Memfilter pemeriksaan kesehatan

Secara default, Middleware Pemeriksaan Kesehatan menjalankan semua pemeriksaan kesehatan terdaftar. Untuk menjalankan subset pemeriksaan kesehatan, berikan fungsi yang mengembalikan boolean ke Predicate opsi .

Contoh berikut memfilter pemeriksaan kesehatan sehingga hanya yang ditandai dengan sample eksekusi:

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    Predicate = healthCheck => healthCheck.Tags.Contains("sample")
});

Mengkustomisasi kode status HTTP

Gunakan ResultStatusCodes untuk menyesuaikan pemetaan status kesehatan ke kode status HTTP. Tugas berikut StatusCodes adalah nilai default yang digunakan oleh middleware. Ubah nilai kode status untuk memenuhi kebutuhan Anda:

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

Menyembunyikan header cache

AllowCachingResponses mengontrol apakah Middleware Pemeriksaan Kesehatan menambahkan header HTTP ke respons pemeriksaan untuk mencegah penembolokan respons. Jika nilainya ( false default), middleware mengatur atau mengambil Cache-Controlalih header , , Expiresdan Pragma untuk mencegah penembolokan respons. Jika nilainya adalah true, middleware tidak mengubah header cache respons:

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    AllowCachingResponses = true
});

Sesuaikan output

Untuk menyesuaikan output laporan pemeriksaan kesehatan, atur HealthCheckOptions.ResponseWriter properti ke delegasi yang menulis respons:

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    ResponseWriter = WriteResponse
});

Delegasi default menulis respons teks biasa minimal dengan nilai HealthReport.Statusstring . Delegasi kustom berikut menghasilkan respons JSON kustom menggunakan System.Text.Json:

private static Task WriteResponse(HttpContext context, HealthReport healthReport)
{
    context.Response.ContentType = "application/json; charset=utf-8";

    var options = new JsonWriterOptions { Indented = true };

    using var memoryStream = new MemoryStream();
    using (var jsonWriter = new Utf8JsonWriter(memoryStream, options))
    {
        jsonWriter.WriteStartObject();
        jsonWriter.WriteString("status", healthReport.Status.ToString());
        jsonWriter.WriteStartObject("results");

        foreach (var healthReportEntry in healthReport.Entries)
        {
            jsonWriter.WriteStartObject(healthReportEntry.Key);
            jsonWriter.WriteString("status",
                healthReportEntry.Value.Status.ToString());
            jsonWriter.WriteString("description",
                healthReportEntry.Value.Description);
            jsonWriter.WriteStartObject("data");

            foreach (var item in healthReportEntry.Value.Data)
            {
                jsonWriter.WritePropertyName(item.Key);

                JsonSerializer.Serialize(jsonWriter, item.Value,
                    item.Value?.GetType() ?? typeof(object));
            }

            jsonWriter.WriteEndObject();
            jsonWriter.WriteEndObject();
        }

        jsonWriter.WriteEndObject();
        jsonWriter.WriteEndObject();
    }

    return context.Response.WriteAsync(
        Encoding.UTF8.GetString(memoryStream.ToArray()));
}

API pemeriksaan kesehatan tidak menyediakan dukungan bawaan untuk format pengembalian JSON yang kompleks karena formatnya khusus untuk sistem pemantauan pilihan Anda. Sesuaikan respons dalam contoh sebelumnya sesuai kebutuhan. Untuk informasi selengkapnya tentang serialisasi JSON dengan System.Text.Json, lihat Cara membuat serialisasi dan deserialisasi JSON di .NET.

Pemeriksaan database

Pemeriksaan kesehatan dapat menentukan kueri database untuk dijalankan sebagai pengujian boolean untuk menunjukkan apakah database merespons secara normal.

AspNetCore.Diagnostics.HealthChecks, pustaka pemeriksaan kesehatan untuk aplikasi ASP.NET Core, menyertakan pemeriksaan kesehatan yang berjalan terhadap database SQL Server. AspNetCore.Diagnostics.HealthChecksSELECT 1 menjalankan kueri terhadap database untuk mengonfirmasi koneksi ke database sehat.

Untuk menggunakan pemeriksaan kesehatan SQL Server ini, sertakan referensi paket ke AspNetCore.HealthChecks.SqlServer paket NuGet. Contoh berikut mendaftarkan pemeriksaan kesehatan SQL Server:

builder.Services.AddHealthChecks()
    .AddSqlServer(
        builder.Configuration.GetConnectionString("DefaultConnection"));

Pemeriksaan Entity Framework Core DbContext

Pemeriksaan DbContext mengonfirmasi bahwa aplikasi dapat berkomunikasi dengan database yang dikonfigurasi untuk EF CoreDbContext. DbContext Pemeriksaan didukung di aplikasi yang:

• Gunakan Core Entity Framework (EF).
• Sertakan referensi paket ke Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore paket NuGet.

AddDbContextCheck mendaftarkan pemeriksaan kesehatan untuk DbContext. DbContext disediakan ke metode sebagai TContext. Kelebihan beban tersedia untuk mengonfigurasi status kegagalan, tag, dan kueri pengujian kustom.

Secara default:

• Metode DbContextHealthCheck panggilanEF CoreCanConnectAsync. Anda dapat menyesuaikan operasi apa yang dijalankan saat memeriksa kesehatan menggunakan AddDbContextCheck kelebihan beban metode.
• Nama pemeriksaan kesehatan adalah nama jenisnya TContext .

Contoh berikut mendaftarkan DbContext dan terkait DbContextHealthCheck:

builder.Services.AddDbContext<SampleDbContext>(options =>
    options.UseSqlServer(
        builder.Configuration.GetConnectionString("DefaultConnection")));

builder.Services.AddHealthChecks()
    .AddDbContextCheck<SampleDbContext>();

Pemeriksaan kesiapan dan keaktifan terpisah

Dalam beberapa skenario hosting, sepasang pemeriksaan kesehatan digunakan untuk membedakan dua status aplikasi:

• Kesiapan menunjukkan apakah aplikasi berjalan normal tetapi belum siap untuk menerima permintaan.
• Liveness menunjukkan apakah aplikasi mengalami crash dan harus dimulai ulang.

Pertimbangkan contoh berikut: Aplikasi harus mengunduh file konfigurasi besar sebelum siap memproses permintaan. Kami tidak ingin aplikasi dimulai ulang jika unduhan awal gagal karena aplikasi dapat mencoba lagi mengunduh file beberapa kali. Kami menggunakan pemeriksaan keaktifan untuk menggambarkan keaktifan proses, tidak ada pemeriksaan lain yang dijalankan. Kami juga ingin mencegah permintaan dikirim ke aplikasi sebelum pengunduhan file konfigurasi berhasil. Kami menggunakan pemeriksaan kesiapan untuk menunjukkan status "belum siap" sampai unduhan berhasil dan aplikasi siap menerima permintaan.

Tugas latar belakang berikut mensimulasikan proses startup yang memakan waktu sekitar 15 detik. Setelah selesai, tugas mengatur StartupHealthCheck.StartupCompleted properti ke true:

public class StartupBackgroundService : BackgroundService
{
    private readonly StartupHealthCheck _healthCheck;

    public StartupBackgroundService(StartupHealthCheck healthCheck)
        => _healthCheck = healthCheck;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // Simulate the effect of a long-running task.
        await Task.Delay(TimeSpan.FromSeconds(15), stoppingToken);

        _healthCheck.StartupCompleted = true;
    }
}

Laporan StartupHealthCheck penyelesaian tugas startup yang berjalan lama dan mengekspos StartupCompleted properti yang diatur oleh layanan latar belakang:

public class StartupHealthCheck : IHealthCheck
{
    private volatile bool _isReady;

    public bool StartupCompleted
    {
        get => _isReady;
        set => _isReady = value;
    }

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        if (StartupCompleted)
        {
            return Task.FromResult(HealthCheckResult.Healthy("The startup task has completed."));
        }

        return Task.FromResult(HealthCheckResult.Unhealthy("That startup task is still running."));
    }
}

Pemeriksaan kesehatan didaftarkan AddCheck bersama dengan layanan yang dihosting Program.cs . Karena layanan yang dihosting harus mengatur properti pada pemeriksaan kesehatan, pemeriksaan kesehatan juga terdaftar dalam kontainer layanan sebagai singleton:

builder.Services.AddHostedService<StartupBackgroundService>();
builder.Services.AddSingleton<StartupHealthCheck>();

builder.Services.AddHealthChecks()
    .AddCheck<StartupHealthCheck>(
        "Startup",
        tags: new[] { "ready" });

Untuk membuat dua titik akhir pemeriksaan kesehatan yang berbeda, panggil MapHealthChecks dua kali:

app.MapHealthChecks("/healthz/ready", new HealthCheckOptions
{
    Predicate = healthCheck => healthCheck.Tags.Contains("ready")
});

app.MapHealthChecks("/healthz/live", new HealthCheckOptions
{
    Predicate = _ => false
});

Contoh sebelumnya membuat titik akhir pemeriksaan kesehatan berikut:

• /healthz/ready untuk pemeriksaan kesiapan. Pemeriksaan kesiapan memfilter pemeriksaan kesehatan ke yang ditandai dengan ready.
• /healthz/live untuk pemeriksaan keaktivaan. Pemeriksaan keakuratan memfilter semua pemeriksaan kesehatan dengan kembali false ke HealthCheckOptions.Predicate delegasi. Untuk informasi selengkapnya tentang pemfilteran pemeriksaan kesehatan, lihat Memfilter pemeriksaan kesehatan di artikel ini.

Sebelum tugas startup selesai, /healthz/ready titik akhir melaporkan Unhealthy status. Setelah tugas startup selesai, titik akhir ini melaporkan Healthy status. Titik /healthz/live akhir mengecualikan semua pemeriksaan dan melaporkan Healthy status untuk semua panggilan.

Contoh Kubernetes

Menggunakan pemeriksaan kesiapan dan keaktifan terpisah berguna di lingkungan seperti Kubernetes. Di Kubernetes, aplikasi mungkin diperlukan untuk menjalankan pekerjaan startup yang memakan waktu sebelum menerima permintaan, seperti pengujian ketersediaan database yang mendasarinya. Menggunakan pemeriksaan terpisah memungkinkan orkestrator untuk membedakan apakah aplikasi berfungsi tetapi belum siap atau jika aplikasi gagal dimulai. Untuk informasi selengkapnya tentang pemeriksaan kesiapan dan keaktifan di Kubernetes, lihat Mengonfigurasi Pemeriksaan Keaktifan dan Kesiapan dalam dokumentasi Kubernetes.

Contoh berikut menunjukkan konfigurasi pemeriksaan kesiapan Kube:

spec:
  template:
  spec:
    readinessProbe:
      # an http probe
      httpGet:
        path: /healthz/ready
        port: 80
      # length of time to wait for a pod to initialize
      # after pod startup, before applying health checking
      initialDelaySeconds: 30
      timeoutSeconds: 1
    ports:
      - containerPort: 80

Mendistribusikan pustaka pemeriksaan kesehatan

Untuk mendistribusikan pemeriksaan kesehatan sebagai pustaka:

1. Tulis pemeriksaan kesehatan yang mengimplementasikan IHealthCheck antarmuka sebagai kelas mandiri. Kelas dapat mengandalkan injeksi dependensi (DI), aktivasi jenis, dan opsi bernama untuk mengakses data konfigurasi.

2. Tulis metode ekstensi dengan parameter yang dipanggil aplikasi yang mengonsumsi dalam metodenya Program.cs . Pertimbangkan contoh pemeriksaan kesehatan berikut, yang menerima arg1 dan arg2 sebagai parameter konstruktor:

   public SampleHealthCheckWithArgs(int arg1, string arg2)
       => (_arg1, _arg2) = (arg1, arg2);
   

   Tanda tangan sebelumnya menunjukkan bahwa pemeriksaan kesehatan memerlukan data kustom untuk memproses logika pemeriksaan kesehatan. Data diberikan kepada delegasi yang digunakan untuk membuat instans pemeriksaan kesehatan saat pemeriksaan kesehatan terdaftar dengan metode ekstensi. Dalam contoh berikut, pemanggil menentukan:

   • arg1: Titik data bilangan bulat untuk pemeriksaan kesehatan.
   • arg2: Argumen string untuk pemeriksaan kesehatan.
   • name: Nama pemeriksaan kesehatan opsional. Jika null, nilai default digunakan.
   • failureStatus: Opsional HealthStatus, yang dilaporkan untuk status kegagalan. Jika null, HealthStatus.Unhealthy digunakan.
   • tags: Kumpulan tag opsional IEnumerable<string> .

   public static class SampleHealthCheckBuilderExtensions
   {
       private const string DefaultName = "Sample";
   
       public static IHealthChecksBuilder AddSampleHealthCheck(
           this IHealthChecksBuilder healthChecksBuilder,
           int arg1,
           string arg2,
           string? name = null,
           HealthStatus? failureStatus = null,
           IEnumerable<string>? tags = default)
       {
           return healthChecksBuilder.Add(
               new HealthCheckRegistration(
                   name ?? DefaultName,
                   _ => new SampleHealthCheckWithArgs(arg1, arg2),
                   failureStatus,
                   tags));
       }
   }
   

Penerbit Pemeriksaan Kesehatan

IHealthCheckPublisher Ketika ditambahkan ke kontainer layanan, sistem pemeriksaan kesehatan secara berkala menjalankan pemeriksaan dan panggilan PublishAsync kesehatan Anda dengan hasilnya. Proses ini berguna dalam skenario sistem pemantauan kesehatan berbasis dorong yang mengharapkan setiap proses memanggil sistem pemantauan secara berkala untuk menentukan kesehatan.

HealthCheckPublisherOptions memungkinkan Anda untuk mengatur:

• Delay: Penundaan awal diterapkan setelah aplikasi dimulai sebelum menjalankan IHealthCheckPublisher instans. Penundaan diterapkan sekali saat startup dan tidak berlaku untuk perulangan nanti. Nilai defaultnya adalah lima detik.
• Period: Periode IHealthCheckPublisher eksekusi. Nilai {i>default
• Predicate: Jika Predicate ( null default), layanan penerbit pemeriksaan kesehatan menjalankan semua pemeriksaan kesehatan terdaftar. Untuk menjalankan subset pemeriksaan kesehatan, berikan fungsi yang memfilter serangkaian pemeriksaan. Predikat dievaluasi setiap periode.
• Timeout: Batas waktu untuk menjalankan pemeriksaan kesehatan untuk semua IHealthCheckPublisher instans. Gunakan InfiniteTimeSpan untuk mengeksekusi tanpa batas waktu. Nilai {i>default

Contoh berikut menunjukkan tata letak penerbit kesehatan:

public class SampleHealthCheckPublisher : IHealthCheckPublisher
{
    public Task PublishAsync(HealthReport report, CancellationToken cancellationToken)
    {
        if (report.Status == HealthStatus.Healthy)
        {
            // ...
        }
        else
        {
            // ...
        }

        return Task.CompletedTask;
    }
}

Kelas HealthCheckPublisherOptions menyediakan properti untuk mengonfigurasi perilaku penerbit pemeriksaan kesehatan.

Contoh berikut mendaftarkan penerbit pemeriksaan kesehatan sebagai singleton dan mengonfigurasi HealthCheckPublisherOptions:

builder.Services.Configure<HealthCheckPublisherOptions>(options =>
{
    options.Delay = TimeSpan.FromSeconds(2);
    options.Predicate = healthCheck => healthCheck.Tags.Contains("sample");
});

builder.Services.AddSingleton<IHealthCheckPublisher, SampleHealthCheckPublisher>();

Injeksi Dependensi dan Pemeriksaan Kesehatan

Dimungkinkan untuk menggunakan injeksi dependensi untuk menggunakan instans tertentu Type di dalam kelas Pemeriksaan Kesehatan. Injeksi dependensi dapat berguna untuk menyuntikkan opsi atau konfigurasi global ke Pemeriksaan Kesehatan. Menggunakan injeksi dependensi bukanlah skenario umum untuk mengonfigurasi Pemeriksaan Kesehatan. Biasanya, setiap Pemeriksaan Kesehatan cukup spesifik untuk pengujian aktual dan dikonfigurasi menggunakan IHealthChecksBuilder metode ekstensi.

Contoh berikut menunjukkan sampel Pemeriksaan Kesehatan yang mengambil objek konfigurasi melalui injeksi dependensi:

public class SampleHealthCheckWithDI : IHealthCheck
{
    private readonly SampleHealthCheckWithDiConfig _config;

    public SampleHealthCheckWithDI(SampleHealthCheckWithDiConfig config)
        => _config = config;

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        var isHealthy = true;

        // use _config ...

        if (isHealthy)
        {
            return Task.FromResult(
                HealthCheckResult.Healthy("A healthy result."));
        }

        return Task.FromResult(
            new HealthCheckResult(
                context.Registration.FailureStatus, "An unhealthy result."));
    }
}

SampleHealthCheckWithDiConfig Pemeriksaan kesehatan dan perlu ditambahkan ke kontainer layanan :

builder.Services.AddSingleton<SampleHealthCheckWithDiConfig>(new SampleHealthCheckWithDiConfig
{
    BaseUriToCheck = new Uri("https://sample.contoso.com/api/")
});
builder.Services.AddHealthChecks()
    .AddCheck<SampleHealthCheckWithDI>(
        "With Dependency Injection",
        tags: new[] { "inject" });

UseHealthChecks vs. MapHealthChecks

Ada dua cara untuk membuat pemeriksaan kesehatan dapat diakses oleh penelepon:

• UseHealthChecks mendaftarkan middleware untuk menangani permintaan pemeriksaan kesehatan di alur middleware.
• MapHealthChecks mendaftarkan titik akhir pemeriksaan kesehatan. Titik akhir dicocokkan dan dijalankan bersama dengan titik akhir lain di aplikasi.

Keuntungan menggunakan MapHealthChecks lebih UseHealthChecks dari adalah kemampuan untuk menggunakan middleware sadar titik akhir, seperti otorisasi, dan untuk memiliki kontrol terperinci yang lebih besar atas kebijakan pencocokan. Keuntungan utama menggunakan UseHealthChecks over MapHealthChecks adalah mengontrol persis di mana pemeriksaan kesehatan berjalan di alur middleware.

UseHealthChecks:

• Mengakhiri alur saat permintaan cocok dengan titik akhir pemeriksaan kesehatan. Sirkuit pendek sering diinginkan karena menghindari pekerjaan yang tidak perlu, seperti pengelogan dan middleware lainnya.
• Terutama digunakan untuk mengonfigurasi middleware pemeriksaan kesehatan dalam alur.
• Dapat mencocokkan jalur apa pun pada port dengan null atau kosong PathString. Memungkinkan melakukan pemeriksaan kesehatan pada permintaan apa pun yang dibuat ke port yang ditentukan.
• Kode sumber

MapHealthChecks Memungkinkan:

• Memetakan rute atau titik akhir tertentu untuk pemeriksaan kesehatan.
• Kustomisasi URL atau jalur tempat titik akhir pemeriksaan kesehatan dapat diakses.
• Memetakan beberapa titik akhir pemeriksaan kesehatan dengan rute atau konfigurasi yang berbeda. Dukungan beberapa titik akhir:
  • Mengaktifkan titik akhir terpisah untuk berbagai jenis pemeriksaan kesehatan atau komponen.
  • Digunakan untuk membedakan antara berbagai aspek kesehatan aplikasi atau menerapkan konfigurasi tertentu ke subset pemeriksaan kesehatan.
• Kode sumber

Sumber Daya Tambahan:

• Melihat atau mengunduh kode sampel (cara mengunduh)