Skip to main content

AOT Compatibility Matrix

This page records known public trim/AOT warning contracts, internal suppressions and compatibility metadata for shipping packages. Use it when planning AOT-published applications.

The table identifies known constraints; it is not certification that every path in a package publishes or runs correctly under NativeAOT. A package marked Not compatible does not claim general AOT compatibility. Its constraints can come from a dependency or framework code.

For setup instructions and source generator usage, see the Native AOT Guide.


How to Read This Matrix​

The column describes known warning contracts when trim/AOT analysis is enabled, and constraints that metadata or suppressed diagnostics can hide. Validate the paths your application uses in an actual published binary.

StatusWhat it means for your buildWhat to do
CleanNo public RequiresDynamicCode / RequiresUnreferencedCode annotation or internal suppression is recorded by these inventories. This does not guarantee a clean publish.Publish and exercise your application's paths.
Warns youExported declarations carry trim/AOT warning annotations. Some are conservative interface contracts rather than reflective operations in every implementation.Read the warning and use an appropriate alternative. A suppression requires evidence for the specific configuration.
Doesn't warn youReflection is present, but it is internal and suppressed here, so your build will say nothing about it.Your compiler cannot help you for this package. Publish an ahead-of-time binary and exercise these paths before you ship.
Not compatibleIsAotCompatible=false. The package does not claim ahead-of-time compatibility — usually a blocking dependency, sometimes reflection in its own code.
N/ATooling package (analyzer, source generator) — runs at compile time, not at runtime.

Dispatch Packages​

Core​

PackageAOT StatusNotes
Excalibur.DispatchWarns youSource-generated handler resolution via PrecompiledHandlerRegistry. Annotated declarations include ContextValidationDispatchBuilderExtensions.UseContextValidation, ContextValidationServiceCollectionExtensions.AddContextValidation, DeliveryServiceCollectionExtensions.AddInboxOptions and 38 more. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.AbstractionsWarns youInterface methods carry warning contracts for their implementations. Annotated declarations include IFencedOutboxStore.GetUnsentMessagesAsync, IOutboxDispatcher.RunOutboxDispatchAsync, IOutboxProcessor.DispatchPendingMessagesAsync and 12 more. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.PatternsWarns youAnnotated declarations include ClaimCheck.ClaimCheckMessageSerializer, ClaimCheckServiceCollectionExtensions.AddClaimCheck. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.Patterns.AzureWarns youAnnotated path: the IConfiguration-binding overload of AddAzureBlobClaimCheck, which reflects over the options type. The overload taking options in code avoids that configuration-binding path. Annotated declarations include AzurePatternsServiceCollectionExtensions.AddAzureBlobClaimCheck. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.Patterns.ClaimCheck.InMemoryWarns youAnnotated path: the IConfiguration-binding overload of AddInMemoryClaimCheck, which reflects over the options type. The overload taking options in code avoids that configuration-binding path. Annotated declarations include InMemoryClaimCheckServiceCollectionExtensions.AddInMemoryClaimCheck. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.Patterns.Hosting.JsonDoesn't warn you

Middleware and Pipeline​

PackageAOT StatusNotes
Excalibur.Dispatch.CachingWarns youCachingMiddleware uses RuntimeFeature.IsDynamicCodeSupported branching. Review this package's warning contracts and internal suppressions for the paths you use. Annotated declarations include CachingDispatchBuilderExtensions.UseCaching, CachingDispatchBuilderExtensions.WithCachingOptions, CachingServiceCollectionExtensions.AddCachePolicy and 7 more. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.Resilience.PollyWarns youPolly v8 is AOT-compatible. Annotated declarations include DispatchBuilderResilienceExtensions.UseResilience, PollyResilienceServiceCollectionExtensions.AddPollyResilience. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.Validation.FluentValidationWarns youDual-path: AotFluentValidatorResolver + source-gen IAotValidationDispatcher. Annotated declarations include FluentValidationServiceCollectionExtensions.WithFluentValidation. Other paths still require their own trim/AOT validation.

Serialization​

PackageAOT StatusNotes
Excalibur.Dispatch.Serialization.MemoryPackWarns youMemoryPack uses source generation. Annotated declarations include MemoryPack.MemoryPackSerializer. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.Serialization.AvroNot compatibleApache.Avro uses runtime code generation
Excalibur.Dispatch.Serialization.MessagePackNot compatibleMessagePack reflection-based resolvers
Excalibur.Dispatch.Serialization.ProtobufWarns youUses Google.Protobuf (v3.32.1+), which is AOT-compatible. Annotated declarations include Protobuf.ProtobufSerializer. Other paths still require their own trim/AOT validation.

Transport​

