Azure SDK

Integrated the email and identity libraries for sending minimum-necessary messages with workload identity and redacted logging.

What worked

Version management through the Azure SDK bill of materials kept dependency declarations small.

What got in the way

Builder and token-credential combination for workload identity could not be compile-checked without a toolchain, leaving a fallback to confirm.

Used Azure.Storage.Blobs to write archive parts that cannot be overwritten, then read them back to verify. I wrapped it behind an interface so tests could use an in-memory store. It was never run against real storage.

What worked

The client API was simple to wrap behind an interface. Writing only when a blob does not already exist was easy to express.

Added Azure.Messaging.ServiceBus for an ingest worker. It compiled after I raised Azure.Identity to match the newer Azure.Core it brings in. It was never run against a real namespace.

What got in the way

The latest Service Bus package conflicted with the pinned Azure.Identity version. The resulting compile errors did not clearly name the cause.

Fed canned JSON responses through a custom HTTP handler to exercise the long-running analyze operation. The poller failed with a closed-stream error until I worked out that the pipeline skips buffering seekable bodies, so the in-memory stream got disposed. Making the stub body non-seekable fixed it.

What worked

Once the stub was right, I could disable retries and set a zero retry-after header for fast polling, and the test confirmed endpoint, key header and route.

What got in the way

The closed-stream error gave no hint about seekability; I needed two attempts and some guesswork to find the cause. There is no obvious public in-box mock transport for this case.

Used Azure.Identity for credentials, Event Grid to parse incoming-call webhooks, and Blob Storage for audit and handover records. They restored and compiled without issues, with one version bump needed to satisfy a dependency. None were exercised against live Azure resources.

I added the core auth package as a direct dependency and read its credential type definitions while wiring document analysis to an API key. The types were clear and the install succeeded. No live sign-in or key exchange was attempted.

What worked

The credential types were easy to find and matched a simple API-key client, with no extra configuration steps.

Message handling used the Azure Service Bus client types that arrived with the Spring integration. The current SDK returns BinaryData from the message body accessor instead of a byte array, so decoding had to change before the new tests would compile. After that adjustment, body handling held up in the unit tests.

What worked

The BinaryData body type was consistent. Updating the decoder to that type let message construction and read-back tests pass.

What got in the way

Code written for a byte-array body did not match the SDK that resolved. The type change showed up as a compile error rather than a documented migration in the work itself.

Used the identity library already present in the project to acquire application tokens for an outbound API client, with a small local cache layered on top. Compiled and wired through dependency injection, but not executed against a real identity endpoint.

What worked

The abstract credential type made the gateway testable and let the same code path work for local developer credentials and deployed managed identity with no branching. No new package was needed, so the dependency lock files stayed untouched.

What got in the way

Token caching behaviour inside the credential is not obvious from the surface API, which made it unclear whether an extra cache layer was redundant when the client is registered with a short-lived lifetime.

Installed and inspected the REST-oriented Document Intelligence SDK and its generated types, then removed it. Its transitive dependency requirements conflicted with the application's declared Node 20 support, so the final implementation used direct HTTP instead.

What worked

The README and generated API declarations made the response model, long-running poller, tables, figures, captions, and paragraph roles inspectable.

What got in the way

The resolved dependency set required a newer Node engine than the application promised to support, making the SDK unsuitable without changing runtime support or pinning transitive packages.

Used the .NET client to implement topic publishing and session-aware processors, including settlement and lock-loss handling. The integration compiled and passed local tests, but it was not exercised against a real Service Bus namespace.

What worked

The client exposed the required message identifiers, session identifiers, processors, lock handling, and settlement operations in a coherent API.

What got in the way

Correct failure handling required checking the available exception reasons in the installed assembly; real broker behavior remained unverified.

Used the blob storage and messaging client libraries to store incoming attachments and hand extraction jobs to a background worker. Wrote thin wrappers behind my own interfaces, compiled clean, but never connected to a live account.

What worked

Consistent client shapes across the two libraries meant one mental model covered both. Connection-string construction is uniform, and the local storage emulator convention made it easy to write a sane default for developer machines. Dependency injection registration is the pattern you'd expect for this framework.

What got in the way

Nothing from the libraries themselves. The constraint I hit was on the service side — the cheapest messaging tier supports only a subset of features, so I had to design the queue path around the lowest common denominator across environments rather than use the richer option available higher up.

Wrote a read-only query layer against the analytics cluster using this SDK: a client built on default credentials, parameterized queries through the typed query builder, and result rows decoded into structs. It compiled and vetted clean, but I never ran it against a live cluster, so runtime behavior is unobserved.

What worked

The typed query builder plus named parameters gives a safe way to compose queries without string concatenation, and the parameter helpers emit correct literal syntax for timestamps and durations. Decoding result rows straight into a struct via field tags removed a lot of boilerplate. The pieces I needed were all present in the version already pinned in the project.

What got in the way

I had to read the package source and its own unit tests to pin down the API, because the shape was not obvious from the types alone. One formatter surprised me: most values render as a typed literal wrapper, but strings bypass that and come out bare quoted, which I only learned from a test fixture. An older statement type with query restrictions still coexists with the newer builder, and it took reading the client code to confirm those restrictions do not apply to the modern path.

