NativeAOT Deployment

OfficeIMO's NativeAOT evidence covers the complete production project inventory rather than a hand-picked package list. 97 of 99 production projects publish and execute in NativeAOT validation. The optional Chromium browser-PDF bridge uses managed cross-platform deployment through HtmlTinkerX and Playwright. The WPF/WebView2 renderer is tested as a managed Windows component because the .NET SDK rejects trimming for WPF executables (NETSDK1168).

The 97 native-validated projects are not all proved in the same way:

• 95 production libraries are fully rooted as complete assemblies across two native hosts: 94 in the main compile graph and the optional OfficeIMO.Security package in its dedicated host. Both executables must start successfully.
• 1 optional Google APIs adapter runs a bounded token-store workflow natively. Its complete Google authorization dependency surface is not advertised as trim-safe because fully rooting Google.Apis and Newtonsoft.Json produces upstream warnings.
• 1 production command-line tool publishes as a native executable and must start and return its real command help.

The machine-readable project matrix names all 99 production projects and records which proof applies to each one. This distinction matters to customers: a green native workflow is useful evidence, but it is not permission to assume that every optional third-party API has been executed.

Publish your application

Use .NET 8 or .NET 10 and enable NativeAOT in the application that consumes OfficeIMO:

<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
  <PublishAot>true</PublishAot>
</PropertyGroup>

Publish for the operating system and architecture you plan to deploy:

dotnet publish -c Release -r win-x64
dotnet publish -c Release -r linux-x64

NativeAOT evaluates your complete application, including every package and code path you use. Run the published executable and assert the generated or extracted document content before shipping it.

The Word, Excel, PowerPoint, and Word-to-HTML packages use the Microsoft Open XML SDK in the supported range [3.5.1, 4.0.0). Normal OfficeIMO consumers receive that dependency transitively. If your application references DocumentFormat.OpenXml directly, keep its resolved version inside the same range so the dependency graph matches the versions validated by OfficeIMO.

Project-level coverage

CI fails if a production project is added, removed, or renamed without being classified in this matrix.

Executed document workflows

The repository publishes one namespaced native command surface while keeping each document workflow in its owning library.

These eight document workflows complement the project-level compile matrix with behavior and output checks. They are useful end-to-end baselines, not a claim that every possible document, option, or third-party service has been exercised. Add your templates, accepted formats, fonts, and representative source files to your application tests.

Package-family guidance

Prefer typed data paths

NativeAOT works best when types are visible to the compiler. OfficeIMO's normal document APIs already follow that model. APIs that inspect an arbitrary runtime object graph are marked so the compiler can warn at the call site.

Recommended patterns include:

• write Excel tables from DataTable, explicit cell values, or typed row mappings;
• read Excel rows with generic typed readers whose model type is known at publish time;
• build Word tables from explicit columns and cells when the model shape is dynamic;
• use generic Markdown object/table builders or dictionary-based data when fields are selected at runtime;
• register Reader adapters explicitly, or use AddAllOfficeIMOHandlers() for the complete local preset.

If your application loads plug-ins, type names, templates, or model members dynamically, preserve those members in the application or replace discovery with an explicit mapping. This is an application boundary rather than an OfficeIMO-specific switch.

Validate the deployment you will ship

A practical NativeAOT acceptance test should:

1. publish for the target runtime identifier;
2. start the produced native executable;
3. create, convert, or read a representative document;
4. reopen the output where the format supports it;
5. assert useful content such as text, tables, formulas, slides, relationships, or searchable PDF text.

OfficeIMO contributors can run the checked-in matrix for the current machine:

./Build/Test-AotScenarios.ps1

The script first validates the production-library host, then runs the eight document workflows and the two production CLI startup checks. Each scenario receives a fresh SDK artifacts directory, so a Linux run cannot consume Windows obj metadata and one scenario cannot reuse another scenario's native state. The same matrix runs in repository CI on Windows and Linux. Optional JSON results can be retained for deployment evidence:

./Build/Test-AotScenarios.ps1 -JsonOutputPath ./artifacts/aot-results.json
./Build/Test-AotProjectCoverage.ps1 -JsonOutputPath ./artifacts/aot-project-matrix.json

Trimming, ReadyToRun, and single-file deployment

These deployment modes solve different problems:

Do not copy warning suppressions from another application. Treat every trim or AOT warning at your call site as a request to choose a typed API, preserve an intentionally dynamic model, or remove a dependency that cannot support the deployment target.