Настройка веб-API ASP.NET 2

Статья
07/13/2023

В этом разделе описывается настройка веб-API ASP.NET.

Параметры конфигурации
Настройка веб-API с размещением ASP.NET
Настройка веб-API с помощью самостоятельного размещения OWIN
Глобальные службы веб-API
Конфигурация для каждого контроллера

Параметры конфигурации

Параметры конфигурации веб-API определяются в классе HttpConfiguration .

Член	Описание
DependencyResolver	Включает внедрение зависимостей для контроллеров. См . раздел Использование сопоставителя зависимостей веб-API.
Фильтры	Фильтры действий.
Форматировщики	Модули форматирования типа мультимедиа.
IncludeErrorDetailPolicy	Указывает, должен ли сервер включать сведения об ошибках, такие как сообщения об исключениях и трассировки стека, в сообщения ответов HTTP. См. статью IncludeErrorDetailPolicy.
Инициализатор	Функция, которая выполняет окончательную инициализацию HttpConfiguration.
MessageHandlers	Обработчики сообщений HTTP.
ParameterBindingRules	Коллекция правил для привязки параметров для действий контроллера.
Свойства	Универсальный контейнер свойств.
Маршруты	Коллекция маршрутов. См. раздел Маршрутизация в веб-API ASP.NET.
Службы	Коллекция служб. См. раздел Службы.

Предварительные требования

Visual Studio 2017 — выпуски Community, Professional или Enterprise.

Настройка веб-API с размещением ASP.NET

В приложении ASP.NET настройте веб-API, вызвав GlobalConfiguration.Configure в методе Application_Start . Метод Configure принимает делегат с одним параметром типа HttpConfiguration. Выполните всю настройку внутри делегата.

Ниже приведен пример использования анонимного делегата:

using System.Web.Http;
namespace WebApplication1
{
    public class WebApiApplication : System.Web.HttpApplication
    {
        protected void Application_Start()
        {
            GlobalConfiguration.Configure(config =>
            {
                config.MapHttpAttributeRoutes();

                config.Routes.MapHttpRoute(
                    name: "DefaultApi",
                    routeTemplate: "api/{controller}/{id}",
                    defaults: new { id = RouteParameter.Optional }
                );
            });
        }
    }
}

В Visual Studio 2017 шаблон проекта "веб-приложение ASP.NET" автоматически настраивает код конфигурации, если выбрать "Веб-API" в диалоговом окне Новый проект ASP.NET .

Шаблон проекта создает файл с именем WebApiConfig.cs в папке App_Start. Этот файл кода определяет делегат, в который следует поместить код конфигурации веб-API.

Снимок экрана: диалоговое окно Обозреватель решений, где в папке

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;

namespace WebApplication1
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            // TODO: Add any additional configuration code.

            // Web API routes
            config.MapHttpAttributeRoutes();

            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );
        }
    }
}

Шаблон проекта также добавляет код, который вызывает делегат из Application_Start.

public class WebApiApplication : System.Web.HttpApplication
{
    protected void Application_Start()
    {
        GlobalConfiguration.Configure(WebApiConfig.Register);
    }
}

Настройка веб-API с помощью Self-Hosting OWIN

Если вы используете OWIN для самостоятельного размещения, создайте экземпляр HttpConfiguration . Выполните настройку этого экземпляра, а затем передайте экземпляр в метод расширения Owin.UseWebApi .

public class Startup 
{ 
    public void Configuration(IAppBuilder appBuilder) 
    { 
        HttpConfiguration config = new HttpConfiguration(); 

        config.Routes.MapHttpRoute( 
            name: "DefaultApi", 
            routeTemplate: "api/{controller}/{id}", 
            defaults: new { id = RouteParameter.Optional } 
        ); 

        appBuilder.UseWebApi(config); 
    } 
}

В руководстве Использование OWIN для Self-Host веб-API ASP.NET 2 показаны все шаги.

Глобальные службы веб-API

Коллекция HttpConfiguration.Services содержит набор глобальных служб, которые веб-API использует для выполнения различных задач, таких как выбор контроллера и согласование содержимого.

Примечание

Коллекция Служб не является механизмом общего назначения для обнаружения служб или внедрения зависимостей. В ней хранятся только типы служб, известные платформе веб-API.

