Delen via

Startassemblies hosten in ASP.NET Core

Note

Dit is niet de nieuwste versie van dit artikel. Zie de .NET 9-versie van dit artikel voor de huidige release.

Warning

Deze versie van ASP.NET Core wordt niet meer ondersteund. Zie het .NET- en .NET Core-ondersteuningsbeleid voor meer informatie. Zie de .NET 9-versie van dit artikel voor de huidige release.

Important

Deze informatie heeft betrekking op een pre-releaseproduct dat aanzienlijk kan worden gewijzigd voordat het commercieel wordt uitgebracht. Microsoft geeft geen garanties, uitdrukkelijk of impliciet, met betrekking tot de informatie die hier wordt verstrekt.

Zie de .NET 9-versie van dit artikel voor de huidige release.

Door Pavel Krymets

Een IHostingStartup (hosting startup) implementatie integreert verbeteringen in een app bij het starten van een externe assembly. Een externe bibliotheek kan bijvoorbeeld een opstart-implementatie voor hosting gebruiken om extra configuratieproviders of -services aan een app te bieden.

Voorbeeldcode bekijken of downloaden (hoe download je)

Kenmerk HostingStartup

Een kenmerk HostingStartup geeft de aanwezigheid aan van een hosting-opstartassembly die tijdens runtime moet worden geactiveerd.

De invoerassembly of de assembly met de Startup klasse wordt automatisch gescand op het HostingStartup kenmerk. De lijst met assembly's voor het zoeken naar HostingStartup kenmerken wordt tijdens runtime geladen vanuit de configuratie in de WebHostDefaults.HostingStartupAssembliesKey. De lijst met assembly's die moeten worden uitgesloten van detectie wordt geladen van de WebHostDefaults.HostingStartupExcludeAssembliesKey.

In het volgende voorbeeld is StartupEnhancementde naamruimte van de hosting-opstartassembly. De klasse met de opstartcode van de hosting is StartupEnhancementHostingStartup:

[assembly: HostingStartup(typeof(StartupEnhancement.StartupEnhancementHostingStartup))]

Het HostingStartup kenmerk bevindt zich meestal in het implementatieklassebestand van IHostingStartup de hosting-assembly.

Geladen opstartassembly's voor hosting detecteren

Als u geladen hostingstartassemblages wilt detecteren, schakelt u logging in en controleert u de logboeken van de app. Fouten die optreden bij het laden van assembly's worden vastgelegd. Geladen hosting startup-assembly's worden geregistreerd op Debug-niveau en alle fouten worden vastgelegd.

Automatisch laden van opstartassembly's voor hosting uitschakelen

Als u het automatisch laden van opstartassemblages wilt uitschakelen, gebruikt u een van de volgende methodes:

  • Als u wilt voorkomen dat alle opstartassembly's worden geladen, stelt u een van de volgende opties in op true of 1:

    • Voorkom opstarten van hosting: hostconfiguratie-instelling.

      public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseSetting(
                    WebHostDefaults.PreventHostingStartupKey, "true")
                .UseStartup<Startup>();
        });

    • ASPNETCORE_PREVENTHOSTINGSTARTUP omgevingsvariabele.

  • Als u wilt voorkomen dat specifieke opstartassembly's worden geladen, stelt u een van de volgende in als een door puntkomma's gescheiden tekenreeks van opstartassembly's voor hosting die moeten worden uitgesloten bij het opstarten:

    • Hostconfiguratie-instelling voor het uitsluiten van assemblies tijdens het opstartproces:

      public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseSetting(
                    WebHostDefaults.HostingStartupExcludeAssembliesKey, 
                    "{ASSEMBLY1;ASSEMBLY2; ...}")
                .UseStartup<Startup>();
        });

      De {ASSEMBLY1;ASSEMBLY2; ...} placeholder vertegenwoordigt de lijst van assemblies gescheiden door puntkomma's.

    • ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES omgevingsvariabele.

Als zowel de hostconfiguratie-instelling als de omgevingsvariabele zijn ingesteld, bepaalt de hostinstelling het gedrag.

Door het hosten van opstartassembly's uit te schakelen met behulp van de hostinstelling of omgevingsvariabele, wordt de assembly globaal uitgeschakeld en kunnen verschillende kenmerken van een app worden uitgeschakeld.

Project

Maak een hostingstart met een van de volgende projecttypen:

Klassebibliotheek

Er kan een opstartverbetering voor hosting worden geboden in een klassebibliotheek. De bibliotheek bevat een HostingStartup kenmerk.

De voorbeeldcode bevat een Razor Pages-app, HostingStartupApp en een klassebibliotheek, HostingStartupLibrary. De klassebibliotheek:

  • Bevat een opstartklasse voor hosting, ServiceKeyInjectiondie implementeert IHostingStartup. ServiceKeyInjection voegt een paar servicetekenreeksen toe aan de configuratie van de app met behulp van de in-memory configuratieprovider (AddInMemoryCollection).
  • Bevat een HostingStartup kenmerk dat de naamruimte en klasse van de hosting start-up identificeert.

De methode van ServiceKeyInjection de Configure klasse maakt gebruik van een IWebHostBuilder methode om verbeteringen aan een app toe te voegen.

HostingStartupLibrary/ServiceKeyInjection.cs:

[assembly: HostingStartup(typeof(HostingStartupLibrary.ServiceKeyInjection))]

namespace HostingStartupLibrary
{
    public class ServiceKeyInjection : IHostingStartup
    {
        public void Configure(IWebHostBuilder builder)
        {
            builder.ConfigureAppConfiguration(config =>
            {
                var dict = new Dictionary<string, string>
                {
                    {"DevAccount_FromLibrary", "DEV_1111111-1111"},
                    {"ProdAccount_FromLibrary", "PROD_2222222-2222"}
                };

                config.AddInMemoryCollection(dict);
            });
        }
    }
}

De indexpagina van de app leest en geeft de configuratiewaarden weer voor de twee keys die zijn ingesteld door de hostingstartupassembly van de klassebibliotheek.

HostingStartupApp/Pages/Index.cshtml.cs:

public class IndexModel : PageModel
{
    public IndexModel(IConfiguration config)
    {
        ServiceKey_Development_Library = config["DevAccount_FromLibrary"];
        ServiceKey_Production_Library = config["ProdAccount_FromLibrary"];
        ServiceKey_Development_Package = config["DevAccount_FromPackage"];
        ServiceKey_Production_Package = config["ProdAccount_FromPackage"];
    }

    public string ServiceKey_Development_Library { get; private set; }
    public string ServiceKey_Production_Library { get; private set; }
    public string ServiceKey_Development_Package { get; private set; }
    public string ServiceKey_Production_Package { get; private set; }

    public void OnGet()
    {
    }
}

De voorbeeldcode bevat ook een NuGet-pakketproject dat een afzonderlijke hostingstart, HostingStartupPackage, biedt. Het pakket heeft dezelfde kenmerken van de eerder beschreven klassebibliotheek. Het pakket:

  • Bevat een opstartklasse voor hosting, ServiceKeyInjectiondie implementeert IHostingStartup. ServiceKeyInjection voegt een paar servicetekenreeksen toe aan de configuratie van de app.
  • Bevat een HostingStartup kenmerk.

HostingStartupPackage/ServiceKeyInjection.cs:

[assembly: HostingStartup(typeof(HostingStartupPackage.ServiceKeyInjection))]

namespace HostingStartupPackage
{
    public class ServiceKeyInjection : IHostingStartup
    {
        public void Configure(IWebHostBuilder builder)
        {
            builder.ConfigureAppConfiguration(config =>
            {
                var dict = new Dictionary<string, string>
                {
                    {"DevAccount_FromPackage", "DEV_3333333-3333"},
                    {"ProdAccount_FromPackage", "PROD_4444444-4444"}
                };

                config.AddInMemoryCollection(dict);
            });
        }
    }
}

