Upgrade Hot Chocolate to version 16.0.0 by aaronburtle · Pull Request #3480 · Azure/data-api-builder

aaronburtle · 2026-04-29T07:27:13Z

Why make this change?

Hot Chocolate has released stable v16.0.0 and we upgrade DAB to that version.

What is this change?

Update deps

Bump 6 HC packages to 16.0.0 in Directory.Packages.props:
HotChocolate, HotChocolate.AspNetCore, HotChocolate.AspNetCore.Authorization,
HotChocolate.Types.NodaTime, HotChocolate.Utilities.Introspection,
HotChocolate.Diagnostics.

Breaking changes (GraphQL schema)

HC v16 forces / motivates two schema-type renames. Wire formats and runtime
values are unchanged for both. REST and CLI surface area is unchanged.

Scalar: Byte -> UnsignedByte
Filter input: ByteFilterInput -> UnsignedByteFilterInput

HC v16 split the legacy ByteType into a signed ByteType (sbyte,
-128..127) and a new UnsignedByteType (byte, 0..255). SQL Server tinyint
is unsigned, so DAB must bind to UnsignedByteType.

Scalar: ByteArray -> Base64String
Filter input: ByteArrayFilterInput -> Base64StringFilterInput

HC v16 marked ByteArrayType as [Obsolete] in favor of Base64StringType.
Both serialize byte[] as a base64-encoded JSON string (identical wire
format), but the GraphQL scalar name is now Base64String. DAB targets the
new name so the generated schema does not depend on a deprecated scalar.

Inline literal filters continue to work for both renames. Clients that
declare typed variables of ByteFilterInput or ByteArrayFilterInput, or
that regenerate code from the schema (graphql-codegen, Strawberry Shake,
etc.), must update the type names.

Refactor scalar APIs

v16 renamed scalar overrides (ParseLiteral/ParseValue ->
OnCoerceInputLiteral/OnCoerceInputValue/OnCoerceOutputValue/
OnValueToLiteral) and call-site helpers (ParseValue/ParseResult ->
ValueToLiteral). DateTimeType.ValueToLiteral only accepts DateTimeOffset,
so we convert at the boundary. HC v16 also elides trailing zero fractional
seconds on DateTime output (...:54.000Z -> ...:54Z), which surfaced in
several test assertion updates.

Refactor resolver/execution APIs

ISelection was removed (use concrete Selection); Selection.SyntaxNode
became a ReadOnlySpan<FieldSelectionNode> (SyntaxNodes) to support
field-merging; TimeSpanType was replaced by DurationType (ISO-8601,
parsed via XmlConvert.ToTimeSpan); OperationResult.WithContextData is
gone (set singleResult.ContextData directly).

Refactor request interceptor and status middleware

IntrospectionInterceptor now has a no-arg constructor (schema services are
isolated from request services in v16) and implements the new four-arg
OnCreateAsync(HttpContext, IRequestExecutor, OperationRequestBuilder, CancellationToken)
signature; RuntimeConfigProvider is resolved from
context.RequestServices at request time.

DetermineStatusCodeMiddleware was updated for the unified OperationResult
type. Status codes are now propagated via context-data
(ExecutionContextData.HttpStatusCode) using an ImmutableDictionary
builder rather than mutating the response directly.

Adopt lazy schema initialization (LazyInitialization = true)

HC v16 builds the schema eagerly during host startup by default. DAB
supports a "hosted" scenario where the runtime config is supplied after the
host starts (POST /configuration), so eager construction races with our
placeholder fallback. We opt back into the v15 default
(options.LazyInitialization = true) so the schema is built on the first
GraphQL request, by which time the runtime config and metadata provider are
ready.

Drop ModifyOptions(o => o.EnableOneOf = true)

OneOf is on by default in v16.

Refactor startup

DateTimeType(disableFormatCheck: bool) is obsolete (replaced by
DateTimeOptions { ValidateInputFormat = ... }, polarity flipped);
WithOptions only accepts Action<GraphQLServerOptions> (per-request);
MapNitroApp().WithOptions(GraphQLToolOptions) was removed. Nitro is now
served by the same /graphql endpoint and is governed by
options.Tool.Enable on the per-request server options.

