ASP.NET Core API-k használata egy osztálytárban

Készítette: Scott Addie

Ez a dokumentum útmutatást nyújt a ASP.NET Core API-k osztálytárakban való használatához. További útmutatásért tekintse meg nyílt forráskódú kódtárak útmutatóját.

Annak meghatározása, hogy mely ASP.NET Core-verziókat kell támogatni

ASP.NET Core betartja a .NET és a .NET Core támogatási szabályzatot. Tekintse meg a támogatási szabályzatot, amikor meghatározza, hogy mely ASP.NET Core-verziókat kell támogatni egy könyvtárban. A könyvtárnak:

Igyekezz támogatni az összes ASP.NET Core verziót, amelyeket Long-Term támogatási (LTS) kategóriába soroltunk.
Nem érzi kötelezőnek ASP.NET End of Life (EOL) besorolású Core-verziók támogatását.

Az ASP.NET Core előzetes kiadásainak elérhetővé válásakor a megszakító módosításokat az aspnet/Announcements GitHub-adattárban teszik közzé. A kódtárak kompatibilitási tesztelése a keretrendszer-funkciók fejlesztése során végezhető el.

A ASP.NET Core megosztott keretrendszerének használata

A .NET Core 3.0 kiadásával számos ASP.NET Core-szerelvények már nem jelennek meg csomagként a NuGetben. Ehelyett az összeállítások a megosztott keretrendszerbe tartoznak, amely a .NET SDK és a futtatókörnyezet telepítőivel van telepítve. A már nem közzétett csomagok listáját a Elavult csomaghivatkozások eltávolításacímű témakörben találja.

A .NET Core 3.0-s verziójától a Microsoft.NET.Sdk.Web MSBuild SDK-t használó projektek implicit módon hivatkoznak a megosztott keretrendszerre. A Microsoft.NET.Sdk vagy Microsoft.NET.Sdk.Razor SDK-t használó projekteknek ASP.NET Core-ra kell hivatkoznia a megosztott keretrendszerben ASP.NET Core API-k használatához.

Az ASP.NET Core-ra való hivatkozáshoz adja hozzá a következő <FrameworkReference> elemet a projektfájlhoz:

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

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

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

</Project>

Blazor bővíthetőségének belefoglalása

Blazor támogatja Razor összetevők osztálykódtárak létrehozását kiszolgálóoldali és ügyféloldali alkalmazásokhoz. Az osztálytárak Razor összetevőinek támogatásához az osztálytárnak a Microsoft.NET.Sdk kell használnia.Razor SDK.

Kiszolgálóoldali és ügyféloldali alkalmazások támogatása

Ha egyetlen erőforrástárból szeretné támogatni Razor összetevő-felhasználást kiszolgálóoldali és ügyféloldali alkalmazásokban, használja az alábbi utasításokat a szerkesztőhöz.

Visual Studio
Visual Studio Code/ .NET CLI

Használja az Razor Osztálytár projektsablont.

Note

Ne jelölje be a támogatási oldalak és nézetek jelölőnégyzetet. Ha bejelöli a jelölőnégyzetet, egy olyan osztálytárat eredményez, amely csak a kiszolgálóoldali alkalmazásokat támogatja.

Futtassa a következő parancsot az integrált terminálban (VS Code) vagy egy parancssorban (.NET CLI):

dotnet new razorclasslib

Note

Ne adja hozzá a -s|--support-pages-and-views lehetőséget a dotnet new parancshoz. A beállítás alkalmazása olyan osztálytárat eredményez, amely csak a kiszolgálóoldali alkalmazásokat támogatja.

A projektsablonból létrehozott kódtár:

Az aktuális .NET-keretrendszert célozza meg a telepített SDK alapján.
Lehetővé teszi a böngésző kompatibilitás-ellenőrzését a platformfüggőségek esetében, ha browser támogatott platformként szerepel az SupportedPlatform MSBuild elemben.
Hozzáad egy NuGet-csomaghivatkozást Microsoft.AspNetCore.Components.Web.

RazorClassLibrary-CSharp.csproj (referenciaforrás)

Note

