Condividi tramite

Adattatori System.Web

Il caso d'uso principale degli adattatori nel repository dotnet/systemweb-adapters consiste nell'aiutare gli sviluppatori che hanno fatto affidamento sui System.Web tipi nelle loro librerie di classi mentre vogliono passare ad ASP.NET Core.

Una funzionalità importante degli adattatori è che gli adattatori consentono l'uso della libreria sia da ASP.NET Framework che da ASP.NET progetti Core. L'aggiornamento di più app ASP.NET Framework a ASP.NET Core comporta spesso stati intermedi in cui non tutte le app sono state completamente aggiornate. Usando gli System.Web adattatori, la libreria può essere usata sia dai chiamanti ASP.NET Core che dai chiamanti di ASP.NET Framework che non sono stati aggiornati.

Di seguito viene illustrato un esempio che usa gli adattatori che passano da .NET Framework a ASP.NET Core.

Pacchetti

  • Microsoft.AspNetCore.SystemWebAdapters: questo pacchetto viene usato nelle librerie di supporto e fornisce le API System.Web da cui potrebbe essere stata acquisita una dipendenza, ad esempio HttpContext e altri. Questo pacchetto è destinato a .NET Standard 2.0, .NET Framework 4.5+e .NET 5+.
  • Microsoft.AspNetCore.SystemWebAdapters.FrameworkServices: questo pacchetto è destinato solo a .NET Framework ed è progettato per fornire servizi alle applicazioni ASP.NET Framework che potrebbero dover fornire migrazioni incrementali. Questo non è in genere previsto che venga fatto riferimento dalle librerie, ma piuttosto dalle applicazioni stesse.
  • Microsoft.AspNetCore.SystemWebAdapters.CoreServices: questo pacchetto è destinato solo a .NET 6+ ed è destinato a fornire servizi alle applicazioni ASP.NET Core per configurare il comportamento delle API System.Web, nonché acconsentire esplicitamente a eventuali comportamenti per la migrazione incrementale. Questo non è in genere previsto che venga fatto riferimento dalle librerie, ma piuttosto dalle applicazioni stesse.
  • Microsoft.AspNetCore.SystemWebAdapters.Abstractions: questo pacchetto è un pacchetto di supporto che fornisce astrazioni per i servizi usati sia dall'applicazione ASP.NET Core che da ASP.NET Framework, ad esempio la serializzazione dello stato della sessione.

Conversione in System.Web.HttpContext

Per eseguire la conversione tra le due rappresentazioni di HttpContext, è possibile eseguire le operazioni seguenti:

Da HttpContext a HttpContext:

  • Cast implicito
  • HttpContext.AsSystemWeb()

Per HttpContext a HttpContext

  • Cast implicito
  • HttpContext.AsAspNetCore()

Entrambi questi metodi useranno una rappresentazione memorizzata HttpContext nella cache per la durata di una richiesta. In questo modo è possibile effettuare riscritture mirate a HttpContext secondo delle esigenze.

Esempio

Framework ASP.NET

Si consideri un controller che esegue operazioni come:

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

che poi ha la logica in un assembly separato, passando HttpContext finché, infine, qualche metodo interno non esegue delle operazioni logiche su di esso, ad esempio:

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

ASP.NET Core

Per eseguire la logica precedente in ASP.NET Core, uno sviluppatore dovrà aggiungere il Microsoft.AspNetCore.SystemWebAdapters pacchetto, che consentirà ai progetti di funzionare su entrambe le piattaforme.

Le librerie devono essere aggiornate per comprendere gli adattatori, ma sarà semplice come aggiungere il pacchetto e ricompilare. Se si tratta delle uniche dipendenze di un sistema in System.Web.dll, le librerie saranno in grado di usare .NET Standard 2.0 per facilitare un processo di compilazione più semplice durante la migrazione.

Il controller in ASP.NET Core avrà ora un aspetto simile al seguente:

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

Si noti che, poiché è presente una proprietà HttpContext, possono trasmetterlo, e in genere sembra uguale. Usando le conversioni implicite, è possibile convertire l'oggetto HttpContext nell'adattatore che può quindi essere passato attraverso i livelli che utilizzano il codice nello stesso modo.

Test unitario

Quando si esegue lo unit test del codice che usa gli adattatori System.Web, è necessario tenere presenti alcune considerazioni speciali.

Nella maggior parte dei casi, non è necessario configurare componenti aggiuntivi per l'esecuzione dei test. Tuttavia, se il componente sottoposto a test usa HttpRuntime, potrebbe essere necessario avviare il SystemWebAdapters servizio, come illustrato nell'esempio seguente:

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

I test devono essere eseguiti in sequenza, non in parallelo. L'esempio precedente illustra come ottenere questo risultato impostando l'opzione di DisableParallelization XUnit su true. Questa impostazione disabilita l'esecuzione parallela per una raccolta di test specifica, assicurandosi che i test all'interno della raccolta vengano eseguiti uno dopo l'altro, senza concorrenza.

  • Last updated on