Harden Selection.SyntaxNodes access

HC v16's Selection.SyntaxNodes is a ReadOnlySpan<FieldSelectionNode>,
so direct SyntaxNodes[0].Node indexing would surface as
IndexOutOfRangeException at request time if the span were ever empty.
Added Selection.RequireFieldNode() in SelectionExtensions.cs
(IsEmpty check, return SyntaxNodes[0].Node, throw targeted
DataApiBuilderException otherwise). Adopted at all call sites in
SqlQueryStructure, CosmosQueryStructure, and ExecutionHelper.

Test updates

Adopt v16 OperationResultData / ResultDocument / ResultElement /
ResultProperty traversal in MultiSourceQueryExecutionUnitTests. Update
TestNoConfigReturnsServiceUnavailable to recognize that lazy
WithOptions resolution surfaces "no runtime config" as
DataApiBuilderException(ServiceUnavailable) rather than a 503 response or
ApplicationException. Update DateTime literal assertions and filter input
name references in affected test files. Decouple the GraphQL-scalar name
from the test database column name in GraphQLSupportedTypesTestsBase and
the My/Pg test classes so the Byte/UnsignedByte and
ByteArray/Base64String renames do not require renaming
byte_types/bytearray_types columns.

How was this tested?

Run against current test suite.

Bumps the HotChocolate family of packages from 16.0.0-p.7.68 (preview) to 16.0.0-rc.1.43 (release candidate). Affected packages: - HotChocolate - HotChocolate.AspNetCore - HotChocolate.AspNetCore.Authorization - HotChocolate.ModelContextProtocol - HotChocolate.Types.NodaTime - HotChocolate.Utilities.Introspection - HotChocolate.Transport.Http - HotChocolate.Diagnostics - CookieCrumble This commit is intentionally a single-line version bump; the API surface changes required to compile against rc.1.43 are split across the following commits in this series. Note: rc.1.43 is not yet cached on the internal feed (pkgs.dev.azure.com/sqldab/data_api_builder_build_packages). The NuGetAuthenticate@1 step in the build pipeline will trigger an authenticated upstream fetch on the first restore, after which the package will be permanently cached for all subsequent builds.

Hot Chocolate v16 reshaped the scalar type API surface. This commit adopts the new pattern in DAB's custom and built-in scalar usages. Scalar override renames (Service.GraphQLBuilder/CustomScalars/SingleType.cs): ParseLiteral(IFloatValueLiteral) -> OnCoerceInputLiteral(IFloatValueLiteral) ParseValue(JsonElement) -> OnCoerceInputValue(JsonElement) ParseResult / FormatResult -> OnCoerceOutputValue(T, ResultElement) ParseValue(T runtime) -> OnValueToLiteral(T) The output methods now write into a HotChocolate.Text.Json.ResultElement buffer rather than returning a value, and OnValueToLiteral replaces the old "ValueToLiteral / ParseResult / ParseValue" trio with a single literal-producing override. Scalar invocation renames at call sites (GraphQLStoredProcedureBuilder.cs, Sql/SchemaConverter.cs): type.ParseValue(runtimeValue) -> type.ValueToLiteral(runtimeValue) type.ParseResult(runtimeValue) -> type.ValueToLiteral(runtimeValue) Type rename (GraphQLTypes/DefaultValueType.cs, GraphQLStoredProcedureBuilder.cs, Sql/SchemaConverter.cs): ByteArrayType -> Base64StringType The legacy ByteArrayType identifier is now [Obsolete] and the Base64-string-encoded byte-array scalar lives under Base64StringType. DateTime / DateTimeOffset boundary (GraphQLStoredProcedureBuilder.cs, Sql/SchemaConverter.cs): HC v16's DateTimeType.ValueToLiteral(...) accepts only DateTimeOffset. Inputs from config (System.DateTime) are converted at the boundary preserving DateTimeKind: - Unspecified -> DateTimeOffset(value, TimeSpan.Zero) - Local / Utc -> DateTimeOffset(value) The CLR-driven schema-converter path now parses datetime defaults as DateTimeOffset directly rather than via DateTime. These changes match the patterns proposed in PR #3136 (HC v16 milestone-11 migration) and continue to compile cleanly against rc.1.43.