PackageAOT StatusNotes
Excalibur.Dispatch.Transport.AbstractionsWarns youCloudEventEncoderAdapter<TOutbound> forwards to the registered ICloudEventEncoder<TOutbound>, which may serialize reflectively. Annotated declarations include ICloudEventEncoder.ToTransportMessageAsync. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.Transport.RabbitMQWarns youBuilder registration includes the annotated CloudEvents paths listed here. Annotated declarations include RabbitMqCloudEventsServiceCollectionExtensions.AddCloudEventsForRabbitMq. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.Transport.AwsSqsWarns youBuilder registration includes the annotated CloudEvents paths listed here. Annotated declarations include AwsCloudEventsServiceCollectionExtensions.AddCloudEventsForEventBridge, AwsCloudEventsServiceCollectionExtensions.AddCloudEventsForSns, AwsCloudEventsServiceCollectionExtensions.AddCloudEventsForSqs and 2 more. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.Transport.AzureServiceBusWarns youMessageDeserializerRegistry typed pattern; EventGridTransportSender annotated. Annotated declarations include AzureCloudEventsServiceCollectionExtensions.AddCloudEventsForEventHubs, AzureCloudEventsServiceCollectionExtensions.AddCloudEventsForServiceBus, AzureCloudEventsServiceCollectionExtensions.UseCloudEvents. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.Transport.GooglePubSubNot compatibleGoogle Cloud SDK dependency uses reflection. UseCloudEvents and AddCloudEventsForPubSub are separately annotated: the bundled mapper serializes payloads reflectively
Excalibur.Dispatch.Transport.KafkaNot compatibleConfluent.Kafka SchemaRegistry uses Activator.CreateInstance. AddCloudEventsForKafka is separately annotated: the bundled mapper serializes payloads reflectively
Excalibur.Dispatch.Transport.GrpcDoesn't warn youGrpcJsonSerializerContext source-gen JSON for all 10 transport types

Hosting​

PackageAOT StatusNotes
Excalibur.Dispatch.Hosting.AspNetCoreWarns youAnnotated declarations include EndpointRouteBuilderExtensions.DispatchDeleteAction, EndpointRouteBuilderExtensions.DispatchGetAction, EndpointRouteBuilderExtensions.DispatchPostAction and 4 more. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.Hosting.AwsLambdaWarns youAnnotated declarations include AwsLambdaServiceCollectionExtensions.AddAwsLambdaServerless. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.Hosting.AzureFunctionsWarns youAnnotated path: the IConfiguration-binding overload of AddAzureFunctionsServerless, which reflects over the options type. The overload taking options in code avoids that configuration-binding path. Annotated declarations include AzureFunctionsServiceCollectionExtensions.AddAzureFunctionsServerless. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.Hosting.GoogleCloudFunctionsWarns youAnnotated path: the IConfiguration-binding overload of AddGoogleCloudFunctionsServerless, which reflects over the options type. The overload taking options in code avoids that configuration-binding path. Annotated declarations include GoogleCloudFunctionsServiceCollectionExtensions.AddGoogleCloudFunctionsServerless. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.Hosting.Serverless.AbstractionsWarns youAnnotated path: the IConfiguration-binding overload of AddServerlessHosting, which reflects over the options type. The overload taking options in code avoids that configuration-binding path. Annotated declarations include ServerlessServiceCollectionExtensions.AddServerlessHosting. Other paths still require their own trim/AOT validation.

Observability​

PackageAOT StatusNotes
Excalibur.Dispatch.ObservabilityWarns youUses System.Diagnostics (OTel-aligned). Review this package's warning contracts and internal suppressions for the paths you use. Annotated declarations include ContextTraceEnricher.CreateContextOperationSpan, ContextTraceEnricher.EnrichActivity, DispatchBuilderObservabilityExtensions.UseObservability and 2 more. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.Observability.AwsClean

Security​

PackageAOT StatusNotes
Excalibur.SecurityWarns youAnnotated declarations include Argon2ServiceCollectionExtensions.AddPasswordHasher, SecurityExcaliburBuilderExtensions.UseSecurity, SecurityMiddlewareExtensions.AddDispatchSecurityMiddleware and 7 more. Other paths still require their own trim/AOT validation.
Excalibur.Security.AwsNot compatibleAWS SDK v3 (AWSSDK.Core, AWSSDK.SecretsManager) is reflection-based and declares no trim or AOT properties, so the analyzer cannot see its reflection and reports nothing while a native publish fails at link time
Excalibur.Security.AzureClean

Compliance​

PackageAOT StatusNotes
Excalibur.Compliance.AbstractionsWarns you
Excalibur.ComplianceWarns youThe public paths listed here carry trim/AOT warning contracts. Annotated declarations include EncryptionDecryptionService.ExportDecryptedAsync, GdprServiceCollectionExtensions.AddRetentionPoliciesFromAssembly, RegexDataMasker.MaskObject. Other paths still require their own trim/AOT validation.
Excalibur.Compliance.AwsNot compatibleAWS KMS SDK dependency
Excalibur.Compliance.AzureDoesn't warn you
Excalibur.Compliance.VaultDoesn't warn you

Audit Logging​

