Asp net коды ошибок

Обработка ошибок

Данное руководство устарело. Актуальное руководство: Руководство по ASP.NET Core 7

Последнее обновление: 06.11.2019

Ошибки в приложении можно условно разделить на два типа: исключения, которые возникают в процессе выполнения кода (например, деление на 0), и
стандартные ошибки протокола HTTP (например, ошибка 404).

Обычные исключения могут быть полезны для разработчика в процессе создания приложения, но простые пользователи не должны будут их видеть.

UseDeveloperExceptionPage

Если мы создаем проект ASP.NET Core, например, по типу Empty (да и в других типах проектов), то в классе Startup мы можем найти в начале метода Configure() следующие строки:

if (env.IsDevelopment())
{
	app.UseDeveloperExceptionPage();
}

Если приложение находится в состоянии разработки, то с помощью middleware app.UseDeveloperExceptionPage() приложение перехватывает исключения и
выводит информацию о них разработчику.

Например, изменим класс Startup следующим образом:

public class Startup
{
	public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
	{
		if (env.IsDevelopment())
		{
			app.UseDeveloperExceptionPage();
		}
		app.Run(async (context) =>
		{
			int x = 0;
			int y = 8 / x;
			await context.Response.WriteAsync($"Result = {y}");
		});
	}
}

В middleware app.Run симулируется генерация исключения при делении ноль. И если мы запустим проект, то в браузере мы увидим
информацию об исключении:

Этой информации достаточно, чтобы определить где именно в коде произошло исключение.

Теперь посмотрим, как все это будет выглядеть для простого пользователя. Для этого изменим метод Configure:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
	env.EnvironmentName = "Production";
	if (env.IsDevelopment())
	{
		app.UseDeveloperExceptionPage();
	}
	app.Run(async (context) =>
	{
		int x = 0;
		int y = 8 / x;
		await context.Response.WriteAsync($"Result = {y}");
	});
}

Выражение env.EnvironmentName = "Production"; устанавливает режим развертывания вместо режима разработки. В этом случае выражение if (env.IsDevelopment()) будет возвращать false, и мы увидим в браузере что-то наподобие «HTTP ERROR 500»

UseExceptionHandler

Это не самая лучшая ситуация, и нередко все-таки возникает необходимость дать пользователям некоторую информацию о том, что же все-таки произошло. Либо потребуется как-то обработать данную ситуацию.
Для этих целей можно использовать еще один встроенный middleware в виде метода UseExceptionHandler(). Он перенаправляет
при возникновении исключения на некоторый адрес и позволяет обработать исключение. Например, изменим метод Configure следующим образом:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
	env.EnvironmentName = "Production";
	
	if (env.IsDevelopment())
	{
		app.UseDeveloperExceptionPage();
	}
	else
	{
		app.UseExceptionHandler("/error");
	}
	
	app.Map("/error", ap => ap.Run(async context =>
	{
		await context.Response.WriteAsync("DivideByZeroException occured!");
	}));
	
	app.Run(async (context) =>
	{
		int x = 0;
		int y = 8 / x;
		await context.Response.WriteAsync($"Result = {y}");
	});
}

Метод app.UseExceptionHandler("/error"); перенаправляет при возникновении ошибки на адрес «/error».

Для обработки пути по определенному адресу здесь использовался метод app.Map(). В итоге при возникновении исключения будет срабатывать делегат
из метода app.Map.

Следует учитывать, что оба middleware — app.UseDeveloperExceptionPage() и app.UseExceptionHandler()
следует помещать ближе к началу конвейера middleware.

Обработка ошибок HTTP

В отличие от исключений стандартный функционал проекта ASP.NET Core почти никак не обрабатывает ошибки HTTP, например, в случае если ресурс не найден.
При обращении к несуществующему ресурсу мы увидим в браузере пустую страницу, и только через консоль веб-браузера мы сможем увидеть статусный код.
Но с помощью компонента StatusCodePagesMiddleware можно добавить в проект отправку информации о статусном коде.
Для этого добавим в метод Configure() класса Startup вызов app.UseStatusCodePages():

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
	if (env.IsDevelopment())
	{
		app.UseDeveloperExceptionPage();
	}
	
	// обработка ошибок HTTP
	app.UseStatusCodePages();
	
	app.Map("/hello", ap => ap.Run(async (context) =>
	{
		await context.Response.WriteAsync($"Hello ASP.NET Core");
	}));
}

Здесь мы можем обращаться только по адресу «/hello». При обращении ко всем остальным адресам браузер отобразит базовую информацию об ошибке:

Данный метод позволяет настроить отправляемое пользователю сообщение. В частности, мы можем изменить вызов метода так:

app.UseStatusCodePages("text/plain", "Error. Status code : {0}");

В качестве первого параметра указывается MIME-тип ответа, а в качестве второго — собственно то сообщение, которое увидит пользователь. В сообщение мы можем
передать код ошибки через плейсхолдер «{0}».

Вместо метода app.UseStatusCodePages() мы также можем использовать еще пару других, которые также обрабатываю ошибки HTTP.

С помощью метода app.UseStatusCodePagesWithRedirects() можно выполнить переадресацию на определенный метод, который непосредственно обработает статусный код:

app.UseStatusCodePagesWithRedirects("/error?code={0}");

Здесь будет идти перенаправление по адресу «/error?code={0}». В качестве параметра через плейсхолдер «{0}» будет передаваться статусный код
ошибки.

Но теперь при обращении к несуществующему ресурсу клиент получит статусный код 302 / Found. То есть формально несуществующий ресурс будет существовать, просто статусный код 302
будет указывать, что ресурс перемещен на другое место — по пути «/error/404».

Подобное поведение может быть неудобно, особенно с точки зрения поисковой индексации, и в этом случае мы можем применить другой метод
app.UseStatusCodePagesWithReExecute():

app.UseStatusCodePagesWithReExecute("/error", "?code={0}");

Первый параметр метода указывает на путь перенаправления, а второй задает параметры строки запроса, которые будут передаваться при перенаправлении.
Вместо плейсхолдера {0} опять же будет передаваться статусный код ошибки. Формально мы получим тот же ответ, так как так же будет идти перенаправление на путь «/error?code=404». Но теперь браузер получит оригинальный статусный код 404.