…tData Migrates DAB's Hot Chocolate runtime integration to v16's resolver and execution-pipeline contracts. Selection -> concrete type (Resolvers/CosmosQueryStructure.cs): ISelection -> Selection The ISelection interface was removed in HC v16; the runtime always returns the concrete Selection type. Selection.SyntaxNode -> SyntaxNodes[0].Node (Resolvers/CosmosQueryStructure.cs, Resolvers/Sql Query Structures/SqlQueryStructure.cs, Services/ExecutionHelper.cs) HC v16 introduces field-merging during query analysis, so a single Selection can now be backed by multiple syntactic occurrences in the query document. The shape changed from a single FieldNode (SyntaxNode) to an immutable list (SyntaxNodes) whose first entry is the canonical node for code that does not yet handle merged fields. DAB does not currently exercise merging, so .SyntaxNodes[0].Node is the equivalent canonical node and matches PR #3136's pattern. TimeSpanType -> DurationType (Services/ExecutionHelper.cs): The TimeSpanType scalar was removed; its replacement DurationType serializes values as ISO-8601 duration strings (e.g. "PT1H30M") rather than .NET's "1.06:00:00" round-trip format. The runtime-coercion path now parses with System.Xml.XmlConvert.ToTimeSpan, which is the ISO-8601-aware parser shipped in BCL. ByteArrayType -> Base64StringType (Services/ExecutionHelper.cs): Same scalar rename as the GraphQLBuilder commit; applied here in the runtime fieldValue coercion switch. OperationResult.WithContextData(...) -> direct property setter (Services/DetermineStatusCodeMiddleware.cs): context.Result = singleResult.WithContextData(contextData.ToImmutable()); is now singleResult.ContextData = contextData.ToImmutable(); OperationResult is mutable in v16, so the WithContextData fluent helper was removed; mutate ContextData directly. The middleware no longer needs to reassign context.Result since the existing instance reference now carries the change.

