Použití rozhraní ASP.NET Core API v knihovně tříd

Článek
01/16/2025

Tento dokument obsahuje pokyny k používání rozhraní ASP.NET Core API v knihovně tříd. Pro všechny ostatní pokyny ke knihovně, viz pokyny k open-source knihovně.

Určení verzí ASP.NET Core, které se mají podporovat

ASP.NET Core dodržuje zásady podpory .NET Core. Při určování, které verze ASP.NET Core podporovat v knihovně, konzultujte zásady podpory. Knihovna by měla:

Snažte se podporovat všechny verze ASP.NET Core klasifikované jako Long-Term support (LTS).
Nemáte povinnost podporovat verze ASP.NET Core, které jsou klasifikovány jako konec podpory (EOL).

Jakmile jsou k dispozici předběžné verze ASP.NET Core, jsou zásadní změny zveřejněny v úložišti GitHubu aspnet/Announcements. Testování kompatibility knihoven je možné provádět při vývoji funkcí architektury.

Použití sdílené architektury ASP.NET Core

S vydáním .NET Core 3.0 již mnoho sestavení ASP.NET Core není publikováno na NuGet jako balíčky. Místo toho jsou sestavení zahrnuta v rámci sdíleného rozhraní Microsoft.AspNetCore.App, které je nainstalováno s instalačními programy .NET Core SDK a modulu runtime. Seznam balíčků, které již nejsou publikovány, naleznete v tématu Odebrání zastaralých odkazů na balíčky.

Od verze .NET Core 3.0 projekty využívající sadu Microsoft.NET.Sdk.Web MSBuild SDK implicitně odkazují na sdílenou architekturu. Projekty používající SDK Microsoft.NET.Sdk nebo Microsoft.NET.Sdk.Razor musejí odkazovat na ASP.NET Core, aby mohly používat rozhraní API ASP.NET Core ve sdíleném rámci.

Pokud chcete odkazovat na ASP.NET Core, přidejte do souboru projektu následující prvek <FrameworkReference>:

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

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

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

</Project>

Zahrnutí rozšiřitelnosti Blazor

Blazor podporuje vytváření komponent Razor knihoven tříd pro aplikace na straně serveru a na straně klienta. Aby knihovna tříd podporovala Razor komponenty, musí používat Microsoft.NET.Sdk.Razor SDK.

Podpora aplikací na straně serveru a na straně klienta

Pokud chcete podporovat Razor spotřebu komponent na straně serveru a aplikací na straně klienta z jedné knihovny, postupujte podle následujících pokynů pro váš editor.

Visual Studio
Visual Studio Code / rozhraní příkazového řádku .NET

Použijte šablonu projektu knihovny tříd Razor.

Poznámka

Nevybírejte zaškrtávací políčko stránky podpory a zobrazení. Zaškrtnutím políčka se zobrazí knihovna tříd, která podporuje jenom aplikace na straně serveru.

V integrovaném terminálu (VS Code) nebo v příkazovém prostředí (.NET CLI) spusťte následující příkaz:

dotnet new razorclasslib

Poznámka

Do příkazu dotnet newnepřidávejte možnost -s|--support-pages-and-views. Když použijete možnost, zobrazí se knihovna tříd, která podporuje jenom aplikace na straně serveru.

Knihovna vygenerovaná ze šablony projektu:

Cílí na aktuální rozhraní .NET Framework na základě nainstalované sady SDK.
Umožňuje kontrolu kompatibility prohlížeče pro závislosti platformy zahrnutím browser jako podporované platformy s položkou SupportedPlatform MSBuild.
Přidá odkaz na balíček NuGet pro Microsoft.AspNetCore.Components.Web.

RazorClassLibrary-CSharp.csproj (referenční zdroj)

Poznámka

Odkazy na referenční dokumentaci .NET obvykle načítají výchozí větev úložiště, která představuje aktuální vývoj pro příští verzi .NET. Pokud chcete vybrat značku pro konkrétní verzi, použijte rozevírací seznam Přepnout větve nebo značky. Další informace najdete v tématu Jak vybrat značku verze zdrojového kódu ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Podpora více verzí architektury

