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

Autor: Scott Addie

Tento dokument obsahuje pokyny k používání rozhraní ASP.NET Core API v knihovně tříd. Všechny ostatní doprovodné materiály ke knihovně najdete v pokynech k opensourcové 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 pro podporu v knihovně, najdete v zásadách podpory. Knihovna by měla:

• Snažte se podporovat všechny verze ASP.NET Core klasifikované jako dlouhodobé podpory (LTS).
• Není nutné podporovat verze ASP.NET Core klasifikované jako konec životnosti (EOL).

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

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

Ve verzi .NET Core 3.0 už mnoho sestavení ASP.NET Core není publikováno do Balíčku NuGet jako balíčky. Místo toho jsou sestavení součástí Microsoft.AspNetCore.App sdílené architektury, která se instaluje s instalačními programy sady .NET Core SDK a modulu runtime. Seznam balíčků, které se už nepublikují, najdete v tématu Odebrání zastaralých odkazů na balíčky.

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

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

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

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

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

</Project>

Zahrnutí Blazor rozšiřitelnosti

Blazor podporuje vytváření Razor knihoven tříd komponent pro aplikace na straně serveru a na straně klienta. Aby bylo možné podporovat Razor komponenty v knihovně tříd, musí knihovna tříd používat sadu 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

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

Poznámka

Nezaškrtávejte políčko Stránky podpory a zobrazení. Zaškrtnutím políčka se zobrazí knihovna tříd, která podporuje jenom aplikace na straně serveru.

Visual Studio Code / .NET Core CLI

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

Nepřidávejte do -s|--support-pages-and-viewsdotnet new příkazu možnost. 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 kontroly kompatibility prohlížeče pro závislosti platformy zahrnutím browser jako podporované platformy s SupportedPlatform položkou MSBuild.
• Přidá odkaz na balíček NuGet pro Microsoft.AspNetCore.Components.Web.

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

Poznámka

Odkazy na dokumentaci k referenčnímu zdroji .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 pro přepnutí větví nebo značek. 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 aktuální verze a zároveň podporovat jednu nebo více dřívějších verzí, více cílit na knihovnu. Zadejte středník oddělený seznam cílových architektur Monikers (TFMs) ve TargetFrameworks vlastnosti MSBuild:

<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>

V předchozím příkladu {TARGET FRAMEWORKS} představuje zástupný symbol 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 přístup nebo CircuitHandlerMicrosoft.AspNetCore.Components.Server.ProtectedBrowserStoragepoužití ASP.NET funkcí specifických pro jádra, jako jsou middleware, kontrolery MVC nebo Razor stránky, použijte jeden z následujících přístupů:

• Určete, že knihovna podporuje stránky a zobrazení při vytváření knihovny pomocí zaškrtávacího políčka Stránky podpory a zobrazení (Visual Studio) nebo pomocí -s|--support-pages-and-viewsdotnet new příkazu:

  dotnet new razorclasslib -s
  

• Kromě všech dalších požadovaných vlastností sestavení MS uveďte odkaz na architekturu pouze na ASP.NET Core v souboru projektu knihovny:

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

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

Zahrnutí rozšiřitelnosti MVC

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

• Razor zobrazení nebo Razor stránky
• Pomocné rutiny značek
• Komponenty zobrazení

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

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 MSBuild nastavena AddRazorSupportForMvc na true.
• Prvek <FrameworkReference> pro sdílenou architekturu.

Šablona Razor projektu 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.

Visual Studio

Razor Použijte šablonu projektu Knihovny tříd. Mělo by být zaškrtnuté políčko Stránky podpory a zobrazení šablony.

Visual Studio Code / .NET Core CLI

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

Pří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. Pří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é rutiny značek

Projekt, který obsahuje pomocné rutiny značek, by měl používat Microsoft.NET.Sdk sadu SDK. Pokud cílíte na .NET Core 3.x, přidejte prvek pro sdílenou <FrameworkReference> architekturu. Pří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. Příklad:

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

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

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

</Project>

Komponenty zobrazení

Projekt, který obsahuje součásti zobrazení, by měl používat Microsoft.NET.Sdk sadu SDK. Pokud cílíte na .NET Core 3.x, přidejte prvek pro sdílenou <FrameworkReference> architekturu. Pří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. Pří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
• ASP.NET Core 2.x cílí 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 TargetFrameworks vlastnosti:

<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, kteří cílí na rozhraní .NET Framework 4.6.1 nebo novější nebo .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 pomocné rutiny značek, je jednodušší cílit na konkrétní platformy, na kterých běží ASP.NET Core: .NET Core a .NET Framework. Pomocné rutiny značek nemůžou používat jiné cílové architektury kompatibilní s .NET Standard 2.0, jako jsou Unity, UPW a Xamarin.
• 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. Další informace najdete v tématu Cílení na více verzí.

Použití 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 používané 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 pro sdílenou <FrameworkReference> architekturu.
• K podmíněné kompilaci kódu použijte direktivu #if preprocesoru 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 uzavřít kód, který umožní synchronní funkce v příslušné direktivě preprocesoru. Pří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:

1. Vyžaduje knihovna nové rozhraní API funkčně?
2. 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:

• Cílová pouze .NET Core 3.x.
• Přidejte prvek pro sdílenou <FrameworkReference> architekturu.

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

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

Například následující pomocník značky IWebHostEnvironment používá rozhraní zavedené v ASP.NET Core 3.1. Uživatelé, kteří cílí na .NET Core 3.1, spouštějí cestu kódu definovanou NETCOREAPP3_1 symbolem cílové architektury. Typ parametru konstruktoru značky se změní na IHostingEnvironment 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čila IHostingEnvironment jako zastaralá a doporučená IWebHostEnvironment jako náhrada.

[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í soubor projektu s více cíli podporuje tento scénář pomocné rutiny 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žití rozhraní API odebrané ze sdílené architektury

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>

Další prostředky

• Opakovaně použitelné uživatelské rozhraní Razor v knihovnách tříd s využitím ASP.NET Core
• Využívání komponent ASP.NET Core Razor v knihovně tříd Razor (RCL)
• Podpora implementace .NET
• Zásady podpory .NET