PackageAOT StatusNotes
Excalibur.AuditLoggingDoesn't warn you
Excalibur.AuditLogging.AwsDoesn't warn you
Excalibur.AuditLogging.DatadogDoesn't warn you
Excalibur.AuditLogging.ElasticsearchDoesn't warn you
Excalibur.AuditLogging.GoogleCloudDoesn't warn you
Excalibur.AuditLogging.OpenSearchDoesn't warn you
Excalibur.AuditLogging.PostgresWarns youAnnotated path: the IConfiguration-binding overload of AddPostgresAuditStore, which reflects over the options type. The overload taking options in code avoids that configuration-binding path. Annotated declarations include PostgresAuditServiceCollectionExtensions.AddPostgresAuditStore. Other paths still require their own trim/AOT validation.
Excalibur.AuditLogging.SentinelDoesn't warn you
Excalibur.AuditLogging.SplunkDoesn't warn you
Excalibur.AuditLogging.SqlServerDoesn't warn you

Claim Check​

PackageAOT StatusNotes
Excalibur.Dispatch.ClaimCheck.AwsS3Not compatibleAWS S3 SDK dependency
Excalibur.Dispatch.ClaimCheck.GoogleCloudStorageNot compatibleGoogle Cloud Storage SDK dependency

Leader Election​

PackageAOT StatusNotes
Excalibur.Dispatch.LeaderElection.AbstractionsClean

Testing​

PackageAOT StatusNotes
Excalibur.Dispatch.TestingWarns youAnnotated declarations include DispatchTestHarness.CreateAsyncScope, DispatchTestHarness.CreateScope, DispatchTestHarness.Dispatcher and 1 more. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.Testing.ShouldlyClean

Tooling (compile-time only)​

PackageAOT StatusNotes
Excalibur.Dispatch (bundled generator)N/ARoslyn source generator (netstandard2.0)
Excalibur.Dispatch (bundled analyzer)N/ARoslyn analyzer (netstandard2.0)
Excalibur.Dispatch.AnalyzersN/ARoslyn analyzer (netstandard2.0)

Excalibur Packages​

Domain and Data Access​

PackageAOT StatusNotes
Excalibur.DomainWarns youAnnotated declarations include BoundedContextServiceCollectionExtensions.AddBoundedContextEnforcement, DefaultBoundedContextValidator.#ctor, DefaultBoundedContextValidator.ValidateAsync and 3 more. Other paths still require their own trim/AOT validation.
Excalibur.ApplicationWarns youAnnotated declarations include ExcaliburApplicationServiceCollectionExtensions.AddActivities. Other paths still require their own trim/AOT validation.
Excalibur.Data.AbstractionsClean
Excalibur.DataWarns youAnnotated declarations include Serialization.ExcaliburJsonSerializerOptions. Other paths still require their own trim/AOT validation.
Excalibur.Data.InMemoryWarns youReview this package's warning contracts and internal suppressions for the paths you use. Annotated declarations include InMemoryPersistenceProvider.InitializeAsync, InMemoryPersistenceProvider.PersistToDiskAsync, InMemoryServiceCollectionExtensions.AddExcaliburInMemory. Other paths still require their own trim/AOT validation.
Excalibur.Data.SqlServerWarns youDapper itself is AOT-compatible. The dead-letter property bag uses a source-generated JSON context; configuration-binding registration can still warn. Annotated path: AddSqlServerPersistence. Annotated declarations include SqlServerPersistenceExtensions.AddSqlServerPersistence. Other paths still require their own trim/AOT validation.
Excalibur.Data.PostgresWarns youDapper itself is AOT-compatible. The dead-letter property bag uses a source-generated JSON context; configuration-binding registration can still warn. Annotated declarations include PostgresPersistenceServiceCollectionExtensions.AddPostgresPersistence, PostgresPersistenceServiceCollectionExtensions.AddPostgresPersistenceFromSection, PostgresServiceCollectionExtensions.AddPostgresDeadLetterStore. Other paths still require their own trim/AOT validation.
Excalibur.Data.MySqlDoesn't warn you
Excalibur.Data.MongoDBWarns youReview this package's warning contracts and internal suppressions for the paths you use. Annotated declarations include MongoDbMaterializedViewStore.GetAsync, MongoDbMaterializedViewStore.SaveAsync, MongoDbMaterializedViewStore.SaveViewAndPositionAsync and 9 more. Other paths still require their own trim/AOT validation.
Excalibur.Data.RedisDoesn't warn you
Excalibur.Data.ElasticSearchWarns youReview this package's warning contracts and internal suppressions for the paths you use. Annotated declarations include ElasticSearchMaterializedViewStore.GetAsync, ElasticSearchMaterializedViewStore.SaveAsync, ElasticSearchProjectionStore.GetByIdAsync and 36 more. Other paths still require their own trim/AOT validation.
Excalibur.Data.ElasticSearch.AzureWarns youAddAzureKeyVaultCredentialStorage is annotated, so the diagnostic surfaces at your call site rather than in this package's own build. Annotated declarations include ElasticsearchAzureServiceCollectionExtensions.AddAzureKeyVaultCredentialStorage. Other paths still require their own trim/AOT validation.
Excalibur.Data.DataProcessingWarns youAnnotated declarations include DataProcessingBuilderExtensions.AddProcessorsFromAssembly, DataProcessingBuilderExtensions.AddRecordHandlersFromAssembly, DataProcessingServiceCollectionExtensions.AddDataProcessing. Other paths still require their own trim/AOT validation.
Excalibur.Data.CosmosDbNot compatibleCosmosDB SDK uses Expression.Compile()
Excalibur.Data.DynamoDbNot compatibleDynamoDB SDK reflection-based marshalling
Excalibur.Data.FirestoreNot compatibleFirestore SDK uses reflection
Excalibur.Data.OpenSearchNot compatibleOpenSearch SDK dependency

