FluentGraphQL netstandard2.1 v2.0.0

API Reference

Type-safe GraphQL, written as a fluent chain.

Describe a query with lambda selectors and anonymous arguments — get a valid, escaped GraphQL document plus its variables. No expression trees, no reflection on the hot path.

Program.csC#
var builder = new GraphQLQueryBuilder();

builder
    .AddVariable("cities", GraphQLParameterType.STRING_ARRAY, new[] { "Paris" })
    .AddQuery(new GraphQLQueryObject<Account>("accounts")
        .AddField(a => a.Id)
        .AddField(a => a.SocietyName)
        .AddCollectionField(a => a.Contacts, c => c
            .AddField(x => x.Email))
        .WithArguments(new { where = new { city = new { @in = Var("cities") } } }));

string query = builder.Query;
output.graphqlGraphQL
query ($cities: [String]!) {
  accounts(where: { city: { in: $cities } }) {
    id
    societyName
    contacts {
      email
    }
  }
}

Entry point

Where a query starts — and where variables are referenced.

static class

GraphQL

Static entry points for the fluent GraphQL API. A string that is not a Var is always treated as a literal, escaped value.

static GraphQLVariable Var(string name) method

References a variable previously declared with AddVariable. Rendered as $name.

name
The variable name (without the leading $) to reference.
returnsA reference usable inside an argument object, rendered as $name.

Builder

Assembles the document and its variables.

class

GraphQLQueryBuilder

Builds a GraphQL query or mutation and its variables from a fluent, strongly-typed description. Configure it on one thread; once configured, Query and Variables may be read concurrently — they allocate their own output and never mutate shared state. Do not add queries or variables while another thread is reading.

GraphQLQueryBuilder(bool mutation = false)constructor

Creates a builder for a query, or for a mutation when mutation is true.

mutation
Whether to emit a mutation rather than a query.
string Query { get; }property

The generated GraphQL document. Built on each access.

JsonObject Variables { get; }property

The declared variables and their values, camelCased, ready to send alongside Query.

GraphQLRequest Request { get; }property

The Query and Variables bundled as a request payload.

int QueriesCount { get; }property

The number of root queries (or mutations) currently added.

GraphQLQueryBuilder AddQuery<T>(GraphQLQueryObject<T> queryObject)method

Adds a root query (or mutation) object.

T type
The type selected by the query object.
queryObject
The root query to add.
returnsThe same builder, to continue chaining.
throwsInvalidOperationException — a query with the same name or alias was already added.
GraphQLQueryBuilder AddVariable(string name, object value)method

Declares a variable, inferring its GraphQL type from the value's CLR type.

name
The variable name (without the leading $).
value
The variable value; its CLR type determines the GraphQL type.
returnsThe same builder, to continue chaining.
GraphQLQueryBuilder AddVariable(string name, GraphQLParameterType type, object value)method

Declares a variable with an explicit GraphQL type, rather than inferring it from the value.

name
The variable name (without the leading $).
type
The explicit GraphQL type of the variable.
value
The variable value.
returnsThe same builder, to continue chaining.
GraphQLQueryBuilder AddVariable(GraphQLParameter parameter)method

Declares a variable from a pre-built parameter.

parameter
The variable to declare.
returnsThe same builder, to continue chaining.
GraphQLQueryBuilder AddVariables(params GraphQLParameter[] parameters)method

Declares several variables in one call.

parameters
The variables to declare.
returnsThe same builder, to continue chaining.

Selection · root

Selects fields on a root query object.

class

GraphQLQueryObject<T>

A root query (or mutation) object selecting fields of T. T is the type whose fields are selected.

GraphQLQueryObject<T>(string name)constructor

Creates a query object for the given GraphQL field name.

name
The GraphQL field name this query targets.
…<T> AddField<TProperty>(Func<T, TProperty> selector, string aliasName = null)method

Selects a scalar field, e.g. AddField(x => x.Id).

TProperty type
Type of the selected field.
selector
The field to select, e.g. x => x.Id.
aliasName
Optional alias rendered as alias: field.
selectorText auto
Compiler-supplied from selector; leave unset.
returnsThe same query object, to continue chaining.
…<T> AddField<TProperty>(Func<T, TProperty> selector, Func<…> complexPropertySelector, string aliasName = null)method

Selects a nested object field and its sub-selection, e.g. AddField(x => x.Adresse, a => a.AddField(v => v.City)).

TProperty type
Type of the nested object field.
selector
The nested field to select, e.g. x => x.Adresse.
complexPropertySelector
Builds the sub-selection of the nested field.
aliasName
Optional alias rendered as alias: field.
selectorText auto
Compiler-supplied from selector; leave unset.
returnsThe same query object, to continue chaining.
…<T> AddCollectionField<TProperty>(Func<T, IEnumerable<TProperty>> selector, Func<…> complexPropertySelector, string aliasName = null)method

Selects a collection field and its sub-selection, e.g. AddCollectionField(x => x.Contacts, c => c.AddEveryFields()).

