Skip to content

migrate-from-13-to-14.md

Latest commit

 

History

History
230 lines (161 loc) · 12.3 KB

migrate-from-13-to-14.md

File metadata and controls

230 lines (161 loc) · 12.3 KB
Raw
title Migrate Hot Chocolate from 13 to 14

This guide will walk you through the manual migration steps to update your Hot Chocolate GraphQL server to version 14.

Start by installing the latest 14.x.x version of all of the HotChocolate.* packages referenced by your project.

This guide is still a work in progress with more updates to follow.

Breaking changes

Things that have been removed or had a change in behavior that may cause your code not to compile or lead to unexpected behavior at runtime if not addressed.

Banana Cake Pop and Barista renamed to Nitro

Old New Notes
AddBananaCakePopExporter AddNitroExporter
AddBananaCakePopServices AddNitro
BananaCakePop.Middleware ChilliCream.Nitro.App
BananaCakePop.Services ChilliCream.Nitro
BananaCakePop.Services.Azure ChilliCream.Nitro.Azure
BananaCakePop.Services.Fusion ChilliCream.Nitro.Fusion
barista nitro CLI executable
Barista ChilliCream.Nitro.CLI CLI NuGet package
BARISTA_API_ID NITRO_API_ID
BARISTA_API_KEY NITRO_API_KEY
BARISTA_CLIENT_ID NITRO_CLIENT_ID
BARISTA_OPERATIONS_FILE NITRO_OPERATIONS_FILE
BARISTA_OUTPUT_FILE NITRO_OUTPUT_FILE
BARISTA_SCHEMA_FILE NITRO_SCHEMA_FILE
BARISTA_STAGE NITRO_STAGE
BARISTA_SUBGRAPH_ID NITRO_SUBGRAPH_ID
BARISTA_SUBGRAPH_NAME NITRO_SUBGRAPH_NAME
BARISTA_TAG NITRO_TAG
bcp nitro Key in subgraph-config.json
bcp-config.json nitro-config.json
BCP_API_ID NITRO_API_ID
BCP_API_KEY NITRO_API_KEY
BCP_STAGE NITRO_STAGE
eat.bananacakepop.com nitro.chillicream.com
MapBananaCakePop MapNitroApp
@chillicream/bananacakepop-express-middleware @chillicream/nitro-express-middleware
@chillicream/bananacakepop-graphql-ide @chillicream/nitro-embedded mode: "self" is now mode: "embedded"

New GID format

This release introduces a more performant GID serializer, which also simplifies the underlying format of globally unique IDs.

By default, the new serializer will be able to parse both the old and new ID format, while only emitting the new format.