De indexpagina van de app leest en geeft de configuratiewaarden weer voor de twee kenmerken die zijn ingesteld door de opstart-assembly van het pakket.

HostingStartupApp/Pages/Index.cshtml.cs:

public class IndexModel : PageModel
{
    public IndexModel(IConfiguration config)
    {
        ServiceKey_Development_Library = config["DevAccount_FromLibrary"];
        ServiceKey_Production_Library = config["ProdAccount_FromLibrary"];
        ServiceKey_Development_Package = config["DevAccount_FromPackage"];
        ServiceKey_Production_Package = config["ProdAccount_FromPackage"];
    }

    public string ServiceKey_Development_Library { get; private set; }
    public string ServiceKey_Production_Library { get; private set; }
    public string ServiceKey_Development_Package { get; private set; }
    public string ServiceKey_Production_Package { get; private set; }

    public void OnGet()
    {
    }
}

Console-app zonder toegangspunt

Deze benadering is alleen beschikbaar voor .NET-apps, niet voor .NET Framework.

Een dynamische opstartverbetering voor hosting waarvoor geen referentie voor compileertijd voor activering is vereist, kan worden opgegeven in een console-app zonder een ingangspunt dat een HostingStartup kenmerk bevat. Het publiceren van de console-app produceert een host-opstartassembly die kan worden gebruikt vanuit de runtime store.

In dit proces wordt een console-app zonder invoerpunt gebruikt, omdat:

  • Er is een afhankelijkheidsbestand vereist om de hosting-startup te gebruiken in de hosting-startup-assembly. Een afhankelijkheidsbestand is een uitvoerbare app-asset die wordt geproduceerd door het publiceren van een app, niet een bibliotheek.
  • Een bibliotheek kan niet rechtstreeks worden toegevoegd aan het runtime-pakketarchief. Hiervoor is een uitvoerbaar project vereist dat gericht is op de gedeelde runtime.

Bij het opzetten van een dynamische hoststartup:

  • Er wordt een hosting-opstartassembly gemaakt vanuit de console-app zonder een ingangspunt dat:
    • Bevat een klasse die de IHostingStartup implementatie bevat.
    • Bevat een HostingStartup-kenmerk om de IHostingStartup implementatieklasse te identificeren.
  • De console-applicatie wordt gepubliceerd om de afhankelijkheden van de hostingstartup te verkrijgen. Als gevolg van het publiceren van de console-app is dat ongebruikte afhankelijkheden worden afgekapt uit het afhankelijkhedenbestand.
  • Het afhankelijkhedenbestand wordt gewijzigd om de runtimelocatie van de host-opstartassembly in te stellen.
  • De hosting-opstartassembly en het bijbehorende afhankelijkhedenbestand worden in het runtime-pakketarchief geplaatst. Als u de opstartassembly en het bijbehorende afhankelijkhedenbestand wilt detecteren, worden ze vermeld in een paar omgevingsvariabelen.

De console-app verwijst naar het pakket Microsoft.AspNetCore.Hosting.Abstractions :

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

  <PropertyGroup>
    <TargetFramework>netcoreapp3.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Hosting.Abstractions" 
                      Version="3.0.0" />
  </ItemGroup>

</Project>

Een HostingStartup-kenmerk identificeert een klasse als een implementatie van IHostingStartup voor het laden en uitvoeren bij het bouwen van de IWebHost. In het volgende voorbeeld is StartupEnhancementde naamruimte en de klasse:StartupEnhancementHostingStartup

[assembly: HostingStartup(typeof(StartupEnhancement.StartupEnhancementHostingStartup))]

Een klasse implementeert IHostingStartup. De methode van Configure de klasse maakt gebruik van een IWebHostBuilder methode om verbeteringen aan een app toe te voegen. IHostingStartup.Configure in de hosting-startassembly wordt aangeroepen door de runtime vóór Startup.Configure in de gebruikerscode, waardoor de gebruikerscode alle configuraties kan overschrijven die door de hosting-startassembly worden geleverd.

namespace StartupEnhancement
{
    public class StartupEnhancementHostingStartup : IHostingStartup
    {
        public void Configure(IWebHostBuilder builder)
        {
            // Use the IWebHostBuilder to add app enhancements.
        }
    }
}

Bij het bouwen van een IHostingStartup project stelt het afhankelijkhedenbestand (.deps.json) de runtime locatie van de assembly in op de bin-map :

"targets": {
  ".NETCoreApp,Version=v3.0": {
    "StartupEnhancement/1.0.0": {
      "dependencies": {
        "Microsoft.AspNetCore.Hosting.Abstractions": "3.0.0"
      },
      "runtime": {
        "StartupEnhancement.dll": {}
      }
    }
  }
}

Er wordt slechts een deel van het bestand weergegeven. De assemblynaam in het voorbeeld is StartupEnhancement.

Configuratie geleverd door het opstarten van de hosting

Er zijn twee methoden voor het afhandelen van configuratie, afhankelijk van of u wilt dat de configuratie van het hosting-opstartprogramma voorrang krijgt of dat de configuratie van de app voorrang krijgt:

  1. Geef configuratie aan de app door ConfigureAppConfiguration te gebruiken om de configuratie te laden nadat de gedelegeerden van ConfigureAppConfiguration de app zijn uitgevoerd. Het hosten van opstartconfiguratie heeft voorrang op de configuratie van de app met behulp van deze benadering.
  2. Geef configuratie voor de app op door gebruik van UseConfiguration om de configuratie te laden voordat de gedelegeerden van de app ConfigureAppConfiguration worden uitgevoerd. De configuratiewaarden van de app hebben voorrang op de waarden die door de hosting-startup worden geleverd via deze methode.
public class ConfigurationInjection : IHostingStartup
{
    public void Configure(IWebHostBuilder builder)
    {
        Dictionary<string, string> dict;

        builder.ConfigureAppConfiguration(config =>
        {
            dict = new Dictionary<string, string>
            {
                {"ConfigurationKey1", 
                    "From IHostingStartup: Higher priority " +
                    "than the app's configuration."},
            };

            config.AddInMemoryCollection(dict);
        });

        dict = new Dictionary<string, string>
        {
            {"ConfigurationKey2", 
                "From IHostingStartup: Lower priority " +
                "than the app's configuration."},
        };

        var builtConfig = new ConfigurationBuilder()
            .AddInMemoryCollection(dict)
            .Build();

        builder.UseConfiguration(builtConfig);
    }
}

De hosting opstartassembly specificeren

Geef de naam van de hosting-startup-assembly op in de ASPNETCORE_HOSTINGSTARTUPASSEMBLIES omgevingsvariabele voor een hosting-startup die wordt geleverd door een klassebibliotheek of consoletoepassing. De omgevingsvariabele is een door puntkomma's gescheiden lijst met assembly's.

Alleen start-upassembly's voor hosting worden gescand op het HostingStartup attribuut. Voor de voorbeeld-app HostingStartupApp wordt de omgevingsvariabele ingesteld op de volgende waarde om de eerder beschreven hosting startups te ontdekken:

HostingStartupLibrary;HostingStartupPackage;StartupDiagnostics

Een host-opstartassembly kan ook worden ingesteld met behulp van de hostconfiguratie-instelling voor host-opstartassemblies.

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseSetting(
                    WebHostDefaults.HostingStartupAssembliesKey, 
                    "{ASSEMBLY1;ASSEMBLY2; ...}")
                .UseStartup<Startup>();
        });

