použití rozhraní api ASP.NET Core v knihovně tříd

Scott Addie

tento dokument poskytuje pokyny pro použití rozhraní api ASP.NET Core v knihovně tříd. Všechny ostatní doprovodné materiály ke knihovně naleznete v tématu Open-Source doprovodnémateriály.

určete, které verze ASP.NET Core se mají podporovat.

ASP.NET Core dodržuje zásady podpory .net Core. při určování, které verze ASP.NET Core se mají podporovat v knihovně, se podívejte na zásady podpory. Knihovna by měla:

• udělejte úsilí, aby podporovalo všechny ASP.NET Core verze klasifikované jako dlouhodobá podpora (LTS).
• nejedná se o povinnost podporovat ASP.NET Core verze klasifikované jako konec života (konce řádku).

v rámci verze preview ASP.NET Core k dispozici jsou zásadní změny publikované v úložišti aspnet/oznámení GitHub. Testování kompatibility knihoven se dá provádět jako vývoj funkcí rozhraní.

použití sdíleného rozhraní ASP.NET Core

s vydáním .net Core 3,0 se už mnoho ASP.NET Corech sestavení nezveřejňuje, aby se NuGet jako balíčky. Místo toho jsou sestavení zahrnuta do Microsoft.AspNetCore.App sdíleného rozhraní, které je nainstalováno s instalačními programy .NET Core SDK a modulem runtime. Seznam balíčků, které už nejsou publikované, najdete v tématu odebrání zastaralých odkazů na balíčky.

od .net Core 3,0 projekty, které používají Microsoft.NET.Sdk.Web sadu MSBuild SDK, implicitně odkazují na sdílené rozhraní. projekty, které Microsoft.NET.Sdk používají Microsoft.NET.Sdk.Razor sadu SDK nebo, musí odkazovat ASP.NET Core, aby používaly rozhraní api ASP.NET Core ve sdíleném rozhraní.

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

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

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

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

</Project>

odkazování ASP.NET Core tímto způsobem je podporováno pouze pro projekty cílené na .net Core 3. x.

informace o použití rozhraní api ASP.NET Core 5,0 a novějších v knihovně tříd naleznete v tomto GitHub problém.

Zahrnout Blazor rozšiřitelnost

Blazor podporuje WebAssembly (WASM) a hostitelské modelyzaložené na serveru. Pokud neexistuje konkrétní důvod k podpoře obou hostujících modelů, knihovna Razor komponent by měla podporovat oba modely hostování. RazorKnihovna komponent musí používat Microsoft. NET. SDK. Razor Sada SDK.

Podpora obou modelů hostování

Pro podporu Razor spotřeby komponent podle Blazor WebAssembly a Blazor Server projektů použijte následující pokyny pro Editor.

dotnet new razorclasslib

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

  <PropertyGroup>
    <TargetFramework>{TARGET FRAMEWORK}</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <SupportedPlatform Include="browser" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Components.Web" Version="{VERSION}" />
  </ItemGroup>

</Project>

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

  <PropertyGroup>
    <TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>
  </PropertyGroup>

  <ItemGroup>
    <SupportedPlatform Include="browser" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Components.Web" Version="{VERSION}" />
  </ItemGroup>

</Project>

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

  <PropertyGroup>
    <TargetFrameworks>netstandard2.0</TargetFrameworks>
    <RazorLangVersion>3.0</RazorLangVersion>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Components" Version="3.1.17" />
    <PackageReference Include="Microsoft.AspNetCore.Components.Web" Version="3.1.17" />
  </ItemGroup>

</Project>

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

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

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

</Project>

Další informace o knihovnách obsahujících Razor komponenty naleznete v tématu využívání Razor komponent ASP.NET Core z Razor knihoven tříd .

Zahrnutí rozšiřitelnosti MVC

V této části najdete popis doporučení pro knihovny, které zahrnují:

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

Tato část se nezabývá cílením 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 Microsoft. NET. SDK. Razor Sada SDK.

Pokud je projekt cílen na rozhraní .NET Core 3. x, vyžaduje:

• AddRazorSupportForMvcvlastnost MSBuild nastavena na hodnotu true .
• <FrameworkReference>Prvek pro sdílenou architekturu.

Šablona projektu Razor knihovny tříd splňuje předchozí požadavky pro projekty cílené na .NET Core 3. x. Pro editor použijte následující pokyny.

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 se místo toho projekt cílí .NET Standard, je vyžadován odkaz na balíček Microsoft. AspNetCore. Mvc . Microsoft.AspNetCore.Mvcbalíček se přesunul do sdíleného rozhraní v ASP.NET Core 3,0, a proto už není publikovaný. 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íky značek , by měl používat Microsoft.NET.Sdk sadu SDK. Pokud cílíte na rozhraní .NET Core 3. x, přidejte <FrameworkReference> element pro sdílené rozhraní. 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 do Microsoft. AspNetCore. Razor Mvc.. Balíček Microsoft.AspNetCore.Mvc.Razor se přesunul do sdílené architektury, a proto už není publikovaný. 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 View, by měl používat Microsoft.NET.Sdk sadu SDK. Pokud cílíte na .NET Core 3.x, přidejte <FrameworkReference> element pro sdílenou rozhraní. Příklad:

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

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

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