The OneOf input-object directive (graphql/graphql-spec#825) is permanently enabled in Hot Chocolate v16 and the SchemaOptions.EnableOneOf toggle was removed. Drops the now-obsolete .ModifyOptions(o => o.EnableOneOf = true) configuration call from the schema builder; behavior is unchanged.

…delegate Updates the GraphQL server wire-up in Startup.cs for three v16 API changes: 1. DateTimeType options bag The bool-flag overload `new DateTimeType(disableFormatCheck: bool)` is now [Obsolete]. Replaced with `new DateTimeType(new DateTimeOptions { ValidateInputFormat = ... })`. Note the boolean polarity flipped: old: disableFormatCheck = !graphQLRuntimeOptions.EnableLegacyDateTimeScalar new: ValidateInputFormat = !graphQLRuntimeOptions.EnableLegacyDateTimeScalar ...so the resulting condition that controls validation is unchanged. 2. WithOptions accepts only Action<GraphQLServerOptions> The MapGraphQL().WithOptions(...) overload that took a literal GraphQLServerOptions instance was removed. Options are now configured per-request via a delegate: .WithOptions(options => options.Tool.Enable = IsUIEnabled(...)); This means options are evaluated lazily on each incoming request rather than captured eagerly at startup. The behavioral difference is exercised by ConfigurationTests.TestNoConfigReturnsServiceUnavailable; see the test commit later in this series. 3. Nitro mapping consolidated under GraphQL server options `endpoints.MapNitroApp().WithOptions(new GraphQLToolOptions { ... })` was removed; GraphQLToolOptions is no longer a public type. The Nitro / Banana Cake Pop IDE is now governed solely by GraphQLServerOptions.Tool.Enable on the GraphQL endpoint mapping. Dropped the explicit MapNitroApp block because Tool.Enable already covers the dev-mode disable case.

Updates two test files affected by Hot Chocolate v16 runtime API changes that altered observable behavior. MultiSourceQueryExecutionUnitTests.cs - OperationResult.Data shape: HC v16 changed `OperationResult.Data` from `IReadOnlyDictionary<string, object>` to `OperationResultData?` (a struct wrapping a `ResultDocument`). The `Errors` property is also no longer nullable; it is an immutable list with an `IsEmpty` member. Old: Assert.IsNull(singleResult.Errors, ...); IReadOnlyDictionary<string, object> data = singleResult.Data; data.TryGetValue(QUERY_NAME_1, out object queryNode1); var firstEntry = ((IReadOnlyDictionary<string, object>)queryNode1) .FirstOrDefault(); Assert.AreEqual("db1", firstEntry.Value, ...); New: Assert.IsTrue(singleResult.Errors.IsEmpty, ...); ResultDocument document = (ResultDocument)singleResult.Data.Value.Value; document.Data.TryGetProperty(QUERY_NAME_1, out ResultElement queryNode1); ResultProperty firstEntry = queryNode1.EnumerateObject().FirstOrDefault(); Assert.AreEqual("db1", firstEntry.Value.GetString(), ...); The traversal is now: OperationResultData (struct) -> .Value (object, the ResultDocument) -> .Data (root ResultElement) -> .TryGetProperty -> .EnumerateObject -> ResultProperty -> .Value.GetString(). ConfigurationTests.cs - exception contract for "no runtime config": HC v16 resolves WithOptions(Action<>) per request rather than eagerly at startup, so the "no runtime config" condition that previously manifested as a 503 response (hosted-on-demand scenario) or ApplicationException (CLI startup scenario) now bubbles out of the request pipeline as DataApiBuilderException(HttpStatusCode.ServiceUnavailable). The catch block in TestNoConfigReturnsServiceUnavailable is split into two typed handlers so the assertion remains precise: catch (DataApiBuilderException dabException) Assert StatusCode == ServiceUnavailable. (Covers all three [DataRow] cases under HC v16.) catch (ApplicationException appException) Assert isUpdateableRuntimeConfig == false. Assert message matches the historical CLI startup message. (Preserved for symmetry; not exercised under HC v16 runtime behavior on the in-process test host but kept to avoid silently weakening the contract for legacy hosting variants.) Added a remarks block on the test summarizing the behavioral change.

Adds `#nullable enable annotations` to three test files that contain nullable reference type annotations (e.g. `string?`) but live in the Service.Tests project, which has `<Nullable>disable</Nullable>` set project-wide. Without an explicit annotation context the compiler emits CS8632 ("The annotation for nullable reference types should only be used in code within a '#nullable' annotations context"), which the repo-wide `<TreatWarningsAsErrors>True</TreatWarningsAsErrors>` setting promotes to a build error. These errors were introduced on main by an earlier change (PR #3476) and surfaced here only because the HC 16 upgrade pulled the build all the way through Service.Tests. The fix is intentionally narrow: "#nullable enable annotations" allows `?` syntax without enabling flow-sensitive null-state checking, so it does not cascade into a sea of unrelated nullable-state diagnostics in these legacy test files. Files affected: - Service.Tests/UnitTests/RequestParserUnitTests.cs - Service.Tests/UnitTests/SqlQueryExecutorUnitTests.cs - Service.Tests/Configuration/RuntimeConfigLoaderTests.cs This commit is independent of the HC 16 upgrade and could land separately on main.

Copilot

Pull request overview

Updates DAB’s GraphQL stack to align with Hot Chocolate v16 RC APIs, unblocking progress toward the finalized v16 surface area (per #3448) while keeping existing DAB REST/GraphQL/CLI behavior consistent.

Changes:

Bump Hot Chocolate (and related) package versions from 16.0.0-p.7.68 to 16.0.0-rc.1.43.
Migrate to v16 API changes across scalars, selection/syntax access, duration handling, and server endpoint options.
Update unit tests for new Hot Chocolate result/data traversal and address nullable-annotation build errors under warnings-as-errors.

Reviewed changes

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

Show a summary per file

File	Description
src/Directory.Packages.props	Updates Hot Chocolate/CookieCrumble package versions to v16 RC.
src/Service/Startup.cs	Migrates DateTime scalar options and GraphQL endpoint options/Nitro handling to v16 APIs.
src/Core/Services/GraphQLSchemaCreator.cs	Removes explicit OneOf enablement now default in v16.
src/Core/Services/ExecutionHelper.cs	Updates scalar runtime conversions (Base64String, Duration) and selection syntax node access.
src/Core/Services/DetermineStatusCodeMiddleware.cs	Migrates from `WithContextData` to setting `ContextData` directly.
src/Core/Resolvers/Sql Query Structures/SqlQueryStructure.cs	Updates selection syntax node access for v16 selection changes.
src/Core/Resolvers/CosmosQueryStructure.cs	Updates selection type and syntax node access for v16 selection changes.
src/Service.GraphQLBuilder/Sql/SchemaConverter.cs	Updates default value literal creation to new scalar APIs and Base64StringType.
src/Service.GraphQLBuilder/GraphQLTypes/DefaultValueType.cs	Replaces obsolete ByteArrayType with Base64StringType.
src/Service.GraphQLBuilder/GraphQLStoredProcedureBuilder.cs	Updates scalar literal creation APIs for stored proc default values.
src/Service.GraphQLBuilder/CustomScalars/SingleType.cs	Migrates custom scalar overrides to v16 coercion hooks and result writing.
src/Service.Tests/UnitTests/MultiSourceQueryExecutionUnitTests.cs	Updates assertions to v16 result/document traversal types.
src/Service.Tests/Configuration/ConfigurationTests.cs	Updates “no runtime config” expectations for v16 request-time option resolution.
src/Service.Tests/UnitTests/SqlQueryExecutorUnitTests.cs	Enables nullable annotations to fix CS8632 under warnings-as-errors.
src/Service.Tests/UnitTests/RequestParserUnitTests.cs	Enables nullable annotations to fix CS8632 under warnings-as-errors.
src/Service.Tests/Configuration/RuntimeConfigLoaderTests.cs	Enables nullable annotations to fix CS8632 under warnings-as-errors.

Comments suppressed due to low confidence (1)

src/Service.Tests/Configuration/ConfigurationTests.cs:756

The test metadata still says "Throws Application exception" (DataRow DisplayName) and the [TestMethod] description mentions an ApplicationException for the CLI scenario, but the updated assertions now accept DataApiBuilderException(ServiceUnavailable) as well. Please update the DisplayName/description to match the new expected behavior so the test output remains accurate.

        [DataRow(new string[] { }, true, DisplayName = "No config returns 503 - config file flag absent")]
        [DataRow(new string[] { "--ConfigFileName=" }, true, DisplayName = "No config returns 503 - empty config file option")]
        [DataRow(new string[] { }, false, DisplayName = "Throws Application exception")]
        [TestMethod("Validates that queries before runtime is configured returns a 503 in hosting scenario whereas an application exception when run through CLI")]
        public async Task TestNoConfigReturnsServiceUnavailable(

souvikghosh04

Posting comments so far..

…ure/data-api-builder into dev/aaronburtle/HC-16-upgrade

Aniruddh25

Consider optimizing Placeholder query node creation

Aniruddh25

Approving with suggestions. Thanks for the change

souvikghosh04

thanks for addressing the comments

…ure/data-api-builder into dev/aaronburtle/HC-16-upgrade

aaronburtle added 7 commits April 28, 2026 23:37

Copilot AI review requested due to automatic review settings April 29, 2026 07:27

aaronburtle requested review from Alekhya-Polavarapu, Aniruddh25, JerryNixon, RubenCerna2079, anushakolan, rusamant, sourabh1007, souvikghosh04, stuartpa and vadeveka as code owners April 29, 2026 07:27

Copilot started reviewing on behalf of aaronburtle April 29, 2026 07:27 View session

Copilot AI reviewed Apr 29, 2026

View reviewed changes

aaronburtle and others added 10 commits April 29, 2026 01:00

addressing comments

50ebc29

addressing comments

234b24f

fix tests

b8b5aa0

fix more tests

71855e7

lay GQL schema build in test

40c2a8e

fix more test failures

bb20141

Merge branch 'main' into dev/aaronburtle/HC-16-upgrade

c253578

fix more tests

ff088bd

more test fixes

eb37d90

fixing tests

d1f8950

aaronburtle unassigned RubenCerna2079, aaronburtle and souvikghosh04 May 6, 2026

souvikghosh04 assigned Aniruddh25 and unassigned RubenCerna2079 May 11, 2026

Merge branch 'main' into dev/aaronburtle/HC-16-upgrade

4353a63

souvikghosh04 reviewed May 12, 2026

View reviewed changes

aaronburtle added 3 commits May 12, 2026 13:24

comment cleanup, remove warns suppression

7186285

Merge branch 'dev/aaronburtle/HC-16-upgrade' of https://github.com/Az…

12da518

…ure/data-api-builder into dev/aaronburtle/HC-16-upgrade

transition from obsolete datatype

f112399

Aniruddh25 reviewed May 13, 2026

View reviewed changes

Comment thread src/Core/Services/GraphQLSchemaCreator.cs Outdated

Aniruddh25 reviewed May 13, 2026

View reviewed changes

Comment thread src/Core/Services/GraphQLSchemaCreator.cs Outdated

Aniruddh25 requested changes May 13, 2026

View reviewed changes

aaronburtle and others added 2 commits May 14, 2026 16:00

optimize node scan and rebuild

18d5020

Merge branch 'main' into dev/aaronburtle/HC-16-upgrade

76793a0

Aniruddh25 reviewed May 15, 2026

View reviewed changes

Comment thread src/Core/Services/GraphQLSchemaCreator.cs

Aniruddh25 reviewed May 15, 2026

View reviewed changes

Comment thread src/Core/Services/GraphQLSchemaCreator.cs

Aniruddh25 approved these changes May 15, 2026

View reviewed changes

souvikghosh04 approved these changes May 15, 2026

View reviewed changes

souvikghosh04 enabled auto-merge (squash) May 15, 2026 03:08

souvikghosh04 disabled auto-merge May 15, 2026 03:32

souvikghosh04 and others added 3 commits May 15, 2026 09:02

Merge branch 'main' into dev/aaronburtle/HC-16-upgrade

b1913e9

add some test coverage

1bc467f

Merge branch 'dev/aaronburtle/HC-16-upgrade' of https://github.com/Az…

94de892

…ure/data-api-builder into dev/aaronburtle/HC-16-upgrade

aaronburtle enabled auto-merge (squash) May 15, 2026 22:48

Merge branch 'main' into dev/aaronburtle/HC-16-upgrade

66d8a42

Aniruddh25 approved these changes May 16, 2026

View reviewed changes

aaronburtle merged commit c6ecc3c into main May 16, 2026
12 checks passed

aaronburtle deleted the dev/aaronburtle/HC-16-upgrade branch May 16, 2026 02:55

github-project-automation Bot moved this from Review In Progress to Done in Data API builder May 16, 2026

Conversation

aaronburtle commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why make this change?

What is this change?

Update deps

Breaking changes (GraphQL schema)

Refactor scalar APIs

Refactor resolver/execution APIs

Refactor request interceptor and status middleware

Adopt lazy schema initialization (LazyInitialization = true)

Drop ModifyOptions(o => o.EnableOneOf = true)

Refactor startup

Harden Selection.SyntaxNodes access

Test updates

How was this tested?

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

souvikghosh04 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Aniruddh25 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Aniruddh25 left a comment

Choose a reason for hiding this comment

Uh oh!

souvikghosh04 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

aaronburtle commented Apr 29, 2026 •

edited

Loading