Пример использования:

public void Configure(IApplicationBuilder app)
{
	// обработка ошибок HTTP
	app.UseStatusCodePagesWithReExecute("/error", "?code={0}");

	app.Map("/error", ap => ap.Run(async context =>
	{
		await context.Response.WriteAsync($"Err: {context.Request.Query["code"]}");
	}));

	app.Map("/hello", ap => ap.Run(async (context) =>
	{
		await context.Response.WriteAsync($"Hello ASP.NET Core");
	}));
}

Настройка обработки ошибок в web.config

Еще один способ обработки кодов ошибок представляет собой определение и настройка в файле конфигурации web.config элемента
httpErrors. Этот способ в принципе использовался и в других версиях ASP.NET.
В ASP.NET Core он также доступен, однако имеет очень ограниченное действие. В частности, мы его можем использовать только при развертывании на IIS, а также не можем использовать ряд настроек.

Итак, добавим в корень проекта новый элемент Web Configurarion File, который естественно назовем web.config:

Изменим его следующим образом:

<?xml version="1.0" encoding="utf-8"?>
<configuration>

  <system.webServer>
	<httpErrors errorMode="Custom" existingResponse="Replace">
      <remove statusCode="404"/>
	  <remove statusCode="403"/>
      <error statusCode="404" path="404.html" responseMode="File"/>
      <error statusCode="403" path="403.html" responseMode="File"/>
	</httpErrors>
   
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified"/>
    </handlers>
    <aspNetCore processPath="%LAUNCHER_PATH%" arguments="%LAUNCHER_ARGS%" stdoutLogEnabled="false" stdoutLogFile=".logsstdout" forwardWindowsAuthToken="false"/>
  </system.webServer>
</configuration>

Также для обработки ошибок добавим в корень проекта новый файл 404.html:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>Ошибка 404</title>
</head>
<body>
    <h1>Ошибка 404</h1>
    <h2>Ресурс не найден!</h2>
</body>
</html>

По аналогии можно добавить файл 403.html для ошибки 403.

Итак, элемент httpErrors имеет ряд настроек. Для тестирования настроек локально, необходимо установить атрибут errorMode="Custom".
Если тестирование необязательно, и приложение уже развернуто для использования, то можно установить значение errorMode="DetailedLocalOnly".

Значение existingResponse="Replace" позволит отобразить ошибку по оригинальному запрошенному пути без переадресации.

Внутри элемента httpErrors с помощью отдельных элементов error устанавливается обработка ошибок. Атрибут statusCode
задает статусный код, атрибут path — адрес url, который будет вызываться, а атрибут responseMode указывает, как будет обрабатываться ответ вызванному url.
Атрибут responseMode имеет значение File, что позволяет рассматривать адрес url из атрибута path как статическую страницу и использовать ее в качестве ответа

Настройки элемента httpErrors могут наследоваться с других уровней, например, от файла конфигурации machine.config. И чтобы удалить
все унаследованные настройки, применяется элемент <clear />. Чтобы удалить настройки для отдельных ошибок, применяется элемент
<remove />.

Для тестирования используем следующий класс Startup:

public class Startup
{
	public void Configure(IApplicationBuilder app)
	{
		app.Map("/hello", ap => ap.Run(async (context) =>
		{
			await context.Response.WriteAsync($"Hello ASP.NET Core");
		}));
	}
}

И после обращения к несуществующему ресурсу в приложении отобразится содержимое из файла 404.html.

Request and response are the backbones of any RESTful Web API. Every status code has a specific meaning and during the development, we must make sure that we are returning a valid response with a valid status code.

What is the Status Code

Status code is a numeric value, and it is the main component of HTTP Response. The status code is issued by the server based on the operation, input data, and some other parameters.

The status code gives some useful information about the behavior of the response.

Status code categories

All status codes are divided into the following 5 categories,

Asp.Net Core Web API has some built-in methods to return the proper status code.

Setup the project

Let us create a new Asp.Net Core Web API application. Now in this application let’s add a new class Employee.cs under the Model folder.

We also need to add a new controller with name EmployeesController at the Controllers folder.

Time to create some hard-coded, in-memory data for employees. because we are only learning about the status code and how to return them from asp.net core web api so hard code data will work for the demo app. In a real application, you will get the data from a database.

For this, we will create a new private method in the EmployeesController.

Let us learn about the status code and how to return them from Asp.Net Core Web API,

200 status code

This is the most common status code that is returned from Web API.

This 200 status code belongs to the Successful category. It means everything about the operation is successful.

Example

• Get all employees data
• Get single employee data 

Asp.Net Core has Ok() method to return 200 status code.

201 Status code

201 status code indicates that the new resource has been created successfully and the server will return the link to get that newly created resource.

 In Asp.Net Core we can use the following methods to return the 201 status code.

Created 

CreatedAtRoute

This method will add a new response header with a key Location and a URL in the value to get this resource.

202 status code

202 status indicates that the request has been accepted but the processing is not yet complete.

In Asp.Net Core we can use the following methods to return the 202 status code.

400 status code

400 status code indicated the bad request. It means there is something wrong in the request data.

In asp.net core we can return 400 status using the BadRequest method. 

301 & 302 are used for local redirection. It means if you are trying to access an action method and from that action method you are redirecting the call to some other action method within the same application then in the response of this request there will be a 301 or 302 status code and a new response header with name Location.

The client will send another request on the value given in the Location header.

In case you are redirecting temporary then the status code will be 302. Or if you are redirecting permanently then the status code will be 301. 

Казалось бы, задача довольно тривиальная и может быть решена написанием буквально пары строк кода. Действительно, так и есть, если вы используете любую популярную серверную технологию. Но только не ASP.NET. Если ваше приложение написано на ASP.NET MVC, и вы первый раз сталкиваетесь с проблемой обработки ошибок, очень легко запутаться и сделать неправильные настройки. Что впоследствии негативно отразится на продвижении сайта в поисковых системах, удобстве работы для пользователя, SEO-оптимизации.

Рассмотрим два подхода, как настроить страницы ошибок. Они в целом похожи, какой выбрать – решать вам.

