diff --git a/website/config/conf.d/default.conf b/website/config/conf.d/default.conf index 34d6ee028a0..95935d7c0f4 100644 --- a/website/config/conf.d/default.conf +++ b/website/config/conf.d/default.conf @@ -139,6 +139,9 @@ server { # barista -> nitro rewrite ^/docs/barista/v1/commands(/.*)?$ /docs/nitro/cli-commands$1 permanent; rewrite ^/docs/barista/v1(/.*)?$ /docs/nitro/cli$1 permanent; + + # error-filter -> errors + rewrite ^/docs/hotchocolate/(v13|v14)/api-reference/error-filter/?$ /docs/hotchocolate/$1/api-reference/errors permanent; } location /img/projects { diff --git a/website/src/docs/docs.json b/website/src/docs/docs.json index f0ced98adea..7d22c543fa1 100644 --- a/website/src/docs/docs.json +++ b/website/src/docs/docs.json @@ -439,6 +439,10 @@ "path": "custom-attributes", "title": "Custom Attributes" }, + { + "path": "errors", + "title": "Errors" + }, { "path": "language", "title": "Language" @@ -785,6 +789,10 @@ "path": "custom-attributes", "title": "Custom Attributes" }, + { + "path": "errors", + "title": "Errors" + }, { "path": "language", "title": "Language" @@ -1111,6 +1119,10 @@ "path": "custom-attributes", "title": "Custom Attributes" }, + { + "path": "error-filter", + "title": "Error Filter" + }, { "path": "language", "title": "Language" @@ -1367,6 +1379,10 @@ "path": "custom-attributes", "title": "Custom Attributes" }, + { + "path": "error-filter", + "title": "Error Filter" + }, { "path": "language", "title": "Language" diff --git a/website/src/docs/hotchocolate/v10/execution-engine/error-filter.md b/website/src/docs/hotchocolate/v10/execution-engine/error-filter.md index 6815005afac..d147e3a7a46 100644 --- a/website/src/docs/hotchocolate/v10/execution-engine/error-filter.md +++ b/website/src/docs/hotchocolate/v10/execution-engine/error-filter.md @@ -2,20 +2,21 @@ title: Error Filter --- -GraphQL errors in Hot Chocolate are passed to the query result by returning an instance of `IError` or an enumerable of `IError` in a field resolver. +GraphQL errors in Hot Chocolate are passed to the operation result by returning an instance of `IError` or an enumerable of `IError` in a field resolver. -Moreover, you can throw a `QueryException` that will be be caught by the query engine and translated to a field error. +Moreover, you can throw a `QueryException` that will be be caught by the execution engine and translated to a field error. -One further way to raise an error are non-terminating field errors. This can be raised by using `IResolverContext.RaiseError`. So, with this you can provide a result and raise an error for your current field. +One further way to raise an error are non-terminating field errors. This can be raised by using `IResolverContext.RaiseError`. With this you can provide a result and raise an error for your current field. > If you do want to log errors head over to our diagnostic source [documentation](/docs/hotchocolate/v10/execution-engine/instrumentation) and see how you can hook up your logging framework of choice to it. # Error Builder -Since, errors can have a lot of properties depending on your case we have introduced a new error builder which provides a nice API without thousands of overloads. +Since errors can have a lot of properties, we have introduced a new error builder which provides a nice API without thousands of overloads. ```csharp -return ErrorBuilder.New() +var error = ErrorBuilder + .New() .SetMessage("This is my error.") .SetCode("FOO_BAR") .Build(); @@ -23,7 +24,7 @@ return ErrorBuilder.New() # Exceptions -If some other exception is thrown during the query execution, then the execution engine will create an instance of `IError` with the message **Unexpected Execution Error** and the actual exception assigned to the error. However, the exception details will not be serialized so by default the user will only see the error message **Unexpected Execution Error**. +If some other exception is thrown during execution, then the execution engine will create an instance of `IError` with the message **Unexpected Execution Error** and the actual exception assigned to the error. However, the exception details will not be serialized so by default the user will only see the error message **Unexpected Execution Error**. If you want to translate exceptions into errors with useful information then you can write an `IErrorFilter`. @@ -59,7 +60,8 @@ IQueryExecuter executer = schema.MakeExecutable(builder => Since errors are immutable we have added some helper functions like `WithMessage`, `WithCode` and so on that create a new error with the desired properties. Moreover, you can create an error builder from an error and modify multiple properties and then rebuild the error object. ```csharp -return ErrorBuilder.FromError(error) +return ErrorBuilder + .FromError(error) .SetMessage("This is my error.") .SetCode("FOO_BAR") .Build(); @@ -70,8 +72,9 @@ return ErrorBuilder.FromError(error) In order to automatically add exception details to your GraphQL error you can switch the execution option to include exception details. By default we will switch this on if the debugger is attached. You can overwrite the behavior by setting the option. ```csharp -SchemaBuilder.New() - ... +SchemaBuilder + .New() + // ... .Create() .MakeExecutable(new QueryExecutionOptions { diff --git a/website/src/docs/hotchocolate/v11/api-reference/error-filter.md b/website/src/docs/hotchocolate/v11/api-reference/error-filter.md index 89cb7103774..496b39ed20b 100644 --- a/website/src/docs/hotchocolate/v11/api-reference/error-filter.md +++ b/website/src/docs/hotchocolate/v11/api-reference/error-filter.md @@ -2,20 +2,21 @@ title: Error Filter --- -GraphQL errors in Hot Chocolate are passed to the query result by returning an instance of `IError` or an enumerable of `IError` in a field resolver. +GraphQL errors in Hot Chocolate are passed to the operation result by returning an instance of `IError` or an enumerable of `IError` in a field resolver. -Moreover, you can throw a `QueryException` that will be be caught by the query engine and translated to a field error. +Moreover, you can throw a `QueryException` that will be be caught by the execution engine and translated to a field error. -One further way to raise an error are non-terminating field errors. This can be raised by using `IResolverContext.RaiseError`. So, with this you can provide a result and raise an error for your current field. +One further way to raise an error are non-terminating field errors. This can be raised by using `IResolverContext.RaiseError`. With this you can provide a result and raise an error for your current field. > If you do want to log errors head over to our diagnostic source [documentation](/docs/hotchocolate/v10/execution-engine/instrumentation) and see how you can hook up your logging framework of choice to it. # Error Builder -Since, errors can have a lot of properties depending on your case we have introduced a new error builder which provides a nice API without thousands of overloads. +Since errors can have a lot of properties, we have introduced a new error builder which provides a nice API without thousands of overloads. ```csharp -return ErrorBuilder.New() +var error = ErrorBuilder + .New() .SetMessage("This is my error.") .SetCode("FOO_BAR") .Build(); @@ -23,7 +24,7 @@ return ErrorBuilder.New() # Exceptions -If some other exception is thrown during the query execution, then the execution engine will create an instance of `IError` with the message **Unexpected Execution Error** and the actual exception assigned to the error. However, the exception details will not be serialized so by default the user will only see the error message **Unexpected Execution Error**. +If some other exception is thrown during execution, then the execution engine will create an instance of `IError` with the message **Unexpected Execution Error** and the actual exception assigned to the error. However, the exception details will not be serialized so by default the user will only see the error message **Unexpected Execution Error**. If you want to translate exceptions into errors with useful information then you can write an `IErrorFilter`. @@ -70,8 +71,9 @@ return ErrorBuilder.FromError(error) In order to automatically add exception details to your GraphQL error you can switch the execution option to include exception details. By default we will switch this on if the debugger is attached. You can overwrite the behavior by setting the option. ```csharp -SchemaBuilder.New() - ... +SchemaBuilder + .New() + // ... .Create() .MakeExecutable(new QueryExecutionOptions { diff --git a/website/src/docs/hotchocolate/v12/api-reference/error-filter.md b/website/src/docs/hotchocolate/v12/api-reference/error-filter.md index 89cb7103774..231d01bc2f4 100644 --- a/website/src/docs/hotchocolate/v12/api-reference/error-filter.md +++ b/website/src/docs/hotchocolate/v12/api-reference/error-filter.md @@ -2,20 +2,21 @@ title: Error Filter --- -GraphQL errors in Hot Chocolate are passed to the query result by returning an instance of `IError` or an enumerable of `IError` in a field resolver. +GraphQL errors in Hot Chocolate are passed to the operation result by returning an instance of `IError` or an enumerable of `IError` in a field resolver. -Moreover, you can throw a `QueryException` that will be be caught by the query engine and translated to a field error. +Moreover, you can throw a `QueryException` that will be be caught by the execution engine and translated to a field error. -One further way to raise an error are non-terminating field errors. This can be raised by using `IResolverContext.RaiseError`. So, with this you can provide a result and raise an error for your current field. +One further way to raise an error are non-terminating field errors. This can be raised by using `IResolverContext.RaiseError`. With this you can provide a result and raise an error for your current field. > If you do want to log errors head over to our diagnostic source [documentation](/docs/hotchocolate/v10/execution-engine/instrumentation) and see how you can hook up your logging framework of choice to it. # Error Builder -Since, errors can have a lot of properties depending on your case we have introduced a new error builder which provides a nice API without thousands of overloads. +Since errors can have a lot of properties, we have introduced a new error builder which provides a nice API without thousands of overloads. ```csharp -return ErrorBuilder.New() +var error = ErrorBuilder + .New() .SetMessage("This is my error.") .SetCode("FOO_BAR") .Build(); @@ -23,7 +24,7 @@ return ErrorBuilder.New() # Exceptions -If some other exception is thrown during the query execution, then the execution engine will create an instance of `IError` with the message **Unexpected Execution Error** and the actual exception assigned to the error. However, the exception details will not be serialized so by default the user will only see the error message **Unexpected Execution Error**. +If some other exception is thrown during execution, then the execution engine will create an instance of `IError` with the message **Unexpected Execution Error** and the actual exception assigned to the error. However, the exception details will not be serialized so by default the user will only see the error message **Unexpected Execution Error**. If you want to translate exceptions into errors with useful information then you can write an `IErrorFilter`. @@ -59,7 +60,8 @@ IQueryExecuter executer = schema.MakeExecutable(builder => Since errors are immutable we have added some helper functions like `WithMessage`, `WithCode` and so on that create a new error with the desired properties. Moreover, you can create an error builder from an error and modify multiple properties and then rebuild the error object. ```csharp -return ErrorBuilder.FromError(error) +return ErrorBuilder + .FromError(error) .SetMessage("This is my error.") .SetCode("FOO_BAR") .Build(); @@ -70,8 +72,9 @@ return ErrorBuilder.FromError(error) In order to automatically add exception details to your GraphQL error you can switch the execution option to include exception details. By default we will switch this on if the debugger is attached. You can overwrite the behavior by setting the option. ```csharp -SchemaBuilder.New() - ... +SchemaBuilder + .New() + // ... .Create() .MakeExecutable(new QueryExecutionOptions { diff --git a/website/src/docs/hotchocolate/v13/api-reference/error-filter.md b/website/src/docs/hotchocolate/v13/api-reference/error-filter.md deleted file mode 100644 index 37ffe3e64b8..00000000000 --- a/website/src/docs/hotchocolate/v13/api-reference/error-filter.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Error Filter ---- - -GraphQL errors in Hot Chocolate are passed to the query result by returning an instance of `IError` or an enumerable of `IError` in a field resolver. - -Moreover, you can throw a `QueryException` that will be be caught by the query engine and translated to a field error. - -One further way to raise an error are non-terminating field errors. This can be raised by using `IResolverContext.ReportError`. So, with this you can provide a result and raise an error for your current field. - -> If you do want to log errors head over to our diagnostic source [documentation](/docs/hotchocolate/v13/server/instrumentation) and see how you can hook up your logging framework of choice to it. - -# Error Builder - -Since, errors can have a lot of properties depending on your case we have introduced a new error builder which provides a nice API without thousands of overloads. - -```csharp -return ErrorBuilder.New() - .SetMessage("This is my error.") - .SetCode("FOO_BAR") - .Build(); -``` - -# Exceptions - -If some other exception is thrown during the query execution, then the execution engine will create an instance of `IError` with the message **Unexpected Execution Error** and the actual exception assigned to the error. However, the exception details will not be serialized so by default the user will only see the error message **Unexpected Execution Error**. - -If you want to translate exceptions into errors with useful information then you can write an `IErrorFilter`. - -An error filter has to be registered with the execution builder or with your dependency injection. - -```csharp -IQueryExecuter executer = schema.MakeExecutable(builder => - builder.UseDefaultPipeline(options) - .AddErrorFilter()); -``` - -OR - -```csharp -services.AddErrorFilter(); -``` - -It is also possible to just register the error filter as a delegate like the following. - -```csharp -IQueryExecuter executer = schema.MakeExecutable(builder => - builder.UseDefaultPipeline(options) - .AddErrorFilter(error => - { - if (error.Exception is NullReferenceException) - { - return error.WithCode("NullRef"); - } - return error; - })); -``` - -Since errors are immutable we have added some helper functions like `WithMessage`, `WithCode` and so on that create a new error with the desired properties. Moreover, you can create an error builder from an error and modify multiple properties and then rebuild the error object. - -```csharp -return ErrorBuilder.FromError(error) - .SetMessage("This is my error.") - .SetCode("FOO_BAR") - .Build(); -``` - -# Exception Details - -In order to automatically add exception details to your GraphQL error you can switch the execution option to include exception details. By default we will switch this on if the debugger is attached. You can overwrite the behavior by setting the option. - -```csharp -SchemaBuilder.New() - ... - .Create() - .MakeExecutable(new QueryExecutionOptions - { - IncludeExceptionDetails = true - }); -``` diff --git a/website/src/docs/hotchocolate/v13/api-reference/errors.md b/website/src/docs/hotchocolate/v13/api-reference/errors.md new file mode 100644 index 00000000000..04d5707d1b9 --- /dev/null +++ b/website/src/docs/hotchocolate/v13/api-reference/errors.md @@ -0,0 +1,71 @@ +--- +title: Errors +--- + +GraphQL errors in Hot Chocolate are passed to the operation result by returning an instance of `IError` or an enumerable of `IError` in a field resolver. + +Moreover, you can throw a `QueryException` that will be be caught by the execution engine and translated to a field error. + +One further way to raise an error are non-terminating field errors. This can be raised by using `IResolverContext.ReportError`. With this you can provide a result and raise an error for your current field. + +> If you do want to log errors head over to our diagnostic source [documentation](/docs/hotchocolate/v13/server/instrumentation) and see how you can hook up your logging framework of choice to it. + +# Error Builder + +Since errors can have a lot of properties, we have introduced a new error builder which provides a nice API without thousands of overloads. + +```csharp +var error = ErrorBuilder + .New() + .SetMessage("This is my error.") + .SetCode("FOO_BAR") + .Build(); +``` + +# Error Filters + +If some other exception is thrown during execution, then the execution engine will create an instance of `IError` with the message **Unexpected Execution Error** and the actual exception assigned to the error. However, the exception details will not be serialized so by default the user will only see the error message **Unexpected Execution Error**. + +If you want to translate exceptions into errors with useful information then you can write an `IErrorFilter`. + +An error filter has to be registered as a service. + +```csharp +builder.Services.AddErrorFilter(); +``` + +It is also possible to just register the error filter as a delegate like the following. + +```csharp +builder.Services.AddErrorFilter(error => +{ + if (error.Exception is NullReferenceException) + { + return error.WithCode("NullRef"); + } + + return error; +}); +``` + +Since errors are immutable we have added some helper functions like `WithMessage`, `WithCode` and so on that create a new error with the desired properties. Moreover, you can create an error builder from an error and modify multiple properties and then rebuild the error object. + +```csharp +return ErrorBuilder + .FromError(error) + .SetMessage("This is my error.") + .SetCode("FOO_BAR") + .Build(); +``` + +# Exception Details + +In order to automatically add exception details to your GraphQL errors, you can enable the `IncludeExceptionDetails` option. By default this will be enabled when the debugger is attached. + +```csharp +builder + .AddGraphQL() + .ModifyRequestOptions( + o => o.IncludeExceptionDetails = + builder.Environment.IsDevelopment()); +``` diff --git a/website/src/docs/hotchocolate/v14/api-reference/error-filter.md b/website/src/docs/hotchocolate/v14/api-reference/error-filter.md deleted file mode 100644 index cb068159e82..00000000000 --- a/website/src/docs/hotchocolate/v14/api-reference/error-filter.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Error Filter ---- - -GraphQL errors in Hot Chocolate are passed to the query result by returning an instance of `IError` or an enumerable of `IError` in a field resolver. - -Moreover, you can throw a `QueryException` that will be be caught by the query engine and translated to a field error. - -One further way to raise an error are non-terminating field errors. This can be raised by using `IResolverContext.ReportError`. So, with this you can provide a result and raise an error for your current field. - -> If you do want to log errors head over to our diagnostic source [documentation](/docs/hotchocolate/v14/server/instrumentation) and see how you can hook up your logging framework of choice to it. - -# Error Builder - -Since, errors can have a lot of properties depending on your case we have introduced a new error builder which provides a nice API without thousands of overloads. - -```csharp -return ErrorBuilder.New() - .SetMessage("This is my error.") - .SetCode("FOO_BAR") - .Build(); -``` - -# Exceptions - -If some other exception is thrown during the query execution, then the execution engine will create an instance of `IError` with the message **Unexpected Execution Error** and the actual exception assigned to the error. However, the exception details will not be serialized so by default the user will only see the error message **Unexpected Execution Error**. - -If you want to translate exceptions into errors with useful information then you can write an `IErrorFilter`. - -An error filter has to be registered with the execution builder or with your dependency injection. - -```csharp -IQueryExecuter executer = schema.MakeExecutable(builder => - builder.UseDefaultPipeline(options) - .AddErrorFilter()); -``` - -OR - -```csharp -builder.Services.AddErrorFilter(); -``` - -It is also possible to just register the error filter as a delegate like the following. - -```csharp -IQueryExecuter executer = schema.MakeExecutable(builder => - builder.UseDefaultPipeline(options) - .AddErrorFilter(error => - { - if (error.Exception is NullReferenceException) - { - return error.WithCode("NullRef"); - } - return error; - })); -``` - -Since errors are immutable we have added some helper functions like `WithMessage`, `WithCode` and so on that create a new error with the desired properties. Moreover, you can create an error builder from an error and modify multiple properties and then rebuild the error object. - -```csharp -return ErrorBuilder.FromError(error) - .SetMessage("This is my error.") - .SetCode("FOO_BAR") - .Build(); -``` - -# Exception Details - -In order to automatically add exception details to your GraphQL error you can switch the execution option to include exception details. By default we will switch this on if the debugger is attached. You can overwrite the behavior by setting the option. - -```csharp -SchemaBuilder.New() - ... - .Create() - .MakeExecutable(new QueryExecutionOptions - { - IncludeExceptionDetails = true - }); -``` diff --git a/website/src/docs/hotchocolate/v14/api-reference/errors.md b/website/src/docs/hotchocolate/v14/api-reference/errors.md new file mode 100644 index 00000000000..e519c7ada78 --- /dev/null +++ b/website/src/docs/hotchocolate/v14/api-reference/errors.md @@ -0,0 +1,71 @@ +--- +title: Errors +--- + +GraphQL errors in Hot Chocolate are passed to the operation result by returning an instance of `IError` or an enumerable of `IError` in a field resolver. + +Moreover, you can throw a `GraphQLException` that will be be caught by the execution engine and translated to a field error. + +One further way to raise an error are non-terminating field errors. This can be raised by using `IResolverContext.ReportError`. With this you can provide a result and raise an error for your current field. + +> If you do want to log errors head over to our diagnostic source [documentation](/docs/hotchocolate/v14/server/instrumentation) and see how you can hook up your logging framework of choice to it. + +# Error Builder + +Since errors can have a lot of properties, we have introduced a new error builder which provides a nice API without thousands of overloads. + +```csharp +var error = ErrorBuilder + .New() + .SetMessage("This is my error.") + .SetCode("FOO_BAR") + .Build(); +``` + +# Error Filters + +If some other exception is thrown during execution, then the execution engine will create an instance of `IError` with the message **Unexpected Execution Error** and the actual exception assigned to the error. However, the exception details will not be serialized so by default the user will only see the error message **Unexpected Execution Error**. + +If you want to translate exceptions into errors with useful information then you can write an `IErrorFilter`. + +An error filter has to be registered as a service. + +```csharp +builder.Services.AddErrorFilter(); +``` + +It is also possible to just register the error filter as a delegate like the following. + +```csharp +builder.Services.AddErrorFilter(error => +{ + if (error.Exception is NullReferenceException) + { + return error.WithCode("NullRef"); + } + + return error; +}); +``` + +Since errors are immutable we have added some helper functions like `WithMessage`, `WithCode` and so on that create a new error with the desired properties. Moreover, you can create an error builder from an error and modify multiple properties and then rebuild the error object. + +```csharp +return ErrorBuilder + .FromError(error) + .SetMessage("This is my error.") + .SetCode("FOO_BAR") + .Build(); +``` + +# Exception Details + +In order to automatically add exception details to your GraphQL errors, you can enable the `IncludeExceptionDetails` option. By default this will be enabled when the debugger is attached. + +```csharp +builder + .AddGraphQL() + .ModifyRequestOptions( + o => o.IncludeExceptionDetails = + builder.Environment.IsDevelopment()); +```