3. A Hot Chocolate subgraph
5m

Overview

We've got a starting point for our already: a Hot Chocolate with information about playlists and tracks.

In this lesson, we will:

  • Enable federation in a Hot Chocolate

Federation in Hot Chocolate

Let's open up our project and take a look at the Odyssey.MusicMatcher.csproj file.

Odyssey.MusicMatcher.csproj
<Project Sdk="Microsoft.NET.Sdk.Web">


 <PropertyGroup>
   <TargetFramework>net8.0</TargetFramework>
   <Nullable>enable</Nullable>
   <ImplicitUsings>enable</ImplicitUsings>
 </PropertyGroup>


 <ItemGroup>
   <PackageReference Include="ApolloGraphQL.HotChocolate.Federation" Version="1.3.0" />
   <PackageReference Include="HotChocolate.AspNetCore" Version="13.6.0" />
   <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
 </ItemGroup>


</Project>

We're using the ApolloGraphQL.HotChocolate.Federation package. This package is an actively maintained Apollo fork of the Hot Chocolate package that implements the latest Federation v2 features.

Let's enable v2 in our .

Open up Program.cs, and find the line where the is initialized. we'll chain the .AddApolloFederationV2() method.

Program.cs
builder.Services
   .AddGraphQLServer()
   .AddApolloFederationV2()

Let's save our changes and restart the server.

Explorer time!

The Explorer is a powerful web IDE for creating, running, and managing . It lets us build operations easily and quickly, look at our operation history, peek at response hints, and share operations with others. We can access the Explorer through , an environment that helps with local graph development.

Note: For a refresher on how to use the Sandbox Explorer, check out Lesson 5: Apollo Sandbox Explorer in the Intro to GraphQL course.

Jump over to the browser and head to at https://studio.apollographql.com/sandbox.

Make sure you're connected to the server's endpoint by pasting in http://localhost:5059/graphql at the top left of the page.

Under the Query type, we can see two new that we didn't specifically add to the schema: _service and _entities. These two are signals that the is now a subgraph.

https://studio.apollographql.com/sandbox/explorer

Explorer showing two new fields added for subgraph

Generating the schema file

One more thing before we bring this into the . We'll need access to our subgraph's schema file.

If we followed Hot Chocolate's schema-first approach, we would already have a schema file! But since we went with the annotation-based approach, we'll need to do a couple of extra steps.

Note: You can learn more about the three different approaches that Hot Chocolate supports (annotation-based, code-first, and schema-first) in Lesson 3: Hot Chocolate of the Intro to GraphQL course.

To generate the schema file, Hot Chocolate provides a handy package to help us out. Let's install it.

dotnet add package HotChocolate.AspNetCore.CommandLine --version 13.6.1

Note the specific version number. Since we're using Hot Chocolate v13.6.1, this additional package needs to match accordingly.

Next, hop over to the Program.cs file and find the line where we run the app. We'll replace it with the method RunWithGraphQLCommands(args);

Program.cs
- app.Run();
+ app.RunWithGraphQLCommands(args);

With that, we can generate the schema by running the following command in the terminal:

dotnet run -- schema export --output schema.graphql

Note: There is a space between the double dashes and schema. There is no space between the double dashes and output.

We can find the generated schema in the schema.graphql file. It should start with the federation definition at the top, letting us know that this is a subgraph schema.

schema.graphql
schema
  @link(
    url: "https://specs.apollo.dev/federation/v2.5"
    import: [
      "@extends"
      "@external"
      "@key"
      "@inaccessible"
      "@override"
      "@provides"
      "@requires"
      "@shareable"
      "@tag"
      "FieldSet"
      "@composeDirective"
      "@interfaceObject"
    ]
  ) {
  query: Query
  mutation: Mutation
}

It also imports federation-specific . We'll be using @requires and @external later on! Taking a peek at the rest of the file, we can see types and related to playlists and tracks.

Practice

Which of these auto-generated fields indicate that the GraphQL server is now a valid subgraph server?

Key takeaways

  • We use the ApolloGraphQL.HotChocolate.Federation package to enable v2 features.
  • Two special , _service and _entities, indicate that the is now a .

Up next

With our ready, we can move on to the next step of the process: publishing the schema to .

Previous

Share your questions and comments about this lesson

This course is currently in

beta
. Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.