[maui-labs docs] Document Native AOT support in DevFlow transports and logging #3551

Source PR

dotnet/maui-labs#527

PR Title: Support reflection-disabled Native AOT in DevFlow transports and logging
Author: davidortinau
Merged: 2026-10--02

Summary of Changes

PR #527 adds full Native AOT support to DevFlow, enabling reflection-disabled trimmed and Native AOT builds. This includes:

1. Native AOT Agent Support: DevFlow agents can now run in reflection-disabled Native AOT hosts without requiring JsonSerializerIsReflectionEnabledByDefault=true

2. Source-Generated JSON Contracts: All built-in HTTP requests/responses, broker registration, lease/recording messages, and WebSocket envelopes use source-generated JSON metadata

3. New Extension Registration APIs:

   • AgentJson.RegisterContext(JsonSerializerContext) - register custom JSON metadata for extension payloads
   • MauiAgentInspection.RegisterType(T)() - preserve inspection contracts for custom types in trimmed/AOT hosts

4. New HTTP Error Responses:

   • MissingJsonMetadata (500 with reason json-metadata-missing) - when extension requests/responses use unregistered custom types in AOT
   • UnsupportedJsonContract (500 with reason json-serialization-unsupported) - ambiguous collection metadata or unsupported custom converters

5. Logging Support: Microsoft.Maui.DevFlow.Logging now works with reflection-disabled Native AOT

Documentation Pages Affected

• DevFlow Getting Started / Integration Guide: docs/developer-tools/devflow/ - needs Native AOT section
• API Reference / DevFlow Specification: Update to include new error response types
• Landing page: docs/developer-tools/index.md - may need Native AOT capability callout

Suggested Changes

1. Add Native AOT Section to DevFlow Integration Guide

Create or update a subsection in the DevFlow quick start documentation covering:

Location: After the main "Quick Start" section, add "### Native AOT and Trimming" subsection

Content:

### Native AOT and Trimming

DevFlow agents support reflection-disabled trimmed and Native AOT builds. Built-in HTTP transports, broker registration, lease/recording messages, and WebSocket envelopes use source-generated JSON metadata and do not require `JsonSerializerIsReflectionEnabledByDefault=true`.

#### For Custom Extension Types

If your extension handler returns custom CLR types (not JSON primitives, collections, `JsonElement`, `JsonNode`, or `JsonDocument`), register a source-generated JSON context before serving requests:

```csharp
using System.Text.Json.Serialization;
using Microsoft.Maui.DevFlow.Agent.Core;

AgentJson.RegisterContext(MyExtensionJsonContext.Default);

[JsonSerializable(typeof(MyRequest))]
[JsonSerializable(typeof(MyResponse))]
internal partial class MyExtensionJsonContext : JsonSerializerContext;
```

Include concrete types used inside `object`-typed members in the context as well.

#### For Custom Controls and Inspection

If you have custom controls or objects accessed through property paths, preserve their inspection contracts in trimmed/AOT hosts:

```csharp
MauiAgentInspection.RegisterType(MyCustomControl)();
MauiAgentInspection.RegisterType(MyCustomPropertyObject)();
```

#### Unsupported Scenarios

The following features still require application-specific metadata or code preservation:

- Automatic `[DevFlowAction]` assembly scanning (use explicit extension routes instead)
- Arbitrary generic/async method invocation (register specific method contracts)
- Custom `TypeConverter` discovery (prefer registered extension routes)
- Legacy reflection-only Comet adapter
- Native UI platform rendering and gesture injection (verify on target device)

#### Error Responses in AOT

When JSON metadata is missing or contracts are ambiguous in reflection-disabled hosts:

- **Missing Metadata**: HTTP 500 with reason `json-metadata-missing`  
  → Register the extension's context with `AgentJson.RegisterContext()`

- **Unsupported Contract**: HTTP 500 with reason `json-serialization-unsupported`  
  → Register concrete collection types or check for ambiguous ancestor metadata

Reflection-enabled hosts retain existing arbitrary-object serialization behavior. No public method signatures or wire field names changed.

2. Update OpenAPI/API Reference

Location: Add or update the error responses section in API documentation

Content to add:

In the HTTP error responses documentation (if separate from OpenAPI spec), document the two new 500-level error types:

3. Update DevFlow Landing / Overview Page

Location: docs/developer-tools/devflow/ overview or index

Addition: Add a "Platform Support / Native AOT" capability statement, e.g.:

Native AOT Ready: DevFlow agents support reflection-disabled trimmed and Native AOT builds. Configure custom extension metadata using AgentJson.RegisterContext() for full AOT compatibility.

Reference: The comprehensive AOT guidance is documented in the source repo at:

• https://github.com/dotnet/maui-labs/blob/main/src/DevFlow/README.md (see "NativeAOT and trimming" section)
• OpenAPI schema additions: https://github.com/dotnet/maui-labs/blob/main/docs/DevFlow/spec/openapi.yaml (new MissingJsonMetadata and UnsupportedJsonContract schemas)

Generated by PR Documentation Check for issue #527 · ◷