De {ASSEMBLY1;ASSEMBLY2; ...} placeholder vertegenwoordigt de lijst van assemblies gescheiden door puntkomma's.

Wanneer er meerdere hosting-opstartassembly's aanwezig zijn, worden hun Configure methoden uitgevoerd in de volgorde waarin de assembly's worden vermeld.

Activation

Opties voor het hosten van opstartactivering zijn:

  • Runtime-archief: voor activering is geen referentie voor de compilatietijd vereist. De voorbeeld-app plaatst de hosting-startup assembly en afhankelijkheidsbestanden in een map, implementatie, om de implementatie van de hosting-startup in een omgeving met meerdere machines te vergemakkelijken. De implementatiemap bevat ook een PowerShell-script waarmee omgevingsvariabelen in het implementatiesysteem worden gemaakt of gewijzigd om het opstarten van de hosting in te schakelen.
  • Referentie voor compilatietijd vereist voor activering

Runtime-archief

De hosting-opstart-implementatie wordt in het runtimearchief geplaatst. Een compilatietijdverwijzing naar de assembly is niet vereist voor de verbeterde app.

Nadat het hostingproject is gebouwd, wordt er een runtime-archief gegenereerd met behulp van het manifestbestand van het project en de dotnet store-opdracht.

dotnet store --manifest {MANIFEST FILE} --runtime {RUNTIME IDENTIFIER} --output {OUTPUT LOCATION} --skip-optimization

In de voorbeeld-app (RuntimeStore-project ) wordt de volgende opdracht gebruikt:

dotnet store --manifest store.manifest.csproj --runtime win7-x64 --output ./deployment/store --skip-optimization

Voor de runtime om de runtime-opslag te detecteren, wordt de locatie van de runtime-opslag toegevoegd aan de DOTNET_SHARED_STORE omgevingsvariabele.

Het afhankelijkhedenbestand van het hosting-opstartproces wijzigen en plaatsen

Als u de uitbreiding wilt activeren zonder een pakketverwijzing naar de uitbreiding, geeft u aanvullende afhankelijkheden op voor de runtime met additionalDeps. additionalDeps stelt u in staat om:

  • Breid de bibliotheekgrafiek van de app uit door een set extra .deps.json bestanden op te geven om samen te voegen met het eigen .deps.json bestand van de app bij het opstarten.
  • Maak de hosting-opstartassembly detecteerbaar en laadbaar.

De aanbevolen methode voor het genereren van het extra afhankelijkhedenbestand is het volgende:

  1. Voer dotnet publish het manifestbestand van het runtimearchief uit waarnaar in de vorige sectie wordt verwezen.
  2. Verwijder de manifestreferentie uit bibliotheken en de runtime sectie van het resulterende .deps.json bestand.

In het voorbeeldproject wordt de store.manifest/1.0.0 eigenschap verwijderd uit de targets en libraries sectie:

{
  "runtimeTarget": {
    "name": ".NETCoreApp,Version=v3.0",
    "signature": ""
  },
  "compilationOptions": {},
  "targets": {
    ".NETCoreApp,Version=v3.0": {
      "store.manifest/1.0.0": {
        "dependencies": {
          "StartupDiagnostics": "1.0.0"
        },
        "runtime": {
          "store.manifest.dll": {}
        }
      },
      "StartupDiagnostics/1.0.0": {
        "runtime": {
          "lib/netcoreapp3.0/StartupDiagnostics.dll": {
            "assemblyVersion": "1.0.0.0",
            "fileVersion": "1.0.0.0"
          }
        }
      }
    }
  },
  "libraries": {
    "store.manifest/1.0.0": {
      "type": "project",
      "serviceable": false,
      "sha512": ""
    },
    "StartupDiagnostics/1.0.0": {
      "type": "package",
      "serviceable": true,
      "sha512": "sha512-xrhzuNSyM5/f4ZswhooJ9dmIYLP64wMnqUJSyTKVDKDVj5T+qtzypl8JmM/aFJLLpYrf0FYpVWvGujd7/FfMEw==",
      "path": "startupdiagnostics/1.0.0",
      "hashPath": "startupdiagnostics.1.0.0.nupkg.sha512"
    }
  }
}

Plaats het .deps.json bestand op de volgende locatie:

{ADDITIONAL DEPENDENCIES PATH}/shared/{SHARED FRAMEWORK NAME}/{SHARED FRAMEWORK VERSION}/{ENHANCEMENT ASSEMBLY NAME}.deps.json
  • {ADDITIONAL DEPENDENCIES PATH}: Locatie toegevoegd aan de DOTNET_ADDITIONAL_DEPS omgevingsvariabele.
  • {SHARED FRAMEWORK NAME}: Gedeeld framework vereist voor dit extra afhankelijkhedenbestand.
  • {SHARED FRAMEWORK VERSION}: Minimale versie van gedeeld framework.
  • {ENHANCEMENT ASSEMBLY NAME}: de assemblynaam van de verbetering.

In de voorbeeld-app (RuntimeStore-project ) wordt het extra afhankelijkhedenbestand op de volgende locatie geplaatst:

deployment/additionalDeps/shared/Microsoft.AspNetCore.App/3.0.0/StartupDiagnostics.deps.json

Om de runtime in staat te stellen de locatie van het runtimearchief te detecteren, wordt de locatie van het aanvullende afhankelijkhedenbestand toegevoegd aan de DOTNET_ADDITIONAL_DEPS omgevingsvariabele.

Note

De DOTNET_ADDITIONAL_DEPS omgevingsvariabele werkt alleen met frameworkafhankelijke toepassingen. Deze omgevingsvariabele wordt genegeerd voor zelfstandige toepassingen.

In de voorbeeld-app (RuntimeStore-project ) wordt het bouwen van het runtimearchief en het genereren van het extra afhankelijkhedenbestand bereikt met behulp van een PowerShell-script .

Zie Meerdere omgevingen gebruiken voor voorbeelden van het instellen van omgevingsvariabelen voor verschillende besturingssystemen.

Deployment

Om de implementatie van een hostingstart in een omgeving met meerdere machines te vergemakkelijken, maakt de voorbeeld-app een implementatiemap in gepubliceerde uitvoer die het volgende bevat:

  • Het hosten van de opstartruntime store.
  • Het opstartafhankelijkhedenbestand van de hosting.
  • Een PowerShell-script dat de ASPNETCORE_HOSTINGSTARTUPASSEMBLIES, DOTNET_SHARED_STORE, en DOTNET_ADDITIONAL_DEPS creëert of wijzigt ter ondersteuning van de activering van de hostingstartup. Voer het script uit vanaf een PowerShell-opdrachtprompt met beheerdersrechten op het implementatiesysteem.

NuGet-pakket

Een verbetering voor een hosting-startup kan worden geleverd in een NuGet-pakket. Het pakket heeft een HostingStartup kenmerk. De hosting-opstarttypen die door het pakket worden geleverd, worden beschikbaar gesteld aan de app met behulp van een van de volgende methoden:

  • Het projectbestand van de verbeterde app maakt een pakketverwijzing voor het opstarten van de hosting in het projectbestand van de app (een referentie voor compileertijd). Met de referentie voor compilatietijd worden de opstartassembly van de hosting en alle bijbehorende afhankelijkheden opgenomen in het afhankelijkheidsbestand van de app (.deps.json). Deze benadering is van toepassing op een hosting-opstartassemblypakket dat is gepubliceerd op nuget.org.
  • Het afhankelijkhedenbestand van de hosting-startup wordt beschikbaar gesteld aan de geoptimaliseerde app, zoals beschreven in de sectie over de Runtime Store (zonder een compile-tijd-referentie).