Для начала вспомним, что означают наиболее популярные коды ошибок, которые отдает сервер.

Код ответа 200. Это значит что все ОК. Запрос клиента обработан успешно, и сервер отдал затребованные клиентом данные в полном объеме. Например, пользователь кликнул по гиперссылке, и в ответ на это в браузере отобразилась нужная ему информация.

Код ответа 404. Это означает, что запрошенный клиентом ресурс не найден на сервере. Например, указанная в адресе гиперссылки статья не найдена, или *.pdf файл был удален и теперь недоступен для скачивания.

Код ответа 500. Внутренняя ошибка на сайте. Что-то сломалось. Это может быть все что угодно, от неправильно написанного кода программистом, до отказа оборудования на сервере.

Допустим, мы только что создали новое веб-приложение типа MVC. На текущий момент, если никаких дополнительных действий для обработки ошибок не принимать, то стандартный сценарий обработки ошибок будет работать как нужно. В браузер пользователя будет отдаваться правильный код ошибки, пользователю будет показана стандартная страница с ошибкой и ее описанием.

Теперь займемся настройкой собственных страниц ошибок. При этом для нас важно не только показать пользователю красивую страницу ошибки, но также сохранить правильный код ответа сервера.

Вариант 1. Ссылка на статичные заранее подготовленные html-страницы.

Первым делом в файле web.config в разделе system.web добавляем новую секцию customErrors со следующими настройками:

<system.web>
  <customErrors mode="On" redirectMode="ResponseRewrite" defaultRedirect="~/404.aspx">
    <error statusCode="404" redirect="~/404.aspx"/>
    <error statusCode="500" redirect="~/500.aspx"/>
  </customErrors>
  ...
</system.web>

Эта секция служит для обработки ошибок на уровне платформы ASP.NET.

Атрибут mode=»On» определяет, что пользовательские страницы ошибок включены. Также допустимы значения Off / RemoteOnly.

Атрибут redirectMode=»ResponseRewrite» определяет, следует ли изменять URL-адрес запроса при перенаправлении на пользовательскую страницу ошибки. Естественно, нам этого не нужно.

Атрибут defaultRedirect=»~/404.aspx» указывает на то, какая страница ошибки будет показана в случае возникновения кода ответа сервера, который мы не описали в настройках. Пусть при любых других ошибках пользователь будет думать, что страница не найдена.

И уже внутри этой секции мы определяем два кода, для которых у нас будут кастомные страницы ошибок.

Далее, как видно из настроек выше, нам понадобятся *.aspx файлы, на которые будет делаться редирект. Обратите внимание, что мы ссылаемся именно на *.aspx файлы, а не на *.html. Эти файлы являются проходными, служебными, в них содержатся настройки для ответа сервера. Содержимое файла 404.aspx:

<%@ Page Language="C#" %>

<%
    var filePath = MapPath("~/404.html");
    Response.StatusCode = 404;
    Response.ContentType = "text/html; charset=utf-8";
    Response.WriteFile(filePath);
%>

В коде выше мы указываем путь непосредственно до конечного *.html файла, а также дополняем настройки ответа сервера. Указываем код ответа, тип отдаваемого контента и кодировку. Если не указать кодировку, то браузер пользователя может интерпретировать ответ от сервера как не отформатированную строку, и, соответственно, не преобразует ее в html-разметку. А если не указать StatusCode = 404 , то получится следующая интересная ситуация:

И хотя на рисунке выше нам показывается пользовательская страница с ошибкой, при этом код ответа 200 — это конечно же неверно. Когда-то давно на форумах Microsoft такое поведение зарепортили как баг. Однако Microsoft возразила, что это не баг, а фича и не стала ничего менять в будущих релизах ASP.NET. Поэтому приходится это исправлять вручную, и вручную в *.aspx файле в ответе сервера указывать код ответа 404.

Попробуйте собственноручно намеренно убрать какую-нибудь из объявленных на данный момент настроек из секции customErrors и понаблюдайте за результатом.

Также по аналогии создаем подобный *.aspx файл для ошибки 500.

И уже после этого нам нужно создать статичные html-файлы, соответственно для ошибок 404 и 500. Пусть они лежат в корне нашего проекта.

Здесь же в файле web.config определяем раздел system.WebServer, если он еще не определен, и в нем объявляем секцию httpErrors:

  <system.webServer>
    <httpErrors errorMode="Custom" defaultResponseMode="File" defaultPath="c:projectsmysite404.html">
      <remove statusCode="404" />
      <remove statusCode="500" />
      <error statusCode="404" path="404.html" responseMode="File" />
      <error statusCode="500" path="500.html" responseMode="File" />
    </httpErrors>
  </system.webServer>

Эта секция служит для обработки ошибок на уровне сервера IIS. Суть в том, что иногда обработка запроса происходит непосредственно на уровне ASP.NET. А иногда ASP.NET просто определяет нужный код ответа и пропускает запрос выше, на уровень сервера. Такой сценарий может случиться, если, например, мы в действии контроллера возвращаем экземпляр класса HttpNotFound:

Или же когда система маршрутизации в MVC-приложении не может определить, к какому маршруту отнести запрошенный пользователем URL-адрес:

https://site.com/long/long/long/long/path

Для секции httpErrors важно отметить следующее. Так как мы ссылаемся на статичные *.html файлы, то и в качестве значений для нужных атрибутов здесь также указываем File . Для атрибута defaultPath необходимо указать абсолютный путь до файла ошибки. Относительный путь именно в этом месте работать не будет. Сам атрибут defaultPath определяет файл, который будет выбран для всех других ошибок, которые мы явно не указали. Но здесь есть одна небольшая проблема. Дело в том, что этот атрибут по умолчанию заблокирован на сервере IIS Express. Если вы разрабатываете свое приложение именно на локальном сервере, то это ограничение нужно снять. Для этого в директории своего проекта нужно найти файл конфигурации сервера и удалить этот атрибут из заблокированных, как это показано на рисунке:

Также проверьте папку App_Start. Если вы создали не пустое приложение, а работаете над реальным проектом, там может находиться класс FilterConfig, в котором регистрируются все глобальные фильтры в приложении. В методе регистрации удалите строчку кода, где регистрируется HandleErrorAttribute, в нашем случае он не понадобится.