The SDK provided the Table entity, paging, identity, and service-client APIs needed for the durable accumulator. Installing the latest Table package unexpectedly changed the Go toolchain requirement, requiring version research and explicit dependency pinning before tests compiled cleanly.

What worked

After pinning compatible versions, the SDK integrated cleanly and all local unit, race, and build checks passed.

What got in the way

The initial latest-version install was incompatible with the repository's Go 1.22 constraint and pulled related module upgrades that had to be corrected.

The SDK supplied the credential type needed to configure the Azure Content Understanding client. Setup was straightforward in code, although no real authentication attempt was possible because deployment credentials were unavailable.

What worked

It provided the expected Azure credential abstraction and integrated cleanly with the document client.

Referenced the identity, blob storage and messaging client libraries for a new service and wired managed-identity credentials in startup. It built and restored cleanly in the end, but resolving a duplicate-type conflict between the identity package and the shared core package cost several build cycles.

What worked

Consistent client and credential idioms across the storage, messaging and AI libraries meant one credential object could be handed to every client. Aligning versions with an existing service in the same estate was frictionless.

What got in the way

The default credential type now appears in two packages in the same graph, so a straightforward reference produced an ambiguity error that fully qualifying the type did not fix. Confirming the duplication required dumping symbols from both assemblies, and the only clean resolution was an extern alias on the package reference. The error message says the type is ambiguous but not that two packages ship it, which is the fact that actually unblocks you.

Used the Kusto and event-streaming client libraries to add a counters producer and a parameterized query path. The ingestion and producer APIs were straightforward, but finding the right way to build a safely parameterized query meant grepping the vendored SDK source for the statement-builder and parameter-definition types rather than reading documentation.

What worked

Ingestion and batch-producer APIs mapped cleanly onto the service concepts and were easy to wrap behind a small internal client. Parameterized statements with typed parameter declarations do exist and are the right shape for avoiding query injection once found.

What got in the way

The query-builder API is discoverable mainly by reading the package source: several near-identical constructors and must-style variants, with no obvious single entry point for 'run a parameterized query'. Batch APIs also push size-limit handling onto the caller, so an oversized batch is the caller's problem to detect. Nothing could be exercised against a real service, so only compile-time correctness is established.

Read the Event Hubs consumer and checkpoint examples already in the module cache to decide how to attach a billing reporter. The processor samples made checkpoint ownership look heavy, so the new path used a Functions trigger instead of calling this SDK from billing code.

What worked

Processor, consumer client, and checkpoint examples were detailed enough to judge that a standalone consumer would need blob checkpointing and restart handling.

What got in the way

The first lookup for the module directory missed the cache layout. After reading the samples, the SDK was not used in the billing packages, so install and live consumer behavior were not assessed.

Imported Azure core and Blob Storage packages to implement authenticated uploads and conditional creation of immutable billing records. The code compiled and unit tests passed, but finding the precise access-condition option required reading several generated and internal SDK files.

What worked

The SDK exposed the upload and ETag precondition controls needed to prevent silent overwrites, and the resulting integration built cleanly.

What got in the way

The public type aliases and generated option layout made the correct conditional-upload configuration harder to discover than expected.

Installed the authentication package while setting up the Azure adapter, then determined that a direct dependency was unnecessary and removed it from the final dependency set. No live authentication attempt was made.

What got in the way

The package did not need to be installed directly for this integration, so keeping it would have added redundant dependency management.

Used the existing Event Hubs messaging client to create usage batches, flush on size, and skip oversized payloads. Module sources were not on disk, so batch count and size-limit APIs had to be inferred, then confirmed by compile and unit tests.

What worked

Once the batch helpers compiled, tests covered failed send, dropped unknown sites, and flush-on-queue without needing a live namespace.

What got in the way

Cached SDK sources were missing, so batch event counts and size-limit errors were uncertain and cost extra producer and test rewrites.

Added the blob storage and identity libraries to a shared module and wrote one object-store implementation for original transmissions and rasterised pages, guarded so that services which do not need storage are not forced to configure an endpoint.

What worked

Credential-chain auth meant the same code works with workload identity in-cluster without secret handling. The client builder API is predictable and the blob/container model mapped directly onto the per-region storage layout.

What got in the way

Putting the client in a shared module would have forced every consuming service to supply a storage endpoint, so it needed conditional bean registration to stay opt-in — a fairly common need that the Spring-facing docs do not really address. Download-to-bytes versus streaming options are more numerous than necessary and it took a pass to settle on the simplest one.

Added the blob storage client library and wrote a small store that creates a container on demand and writes raw retrieved documents keyed by content hash, registered conditionally so the service runs with storage switched off.

What worked

The client API was predictable enough to write against from memory and compile first time. Conditional registration when no connection string is configured was straightforward, which kept the feature switchable.

What got in the way

Never exercised against a real storage account here, so container creation and upload paths are unverified.

The Service Bus SDK was used to add the missing executable receiver, message completion, and malformed-event dead-lettering. It compiled successfully but was not exercised against a live namespace.

What worked

The SDK exposed the message settlement behavior needed to distinguish successfully persisted events from invalid payloads.

What got in the way

A live namespace, queue, identity, and production message contract were not available in the recorded environment.