Repository navigation
Understand the Architecture
Last verified against v3.0.0
IntegratoR is Clean Architecture with dependencies pointing inward: the concrete infrastructure layers (OData, OData.FO, Application, Hosting) reference the abstract core (Abstractions), never the reverse. A consumer wires the whole graph with one call — AddIntegratoR(configuration) — and drives it through IMediator. The rest of this page states the durable invariants that outlive any single file.
Every arrow points at IntegratoR.Abstractions. Higher layers depend on the core; the core depends on nothing above it. This is what lets a consumer reference only IService<T> and Result<T> from Abstractions for testability while the concrete ODataService<T> lives in IntegratoR.OData and is bound at the composition root.
SampleFunction (host / composition root)
-> Hosting -> Application -> Abstractions
-> OData -> Abstractions
-> OData.FO -> OData -> Abstractions
| Project | Role | Depends on |
|---|---|---|
IntegratoR.Abstractions |
Domain interfaces (IService<T>, ICommand<T>, IQuery<T>), the non-generic BaseEntity, CQRS contracts, Result<T> types (IntegrationError, ErrorType), and both Result<T> JSON converter families |
— (core) |
IntegratoR.Application |
MediatR pipeline behaviours, generic command/query handlers, OAuthAuthenticator, cache services |
Abstractions |
IntegratoR.OData |
Generic OData client, ODataService<T>, auth handler, Polly policies, ODataFieldAttribute, the LINQ→$filter translator |
Abstractions |
IntegratoR.OData.FO |
D365 F&O entities (LedgerJournalHeader/Line), dimension queries, feature handlers, FOSettings
|
OData |
IntegratoR.Hosting |
IntegratoRBuilder and the single AddIntegratoR composition root |
Application, OData, OData.FO |
IntegratoR.SampleFunction |
Isolated-worker Functions host — the consumer-side composition root and smoke triggers | Hosting (not published) |
IntegratoR.TestKit |
Shared test infrastructure: Result<T> assertions, fakes, entity builders |
test-only |
Note
AddApplicationServices, AddODataClient, and AddODataClientFOProxy are internal composition steps, not consumer API. Call AddIntegratoR — it is the only public entry point, and it invokes the three in order (see below).
An entity inherits BaseEntity and overrides object[] GetCompositeKey(), returning key-field values in a fixed order. D365 keys are composite — typically DataAreaId plus a business key.
[Table("LedgerJournalHeaders")]
public class LedgerJournalHeader : BaseEntity
{
[JsonPropertyName("dataAreaId")]
public required string DataAreaId { get; set; }
[ODataField(IgnoreOnCreate = true)] // server-assigned
public string? JournalBatchNumber { get; set; }
[ODataField(IgnoreOnUpdate = true)] // read-only on update in D365
public required string JournalName { get; set; }
public required string Description { get; set; }
public override object[] GetCompositeKey() => [DataAreaId, JournalBatchNumber!];
}The generic BaseEntity<TKey> is [Obsolete] since v2.0.0 (the type parameter was never used); removal is planned for a future major version, v4 at the earliest. Never use it. See Define Entities for the full [ODataField]/[JsonPropertyName] matrix.
Commands and queries are record types implementing ICommand<TResponse> or IQuery<TResponse>. A consumer never calls ODataService<T> directly — it sends a command or query and reads back a Result<T>.
LedgerJournalHeader header = new()
{
DataAreaId = "USMF",
JournalName = "GenJrn",
Description = "April accruals",
};
Result<LedgerJournalHeader> result =
await mediator.Send(new CreateCommand<LedgerJournalHeader>(header), cancellationToken);
if (result.IsFailed)
{
IntegrationError? error = result.GetError();
// Code is "{EntityType}.{reason}" — e.g. "LedgerJournalHeader.Conflict" on an HTTP 409 (ErrorType.Conflict).
return;
}
string batchNumber = result.Value.JournalBatchNumber!; // server-assigned on createGeneric CreateCommand<T>/UpdateCommand<T>/DeleteCommand<T> and GetByKeyQuery<T>/GetByFilterQuery<T> work with any IEntity; entity-specific commands compose them only when they add real logging context. See Send Commands and Run Queries.
Every operation returns Result<T> (or non-generic Result) from FluentResults. Business failures return a failed Result carrying an IntegrationError { string Code; ErrorType Type; Exception? Exception }; they do not throw. ErrorType has four members: Failure, Validation, NotFound, Conflict.
ODataService<T> also absorbs infrastructure faults on single-entity operations — a timeout, cancellation, or unrecognised exception comes back as {Entity}.Timeout, {Entity}.Cancelled, or {Entity}.UnexpectedError. The batch path turns a failed chunk send — an HttpClient timeout included — into failed items with StatusCode 0; only your own cancellation propagates. The full list of what still throws is in Handle Errors.
Read failures with result.IsFailed and result.GetError() — never try/catch on the pipeline, never the verbose result.Errors.FirstOrDefault() form. See Handle Errors.
AddApplicationServices registers three MediatR behaviours in one order, and the order is load-bearing.
-
LoggingBehaviour— records request type, duration, andIContext.GetLoggingContext(), and detects a failedResult<T>returned by an inner stage. -
ValidationBehaviour— runs everyIValidator<TRequest>and short-circuits on the first failure withIntegrationError("Validation.Error", …, Validation). -
CachingBehaviour— acts only onICacheableQuery<TResponse>; a hit short-circuits, a miss runs the handler and caches a successful response. -
Handler — the closed generic
CreateCommandHandler<T>/GetByKeyQueryHandler<T>or a consumer handler.
Caution
The order is deliberate. Validation before caching stops an invalid request from ever producing a cache entry; caching before the handler stops a valid cache hit from re-running work. Custom behaviours registered via AddTransient(typeof(IPipelineBehavior<,>), …) run after these three, between caching and the handler. See Extend the Pipeline.
Because LoggingBehaviour inspects the returned Result<T> rather than only catching exceptions, a handler that returns Result.Fail(...) is logged as a failure — a failed Result is never silently logged as success.
The codebase runs both System.Text.Json and Newtonsoft.Json, and Result<T> needs converters in both. Both families delegate to one shared shape helper, ResultJsonShape, so the wire format never drifts.
| Serialiser | Used by | Wiring |
|---|---|---|
| System.Text.Json | Durable Functions data converter, DistributedCacheService
|
Auto — AddIntegratoR wires DurableTaskWorkerOptions.DataConverter; the cache service registers converters in its own static options. Consumers do nothing. |
| Newtonsoft.Json | HTTP trigger payloads, journal-file parsing |
Manual — a JsonConvert.DefaultSettings block in the host Program.cs. |
Note
ResultJsonShape.Project accepts any IError, falling back to (Unknown, message, Failure) for a plain Result.Fail("message"). That leniency is intentional public-API behaviour — external consumers may pass non-IntegrationError results. See Set Up Azure Functions Host for the Newtonsoft snippet.
D365 F&O entities are composite-keyed, and PanoramicData's Key(object) cannot bind a dictionary key — it calls .ToString() on the dictionary and emits a malformed URL. So single-entity Update and Delete route through an owned raw-HttpClient bypass in ODataClientAdapter (since v2.0.0). It builds the keyed URL by hand — LedgerJournalHeaders(dataAreaId='USMF',JournalBatchNumber='B0001') — using the [JsonPropertyName] wire names, and issues the request through the named "ODataClient" client so the write carries the same authentication, Polly resilience, and BaseAddress as every other call. Reads use a parallel $filter bypass over the same key fields.
Note
D365 returns 204 No Content on a composite-key PATCH. UpdateAsync treats that as success and returns the caller's entity, so a successful Result<TEntity> never carries a null Value.
Warning
A single field marked [ODataField(IgnoreOnUpdate = true)] present in an update payload makes D365 reject the whole PATCH with HTTP 403 (ODataSecurityException), not only that field. On LedgerJournalHeader that set is JournalName, AccountingCurrency, IsPosted, JournalTotalDebit, and JournalTotalCredit. Audit every field against D365's update semantics before shipping an entity.
No batch write uses PanoramicData either (since v3.0.0). Every chunk goes through the same named client in one of two shapes, chosen by BatchFailureMode:
| Mode | Wire shape per chunk |
|---|---|
Atomic (default) |
One hand-rolled multipart $batch POST carrying a single changeset — all-or-nothing per chunk |
ContinueOnError |
One POST / PATCH / DELETE per item, failures collected |
ODataService splits the input at ODataSettings.Batch.MaxOperationsPerChunk and aggregates every chunk's per-item results into one BatchOutcome. Key values and the entity-set name are spliced into the $batch body as text, so a key value containing a control character, or an entity-set name that is not a plain OData identifier, is rejected before anything is sent. The batch write path is unit- and integration-tested but not yet verified against a live D365 environment.
AddIntegratoR(configuration, configure) runs these steps, and ODataSettingsValidator : IValidateOptions<ODataSettings> (auto-registered, with ValidateOnStart) fails the host at start-up on invalid auth settings or an out-of-range batch chunk size (1–200) rather than at first request.
-
AddApplicationServices()— pipeline behaviours, MediatR, cache, OAuth authenticator. -
AddODataClient(configuration)— HTTP client, Polly policies,ODataService<T>,ODataSettingsValidator. -
AddODataClientFOProxy(configuration)— F&O handlers and entity bindings. - A combined MediatR scan (Application + F&O + every assembly from
AddConsumerHandlers) that closes the open-generic CRUD handlers against F&O and consumer entity types together. - The Durable Functions
Result<T>converter onDurableTaskWorkerOptions(lazy — zero cost for non-Durable consumers). - Closing and registering the open-generic and consumer validators so
ValidationBehaviourresolves them.
Step 4 exists because MediatR v12 closes open generics only within a single scanned assembly, and step 6 exists because FluentValidation's scanner skips open generics. Both cross-assembly closures happen once, here — a consumer's extended entities get closed generic handlers and validators exactly like the framework's own. The rationale lives in ADR-0001; the Durable wiring in ADR-0002; the [JsonPropertyName]-aware translator fork in ADR-0003; the configurable, chunked $batch write path in ADR-0004.
Get Started
Use Cases
- Handle Errors
- Configure Resilience
- Add Validation
- Cache Query Results
- Work with Dimensions
- Run Smoke Tests
- Extend the Pipeline
- Test with TestKit
Reference