johnrutherford / graphql-aspnetcore

ASP.NET Core MiddleWare to create a GraphQL end-point

GraphQl.AspNetCore

The feedback about my last blog post about the GraphQL end-point in ASP.NET Core was amazing. That post was mentioned on reddit, many times shared on twitter, lInked on http://asp.net and - I'm pretty glad about that - it was mentioned in the ASP.NET Community Standup.

Because of that and because GraphQL is really awesome, I decided to make the GraphQL MiddleWare available as a NuGet package. I did some small improvements to make this MiddleWare more configurable and more easy to use in the Startup.cs

NuGet

Install that package via Package Manager Console:

PM> Install-Package GraphQl.AspNetCore -Pre

Install via dotnet CLI:

dotnet add package GraphQl.AspNetCore --version 1.0.0-preview1

Using the library

You still need to configure your GraphQL schema using the graphql-dotnet library, as described in my last post. If this is done open your Startup.cs and add an using to the GraphQl.AspNetCore library:

using GraphQl.AspNetCore;

You can use two different ways to register the GraphQlMiddleware:

app.UseGraphQl(new GraphQlMiddlewareOptions
{
  GraphApiUrl = "/graph", // default
  RootGraphType = new BooksQuery(bookRepository),
  FormatOutput = true, // default: false
  ComplexityConfiguration = new ComplexityConfiguration { }; //default
});
app.UseGraphQl(options =>
{
  options.GraphApiUrl = "/graph-api";
  options.RootGraphType = new BooksQuery(bookRepository);
  options.FormatOutput = false; // default
  options.ComplexityConfiguration = new ComplexityConfiguration { MaxDepth = 15, MaxComplexity = 20 };
});

Personally I prefer the second way, which is more readable in my opinion.

The root graph type needs to be passed to the GraphQlMiddlewareOptions object, depending on the implementation of your root graph type, you may need to inject the data repository or a EntityFramework DbContext, or whatever you want to use to access your data. In this case I reuse the IBookRepository of the last post and pass it to the BooksQuery which is my root graph type.

I registered the repository like this:

services.AddSingleton<IBookRepository, BookRepository>();

and needed to inject it to the Configure method:

public void Configure(
  IApplicationBuilder app,
  IHostingEnvironment env,
  ILoggerFactory loggerFactory,
  IBookRepository bookRepository)
{
  // ...
}

Another valid option is to also add the BooksQuery to the DependencyInjection container and inject it to the Configure method.

Options

The GraphQlMiddlewareOptions are pretty simple. Currently there are only three properties to configure

• RootGraphType: This configures your GraphQL query schema and needs to be set. If this property is unset an ArgumentNullException will be thrown.
• GraphApiUrl: This property defines your GraphQL endpoint path. The default is set to /graph which means your endpoint is available under //yourdomain.tld/graph
• FormatOutput: This property defines whether the output is prettified and indented for debugging purposes. The default is set to false.

This should be enough for the first time. If needed it is possible to expose the Newtonsoft.JSON settings, which are used in GraphQL library later on.

GraphQL.AspNetCore.Graphiql

This library provides a middleware to add a GraphiQL UI to your GraphQL endpoint. To learn more about it and the way I created it, read the blog post about it: GraphiQL for ASP.NET Core

NuGet

There's no NuGet Package available yet. I will provide one as soon as possible.

Using the library

Open your Startup.cs and add an using to the GraphQl.AspNetCore.Graphiql namespace:

using GraphQl.AspNetCore.Graphiql;

You can use two different ways to register the GraphiqlMiddleware:

app.UseGraphiql(new GraphQlMiddlewareOptions
{
  GraphiqlPath = "/graphiql", // default
  GraphQlEndpoint = "/graph" // default
});
app.UseGraphiql(options =>
{
  options.GraphiqlPath = "/graphiql"; // default
  options.GraphQlEndpoint = "/graph"; // default
});

Personally I prefer the second way, which is more readable in my opinion.

The GraphQlEndpoint need to match any GraphApiUrl of an existing GraphQL endpoint.

Options

Currently the options just have two properties:

• GraphiqlPath: This is the path in the URL of your application, where you want to access the GraphiQL UI
• GraphQlEndpoint: This is the path of your GrpahQL end-point, configured with the GraphQlMiddleware. In theory it could be any possible path or URL that provides an GraphQL endpoint. Until now, I just tested it with the GraphQlMiddleware.

One more thing

I would be happy, if you try this library and get me some feedback about it. A demo application to quickly start playing around with it, is available here on GitHub. Feel free to raise some issues and to create some PRs to improve this MiddleWare.