System.Web-adaptrar

2025-07-21

Det huvudsakliga användningsfallet för adaptrarna i lagringsplatsen dotnet/systemweb-adapters är att hjälpa utvecklare som har förlitat sig på System.Web-typer i sina klassbibliotek när de vill flytta till ASP.NET Core.

En viktig funktion i adaptrarna är att de tillåter att biblioteket används från både ASP.NET Framework- och ASP.NET Core-projekt. Att uppdatera flera ASP.NET Framework-appar till ASP.NET Core omfattar ofta mellanliggande tillstånd där inte alla appar har uppdaterats helt. Med hjälp av adaptrarna System.Web kan biblioteket användas både från ASP.NET Core-anropare och ASP.NET Framework-anropare som inte har uppgraderats.

Nu ska vi ta en titt på ett exempel med hjälp av adaptrar som flyttas från .NET Framework till ASP.NET Core.

Paket

Microsoft.AspNetCore.SystemWebAdapters: Det här paketet används i stödbibliotek och tillhandahåller de System.Web-API:er som HttpContext du kan ha varit beroende av, till exempel och andra. Det här paketet riktar sig till .NET Standard 2.0, .NET Framework 4.5+och .NET 5+.
Microsoft.AspNetCore.SystemWebAdapters.FrameworkServices: Det här paketet riktar sig endast mot .NET Framework och är avsett att tillhandahålla tjänster till ASP.NET Framework-program som kan behöva tillhandahålla inkrementella migreringar. Detta förväntas vanligtvis inte refereras från bibliotek, utan snarare från själva programmen.
Microsoft.AspNetCore.SystemWebAdapters.CoreServices: Det här paketet riktar sig endast mot .NET 6+ och är avsett att tillhandahålla tjänster till ASP.NET Core-program för att konfigurera beteendet för System.Web API:er samt välja eventuella beteenden för inkrementell migrering. Detta förväntas vanligtvis inte refereras från bibliotek, utan snarare från själva programmen.
Microsoft.AspNetCore.SystemWebAdapters.Abstractions: Det här paketet är ett stödpaket som tillhandahåller abstraktioner för tjänster som används av både ASP.NET Core- och ASP.NET Framework-programmet, till exempel serialisering av sessionstillstånd.

Konvertera till System.Web.HttpContext

Om du vill konvertera mellan de två representationerna av HttpContext kan du göra följande:

För HttpContext att HttpContext:

Implicit gjutning
HttpContext.AsSystemWeb()

För HttpContext att HttpContext

Implicit gjutning
HttpContext.AsAspNetCore()

Båda dessa metoder använder en cachelagrad HttpContext representation under en begärans varaktighet. På så sätt kan riktade omskrivningar göras vid behov av HttpContext.

Exempel

ASP.NET Framework

Överväg en kontrollant som gör något som:

public class SomeController : Controller
{
  public ActionResult Index()
  {
    SomeOtherClass.SomeMethod(HttpContext.Current);
  }
}

som sedan har logik i en separat modul som skickar runt den HttpContext tills slutligen, någon inre metod utför logiska operationer på den, till exempel:

public class Class2
{
  public bool PerformSomeCheck(HttpContext context)
  {
    return context.Request.Headers["SomeHeader"] == "ExpectedValue";
  }
}

ASP.NET Core

För att kunna köra logiken ovan i ASP.NET Core måste en utvecklare lägga Microsoft.AspNetCore.SystemWebAdapters till paketet, vilket gör att projekten kan fungera på båda plattformarna.

Biblioteken behöver uppdateras för att förstå adaptrarna, men det är så enkelt som att lägga till paketet och kompilera om. Om dessa är de enda beroenden som ett system har på kan biblioteken rikta in sig på System.Web.dll.NET Standard 2.0 för att underlätta en enklare byggprocess vid migrering.

Styrenheten i ASP.NET Core ser nu ut så här:

public class SomeController : Controller
{
  [Route("/")]
  public IActionResult Index()
  {
    SomeOtherClass.SomeMethod(HttpContext);
  }
}

Observera att eftersom det finns en HttpContext egenskap kan de skicka den igenom, men den ser vanligtvis likadan ut. Med implicita konverteringar HttpContext kan konverteras till adaptern som sedan kan skickas runt genom nivåerna som använder koden på samma sätt.

Enhetstestning

När enhetstester kod som använder System.Web-adaptrar finns det särskilda överväganden att tänka på.

I de flesta fall behöver du inte konfigurera ytterligare komponenter för att köra tester. Men om komponenten som testas använder HttpRuntimekan det vara nödvändigt att starta SystemWebAdapters tjänsten, som du ser i följande exempel:

namespace TestProject1;

/// <summary>
/// This demonstrates an xUnit feature that ensures all tests
/// in classes marked with this collection are run sequentially.
/// </summary>
[CollectionDefinition(nameof(SystemWebAdaptersHostedTests),
    DisableParallelization = true)]
public class SystemWebAdaptersHostedTests
{
}
[Collection(nameof(SystemWebAdaptersHostedTests))]
public class RuntimeTests
{
    /// <summary>
    /// This method starts up a host in the background that
    /// makes it possible to initialize <see cref="HttpRuntime"/>
    /// and <see cref="HostingEnvironment"/> with values needed 
    /// for testing with the <paramref name="configure"/> option.
    /// </summary>
    /// <param name="configure">
    /// Configuration for the hosting and runtime options.
    /// </param>
    public static async Task<IDisposable> EnableRuntimeAsync(
        Action<SystemWebAdaptersOptions>? configure = null,
        CancellationToken token = default)
        => await new HostBuilder()
           .ConfigureWebHost(webBuilder =>
           {
               webBuilder
                   .UseTestServer()
                   .ConfigureServices(services =>
                   {
                       services.AddSystemWebAdapters();
                       if (configure is not null)
                       {
                           services.AddOptions
                               <SystemWebAdaptersOptions>()
                               .Configure(configure);
                       }
                   })
                   .Configure(app =>
                   {
                       // No need to configure pipeline for tests
                   });
           })
           .StartAsync(token);
    [Fact]
    public async Task RuntimeEnabled()
    {
        using (await EnableRuntimeAsync(options =>
            options.AppDomainAppPath = "path"))
        {
            Assert.True(HostingEnvironment.IsHosted);
            Assert.Equal("path", HttpRuntime.AppDomainAppPath);
        }
        Assert.False(HostingEnvironment.IsHosted);
    }
}

Testerna måste köras i följd, inte parallellt. Föregående exempel illustrerar hur du uppnår detta genom att ange XUnits DisableParallelization alternativ till true. Den här inställningen inaktiverar parallell körning för en specifik testsamling, vilket säkerställer att testerna i samlingen körs en efter en, utan samtidighet.

Feedback

Var den här sidan till hjälp?