</Project>

Pokud cílení .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 už není publikovaný. 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 ASP.NET Core verzí

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

• ASP.NET Core 2.1 cílení na .NET Framework 4.6.1
• ASP.NET Core 2.x cílení na .NET Core 2.x
• ASP.NET Core 3.x cílení 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řidaný pro uživatele cílené .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 z důvodu zpětné kompatibility.
• Na sdílené rozhraní 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ě .NET Standard cílí na verzi 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í upozornění:

• Vzhledem k tomu, že knihovna obsahuje pouze pomocné objekty značek, je jednodušší cílit na konkrétní platformy, na ASP.NET Core běží: .NET Core a .NET Framework. Pomocné objekty značek nemůžou používat jiné cílové architektury kompatibilní .NET Standard 2.0, jako je Unity, UPW a Xamarin.
• Při .NET Standard 2.0 z .NET Framework se některé problémy, které byly vyřešeny ve .NET Framework 4.7.2. Prostředí pro uživatele používající .NET Framework 4.6.1 až 4.7.1 můžete vylepšit cílením na .NET Framework 4.6.1.

Pokud vaše knihovna potřebuje volat rozhraní API specifická pro platformu, místo cílení na konkrétní implementace .NET .NET Standard. Další informace najdete v tématu Cílení na více verzí.

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

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

• Postupujte podle pokynů ke standardní knihovně.
• Přidejte odkaz na balíček pro balíček NuGet rozhraní API, pokud odpovídající sestavení ve sdíleném rozhraní neexistuje.

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

Imagine 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á ve ASP.NET Core 3.1 ASP.NET Core změnu. Zvažte, jestli je možné knihovnu přepsat tak, aby nepou rušila rozhraní API ve všech verzích.

Pokud můžete přepsat knihovnu, proveďte to a pokračujte v cílení na starší cílovou rozhraní (například .NET Standard 2.0 nebo .NET Framework 4.6.1) s odkazy na balíček.

Pokud knihovnu nemůžete přepsat, postupujte následovně:

• Přidejte cíl pro .NET Core 3.1.
• Přidejte <FrameworkReference> element pro sdílenou rozhraní.
• Pomocí #if preprocesoru s příslušným symbolem cílové architektury můžete podmíněně kompilovat kód.

Například synchronní čtení a zápisy u požadavků HTTP a streamů odpovědí jsou ve výchozím nastavení ve výchozím nastavení ASP.NET Core 3.1. ASP.NET Core 2.2 ve výchozím nastavení podporuje synchronní chování. Představte si knihovnu middlewaru, ve které by měla být povolena synchronní čtení a zápis v místě, kde dochází k vstupně-výstupním operacem. Knihovna by měla uzavřít kód, který povolí synchronní funkce, do příslušné direktivy 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 představené ve verze 3.1

Imagine, že chcete použít rozhraní API ASP.NET Core, které bylo představeno ve ASP.NET Core 3.1. Zvažte následující otázky:

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

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

• Cílit jenom na .NET Core 3.x
• Přidejte <FrameworkReference> element pro sdílenou rozhraní.

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

• Přidejte .NET Core 3.x jako cílovou rozhraní.
• Přidejte <FrameworkReference> element pro sdílenou rozhraní.
• Pomocí #if preprocesoru s příslušným symbolem cílové architektury můžete podmíněně kompilovat kód.

Například následující pomocná metoda značky používá rozhraní zavedené v ASP.NET Core IWebHostEnvironment 3.1. Spotřebiteli, kteří cílí na .NET Core 3.1, spustí cestu kódu definovanou NETCOREAPP3_1 symbolem cílové architektury. Typ parametru konstruktoru pomocníka značek se změní na pro IHostingEnvironment .NET Core 2.1 a .NET Framework 4.6.1. Tato změna byla nezbytná, ASP.NET Core verzi 3.1 označenou jako zastaralou a IHostingEnvironment IWebHostEnvironment doporučenou 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í soubor projektu s více cílemi podporuje tento scénář pomocníka se značkami:

<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 ASP.NET Core sestavení, které bylo odebráno ze sdílené architektury, přidejte příslušný odkaz na balíček. Seznam balíčků odebraných ze sdílené architektury ve verzi 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>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

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

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

</Project>

Další zdroje informací

• Opakovaně použitelné Razor uživatelské rozhraní v knihovnách tříd pomocí ASP.NET Core
• využívání Razor komponent ASP.NET Core z Razor knihoven tříd
• Podpora implementace .NET
• Zásady podpory pro .NET