Event Sourcing​

PackageAOT StatusNotes
Excalibur.EventSourcing.AbstractionsWarns youAnnotated declarations include IAtomicMaterializedViewStore.SaveViewAndPositionAsync, ICursorProjectionStore.QueryCursorAsync, IDistinctValuesProjectionStore.DistinctValuesAsync and 21 more. Other paths still require their own trim/AOT validation.
Excalibur.EventSourcingWarns youAnnotated declarations include CompositeSnapshotStrategy.ShouldCreateSnapshot, EncryptingProjectionStoreDecorator.GetByIdAsync, EncryptingProjectionStoreDecorator.QueryAsync and 32 more. Other paths still require their own trim/AOT validation.
Excalibur.EventSourcing.InMemoryDoesn't warn you
Excalibur.EventSourcing.SqlServerWarns youReview this package's warning contracts and internal suppressions for the paths you use. Annotated declarations include SqlServerMaterializedViewStore.GetAsync, SqlServerMaterializedViewStore.SaveAsync, SqlServerMaterializedViewStore.SaveViewAndPositionAsync and 9 more. Other paths still require their own trim/AOT validation.
Excalibur.EventSourcing.PostgresWarns youReview this package's warning contracts and internal suppressions for the paths you use. Annotated declarations include PostgresMaterializedViewStore.GetAsync, PostgresMaterializedViewStore.SaveAsync, PostgresMaterializedViewStore.SaveViewAndPositionAsync and 8 more. Other paths still require their own trim/AOT validation.
Excalibur.EventSourcing.MongoDBDoesn't warn youReview this package's warning contracts and internal suppressions for the paths you use.
Excalibur.EventSourcing.RedisDoesn't warn youReview this package's warning contracts and internal suppressions for the paths you use.
Excalibur.EventSourcing.SqliteWarns youAnnotated path: the IConfiguration-binding overload of UseSqlite, which reflects over the options type. The overload taking options in code avoids that configuration-binding path. Annotated declarations include SqliteEventSourcingServiceCollectionExtensions.UseSqlite. Other paths still require their own trim/AOT validation.
Excalibur.EventSourcing.AwsS3Doesn't warn youReview this package's warning contracts and internal suppressions for the paths you use.
Excalibur.EventSourcing.AzureBlobDoesn't warn youReview this package's warning contracts and internal suppressions for the paths you use.
Excalibur.EventSourcing.GcsDoesn't warn youReview this package's warning contracts and internal suppressions for the paths you use.
Excalibur.EventSourcing.CosmosDbNot compatibleCosmosDB SDK dependency
Excalibur.EventSourcing.DynamoDbNot compatibleDynamoDB SDK dependency
Excalibur.EventSourcing.FirestoreNot compatibleFirestore SDK dependency

Outbox​

PackageAOT StatusNotes
Excalibur.OutboxWarns youAnnotated declarations include MessageOutbox.RunOutboxDispatchAsync, MultiTransportOutboxServiceCollectionExtensions.AddMultiTransportOutbox, OutboxExcaliburBuilderExtensions.AddOutbox and 3 more. Other paths still require their own trim/AOT validation.
Excalibur.Outbox.InMemoryWarns youReview this package's warning contracts and internal suppressions for the paths you use. Annotated declarations include InMemoryOutboxStore.EnqueueAsync, InMemoryOutboxStore.GetUnsentMessagesAsync. Other paths still require their own trim/AOT validation.
Excalibur.Outbox.SqlServerWarns youReview this package's warning contracts and internal suppressions for the paths you use. Annotated declarations include SqlServerOutboxStore.EnqueueAsync, SqlServerOutboxStore.GetUnsentMessagesAsync. Other paths still require their own trim/AOT validation.
Excalibur.Outbox.PostgresWarns youAnnotated declarations include PostgresOutboxStore.EnqueueAsync, PostgresOutboxStore.GetUnsentMessagesAsync. Other paths still require their own trim/AOT validation.
Excalibur.Outbox.RedisWarns youAnnotated declarations include RedisOutboxStore.EnqueueAsync, RedisOutboxStore.GetUnsentMessagesAsync. Other paths still require their own trim/AOT validation.
Excalibur.Outbox.ElasticSearchWarns youAnnotated declarations include ElasticsearchOutboxStore.EnqueueAsync, ElasticsearchOutboxStore.GetUnsentMessagesAsync. Other paths still require their own trim/AOT validation.
Excalibur.Outbox.CosmosDbNot compatibleCosmosDB SDK dependency
Excalibur.Outbox.DynamoDbNot compatibleDynamoDB SDK dependency
Excalibur.Outbox.FirestoreNot compatibleFirestore SDK dependency
Excalibur.Outbox.MongoDBNot compatibleMongoDB driver dependency

