Introduce Async API counterparts for AE base class by cheenamalhotra · Pull Request #3673 · dotnet/SqlClient

cheenamalhotra · 2025-10-08T04:20:28Z

Summary

Introduces async API counterparts for the SqlColumnEncryptionKeyStoreProvider abstract base class (Always Encrypted). This enables custom key store providers to implement truly asynchronous key operations instead of being forced to block on synchronous calls during query execution.

Fixes #3672

Public API

Four new virtual methods added to SqlColumnEncryptionKeyStoreProvider:

public virtual Task<byte[]> DecryptColumnEncryptionKeyAsync(
    string masterKeyPath, string encryptionAlgorithm,
    byte[] encryptedColumnEncryptionKey,
    CancellationToken cancellationToken = default);

public virtual Task<byte[]> EncryptColumnEncryptionKeyAsync(
    string masterKeyPath, string encryptionAlgorithm,
    byte[] columnEncryptionKey,
    CancellationToken cancellationToken = default);

public virtual Task<byte[]> SignColumnMasterKeyMetadataAsync(
    string masterKeyPath, bool allowEnclaveComputations,
    CancellationToken cancellationToken = default);

public virtual Task<bool> VerifyColumnMasterKeyMetadataAsync(
    string masterKeyPath, bool allowEnclaveComputations,
    byte[] signature,
    CancellationToken cancellationToken = default);

Design Decisions

Single overload with CancellationToken = default — no separate convenience overloads
Default implementation wraps sync counterpart via Task.FromResult / Task.FromException so existing providers work without changes
Fatal exceptions are not caught — uses ADP.IsCatchableExceptionType(e) filter in catch blocks (consistent with runtime patterns for StackOverflowException, OutOfMemoryException, etc.)

Changes

File	Description
`src/.../SqlColumnEncryptionKeyStoreProvider.cs`	Implementation of 4 virtual async methods
`src/.../ref/Microsoft.Data.SqlClient.cs`	Reference assembly surface
`doc/snippets/.../SqlColumnEncryptionKeyStoreProvider.xml`	XML documentation
`specs/002-async-always-encrypted/spec.md`	Design specification
`tests/.../SqlColumnEncryptionKeyStoreProviderAsyncShould.cs`	16 unit tests

Testing

16 unit tests covering: default sync fallback, faulted task propagation, cancellation support, default parameter behavior
Builds clean on all target frameworks (net462, net8.0, net9.0)
No breaking changes — existing providers continue to work without modification

Checklist

Tests added
Public API changes documented (ref assembly + XML docs)
Design spec included
No breaking changes introduced

Copilot

Pull Request Overview

Adds asynchronous counterparts to key store provider APIs in SqlColumnEncryptionKeyStoreProvider to enable async implementations for Always Encrypted key operations.
Key changes:

Introduced async virtual methods (Decrypt/Encrypt column encryption key, Sign/Verify CMK metadata) that currently throw NotImplementedException.
Added corresponding XML documentation entries for the new async methods.
Minor wording adjustments in existing XML return documentation.

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.

File	Description
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlColumnEncryptionKeyStoreProvider.cs	Adds async virtual method stubs for encryption key and metadata operations.
doc/snippets/Microsoft.Data.SqlClient/SqlColumnEncryptionKeyStoreProvider.xml	Documents newly added async methods and adjusts some existing return descriptions.

paulmedynski

Asking for clarification on return types and synchronous implementation.

benrr101

For new APIs we should have some discussion on the signatures. Definitely won't be able to get this in before preview2.

github-actions · 2025-11-10T02:34:02Z

This pull request has been marked as stale due to inactivity for more than 30 days.

If you would like to keep this pull request open, please provide an update or respond to any comments. Otherwise, it will be closed automatically in 7 days.

cheenamalhotra · 2025-11-10T06:47:43Z

Wait, wait 🙈

github-actions · 2026-01-02T02:38:57Z

This pull request has been marked as stale due to inactivity for more than 30 days.

If you would like to keep this pull request open, please provide an update or respond to any comments. Otherwise, it will be closed automatically in 7 days.

cheenamalhotra · 2026-01-02T08:18:00Z

Stay

- Reorder XML doc elements to place <summary> before <param> tags - Improve masterKeyPath descriptions (provider-specific format examples) - Improve encryptionAlgorithm descriptions (include RSA_OAEP example) - Fix columnEncryptionKey param: 'The column encryption key to encrypt' - Remove 'digitally' and redundant sentence from Sign summary - Wrap long lines to ~100 chars throughout - Use <see cref> for NotImplementedException in Verify docs - Add #nullable enable/restore around new async APIs in ref assembly Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

- Split async methods into two overloads per .NET standard library pattern: virtual overload with explicit CancellationToken (overridable), and non-virtual convenience overload without it (passes CancellationToken.None) - Default implementation checks CancellationToken.IsCancellationRequested and returns Task.FromCanceled before invoking sync method - Move tests from FunctionalTests to UnitTests - Add 4 cancellation token tests validating cancelled task behavior - Update <returns> tags to use <see cref="T:System.Byte[]" /> - Update spec to reflect two-overload design decision Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

