Pemeriksaan kesehatan di ASP.NET Core

Oleh Glenn Condron dan Juergen Gutsch

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 HealthStatusHealthStatus.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();

Docker 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");

Peringatan

API yang bergantung pada header Host, seperti HttpRequest.Host dan RequireHost, tunduk pada potensi spoofing oleh klien.

Untuk mencegah spoofing host dan port, gunakan salah satu pendekatan berikut:

• Gunakan HttpContext.Connection (ConnectionInfo.LocalPort) tempat port diperiksa.
• Menggunakan pemfilteran Host.

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 mengeluarkan respons ON kustom JSmenggunakan 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 ON yang kompleks JSkarena formatnya khusus untuk sistem pemantauan pilihan Anda. Sesuaikan respons dalam contoh sebelumnya sesuai kebutuhan. Untuk informasi selengkapnya tentang JSserialisasi ON 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.

Peringatan

Saat memeriksa koneksi database dengan kueri, pilih kueri yang kembali dengan cepat. Pendekatan kueri menjalankan risiko kelebihan beban database dan menurunkan performanya. Dalam kebanyakan kasus, menjalankan kueri pengujian tidak diperlukan. Hanya membuat koneksi yang berhasil ke database sudah cukup. Jika Anda merasa perlu menjalankan kueri, pilih kueri SELECT sederhana, seperti SELECT 1.

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);

Catatan

AspNetCore.Diagnostics.HealthChecks tidak dipertahankan atau didukung oleh Microsoft.

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 satu per satu. 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)

Catatan

Artikel ini sebagian dibuat dengan bantuan kecerdasan buatan. Sebelum menerbitkan, penulis akan meninjau dan merevisi konten jika diperlukan. Lihat Prinsip kami dalam menggunakan konten yang dihasilkan AI di Microsoft Learn.