Webority.Azure.DataProtection 0.8.0

Webority.Azure

Shared Azure infrastructure for the Webority product fleet — one canonical, optimized implementation of the Azure plumbing every product used to hand-copy (and drift on).

Package IDs stay Webority.Azure.* for a tidy nuget.org grouping, but the C# namespaces are deliberately Webority.AzureStorage / Webority.AzureTelemetry / Webority.AzureDataProtection / Webority.AzureNotificationHubs — not Webority.Azure.*. A Webority.Azure.* namespace would shadow the Azure SDK's own Azure root namespace for any consumer code living under a Webority.* namespace, since C# walks enclosing namespaces and finds Webority.Azure before it ever reaches global Azure.Core/Azure.Identity.

Auth model (Storage)

One options contract, two modes — set exactly one:

• Azure:Storage:StorageAccountName → Entra / managed identity via a narrowed DefaultAzureCredential chain (ManagedIdentity in Azure, Azure CLI locally — nothing else, so no slow credential probing on constrained plans). One cached credential per process.
• Azure:Storage:ConnectionString → shared key (the local-development default: developers without Azure access use the staging account's connection string).

Conventions

• All services register as singletons (Azure SDK clients own their transport and are built for process-wide reuse — see dotnet.md, HttpClient/SDK-client rule).
• Options are validated on start (ValidateDataAnnotations().ValidateOnStart()); a misconfigured host crashes at boot, never at first request. AddWeborityTelemetry is the one that validates earlier still, at registration, because it consumes its own values while wiring the exporter and the span processor, so a startup check would run after the wiring it protects.
• Public type names match the pre-extraction fleet implementations (IAzureStorageBlobService, …), so migrating a product is a using swap plus deleting its local copy.

Telemetry collection policy

AddWeborityTelemetry's fleet defaults implement one rule: collect only what is consumed. Application Insights ingestion is billed, and near nobody looks at the Metrics blade or a complete log of every successful outbound call — so none of that ships to Azure Monitor unless a head opts in.

• No metrics export by default (EnableMetrics = false). This suppresses the distro's standard-metrics/performance-counter pipeline (AzureMonitorOptions.EnableStandardMetrics / EnablePerformanceCounters, both true by default upstream) and the ASP.NET Core/HttpClient runtime meters UseAzureMonitor wires in on .NET 8+, via a catch-all dropping view. Set EnableMetrics = true to restore metrics fleet-wide; DroppedMetrics then trims just the known-noisy subset instead of everything.

• Failed-only spans, sampled successes. Failed spans (Status == Error, or any span carrying a recorded exception event) are always kept, and so is any span answering an HTTP status of 400 or above. ASP.NET Core leaves a 4xx at Unset by semantic convention, so without that rule a refusal a caller saw was sampled like a success and three in four never arrived, and a 5xx recorded by instrumentation that sets no span status went the same way. Successful dependency/client spans are always dropped. Successful server/request spans are kept with probability SuccessfulRequestSamplingRatio (default 0.25), decided deterministically per trace so every span belonging to one trace agrees.

• "Always kept" is literal, because head sampling is switched off. A head sampler decides at span start, before a status code, a response or an exception exists, so it cannot tell a failure from a success and nothing downstream can bring back a trace it dropped. The package therefore pins the exporter to always-on (SamplingRatio to 1.0 and TracesPerSecond to null, both needed because the distro defaults the second to 5.0 and lets it win) and makes every trim after the span ends, where the status is known. SuccessfulRequestSamplingRatio is the one ratio the package has.

  • The cost, stated plainly. Every span is created and fully recorded before it can be judged, which is CPU and allocation a head sampler would have saved. Application Insights also stops extrapolating counts: the exporter stamps one sample rate on every item, taken from its own head ratio, and reads no per-span rate, so successful request counts read as the kept fraction while failure counts are exact. Read a fall in successful request volume after upgrading as this, not as lost traffic.
  • The one hole the package cannot close: do not set OTEL_TRACES_SAMPLER or OTEL_TRACES_SAMPLER_ARG on a Webority head. The exporter reads both from the environment and either one installs a head sampler underneath the package, which puts back exactly the trace loss the pin above removes, silently and with no signal in the app's own config. Nothing in the fleet sets them today.
  • The second hole, and it is not closable here either: the trim is not scoped to Azure Monitor. A span is dropped by clearing its Recorded flag, which every exporter in the pipeline reads, so a head that chains its own exporter onto the returned builder loses exactly the same spans, silently. OpenTelemetry has no per-exporter filter and the Azure Monitor distribution exposes no hook for a processor inside its own pipeline. A head that needs the complete span stream somewhere else should give that exporter its own provider rather than chaining it here.

• Opt-in keeps for successful spans (both off by default, so a head that sets neither sees no change). AlwaysKeepSources lists ActivitySource names whose spans are always kept, and SlowDependencyThresholdMs keeps a successful client or internal span lasting at least that many milliseconds (1 to 600000). A configured AlwaysKeepSources array replaces the default empty list. Each kept span is billed ingestion, so list only sources someone reads and set the threshold above normal latency.

  "WeborityTelemetry": {
    "AlwaysKeepSources": [ "Experimental.Microsoft.Agents.AI", "Experimental.Microsoft.Extensions.AI" ],
    "SlowDependencyThresholdMs": 500
  }
  

• Log export floors at Warning (MinimumLogExportLevel). This filters only what OpenTelemetryLoggerProvider forwards to Azure Monitor — a head's own ILogger calls, and any other registered provider (console, debug, ...), are unaffected.

These are all options on WeborityTelemetryOptions, overridable per head via the configure delegate or the WeborityTelemetry configuration section — this is the fleet default, not a hard rule.

The distro's own AzureMonitor configuration section is not a supported surface here. The package calls the UseAzureMonitor(Action<AzureMonitorOptions>) overload, and only the parameterless overload registers the internal options type that reads that section, so a head putting an AzureMonitor block in its appsettings finds it silently inert. That is deliberate rather than an oversight: the section carries SamplingRatio and TracesPerSecond, so honouring it would hand a head back the head sampler this package pins off. Configure the exporter through the configure delegate.

Telemetry for Functions hosts

An Azure Functions isolated-worker host calls AddWeborityFunctionsTelemetry from Webority.Azure.Telemetry.Functions instead of AddWeborityTelemetry, with the same arguments and the same environment gate:

using Webority.AzureTelemetry.Functions;

if (!environment.IsDevelopment())
{
    services.AddWeborityFunctionsTelemetry(configuration);
}

It does everything AddWeborityTelemetry does, then sets the worker capability WorkerApplicationInsightsLoggingEnabled. That tells the Functions host the worker exports its own logs, so the host stops exporting them a second time as Function.<Name>.User rows. ConfigureFunctionsApplicationInsights sets the same capability but needs the classic Application Insights SDK, which is why it cannot be used here.

• The capability follows WeborityTelemetry:Enabled. A host that switches telemetry off keeps the Functions host's own log export, rather than losing both.
• It returns the same builder, so a host adds its own processors by chaining: .WithTracing(tracing => tracing.AddProcessor<MyProcessor>()). The collection policy above, including the warning about chaining a second exporter, applies unchanged.
• Reference the package directly from the Functions project. The isolated worker drops packages that arrive only transitively from its deployed closure, so check that Webority.Azure.Telemetry.Functions.dll is listed in the published *.deps.json.

Upgrading

0.6.0

• Breaking on 0.x, implementers only: the user and all-installations sends return a PushSendResult. SendNotificationToUserInstallationsAsync and SendNotificationToAllInstallationsAsync return Task<PushSendResult> instead of Task, and the interface gains GetSendOutcomeAsync. A caller that only awaits the send compiles unchanged. A class implementing IAzureNotificationHubsService, a test double above all, must return a result (new PushSendResult([]) will do) and implement the lookup.
• A send never says whether anybody was reached. The push service answers a send before it has matched a device, so every platform in the result reads Enqueued, even for a user with no device. NoTargetFound and the per-device counts come from GetSendOutcomeAsync(notificationId) later, and only on the Standard tier; the Free and Basic tiers return no notification id and refuse the lookup.

0.5.1

No call site changes. What a head records does change, which a workbook or alert counting rows will see: dependencies that answered an expected 4xx stop appearing, and successful requests a portal started appear at the configured ratio where they appeared at none (or all) before.

0.5.0

The changelog carries every entry; these are the ones that change a call site or need an action before deploying.

• SlidingExpiration now works, and the refusal shipped in 0.3.0 is gone. A sliding window is stored with the row and every read pushes the expiry forward; an absolute expiry beside it still wins whenever it falls earlier. A head calling AddSession() against this cache no longer fails on every session-touching request. Refresh and RefreshAsync stopped being no-ops, so a read-only request now keeps a session alive. A sliding read costs one extra write, skipped when the row is already at its absolute cap.
• Breaking on 0.x: IAzureStorageTableService's writes take a TableCacheExpiry, not an int of seconds. SetAsync(..., 60) becomes SetAsync(..., TableCacheExpiry.After(TimeSpan.FromSeconds(60))), and the interface gains RefreshAsync / RefreshValue. Anything implementing the interface itself, a hand-written test double above all, will not compile until it follows.
• Breaking on 0.x: the push contract speaks in our own types. IAzureNotificationHubsService no longer names Microsoft.Azure.NotificationHubs.Installation or NotificationPlatform, so a product registering a device stops compiling against the provider's package. NotificationPlatform.FcmV1 and NotificationPlatform.Apns become DevicePushPlatform.FcmV1 and DevicePushPlatform.Apns; GetInstallationAsync returns a DeviceInstallation, where PushChannel is now PushToken. Every call site gets a compile error. A device found on a platform this package does not send to is refused by name, and so is registering with DevicePushPlatform.None, which is what an unset value reads as.
• Breaking on 0.x: SendNotificationToAllInstallationsWithTagsAsync is now SendNotificationToTagsAsync and returns a result. The rename is deliberate: the return type change alone would have compiled everywhere while silently removing the exception callers relied on for failure. Check result.AllDelivered, or walk result.Failures for the tags to retry. A send to an empty tag list makes no request and reports no batches; use SendNotificationToAllInstallationsAsync to reach everyone.
• A user id the push service cannot hold in a tag is now refused, where it used to fail silently. Tags are checked against the service's own rule, at most 120 characters of letters, digits and _ @ # . : -, before any request. A product whose user identifier can contain a space, a slash or an accented letter must hash or encode it before registering: those devices were registering without a usable tag and receiving nothing. Check this one before upgrading if your user identifier is anything other than a number or a GUID.
• Breaking on 0.x: an empty or blank queue message raises ArgumentException, not ArgumentNullException. A whitespace-only body used to reach the queue.

0.4.0

• Breaking on 0.x: DequeueMessageAsync returns a QueueMessageReceipt, not a string. It no longer deletes the message, so a handler that throws leaves the work to be retried instead of losing it. Read .MessageText, and call CompleteMessageAsync(receipt.MessageId, receipt.PopReceipt) once the work has committed. .DequeueCount is there so a caller can move a message aside as poison after too many attempts. Every call site gets a compile error.
• Breaking on 0.x: data protection refuses to keep keys inside the process by accident. With neither Azure:Storage:StorageAccountName nor Azure:Storage:ConnectionString configured, AddWeborityDataProtectionBlobKeys now throws unless the caller passes allowInProcessKeys: true. Local development says so out loud; a deployed head that had silently lost its storage settings fails at startup naming them instead of signing every user out on each restart.
• The data protection key-ring container is a provisioning prerequisite. Nothing creates it, and neither does the underlying blobs package, so the container (dataprotection by default, private access) must exist on a freshly provisioned storage account before the first request that protects a cookie or an antiforgery token. Note the asymmetry with the storage package, which does create-on-write for blobs.
• Breaking on 0.x: telemetry enabled with no Application Insights connection string is refused. It used to wire no exporter and say nothing, so a production head with a missing connection string ran dark. Keep the !env.IsDevelopment() gate around the call, set the connection string, or set WeborityTelemetry:Enabled to false deliberately.
• Breaking on 0.x: SuccessfulRequestSamplingRatio must be between 0.0 and 1.0. Nothing validated it before, so 25 (meaning 25 per cent) kept every successful request and -1 dropped them all. Correct any head whose configured value is a percentage: 25 becomes 0.25.
• Breaking on 0.x: an Azure:Storage section with neither credential fails at boot. The check lived only in each service's constructor, and all three are lazily resolved singletons, so a head deployed without the section passed its health check and failed on the first upload.
• Breaking on 0.x: table cache rows whose keys contain /, \, #, ? or % are rewritten once. The key transform mapped four characters onto one replacement, so two different cache keys could land on the same row and one caller read back another's value. Every rejected character is percent-escaped now, which makes the transform reversible. Keys without those characters are untouched; a key with one misses once and is written again, the same argument the expiry-column rename used. Nothing serves a stale value.
• Breaking on 0.x: a push to a device on a platform the package cannot build a payload for now throws. WNS, MPNS, legacy FCM, ADM and Baidu used to complete with nothing sent. A legacy FCM installation is pointed at MigrateFcmToFcmV1Async.
• Breaking on 0.x, interface only: IAzureNotificationHubsService.GetInstallationAsync takes a CancellationToken, and a visible push notification must carry a title. Blank text, action, title, user id, installation id or push token now raise ArgumentException naming the parameter rather than ArgumentNullException or a bare InvalidOperationException.
• A blob SAS is capped at seven days under managed identity, because it cannot outlive its user delegation key. A longer request is refused naming the limit instead of answering an opaque 400.
• A container or queue deleted under a running process is recreated rather than failing every later write for the life of the process, matching what the table service already did.
• The packages now carry an MIT licence.

Earlier releases

• Breaking on 0.x: WeborityTelemetry:SamplingRatio is retired, and a configuration that still carries it is refused at startup. It set the exporter's head sampler, which decides at span start and so dropped failed requests, 4xx refusals and unhandled exceptions at the same rate as successes: the keep-every-failure rules beside it could only ever trim what it had already let through. Head sampling is pinned to always-on now, and SuccessfulRequestSamplingRatio (default 0.25) is the one ratio, applied to successful requests only. Remove the key from each head's appsettings, and move its value to SuccessfulRequestSamplingRatio only if that head really wants a different success ratio. The refusal is deliberate: binding would ignore the key silently and leave a head reading its own config as a decision nothing applies. It fires before the Enabled check as well, so a head that has switched telemetry off is told about the stale key too, rather than finding out the first time it switches telemetry back on.

• The distro's rate-limited head sampler is switched off too. AzureMonitorOptions.TracesPerSecond defaults to 5.0 and takes precedence over SamplingRatio, so a busy head was capped at five traces a second whatever ratio it set, with failures discarded above that line. The package sets it to null.

• Expect more Warning-and-above logs to reach Azure Monitor, not just more traces. The distro's trace-based logs sampler is on by default and exports a log record only when its trace was sampled, so while the rate limiter was capping traces it was quietly suppressing those logs too. With head sampling pinned always-on, every record at or above MinimumLogExportLevel now exports. That is the intended direction, and on a busy head it is a real rise in billed ingestion: check the component's daily cap before upgrading.

• A 5xx with no span status is kept like a 4xx. The rule read 400 to 499; it reads 400 and above now, so a server error recorded by instrumentation that leaves the span status Unset is no longer sampled like a success.

• Breaking on 0.x: SlidingExpiration is refused instead of silently written as a fixed window. A row carries one absolute expiry and a read cannot extend it, so an entry asked to slide never slid: the caller asked for one thing and got another, with nothing said. Set and SetAsync now throw ArgumentException whenever SlidingExpiration is set, including when an absolute window sits beside it. Use AbsoluteExpirationRelativeToNow and write the entry again when it should live longer. A head calling AddSession() against this cache is the one to check before upgrading: DistributedSession sets SlidingExpiration on every commit.

• A cache entry shorter than a second is written with a one-second life, not a zero-second one. The relative and sliding branches truncated the window to whole seconds, so anything under a second became a row that had already expired when it was written and every later read missed. The absolute branch already floored at one second; all of them do now.

• The cache table has one default name, DistributedCache. The option's own default said PermissionCache while the cache fell back to DistributedCache when no Table section was configured, so adding "Table": {} to a head's config moved the whole cache to another table and emptied it. The surviving value is the one an unconfigured head already resolves, so nothing in a deployed head changes. A head that configured Azure:Storage:Table:CacheTableName explicitly is unaffected either way; one that relied on the option default while binding an empty section will now read the table it was already writing to.

• A table dropped after the first write is recreated instead of failing forever. The service remembers that it created a table so it stops paying for a create on every write, and that memory outlived the table: drop it by hand, from a cleanup job, or between deployments, and every later write failed for the life of the process. A 404 from a write now forgets the table, creates it and retries once. The failed first attempt is still reported as a failure, because a table disappearing under a running head is worth seeing.

• Table cache rows written by an earlier version are treated as expired and rewritten. The cache stores its TTL in ExpiresDateTimeUtc (previously ExpiresAtUtc) and its write time in CachedDateTimeUtc (previously CachedAtUtc). A row whose expiry cannot be read — column absent, null, or unparseable — is a miss, never a never-expiring hit, so pre-existing rows simply miss once and are rewritten. No action needed, and no dual-read shim: reading both names would restore exactly the ambiguity that let a stale short-TTL entry validate forever.

• A table cache miss is quiet. The cache reads with the not-found-tolerant overload, so a missing row no longer throws inside the SDK, logs an error trace, or exports as a failed dependency. Products that count failed dependencies will see the revocation-check misses disappear from that stream. Writes are unchanged.

• A table cache delete of a row that is already gone is quiet too. The SDK never threw on that 404, so the catch around the delete was doing nothing, but the request still carried no response classifier and the pipeline called every such delete a failure. A per-call policy now classifies 204 and 404 as the success pair for a DELETE, so a sign out racing a TTL, a second instance evicting the same key, or a replayed webhook stops producing an error trace and a failed dependency. A delete that fails for any other reason still throws.

• Breaking on 0.x: IAzureStorageTableService gained three synchronous members, GetValue, SetValue and RemoveValue. AzureTableDistributedCache needs them because IDistributedCache has a synchronous half, and its synchronous members used to block on the asynchronous ones, parking a thread pool thread for each round trip. Consuming products need no change; anything that implements the interface itself, a hand-written test double above all, will not compile until it adds the three.

• A missing blob is quiet on the three read paths; a missing container is now loud. GetAsync, OpenReadAsync and GetStagedBlockIdsAsync already answered a missing blob with null or an empty list, but the pipeline underneath called the 404 a failure, so each ordinary miss wrote an error event and exported a failed dependency. Reads now treat a 404 as a non-failure only when the service says BlobNotFound. The SDK still throws either way, because it decides that from the status code rather than from the classifier, so a missing blob behaves exactly as before.

• Breaking on 0.x: a read only absorbs BlobNotFound now, and throws on any other 404. A missing container answers 404 like a missing blob, and all three read paths used to absorb it and answer null or empty, so a typo in a container name was indistinguishable from an absent file. ContainerNotFound is misconfiguration, not a miss, and a 404 carrying any other code is a case the service does not understand, which is the one that must least become an empty result. Both are let out now, logged by the pipeline as the failures they are. A product that relied on a read of a non-existent container answering empty will start seeing RequestFailedException. Writes are untouched, and still create the container on first use.

• The existence check is the exception, by SDK design. ExistsAsync answers false for a missing container as well as a missing blob, because BlobBaseClient.ExistsAsync absorbs that 404 inside the SDK before our code sees it. The three read paths are the loud ones; do not read a false from the existence check as proof that the container is right.

• Blob containers are created on first write. SaveAsync and the block-staging paths create the resolved container (private, PublicAccessType.None) once per container name per process, matching the queue and table services. Products can drop their own create-if-missing call before every upload. Read paths still fail on a missing container, so a wrong container name surfaces instead of being silently created.

Releasing

Version lives once in Directory.Build.props (<VersionPrefix>), the fleet's standard version-of-record for a package repo. Push to main publishes all five packages to public nuget.org through the fleet's shared workflow (.github/workflows/publish.yml, a thin caller into Webority/gh-actions). No code checks run in CI; build and test locally before pushing (CLAUDE.md). Work happens on development; a release is a PR development → main merged with a merge commit, per the fleet git conventions.

version-check.yml gates that PR on two things, both failing the PR rather than warning:

1. Directory.Build.props <VersionPrefix> has increased against main. Without it the publish skips every package and exits green having shipped nothing.
2. The release paperwork names the new version. CHANGELOG.md must carry a heading for it and must no longer say ## [Unreleased], and README.md's Upgrading section must no longer say ### Unreleased. 0.4.0 shipped with that heading still in place above changes that had gone out, because nothing touched the file at release time and nothing checked it.

So cutting a release is three edits in one commit: the version, the changelog heading, and the Upgrading heading.