Pokud knihovna musí podporovat funkce přidané do Blazor v aktuální verzi a zároveň podporovat jednu nebo více dřívějších verzí, nastavte knihovnu pro více cílů. Do vlastnosti TargetFrameworks MSBuild zadejte středníkem oddělený seznam monikerů cílového rámce (TFMs) .

<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>

V předchozím příkladu zástupný symbol {TARGET FRAMEWORKS} představuje seznam TFM oddělený středníkem. Například netcoreapp3.1;net5.0.

Podpora pouze spotřeby na straně serveru

Knihovny tříd jsou zřídka vytvořené tak, aby podporovaly pouze serverové aplikace. Pokud knihovna tříd vyžaduje jenom funkce specifické pro server, jako je například přístup k CircuitHandler nebo Microsoft.AspNetCore.Components.Server.ProtectedBrowserStorage, nebo používá funkce specifické pro ASP.NET Core, jako jsou middleware, MVC kontrolery nebo Razor Pages, použijte jeden z následujících přístupů:

Uveďte, že knihovna podporuje stránky a zobrazení při jejím vytváření s použitím zaškrtávacího políčka Podpora stránek a zobrazení (Visual Studio) nebo volby -s|--support-pages-and-views s příkazem dotnet new.
```
dotnet new razorclasslib -s
```
Kromě všech dalších potřebných parametrů MSBuild přidejte do souboru projektu knihovny odkaz na framework ASP.NET Core:
```
<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
```

Další informace o knihovnách obsahujících komponenty Razor najdete v tématu Využití komponent ASP.NET Core Razor z knihovny tříd Razor (RCL).

Zahrnutí rozšiřitelnosti MVC

Tato část popisuje doporučení pro knihovny, které zahrnují:

Razor zobrazení nebo Razor stránky
Tag Helpers značek
Zobrazit součásti

Tato část se nezabírá na více cílení na podporu více verzí MVC. Pokyny k podpoře více verzí ASP.NET Core najdete v tématu Podpora více verzí ASP.NET Core.

Razor zobrazení nebo Razor stránek

Projekt, který obsahuje Razor zobrazení nebo Razor stránky, musí používat sadu Microsoft.NET.Sdk.Razor SDK.

Pokud projekt cílí na .NET Core 3.x, vyžaduje:

Vlastnost AddRazorSupportForMvc MSBuild nastavená na true.
Prvek <FrameworkReference> pro sdílenou architekturu.

Šablona projektu Razor knihovny tříd splňuje předchozí požadavky pro projekty, které cílí na .NET Core. Postupujte podle následujících pokynů pro váš editor.

sady Visual Studio
Visual Studio Code / .NET CLI

Použijte šablonu projektu knihovny tříd Razor. Políčko stránky podpory a zobrazení šablony by mělo být zaškrtnuto.

V integrovaném terminálu (VS Code) nebo v příkazovém prostředí (.NET CLI) spusťte následující příkaz:

dotnet new razorclasslib -s

Například:

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

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

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

</Project>

Pokud projekt cílí na .NET Standard, vyžaduje se odkaz na balíček Microsoft.AspNetCore.Mvc. Balíček Microsoft.AspNetCore.Mvc se přesunul do sdílené architektury v ASP.NET Core 3.0 a proto se už nepublikuje. Například:

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

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

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

</Project>

Pomocníci pro značky

Projekt, který zahrnuje Tag Helpers , by měl používat SDK Microsoft.NET.Sdk. Pokud cílíte na .NET Core 3.x, přidejte prvek <FrameworkReference> pro sdílenou architekturu. Například:

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

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

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

</Project>

Pokud cílíte na .NET Standard (pro podporu verzí starších než ASP.NET Core 3.x), přidejte odkaz na balíček Microsoft.AspNetCore.Mvc.Razor. Balíček Microsoft.AspNetCore.Mvc.Razor se přesunul do sdílené architektury, a proto se už nepublikuje. Například:

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

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

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

