Использование api ASP.NET Core в библиотеке классов

Скотт Адди

В этом документе приведены рекомендации по использованию api ASP.NET Core в библиотеке классов. Дополнительные рекомендации по библиотеке см. в руководстве по библиотеке с открытым кодом.

Определение поддерживаемых версий ASP.NET Core

ASP.NET Core соответствует политике поддержки .NET Core . Обратитесь к политике поддержки при определении версий ASP.NET Core для поддержки в библиотеке. Библиотека должна:

• Постарайтесь поддерживать все версии ASP.NET Core, классифицируемые как Long-Term поддержка (LTS).
• Не чувствовать себя обязанным поддерживать версии ASP.NET Core, классифицируемые как end of Life (EOL).

Как только становятся доступными предварительные выпуски ASP.NET Core, критические изменения публикуются в репозитории aspnet/Announcements на GitHub. Тестирование совместимости библиотек можно проводить в рамках разработки функций платформы.

Использование общей платформы ASP.NET Core

В выпуске .NET Core 3.0 многие сборки ASP.NET Core больше не публикуются в NuGet в виде пакетов. Вместо этого сборки включены в общую инфраструктуру Microsoft.AspNetCore.App, которая устанавливается вместе с установщиками SDK и среды выполнения .NET Core. Список пакетов, которые больше не публикуются, см. в разделе Удаление устаревших ссылок на пакеты.

По состоянию на .NET Core 3.0 проекты с помощью пакета SDK MSBuild Microsoft.NET.Sdk.Web неявно ссылались на общую платформу. Проекты, использующие пакет SDK Microsoft.NET.Sdk или Microsoft.NET.Sdk.Razor, должны ссылаться на ASP.NET Core, чтобы использовать api ASP.NET Core в общей платформе.

Чтобы ссылаться на ASP.NET Core, добавьте следующий элемент <FrameworkReference> в файл проекта:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

Включить расширяемость Blazor

Blazor поддерживает создание компонентов Razor библиотек классов для серверных и клиентских приложений. Чтобы поддерживать компоненты Razor в библиотеке классов, библиотека классов должна использовать Microsoft.NET.Sdk.Razor.

Поддержка серверных и клиентских приложений

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

Visual Studio

Используйте шаблон проекта библиотеки классов Razor.

Заметка

Не выбирайте флажок страницы поддержки и представления. Выбор флажка приводит к тому, что библиотека классов поддерживает только серверные приложения.

Visual Studio Code или .NET CLI

Выполните следующую команду в интегрированном терминале (VS Code) или командной оболочке (.NET CLI):

dotnet new razorclasslib

Заметка

Не добавляйте параметр -s|--support-pages-and-views в команду dotnet new. Применение параметра приводит к использованию библиотеки классов, которая поддерживает только серверные приложения.

Библиотека, созданная из шаблона проекта:

• Предназначен для текущей платформы .NET на основе установленного пакета SDK.
• Активирует проверки совместимости браузера для зависимости от платформы, добавляя browser в список поддерживаемых платформ с элементом MSBuild SupportedPlatform.
• Добавляет ссылку на пакет NuGet для Microsoft.AspNetCore.Components.Web.

RazorClassLibrary-CSharp.csproj (эталонный источник)

Заметка

Ссылки на справочную документацию .NET обычно загружают основную ветвь репозитория, которая представляет текущую разработку для следующего выпуска .NET. Чтобы выбрать тег для определенного выпуска, используйте раскрывающийся список Switch ветвей или тегов. Дополнительные сведения см. в разделе Выбор тега версии исходного кода ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Поддержка нескольких версий платформы

Если библиотека должна поддерживать функции, добавленные в Blazor в текущем выпуске, а также один или несколько более ранних выпусков, следует обеспечить многоцелевое нацеливание библиотеки. Укажите разделенный точкой с запятой список целевых платформных идентификаторов (TFMs) в свойстве MSBuild TargetFrameworks.

<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>

В предыдущем примере заполнитель {TARGET FRAMEWORKS} представляет собой список TFM'ов, разделенных точкой с запятой. Например, netcoreapp3.1;net5.0.

Поддержка только потребления на стороне сервера