This change is breaking if your consumers depend on the format of the GIDs, by for example parsing them (which they shouldn't). If possible, strive to decouple your consumers from the internal ID format and exposing the underlying ID as a separate field on your type if necessary.

If you don't want to switch to the new format yet, you can register the legacy serializer, which only supports parsing and emitting the old ID format:

builder.Services
    .AddGraphQLServer()
    .AddLegacyNodeIdSerializer()
    .AddGlobalObjectIdentification();

Note: AddLegacyNodeIdSerializer() needs to be called before AddGlobalObjectIdentification().

How to adopt incrementally in a distributed system

None of your services can start to emit the new ID format, as long as there are services that can't parse the new format.

Therefore, you'll first want to make sure that all of your services support parsing both the old and new format, while still emitting the old format.

This can be done, by configuring the new default serializer to not yet emit the new format:

builder.Services
    .AddGraphQLServer()
    .AddDefaultNodeIdSerializer(outputNewIdFormat: false)
    .AddGlobalObjectIdentification();

Note: AddDefaultNodeIdSerializer() needs to be called before AddGlobalObjectIdentification().

Once all of your services have been updated to this, you can start emitting the new format service-by-service, by removing the AddDefaultNodeIdSerializer() call and switching to the new default behavior:

builder.Services
    .AddGraphQLServer()
    .AddGlobalObjectIdentification();

Node Resolver validation

We now enforce that each object type implementing the Node interface also defines a resolver, so that the object can be refetched through the node(id: ID!) field.

You can opt out of this new behavior by setting the EnsureAllNodesCanBeResolved option to false.

builder.Services
    .AddGraphQLServer()
    .ModifyOptions(o => o.EnsureAllNodesCanBeResolved = false)

Builder APIs

We have aligned all builder APIs to be more consistent and easier to use. Builders can now be created by using the static method Builder.New() and the Build() method to create the final object.

IQueryRequestBuilder replaced by OperationRequestBuilder

The interface IQueryRequestBuilder and its implementations were replaced with OperationRequestBuilder which now supports building standard GraphQL operation requests as well as variable batch requests.

The Build() method returns now a IOperationRequest which is implemented by OperationRequest and VariableBatchRequest.

We have also simplified what the builder does and removed a lot of the convenience methods that allowed to add single variables to it. This has todo with the support of variable batching. Now, you have to provide the variable map directly.

IQueryResultBuilder replaced by OperationResultBuilder

The interface IQueryResultBuilder and its implementations were replaced with OperationResultBuilder which produces an OperationResult on Build().

IQueryResult replaced by OperationResult

The interface IQueryResultBuilder and its implementations were replaced with OperationResultBuilder which produces an OperationResult on Build().

Operation complexity analyzer replaced

The Operation Complexity Analyzer in v13 has been replaced by Cost Analysis in v14, based on the draft IBM Cost Analysis specification.

  • The Complexity property on RequestExecutorOptions (accessed via ModifyRequestOptions) has been removed.
  • Cost analysis is enabled by default.

Please see the documentation for further information.

DateTime scalar enforces a specific format

The DateTime scalar will now enforce a specific format. The time and offset are now required, and fractional seconds are limited to 7. This aligns it with the DateTime Scalar spec (https://www.graphql-scalars.com/date-time/), with the one difference being that fractions of a second are optional, and 0-7 digits may be specified.

Please ensure that your clients are sending date/time strings in the correct format to avoid errors.

Persisted Queries renamed to Persisted Operations

Packages renamed

Old package name New package name
HotChocolate.PersistedQueries.FileSystem HotChocolate.PersistedOperations.FileSystem
HotChocolate.PersistedQueries.InMemory HotChocolate.PersistedOperations.InMemory
HotChocolate.PersistedQueries.Redis HotChocolate.PersistedOperations.Redis

Interfaces renamed

Old interface name New interface name
IPersistedQueryOptionsAccessor IPersistedOperationOptionsAccessor

Methods renamed

Old method name New method name
UsePersistedQueryPipeline UsePersistedOperationPipeline
UseAutomaticPersistedQueryPipeline UseAutomaticPersistedOperationPipeline
AddFileSystemQueryStorage AddFileSystemOperationDocumentStorage
AddInMemoryQueryStorage AddInMemoryOperationDocumentStorage
AddRedisQueryStorage AddRedisOperationDocumentStorage
OnlyAllowPersistedQueries OnlyAllowPersistedOperations
OnlyPersistedQueriesAreAllowedError OnlyPersistedOperationsAreAllowedError
AllowNonPersistedQuery AllowNonPersistedOperation
UseReadPersistedQuery UseReadPersistedOperation
UseAutomaticPersistedQueryNotFound UseAutomaticPersistedOperationNotFound
UseWritePersistedQuery UseWritePersistedOperation

Defaults changed

Parameter Old default New default
cacheDirectory "persisted_queries" "persisted_operations"

MutationResult renamed to FieldResult

Old name New name
MutationResult<TResult> FieldResult<TResult>
IMutationResult IFieldResult

IReadStoredQueries and IWriteStoredQueries now IOperationDocumentStorage

IReadStoredQueries and IWriteStoredQueries have been merged into a single interface named IOperationDocumentStorage.

Renamed interface methods:

Old name New name
TryReadQueryAsync TryReadAsync
WriteQueryAsync SaveAsync

Required keyed services

Accessing a keyed service that has not been registered will now throw, instead of returning null. The return type is now non-nullable.

This change aligns the API with the regular (non-keyed) service access API.

Deprecations

Things that will continue to function this release, but we encourage you to move away from.

SetPagingOptions

In an effort to align our configuration APIs, we're now also offering a delegate based configuration API for pagination options.

Before

builder.Services
    .AddGraphQLServer()
    .SetPagingOptions(new PagingOptions
    {
        MaxPageSize = 100,
        DefaultPageSize = 25
    });

After

builder.Services
    .AddGraphQLServer()
    .ModifyPagingOptions(opt =>
    {
        opt.MaxPageSize = 100;
        opt.DefaultPageSize = 25;
    });