Inbox​

PackageAOT StatusNotes
Excalibur.InboxClean
Excalibur.Inbox.InMemoryClean
Excalibur.Inbox.SqlServerDoesn't warn youUseSqlServer no longer binds configuration for you, so that registration does not perform reflective binding. To read options from configuration, call services.AddOptions<SqlServerInboxOptions>().BindConfiguration("Section:Path") alongside the registration — binding is reflective, so the trim/AOT warning belongs at your own call site where the trimmer can see it.
Excalibur.Inbox.PostgresDoesn't warn you
Excalibur.Inbox.RedisDoesn't warn you
Excalibur.Inbox.ElasticSearchDoesn't warn you
Excalibur.Inbox.MongoDBDoesn't warn you
Excalibur.Inbox.DynamoDbNot compatibleShips Excalibur.Data.DynamoDb, which is not AOT-compatible
Excalibur.Inbox.FirestoreNot compatibleShips Excalibur.Data.Firestore, which is not AOT-compatible
Excalibur.Inbox.CosmosDbNot compatibleCosmosDB SDK dependency

Saga​

PackageAOT StatusNotes
Excalibur.SagaWarns youSource-gen registry population via IPostConfigureOptions pattern. Annotated declarations include SagaBase.RequestTimeoutAsync, SagaBase.SerializeTimeoutData, SagaCoordinator.HandleEventInternalAsync and 3 more. Other paths still require their own trim/AOT validation.
Excalibur.Saga.SqlServerWarns youAnnotated declarations include SagaBuilderSqlServerExtensions.UseSqlServer, SaveSagaRequest.#ctor, SqlServerSagaExtensions.AddSqlServerSagaStore and 2 more. Other paths still require their own trim/AOT validation.
Excalibur.Saga.PostgresWarns youAnnotated declarations include PostgresSagaExtensions.AddPostgresSagaStore, PostgresSagaStore.SaveAsync, SagaBuilderPostgresExtensions.UsePostgres and 1 more. Other paths still require their own trim/AOT validation.
Excalibur.Saga.MongoDBWarns youAnnotated path: SaveAsync — saga state is serialized with a reflection-based serializer. Annotated declarations include MongoDbSagaStore.SaveAsync. Other paths still require their own trim/AOT validation.
Excalibur.Saga.DynamoDbNot compatibleShips Excalibur.Data.DynamoDb, which is not AOT-compatible
Excalibur.Saga.FirestoreNot compatibleShips Excalibur.Data.Firestore, which is not AOT-compatible
Excalibur.Saga.CosmosDbNot compatibleCosmosDB SDK dependency

CDC (Change Data Capture)​

PackageAOT StatusNotes
Excalibur.CdcWarns youAnnotated path: the IConfiguration-binding overload of AddCdcHealthCheck, which reflects over the options type. The overload taking options in code avoids that configuration-binding path. Annotated declarations include CdcHealthChecksBuilderExtensions.AddCdcHealthCheck. Other paths still require their own trim/AOT validation.
Excalibur.Cdc.SqlServerWarns youAnnotated declarations include DataChangeHandlerCdcBuilderExtensions.AddDataChangeHandlersFromAssembly, DataChangeHandlerServiceCollectionExtensions.AddDataChangeHandlersFromAssembly, SqlServerCdcHealthChecksBuilderExtensions.AddCdcHealthCheck. Other paths still require their own trim/AOT validation.
Excalibur.Cdc.PostgresWarns youAnnotated path: UsePostgres — its only overload. The annotation covers the configuration-binding path the builder exposes, so the call site warns even when you configure in code. Annotated declarations include CdcBuilderPostgresExtensions.UsePostgres. Other paths still require their own trim/AOT validation.
Excalibur.Cdc.MongoDBDoesn't warn you
Excalibur.Cdc.DynamoDbNot compatibleShips Excalibur.Data.DynamoDb, which is not AOT-compatible
Excalibur.Cdc.FirestoreNot compatibleShips Excalibur.Data.Firestore, which is not AOT-compatible
Excalibur.Cdc.CosmosDbNot compatibleCosmosDB SDK dependency

Leader Election​

