Name: GraphQL.Server.Ui.Playground
Author: Shane Krueger, Pekka Heikura, Ivan Maximov, et al.

GraphQL.Server.Ui.Playground — nugetz

Package	Downloads	Version	Description
GraphQL.Server.All			Includes all the packages below, plus the `GraphQL.DataLoader` and `GraphQL.MemoryCache` packages
GraphQL.Server.Transports.AspNetCore			Provides GraphQL over HTTP/WebSocket server support on top of ASP.NET Core, plus authorization rule support
GraphQL.Server.Ui.Altair			Provides Altair UI middleware
GraphQL.Server.Ui.Playground :warning:			Provides Playground UI middleware (deprecated)
GraphQL.Server.Ui.GraphiQL			Provides GraphiQL UI middleware
GraphQL.Server.Ui.Voyager			Provides Voyager UI middleware

:warning: When upgrading from prior versions, please remove references to these old packages :warning:
GraphQL.Server.Core
GraphQL.Server.Authentication.AspNetCore
GraphQL.Server.Transports.AspNetCore.NewtonsoftJson
GraphQL.Server.Transports.AspNetCore.SystemTextJson
GraphQL.Server.Transports.Subscriptions.Abstractions
GraphQL.Server.Transports.Subscriptions.WebSockets
GraphQL.Server.Transports.WebSocktes

<Project Sdk="Microsoft.NET.Sdk.Web">

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

  <ItemGroup>
    <PackageReference Include="GraphQL.Server.All" Version="7.0.0" />
  </ItemGroup>

</Project>

using GraphQL;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddGraphQL(b => b
    .AddAutoSchema<Query>()  // schema
    .AddSystemTextJson());   // serializer

var app = builder.Build();
app.UseDeveloperExceptionPage();
app.UseWebSockets();
app.UseGraphQL("/graphql");            // url to host GraphQL endpoint
app.UseGraphQLGraphiQL(
    "/",                               // url to host GraphiQL at
    new GraphQL.Server.Ui.GraphiQL.GraphiQLOptions
    {
        GraphQLEndPoint = "/graphql",         // url of GraphQL endpoint
        SubscriptionsEndPoint = "/graphql",   // url of GraphQL endpoint
    });
await app.RunAsync();

public class Query
{
    public static string Hero() => "Luke Skywalker";
}

http://localhost:5000/graphql?query={hero}

{"data":{"hero":"Luke Skywalker"}}

app.UseGraphQL("/graphql", opts => {
    opts.ReadFormOnPost = true;
});

var app = builder.Build();
app.UseDeveloperExceptionPage();
app.UseWebSockets();
app.UseRouting();
app.UseEndpoints(endpoints =>
{
    endpoints.MapGraphQL("graphql");
    endpoints.MapGraphQLVoyager("ui/voyager");
});
await app.RunAsync();

var app = builder.Build();
app.UseDeveloperExceptionPage();
app.UseWebSockets();
app.UseRouting();
app.UseGraphQLVoyager("/graphql");
app.UseEndpoints(endpoints =>
{
    endpoints.MapGraphQL("/graphql");
});
await app.RunAsync();

var app = builder.Build();
app.UseDeveloperExceptionPage();
app.UseWebSockets();

// configure the graphql endpoint at "/graphql", using GraphQLExecutionHttpResult
// map GET in order to support both GET and WebSocket requests
app.MapGet("/graphql", () => new GraphQLExecutionHttpResult());
// map POST to handle standard GraphQL POST requests
app.MapPost("/graphql", () => new GraphQLExecutionHttpResult());

await app.RunAsync();

app.MapPost("/graphql", async (HttpContext context, IDocumentExecuter<ISchema> documentExecuter, IGraphQLSerializer serializer) =>
{
    var request = await serializer.ReadAsync<GraphQLRequest>(context.Request.Body, context.RequestAborted);
    var opts = new ExecutionOptions
    {
        Query = request?.Query,
        DocumentId = request?.DocumentId,
        Variables = request?.Variables,
        Extensions = request?.Extensions,
        CancellationToken = context.RequestAborted,
        RequestServices = context.RequestServices,
        User = context.User,
    };

    return new ExecutionResultHttpResult(await documentExecuter.ExecuteAsync(opts));
});

public class HomeController : Controller
{
    public IActionResult Index()
        => new GraphiQLActionResult(opts =>
        {
            opts.GraphQLEndPoint = "/Home/graphql";
            opts.SubscriptionsEndPoint = "/Home/graphql";
        });

    [HttpGet]
    [HttpPost]
    [ActionName("graphql")]
    public IActionResult GraphQL()
        => new GraphQLExecutionActionResult();
}