Zie de volgende onderwerpen voor meer informatie over NuGet-pakketten en de runtime-opslag:

Map Van Project-bin

Een hosting-opstartverbetering kan worden geleverd door een door een bin geïmplementeerde assembly in de verbeterde app. De hosting-opstarttypen die door de assembly worden geleverd, worden beschikbaar gesteld aan de app met behulp van een van de volgende methoden:

  • Het projectbestand van de verbeterde app maakt een assemblyverwijzing naar het opstarten van de hosting (een referentie voor compileertijd). Met de referentie voor compilatietijd worden de opstartassembly van de hosting en alle bijbehorende afhankelijkheden opgenomen in het afhankelijkheidsbestand van de app (.deps.json). Deze benadering is van toepassing wanneer het implementatiescenario aanroept om een compileertijdverwijzing te maken naar de assembly van het hosting-opstartproces (.dll bestand) en de assembly naar een van de volgende opties te verplaatsen:
    • Het verbruikende project.
    • Een locatie die toegankelijk is voor het verbruikende project.
  • Het afhankelijkhedenbestand van de hosting-startup wordt beschikbaar gesteld aan de geoptimaliseerde app, zoals beschreven in de sectie over de Runtime Store (zonder een compile-tijd-referentie).
  • Wanneer de assembly is gericht op .NET Framework, kan de assembly worden geladen in de standaardbelastingcontext, wat op .NET Framework betekent dat de assembly zich op een van de volgende locaties bevindt:
    • Toepassingsbasispad: de bin-map waar het uitvoerbare bestand van de app (.exe) zich bevindt.
    • Global Assembly Cache (GAC): De GAC slaat assembly's op die verschillende .NET Framework-apps delen. Voor meer informatie, zie Een assembly installeren in de algemene assemblycache in de .NET Framework-documentatie.

Voorbeeldcode

De voorbeeldcode (downloaden) laat scenario's zien voor het hosten van opstart-implementatiescenario's:

  • Twee hosting opstartassembly's (klassebibliotheken) initialiseren elk een paar configuratiesleutel-waardeparen in het geheugen:
    • NuGet-pakket (HostingStartupPackage)
    • Klassebibliotheek (HostingStartupLibrary)
  • Een hostingstartup wordt geactiveerd vanuit een runtime store-gedeponeerde assembly (StartupDiagnostics). De assembly voegt bij het opstarten twee middlewares toe aan de app die diagnostische informatie biedt over:
    • Geregistreerde services
    • Adres (schema, host, padbasis, pad, pad, querytekenreeks)
    • Verbinding (extern IP, externe poort, lokaal IP, lokale poort, clientcertificaat)
    • Headers aanvragen
    • Omgevingsvariabelen

Het voorbeeld uitvoeren:

Activering vanuit een NuGet-pakket

  1. Compileer het pakket HostingStartupPackage met de opdracht dotnet pack .

  2. Voeg de assemblynaam van het pakket van de HostingStartupPackage toe aan de ASPNETCORE_HOSTINGSTARTUPASSEMBLIES omgevingsvariabele.

  3. Compileer en voer de app uit. Er is een pakketverwijzing aanwezig in de verbeterde app (een referentie voor compileertijd). Een <PropertyGroup> in het projectbestand van de app geeft de uitvoer van het pakketproject (../HostingStartupPackage/bin/Debug) als pakketbron. Hierdoor kan de app het pakket gebruiken zonder het pakket te uploaden naar nuget.org. Zie de notities in het projectbestand HostingStartupApp voor meer informatie.

    <PropertyGroup>
  <RestoreSources>$(RestoreSources);https://api.nuget.org/v3/index.json;../HostingStartupPackage/bin/Debug</RestoreSources>
</PropertyGroup>

  4. U ziet dat de waarden van de serviceconfiguratiesleutel die door de pagina Index worden weergegeven, overeenkomen met de waarden die zijn ingesteld door de methode van ServiceKeyInjection.Configure het pakket.

Als u wijzigingen aanbrengt in het project HostingStartupPackage en het opnieuw samenstelt, wist dan de lokale NuGet-pakketcaches om ervoor te zorgen dat de HostingStartupApp het bijgewerkte pakket ontvangt in plaats van een verouderd pakket uit de lokale cache. Als u de lokale NuGet-caches wilt wissen, voert u de volgende dotnet nuget locals-opdracht uit:

dotnet nuget locals all --clear

Activering vanuit een klassebibliotheek

  1. Compileer de class library HostingStartupLibrary met de dotnet build-opdracht.

  2. Voeg de assemblynaam van de klassebibliotheek van HostingStartupLibrary toe aan de ASPNETCORE_HOSTINGSTARTUPASSEMBLIES omgevingsvariabele.

  3. bin-deploy de assembly van de class library naar de app door het HostingStartupLibrary.dll-bestand te kopiëren van de gecompileerde uitvoer van de class library naar de bin/Debug map van de app.

  4. Compileer en voer de app uit. Een <ItemGroup> in het projectbestand van de app verwijst naar de assembly van de klassebibliotheek (.\bin\Debug\netcoreapp3.0\HostingStartupLibrary.dll) (een referentie voor compileertijd). Zie de notities in het projectbestand HostingStartupApp voor meer informatie.

    <ItemGroup>
  <Reference Include=".\\bin\\Debug\\netcoreapp3.0\\HostingStartupLibrary.dll">
    <HintPath>.\bin\Debug\netcoreapp3.0\HostingStartupLibrary.dll</HintPath>
    <SpecificVersion>False</SpecificVersion> 
  </Reference>
</ItemGroup>

  5. U ziet dat de waarden van de serviceconfiguratiesleutel die door de Indexpagina worden weergegeven, overeenkomen met de waarden die zijn ingesteld door de methode van de klassebibliotheek ServiceKeyInjection.Configure.

Activering van een door een runtime store geïmplementeerde assembly

  1. Het Project StartupDiagnostics gebruikt PowerShell om het StartupDiagnostics.deps.json bestand te wijzigen. PowerShell is standaard geïnstalleerd in Windows vanaf Windows 7 SP1 en Windows Server 2008 R2 SP1. Zie Verschillende versies van PowerShell installeren om PowerShell op andere platforms te verkrijgen.
  2. Voer het build.ps1 script uit in de map RuntimeStore . Het script:
    • Hiermee wordt het StartupDiagnostics pakket gegenereerd in de map obj\packages .
    • Hiermee wordt de runtime store gegenereerd voor StartupDiagnostics in de storemap. De dotnet store opdracht in het script maakt gebruik van de win7-x64runtime-id (RID) voor een hosting-opstartprogramma dat is geïmplementeerd in Windows. Wanneer u de hosting voor een andere runtime instelt, vervangt u de juiste RID op regel 37 van het script. Het runtimearchief voor StartupDiagnostics zou later worden verplaatst naar het runtimearchief van de gebruiker of het systeem op de computer waarop de assembly wordt verbruikt. De installatielocatie van de runtime store van de gebruiker voor de StartupDiagnostics assembly is .dotnet/store/x64/netcoreapp3.0/startupdiagnostics/1.0.0/lib/netcoreapp3.0/StartupDiagnostics.dll.
    • Hiermee genereert u de additionalDeps voor StartupDiagnostics in de map additionalDeps. De aanvullende afhankelijkheden worden later verplaatst naar de aanvullende afhankelijkheden van de gebruiker of het systeem. De installatielocatie voor aanvullende afhankelijkheden van de gebruiker StartupDiagnostics is .dotnet/x64/additionalDeps/StartupDiagnostics/shared/Microsoft.NETCore.App/3.0.0/StartupDiagnostics.deps.json.
    • Hiermee plaatst u het deploy.ps1 bestand in de implementatiemap .
  3. Voer het deploy.ps1 script uit in de implementatiemap. Het script voegt het volgende toe:
    • StartupDiagnostics naar de ASPNETCORE_HOSTINGSTARTUPASSEMBLIES omgevingsvariabele.
    • Het pad voor opstartafhankelijkheden (in de implementatiemap van het RuntimeStore-project) naar de DOTNET_ADDITIONAL_DEPS omgevingsvariabele.
    • Het runtimearchiefpad (in de implementatiemap van het RuntimeStore-project) naar de DOTNET_SHARED_STORE omgevingsvariabele.
  4. Voer de voorbeeld-app uit.
  5. Verzoek het /services-eindpunt om de geregistreerde diensten van de app te bekijken. Vraag het /diag eindpunt aan voor de diagnostische informatie.