- Fix test namespace to Microsoft.Data.SqlClient.UnitTests.AlwaysEncrypted (matching existing convention in UnitTests project) - Improve allowEnclaveComputations param docs: explain that when true, the signature covers the enclave-enabled property for later verification - Improve signature param docs: clarify it's the byte array from SignColumnMasterKeyMetadata with provider-specific format - Add 'live token' tests validating non-cancelled token doesn't interfere with default implementation completion Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

The ref project inherits nullable context from Directory.Build.props, so adding #nullable enable/restore blocks caused 'throw null;' to emit CS8597 errors. Remove the directives to match the ref file convention. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

- Replace SemaphoreSlim pattern with MemoryCache.GetOrCreateAsync for IMemoryCache-backed caches (AKV provider) - Keep check-release-fetch-relock only for custom-cache sites - Remove superseded Decision 8, consolidate to 7 concise decisions - Convert requirements and entities to compact tables - Reduce from 448 to 298 lines Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

…d tests - Add XML <summary> documentation to every [Fact] method and test helpers - Add using Microsoft.Data.SqlClient for explicit namespace import - Add SignColumnMasterKeyMetadataAsync_NoCancellationOverload_ReturnsFaultedTask - Add VerifyColumnMasterKeyMetadataAsync_NoCancellationOverload_ReturnsFaultedTask - Organize tests into regions: fallback, faulted, cancellation, convenience Total: 16 tests passing Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Remove non-virtual convenience overloads. Each async method is now a single virtual method with 'CancellationToken cancellationToken = default' so callers can omit the token and derived classes override one method. - Remove 4 non-virtual NoCancellation overloads from implementation - Remove 4 NoCancellation entries from ref assembly - Remove 4 NoCancellation XML doc blocks - Update spec Decision 2 and FR-002 for single-overload pattern - Rename test region from 'Convenience overloads' to 'Default parameter' Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Fatal exceptions (OOM, StackOverflow, ThreadAbort, etc.) must not be wrapped in Task.FromException — they should propagate synchronously. Use the existing ADP.IsCatchableExceptionType guard in exception filters, matching the pattern used in SqlDataReader and throughout the repo. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

cheenamalhotra added this to the 7.0-preview2 milestone Oct 8, 2025

cheenamalhotra added this to SqlClient Board Oct 8, 2025

cheenamalhotra requested a review from a team as a code owner October 8, 2025 04:20

Copilot AI review requested due to automatic review settings October 8, 2025 04:20

github-project-automation Bot moved this to To triage in SqlClient Board Oct 8, 2025

cheenamalhotra mentioned this pull request Oct 8, 2025

Feature | Async friendly Always Encrypted support #3672

Open

10 tasks

Copilot AI reviewed Oct 8, 2025

View reviewed changes

edwardneal reviewed Oct 8, 2025

View reviewed changes

Comment thread ...Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlColumnEncryptionKeyStoreProvider.cs Outdated

paulmedynski self-assigned this Oct 8, 2025

paulmedynski reviewed Oct 8, 2025

View reviewed changes

benrr101 previously requested changes Oct 8, 2025

View reviewed changes

benrr101 modified the milestones: 7.0-preview2, 7.0.0 Oct 8, 2025

cheenamalhotra moved this from To triage to In progress in SqlClient Board Oct 8, 2025

cheenamalhotra moved this from In progress to In review in SqlClient Board Oct 8, 2025

cheenamalhotra modified the milestones: 7.0.0, 7.0.0-preview3 Oct 9, 2025

paulmedynski previously approved these changes Oct 10, 2025

View reviewed changes

github-actions Bot added the Stale The Issue or PR has become stale and will be automatically closed shortly if no activity occurs. label Nov 10, 2025

github-actions Bot removed the Stale The Issue or PR has become stale and will be automatically closed shortly if no activity occurs. label Nov 11, 2025

mdaigle modified the milestones: 7.0.0-preview3, 7.0.0-preview4 Dec 2, 2025

github-actions Bot added the Stale The Issue or PR has become stale and will be automatically closed shortly if no activity occurs. label Jan 2, 2026

github-actions Bot removed the Stale The Issue or PR has become stale and will be automatically closed shortly if no activity occurs. label Jan 3, 2026

cheenamalhotra added the Public API 🆕 Issues/PRs that introduce new APIs to the driver. label Jan 13, 2026

cheenamalhotra removed this from the 7.0.0-preview4 milestone Jan 20, 2026

cheenamalhotra modified the milestones: 7.1.0-preview2, 7.1.0-preview3 Jul 8, 2026

Copilot AI review requested due to automatic review settings July 9, 2026 20:56

Copilot started reviewing on behalf of cheenamalhotra July 9, 2026 20:56 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.cs Outdated

Comment thread src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.cs Outdated

Copilot AI review requested due to automatic review settings July 9, 2026 21:07

Copilot started reviewing on behalf of cheenamalhotra July 9, 2026 21:08 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 10, 2026 01:37

Copilot started reviewing on behalf of cheenamalhotra July 10, 2026 01:37 View session