</Project>

Zobrazení součástí

Projekt, který obsahuje komponenty View, by měl používat sadu Microsoft.NET.Sdk SDK. Pokud cílíte na .NET Core 3.x, přidejte prvek <FrameworkReference> pro sdílenou architekturu. Například:

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

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

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

</Project>

Pokud cílíte na .NET Standard (pro podporu verzí starších než ASP.NET Core 3.x), přidejte odkaz na balíček Microsoft.AspNetCore.Mvc.ViewFeatures. Balíček Microsoft.AspNetCore.Mvc.ViewFeatures se přesunul do sdílené architektury, a proto se už nepublikuje. Například:

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

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

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

</Project>

Podpora více verzí ASP.NET Core

K vytvoření knihovny, která podporuje více variant ASP.NET Core, se vyžaduje cílení na více verzí. Představte si scénář, ve kterém musí pomocná knihovna značek podporovat následující varianty ASP.NET Core:

ASP.NET Core 2.1, které cílí na rozhraní .NET Framework 4.6.1
Platforma ASP.NET Core 2.x je zaměřena na .NET Core 2.x
ASP.NET Core 3.x cílí na .NET Core 3.x

Následující soubor projektu podporuje tyto varianty prostřednictvím vlastnosti 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>

S předchozím souborem projektu:

Balíček Markdig se přidá pro všechny uživatele.
Odkaz na Microsoft.AspNetCore.Mvc.Razor je přidán pro uživatele zaměřující se na .NET Framework 4.6.1 nebo novější, případně na .NET Core 2.x. Verze 2.1.0 balíčku funguje s ASP.NET Core 2.2 kvůli zpětné kompatibilitě.
Na sdílenou architekturu se odkazuje pro uživatele, kteří cílí na .NET Core 3.x. Balíček Microsoft.AspNetCore.Mvc.Razor je součástí sdílené architektury.

Alternativně může být cílem .NET Standard 2.0 místo cílení na .NET Core 2.1 i .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>

V předchozím souboru projektu existují následující výstrahy:

Vzhledem k tomu, že knihovna obsahuje pouze Tag Helpers, je snazší zaměřit se na konkrétní platformy, na kterých ASP.NET Core běží: .NET Core a .NET Framework. Tag Helpery nemohou být používány jinými cílovými architekturami kompatibilními s .NET Standard 2.0, jako jsou Unity a UWP.
Použití .NET Standard 2.0 z rozhraní .NET Framework obsahuje některé problémy, které byly vyřešeny v rozhraní .NET Framework 4.7.2. Můžete zlepšit prostředí pro uživatele používající rozhraní .NET Framework 4.6.1 až 4.7.1 tím, že cílíte na rozhraní .NET Framework 4.6.1.

Pokud vaše knihovna potřebuje volat rozhraní API specifická pro konkrétní platformu, zaměřte se na konkrétní implementace .NET místo rozhraní .NET Standard. Pro více informací si přečtěte Multi-targeting.

Použijte rozhraní API, které se nezměnilo

Představte si scénář, ve kterém upgradujete middlewarovou knihovnu z .NET Core 2.2 na verzi 3.1. Rozhraní API middlewaru ASP.NET Core, která se používají v knihovně, se mezi ASP.NET Core 2.2 a 3.1 nezměnila. Pokud chcete pokračovat v podpoře middlewarové knihovny v .NET Core 3.1, postupujte takto:

Postupujte podle pokynů standardní knihovny .
Pokud odpovídající sestavení ve sdíleném rozhraní neexistuje, přidejte odkaz na balíček NuGet každého rozhraní API.

Použití rozhraní API, které se změnilo

Představte si scénář, ve kterém upgradujete knihovnu z .NET Core 2.2 na .NET Core 3.1. Rozhraní API ASP.NET Core, které se používá v knihovně, má zásadní změnu v ASP.NET Core 3.1. Zvažte, jestli je možné knihovnu přepsat tak, aby ve všech verzích nepoužíla poškozené rozhraní API.