Вот такой комплекс мер нужно предпринять, чтобы настроить обработку ошибок 404, 500, и любых других. Это настройки в файле web.config, и добавление в наш проект статичных файлов.

Вариант 2. Обработка ошибок с использованием специального контроллера.

Второй подход немного отличается от первого. Здесь нам не понадобится секция customErrors, так как обработку всех ошибок мы будем передавать сразу из приложения на уровень сервера, и он уже будет решать что делать. Можно удалить или закомментировать эту секцию в файле web.config.

Далее создадим специальный контроллер, который будет принимать все ошибки, которые мы хотим обрабатывать:

public class ErrorController : Controller
{
    public ActionResult NotFound()
    {
        Response.StatusCode = 404;
        return View();
    }

    public ActionResult Internal()
    {
        Response.StatusCode = 500;
        return View();
    }
}

Также создадим соответствующие представления с нужной нам красивой разметкой.

Также в файле web.config нам нужно изменить настройки в секции httpErrors. Если раньше мы ссылались на статичные html-файлы, то теперь мы будем обращаться по указанным URL, которые мы определили в ErrorController’е, чтобы именно там обрабатывать ошибки:

<httpErrors errorMode="Custom" existingResponse="Replace" defaultResponseMode="ExecuteURL" defaultPath="/Error/NotFound">
  <remove statusCode="404"/>
  <remove statusCode="500"/>
  <error statusCode="404" path="/Error/NotFound" responseMode="ExecuteURL"/>
  <error statusCode="500" path="/Error/Internal" responseMode="ExecuteURL"/>
</httpErrors>

Вариант 3. Фильтр HandleErrorAttribute

Замечу, что есть еще один способ взять под свой контроль обработку ошибок в приложении – это наследоваться от стандартного класса HandleErrorAttribute и написать свой фильтр. Но это уже более частный случай, когда нужно реализовать какую-то особенную логику при возникновении той или иной ошибки. В большинстве же более менее стандартных приложений наша проблема решается двумя выше описанными способами и в этом фильтре нет необходимости. Более подробную информацию, как работать с классом HandleErrorAttribute можно найти в официальной документации в интернете по этой ссылке.

Итого

Мы посмотрели на два разных подхода, которые можно применить при обработке ошибок на платформе ASP.NET. Опять же повторюсь, что если для вас не принципиально настраивать собственные страницы ошибок, то лучше не изменять эти настройки, так как даже одна упущенная деталь или неверно сконфигурированный параметр может очень сильно навредить репутации вашего сайта для конечного пользователя и в поисковых системах.

| Воскресенье, 3 марта, 2013

Метки: ASP.NET Web API Комментарии: 0

ASP.NET Web API упрощает разработку HTTP-сервисов, а также предоставляет много способов возврата полных и информативных сообщений об ошибках для различных ситуаций. Рассмотрим эти возможности.

Для начала, посмотрим как выглядит обычное сообщение об ошибке для Web API:

{ 
"Message": "No HTTP resource was found that matches the request URI 'http://localhost/Foo'.", 
"MessageDetail": "No type was found that matches the controller named 'Foo'." 
}

То есть ошибка, это просто коллекция пар ключей и значений, которая сообщает нам, что пошло не так. Эта коллекция отсылается клиенту через HTTP-запросы. В примере выше содержимое представлено в формате JSON.

Но если указать в запросе в заголовке Accept «text/html», то ответ будет в xml виде:

<Error> 
  <Message>No HTTP resource was found that matches the request URI 'http://localhost/Foo'.</Message> 
  <MessageDetail>No type was found that matches the controller named 'Foo'.</MessageDetail> 
</Error>

Этот простой формат предоставляет информацию клиентам об ошибках, что дает возможность делать запись в журнал, либо отсылать отчеты на email.

HttpError

Примеры приведенные выше — это объекты HttpError, сериализованные с помощью Json.NET и DataContactSerializer.

Тип HttpError определяет содержательный и расширяемый способ передачи информации об ошибках между различными платформами. Фактически, это просто класс Dictionary, который предоставляет еще несколько вспомогательных конструкторов для создания сообщений об ошибках, исключениях и некорректных состояниях модели.

public HttpError();
public HttpError(string message);
public HttpError(Exception exception, bool includeErrorDetail);
public HttpError(ModelStateDictionary modelState, bool includeErrorDetail);

Так выглядят исключения в формате JSON:

{ 
"Message": "An error has occurred.", 
"ExceptionMessage": "Index was outside the bounds of the array.", 
"ExceptionType": "System.IndexOutOfRangeException", 
"StackTrace": "   at WebApiTest.TestController.Post(Uri uri) in c:\Temp\WebApiTest\WebApiTest\TestController.cs:line 18rn   at System.Web.Http.Controllers.ReflectedHttpActionDescriptor.ActionExecutor.<>c__DisplayClassf.<GetExecutor>b__9(Object instance, Object[] methodParameters)rn   at System.Web.Http.Controllers.ReflectedHttpActionDescriptor.ActionExecutor.Execute(Object instance, Object[] arguments)rn   at System.Threading.Tasks.TaskHelpers.RunSynchronously[TResult](Func`1 func, CancellationToken cancellationToken)" 
}

Так некорректная модель:

{ 
  "Message": "The request is invalid.", 
  "ModelState": 
   { 
       "s": [ "Required property 's' not found in JSON. Path '', line 1, position 2."  ] 
   }
} 

Можно создавать и собственные виды ошибок в классе HttpError, например так:

public HttpResponseMessage Get()
{
   HttpError myCustomError = new HttpError("My custom error message") { { "CustomErrorCode", 37 } };
   return Request.CreateErrorResponse(HttpStatusCode.BadRequest, myCustomError);
}

Результат будет таким:

{ 
  "Message": "My custom error message", 
  "CustomErrorCode": 37 
}

В этом примере метод возвращает ошибку с помощью Request.CreateErrorMessage. Пользовательская ошибка обернута в класс HttpResponseMessage. Это рекомендованный способ создания ответов c сообщениями об ошибках. Ниже приведены расширяемые методы для возврата такой информации:

public static HttpResponseMessage CreateErrorResponse(this HttpRequestMessage request, HttpStatusCode statusCode, Exception exception);
public static HttpResponseMessage CreateErrorResponse(this HttpRequestMessage request, HttpStatusCode statusCode, HttpError error);
public static HttpResponseMessage CreateErrorResponse(this HttpRequestMessage request, HttpStatusCode statusCode, ModelStateDictionary modelState);
public static HttpResponseMessage CreateErrorResponse(this HttpRequestMessage request, HttpStatusCode statusCode, string message);
public static HttpResponseMessage CreateErrorResponse(this HttpRequestMessage request, HttpStatusCode statusCode, string message, Exception exception);

Но можно и просто генерировать любое исключение в методе действия. Web API автоматически перехватывает исключение, конвертирует в ответ сервера с кодом 500 (Internal Server Error) и возвращает сообщение в точно таком же формате, как и с методом CreateErrorResponse.

HttpResponseException

Но как быть, если нужно вернуть ошибку в методе, который возвращает объекты не являющиеся классами HttpResponseMessage? Тут на помощь приходит класс HttpResponseException. Данный тип исключения определен специально для Web API и служит двум целям:

1. Позволяет возвращать специальные ответы HTTP из методов, которые не возвращают HttpResponseMethod.
2. Упрощает код в методах Web API, выполняя вывод ответа сервера с информацией об ошибке немедленно.

Технически, HttpResponseException может быть использован для возврата любых http-ответов, но особенно полезен данный класс для ошибок. Это позволяет нам писать методы следующим образом:

public Person Get(int id)
{
   if (!_contacts.ContainsKey(id))
   {
      throw new HttpResponseException(Request.CreateErrorResponse(HttpStatusCode.NotFound, String.Format("Contact {0} not found.", id)));
   }
   return _contacts[id];
}

Метод предназначен для возврата типа Person, но мы можем также и вернуть пользовательскую ошибку в случае отсутствия возвращаемого значения.

Подробное описание ошибок

В начале статьи в примере упоминался параметр «includeErrorDetails» в конструкторе класса HttpError. Это для случаев, когда клиенту нужно предоставить отладочную информацию, для разрешения проблем на сервере. По умолчанию подробная информация не высылается удаленным клиентам, но предоставляется клиентам на локальном компьютере. В самом первом примере статьи, локальный клиент получит:

{ 
"Message": "No HTTP resource was found that matches the request URI 'http://localhost/Foo'.", 
"MessageDetail": "No type was found that matches the controller named 'Foo'." 
}

А до удаленного клиента дойдет только:

{ 
"Message": "No HTTP resource was found that matches the request URI 'http://localhost/Foo'." 
}

MessageDetails содержит специфичную информацию, которую удаленные клиенты в большинстве случаев видеть не должны. То есть ошибки содержащие отладочную информацию (exception message, exception type, stack trace) не предоставляют подробное описание по умолчанию, но ошибки состояния моделей (кроме исключений) подробно отсылаются и удаленным клиентам.

Явно задавать возврат подробной информации можно в объекте HttpConfiguration:

config.IncludeErrorDetailPolicy = IncludeErrorDetailPolicy.LocalOnly;
config.IncludeErrorDetailPolicy = IncludeErrorDetailPolicy.Always;
config.IncludeErrorDetailPolicy = IncludeErrorDetailPolicy.Never;

Как было упомянуто выше, значение по умолчанию LocalOnly.

Обработка ошибок для некорректных моделей

Еще один распространенный способ использования обработки ошибок Web API – это немедленный возврат ошибки в случае некорректной модели. Для этого лучше всего реализовать следующий фильтр метода действия:

public class ValidationFilterAttribute : ActionFilterAttribute
{
    public override void OnActionExecuting(HttpActionContext actionContext)
    {
        if (!actionContext.ModelState.IsValid)
        {
            actionContext.Response = 
                 actionContext.Request.CreateErrorResponse(HttpStatusCode.BadRequest,   
                 actionContext.ModelState);
         }
     }
}

Можно прописать этот фильтр для каждого метода а можно зарегистрировать его глобально сразу для всех методов:

config.Filters.Add(new ValidationFilterAttribute());

Это позволяет не писать проверку модели в каждом методе, а сразу возвращать ошибку клиенту в случае некорректной модели.

Никто еще не оставил здесь комментарий.

• Download PDF Article — 1.6 MB
• Download source — 213.1 KB

Introduction

This article in the «Web API with ASP.NET Core» series will focus on topics like returning HTTP Status Codes from API and their importance, returning sub resources, serializer strings and content negotiation. We learned how to create an API in ASP.NET Core and how to return resources in last article and paused at Status Codes. We’ll continue to explore the importance of status codes and practical examples as well. We’ll also explore resource creation and returning the child resources as well in this article. We can use the same source code as we got at the completion of last article of the series.

While consuming an API an Http Request is sent and in return, a response is sent along with return data and an HTTP code. The HTTP Status Codes are important because they tell the consumer about what exactly happened to their request; a wrong HTTP code can confuse the consumer. A consumer should know (via a response) that its request has been taken care of or not, and if the response is not as expected, then the Status Code should tell the consumer where the problem is if it is at consumer level or at API level.

Suppose there is a situation where the consumer gets a response as status code 200, but at the service level there is some problem or issue in that case consumer will get a false assumption of everything being fine, whereas that won’t be a case. So if there is something wrong at service or there occurs some error on the server, the status code 500 should be sent to consumer, so that the consumer knows that there actaully is something wrong with the request it sent. In general, there are a lot of access codes. One can find the complete here, but not all are so important except the few. Few status code are very frequently used with the normal CURD operations that a service perform, so service does not necessarily have to support all of them.Let’s have a glance over few of the important status codes.