Een IHostingStartup (hosting startup) implementatie integreert verbeteringen in een app bij het starten van een externe assembly. Een externe bibliotheek kan bijvoorbeeld een opstart-implementatie voor hosting gebruiken om extra configuratieproviders of -services aan een app te bieden.

Voorbeeldcode bekijken of downloaden (hoe download je)

Kenmerk HostingStartup

Een kenmerk HostingStartup geeft de aanwezigheid aan van een hosting-opstartassembly die tijdens runtime moet worden geactiveerd.

De invoerassembly of de assembly met de Startup klasse wordt automatisch gescand op het HostingStartup kenmerk. De lijst met assembly's voor het zoeken naar HostingStartup kenmerken wordt tijdens runtime geladen vanuit de configuratie in de WebHostDefaults.HostingStartupAssembliesKey. De lijst met assembly's die moeten worden uitgesloten van detectie wordt geladen van de WebHostDefaults.HostingStartupExcludeAssembliesKey. Voor meer informatie, zie Webhost: hosting opstart-assembly's en Webhost: hosting opstart-assembly's uitsluiten.

In het volgende voorbeeld is StartupEnhancementde naamruimte van de hosting-opstartassembly. De klasse met de opstartcode van de hosting is StartupEnhancementHostingStartup:

[assembly: HostingStartup(typeof(StartupEnhancement.StartupEnhancementHostingStartup))]

Het HostingStartup kenmerk bevindt zich meestal in het implementatieklassebestand van IHostingStartup de hosting-assembly.

Geladen opstartassembly's voor hosting detecteren

Als u geladen hostingstartassemblages wilt detecteren, schakelt u logging in en controleert u de logboeken van de app. Fouten die optreden bij het laden van assembly's worden vastgelegd. Geladen hosting startup-assembly's worden geregistreerd op Debug-niveau en alle fouten worden vastgelegd.

Automatisch laden van opstartassembly's voor hosting uitschakelen

Als u het automatisch laden van opstartassemblages wilt uitschakelen, gebruikt u een van de volgende methodes:

  • "Om te voorkomen dat alle opstartassembly's worden geladen, stelt u een van de volgende opties in op true of 1:"
  • Als u wilt voorkomen dat specifieke opstartassembly's worden geladen, stelt u een van de volgende opties in op een door puntkomma's gescheiden tekenreeks voor het hosten van opstartassembly's die moeten worden uitgesloten bij het opstarten:

Als zowel de hostconfiguratie-instelling als de omgevingsvariabele zijn ingesteld, bepaalt de hostinstelling het gedrag.

Door het hosten van opstartassembly's uit te schakelen met behulp van de hostinstelling of omgevingsvariabele, wordt de assembly globaal uitgeschakeld en kunnen verschillende kenmerken van een app worden uitgeschakeld.

Project

Maak een hostingstart met een van de volgende projecttypen:

Klassebibliotheek

Er kan een opstartverbetering voor hosting worden geboden in een klassebibliotheek. De bibliotheek bevat een HostingStartup kenmerk.

De voorbeeldcode bevat een Razor Pages-app, HostingStartupApp en een klassebibliotheek, HostingStartupLibrary. De klassebibliotheek:

  • Bevat een opstartklasse voor hosting, ServiceKeyInjectiondie implementeert IHostingStartup. ServiceKeyInjection voegt een paar servicetekenreeksen toe aan de configuratie van de app met behulp van de in-memory configuratieprovider (AddInMemoryCollection).
  • Bevat een HostingStartup kenmerk dat de naamruimte en klasse van de hosting start-up identificeert.

De methode van ServiceKeyInjection de Configure klasse maakt gebruik van een IWebHostBuilder methode om verbeteringen aan een app toe te voegen.

HostingStartupLibrary/ServiceKeyInjection.cs:

[assembly: HostingStartup(typeof(HostingStartupLibrary.ServiceKeyInjection))]

namespace HostingStartupLibrary
{
    public class ServiceKeyInjection : IHostingStartup
    {
        public void Configure(IWebHostBuilder builder)
        {
            builder.ConfigureAppConfiguration(config =>
            {
                var dict = new Dictionary<string, string>
                {
                    {"DevAccount_FromLibrary", "DEV_1111111-1111"},
                    {"ProdAccount_FromLibrary", "PROD_2222222-2222"}
                };

                config.AddInMemoryCollection(dict);
            });
        }
    }
}

De indexpagina van de app leest en geeft de configuratiewaarden weer voor de twee keys die zijn ingesteld door de hostingstartupassembly van de klassebibliotheek.

HostingStartupApp/Pages/Index.cshtml.cs:

public class IndexModel : PageModel
{
    public IndexModel(IConfiguration config)
    {
        ServiceKey_Development_Library = config["DevAccount_FromLibrary"];
        ServiceKey_Production_Library = config["ProdAccount_FromLibrary"];
        ServiceKey_Development_Package = config["DevAccount_FromPackage"];
        ServiceKey_Production_Package = config["ProdAccount_FromPackage"];
    }

    public string ServiceKey_Development_Library { get; private set; }
    public string ServiceKey_Production_Library { get; private set; }
    public string ServiceKey_Development_Package { get; private set; }
    public string ServiceKey_Production_Package { get; private set; }

    public void OnGet()
    {
    }
}

De voorbeeldcode bevat ook een NuGet-pakketproject dat een afzonderlijke hostingstart, HostingStartupPackage, biedt. Het pakket heeft dezelfde kenmerken van de eerder beschreven klassebibliotheek. Het pakket:

  • Bevat een opstartklasse voor hosting, ServiceKeyInjectiondie implementeert IHostingStartup. ServiceKeyInjection voegt een paar servicetekenreeksen toe aan de configuratie van de app.
  • Bevat een HostingStartup kenmerk.

HostingStartupPackage/ServiceKeyInjection.cs:

[assembly: HostingStartup(typeof(HostingStartupPackage.ServiceKeyInjection))]

namespace HostingStartupPackage
{
    public class ServiceKeyInjection : IHostingStartup
    {
        public void Configure(IWebHostBuilder builder)
        {
            builder.ConfigureAppConfiguration(config =>
            {
                var dict = new Dictionary<string, string>
                {
                    {"DevAccount_FromPackage", "DEV_3333333-3333"},
                    {"ProdAccount_FromPackage", "PROD_4444444-4444"}
                };

                config.AddInMemoryCollection(dict);
            });
        }
    }
}

De indexpagina van de app leest en geeft de configuratiewaarden weer voor de twee kenmerken die zijn ingesteld door de opstart-assembly van het pakket.

HostingStartupApp/Pages/Index.cshtml.cs:

public class IndexModel : PageModel
{
    public IndexModel(IConfiguration config)
    {
        ServiceKey_Development_Library = config["DevAccount_FromLibrary"];
        ServiceKey_Production_Library = config["ProdAccount_FromLibrary"];
        ServiceKey_Development_Package = config["DevAccount_FromPackage"];
        ServiceKey_Production_Package = config["ProdAccount_FromPackage"];
    }

    public string ServiceKey_Development_Library { get; private set; }
    public string ServiceKey_Production_Library { get; private set; }
    public string ServiceKey_Development_Package { get; private set; }
    public string ServiceKey_Production_Package { get; private set; }

    public void OnGet()
    {
    }
}

Console-app zonder toegangspunt

Deze benadering is alleen beschikbaar voor .NET-apps, niet voor .NET Framework.

Een dynamische opstartverbetering voor hosting waarvoor geen referentie voor compileertijd voor activering is vereist, kan worden opgegeven in een console-app zonder een ingangspunt dat een HostingStartup kenmerk bevat. Het publiceren van de console-app produceert een host-opstartassembly die kan worden gebruikt vanuit de runtime store.

In dit proces wordt een console-app zonder invoerpunt gebruikt, omdat:

  • Er is een afhankelijkheidsbestand vereist om de hosting-startup te gebruiken in de hosting-startup-assembly. Een afhankelijkheidsbestand is een uitvoerbare app-asset die wordt geproduceerd door het publiceren van een app, niet een bibliotheek.
  • Een bibliotheek kan niet rechtstreeks worden toegevoegd aan het runtime-pakketarchief. Hiervoor is een uitvoerbaar project vereist dat gericht is op de gedeelde runtime.

Bij het opzetten van een dynamische hoststartup:

  • Er wordt een hosting-opstartassembly gemaakt vanuit de console-app zonder een ingangspunt dat:
    • Bevat een klasse die de IHostingStartup implementatie bevat.
    • Bevat een HostingStartup-kenmerk om de IHostingStartup implementatieklasse te identificeren.
  • De console-applicatie wordt gepubliceerd om de afhankelijkheden van de hostingstartup te verkrijgen. Als gevolg van het publiceren van de console-app is dat ongebruikte afhankelijkheden worden afgekapt uit het afhankelijkhedenbestand.
  • Het afhankelijkhedenbestand wordt gewijzigd om de runtimelocatie van de host-opstartassembly in te stellen.
  • De hosting-opstartassembly en het bijbehorende afhankelijkhedenbestand worden in het runtime-pakketarchief geplaatst. Als u de opstartassembly en het bijbehorende afhankelijkhedenbestand wilt detecteren, worden ze vermeld in een paar omgevingsvariabelen.

De console-app verwijst naar het pakket Microsoft.AspNetCore.Hosting.Abstractions :

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

  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Hosting.Abstractions" 
                      Version="2.1.1" />
  </ItemGroup>

</Project>

Een HostingStartup-kenmerk identificeert een klasse als een implementatie van IHostingStartup voor het laden en uitvoeren bij het bouwen van de IWebHost. In het volgende voorbeeld is StartupEnhancementde naamruimte en de klasse:StartupEnhancementHostingStartup

[assembly: HostingStartup(typeof(StartupEnhancement.StartupEnhancementHostingStartup))]

Een klasse implementeert IHostingStartup. De methode van Configure de klasse maakt gebruik van een IWebHostBuilder methode om verbeteringen aan een app toe te voegen. IHostingStartup.Configure in de hosting-startassembly wordt aangeroepen door de runtime vóór Startup.Configure in de gebruikerscode, waardoor de gebruikerscode alle configuraties kan overschrijven die door de hosting-startassembly worden geleverd.

namespace StartupEnhancement
{
    public class StartupEnhancementHostingStartup : IHostingStartup
    {
        public void Configure(IWebHostBuilder builder)
        {
            // Use the IWebHostBuilder to add app enhancements.
        }
    }
}

Bij het bouwen van een IHostingStartup project stelt het afhankelijkhedenbestand (.deps.json) de runtime locatie van de assembly in op de bin-map :

"targets": {
  ".NETCoreApp,Version=v2.1": {
    "StartupEnhancement/1.0.0": {
      "dependencies": {
        "Microsoft.AspNetCore.Hosting.Abstractions": "2.1.1"
      },
      "runtime": {
        "StartupEnhancement.dll": {}
      }
    }
  }
}

Er wordt slechts een deel van het bestand weergegeven. De assemblynaam in het voorbeeld is StartupEnhancement.

Configuratie geleverd door het opstarten van de hosting

Er zijn twee methoden voor het afhandelen van configuratie, afhankelijk van of u wilt dat de configuratie van het hosting-opstartprogramma voorrang krijgt of dat de configuratie van de app voorrang krijgt:

  1. Geef configuratie aan de app door ConfigureAppConfiguration te gebruiken om de configuratie te laden nadat de gedelegeerden van ConfigureAppConfiguration de app zijn uitgevoerd. Het hosten van opstartconfiguratie heeft voorrang op de configuratie van de app met behulp van deze benadering.
  2. Geef configuratie voor de app op door gebruik van UseConfiguration om de configuratie te laden voordat de gedelegeerden van de app ConfigureAppConfiguration worden uitgevoerd. De configuratiewaarden van de app hebben voorrang op de waarden die door de hosting-startup worden geleverd via deze methode.
public class ConfigurationInjection : IHostingStartup
{
    public void Configure(IWebHostBuilder builder)
    {
        Dictionary<string, string> dict;

        builder.ConfigureAppConfiguration(config =>
        {
            dict = new Dictionary<string, string>
            {
                {"ConfigurationKey1", 
                    "From IHostingStartup: Higher priority " +
                    "than the app's configuration."},
            };

            config.AddInMemoryCollection(dict);
        });

        dict = new Dictionary<string, string>
        {
            {"ConfigurationKey2", 
                "From IHostingStartup: Lower priority " +
                "than the app's configuration."},
        };

        var builtConfig = new ConfigurationBuilder()
            .AddInMemoryCollection(dict)
            .Build();

        builder.UseConfiguration(builtConfig);
    }
}

De hosting opstartassembly specificeren

Geef de naam van de hosting-startup-assembly op in de ASPNETCORE_HOSTINGSTARTUPASSEMBLIES omgevingsvariabele voor een hosting-startup die wordt geleverd door een klassebibliotheek of consoletoepassing. De omgevingsvariabele is een door puntkomma's gescheiden lijst met assembly's.

Alleen start-upassembly's voor hosting worden gescand op het HostingStartup attribuut. Voor de voorbeeld-app HostingStartupApp wordt de omgevingsvariabele ingesteld op de volgende waarde om de eerder beschreven hosting startups te ontdekken:

HostingStartupLibrary;HostingStartupPackage;StartupDiagnostics

Een opstartassembly voor hosting kan ook worden ingesteld met de hostconfiguratie-instelling Hosting Startup Assemblies.

Wanneer er meerdere hosting-opstartassembly's aanwezig zijn, worden hun Configure methoden uitgevoerd in de volgorde waarin de assembly's worden vermeld.

Activation

Opties voor het hosten van opstartactivering zijn:

  • Runtime-archief: voor activering is geen referentie voor de compilatietijd vereist. De voorbeeld-app plaatst de hosting-startup assembly en afhankelijkheidsbestanden in een map, implementatie, om de implementatie van de hosting-startup in een omgeving met meerdere machines te vergemakkelijken. De implementatiemap bevat ook een PowerShell-script waarmee omgevingsvariabelen in het implementatiesysteem worden gemaakt of gewijzigd om het opstarten van de hosting in te schakelen.
  • Referentie voor compilatietijd vereist voor activering

Runtime-archief