Библиотеки классов редко создаются только для поддержки серверных приложений. Если для библиотеки классов требуются только функции на стороне сервера, например доступ к CircuitHandler или Microsoft.AspNetCore.Components.Server.ProtectedBrowserStorage, или используются функции ASP.NET Core, такие как по промежуточному слоям, контроллерам MVC или Razor Pages, используйте один следующих подходов:

• Укажите, что библиотека поддерживает страницы и представления, используя флажок "Поддержка страниц и представлений" (Visual Studio) или параметр -s|--support-pages-and-views с командой dotnet new:

  dotnet new razorclasslib -s
  

• В файле проекта библиотеки должна быть предоставлена только ссылка на платформу ASP.NET Core, а также любые другие необходимые свойства MSBuild.

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>
  

Для получения дополнительной информации о библиотеках, содержащих компоненты Razor, см. раздел «Использование компонентов ASP.NET Core Razor из библиотеки классов (RCL) Razor».

Включение расширяемости MVC

В этом разделе описываются рекомендации по библиотекам, которые включают:

• Razor представления или Razor страницы
• помощники тегов
• Просмотр компонентов

В этом разделе не обсуждается мульти-таргетинг с целью поддержки нескольких версий MVC. Рекомендации по поддержке нескольких версий ASP.NET Core см. в разделе Поддержка нескольких версий ASP.NET Core.

Razor просмотры или Razor страницы

Проект, включающий представления Razor или Razor Pages, должен использовать Microsoft.NET.Sdk.пакета SDKRazor .

Если проект предназначен для .NET Core 3.x, он требует:

• Для свойства MSBuild AddRazorSupportForMvc задано значение true.
• Элемент <FrameworkReference> для общей платформы.

Шаблон проекта Class Library Razor соответствует предыдущим требованиям для проектов, рассчитанных на .NET Core. Используйте следующие инструкции для редактора.

Visual Studio

Используйте шаблон проекта библиотеки классов Razor. Флажок поддержки страниц и представлений шаблона должен быть установлен.

Visual Studio Code или .NET CLI

Выполните следующую команду в интегрированном терминале (VS Code) или командной оболочке (.NET CLI):

dotnet new razorclasslib -s

Например:

<Project Sdk="Microsoft.NET.Sdk.Razor">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <AddRazorSupportForMvc>true</AddRazorSupportForMvc>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

Если проект предназначен для .NET Standard, требуется справочник по пакету Microsoft.AspNetCore.Mvc. Пакет Microsoft.AspNetCore.Mvc перемещен в общую платформу в ASP.NET Core 3.0 и поэтому больше не публикуется. Например:

<Project Sdk="Microsoft.NET.Sdk.Razor">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
  </ItemGroup>

</Project>

Вспомогательные функции тегов

Проект, включающий вспомогательные функции тегов , должен использовать пакет SDK Microsoft.NET.Sdk. Если вы нацелены на .NET Core 3.x, добавьте элемент <FrameworkReference> для общей среды выполнения. Например:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

Если вы используете .NET Standard (для поддержки версий, предшествующих ASP.NET Core 3.x), добавьте ссылку на пакет Microsoft.AspNetCore.Mvc.Razor. Пакет Microsoft.AspNetCore.Mvc.Razor перемещен в общую платформу и поэтому больше не публикуется. Например:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
  </ItemGroup>

</Project>

Просмотр компонентов

Проект, включающий компоненты представления , должен использовать пакет SDK Microsoft.NET.Sdk. Если вы используете .NET Core 3.x, добавьте элемент <FrameworkReference> для общего фреймворка. Например:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

Если вы используете .NET Standard (для поддержки версий, предшествующих ASP.NET Core 3.x), добавьте ссылку на пакет Microsoft.AspNetCore.Mvc.ViewFeatures. Пакет Microsoft.AspNetCore.Mvc.ViewFeatures перемещен в общую платформу и поэтому больше не публикуется. Например:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc.ViewFeatures" Version="2.2.0" />
  </ItemGroup>

</Project>

Поддержка нескольких версий ASP.NET Core

Для создания библиотеки, поддерживающей несколько вариантов ASP.NET Core, требуется многоцелевое таргетирование. Рассмотрим сценарий, в котором вспомогательные библиотеки тегов должны поддерживать следующие варианты ASP.NET Core:

• ASP.NET Core 2.1, предназначенный для .NET Framework 4.6.1
• ASP.NET Core 2.x, нацеленный на .NET Core 2.x
• ASP.NET Core 3.x для .NET Core 3.x

