> For the complete documentation index, see [llms.txt](https://docs.pal.aic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pal.aic.io/engineering-and-delivery/hosting-and-client-integration.md).

# Hosting and client integration

PAL.NET can be hosted directly or composed into the AIC Foundation clients in this repository.

## ASP.NET Core API and web hosts

The API host loads Foundation configuration, registers Foundation web services, and then composes the rest of the application. A typical PAL-enabled host adds:

```csharp
var builder = WebApplication.CreateBuilder(args);
builder.Configuration.ConfigureFoundationHost(args);

builder.Services.RegisterPlatformCoreServices(
    builder.Configuration,
    includeVaultServices: true,
    includeBackgroundServices: true,
    includeLogging: true);

var app = builder.Build();
app.Run();
```

`RegisterPlatformCoreServices` calls the optional PAL registration when `Palantir` exists. The web host remains responsible for authentication middleware, routing, authorization, and problem-details presentation.

## Workers and Azure Functions

Use the core runtime registration in a worker or function composition root. Create a scope per invocation and pass the invocation cancellation token to all PAL calls. Do not keep a streamed result beyond the invocation scope.

## Messaging broker

The broker host composes the same Foundation configuration and services.

{% stepper %}
{% step %}

## Create or receive a DI scope

{% endstep %}

{% step %}

## Validate the message and resolve a PAL client

{% endstep %}

{% step %}

## Pass the broker cancellation token through every call

{% endstep %}

{% step %}

## Distinguish failures

Distinguish transient upstream failures from validation, authorization, and licensing failures.
{% endstep %}

{% step %}

## Acknowledge the message

Acknowledge the message only after all streamed resources are disposed and the business action is durable.
{% endstep %}
{% endstepper %}

## Native Avalonia shell

`PAL.Clients.Native.Shell` is a composition root for the native modular client. Its startup order is configuration, native logging, Foundation core services, native framework/regions, module discovery, module messaging, configured native authentication, local administrator seeding, lifecycle start, region activation, navigation wiring, session restore, then window display.

PAL.NET can be registered as part of the shared Foundation call. Keep PAL.NET capability clients in services or modules; do not put transport or credentials in view models.

## Configuration protection tool

The standalone protection tool converts `appsettings.{environment}.json` into `settings.{environment}.enc` using the same Foundation key resolution as runtime:

```powershell
dotnet run --project src/PAL.Clients.Internal.Configuration.Protection -- `
  src/PAL.Clients.Internal.Configuration.Protection `
  src/PAL.Core.Infrastructure.Dependencies.Configuration `
  development
```

It accepts `local`, `development`, `production`, or a comma-separated combination. Production keys must come from a protected deployment secret store. Encrypted files are deployment artefacts and should not be committed.

## Host responsibilities

The host owns:

* identity provider integration and user/session lifetime;
* secret and configuration providers;
* logging sinks and OpenTelemetry exporters;
* request, message, function, or window cancellation;
* retrying or dead-lettering whole business workflows;
* presentation of PAL exceptions to users or callers.

PAL.NET owns the protocol boundary and must be allowed to preserve operation, scope, licence, retry, stream, and diagnostic semantics.