When we talk about the levels of status codes, there are 5 levels. Level 100 status codes are more of informal nature. Level 200 status codes are specifically for request being sent well. We get 200 codes for success of a GET request, 201 if a new resource has been successfully created. 204 status codes is also for success but in return it does not returns anything, just like if consumer has performed delete operation and in return doesn’t really expect something back. Level 300 http status codes are basically used for redirection, for e.g. to tell a consumer that the requested resource like page, image has been moved to another location. Level 400 status codes are meant to state errors or client error for e.g. status code 400 means Bad Request, 401 is Unauthorized that is invalid authentication credentials or details have been provided by the consumer, 403 means that authentication is a success, but the user is not authorized. 404 are very common and we often encounter which mean that the requested resource is not available. Level 500 are for server errors. Internal Server Error exception is very common, that contains the code 500. This error means that there is some unexpected error on the server and client cannot do anything about it. We’ll cover how we can use these HTTP status codes in our application.

RoadMap

We’ll follow a roadmap to learn and cover all the aspects of ASP.NET Core in detail. Following is the roadmap or list of articles that will cover the entire series.

1. Create API with ASP.NET Core (Day 1): Getting Started and ASP.NET Core Request Pipeline
2. Create API with ASP.NET Core (Day 2): Create an API and return resources in ASP.NET Core
3. Create API with ASP.NET Core (Day 3): Working with HTTP Status Codes, Serializer Settings and Content Negotiation in ASP.NET Core API
4. Create API with ASP.NET Core (Day 4): Understanding Resources in ASP.NET CORE API
5. Create API with ASP.NET Core (Day 5): Inversion of Control and Dependency Injection in ASP.NET CORE API
6. Create API with ASP.NET Core (Day 6): Getting Started with Entity Framework Core
7. Create API with ASP.NET Core (Day 7): Entity Framework Core in ASP.NET CORE API

HTTP Status Codes Implementation

Let’s try to tweak our implementation, and try to return HTTP Status Codes from API. Now in the EmployeesController, we need to return the JSON result along with the status code in response. Right now we return only the JSON result as shown below.

If we look closely at JsonResult class and press F12 to see its definition. We find that it is derived from ActionResult class which purposely formats the object in the form of a JSON object. ActionResult class implements IActionResult interface.

Ideally API should not only return JSON all the time, they should return what consumer is expecting i.e. via inspecting the request headers, and ideally we should be able to return the Status Code also along with the result.

We’ll see that it could also be possible with the JSonResult that we return. So if you assign the JSON result that we create to any variable say «employees», you can find the StatusCode property associated with that variable, we can set that StatusCode property.

So we can set the status code to 200 and return this variable as shown below.

[HttpGet()]
 public JsonResult GetEmployees()
 {
   var employees= new JsonResult(EmployeesDataStore.Current.Employees);
   employees.StatusCode = 200;
   return employees;
 }

But that would be a tedious job to do everytime. There are predefined methods in ASP.NET core that create IActionResult, and all those are mapped to correct status codes (i.e. NotFound if the resource doesn’t exist or BadRequest for erroneous requests, etc.).

So replace the return type of methods with IActionResult instead of JsonResult, and in the GetEmployee method make the implementation as if there is a request of Employee with the id that does not exists, we can return NotFound, else Employee data with the status code OK. In the similar way for the first method where we return the list of employees, we can directly return Ok with the data. There is no scope of NotFound in this method, because even if no records exist an empty list could be returned with HTTP Status Code OK. So, our code becomes something like shown below,

using Microsoft.AspNetCore.Mvc;
using System.Linq;

namespace EmployeeInfo.API.Controllers
{
  [Route("api/employees")]
  public class EmployeesInfoController : Controller
  {
    [HttpGet()]
    public IActionResult GetEmployees()
    {
      return Ok(EmployeesDataStore.Current.Employees);
    }

    [HttpGet("{id}")]
    public IActionResult GetEmployee(int id)
    {
      var employee = EmployeesDataStore.Current.Employees.FirstOrDefault(emp => emp.Id == id);
      if (employee == null)
        return NotFound();
      return Ok(employee);

    }
  }
}

Compile the application and run it. Now go to postman and try to make requests. In the last article, we made a request of an employee with the Id 8, that does not exist and we got the following result.

The result said null, that is not ideally a correct response. So try to make the same request now with this new implementation that we did. In this case, we get a proper status 404 with Not Found message as shown below,

Since we know that we can also send the request from web browsers as browsers support HTTP Request. If we try to access our API via browser, we get an empty page with the error or response in the developer’s tool as shown below.

We can make our responses more meaningful by displaying the same on the page itself as ASP.NET Core contains a middle ware for Status Codes as well. Just open the configure method of the startup class and add following line to the method.

app.UseStatusCodePages();

That is adding it to our request pipe line. So the method will look like,

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
    {
      loggerFactory.AddConsole();

      if (env.IsDevelopment())
      {
        app.UseDeveloperExceptionPage();
      }
      else
      {
        app.UseExceptionHandler();
      }

      app.UseStatusCodePages();

      app.UseMvc();


      
      
      
      

      
      
      
      
    }

Now again make the same API request from browser and we get the following message on the browser page itself.

Returning Sub Resources

In the EmployeeDto, we have a property named NumberOfCompaniesWorkedWith, considering this as a sub resource or child resource, we might want to return this as a result as well. Let’s see how we can achieve that. Add a DTO class named NumberOfCompaniesWorkedDto to the Model folder, and add Id, name and Description to that newly added class.

NumberOfCompaniesWorkedDto.cs

namespace EmployeeInfo.API.Models
{
  public class NumberOfCompaniesWorkedDto
  {
    public int Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
  }
}

Now in the EmployeeDto class add a property w.r.t. this NumberOfCompaniesWorkedDto that returns the collection of all companies an employee has worked with.

EmployeeDto.cs

using System.Collections.Generic;

namespace EmployeeInfo.API.Models
{
  public class EmployeeDto
  {
    public int Id { get; set; }
    public string Name { get; set; }
    public string Designation { get; set; }
    public string Salary { get; set; }
    public int NumberOfCompaniesWorkedWith
    {
      get
      {
        return CompaniesWorkedWith.Count;
      }
    }

    public ICollection<NumberOfCompaniesWorkedDto> CompaniesWorkedWith { get; set; } = new List<NumberOfCompaniesWorkedDto>();

  }
}