PackageAOT StatusNotes
Excalibur.LeaderElectionWarns youAnnotated declarations include LeaderElectionWatchServiceCollectionExtensions.AddLeaderElectionWatcher. Other paths still require their own trim/AOT validation.
Excalibur.LeaderElection.InMemoryWarns youAnnotated path: the IConfiguration-binding overload of AddInMemoryLeaderElection, which reflects over the options type. The overload taking options in code avoids that configuration-binding path. Annotated declarations include InMemoryLeaderElectionServiceCollectionExtensions.AddInMemoryLeaderElection. Other paths still require their own trim/AOT validation.
Excalibur.LeaderElection.SqlServerCleanUseSqlServer no longer binds configuration for you, so that registration does not perform reflective binding. To read options from configuration, call services.AddOptions<SqlServerLeaderElectionOptions>().BindConfiguration("Section:Path") alongside the registration — binding is reflective, so the trim/AOT warning belongs at your own call site where the trimmer can see it.
Excalibur.LeaderElection.PostgresCleanUsePostgres no longer binds configuration for you, so that registration does not perform reflective binding. To read options from configuration, call services.AddOptions<PostgresLeaderElectionOptions>().BindConfiguration("Section:Path") alongside the registration — binding is reflective, so the trim/AOT warning belongs at your own call site where the trimmer can see it.
Excalibur.LeaderElection.RedisDoesn't warn you
Excalibur.LeaderElection.MongoDBDoesn't warn you
Excalibur.LeaderElection.ConsulNot compatibleConsul SDK dependency
Excalibur.LeaderElection.KubernetesNot compatibleKubernetes SDK dependency

Hosting​

PackageAOT StatusNotes
Excalibur.HostingWarns youAnnotated declarations include DispatchHealthChecksBuilderExtensions.AddExcaliburHealthChecks, ExcaliburBuilderContextExtensions.ScanAssemblies, ExcaliburBuilderDispatchExtensions.AddDispatch. Other paths still require their own trim/AOT validation.
Excalibur.Hosting.WebClean
Excalibur.Hosting.AwsClean
Excalibur.Hosting.AwsLambdaWarns youAnnotated declarations include ExcaliburAwsLambdaServiceCollectionExtensions.AddExcaliburAwsLambdaServerless. Other paths still require their own trim/AOT validation.
Excalibur.Hosting.AzureFunctionsWarns youAnnotated path: the IConfiguration-binding overload of AddExcaliburAzureFunctionsServerless, which reflects over the options type. The overload taking options in code avoids that configuration-binding path. Annotated declarations include ExcaliburAzureFunctionsServiceCollectionExtensions.AddExcaliburAzureFunctionsServerless. Other paths still require their own trim/AOT validation.
Excalibur.Hosting.GoogleCloudFunctionsWarns youAnnotated path: the IConfiguration-binding overload of AddExcaliburGoogleCloudFunctionsServerless, which reflects over the options type. The overload taking options in code avoids that configuration-binding path. Annotated declarations include ExcaliburGoogleCloudFunctionsServiceCollectionExtensions.AddExcaliburGoogleCloudFunctionsServerless. Other paths still require their own trim/AOT validation.
Excalibur.Hosting.HealthChecksWarns youAnnotated declarations include ExcaliburHealthChecksApplicationExtensions.UseExcaliburHealthChecks. Other paths still require their own trim/AOT validation.
Excalibur.Hosting.JobsNot compatibleShips Excalibur.Jobs, which is not AOT-compatible
Excalibur.Hosting.ObservabilityClean
Excalibur.Hosting.Logging.SerilogClean

A3 (Authentication, Authorization, Audit)​

PackageAOT StatusNotes
Excalibur.A3Warns youAnnotated declarations include A3ServiceCollectionExtensions.AddA3DispatchServices, A3ServiceCollectionExtensions.AddExcaliburA3, AuditExcaliburBuilderExtensions.AddAudit and 2 more. Other paths still require their own trim/AOT validation.
Excalibur.A3.AbstractionsClean
Excalibur.A3.AspNetCoreClean
Excalibur.A3.CoreWarns youAnnotated path: the IConfiguration-binding overload of AddRoles, which reflects over the options type. The overload taking options in code avoids that configuration-binding path. Annotated declarations include RoleServiceCollectionExtensions.AddRoles. Other paths still require their own trim/AOT validation.
Excalibur.A3.GovernanceWarns youAnnotated path: the IConfiguration-binding overload of AddOrphanedAccessDetection, which reflects over the options type. The overload taking options in code avoids that configuration-binding path. Annotated declarations include OrphanedAccessGovernanceBuilderExtensions.AddOrphanedAccessDetection. Other paths still require their own trim/AOT validation.
Excalibur.A3.Governance.AbstractionsClean
Excalibur.A3.Policy.CedarClean
Excalibur.A3.Policy.OpaClean

Security and Compliance​

