Introduction

GraphQL is classified as a query language for querying your data.

I’m not going to go into a full description of it’s capabilities/uses, for that go to the GraphQL website, but one thing which has always interested me, is an API where the client application can tell the server API what data to return. Thus allow the client to reduce bandwidth as well as reduce the amount of data being deserialised to exactly what the client application requires – obviously particularly useful for mobile applications.

Using graphiql-dotnet and ASP.NET core

We’re going to be using graphql-dotnet and ASP.NET core to implement a basic

• Create an ASP.NET Core Web Application, mine’s named GraphQLService
• Select an Empty project
• I’m going to uncheck “Configure for HTTPS”
• Now add the following packages via NuGet
  • GraphQL.Server.Transports.AspNetCore
  • GraphQL.Server.Transports.WebSockets
  • GraphQL.Server.Ui.GraphiQL
  • GraphQL.Server.Ui.Playground
  • GraphQL.Server.Ui.Voyager
  • GraphQL-Parser

Note: We’ve added the GraphQL.Server.Ui.Playground package to allow us to write queries within an interactive environment (http://localhost:5000/ui/playground) which also allows us to view the schema definitions etc. We’ve added GraphQL.Server.Ui.Voyager which adds a cool schema/type viewer (http://localhost:5000/ui/voyager). Finally we’ve added GraphQL.Server.Ui.GraphiQL to allow us to use the well known GraphiQL interactive environment (http://localhost:5000/ui/graphiql), feel free to remove all or some of these as required.

Remove the code from the Configure method of the Startup.cs file except for the following

if (env.IsDevelopment())
{
   app.UseDeveloperExceptionPage();
}

Now we’re going to add some tools, the playground (an interactive query web app) the voyager for digging into the schema and the GraphQL endpoint. So add the following to the Startup.cs below the code shown above

app.UseWebSockets();
app.UseGraphQLWebSockets<PersonSchema>("/graphql");
app.UseGraphQL<PersonSchema>("/graphql");
app.UseGraphQLPlayground(new GraphQLPlaygroundOptions()
{
   Path = "/ui/playground",
});
app.UseGraphiQLServer(new GraphiQLOptions
{
   GraphiQLPath = "/ui/graphiql",
   GraphQLEndPoint = "/graphql"
});
app.UseGraphQLVoyager(new GraphQLVoyagerOptions()
{
   GraphQLEndPoint = "/graphql",
   Path = "/ui/voyager"
});

Finally within Startup.cs, within the ConfigureServices method add the following code, which will register some types (which we’ll be supplying soon, the schema and query classes) and configures the GraphQL middleware.

services.AddSingleton<PersonSchema>();

services.AddGraphQL(options =>
{
   options.EnableMetrics = true;
   options.ExposeExceptions = true;
})
.AddWebSockets()
.AddDataLoader();

Schema

At this point we can see a need for the classes PersonSchema and PersonQuery. As you’ve realised, we are needing to create a schema object which will define our queries and types that we can query against. We’ll just create the bare bones schema class in PersonSchema.cs

public class PersonSchema : Schema
{
   public PersonSchema()
   {
      Query = new PersonQuery();
   }
}

Queries

Now we’ll create a bare PersonQuery.cs file which will be the starting point for some query functionality

public class PersonQuery : ObjectGraphType
{
}

At this point we could compiler and run the ASP.NET core application and navigate to http://localhost:5000/ui/playground to view the playground web application. However there’s not much we can do at this point.

Let’s add a domain object which represents a Person object, so add the following class. This represents the class that might come from a database or from another service

public class Person
{
   public string Name { get; set; }
}

For graphql-dotnet to allow us to use this class we need to wrap our Person object within a graphql-dotnet type, so create the following PersonType

public class PersonType : ObjectGraphType<Person>
{
   public PersonType()
   {
      Field(o => o.Name);
   }
}

In this case graphql-dotnet will now map fields to the Person object via the Field methods. This type then needs to be added to the PersonQuery class, to allow for querying again PersonType (and then ultimately Person) data. So add the PersonQuery constructor with the following code

public PersonQuery()
{
   Field<ListGraphType<PersonType>>("people", resolve: context => new[]
   {
      new Person {Name = "Scooby Doo"},
      new Person {Name ="Daphne Blake" },
      new Person {Name ="Shaggy Rogers" },
      new Person {Name ="Velma Dinkley" },
      new Person {Name ="Fred Jones" }
   });
}

Now if we run the application and navigate to http://localhost:5000/ui/playground we’ll find a Schema tab which displays information about how to query our data and if we write the following query

{
  people {
     name
  }
}

and run it from the playground we’ll see a list of the names from our Person data.

The previous example omitted the query keyword, i.e. it would look like this in a more formal definition of a query

query {
  people {
     name
  }
}

We can also implement our own query methods that might be called using the following (the C# for this is shown further down the post)

find(input : "Scooby Doo") {
   name
}

Or we can create a query which takes parameters/arguments from query variables. This example shows the use of an operation name, i.e. getPerson.

Note: operation names can be used for queries, mutations and subcriptions.

query getPerson($input : String) {
  find(input : $input) {
    name
  }
}

along with the input

{
  "input" : "Scooby Doo"
}

We’ll now create an input type in C# which will work with the above queries, such as

public class PersonInputType : InputObjectGraphType
{
   public PersonInputType()
   {
      Field<StringGraphType>("input");
   }
}

Now add another field to the PersonQuery constructor like this

Field<PersonType>(
   "find", 
   arguments: new QueryArguments(
      new QueryArgument<StringGraphType> 
      {
         Name = "input"
     }),
   resolve: context =>
   {
      var i = context.GetArgument<string>("input");
      return new Person {Name = i.ToString()};
   });

In the above, we essentially have created a new field in the PersonQuery which acts like a method, it is of type PersonType (the return type in this instance) and named find it takes a single argument of type string and expects the argument name of input. Finally it resolves to a method which we can then write something more substantial code for querying our data. In this simple example we’re just returning the argument passed in.

Note: We can also create multiple queries, so for example say we want to locate Person A and Person B and return data as a single result, we could write

{
   A : find(input : "Scooby") {
      name
   }
   B : find(input : "Shaggy") {
      name
   }
}

In the above query we use a GraphQL feature using aliases, the A and B acting like variable names. This allows us to create multiple queries against the same query/method.

When our queries start to become more complicated, we might prefer to place the field selection into, what’s know as a fragment, for example

{
   find(input : "Scooby") {
    ...fields
   }
}

fragment fields on PersonType {
  name
}

Obviously in our example it took more work to create and use the fragment that just using the field name, but you get the idea. However fragments can also be reused if we had multiple queries, so hence with more fields this become a much more useful technique.

Mutations

We’ve created our queries, which is great for scenarios where we’re simply reading data, but we can also create mutations, i.e. code that changes our data.

We can write a GraphQL mutation like this

mutation addPerson($input : String) {
   addPerson(input : $input)
   {
      name
   }
}

along with input such as

{
  "input" : "Scooby Doo"
}

What we now need to do is create our mutation class, like this

public class PersonMutation : ObjectGraphType<Person>
{
   public PersonMutation()
   {
      Field<PersonType>("addPerson",
         arguments: new QueryArguments(
            new QueryArgument<StringGraphType> {Name = "input"}),
         resolve: context =>
         {
            var n = context.GetArgument<string>("input");
            return new Person { Name = n };
         });
    }
}

We also need to alter the PersonSchema constructor to look like this

public PersonSchema()
{
   Query = new PersonQuery();
   Mutation = new PersonMutation();
}

Subscriptions

As you might expect, subscriptions are a way to handle something similar to events, hence we can connect to our service and received updates. Here’s a simple example of a query

subscription {
  personAdded {
    name
  }
}

Here’s a simple example of a subscription, to keep things simple this will simply send a message every second to any subcribers

public class PersonSubscription : ObjectGraphType
{
   public PersonSubscription()
   {
      AddField(new EventStreamFieldType
      {
         Name = "personAdded",
         Type = typeof(PersonType),
         Resolver = new FuncFieldResolver<Person>(ResolvePerson),
         Subscriber = new EventStreamResolver<Person>(SubscribePerson)
      });
   }

   private Person ResolvePerson(ResolveFieldContext context)
   {
      return context.Source as Person;
   }

   private IObservable<Person> SubscribePerson(ResolveEventStreamContext context)
   {
      return Observable.Interval(
         TimeSpan.FromSeconds(1))
           .Select(s => new Person 
           {
              Name = s.ToString()
           });
   }
}

Now we need to update the schema constructor like this

public PersonSubscription()
{
   AddField(new EventStreamFieldType
   {
      Name = "personAdded",
      Type = typeof(PersonType),
      Resolver = new FuncFieldResolver<Person>(ResolvePerson),
      Subscriber = new EventStreamResolver<Person>(SubscribePerson)
   });
}

Further reading

Refer to the GraphQL site for in depth examples and more complete explanations of the everything I’ve discussed above.

Also check out the GraphQL.net web site for graphql-dotnet documentation.

If you’re interested in code for the project, it’s available on GitHub.