In the above code, we added a new property that returns the list of companies an employee has worked with. For the property NumberOfCompaniesWorkedWith, we calculated the count from the collection that we have. We initialized the CompaniesWorkedWith property to return an empty list so that we do not end up having null-reference exceptions. Now add some mock data of CompaniesWorkedWith to the EmployeesDataStore class.

EmployeesDataStore.cs

using EmployeeInfo.API.Models;
using System.Collections.Generic;

namespace EmployeeInfo.API
{
  public class EmployeesDataStore
  {
    public static EmployeesDataStore Current { get; } = new EmployeesDataStore();
    public List<EmployeeDto> Employees { get; set; }

    public EmployeesDataStore()
    {
      
      Employees = new List<EmployeeDto>()
            {
                new EmployeeDto()
                {
                     Id = 1,
                     Name = "Akhil Mittal",
                     Designation = "Technical Manager",
                     Salary="$50000",
                     CompaniesWorkedWith=new List<NumberOfCompaniesWorkedDto>()
                     {
                       new NumberOfCompaniesWorkedDto()
                       {
                         Id=1,
                         Name="Eon Technologies",
                         Description="Financial Technologies"
                       },
                       new NumberOfCompaniesWorkedDto()
                       {
                         Id=2,
                         Name="CyberQ",
                         Description="Outsourcing"
                       },
                       new NumberOfCompaniesWorkedDto()
                       {
                         Id=3,
                         Name="Magic Software Inc",
                         Description="Education Technology and Fin Tech"
                       }
                     }
                },
                new EmployeeDto()
                {
                     Id = 2,
                     Name = "Keanu Reaves",
                     Designation = "Developer",
                     Salary="$20000",
                     CompaniesWorkedWith=new List<NumberOfCompaniesWorkedDto>()
                     {
                       new NumberOfCompaniesWorkedDto()
                       {
                         Id=1,
                         Name="Eon Technologies",
                         Description="Financial Technologies"
                       }
                     }
                },
                 new EmployeeDto()
                {
                     Id = 3,
                     Name = "John Travolta",
                     Designation = "Senior Architect",
                     Salary="$70000",
                     CompaniesWorkedWith=new List<NumberOfCompaniesWorkedDto>()
                     {
                       new NumberOfCompaniesWorkedDto()
                       {
                         Id=1,
                         Name="Eon Technologies",
                         Description="Financial Technologies"
                       },
                       new NumberOfCompaniesWorkedDto()
                       {
                         Id=2,
                         Name="CyberQ",
                         Description="Outsourcing"
                       }
                     }
                },
                  new EmployeeDto()
                {
                     Id = 4,
                     Name = "Brad Pitt",
                     Designation = "Program Manager",
                     Salary="$80000",
                     CompaniesWorkedWith=new List<NumberOfCompaniesWorkedDto>()
                     {
                       new NumberOfCompaniesWorkedDto()
                       {
                         Id=1,
                         Name="Infosys Technologies",
                         Description="Financial Technologies"
                       },
                       new NumberOfCompaniesWorkedDto()
                       {
                         Id=2,
                         Name="Wipro",
                         Description="Outsourcing"
                       },
                       new NumberOfCompaniesWorkedDto()
                       {
                         Id=3,
                         Name="Magic Software Inc",
                         Description="Education Technology and Fin Tech"
                       }
                     }
                },
                   new EmployeeDto()
                {
                     Id = 5,
                     Name = "Jason Statham",
                     Designation = "Delivery Head",
                     Salary="$90000",
                     CompaniesWorkedWith=new List<NumberOfCompaniesWorkedDto>()
                     {
                       new NumberOfCompaniesWorkedDto()
                       {
                         Id=1,
                         Name="Fiserv",
                         Description="Financial Technologies"
                       },
                       new NumberOfCompaniesWorkedDto()
                       {
                         Id=2,
                         Name="Wipro",
                         Description="Outsourcing"
                       },
                       new NumberOfCompaniesWorkedDto()
                       {
                         Id=3,
                         Name="Magic Software Inc",
                         Description="Education Technology and Fin Tech"
                       }
                       ,
                       new NumberOfCompaniesWorkedDto()
                       {
                         Id=4,
                         Name="Sapient",
                         Description="Education Technology and Fin Tech"
                       }
                     }
                }
            };

    }
  }
}

Now add a new controller named CompaniesWorkedWithController in the same way as we created EmployeesController in the last article. The new controller should be derived from Controller class.

Since CompaniesWorkedWith is directly related to Employees, if we put a default route to «api/companiesworkedwith» won’t look good and justifiable. If this is related to employees, the URI of the API should also show that. CompaniesWorkedWith could be considered as a sub resource of Employees or child resource of Employee. So the companies worked with as a resource should be accessed via employees, therefore the URI will be somewhat like «api/employees/<employee id>/companiesworkedwith». Therefore, the controller route will be «api/employees» as it would be common to all the actions.

Since the child resource is dependent on parent resources, we take Id of the parent resource to get child resource.

The following is the actual implementation for returning the list of companies of an employee.

[HttpGet("{employeeid}/companiesworkedwith")]
public IActionResult GetCompaniesWorkedWith(int employeeId)
{
  var employee = EmployeesDataStore.Current.Employees.FirstOrDefault(emp => emp.Id == employeeId);
  if (employee == null) return NotFound();
  return Ok(employee.CompaniesWorkedWith);
}

If we look at the above code, we first find an employee with the passed id, and we’ll have to do so because if there is no employee with that id then it is understood that his companies worked with won’t exist even, that gives us the liberty to send the status code NotFound if there is no employee, on the other hand if we find an employee, we can send the companiesworkedwith to the consumer.

In a similar way, we write the code for getting a single company worked with information. In that case, we should pass two IDs one for the employee and the other for the company like shown in below code.

[HttpGet("{employeeid}/companyworkedwith/{id}")]
 public IActionResult GetCompanyWorkedWith(int employeeId, int Id)
 {
   var employee = EmployeesDataStore.Current.Employees.FirstOrDefault(emp => emp.Id == employeeId);
   if (employee == null) return NotFound();

   var companyWorkedWith = employee.CompaniesWorkedWith.FirstOrDefault(comp => comp.Id == Id);
   if (companyWorkedWith == null) return NotFound();
   return Ok(companyWorkedWith);
 }