PackageAOT StatusNotes
Excalibur.Security.AbstractionsClean
Excalibur.Compliance.SqlServerWarns youAnnotated path: the IConfiguration-binding overload of AddSqlServerKeyEscrow, which reflects over the options type. The overload taking options in code avoids that configuration-binding path. Annotated declarations include SqlServerKeyEscrowServiceCollectionExtensions.AddSqlServerKeyEscrow. Other paths still require their own trim/AOT validation.
Excalibur.Compliance.PostgresClean
Excalibur.CachingNot compatibleHybridCache uses reflection

Jobs​

PackageAOT StatusNotes
Excalibur.JobsNot compatibleThe projection-rebuild and outbox jobs drive reflective paths; the requirement is annotated at the members that do it
Excalibur.Jobs.AbstractionsWarns you
Excalibur.Jobs.AwsClean
Excalibur.Jobs.AzureClean
Excalibur.Jobs.CdcNot compatibleShips Excalibur.Jobs, which is not AOT-compatible
Excalibur.Jobs.DataProcessingNot compatibleShips Excalibur.Jobs, which is not AOT-compatible
Excalibur.Jobs.GoogleCloudClean
Excalibur.Jobs.RedisWarns youAnnotated declarations include RedisJobCoordinator.DistributeJobAsync, RedisJobCoordinator.ReportJobCompletionAsync. Other paths still require their own trim/AOT validation.
Excalibur.Jobs.SqlServerNot compatibleShips Excalibur.Jobs, which is not AOT-compatible

Testing​

PackageAOT StatusNotes
Excalibur.TestingClean
Excalibur.Testing.ConformanceNot compatibleTest kits that read stored data back through the store under test, which deserializes reflectively. A trimmed test host is not a supported configuration

Tools​

PackageAOT StatusNotes
Excalibur.Migrate.ToolDoesn't warn you

Metapackages​

PackageAOT StatusNotes
Excalibur.Dispatch.RabbitMQWarns youThe single entry point is annotated, so there is no unannotated path to avoid Annotated declarations include DispatchRabbitMQServiceCollectionExtensions.AddDispatchRabbitMQ. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.AwsWarns youThe single entry point is annotated, so there is no unannotated path to avoid Annotated declarations include DispatchAwsServiceCollectionExtensions.AddDispatchAws. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.AzureWarns youThe single entry point is annotated, so there is no unannotated path to avoid Annotated declarations include DispatchAzureServiceCollectionExtensions.AddDispatchAzure. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.KafkaNot compatibleShips Excalibur.Dispatch.Transport.Kafka, which is not AOT-compatible
Excalibur.Dispatch.PostgresWarns youAnnotated declarations include DispatchPostgresServiceCollectionExtensions.AddDispatchWithPostgres. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.SqlServerWarns youRegisters an outbox, which serializes payloads reflectively. The single entry point is annotated, so there is no unannotated path to avoid Annotated declarations include DispatchSqlServerServiceCollectionExtensions.AddDispatchWithSqlServer. Other paths still require their own trim/AOT validation.
Excalibur.PostgresWarns youAnnotated declarations include ExcaliburPostgresServiceCollectionExtensions.AddExcaliburPostgres. Other paths still require their own trim/AOT validation.
Excalibur.SqlServerWarns youRegisters an outbox, which serializes payloads reflectively. Both entry points are annotated, so there is no unannotated path to avoid Annotated declarations include ExcaliburSqlServerServiceCollectionExtensions.AddExcaliburSqlServer. Other paths still require their own trim/AOT validation.

Blocking Dependencies​

These third-party dependencies prevent AOT compatibility in the affected packages:

DependencyBlocking ReasonAffected Packages
Azure CosmosDB SDKExpression.Compile() in LINQ providerCosmosDb data, event sourcing, outbox, inbox, saga, CDC
AWS DynamoDB SDKReflection-based marshallingDynamoDb data, event sourcing, outbox
Google Firestore SDKReflection-based serializationFirestore data, event sourcing, outbox
Confluent.KafkaActivator.CreateInstance for schema strategiesKafka transport
FluentValidationExpression.Compile() for validatorsFluentValidation middleware
Apache.AvroRuntime code generationAvro serialization
MessagePack-CSharpReflection-based resolversMessagePack serialization
protobuf-netExpression.Compile()(none currently — Excalibur.Dispatch.Serialization.Protobuf uses Google.Protobuf, which is AOT-safe)
OpenSearch SDKReflection-based serializationOpenSearch data
Consul SDKReflection-based HTTP clientConsul leader election
Kubernetes SDKReflection-based clientKubernetes leader election

When these dependencies release AOT-compatible versions, the affected packages will be updated.


Consumer Checklist​

