Hello world

4. Hello world

Overview

For now, we'll keep things simple and try a classic "Hello world" example for our schema. Don't worry, we'll jump into playlists and tracks later on!

In this lesson, we will:

Learn about the Query type
Implement a resolver function for a "Hello world" example
Register the Query type in our GraphQL server
Compare and contrast the annotation-based, schema-first, and code-first approaches

The `Query` type

The Query type defines a list of everything we're allowed to ask for from our GraphQL server. It's the entry point into our schema!

First, let's create a folder in the root of our project called Types, where we'll organize all of our GraphQL schema types.

Then, let's add a class called Query.

Types/Query.cs

namespace Odyssey.MusicMatcher;

public class Query
{
  // where Query resolver functions will go
}

Note: If you're using VS Code, the C# Dev Kit extension grants you access to a "Solution Explorer" section. Use this to quickly create folders and classes with the boilerplate code you see above.

Inside the Query class, let's write the resolver function for a field called Hello. It will be a public function returning a string type. Inside the function body, we'll return a hard-coded value of "Hello world".

Types/Query.cs

public string Hello()
{
    return "Hello world";
}

This is our first resolver, a function that populates the data for a field in our schema. Remember, with the annotation-based approach, Hot Chocolate generates the GraphQL schema based on our resolvers. So right now, our schema looks something like this:

Generated GraphQL schema

type Query {
  hello: String!
}

namespace Odyssey.MusicMatcher;

public class Query
{
    public string Hello()
    {
        return "Hello world";
    }
}

Registering the `Query` type

Our GraphQL server needs to know about the Query type. Hopping into the Program.cs file, find the line where we added the GraphQL server. We'll chain a new function called AddQueryType and pass in the Query type.

Program.cs

builder.Services.AddGraphQLServer()
   .AddQueryType<Query>();

The Program.cs file doesn't know where this Query type is coming from, so we'll also need to import the namespace at the top of the file.

Program.cs

using Odyssey.MusicMatcher;

Note: This namespace was defined by default in the starter code you cloned. If you look at the top of the Query.cs file, you can see that the Query type is defined as part of the Odyssey.MusicMatcher namespace. If you change this namespace to a different value, you'll also need to change the import in Program.cs accordingly!

Let's not forget to save our changes and restart the server with dotnet run.

Here's what our Hello World example would look like if we used the schema-first approach. Note the filenames.

Types/schema.graphql

type Query {
  hello: String!
}

Types/Query.cs

namespace Odyssey.MusicMatcher;

public class Query
{
  public string Hello()
  {
      return "Hello world";
  }
}

Program.cs

using Odyssey.MusicMatcher;

var builder = WebApplication.CreateBuilder(args);

builder.Services
  .AddGraphQLServer()
  .AddDocumentFromFile("Types/schema.graphql")
  .BindRuntimeType<Query>();

var app = builder.Build();

app.MapGraphQL();

app.Run();

We can see that the resolvers in Query.cs stay the same but we have an extra file that contains the SDL in schema.graphql. We also need to connect that schema file with the GraphQL server using AddDocumentFromFile, then bind the Query type using BindRuntimeType.

If the types in the resolvers and the schema don't match, we would get an error when sending queries to the server.

Even if we don't implement our server using the schema-first approach, consulting with API consumers on what they expect and need from the GraphQL schema is still important.

Here's what our Hello World example would look like if we used the code-first approach:

Types/Query.cs

namespace Odyssey.MusicMatcher;

public class Query
{
  public string Hello()
  {
      return "Hello world";
  }
}

public class QueryType : ObjectType<Query>
{
  protected override void Configure(IObjectTypeDescriptor<Query> descriptor)
  {
      descriptor
          .Field(f => f.Hello())
          .Type<StringType>();
  }
}

Program.cs

using Odyssey.MusicMatcher

var builder = WebApplication.CreateBuilder(args);

builder.Services
  .AddGraphQLServer()
  .AddQueryType<QueryType>();

var app = builder.Build()

app.MapGraphQL();

app.Run();

We can see the addition of a QueryType class that implements the HotChocolate.Types.ObjectType class from Hot Chocolate. The Configure method contains the code required to hook up the Query class to work with the GraphQL server.

Remember that both annotation-based and schema-first approaches end up being translated to this code behind the scenes!

In this course, we cloned a repo that contained the minimal version of a .NET web template, added the Hot Chocolate package and set up all the code ourselves to get a "Hello world" example running.

Don't want to go through all that work for your next project? You can use rover template for Hot Chocolate!

First, follow the instructions to install Rover. Rover is a command-line interface for managing and maintaining graphs with Apollo.

In a terminal window, run rover template use subgraph-csharp-hotchocolate-annotation.

Now you've got a fully-functioning and ready-to-use GraphQL server implemented in Hot Chocolate!

You can see the full list of available templates for different languages by running rover template list.

Practice

What is the purpose of the Query type in GraphQL?

To serve as the entry point into the schemaTo manage database queriesTo define the resolversTo organize GraphQL schema files

What is a resolver in GraphQL?

A function that populates data for a specific field in the schemaA separate GraphQL schema fileA GraphQL type definitionA file containing GraphQL schema annotations

How is the Query type registered in the GraphQL server in the annotation-based approach?

By defining a separate QueryResolver classBy importing a GraphQL schema fileUsing the AddQueryType functionUsing the AddDocumentFromFile function

Key takeaways

The fields of the Query type are entry points into our schema. These are the top-level fields that a GraphQL consumer can query for.
We can connect the Query file with our GraphQL server using the function AddQueryType<Query>().
A resolver is a function that populates the data for a field in our schema.

Up next

Our GraphQL server is ready to receive queries. In the next lesson, we'll discover the best way to write and send queries: Apollo Explorer.

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.

Overview

The Query type

Registering the Query type

Practice

Key takeaways

Up next

Share your questions and comments about this lesson

The `Query` type

Registering the `Query` type