public class HomeController : Controller
{
    private readonly IDocumentExecuter _documentExecuter;

    public TestController(IDocumentExecuter<ISchema> documentExecuter)
    {
        _documentExecuter = documentExecuter;
    }

    [HttpGet]
    public async Task<IActionResult> GraphQL(string query)
    {
        var result = await _documentExecuter.ExecuteAsync(new()
        {
            Query = query,
            RequestServices = HttpContext.RequestServices,
            CancellationToken = HttpContext.RequestAborted,
        });
        return new ExecutionResultActionResult(result);
    }
}

[FunctionName("GraphQL")]
public static IActionResult RunGraphQL(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post"] HttpRequest req)
{
    return new GraphQLExecutionActionResult();
}

[FunctionName("GraphiQL")]
public static IActionResult RunGraphiQL(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get"] HttpRequest req)
{
    return new GraphiQLActionResult(opts => opts.GraphQLEndPoint = "/api/graphql");
}

builder.Services.AddGraphQL(b => b
    .AddAutoSchema<Query>()
    .AddSystemTextJson()
    .AddUserContextBuilder(httpContext => new MyUserContext(httpContext));

public class MyUserContext : Dictionary<string, object?>
{
    public ClaimsPrincipal User { get; }

    public MyUserContext(HttpContext context)
    {
        User = context.User;
    }
}

app.UseAuthentication();
app.UseAuthorization();
app.UseWebSockets();
app.UseGraphQL("/graphql");

app.UseGraphQL("/graphql", config =>
{
    // require that the user be authenticated
    config.AuthorizationRequired = true;

    // require that the user be a member of at least one role listed
    config.AuthorizedRoles.Add("MyRole");
    config.AuthorizedRoles.Add("MyAlternateRole");

    // require that the user pass a specific authorization policy
    config.AuthorizedPolicy = "MyPolicy";
});

builder.Services.AddGraphQL(b => b
    .AddAutoSchema<Query>()
    .AddSystemTextJson()
    .AddAuthorizationRule());

{
  cat {
    # validates against Cat.Name
    name

    # validates against Animal.Name
    ... on Animal {
      name
    }
  }
}

builder.Services.AddGraphQL(b => b
    .AddAutoSchema<Query>()
    .AddSystemTextJson()
    .AddAuthorizationRule()  // not required for endpoint authorization
    .AddWebSocketAuthentication<MyAuthService>());

app.UseGraphQL("/graphql", config =>
{
    // require that the user be authenticated
    config.AuthorizationRequired = true;
});

class MyAuthService : IWebSocketAuthenticationService
{
    private readonly IGraphQLSerializer _serializer;

    public MyAuthService(IGraphQLSerializer serializer)
    {
        _serializer = serializer;
    }

    public async ValueTask<bool> AuthenticateAsync(IWebSocketConnection connection, OperationMessage operationMessage)
    {
        // read payload of ConnectionInit message and look for an "Authorization" entry that starts with "Bearer "
        var payload = _serializer.ReadNode<Inputs>(operationMessage.Payload);
        if ((payload?.TryGetValue("Authorization", out var value) ?? false) && value is string valueString)
        {
            var user = ParseToken(valueString);
            if (user != null)
            {
                // set user and indicate authentication was successful
                connection.HttpContext.User = user;
                return true;
            }
        }
        return false; // authentication failed
    }

    private ClaimsPrincipal? ParseToken(string authorizationHeaderValue)
    {
        // parse header value and return user, or null if unable
    }
}

app.UseGraphQL("/graphql", config =>
{
    // specify a specific authentication scheme to use
    config.AuthenticationSchemes.Add(JwtBearerDefaults.AuthenticationScheme);
});

app.UseGraphQLAltair();
app.UseGraphQLGraphiQL();
app.UseGraphQLPlayground();  // deprecated
app.UseGraphQLVoyager();

// or

endpoints.MapGraphQLAltair();
endpoints.MapGraphQLGraphiQL();
endpoints.MapGraphQLPlayground();  // deprecated
endpoints.MapGraphQLVoyager();

builder.Services.AddCors();

app.UseCors(policy => {
    // configure default policy here
});

// ...
builder.Services.AddRouting();
builder.Services.AddCors(builder =>
{
    // configure named and/or default policies here
});

var app = builder.Build();
app.UseDeveloperExceptionPage();
app.UseWebSockets();
app.UseRouting();
app.UseCors();
app.UseEndpoints(endpoints =>
{
    // configure the graphql endpoint with the specified CORS policy
    endpoints.MapGraphQL()
        .RequireCors("MyCorsPolicy");
});
await app.RunAsync();

app.UseGraphQL("/graphql", config =>
{
    config.CsrfProtectionEnabled = false;
});

app.UseGraphQL("/graphql", config =>
{
    config.CsrfProtectionHeaders = ["MyCustomHeader"];
});

// add and configure the service
builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true; // may lead to CRIME and BREACH attacks
    options.MimeTypes = new[] { "application/json", "application/graphql-response+json" };
})

// place this first/early in the pipeline
app.UseResponseCompression();

services.AddHostApplicationLifetime();

Builder interface	Method	Description
`IGraphQLBuilder`	`AddUserContextBuilder`	Sets up a delegate to create the UserContext for each GraphQL request.
`IApplicationBuilder`	`UseGraphQL`	Adds the GraphQL middleware to the HTTP request pipeline.
`IEndpointRouteBuilder`	`MapGraphQL`	Adds the GraphQL middleware to the HTTP request pipeline.

Property	Description	Default value
`AuthorizationRequired`	Requires `HttpContext.User` to represent an authenticated user.	False
`AuthorizedPolicy`	If set, requires `HttpContext.User` to pass authorization of the specified policy.
`AuthorizedRoles`	If set, requires `HttpContext.User` to be a member of any one of a list of roles.
`CsrfProtectionEnabled`	Enables cross-site request forgery (CSRF) protection for both GET and POST requests.	True
`CsrfProtectionHeaders`	Sets the headers used for CSRF protection when necessary.	`GraphQL-Require-Preflight`
`DefaultResponseContentType`	Sets the default response content type used within responses.	`application/graphql-response+json; charset=utf-8`
`EnableBatchedRequests`	Enables handling of batched GraphQL requests for POST requests when formatted as JSON.	True
`ExecuteBatchedRequestsInParallel`	Enables parallel execution of batched GraphQL requests.	True
`HandleGet`	Enables handling of GET requests.	True
`HandlePost`	Enables handling of POST requests.	True
`HandleWebSockets`	Enables handling of WebSockets requests.	True
`MaximumFileSize`	Sets the maximum file size allowed for GraphQL multipart requests.	unlimited
`MaximumFileCount`	Sets the maximum number of files allowed for GraphQL multipart requests.	unlimited
`ReadExtensionsFromQueryString`	Enables reading extensions from the query string.	True
`ReadFormOnPost`	Enables parsing of form data for POST requests (may have security implications).	False
`ReadQueryStringOnPost`	Enables parsing the query string on POST requests.	True
`ReadVariablesFromQueryString`	Enables reading variables from the query string.	True
`ValidationErrorsReturnBadRequest`	When enabled, GraphQL requests with validation errors have the HTTP status code set to 400 Bad Request.	Automatic¹
`WebSockets`	Returns a set of configuration properties for WebSocket connections.

Property	Description	Default value
`ConnectionInitWaitTimeout`	The amount of time to wait for a GraphQL initialization packet before the connection is closed.	10 seconds
`DisconnectionTimeout`	The amount of time to wait to attempt a graceful teardown of the WebSockets protocol.	10 seconds
`DisconnectAfterErrorEvent`	Disconnects a subscription from the client if the subscription source dispatches an `OnError` event.	True
`DisconnectAfterAnyError`	Disconnects a subscription from the client if there are any GraphQL errors during a subscription.	False
`KeepAliveMode`	The mode to use for sending keep-alive packets.	protocol-dependent
`KeepAliveTimeout`	The amount of time to wait between sending keep-alive packets.	disabled
`SupportedWebSocketSubProtocols`	A list of supported WebSocket sub-protocols.	`graphql-ws`, `graphql-transport-ws`

var app = builder.Build();
app.UseDeveloperExceptionPage();
app.UseGraphQL<DogSchema>("/dogs/graphql");
app.UseGraphQL<CatSchema>("/cats/graphql");
await app.RunAsync();

var app = builder.Build();
app.UseDeveloperExceptionPage();
app.UseGraphQL("/graphql", options =>
{
    options.HandleGet = true;
    options.HandlePost = false;
    options.HandleWebSockets = false;
    options.AuthorizationRequired = false;
});
app.UseGraphQL("/graphql", options =>
{
    options.HandleGet = false;
    options.HandlePost = true;
    options.HandleWebSockets = true;
    options.AuthorizationRequired = true;   // require authentication for POST/WebSocket connections
});
await app.RunAsync();

builder.Services.AddGraphQL(b => b
    .AddSchema<MySchema>()
    .AddSystemTextJson()
    .AddAuthorizationRule()); // add authorization validation rule

var app = builder.Build();
app.UseDeveloperExceptionPage();
app.UseGraphQL();
await app.RunAsync();

// demonstration of code-first schema; also possible with schema-first or type-first schemas
public class MySchema : Schema
{
    public MySchema(IServiceProvider provider, MyQuery query, MyMutation mutation) : base(provider)
    {
        Query = query;
        Mutation = mutation;

        mutation.Authorize(); // require authorization for any mutation request
    }
}

Keep-alive mode	Description
`Default`	Same as `Timeout`.
`Timeout`	Sends a unidirectional keep-alive message when no message has been received within the specified timeout period.
`Interval`	Sends a unidirectional keep-alive message at a fixed interval, regardless of message activity.
`TimeoutWithPayload`	Sends a bidirectional keep-alive message with a payload on a fixed interval, and validates the payload matches in the response.

app.UseGraphQL("/graphql", options =>
{
    // configure keep-alive packets
    options.WebSockets.KeepAliveTimeout = TimeSpan.FromSeconds(10);
    options.WebSockets.KeepAliveMode = KeepAliveMode.TimeoutWithPayload;
    // set the supported sub-protocols to only include the graphql-transport-ws sub-protocol
    options.WebSockets.SupportedWebSocketSubProtocols = [GraphQLWs.SubscriptionServer.SubProtocol];
});

Method	Description
`InvokeAsync`	Entry point of the middleware
`HandleRequestAsync`	Handles a single GraphQL request.
`HandleBatchRequestAsync`	Handles a batched GraphQL request.
`HandleWebSocketAsync`	Handles a WebSocket connection request.
`BuildUserContextAsync`	Builds the user context based on a `HttpContext`.
`ExecuteRequestAsync`	Executes a GraphQL request.
`ExecuteScopedRequestAsync`	Executes a GraphQL request with a scoped service provider.
`SelectResponseContentType`	Selects a content-type header for the JSON-formatted GraphQL response.
`WriteErrorResponseAsync`	Writes the specified error message as a JSON-formatted GraphQL response, with the specified HTTP status code.
`WriteJsonResponseAsync`	Writes the specified object (usually a GraphQL response) as JSON to the HTTP response stream.

Error handling method	Description
`HandleBatchedRequestsNotSupportedAsync`	Writes a '400 Batched requests are not supported.' message to the output.
`HandleContentTypeCouldNotBeParsedErrorAsync`	Writes a '415 Invalid Content-Type header: could not be parsed.' message to the output.
`HandleDeserializationErrorAsync`	Writes a '400 JSON body text could not be parsed.' message to the output.
`HandleInvalidContentTypeErrorAsync`	Writes a '415 Invalid Content-Type header: non-supported type.' message to the output.
`HandleInvalidHttpMethodErrorAsync`	Indicates that an unsupported HTTP method was requested. Executes the next delegate in the chain by default.
`HandleWebSocketSubProtocolNotSupportedAsync`	Writes a '400 Invalid WebSocket sub-protocol.' message to the output.

class MyMiddleware<TSchema> : GraphQLHttpMiddleware<TSchema>
    where TSchema : ISchema
{
    public MyMiddleware(
        RequestDelegate next,
        IGraphQLTextSerializer serializer,
        IDocumentExecuter<TSchema> documentExecuter,
        IServiceScopeFactory serviceScopeFactory,
        GraphQLHttpMiddlewareOptions options,
        IHostApplicationLifetime hostApplicationLifetime)
        : base(next, serializer, documentExecuter, serviceScopeFactory, options, hostApplicationLifetime)
    {
    }

    protected override string SelectResponseContentType(HttpContext context)
        => "application/json";
}

app.UseGraphQL<MyMiddleware<ISchema>>("/graphql", new GraphQLHttpMiddlewareOptions());

Interface / Class	Description
`IWebSocketConnection`	Provides methods to send a message to a client or close the connection.
`IOperationMessageProcessor`	Handles incoming messages from the client.
`GraphQLWebSocketOptions`	Provides configuration options for WebSocket connections.
`WebSocketConnection`	Standard implementation of a message pump for `OperationMessage` messages across a WebSockets connection. Implements `IWebSocketConnection` and delivers messages to a specified `IOperationMessageProcessor`.
`BaseSubscriptionServer`	Abstract implementation of `IOperationMessageProcessor`, a message handler for `OperationMessage` messages. Provides base functionality for managing subscriptions and requests.
`GraphQLWs.SubscriptionServer`	Implementation of `IOperationMessageProcessor` for the `graphql-transport-ws` sub-protocol.
`SubscriptionsTransportWs.SubscriptionServer`	Implementation of `IOperationMessageProcessor` for the `graphql-ws` sub-protocol.
`IWebSocketAuthorizationService`	Allows authorization of GraphQL requests for WebSocket connections.

services.AddGraphQL(b => b
    .AddAutoSchema<Query>()
    .AddSystemTextJson()
    // configure queries for serial execution (optional)
    .AddExecutionStrategy<SerialExecutionStrategy>(OperationType.Query)
    // configure subscription field resolvers for scoped serial execution (parallel is optional)
    .AddScopedSubscriptionExecutionStrategy());

var app = builder.Build();
app.UseDeveloperExceptionPage();
app.UseIgnoreDisconnections();
app.UseWebSockets();
app.UseGraphQL();

services.AddGraphQL(b => b
    .AddAutoSchema<Query>()
    .AddFormFileGraphType()
    .AddSystemTextJson());

Name	Framework	Description
Authorization	.NET 8 Minimal	Based on the VS template, demonstrates authorization functionality with cookie-based authentication
Basic	.NET 8 Minimal	Demonstrates simplest possible implementation
Complex	.NET 3.1 / 6 / 8	Demonstrates older Program/Startup files and various configuration options, and multiple UI endpoints
Controller	.NET 8 Minimal	MVC implementation; does not include WebSocket support
Cors	.NET 8 Minimal	Demonstrates configuring a GraphQL endpoint to use a specified CORS policy
EndpointRouting	.NET 8 Minimal	Demonstrates configuring GraphQL through endpoint routing
HttpResult	.NET 8 Minimal	Demonstrates using `MapGet` and/or `MapPost` to return a GraphQL response
Jwt	.NET 8 Minimal	Demonstrates authenticating GraphQL requests with a JWT bearer token over HTTP POST and WebSocket connections
MultipleSchemas	.NET 8 Minimal	Demonstrates configuring multiple schemas within a single server
NativeAot	.NET 8 Slim	Demonstrates configuring GraphQL for Native AOT publishing
Net48	.NET Core 2.1 / .NET 4.8	Demonstrates configuring GraphQL on .NET 4.8 / Core 2.1
Pages	.NET 8 Minimal	Demonstrates configuring GraphQL on top of a Razor Pages template
Upload	.NET 8 Minimal	Demonstrates uploading files via the `multipart/form-data` content type

{
  count
}

{
  lastMessage {
    id
    message
    from
    sent
  }
}

mutation {
  addMessage(message: { message: "Hello", from: "John Doe" }) {
    id
  }
}

mutation {
  clearMessages
}

subscription {
  newMessages {
    id
    message
    from
    sent
  }
}

joemcbride/GraphQL.Server.Ui.Playgroundv8.3.3

Get Started

Readme

ASP.NET Core GraphQL Server driven by GraphQL.NET

Description

Migration from older version

Configuration

Typical configuration with HTTP middleware

Project file

Program.cs file

Schema

Sample request url

Sample response

Basic options

Configuration with endpoint routing

Configuration with route handlers (.NET 6+)

Using GraphQLExecutionHttpResult

Using ExecutionResultHttpResult

Configuration with a MVC controller

Using GraphQLExecutionActionResult

Using ExecutionResultActionResult

Configuration with Azure Functions

User context configuration

Program.cs / Startup.cs

MyUserContext.cs

Authorization configuration

Endpoint authorization (which would include introspection requests)

For individual graph types, fields and query arguments

Custom authentication configuration for GET/POST requests

Authentication for WebSocket requests

Authentication schemes

UI configuration

CORS configuration

Response compression

ASP.NET Core 2.1 / .NET Framework 4.8

Advanced configuration

Configuration options

GraphQLHttpMiddlewareOptions

GraphQLWebSocketOptions

Multi-schema configuration

Different global authorization settings for different transports (GET/POST/WebSockets)

Keep-alive configuration

Customizing middleware behavior

GraphQLHttpMiddleware

WebSocket handler classes

Additional notes / FAQ

Service scope

User context builder

Mutations within GET requests

Handling form data for POST requests

Excessive OperationCanceledExceptions

File uploading/downloading

Native AOT support

Samples

Queries

Return number of messages

Return last message

Mutations

Add a message

Clear all messages

Subscriptions

Contributors

Footnotes

Links

Keywords

Maintainers

Using `GraphQLExecutionHttpResult`

Using `ExecutionResultHttpResult`

Using `GraphQLExecutionActionResult`

Using `ExecutionResultActionResult`

Excessive `OperationCanceledException`s