To publish an AOT application with Excalibur:

  1. Verify all referenced packages are AOT-safe using the matrix above

  2. Add source generators to your project:

    <!-- The generators and DISP analyzers are bundled in Excalibur.Dispatch; no extra reference needed. -->
    <PackageReference Include="Excalibur.Dispatch" />
  3. Create a JsonSerializerContext for your application types (see Native AOT Guide)

  4. Mark handlers with [AutoRegister] for compile-time DI registration

  5. Publish with AOT for your target runtime (this example uses Linux x64):

    dotnet publish -c Release -r linux-x64 -p:PublishAot=true
  6. Check for warnings — and know what their absence does and does not prove.

    Zero IL2xxx/IL3xxx warnings is useful evidence for the paths analyzed by the toolchain, but does not certify a package or application as AOT compatible. An annotation can be missing, a suppression can hide a warning, and an unexercised runtime path can still fail. For every package status, run the published native binary and exercise the application paths you depend on. Review suppressed paths especially carefully for a Doesn't warn you package.

  7. For any package in the "Doesn't warn you" column, test the binary, not the build log. Run the published ahead-of-time output and exercise the paths you depend on. That is the only signal available to you for those packages, because the compile-time one has been turned off.

For a Warns you package, [RequiresUnreferencedCode] and [RequiresDynamicCode] propagate the warning to your call site, so you can make the decision where you can see it. That propagation is what the Doesn't warn you column is telling you that you will not get.

Additional Packages​

These packages ship from this repository and were absent from the matrix above. Status is read directly from each project's IsAotCompatible property, the same source the sections above use.

PackageAOT StatusNotes
Excalibur.Dispatch.Compat.MassTransitClean
Excalibur.Dispatch.Compat.MediatRCleanAddMediatRCompat registers a fixed set of adapters and needs no reflection over consumer types, so no exported warning contract is recorded for that adapter registration.
Excalibur.Dispatch.MigrationNot compatible
Excalibur.Dispatch.Transport.IbmMqNot compatibleNOT compatible. The IBM MQ managed client uses runtime reflection and dynamic assembly loading.
Excalibur.Dispatch.Transport.MqttWarns youBuilder registration includes the annotated CloudEvents paths listed here. The CloudEvents encoder serializes the payload through reflection-based JSON. Annotated declarations include MqttCloudEventsServiceCollectionExtensions.AddCloudEventsForMqtt. Other paths still require their own trim/AOT validation.
Excalibur.Dispatch.Transport.PulsarClean
Excalibur.AuditLogging.AbstractionsClean
Excalibur.Compliance.MongoDbClean
Excalibur.Compliance.PdfNot compatible
Excalibur.Data.IdentityMap.SqlServerCleanUseSqlServer no longer binds configuration for you, so that registration does not perform reflective binding. To read options from configuration, call services.AddOptions<SqlServerIdentityMapOptions>().BindConfiguration("Section:Path") alongside the registration — binding is reflective, so the trim/AOT warning belongs at your own call site where the trimmer can see it.
Excalibur.Data.IdentityMapClean
Excalibur.Data.SpannerNot compatibleNOT compatible. Google.Cloud.Spanner.Data uses gRPC + reflection-based value conversion.
Excalibur.EventSourcing.HandlersClean
Excalibur.EventSourcing.OracleDoesn't warn youReview this package's warning contracts and internal suppressions for the paths you use.
Excalibur.Inbox.OracleDoesn't warn youUseOracle no longer binds configuration for you, so that registration does not perform reflective binding. To read options from configuration, call services.AddOptions<OracleInboxOptions>().BindConfiguration("Section:Path") alongside the registration — binding is reflective, so the trim/AOT warning belongs at your own call site where the trimmer can see it.
Excalibur.MultiTenancyNot compatibleRow-discriminator decoration of open-generic IProjectionStore<T> uses reflective MakeGenericType over the DI descriptor set, so this composition
Excalibur.Operations.Dashboard.EventSourcingClean
Excalibur.Operations.Dashboard.SpaClean
Excalibur.Operations.DashboardClean
Excalibur.Outbox.MartenNot compatible
Excalibur.Outbox.OracleWarns youAnnotated declarations include OracleOutboxStore.EnqueueAsync, OracleOutboxStore.GetUnsentMessagesAsync. Other paths still require their own trim/AOT validation.
Excalibur.Saga.OracleWarns youAnnotated declarations include OracleSagaExtensions.AddOracleSagaStore, OracleSagaExtensions.UseOracleSagaStore, OracleSagaStore.SaveAsync and 2 more. Other paths still require their own trim/AOT validation.
Excalibur.Security.AuditLoggingClean
Excalibur.Testing.ContainersNot compatibleFixtures run under a test host, not a trimmed consumer app; reflection in Testcontainers is acceptable here.
Excalibur.Workflows.AbstractionsClean
Excalibur.Workflows.SqlServerClean
Excalibur.WorkflowsDoesn't warn you
Excalibur.Dispatch.AspNetCoreWarns youAnnotated declarations include DispatchAspNetCoreServiceCollectionExtensions.AddDispatchAspNetCore. Other paths still require their own trim/AOT validation.