Pokud můžete knihovnu přepsat, pokračujte v cílení na starší cílovou architekturu (například .NET Standard 2.0 nebo .NET Framework 4.6.1) s odkazy na balíčky.

Pokud knihovnu nemůžete přepsat, proveďte následující kroky:

Přidejte cíl pro .NET Core 3.1.
Přidejte prvek <FrameworkReference> pro sdílenou architekturu.
K podmíněné kompilaci kódu použijte direktivu preprocesoru #if s odpovídajícím symbolem cílové architektury.

Například synchronní čtení a zápisy v datových proudech požadavků HTTP a odpovědí jsou ve výchozím nastavení zakázány v ASP.NET Core 3.1. ASP.NET Core 2.2 ve výchozím nastavení podporuje synchronní chování. Zvažte middlewarovou knihovnu, ve které by se měly povolit synchronní čtení a zápisy, kde dochází k vstupně-výstupním operacím. Knihovna by měla vložit kód umožňující synchronní funkce do příslušné direktivy preprocesoru. Například:

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);
}

Použití rozhraní API zavedeného ve verzi 3.1

Představte si, že chcete použít rozhraní API ASP.NET Core, které bylo zavedeno v ASP.NET Core 3.1. Zvažte následující otázky:

Vyžaduje knihovna funkčně nové rozhraní API?
Může knihovna tuto funkci implementovat jiným způsobem?

Pokud knihovna funkčně vyžaduje rozhraní API a neexistuje způsob, jak ji implementovat na nižší úrovni:

Zaměřte se pouze na .NET Core 3.x.
Přidejte prvek <FrameworkReference> pro sdílenou architekturu.

Pokud knihovna může funkci implementovat jiným způsobem:

Přidejte .NET Core 3.x jako cílovou architekturu.
Přidejte prvek <FrameworkReference> pro sdílenou architekturu.
K podmíněné kompilaci kódu použijte direktivu preprocesoru #if s odpovídajícím symbolem cílové architektury.

Například následující pomocník značky používá rozhraní IWebHostEnvironment zavedené v ASP.NET Core 3.1. Uživatelé, kteří cílí na .NET Core 3.1, spouštějí cestu kódu definovanou symbolem cílové architektury NETCOREAPP3_1. Typ parametru značkového pomocníka se změní na IHostingEnvironment pro uživatele .NET Core 2.1 a .NET Framework 4.6.1. Tato změna byla nezbytná, protože ASP.NET Core 3.1 označil IHostingEnvironment jako zastaralé a doporučené IWebHostEnvironment jako náhradu.

[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
}

Následující víceúčelový soubor projektu podporuje tento scénář pomocníka značek.

<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>

Použít API odebrané ze sdíleného frameworku

Chcete-li použít sestavení ASP.NET Core, které bylo odebráno ze sdílené architektury, přidejte odpovídající odkaz na balíček. Seznam balíčků odebraných ze sdílené architektury v ASP.NET Core 3.1 najdete v tématu Odebrání zastaralých odkazů na balíčky.

Pokud například chcete přidat klienta webového rozhraní 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>

Sdílet prostřednictvím

Použití rozhraní ASP.NET Core API v knihovně tříd

Určení verzí ASP.NET Core, které se mají podporovat

Použití sdílené architektury ASP.NET Core

Zahrnutí rozšiřitelnosti Blazor

Podpora aplikací na straně serveru a na straně klienta

Podpora více verzí architektury

Podpora pouze spotřeby na straně serveru

Zahrnutí rozšiřitelnosti MVC

Razor zobrazení nebo Razor stránek

Pomocníci pro značky

Zobrazení součástí

Podpora více verzí ASP.NET Core

Použijte rozhraní API, které se nezměnilo

Použití rozhraní API, které se změnilo

Použití rozhraní API zavedeného ve verzi 3.1

Použít API odebrané ze sdíleného frameworku

Další zdroje informací

Další materiály