Enums

The ENUM graph type is represented by an enum type in .NET. The naming and exclusion rules used with object types apply in the same manner to enums.

By Default:

• An ENUM graph type will have the same name as its enum type in your code.
• All declared enum values are included, including compound values.

DonutType.cs

public enum DonutType
{
    Glazed,
    Cake,
    Custard,
    Jelly,
    SugarCoated,
}

DonutType Type Definition

enum DonutType {
  GLAZED
  CAKE
  CUSTARD
  JELLY
  SUGARCOATED
}

Compound Values are represented as their own enum value option.

DonutType.cs

public enum DonutType
{
    Glazed,
    Cake,
    Custard,
    Jelly,
    SugarCoated,
    Filled = Custard | Jelly
}

DonutType Type Definition

enum DonutType {
  GLAZED
  CAKE
  CUSTARD
  JELLY
  SUGARCOATED
  FILLED
}

Including an Enum in Your Schema

An enum graph type is automatically created from a .NET enum if it is:

• Used as a parameter to an action method
• Used as a return value of an action method
• Used as a parameter or return type of any property or method of any included class or struct.

DonutController.cs

public class DonutController : GraphController 
{
  [QueryRoot]
  public int RetrieveDonutCount(DonutType donutType)
  {
    /* ... */
  }
}

You can also explicitly add an enum at start up:

Startup code

services.AddGraphQL(options => 
{
   options.AddGraphType<DonutType>();
});

Excluding an Enum Value

Use the [GraphSkip] attribute to omit a value from the schema. A query will be rejected if it attempts to submit an omitted enum value.

DonutType.cs

public enum DonutType
{
    Glazed,
    Cake,
    Custard,
    Jelly,

    [GraphSkip]
    SugarCoated,
}

DonutType Type Definition

# Sugar Coated is not part of the enum type
enum DonutType {
  GLAZED
  CAKE
  CUSTARD
  JELLY
}

caution

An excluded enum value is not just hidden, its NOT part of the schema. Any attempt to use it as a value in a query, a variable or as a result from a field resolution will cause a validation error.

Custom Type Name

Like with other graph types, use the [GraphType] attribute to indicate a custom name for the enum in the schema.

DonutType.cs

[GraphType("Donut_Type")]
public enum DonutType
{
    Glazed,
    Cake,
    Custard,
    Jelly,
    SugarCoated,
}

DonutType Type Definition

enum Donut_Type {
  GLAZED
  CAKE
  CUSTARD
  JELLY
  SUGARCOATED
}

Custom Value Names

Use [GraphEnumValue] to declare a custom name for the enum value and GraphQL will automatically handle the name translation when parsing a query document. A target schema's naming format rules will be applied and enforced on the value provided.

DonutType.cs

public enum DonutType
{
    Glazed,
    Cake,
    Custard,
    Jelly,

    [GraphEnumValue("Sugar_Coated")]
    SugarCoated,
}

DonutType Type Definition

enum DonutType {
  GLAZED
  CAKE
  CUSTARD
  JELLY
  SUGAR_COATED
}

Value Name Formatting

By default, enum values are rendered in all CAPITAL LETTERS. This is the standard convention for GraphQL. If, however; you'd prefer something different you can override the defaults by creating a new GraphNameFormatter on your schema configuration.

Startup Code

services.AddGraphQL(o => {
  var customFormatter = new GraphNameFormatter(enumValueStrategy: GraphNameFormatStrategy.ProperCase);
  o.DeclarationOptions.GraphNamingFormatter = customFormatter;
})

Sample Formatting

enum DonutType {
  Glazed
  Cake
  Custard
  Jelly
}

tip

If you need something even more exotic, inherit from GraphNameFormatter and override the various methods as you see fit.