Коллекция Services инициализируется набором служб по умолчанию, и вы можете предоставить собственные пользовательские реализации. Некоторые службы поддерживают несколько экземпляров, в то время как другие могут иметь только один экземпляр. (Однако вы также можете предоставлять службы на уровне контроллера; см. раздел Конфигурация каждого контроллера.

Службы Single-Instance

Служба	Описание
IActionValueBinder	Возвращает привязку для параметра.
IApiExplorer	Возвращает описания API- интерфейсов, предоставляемых приложением. См. статью Создание страницы справки для веб-API.
IAssembliesResolver	Возвращает список сборок для приложения. См. раздел Выбор маршрутизации и действий.
IBodyModelValidator	Проверяет модель, которая считывается из текста запроса с помощью модуля форматирования типа носителя.
IContentNegotiator	Выполняет согласование содержимого.
IDocumentationProvider	Предоставляет документацию по API. Значение по умолчанию — NULL. См. статью Создание страницы справки для веб-API.
IHostBufferPolicySelector	Указывает, должен ли узел буферистить тела сущности сообщения HTTP.
IHttpActionInvoker	Вызывает действие контроллера. См. раздел Выбор маршрутизации и действий.
IHttpActionSelector	Выбирает действие контроллера. См. раздел Выбор маршрутизации и действий.
IHttpControllerActivator	Активирует контроллер. См. раздел Выбор маршрутизации и действий.
IHttpControllerSelector	Выбирает контроллер. См. раздел Выбор маршрутизации и действий.
IHttpControllerTypeResolver	Предоставляет список типов контроллеров веб-API в приложении. См. раздел Выбор маршрутизации и действий.
ITraceManager	Инициализирует платформу трассировки. См. раздел Трассировка в веб-API ASP.NET.
ITraceWriter	Предоставляет модуль записи трассировки. По умолчанию используется модуль записи трассировки без операции. См. раздел Трассировка в веб-API ASP.NET.
IModelValidatorCache	Предоставляет кэш проверяющих элементов управления моделью.

Службы Multiple-Instance

Служба	Описание
IFilterProvider	Возвращает список фильтров для действия контроллера.
ModelBinderProvider	Возвращает связыватель модели для заданного типа.
ModelMetadataProvider	Предоставляет метаданные для модели.
ModelValidatorProvider	Предоставляет проверяющий элемент управления для модели.
ValueProviderFactory	Создает поставщик значений. Дополнительные сведения см. в записи блога Майка Стола Создание пользовательского поставщика значений в WebAPI

Чтобы добавить пользовательскую реализацию в службу с несколькими экземплярами, вызовите метод Add или Insert в коллекции Services :

config.Services.Add(typeof(IFilterProvider), new MyFilterProvider());

Чтобы заменить службу с одним экземпляром пользовательской реализацией, вызовите Replace в коллекции Services :

config.Services.Replace(typeof(ITraceWriter), new MyTraceWriter());

Конфигурация Per-Controller

Для каждого контроллера можно переопределить следующие параметры:

Форматировщики типов мультимедиа
Правила привязки параметров
Службы

Для этого определите настраиваемый атрибут, реализующий интерфейс IControllerConfiguration . Затем примените атрибут к контроллеру.

В следующем примере форматировщики типов мультимедиа по умолчанию заменяются настраиваемым форматировщиком.

using System;
using System.Web.Http;
using System.Web.Http.Controllers;

namespace WebApplication1.Controllers
{

    public class UseMyFormatterAttribute : Attribute, IControllerConfiguration
    {
        public void Initialize(HttpControllerSettings settings,
            HttpControllerDescriptor descriptor)
        {
            // Clear the formatters list.
            settings.Formatters.Clear();

            // Add a custom media-type formatter.
            settings.Formatters.Add(new MyFormatter());
        }
    }

    [UseMyFormatter]
    public class ValuesController : ApiController
    {
        // Controller methods not shown...
    }
}

Метод IControllerConfiguration.Initialize принимает два параметра:

Объект HttpControllerSettings
Объект HttpControllerDescriptor

HttpControllerDescriptor содержит описание контроллера, которое можно изучить в информационных целях (например, для различения двух контроллеров).

Используйте объект HttpControllerSettings для настройки контроллера. Этот объект содержит подмножество параметров конфигурации, которые можно переопределить для каждого контроллера. Все параметры, которые не изменяются по умолчанию на глобальный объект HttpConfiguration .

Поделиться через