TProperty type
Element type of the selected collection.
selector
The collection to select, e.g. x => x.Contacts.
complexPropertySelector
Builds the sub-selection of each element.
aliasName
Optional alias rendered as alias: field.
selectorText auto
Compiler-supplied from selector; leave unset.
returnsThe same query object, to continue chaining.
…<T> WithArguments<TArguments>(TArguments arguments)method

Sets the query arguments from an anonymous object. Use Var for variable references.

TArguments type
Type of the arguments object.
arguments
The arguments as an anonymous object, e.g. new { where = new { id = new { eq = 1 } } }.
returnsThe same query object, to continue chaining.
…<T> As(string aliasName)method

Gives this query an alias (rendered as alias: name).

aliasName
The alias; ignored when null or whitespace.
returnsThe same query object, to continue chaining.
…<T> AddEveryFields()method

Selects every scalar and enum property of T.

returnsThe same query object, to continue chaining.
…<T> Except<TProperty>(Func<T, TProperty> selector)method

Removes a previously selected field (e.g. after AddEveryFields).

TProperty type
Type of the field being removed.
selector
The field to remove, e.g. x => x.Name.
selectorText auto
Compiler-supplied from selector; leave unset.
returnsThe same query object, to continue chaining.

Selection · nested

Selects sub-fields inside a nested object or collection.

class

GraphQLQueryObjectField<T>

Builds the sub-selection of a nested object or collection field of element type T. The non-generic GraphQLQueryObjectField is a selected field that may itself carry a nested selection.

…<T> AddField<TProperty>(Func<T, TProperty> selector, string aliasName = null)method

Selects a scalar sub-field.

TProperty type
Type of the selected sub-field.
selector
The sub-field to select, e.g. x => x.Id.
aliasName
Optional alias rendered as alias: field.
selectorText auto
Compiler-supplied from selector; leave unset.
returnsThe same field, to continue chaining.
…<T> AddField<TProperty>(Func<T, TProperty> selector, Func<…> complexPropertySelector, string aliasName = null)method

Selects a nested object sub-field and its sub-selection.

TProperty type
Type of the nested object sub-field.
selector
The nested sub-field to select, e.g. x => x.Adresse.
complexPropertySelector
Builds the sub-selection of the nested field.
aliasName
Optional alias rendered as alias: field.
selectorText auto
Compiler-supplied from selector; leave unset.
returnsThe same field, to continue chaining.
…<T> AddCollectionField<TProperty>(Func<T, IEnumerable<TProperty>> selector, Func<…> complexPropertySelector, string aliasName = null)method

Selects a nested collection field and its sub-selection.

TProperty type
Element type of the nested collection.
selector
The collection to select, e.g. x => x.Tasks.
complexPropertySelector
Builds the sub-selection of each element.
aliasName
Optional alias rendered as alias: field.
selectorText auto
Compiler-supplied from selector; leave unset.
returnsThe same field, to continue chaining.
…<T> AddField<TProperty, TArguments>(Func<T, IEnumerable<TProperty>> selector, TArguments arguments, Func<…> complexPropertySelector, string aliasName = null)method

Selects a nested collection field carrying its own arguments, plus its sub-selection.

TProperty type
Element type of the nested collection.
TArguments type
Type of the arguments object.
selector
The collection to select, e.g. x => x.Tasks.
arguments
The field arguments as an anonymous object; use Var for variable references.
complexPropertySelector
Builds the sub-selection of each element.
aliasName
Optional alias rendered as alias: field.
selectorText auto
Compiler-supplied from selector; leave unset.
returnsThe same field, to continue chaining.
…<T> AddEveryFields()method

Selects every scalar and enum property of T.

returnsThe same field, to continue chaining.

Variables

The variable value types.

sealed class

GraphQLVariable

A reference to a declared GraphQL variable, produced by GraphQL.Var. Pass it inside an arguments object to render $name.

class

GraphQLParameter

A declared GraphQL variable: its name, value, and (optionally) explicit type. A null Type means the type is inferred from the value.

enum

GraphQLParameterType

Explicit GraphQL type of a variable, used by the AddVariable(name, type, value) overload.

INTFLOATSTRINGBOOLEANDATETIMEUUID INT_ARRAYFLOAT_ARRAYSTRING_ARRAYDATETIME_ARRAYOBJECT

Request

Sending and receiving.

class

GraphQLRequest

A GraphQL request payload: the query document and its variables. Read it straight off the builder via builder.Request.

class

GraphQLRequestData<T>

Envelope for deserializing a GraphQL response's data field into T.

Base types

Shared foundations — rarely used directly.

abstract

GraphQLObject

Base for anything that has a name, an optional alias, arguments and a nested field selection.

abstract GraphQLBuilderabstract

Base builder holding the declared variables shared by query and mutation builders.

abstract GraphQLQueryObjectabstract

Non-generic base for root query objects, so a builder can hold queries of different types.