A .NET referenciaforrásra mutató dokumentációs hivatkozások általában betöltik az adattár alapértelmezett ágát, amely a .NET következő kiadásának aktuális fejlesztését jelöli. Egy adott kiadás címkéjének kiválasztásához használja az Ágak vagy címkék váltása legördülő listát. További információ: A ASP.NET Core-forráskód (dotnet/AspNetCore.Docs #26205) verziócímkéjének kiválasztása.

Több keretrendszerverzió támogatása

Ha a könyvtárnak támogatnia kell a jelenlegi kiadásban a Blazor-hoz hozzáadott funkciókat, miközben egy vagy több korábbi kiadást is támogatnia kell, célozza meg a könyvtárat több célkerethez egyidejűleg. Adja meg a Target Framework Monikers (TFMs) pontosvesszővel tagolt listáját az TargetFrameworks MSBuild tulajdonságban:

<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>

Az előző példában a {TARGET FRAMEWORKS} helyőrző a pontosvesszővel tagolt TFM-listát jelöli. Például netcoreapp3.1;net5.0.

Csak a kiszolgálóoldali használat támogatása

Az osztálykódtárak ritkán épülnek fel, hogy csak a kiszolgálóoldali alkalmazásokat támogassák. Ha az osztálykönyvtár csak kiszolgálóoldali funkciókat igényel, ha például CircuitHandler vagy Microsoft.AspNetCore.Components.Server.ProtectedBrowserStoragehozzáférést igényel, vagy ASP.NET Core-specifikus szolgáltatásokat, például köztes szoftvert, MVC-vezérlőket vagy Razor oldalakat használ, használja az alábbi módszerek egyikét :

Adja meg, hogy a könyvtár támogatja-e a lapokat és a nézeteket, amikor a könyvtár a Támogatja a lapokat és a nézeteket jelölőnégyzettel (Visual Studio) vagy a -s|--support-pages-and-views paranccsal és a dotnet new beállítással jön létre:
```
dotnet new razorclasslib -s
```
A kódtár projektfájljában csak a ASP.NET Core-ra mutató keretrendszerhivatkozást adjon meg minden más szükséges MSBuild tulajdonságon kívül:
```
<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
```

Az Razor összetevőket tartalmazó könyvtárakról további információért lásd: Az ASP.NET Core Razor összetevők felhasználása Razor osztály könyvtárból (RCL).

Az MVC bővíthetőségének belefoglalása

Ez a szakasz a következő könyvtárakra vonatkozó ajánlásokat tartalmazza:

Razor nézetek vagy Razor Lapok
Segítők címkézése
Összetevők megtekintése

Ez a szakasz nem foglalkozik az MVC több verziójának támogatásához használható több célzással. A több ASP.NET Core-verzió támogatásával kapcsolatos útmutatásért lásd: Több ASP.NET Core-verzió támogatása.

Razor nézetek vagy Razor oldalak

A Razor nézeteket vagy Razor Oldalak tartalmazó projekteknek a Microsoft.NET.Sdk kell használniuk.Razor SDK.

Ha a projekt a .NET Core 3.x-et célozza meg, a következőt igényli:

Egy AddRazorSupportForMvc MSBuild tulajdonság van beállítva true-re.
A megosztott keretrendszer <FrameworkReference> eleme.

A Razor osztálykódtár projektsablon megfelel a .NET Core-t célzó projektekre vonatkozó fenti követelményeknek. A szerkesztő használatához kövesse az alábbi utasításokat.

Visual Studio
Visual Studio Code/ .NET CLI

Használja az Razor Osztálytár projektsablont. Be kell jelölni a sablon támogatási lapjait és nézeteit jelölőnégyzetet.

Futtassa a következő parancsot az integrált terminálban (VS Code) vagy egy parancssorban (.NET CLI):

dotnet new razorclasslib -s

Például:

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

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

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

</Project>

Ha a projekt a .NET Standardot célozza meg, Microsoft.AspNetCore.Mvc csomaghivatkozásra van szükség. A Microsoft.AspNetCore.Mvc csomag a Core 3.0 ASP.NET megosztott keretrendszerébe került, ezért a továbbiakban nem lesz közzétéve. Például:

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

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

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

</Project>

Címkesegítők

A címkesegédeket tartalmazó projekteknek a Microsoft.NET.Sdk SDK-t kell használniuk. Ha a .NET Core 3.x-et célozza, adjon hozzá egy <FrameworkReference> elemet a megosztott keretrendszerhez. Például:

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

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

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

</Project>

Ha a .NET Standardot célozza (az ASP.NET Core 3.x-nél korábbi verziók támogatása érdekében), adjon hozzá egy csomaghivatkozást a Microsoft.AspNetCore.Mvc .Razor. A Microsoft.AspNetCore.Mvc.Razor csomag átkerült a megosztott keretrendszerbe, ezért a továbbiakban nem kerül közzétételre. Például:

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

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

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

</Project>

Összetevők megtekintése

A View-összetevőket tartalmazó projekteknek a Microsoft.NET.Sdk SDK-t kell használniuk. Ha a .NET Core 3.x-et célozza, adjon hozzá egy <FrameworkReference> elemet a megosztott keretrendszerhez. Például:

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

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

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

</Project>

Ha a .NET Standardot célozza (a Core 3.x ASP.NET-nél korábbi verziók támogatása érdekében), adjon hozzá egy csomaghivatkozást Microsoft.AspNetCore.Mvc.ViewFeatures. A Microsoft.AspNetCore.Mvc.ViewFeatures csomag átkerült a megosztott keretrendszerbe, ezért a továbbiakban nem kerül közzétételre. Például:

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

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

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

</Project>

Több ASP.NET Core-verzió támogatása

Több célzásra van szükség egy olyan kódtár létrehozásához, amely támogatja a ASP.NET Core több változatát. Fontolja meg azt a forgatókönyvet, amelyben a Címkesegítő-kódtárnak támogatnia kell a következő ASP.NET Core-változatokat:

ASP.NET Core 2.1 a .NET-keretrendszer 4.6.1-et célozza
ASP.NET Core 2.x a .NET Core 2.x-et célozza
ASP.NET Core 3.x megcélozva .NET Core 3.x

A következő projektfájl a TargetFrameworks tulajdonságon keresztül támogatja ezeket a változatokat:

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

Az előző projektfájllal:

A Markdig csomag minden fogyasztóhoz hozzá lett adva.
A(z) Microsoft.AspNetCore.Mvc.Razor hivatkozás hozzáadva a .NET Framework 4.6.1 vagy újabb verzióját, illetve a .NET Core 2.x-et megcélzó felhasználók számára. A csomag 2.1.0-s verziója a visszafelé kompatibilitás miatt ASP.NET Core 2.2-vel működik.
A megosztott keretrendszerre a .NET Core 3.x-et megcélzó felhasználók hivatkoznak. A Microsoft.AspNetCore.Mvc.Razor csomag a megosztott keretrendszer részét képezi.

Másik lehetőségként a .NET Standard 2.0 a .NET Core 2.1 és a .NET Framework 4.6.1 célzása helyett is megcélzható:

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

Az előző projektfájlban a következő kikötések léteznek:

Mivel a kódtár csak címkesegítőket tartalmaz, egyszerűbb azokat a platformokat megcélzni, amelyeken ASP.NET Core fut: .NET Core és .NET Framework. A címkesegédeket nem használhatják más .NET Standard 2.0-kompatibilis cél-keretrendszerek, például a Unity és az UWP.
A .NET-keretrendszerből származó .NET Standard 2.0 használata során a .NET-keretrendszer 4.7.2-ben elhárítottunk néhány problémát. A .NET-keretrendszer 4.6.1-4.7.1-et használó felhasználói élményt a .NET-keretrendszer 4.6.1-et célozva javíthatja.

Ha a kódtárnak platformspecifikus API-kat kell meghívnia, a .NET Standard helyett konkrét .NET-implementációkat célozzon meg. További információ: Többcélú célzás.

Olyan API használata, amely nem változott

Képzeljen el egy forgatókönyvet, amelyben egy köztes szoftvertárat frissít a .NET Core 2.2-ről 3.1-re. A kódtárban használt ASP.NET Core köztes szoftver API-k nem változtak ASP.NET Core 2.2 és 3.1 között. A köztes szoftvertár .NET Core 3.1-ben való támogatásának folytatásához hajtsa végre a következő lépéseket:

Kövesse a standard könyvtár útmutatóját.
Adjon hozzá csomaghivatkozást az egyes API-k NuGet-csomagjához, ha a megfelelő szerelvény nem létezik a megosztott keretrendszerben.

Módosított API használata

Képzeljen el egy forgatókönyvet, amelyben egy .NET Core 2.2-ről .NET Core 3.1-re frissít egy könyvtárat. Az ASP.NET Core 3.1 verziójában a kódtárban használt ASP.NET Core API egy kompatibilitástörő változáson esik át. Fontolja meg, hogy a kódtár átírható-e úgy, hogy ne használja a hibás API-t az összes verzióban.

Ha át tudja írni a kódtárat, tegye ezt meg, és folytassa egy korábbi cél keretrendszer (például .NET Standard 2.0 vagy .NET Framework 4.6.1) megcélzását csomaghivatkozásokkal.

Ha nem tudja újraírni a kódtárat, hajtsa végre a következő lépéseket:

Adjon hozzá egy célértéket a .NET Core 3.1-hez.
Adjon hozzá egy <FrameworkReference> elemet a megosztott keretrendszerhez.
A kód feltételes fordításához használja a #if előfeldolgozási a megfelelő célkeretszimbólummal.

A HTTP-kéréseken és válaszstreameken történő szinkron olvasások és írások például alapértelmezés szerint le vannak tiltva ASP.NET Core 3.1-ről. ASP.NET Core 2.2 alapértelmezés szerint támogatja a szinkron működést. Fontolja meg egy köztes szoftvertár használatát, amelyben engedélyezni kell a szinkron olvasást és írást, ahol az I/O történik. A kódtárnak mellékelnie kell a kódot, hogy lehetővé tegye a szinkron funkciókat a megfelelő előfeldolgozási irányelvben. Például:

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

A 3.1-ben bevezetett API használata

Tegyük fel, hogy egy ASP.NET Core 3.1-ben bevezetett ASP.NET Core API-t szeretne használni. Vegye figyelembe a következő kérdéseket:

A kódtárnak funkcionálisan szüksége van az új API-ra?
A kódtár másképpen implementálhatja ezt a funkciót?

Ha a kódtárnak funkcionálisan szüksége van az API-ra, és nem lehet alacsonyabb szinten implementálni:

Csak a .NET Core 3.x verziót célozza meg.
Adjon hozzá egy <FrameworkReference> elemet a megosztott keretrendszerhez.

Ha a kódtár más módon tudja implementálni a funkciót:

Adja hozzá a .NET Core 3.x-et cél-keretrendszerként.
Adjon hozzá egy <FrameworkReference> elemet a megosztott keretrendszerhez.
A kód feltételes fordításához használja a #if előfeldolgozási a megfelelő célkeretszimbólummal.

Az alábbi Címkesegítő például a ASP.NET Core 3.1-ben bevezetett IWebHostEnvironment felületet használja. A .NET Core 3.1-et megcélzó felhasználók végrehajtják a NETCOREAPP3_1 célkeretrendszer szimbólum által meghatározott kódútvonalat. A Címkesegéd konstruktorparaméter-típusa IHostingEnvironment-ra változik a .NET Core 2.1-es és a .NET Framework 4.6.1-es felhasználók esetében. Erre a módosításra azért volt szükség, mert ASP.NET Core 3.1 elavultként jelölte meg IHostingEnvironment, és ajánlott IWebHostEnvironment csereként.

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

A következő többcélú projektfájl támogatja ezt a Címkesegítő forgatókönyvet:

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

A megosztott keretrendszerből eltávolított API használata

A megosztott keretrendszerből eltávolított ASP.NET Core-szerelvény használatához adja hozzá a megfelelő csomaghivatkozást. A ASP.NET Core 3.1-ben a megosztott keretrendszerből eltávolított csomagok listájáért lásd: Elavult csomaghivatkozások eltávolítása.

Például a webes API-ügyfél hozzáadásához:

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

További erőforrások

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2025-01-16

Megosztás a következőn keresztül:

ASP.NET Core API-k használata egy osztálytárban

Annak meghatározása, hogy mely ASP.NET Core-verziókat kell támogatni

A ASP.NET Core megosztott keretrendszerének használata

Blazor bővíthetőségének belefoglalása

Kiszolgálóoldali és ügyféloldali alkalmazások támogatása

Több keretrendszerverzió támogatása

Csak a kiszolgálóoldali használat támogatása

Az MVC bővíthetőségének belefoglalása

Razor nézetek vagy Razor oldalak

Címkesegítők

Összetevők megtekintése

Több ASP.NET Core-verzió támogatása

Olyan API használata, amely nem változott

Módosított API használata

A 3.1-ben bevezetett API használata

A megosztott keretrendszerből eltávolított API használata

További erőforrások

Visszajelzés

További források