So in the code above, we first get the employee for the ID passed. If the employee exists we go further to fetch the company with the passed ID, else, we return Not Found. If the company does not exist, we again return NotFound, else, we return the result OK with the company object. We can try to check these implementations on Postman.

Companiesworkedwith for existing employee

Companiesworkedwith for non existing employee

Particular Companiesworkedwith for a particular employee

Non existing Companyworkedwith for a particular employee

Get All Employees

So we see that we get the results as expected. For example, in the similar way as the API is written and in those cases consumer also gets the correct response and the response does not confuse the consumer. We also see that we get the related or child resources along with Employees if we send a request to get all employees. Well this scenario would not be an ideal for every request. For example, the consumer may only want employees and not the related companies worked with data. Yes, we can also control this with the help of Entity Framework that we’ll cover in the later articles of the series. Notice that we can also control the casing of the JSON data that is returned as the consumer may expect the properties to be in upper case, we can also do this with the help of serializer settings that we’ll cover now.

Serializer Settings in ASP.NET Core API

By default, ASP.NET Core uses JSON for serialization and de-serialization, but the best thing is that we can also configure this in our code. We used the ConfigureServices method in the startup class to configure the services use be the container, in a similar way we can configure for MVC.

We can add JSON options to the added MVC service.

Since the AddJsonOptions method expects an action, we supply a lambda expression there as options parameter through which we can easily access the serializer settings as shown in above image. We fetch the contract resolver as we’ll override the default settings of naming strategy. The line var resolver = opt.SerializerSettings.ContractResolver as DefaultContractResolver; takes out the contract resolver and cast ot to the default contract resolver, we can now override its NamingStrategy property and mark it to null. So now it should not typically follow that lower letters convention, which it followed by default. We use the DefaultContractResolver class which is part of Newtonsoft.Json.Serialization, so we’ll have to add the namespace for it as well. The code will be as shown below:

public void ConfigureServices(IServiceCollection services)
    {
      services.AddMvc().AddJsonOptions(opt =>
      {
        if (opt.SerializerSettings.ContractResolver != null)
        {
          var resolver = opt.SerializerSettings.ContractResolver as DefaultContractResolver;
          resolver.NamingStrategy = null;
        }
      });
    }

Now let’s test this with Postman. In the last request, we got the JSON properties in small case letters as shown below:

Now run the application and make a request for the same API from postman as consumer.

Now we get the JSON properties in capital letters (i.e. overridden by our implementation). This implementation is on need basis or based on the kind of JSON the consumer wants. Here comes the concept of content negotiation where a response is sent based on consumers request parameters.

Content Negotiation and Formatters in ASP.NET Core API

Content negotiation is one of the important concepts when we develop an API. This enables an API to select best representation for a desired response when there are more than one representations available. Suppose we build an API for multiple consumers and clients we are not sure that whether all the clients would be able to consume the default representation that an API sends in the form JSON. Some consumers may expect XML as a response or any other format. In that case it would be hard for the consumers to understand and work with JSON instead of XML.

There is always an option to the consumer to send a request for a specific format by specifying the requested media type in the Accept header. For example, if in the accept header the requested format is XML, the API should send the response in XML format and if it is JSON, the API should send the response in JSON format. If there is no header specified, then API can take liberty to send the response in the default format that it has. For example, JSON in our case. ASP.NET Core also supports this functionality via output formatters. Output formatter (as the name suggests) mostly deals with the output. The consumer in that case can request any specific type of output that it wants by setting the accept header to request media type such as Application/JSON or Application/XML. It also works with the input formats in a way that supposes there is a POST request to an API for creating a resource, the input media type and the content that comes along with the request is then identified by content-type header in the request. Let’s cover this with practical implementations. Let’s try to request the list of employees with the JSON accept header. So, we’ll set Header key as «Accept» and Value as «application/json», and we get JSON as shown below.

Now make a request with accept header application/xml, we still get JSON.

But ideally, the API should return XML. Let’s see how we can configure our service to return the same. If we go to the Startup class’s ConfigureService method, we have an option to add MvcOptions to the service, which in turn has options to add input and output formatters.

If we need to use the Xml Output formatter, we’ll have to install a nugget package named Microsoft.AspNetCore.MVC.Formatters.Xml as shown below. So right click on the project, go to manage nugget packages and search online for this package and install it.

Now if we can add the XML output formatter as shown in following code:

services.AddMvc()
        .AddMvcOptions(opt => opt.OutputFormatters.Add(new XmlDataContractSerializerOutputFormatter()));

Similarly, Input formatters can also be added with XmlDataContractSerializerInputFormatter. So, build the solution, run the project and then now again try to request the employees list.

First with default or JSON formatter, we get JSON as shown below.

And now with the XML accept header we get XML as shown below.

Hence now a consumer can request the response in desired format and our API is capable of delivering that as well.

Our code for the Startup class looks like the following:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.AspNetCore.Mvc.Formatters;

namespace EmployeeInfo.API
{
  public class Startup
  {
    
    
    public void ConfigureServices(IServiceCollection services)
    {
      services.AddMvc()
        .AddMvcOptions(opt => opt.OutputFormatters.Add(new XmlDataContractSerializerOutputFormatter()));
      
      
      
      
      
      
      
      
    }

    
    public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
    {
      loggerFactory.AddConsole();

      if (env.IsDevelopment())
      {
        app.UseDeveloperExceptionPage();
      }
      else
      {
        app.UseExceptionHandler();
      }

      app.UseStatusCodePages();

      app.UseMvc();

      
      
      
      

      
      
      
      
    }
  }
}

Conclusion

In this article, we learned about the HTTP Codes and their importance and how we can configure our service to use HTTP Codes. We also focused on how sub resources or child resources could be sent via an API. We learnt about serializer settings and most importantly the formatters and how we can enable the API to support content negotiation as well. In the next article of learning ASP.NET Core API we’ll do some more practical stuff when we perform CRUD operations.

<< Previous Article

Source Code on Github

Source Code

References

• https://www.asp.net/core
• https://www.pluralsight.com/courses/asp-dotnet-core-api-building-first