De hosting-opstart-implementatie wordt in het runtimearchief geplaatst. Een compilatietijdverwijzing naar de assembly is niet vereist voor de verbeterde app.

Nadat het hostingproject is gebouwd, wordt er een runtime-archief gegenereerd met behulp van het manifestbestand van het project en de dotnet store-opdracht.

dotnet store --manifest {MANIFEST FILE} --runtime {RUNTIME IDENTIFIER} --output {OUTPUT LOCATION} --skip-optimization

In de voorbeeld-app (RuntimeStore-project ) wordt de volgende opdracht gebruikt:

dotnet store --manifest store.manifest.csproj --runtime win7-x64 --output ./deployment/store --skip-optimization

Voor de runtime om de runtime-opslag te detecteren, wordt de locatie van de runtime-opslag toegevoegd aan de DOTNET_SHARED_STORE omgevingsvariabele.

Het afhankelijkhedenbestand van het hosting-opstartproces wijzigen en plaatsen

Als u de uitbreiding wilt activeren zonder een pakketverwijzing naar de uitbreiding, geeft u aanvullende afhankelijkheden op voor de runtime met additionalDeps. additionalDeps stelt u in staat om:

  • Breid de bibliotheekgrafiek van de app uit door een set extra .deps.json bestanden op te geven om samen te voegen met het eigen .deps.json bestand van de app bij het opstarten.
  • Maak de hosting-opstartassembly detecteerbaar en laadbaar.

De aanbevolen methode voor het genereren van het extra afhankelijkhedenbestand is het volgende:

  1. Voer dotnet publish het manifestbestand van het runtimearchief uit waarnaar in de vorige sectie wordt verwezen.
  2. Verwijder de manifestreferentie uit bibliotheken en de runtime sectie van het resulterende .deps.json bestand.

In het voorbeeldproject wordt de store.manifest/1.0.0 eigenschap verwijderd uit de targets en libraries sectie:

{
  "runtimeTarget": {
    "name": ".NETCoreApp,Version=v2.1",
    "signature": "4ea77c7b75ad1895ae1ea65e6ba2399010514f99"
  },
  "compilationOptions": {},
  "targets": {
    ".NETCoreApp,Version=v2.1": {
      "store.manifest/1.0.0": {
        "dependencies": {
          "StartupDiagnostics": "1.0.0"
        },
        "runtime": {
          "store.manifest.dll": {}
        }
      },
      "StartupDiagnostics/1.0.0": {
        "runtime": {
          "lib/netcoreapp2.1/StartupDiagnostics.dll": {
            "assemblyVersion": "1.0.0.0",
            "fileVersion": "1.0.0.0"
          }
        }
      }
    }
  },
  "libraries": {
    "store.manifest/1.0.0": {
      "type": "project",
      "serviceable": false,
      "sha512": ""
    },
    "StartupDiagnostics/1.0.0": {
      "type": "package",
      "serviceable": true,
      "sha512": "sha512-oiQr60vBQW7+nBTmgKLSldj06WNLRTdhOZpAdEbCuapoZ+M2DJH2uQbRLvFT8EGAAv4TAKzNtcztpx5YOgBXQQ==",
      "path": "startupdiagnostics/1.0.0",
      "hashPath": "startupdiagnostics.1.0.0.nupkg.sha512"
    }
  }
}

Plaats het .deps.json bestand op de volgende locatie:

{ADDITIONAL DEPENDENCIES PATH}/shared/{SHARED FRAMEWORK NAME}/{SHARED FRAMEWORK VERSION}/{ENHANCEMENT ASSEMBLY NAME}.deps.json
  • {ADDITIONAL DEPENDENCIES PATH}: Locatie toegevoegd aan de DOTNET_ADDITIONAL_DEPS omgevingsvariabele.
  • {SHARED FRAMEWORK NAME}: Gedeeld framework vereist voor dit extra afhankelijkhedenbestand.
  • {SHARED FRAMEWORK VERSION}: Minimale versie van gedeeld framework.
  • {ENHANCEMENT ASSEMBLY NAME}: de assemblynaam van de verbetering.

In de voorbeeld-app (RuntimeStore-project ) wordt het extra afhankelijkhedenbestand op de volgende locatie geplaatst:

deployment/additionalDeps/shared/Microsoft.AspNetCore.App/2.1.0/StartupDiagnostics.deps.json

Om de runtime in staat te stellen de locatie van het runtimearchief te detecteren, wordt de locatie van het aanvullende afhankelijkhedenbestand toegevoegd aan de DOTNET_ADDITIONAL_DEPS omgevingsvariabele.

Note

De DOTNET_ADDITIONAL_DEPS omgevingsvariabele werkt alleen met frameworkafhankelijke toepassingen. Deze omgevingsvariabele wordt genegeerd voor zelfstandige toepassingen.

In de voorbeeld-app (RuntimeStore-project ) wordt het bouwen van het runtimearchief en het genereren van het extra afhankelijkhedenbestand bereikt met behulp van een PowerShell-script .

Zie Meerdere omgevingen gebruiken voor voorbeelden van het instellen van omgevingsvariabelen voor verschillende besturingssystemen.

Deployment

Om de implementatie van een hostingstart in een omgeving met meerdere machines te vergemakkelijken, maakt de voorbeeld-app een implementatiemap in gepubliceerde uitvoer die het volgende bevat:

  • Het hosten van de opstartruntime store.
  • Het opstartafhankelijkhedenbestand van de hosting.
  • Een PowerShell-script dat de ASPNETCORE_HOSTINGSTARTUPASSEMBLIES, DOTNET_SHARED_STORE, en DOTNET_ADDITIONAL_DEPS creëert of wijzigt ter ondersteuning van de activering van de hostingstartup. Voer het script uit vanaf een PowerShell-opdrachtprompt met beheerdersrechten op het implementatiesysteem.

NuGet-pakket

Een verbetering voor een hosting-startup kan worden geleverd in een NuGet-pakket. Het pakket heeft een HostingStartup kenmerk. De hosting-opstarttypen die door het pakket worden geleverd, worden beschikbaar gesteld aan de app met behulp van een van de volgende methoden:

  • Het projectbestand van de verbeterde app maakt een pakketverwijzing voor het opstarten van de hosting in het projectbestand van de app (een referentie voor compileertijd). Met de referentie voor compilatietijd worden de opstartassembly van de hosting en alle bijbehorende afhankelijkheden opgenomen in het afhankelijkheidsbestand van de app (.deps.json). Deze benadering is van toepassing op een hosting-opstartassemblypakket dat is gepubliceerd op nuget.org.
  • Het afhankelijkhedenbestand van de hosting-startup wordt beschikbaar gesteld aan de geoptimaliseerde app, zoals beschreven in de sectie over de Runtime Store (zonder een compile-tijd-referentie).

Zie de volgende onderwerpen voor meer informatie over NuGet-pakketten en de runtime-opslag:

Map Van Project-bin

