Add-KrHealthEndpoint

SYNOPSIS

Registers the built-in aggregated health endpoint for the active Kestrun server.

SYNTAX

__AllParameterSets

Add-KrHealthEndpoint [[-Server] <KestrunHost>] [[-Pattern] <string>] [[-DefaultTags] <string[]>]
 [[-AllowAnonymous] <bool>] [[-TreatDegradedAsUnhealthy] <bool>] [[-ThrowOnDuplicate] <bool>]
 [[-RequireSchemes] <string[]>] [[-RequirePolicies] <string[]>] [[-CorsPolicy] <string>]
 [[-RateLimitPolicyName] <string>] [[-ShortCircuit] <bool>] [[-ShortCircuitStatusCode] <int>]
 [[-OpenApiSummary] <string>] [[-OpenApiDescription] <string>] [[-OpenApiOperationId] <string>]
 [[-OpenApiTags] <string[]>] [[-OpenApiGroupName] <string>] [[-MaxDegreeOfParallelism] <int>]
 [[-ProbeTimeout] <timespan>] [[-DefaultScriptLanguage] <ScriptLanguage>]
 [[-ResponseContentType] <HealthEndpointContentType>] [[-XmlRootElementName] <string>] [-Compress]
 [-PassThru] [<CommonParameters>]

ALIASES

This cmdlet has the following aliases, {{Insert list of aliases}}

DESCRIPTION

Wraps the Kestrun host health extension to add (or replace) the HTTP endpoint that aggregates all registered health probes. Most parameters are optional and override the defaults provided by the active host configuration. When no overrides are supplied the endpoint is registered at ‘/health’ and inherits the server’s existing security posture.

EXAMPLES

EXAMPLE 1

Add-KrHealthEndpoint -Pattern ‘/healthz’ -TreatDegradedAsUnhealthy $true -ProbeTimeout ‘00:00:05’ Registers a health endpoint at /healthz that fails when probes report a degraded status and enforces a 5 second probe timeout.

EXAMPLE 2

Get-KrServer | Add-KrHealthEndpoint -OpenApiTags ‘Diagnostics’,’Monitoring’ -PassThru Adds the health endpoint to the current server, customises OpenAPI metadata, and returns the server for further configuration.

PARAMETERS

-AllowAnonymous

Set to $true to permit anonymous calls or $false to require authentication. When omitted, the existing configuration is used.

Type: System.Boolean
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 3
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Compress

When set, JSON and XML output are compact (no indentation). By default output is human readable.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-CorsPolicy

Optional ASP.NET Core CORS policy name applied to the endpoint.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 8
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-DefaultScriptLanguage

Overrides the default script language used when registering script-based probes.

Type: Kestrun.Scripting.ScriptLanguage
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 19
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-DefaultTags

Optional collection of probe tags to evaluate when the incoming request does not specify an explicit tag filter.

Type: System.String[]
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 2
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-MaxDegreeOfParallelism

Limits the number of concurrent probes executed during a health request.

Type: System.Int32
DefaultValue: 0
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 17
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-OpenApiDescription

Overrides the OpenAPI description documented for the endpoint.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 13
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-OpenApiGroupName

Overrides the OpenAPI group name documented for the endpoint.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 16
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-OpenApiOperationId

Overrides the OpenAPI operation id documented for the endpoint.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 14
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-OpenApiSummary

Overrides the OpenAPI summary documented for the endpoint.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 12
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-OpenApiTags

Overrides the OpenAPI tag list documented for the endpoint.

Type: System.String[]
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 15
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-PassThru

Emits the configured server instance so the call can be chained.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Pattern

The relative URL pattern for the endpoint (for example ‘/healthz’). Must begin with ‘/’.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 1
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ProbeTimeout

Adjusts the timeout enforced for each probe during a health request.

Type: System.TimeSpan
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 18
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-RateLimitPolicyName

Optional ASP.NET Core rate limiting policy name applied to the endpoint.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 9
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-RequirePolicies

Optional list of authorization policies required to access the endpoint.

Type: System.String[]
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 7
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-RequireSchemes

Optional list of authentication schemes required to access the endpoint.

Type: System.String[]
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 6
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ResponseContentType

Controls the response payload format returned by the endpoint (Json, Yaml, Xml, or Auto for content negotiation).

Type: Kestrun.Health.HealthEndpointContentType
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 20
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Server

The Kestrun host instance to configure. If omitted, the current server context is resolved automatically.

Type: Kestrun.Hosting.KestrunHost
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 0
  IsRequired: false
  ValueFromPipeline: true
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ShortCircuit

Set to $true to short-circuit the pipeline with the health result.

Type: System.Boolean
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 10
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ShortCircuitStatusCode

Overrides the status code used when ShortCircuit is $true.

Type: System.Int32
DefaultValue: 0
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 11
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ThrowOnDuplicate

When $true, throws if another GET route already exists at the specified pattern. Otherwise the endpoint is skipped with a warning.

Type: System.Boolean
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 5
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-TreatDegradedAsUnhealthy

Set to $true to return HTTP 503 when any probe reports a degraded state. Defaults to $false.

Type: System.Boolean
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 4
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-XmlRootElementName

When emitting XML output, overrides the root element name (defaults to ‘Response’). Ignored for non-XML formats.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 21
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

Kestrun.Hosting.KestrunHost

{{ Fill in the Description }}

OUTPUTS

Kestrun.Hosting.KestrunHost

{{ Fill in the Description }}

NOTES

RELATED LINKS

{{ Fill in the related links here }}