Следующий файл проекта поддерживает эти варианты через свойство TargetFrameworks:

<Project Sdk="Microsoft.NET.Sdk">
  
  <PropertyGroup>
    <TargetFrameworks>netcoreapp2.1;netcoreapp3.1;net461</TargetFrameworks>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="Markdig" Version="0.16.0" />
  </ItemGroup>
  
  <ItemGroup Condition="'$(TargetFramework)' != 'netcoreapp3.1'">
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor" Version="2.1.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netcoreapp3.1'">
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>
</Project>

С помощью предыдущего файла проекта:

• Пакет Markdig добавляется для всех потребителей.
• Ссылка на Microsoft.AspNetCore.Mvc.Razor добавляется для потребителей, работающих с .NET Framework 4.6.1 или более поздней версией или .NET Core 2.x. Версия 2.1.0 пакета работает с ASP.NET Core 2.2 из-за обратной совместимости.
• Общая платформа используется для приложений, нацеленных на .NET Core 3.x. Пакет Microsoft.AspNetCore.Mvc.Razor входит в общую платформу.

В качестве альтернативы, можно использовать .NET Standard 2.0 вместо нацеливания на оба: .NET Core 2.1 и .NET Framework 4.6.1.

<Project Sdk="Microsoft.NET.Sdk">
  
  <PropertyGroup>
    <TargetFrameworks>netstandard2.0;netcoreapp3.1</TargetFrameworks>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="Markdig" Version="0.16.0" />
  </ItemGroup>
  
  <ItemGroup Condition="'$(TargetFramework)' != 'netcoreapp3.1'">
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor" Version="2.1.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netcoreapp3.1'">
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>
</Project>

В предыдущем файле проекта существуют следующие предостережения:

• Так как библиотека содержит только вспомогательные функции тегов, проще использовать определенные платформы, на которых выполняется ASP.NET Core: .NET Core и .NET Framework. Вспомогательные платформы тегов не могут использоваться другими целевыми платформами, совместимыми с .NET Standard 2.0, такими как Unity и UWP.
• Использование .NET Standard 2.0 из .NET Framework имеет некоторые проблемы, которые были устранены в .NET Framework 4.7.2. Вы можете улучшить опыт для потребителей, используя .NET Framework от 4.6.1 до 4.7.1 включительно, ориентируя на .NET Framework 4.6.1.

Если библиотеке необходимо вызвать API для конкретной платформы, нацелите конкретные реализации .NET вместо .NET Standard. Для получения дополнительной информации см. Мульти-таргетинг.

Используйте API, который не изменился

Представьте сценарий, в котором вы обновляете библиотеку промежуточного слоя с .NET Core 2.2 до 3.1. API посреднические интерфейсы ASP.NET Core, используемые в библиотеке, не изменились между версиями ASP.NET Core 2.2 и 3.1. Чтобы продолжить поддержку библиотеки ПО промежуточного слоя в .NET Core 3.1, сделайте следующее:

• Следуйте руководству стандартной библиотеки .
• Добавьте ссылку на пакет NuGet каждого API, если соответствующая сборка не существует в общей платформе.

Используйте изменённый API

Представьте сценарий, в котором вы обновляете библиотеку с .NET Core 2.2 до .NET Core 3.1. API ASP.NET Core, используемый в библиотеке, имеет ломающее изменение в ASP.NET Core 3.1. Рассмотрите возможность перезаписи библиотеки, чтобы не использовать неисправный API во всех версиях.

Если вы можете перезаписать библиотеку, сделайте это и продолжите использовать более раннюю целевую платформу (например, .NET Standard 2.0 или .NET Framework 4.6.1) со ссылками на пакеты.

Если вы не можете переписать библиотеку, выполните следующие действия.

• Добавьте целевой объект для .NET Core 3.1.
• Добавьте элемент <FrameworkReference> для общей платформы.
• Используйте директиву препроцессора #if с соответствующим символом целевой платформы для условной компиляции кода.

Например, синхронные операции чтения и записи в потоках HTTP-запросов и ответов по умолчанию отключены по состоянию на ASP.NET Core 3.1. ASP.NET Core 2.2 поддерживает синхронное поведение по умолчанию. Рассмотрим библиотеку ПО промежуточного слоя, в которой должны быть включены синхронные операции чтения и записи, в которых выполняется ввод-вывод. Библиотека должна помещать код, чтобы активировать синхронные функции в соответствующую директиву препроцессора. Например:

public async Task Invoke(HttpContext httpContext)
{
    if (httpContext.Request.Path.StartsWithSegments(_path, StringComparison.Ordinal))
    {
        httpContext.Response.StatusCode = (int) HttpStatusCode.OK;
        httpContext.Response.ContentType = "application/json";
        httpContext.Response.ContentLength = _bufferSize;

#if !NETCOREAPP3_1 && !NETCOREAPP5_0
        var syncIOFeature = httpContext.Features.Get<IHttpBodyControlFeature>();
        if (syncIOFeature != null)
        {
            syncIOFeature.AllowSynchronousIO = true;
        }

        using (var sw = new StreamWriter(
            httpContext.Response.Body, _encoding, bufferSize: _bufferSize))
        {
            _json.Serialize(sw, new JsonMessage { message = "Hello, World!" });
        }
#else
        await JsonSerializer.SerializeAsync<JsonMessage>(
            httpContext.Response.Body, new JsonMessage { message = "Hello, World!" });
#endif
        return;
    }

    await _next(httpContext);
}

Использование API, представленного в версии 3.1

Представьте, что вы хотите использовать ASP.NET Core API, который был представлен в ASP.NET Core 3.1. Рассмотрим следующие вопросы:

1. Требуется ли библиотеке новый API функционально?
2. Может ли библиотека реализовать эту функцию по-другому?

Если библиотеке функционально требуется API и его реализация не выполняется на нижнем уровне:

• Предназначен только для .NET Core 3.x.
• Добавьте элемент <FrameworkReference> для общей платформы.

Если библиотека может реализовать функцию по-другому:

• Добавьте .NET Core 3.x в качестве целевой платформы.
• Добавьте элемент <FrameworkReference> для общей платформы.
• Используйте директиву препроцессора #if с соответствующим символом целевой платформы для условной компиляции кода.

Например, следующий вспомогательный тег использует интерфейс IWebHostEnvironment, представленный в ASP.NET Core 3.1. Потребители, нацеленные на .NET Core 3.1, выполняют код, определенный символом целевой платформы NETCOREAPP3_1. Тип параметра конструктора помощника тегов изменяется на IHostingEnvironment для пользователей .NET Core 2.1 и .NET Framework 4.6.1. Это изменение было необходимо, так как ASP.NET Core 3.1 IHostingEnvironment помечены как устаревшие и рекомендуемые IWebHostEnvironment в качестве замены.

[HtmlTargetElement("script", Attributes = "asp-inline")]
public class ScriptInliningTagHelper : TagHelper
{
    private readonly IFileProvider _wwwroot;

#if NETCOREAPP3_1
    public ScriptInliningTagHelper(IWebHostEnvironment env)
#else
    public ScriptInliningTagHelper(IHostingEnvironment env)
#endif
    {
        _wwwroot = env.WebRootFileProvider;
    }

    // code omitted for brevity
}

Следующий многоцелевой файл проекта поддерживает этот вспомогательный сценарий тега:

<Project Sdk="Microsoft.NET.Sdk">
  
  <PropertyGroup>
    <TargetFrameworks>netcoreapp2.1;netcoreapp3.1;net461</TargetFrameworks>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="Markdig" Version="0.16.0" />
  </ItemGroup>
  
  <ItemGroup Condition="'$(TargetFramework)' != 'netcoreapp3.1'">
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor" Version="2.1.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netcoreapp3.1'">
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>
</Project>

Использование API, удаленного из общей платформы

Чтобы использовать сборку ASP.NET Core, удаленную из общей платформы, добавьте соответствующую ссылку на пакет. Список пакетов, удаленных из общей платформы в ASP.NET Core 3.1, см. в разделе Удаление устаревших ссылок на пакеты.

Например, чтобы добавить клиент веб-API:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNet.WebApi.Client" Version="5.2.7" />
  </ItemGroup>

</Project>

Дополнительные ресурсы

• Повторное использование пользовательского интерфейса Razor в библиотеках классов с ASP.NET Core
• Использование компонентов ASP.NET Core Razor из библиотеки классов Razor (RCL)
• поддержка реализации .NET
• Поддержка .NET: принципы и политика