Een hosting-opstartverbetering kan worden geleverd door een door een bin geïmplementeerde assembly in de verbeterde app. De hosting-opstarttypen die door de assembly worden geleverd, worden beschikbaar gesteld aan de app met behulp van een van de volgende methoden:

  • Het projectbestand van de verbeterde app maakt een assemblyverwijzing naar het opstarten van de hosting (een referentie voor compileertijd). Met de referentie voor compilatietijd worden de opstartassembly van de hosting en alle bijbehorende afhankelijkheden opgenomen in het afhankelijkheidsbestand van de app (.deps.json). Deze benadering is van toepassing wanneer het implementatiescenario aanroept om een compileertijdverwijzing te maken naar de assembly van het hosting-opstartproces (.dll bestand) en de assembly naar een van de volgende opties te verplaatsen:
    • Het verbruikende project.
    • Een locatie die toegankelijk is voor het verbruikende project.
  • Het afhankelijkhedenbestand van de hosting-startup wordt beschikbaar gesteld aan de geoptimaliseerde app, zoals beschreven in de sectie over de Runtime Store (zonder een compile-tijd-referentie).
  • Wanneer de assembly is gericht op .NET Framework, kan de assembly worden geladen in de standaardbelastingcontext, wat op .NET Framework betekent dat de assembly zich op een van de volgende locaties bevindt:
    • Toepassingsbasispad: de bin-map waar het uitvoerbare bestand van de app (.exe) zich bevindt.
    • Global Assembly Cache (GAC): De GAC slaat assembly's op die verschillende .NET Framework-apps delen. Voor meer informatie, zie Een assembly installeren in de algemene assemblycache in de .NET Framework-documentatie.

Voorbeeldcode

De voorbeeldcode (downloaden) laat scenario's zien voor het hosten van opstart-implementatiescenario's:

  • Twee hosting opstartassembly's (klassebibliotheken) initialiseren elk een paar configuratiesleutel-waardeparen in het geheugen:
    • NuGet-pakket (HostingStartupPackage)
    • Klassebibliotheek (HostingStartupLibrary)
  • Een hostingstartup wordt geactiveerd vanuit een runtime store-gedeponeerde assembly (StartupDiagnostics). De assembly voegt bij het opstarten twee middlewares toe aan de app die diagnostische informatie biedt over:
    • Geregistreerde services
    • Adres (schema, host, padbasis, pad, pad, querytekenreeks)
    • Verbinding (extern IP, externe poort, lokaal IP, lokale poort, clientcertificaat)
    • Headers aanvragen
    • Omgevingsvariabelen

Het voorbeeld uitvoeren:

Activering vanuit een NuGet-pakket

  1. Compileer het pakket HostingStartupPackage met de opdracht dotnet pack .

  2. Voeg de assemblynaam van het pakket van de HostingStartupPackage toe aan de ASPNETCORE_HOSTINGSTARTUPASSEMBLIES omgevingsvariabele.

  3. Compileer en voer de app uit. Er is een pakketverwijzing aanwezig in de verbeterde app (een referentie voor compileertijd). Een <PropertyGroup> in het projectbestand van de app geeft de uitvoer van het pakketproject (../HostingStartupPackage/bin/Debug) als pakketbron. Hierdoor kan de app het pakket gebruiken zonder het pakket te uploaden naar nuget.org. Zie de notities in het projectbestand HostingStartupApp voor meer informatie.

    <PropertyGroup>
  <RestoreSources>$(RestoreSources);https://api.nuget.org/v3/index.json;../HostingStartupPackage/bin/Debug</RestoreSources>
</PropertyGroup>

  4. U ziet dat de waarden van de serviceconfiguratiesleutel die door de pagina Index worden weergegeven, overeenkomen met de waarden die zijn ingesteld door de methode van ServiceKeyInjection.Configure het pakket.

Als u wijzigingen aanbrengt in het project HostingStartupPackage en het opnieuw samenstelt, wist dan de lokale NuGet-pakketcaches om ervoor te zorgen dat de HostingStartupApp het bijgewerkte pakket ontvangt in plaats van een verouderd pakket uit de lokale cache. Als u de lokale NuGet-caches wilt wissen, voert u de volgende dotnet nuget locals-opdracht uit:

dotnet nuget locals all --clear

Activering vanuit een klassebibliotheek

  1. Compileer de class library HostingStartupLibrary met de dotnet build-opdracht.

  2. Voeg de assemblynaam van de klassebibliotheek van HostingStartupLibrary toe aan de ASPNETCORE_HOSTINGSTARTUPASSEMBLIES omgevingsvariabele.

  3. bin-deploy de assembly van de class library naar de app door het HostingStartupLibrary.dll-bestand te kopiëren van de gecompileerde uitvoer van de class library naar de bin/Debug map van de app.

  4. Compileer en voer de app uit. Een <ItemGroup> in het projectbestand van de app verwijst naar de assembly van de klassebibliotheek (.\bin\Debug\netcoreapp2.1\HostingStartupLibrary.dll) (een referentie voor compileertijd). Zie de notities in het projectbestand HostingStartupApp voor meer informatie.

    <ItemGroup>
  <Reference Include=".\\bin\\Debug\\netcoreapp2.1\\HostingStartupLibrary.dll">
    <HintPath>.\bin\Debug\netcoreapp2.1\HostingStartupLibrary.dll</HintPath>
    <SpecificVersion>False</SpecificVersion>
  </Reference>
</ItemGroup>

  5. U ziet dat de waarden van de serviceconfiguratiesleutel die door de Indexpagina worden weergegeven, overeenkomen met de waarden die zijn ingesteld door de methode van de klassebibliotheek ServiceKeyInjection.Configure.

Activering van een door een runtime store geïmplementeerde assembly

  1. Het Project StartupDiagnostics gebruikt PowerShell om het StartupDiagnostics.deps.json bestand te wijzigen. PowerShell is standaard geïnstalleerd in Windows vanaf Windows 7 SP1 en Windows Server 2008 R2 SP1. Zie Verschillende versies van PowerShell installeren om PowerShell op andere platforms te verkrijgen.
  2. Voer het build.ps1 script uit in de map RuntimeStore . Het script:
    • Hiermee wordt het StartupDiagnostics pakket gegenereerd in de map obj\packages .
    • Hiermee wordt de runtime store gegenereerd voor StartupDiagnostics in de storemap. De dotnet store opdracht in het script maakt gebruik van de win7-x64runtime-id (RID) voor een hosting-opstartprogramma dat is geïmplementeerd in Windows. Wanneer u de hosting voor een andere runtime instelt, vervangt u de juiste RID op regel 37 van het script. Het runtimearchief voor StartupDiagnostics zou later worden verplaatst naar het runtimearchief van de gebruiker of het systeem op de computer waarop de assembly wordt verbruikt. De installatielocatie voor het runtimearchief van de gebruiker voor de StartupDiagnostics assembly is .dotnet/store/x64/netcoreapp2.2/startupdiagnostics/1.0.0/lib/netcoreapp2.2/StartupDiagnostics.dll.
    • Hiermee genereert u de additionalDeps voor StartupDiagnostics in de map additionalDeps. De aanvullende afhankelijkheden worden later verplaatst naar de aanvullende afhankelijkheden van de gebruiker of het systeem. De installatielocatie voor aanvullende afhankelijkheden van de gebruiker StartupDiagnostics is .dotnet/x64/additionalDeps/StartupDiagnostics/shared/Microsoft.NETCore.App/2.2.0/StartupDiagnostics.deps.json.
    • Hiermee plaatst u het deploy.ps1 bestand in de implementatiemap .
  3. Voer het deploy.ps1 script uit in de implementatiemap. Het script voegt het volgende toe:
    • StartupDiagnostics naar de ASPNETCORE_HOSTINGSTARTUPASSEMBLIES omgevingsvariabele.
    • Het pad voor opstartafhankelijkheden (in de implementatiemap van het RuntimeStore-project) naar de DOTNET_ADDITIONAL_DEPS omgevingsvariabele.
    • Het runtimearchiefpad (in de implementatiemap van het RuntimeStore-project) naar de DOTNET_SHARED_STORE omgevingsvariabele.
  4. Voer de voorbeeld-app uit.
  5. Verzoek het /services-eindpunt om de geregistreerde diensten van de app te bekijken. Vraag het /diag eindpunt aan voor de diagnostische informatie.