Umbraco Health Check

Related Foundation Skills

• Context API: When accessing application state

  • Reference skill: umbraco-context-api

• Controllers: When creating API endpoints for checks

  • Reference skill: umbraco-controllers

Workflow

1. Fetch docs - Use WebFetch on the URLs above
2. Ask questions - What should be checked? What actions to provide?
3. Generate files - Create manifest + context based on latest docs
4. Explain - Show what was created and how to test

Minimal Examples

Manifest (manifests.ts)

import type { ManifestHealthCheck } from '@umbraco-cms/backoffice/health-check';

export const manifests: Array<ManifestHealthCheck> = [
  {
    type: 'healthCheck',
    alias: 'My.HealthCheck.Custom',
    name: 'Custom Health Check',
    api: () => import('./my-health-check.context.js'),
    meta: {
      label: 'Custom Check',
    },
  },
];

Context Implementation (my-health-check.context.ts)

import { UmbHealthCheckContext } from '@umbraco-cms/backoffice/health-check';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
import type { HealthCheckResultResponseModel } from '@umbraco-cms/backoffice/external/backend-api';

export class MyHealthCheckContext extends UmbHealthCheckContext {
  constructor(host: UmbControllerHost) {
    super(host);
  }

  override async check(): Promise<HealthCheckResultResponseModel> {
    // Perform your health check logic
    const isHealthy = await this.#performCheck();

    return {
      message: isHealthy ? 'All systems operational' : 'Issue detected',
      resultType: isHealthy ? 'Success' : 'Warning',
      actions: isHealthy ? [] : [
        {
          alias: 'fix-issue',
          name: 'Fix Issue',
          description: 'Attempt to automatically fix this issue',
        },
      ],
    };
  }

  async #performCheck(): Promise<boolean> {
    // Your custom check logic here
    return true;
  }

  override async executeAction(actionAlias: string): Promise<HealthCheckResultResponseModel> {
    if (actionAlias === 'fix-issue') {
      // Execute the fix action
      return {
        message: 'Issue has been resolved',
        resultType: 'Success',
        actions: [],
      };
    }

    return {
      message: 'Unknown action',
      resultType: 'Error',
      actions: [],
    };
  }
}

export { MyHealthCheckContext as api };

Interface Reference

interface ManifestHealthCheck extends ManifestBase {
  type: 'healthCheck';
  api: ApiLoaderProperty; // Should implement UmbHealthCheckContext
  meta: MetaHealthCheck;
}

interface MetaHealthCheck {
  label: string;
}

// Result types: 'Success' | 'Warning' | 'Error' | 'Info'
interface HealthCheckResultResponseModel {
  message: string;
  resultType: string;
  actions?: Array<{
    alias: string;
    name: string;
    description?: string;
  }>;
}

Backend C# Health Check

Health checks can also be implemented as C# classes that are auto-discovered by Umbraco.

using Umbraco.Cms.Core.HealthChecks;

namespace MyPackage.HealthChecks;

[HealthCheck(
    "12345678-1234-1234-1234-123456789012",
    "My Custom Check",
    Description = "Verifies custom services are running",
    Group = "Custom")]
public class MyHealthCheck : HealthCheck
{
    public MyHealthCheck(HealthCheckContext context) : base(context) { }

    public override Task<IEnumerable<HealthCheckStatus>> GetStatus()
    {
        var isHealthy = CheckMyService();
        var status = new HealthCheckStatus(isHealthy ? "Service running" : "Service down")
        {
            ResultType = isHealthy ? StatusResultType.Success : StatusResultType.Error,
            Actions = isHealthy ? null : new List<HealthCheckAction>
            {
                new("restart", Id) { Name = "Restart Service" }
            }
        };
        return Task.FromResult<IEnumerable<HealthCheckStatus>>(new[] { status });
    }

    public override HealthCheckStatus ExecuteAction(HealthCheckAction action)
    {
        if (action.Alias == "restart")
        {
            RestartMyService();
            return new HealthCheckStatus("Restarted") { ResultType = StatusResultType.Success };
        }
        throw new InvalidOperationException("Unknown action");
    }

    private bool CheckMyService() => true;
    private void RestartMyService() { }
}

Best Practices

• Return clear, actionable messages
• Provide fix actions when possible
• Use appropriate result types (Success, Warning, Error, Info)
• Consider performance - health checks run periodically

That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.