Udostępnij za pośrednictwem


Używanie zestawów uruchamiania hostingu w programie ASP.NET Core

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz .NET i .NET Core Support Policy (Zasady obsługi platformy .NET Core). Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

Ważne

Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Aby zapoznać się z bieżącą wersją, zapoznaj się z wersją tego artykułu platformy .NET 8.

Autor: Pavel Krymets

Implementacja IHostingStartup (uruchamianie hostingu) dodaje ulepszenia aplikacji podczas uruchamiania z zestawu zewnętrznego. Na przykład zewnętrzna biblioteka może używać implementacji uruchamiania hostingu w celu zapewnienia dodatkowych dostawców konfiguracji lub usług dla aplikacji.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Atrybut HostingStartup

Atrybut HostingStartup wskazuje obecność zestawu uruchamiania hostingu do aktywowania w czasie wykonywania.

Zestaw wejściowy lub zestaw zawierający Startup klasę jest automatycznie skanowany pod kątem atrybutu HostingStartup . Lista zestawów do HostingStartup wyszukiwania atrybutów jest ładowana w czasie wykonywania z konfiguracji w webHostDefaults.HostingStartupAssembliesKey. Lista zestawów do wykluczenia z odnajdywania jest ładowana z elementu WebHostDefaults.HostingStartupExcludeAssembliesKey.

W poniższym przykładzie przestrzeń nazw zestawu uruchamiania hostingu to StartupEnhancement. Klasa zawierająca kod uruchamiania hostingu to StartupEnhancementHostingStartup:

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

Atrybut HostingStartup zazwyczaj znajduje się w pliku klasy implementacji zestawu uruchamiania hostingu IHostingStartup .

Odnajdywanie załadowanych zestawów uruchamiania hostingu

Aby odnaleźć załadowane zestawy uruchamiania hostingu, włącz rejestrowanie i sprawdź dzienniki aplikacji. Błędy występujące podczas ładowania zestawów są rejestrowane. Załadowane zestawy uruchamiania hostingu są rejestrowane na poziomie debugowania, a wszystkie błędy są rejestrowane.

Wyłączanie automatycznego ładowania zestawów uruchamiania hostingu

Aby wyłączyć automatyczne ładowanie zestawów uruchamiania hostingu, użyj jednej z następujących metod:

  • Aby zapobiec ładowaniu wszystkich zestawów uruchamiania hostingu, ustaw jedną z następujących wartości na true lub 1:

    • Zapobiegaj ustawieniu konfiguracji hosta uruchamiania hostingu:

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

  • Aby zapobiec ładowaniu określonych zestawów uruchamiania hostingu, ustaw jeden z następujących elementów na rozdzielany średnikami ciąg hostowania zestawów uruchamiania, które mają zostać wykluczone podczas uruchamiania:

    • Ustawienie konfiguracji hosta Wykluczanie zestawów podczas uruchamiania hostingu:

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

      Symbol {ASSEMBLY1;ASSEMBLY2; ...} zastępczy reprezentuje rozdzieloną średnikami listę zestawów.

    • ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES zmienna środowiskowa.

Jeśli zarówno ustawienie konfiguracji hosta, jak i zmienna środowiskowa są ustawione, ustawienie hosta kontroluje zachowanie.

Wyłączenie hostowania zestawów uruchamiania przy użyciu ustawienia hosta lub zmiennej środowiskowej powoduje wyłączenie zestawu globalnie i może wyłączyć kilka cech aplikacji.

Projekt

Utwórz uruchomienie hostingu przy użyciu jednego z następujących typów projektów:

Biblioteka klas

Ulepszenia uruchamiania hostingu można udostępnić w bibliotece klas. Biblioteka zawiera HostingStartup atrybut.

Przykładowy kod zawiera aplikację Razor Pages, HostingStartupApp i bibliotekę klas HostingStartupLibrary. Biblioteka klas:

  • Zawiera klasę uruchamiania hostingu , ServiceKeyInjectionktóra implementuje IHostingStartupelement . ServiceKeyInjection Dodaje parę ciągów usługi do konfiguracji aplikacji przy użyciu dostawcy konfiguracji w pamięci (AddInMemoryCollection).
  • HostingStartup Zawiera atrybut identyfikujący przestrzeń nazw i klasę uruchamiania hostingu.

Metoda ServiceKeyInjection klasy Configure używa klasy , IWebHostBuilder aby dodać ulepszenia do aplikacji.

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

Strona Indeks aplikacji odczytuje i renderuje wartości konfiguracji dla dwóch kluczy ustawionych przez hostowany zestaw startowy biblioteki klas:

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()
    {
    }
}

Przykładowy kod zawiera również projekt pakietu NuGet, który zapewnia oddzielne uruchomienie hostingu HostingStartupPackage. Pakiet ma te same cechy biblioteki klas opisanej wcześniej. Pakiet:

  • Zawiera klasę uruchamiania hostingu , ServiceKeyInjectionktóra implementuje IHostingStartupelement . ServiceKeyInjection dodaje parę ciągów usługi do konfiguracji aplikacji.
  • HostingStartup Zawiera atrybut.

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

Strona Indeks aplikacji odczytuje i renderuje wartości konfiguracji dla dwóch kluczy ustawionych przez zestaw uruchamiania hostingu pakietu:

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()
    {
    }
}

Aplikacja konsolowa bez punktu wejścia

To podejście jest dostępne tylko dla aplikacji .NET Core, a nie .NET Framework.

Rozszerzenie dynamicznego uruchamiania hostingu, które nie wymaga odwołania czasu kompilacji do aktywacji, można udostępnić w aplikacji konsolowej bez punktu wejścia zawierającego HostingStartup atrybut. Publikowanie aplikacji konsolowej tworzy zestaw uruchamiania hostingu, który może być używany z magazynu środowiska uruchomieniowego.

W tym procesie jest używana aplikacja konsolowa bez punktu wejścia, ponieważ:

  • Plik zależności jest wymagany do korzystania z uruchamiania hostingu w zestawie startowym hostingu. Plik zależności jest zasobem aplikacji, który można uruchomić, który jest generowany przez opublikowanie aplikacji, a nie biblioteki.
  • Biblioteki nie można dodać bezpośrednio do magazynu pakietów środowiska uruchomieniowego, co wymaga projektu możliwego do uruchomienia, który jest przeznaczony dla współużytkowanego środowiska uruchomieniowego.

Podczas tworzenia dynamicznego uruchamiania hostingu:

  • Zestaw uruchamiania hostingu jest tworzony z poziomu aplikacji konsolowej bez punktu wejścia, który:
    • Zawiera klasę zawierającą implementację IHostingStartup .
    • Zawiera atrybut HostingStartup, aby zidentyfikować klasę implementacjiIHostingStartup.
  • Aplikacja konsolowa jest publikowana w celu uzyskania zależności uruchamiania hostingu. Konsekwencją publikowania aplikacji konsolowej jest to, że nieużywane zależności są przycinane z pliku zależności.
  • Plik zależności jest modyfikowany w celu ustawienia lokalizacji środowiska uruchomieniowego zestawu uruchamiania hostingu.
  • Zestaw uruchamiania hostingu i jego plik zależności jest umieszczany w magazynie pakietów środowiska uruchomieniowego. Aby odnaleźć zestaw uruchamiania hostingu i jego plik zależności, są one wymienione w parze zmiennych środowiskowych.

Aplikacja konsolowa odwołuje się do pakietu 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>

Atrybut HostingStartup identyfikuje klasę jako implementację IHostingStartup ładowania i wykonywania podczas kompilowania IWebHostobiektu . W poniższym przykładzie przestrzeń nazw to StartupEnhancement, a klasa to StartupEnhancementHostingStartup:

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

Klasa implementuje IHostingStartupelement . Metoda klasy Configure używa klasy , IWebHostBuilder aby dodać ulepszenia do aplikacji. IHostingStartup.Configure w zestawie uruchamiania hostingu jest wywoływany przez środowisko uruchomieniowe przed Startup.Configure kodem użytkownika, co umożliwia kodowi użytkownika zastąpienie dowolnej konfiguracji dostarczonej przez zestaw uruchamiania hostingu.

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

Podczas kompilowania IHostingStartup projektu plik zależności (.deps.json) ustawia runtime lokalizację zestawu w folderze bin :

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

Wyświetlana jest tylko część pliku. Nazwa zestawu w przykładzie to StartupEnhancement.

Konfiguracja dostarczana przez uruchamianie hostingu

Istnieją dwa podejścia do obsługi konfiguracji w zależności od tego, czy konfiguracja uruchamiania hostingu ma mieć pierwszeństwo, czy konfiguracja aplikacji ma mieć pierwszeństwo:

  1. Podaj konfigurację aplikacji przy użyciu polecenia ConfigureAppConfiguration , aby załadować konfigurację po wykonaniu delegatów aplikacji ConfigureAppConfiguration . Konfiguracja uruchamiania hostingu ma priorytet nad konfiguracją aplikacji przy użyciu tego podejścia.
  2. Podaj konfigurację aplikacji przy użyciu polecenia UseConfiguration , aby załadować konfigurację przed wykonaniem delegatów aplikacji ConfigureAppConfiguration . Wartości konfiguracji aplikacji mają priorytet nad wartościami dostarczonymi przez startup hostingu przy użyciu tego podejścia.
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);
    }
}

Określanie zestawu uruchamiania hostingu

W przypadku uruchamiania hostingu dostarczonego przez bibliotekę klas lub konsolę określ nazwę zestawu uruchamiania hostingu w zmiennej środowiskowej ASPNETCORE_HOSTINGSTARTUPASSEMBLIES . Zmienna środowiskowa to rozdzielana średnikami lista zestawów.

Dla atrybutu są skanowane tylko zestawy uruchamiania HostingStartup . W przypadku przykładowej aplikacji HostStartupApp w celu odnalezienia opisanych wcześniej startupów hostingu zmienna środowiskowa jest ustawiona na następującą wartość:

HostingStartupLibrary;HostingStartupPackage;StartupDiagnostics

Zestaw uruchamiania hostingu można również ustawić przy użyciu ustawienia konfiguracji hosta Zestawy uruchamiania hostingu:

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

Symbol {ASSEMBLY1;ASSEMBLY2; ...} zastępczy reprezentuje rozdzieloną średnikami listę zestawów.

Gdy istnieje wiele zestawów uruchamiania hostingu, ich Configure metody są wykonywane w kolejności, w których są wyświetlane zestawy.

Aktywacja

Opcje hostingu aktywacji uruchamiania to:

  • Magazyn środowiska uruchomieniowego: aktywacja nie wymaga odwołania do czasu kompilacji na potrzeby aktywacji. Przykładowa aplikacja umieszcza hostowanie plików zestawów startowych i zależności w folderze, wdrożeniu, aby ułatwić wdrażanie uruchamiania hostingu w środowisku wielomaszynowym. Folder wdrożenia zawiera również skrypt programu PowerShell, który tworzy lub modyfikuje zmienne środowiskowe w systemie wdrażania w celu włączenia uruchamiania hostingu.
  • Dokumentacja czasu kompilacji wymagana do aktywacji

Magazyn środowiska uruchomieniowego

Implementacja uruchamiania hostingu jest umieszczana w magazynie środowiska uruchomieniowego. Odwołanie do zestawu w czasie kompilacji nie jest wymagane przez rozszerzoną aplikację.

Po utworzeniu uruchamiania hostingu magazyn środowiska uruchomieniowego jest generowany przy użyciu pliku projektu manifestu i polecenia dotnet store .

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

W przykładowej aplikacji (projekt RuntimeStore ) jest używane następujące polecenie:

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

Aby środowisko uruchomieniowe odnajdywać magazyn środowiska uruchomieniowego, lokalizacja magazynu środowiska uruchomieniowego jest dodawana do zmiennej środowiskowej DOTNET_SHARED_STORE .

Modyfikowanie i umieszczanie pliku zależności uruchamiania hostingu

Aby aktywować rozszerzenie bez odwołania do pakietu do rozszerzenia, określ dodatkowe zależności środowiska uruchomieniowego za pomocą polecenia additionalDeps. additionalDeps umożliwia:

  • Rozszerz graf biblioteki aplikacji, udostępniając zestaw dodatkowych .deps.json plików do scalenia z własnym .deps.json plikiem aplikacji podczas uruchamiania.
  • Umożliwia odnajdywanie i ładowanie zestawu uruchamiania hostingu.

Zalecaną metodą generowania pliku dodatkowych zależności jest:

  1. Wykonaj polecenie dotnet publish w pliku manifestu magazynu środowiska uruchomieniowego, do których odwołuje się poprzednia sekcja.
  2. Usuń odwołanie manifestu z bibliotek i runtime sekcji wynikowego .deps.json pliku.

W przykładowym projekcie właściwość zostanie usunięta store.manifest/1.0.0 z targets sekcji i libraries :

{
  "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"
    }
  }
}

.deps.json Umieść plik w następującej lokalizacji:

{ADDITIONAL DEPENDENCIES PATH}/shared/{SHARED FRAMEWORK NAME}/{SHARED FRAMEWORK VERSION}/{ENHANCEMENT ASSEMBLY NAME}.deps.json
  • {ADDITIONAL DEPENDENCIES PATH}: Lokalizacja dodana do zmiennej środowiskowej DOTNET_ADDITIONAL_DEPS .
  • {SHARED FRAMEWORK NAME}: Platforma udostępniona wymagana dla tego dodatkowego pliku zależności.
  • {SHARED FRAMEWORK VERSION}: Minimalna wersja platformy udostępnionej.
  • {ENHANCEMENT ASSEMBLY NAME}: nazwa zestawu rozszerzenia.

W przykładowej aplikacji (projekt RuntimeStore ) plik dodatkowych zależności jest umieszczany w następującej lokalizacji:

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

Aby środowisko uruchomieniowe wykryło lokalizację magazynu środowiska uruchomieniowego, do zmiennej środowiskowej DOTNET_ADDITIONAL_DEPS zostanie dodana dodatkowa lokalizacja pliku zależności.

W przykładowej aplikacji (projekt RuntimeStore ) kompilowanie magazynu środowiska uruchomieniowego i generowanie dodatkowego pliku zależności odbywa się przy użyciu skryptu programu PowerShell .

Przykłady ustawiania zmiennych środowiskowych dla różnych systemów operacyjnych można znaleźć w temacie Use multiple environments (Używanie wielu środowisk).

Wdrożenie

Aby ułatwić wdrażanie uruchamiania hostingu w środowisku wielomaszynowym, przykładowa aplikacja tworzy folder wdrożenia w opublikowanych danych wyjściowych, które zawierają:

  • Hostowanie magazynu środowiska uruchomieniowego uruchamiania.
  • Plik zależności uruchamiania hostingu.
  • Skrypt programu PowerShell, który tworzy lub modyfikuje ASPNETCORE_HOSTINGSTARTUPASSEMBLIESelement , DOTNET_SHARED_STOREi DOTNET_ADDITIONAL_DEPS w celu obsługi aktywacji uruchamiania hostingu. Uruchom skrypt z administracyjnego wiersza polecenia programu PowerShell w systemie wdrażania.

Pakiet NuGet

Ulepszenia uruchamiania hostingu można udostępnić w pakiecie NuGet. Pakiet ma HostingStartup atrybut. Typy uruchamiania hostingu udostępniane przez pakiet są udostępniane aplikacji przy użyciu jednej z następujących metod:

  • Plik projektu rozszerzonej aplikacji zawiera odwołanie do pakietu dla uruchamiania hostingu w pliku projektu aplikacji (odwołanie do czasu kompilacji). W przypadku odwołania do czasu kompilacji zestaw uruchamiania hostowania i wszystkie jego zależności są włączone do pliku zależności aplikacji (.deps.json). Takie podejście dotyczy pakietu zestawu uruchamiania hostingu opublikowanego w nuget.org.
  • Plik zależności uruchamiania hostingu jest udostępniany rozszerzonej aplikacji zgodnie z opisem w sekcji Magazyn środowiska uruchomieniowego (bez odwołania do czasu kompilacji).

Aby uzyskać więcej informacji na temat pakietów NuGet i magazynu środowiska uruchomieniowego, zobacz następujące tematy:

Folder pojemnika projektu

Ulepszenia uruchamiania hostingu mogą być udostępniane przez zestaw wdrożony w pojemniku w rozszerzonej aplikacji. Typy uruchamiania hostingu udostępniane przez zestaw są udostępniane aplikacji przy użyciu jednego z następujących metod:

  • Plik projektu rozszerzonej aplikacji zawiera odwołanie do zestawu podczas uruchamiania hostingu (odwołanie do czasu kompilacji). W przypadku odwołania do czasu kompilacji zestaw uruchamiania hostowania i wszystkie jego zależności są włączone do pliku zależności aplikacji (.deps.json). Takie podejście ma zastosowanie, gdy scenariusz wdrażania wywołuje odwołanie w czasie kompilacji do zestawu (pliku .dll ) hostingu i przeniesienie zestawu do jednego z następujących elementów:
    • Projekt zużywania.
    • Lokalizacja dostępna dla projektu zużywanego.
  • Plik zależności uruchamiania hostingu jest udostępniany rozszerzonej aplikacji zgodnie z opisem w sekcji Magazyn środowiska uruchomieniowego (bez odwołania do czasu kompilacji).
  • W przypadku określania wartości docelowej programu .NET Framework zestaw jest ładowany w domyślnym kontekście ładowania, co w programie .NET Framework oznacza, że zestaw znajduje się w jednej z następujących lokalizacji:

Przykładowy kod

Przykładowy kod (jak pobrać) demonstruje hostowanie scenariuszy implementacji uruchamiania:

  • Dwa zestawy uruchamiania hostingu (biblioteki klas) ustawiają parę par klucz-wartość konfiguracji w pamięci każdy:
    • Pakiet NuGet (HostingStartupPackage)
    • Biblioteka klas (HostingStartupLibrary)
  • Uruchamianie hostingu jest aktywowane z zestawu wdrożonego w magazynie środowiska uruchomieniowego (StartupDiagnostics). Zestaw dodaje do aplikacji dwa oprogramowanie pośredniczące podczas uruchamiania, które udostępniają informacje diagnostyczne dotyczące:
    • Zarejestrowane usługi
    • Adres (schemat, host, ścieżka podstawowa, ścieżka, ciąg zapytania)
    • Połączenie (zdalny adres IP, port zdalny, lokalny adres IP, port lokalny, certyfikat klienta)
    • Nagłówki żądań
    • Zmienne środowiskowe

Aby uruchomić przykład:

Aktywacja z pakietu NuGet

  1. Skompiluj pakiet HostingStartupPackage za pomocą polecenia dotnet pack .

  2. Dodaj nazwę zestawu pakietu HostingStartupPackage do zmiennej środowiskowej ASPNETCORE_HOSTINGSTARTUPASSEMBLIES .

  3. Skompiluj i uruchom aplikację. Odwołanie do pakietu znajduje się w rozszerzonej aplikacji (odwołanie w czasie kompilacji). Element <PropertyGroup> w pliku projektu aplikacji określa dane wyjściowe projektu pakietu (.. /HostingStartupPackage/bin/Debug) jako źródło pakietu. Dzięki temu aplikacja może używać pakietu bez przekazywania pakietu do nuget.org. Aby uzyskać więcej informacji, zobacz uwagi w pliku projektu HostingStartupApp.

    <PropertyGroup>
      <RestoreSources>$(RestoreSources);https://api.nuget.org/v3/index.json;../HostingStartupPackage/bin/Debug</RestoreSources>
    </PropertyGroup>
    
  4. Zwróć uwagę, że wartości klucza konfiguracji usługi renderowane przez stronę Indeks są zgodne z wartościami ustawionymi przez metodę pakietu ServiceKeyInjection.Configure .

Jeśli wprowadzisz zmiany w projekcie HostingStartupPackage i ponownie skompilujesz go, wyczyść lokalne pamięci podręczne pakietów NuGet, aby upewnić się, że hostStartupApp otrzyma zaktualizowany pakiet, a nie nieaktualny pakiet z lokalnej pamięci podręcznej. Aby wyczyścić lokalne pamięci podręczne NuGet, wykonaj następujące polecenie dotnet nuget locals :

dotnet nuget locals all --clear

Aktywacja z biblioteki klas

  1. Skompiluj bibliotekę klas HostingStartupLibrary za pomocą polecenia dotnet build .

  2. Dodaj nazwę zestawu biblioteki klas HostingStartupLibrary do zmiennej środowiskowej ASPNETCORE_HOSTINGSTARTUPASSEMBLIES .

  3. bin-deploy zestawu biblioteki klas w aplikacji, kopiując plik HostingStartupLibrary.dll z skompilowanych danych wyjściowych biblioteki klas do folderu bin/Debug aplikacji.

  4. Skompiluj i uruchom aplikację. Element <ItemGroup> w pliku projektu aplikacji odwołuje się do zestawu biblioteki klas (.\bin\Debug\netcoreapp3.0\HostingStartupLibrary.dll) (odwołanie do czasu kompilacji). Aby uzyskać więcej informacji, zobacz uwagi w pliku projektu HostingStartupApp.

    <ItemGroup>
      <Reference Include=".\\bin\\Debug\\netcoreapp3.0\\HostingStartupLibrary.dll">
        <HintPath>.\bin\Debug\netcoreapp3.0\HostingStartupLibrary.dll</HintPath>
        <SpecificVersion>False</SpecificVersion> 
      </Reference>
    </ItemGroup>
    
  5. Zwróć uwagę, że wartości klucza konfiguracji usługi renderowane przez stronę Indeks są zgodne z wartościami ustawionymi przez metodę biblioteki ServiceKeyInjection.Configure klas.

Aktywacja z zestawu wdrożonego w magazynie środowiska uruchomieniowego

  1. Projekt StartupDiagnostics używa programu PowerShell do modyfikowania jego StartupDiagnostics.deps.json pliku. Program PowerShell jest instalowany domyślnie w systemie Windows, począwszy od systemu Windows 7 z dodatkiem SP1 i Windows Server 2008 R2 z dodatkiem SP1. Aby uzyskać program PowerShell na innych platformach, zobacz Instalowanie różnych wersji programu PowerShell.
  2. Wykonaj skrypt build.ps1 w folderze RuntimeStore. Skrypt:
    • StartupDiagnostics Generuje pakiet w folderze obj\packages.
    • Generuje magazyn środowiska uruchomieniowego dla StartupDiagnostics elementu w folderze store . Polecenie dotnet store w skry skryptzie używa identyfikatora win7-x64 środowiska uruchomieniowego (RID) na potrzeby uruchamiania hostingu wdrożonego w systemie Windows. Podczas udostępniania uruchamiania hostingu dla innego środowiska uruchomieniowego zastąp prawidłowy identyfikator RID w wierszu 37 skryptu. Magazyn środowiska uruchomieniowego programu StartupDiagnostics zostanie później przeniesiony do magazynu środowiska uruchomieniowego użytkownika lub systemu na maszynie, na której będzie używany zestaw. Lokalizacja instalacji magazynu środowiska uruchomieniowego użytkownika dla StartupDiagnostics zestawu to .dotnet/store/x64/netcoreapp3.0/startupdiagnostics/1.0.0/lib/netcoreapp3.0/StartupDiagnostics.dll.
    • Generuje element additionalDeps for StartupDiagnostics w folderze additionalDeps . Dodatkowe zależności zostaną później przeniesione do dodatkowych zależności użytkownika lub systemu. Lokalizacja instalacji dodatkowych zależności użytkownika StartupDiagnostics to .dotnet/x64/additionalDeps/StartupDiagnostics/shared/Microsoft.NETCore.App/3.0.0/StartupDiagnostics.deps.json.
    • Umieszcza plik deploy.ps1 w folderze wdrożenia.
  3. Uruchom skrypt deploy.ps1 w folderze wdrożenia. Skrypt dołącza:
    • StartupDiagnostics do zmiennej środowiskowej ASPNETCORE_HOSTINGSTARTUPASSEMBLIES .
    • Ścieżka zależności uruchamiania hostingu (w folderze wdrażania projektu RuntimeStore) do zmiennej środowiskowejDOTNET_ADDITIONAL_DEPS.
    • Ścieżka magazynu środowiska uruchomieniowego (w folderze wdrożenia projektu RuntimeStore) do zmiennej środowiskowejDOTNET_SHARED_STORE.
  4. Uruchom przykładową aplikację.
  5. Zażądaj punktu końcowego, /services aby wyświetlić zarejestrowane usługi aplikacji. Zażądaj punktu końcowego, /diag aby wyświetlić informacje diagnostyczne.

Implementacja IHostingStartup (uruchamianie hostingu) dodaje ulepszenia aplikacji podczas uruchamiania z zestawu zewnętrznego. Na przykład zewnętrzna biblioteka może używać implementacji uruchamiania hostingu w celu zapewnienia dodatkowych dostawców konfiguracji lub usług dla aplikacji.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Atrybut HostingStartup

Atrybut HostingStartup wskazuje obecność zestawu uruchamiania hostingu do aktywowania w czasie wykonywania.

Zestaw wejściowy lub zestaw zawierający Startup klasę jest automatycznie skanowany pod kątem atrybutu HostingStartup . Lista zestawów do HostingStartup wyszukiwania atrybutów jest ładowana w czasie wykonywania z konfiguracji w webHostDefaults.HostingStartupAssembliesKey. Lista zestawów do wykluczenia z odnajdywania jest ładowana z elementu WebHostDefaults.HostingStartupExcludeAssembliesKey. Aby uzyskać więcej informacji, zobacz Host sieci Web: hostowanie zestawów startowych i hosta internetowego: hostowanie zestawów wykluczania uruchamiania.

W poniższym przykładzie przestrzeń nazw zestawu uruchamiania hostingu to StartupEnhancement. Klasa zawierająca kod uruchamiania hostingu to StartupEnhancementHostingStartup:

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

Atrybut HostingStartup zazwyczaj znajduje się w pliku klasy implementacji zestawu uruchamiania hostingu IHostingStartup .

Odnajdywanie załadowanych zestawów uruchamiania hostingu

Aby odnaleźć załadowane zestawy uruchamiania hostingu, włącz rejestrowanie i sprawdź dzienniki aplikacji. Błędy występujące podczas ładowania zestawów są rejestrowane. Załadowane zestawy uruchamiania hostingu są rejestrowane na poziomie debugowania, a wszystkie błędy są rejestrowane.

Wyłączanie automatycznego ładowania zestawów uruchamiania hostingu

Aby wyłączyć automatyczne ładowanie zestawów uruchamiania hostingu, użyj jednej z następujących metod:

  • Aby zapobiec ładowaniu wszystkich zestawów uruchamiania hostingu, ustaw jedną z następujących wartości na true lub 1:
  • Aby zapobiec ładowaniu określonych zestawów uruchamiania hostingu, ustaw jeden z następujących elementów na rozdzielany średnikami ciąg hostowania zestawów uruchamiania, które mają zostać wykluczone podczas uruchamiania:

Jeśli zarówno ustawienie konfiguracji hosta, jak i zmienna środowiskowa są ustawione, ustawienie hosta kontroluje zachowanie.

Wyłączenie hostowania zestawów uruchamiania przy użyciu ustawienia hosta lub zmiennej środowiskowej powoduje wyłączenie zestawu globalnie i może wyłączyć kilka cech aplikacji.

Projekt

Utwórz uruchomienie hostingu przy użyciu jednego z następujących typów projektów:

Biblioteka klas

Ulepszenia uruchamiania hostingu można udostępnić w bibliotece klas. Biblioteka zawiera HostingStartup atrybut.

Przykładowy kod zawiera aplikację Razor Pages, HostingStartupApp i bibliotekę klas HostingStartupLibrary. Biblioteka klas:

  • Zawiera klasę uruchamiania hostingu , ServiceKeyInjectionktóra implementuje IHostingStartupelement . ServiceKeyInjection Dodaje parę ciągów usługi do konfiguracji aplikacji przy użyciu dostawcy konfiguracji w pamięci (AddInMemoryCollection).
  • HostingStartup Zawiera atrybut identyfikujący przestrzeń nazw i klasę uruchamiania hostingu.

Metoda ServiceKeyInjection klasy Configure używa klasy , IWebHostBuilder aby dodać ulepszenia do aplikacji.

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

Strona Indeks aplikacji odczytuje i renderuje wartości konfiguracji dla dwóch kluczy ustawionych przez hostowany zestaw startowy biblioteki klas:

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()
    {
    }
}

Przykładowy kod zawiera również projekt pakietu NuGet, który zapewnia oddzielne uruchomienie hostingu HostingStartupPackage. Pakiet ma te same cechy biblioteki klas opisanej wcześniej. Pakiet:

  • Zawiera klasę uruchamiania hostingu , ServiceKeyInjectionktóra implementuje IHostingStartupelement . ServiceKeyInjection dodaje parę ciągów usługi do konfiguracji aplikacji.
  • HostingStartup Zawiera atrybut.

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

Strona Indeks aplikacji odczytuje i renderuje wartości konfiguracji dla dwóch kluczy ustawionych przez zestaw uruchamiania hostingu pakietu:

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()
    {
    }
}

Aplikacja konsolowa bez punktu wejścia

To podejście jest dostępne tylko dla aplikacji .NET Core, a nie .NET Framework.

Rozszerzenie dynamicznego uruchamiania hostingu, które nie wymaga odwołania czasu kompilacji do aktywacji, można udostępnić w aplikacji konsolowej bez punktu wejścia zawierającego HostingStartup atrybut. Publikowanie aplikacji konsolowej tworzy zestaw uruchamiania hostingu, który może być używany z magazynu środowiska uruchomieniowego.

W tym procesie jest używana aplikacja konsolowa bez punktu wejścia, ponieważ:

  • Plik zależności jest wymagany do korzystania z uruchamiania hostingu w zestawie startowym hostingu. Plik zależności jest zasobem aplikacji, który można uruchomić, który jest generowany przez opublikowanie aplikacji, a nie biblioteki.
  • Biblioteki nie można dodać bezpośrednio do magazynu pakietów środowiska uruchomieniowego, co wymaga projektu możliwego do uruchomienia, który jest przeznaczony dla współużytkowanego środowiska uruchomieniowego.

Podczas tworzenia dynamicznego uruchamiania hostingu:

  • Zestaw uruchamiania hostingu jest tworzony z poziomu aplikacji konsolowej bez punktu wejścia, który:
    • Zawiera klasę zawierającą implementację IHostingStartup .
    • Zawiera atrybut HostingStartup, aby zidentyfikować klasę implementacjiIHostingStartup.
  • Aplikacja konsolowa jest publikowana w celu uzyskania zależności uruchamiania hostingu. Konsekwencją publikowania aplikacji konsolowej jest to, że nieużywane zależności są przycinane z pliku zależności.
  • Plik zależności jest modyfikowany w celu ustawienia lokalizacji środowiska uruchomieniowego zestawu uruchamiania hostingu.
  • Zestaw uruchamiania hostingu i jego plik zależności jest umieszczany w magazynie pakietów środowiska uruchomieniowego. Aby odnaleźć zestaw uruchamiania hostingu i jego plik zależności, są one wymienione w parze zmiennych środowiskowych.

Aplikacja konsolowa odwołuje się do pakietu 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>

Atrybut HostingStartup identyfikuje klasę jako implementację IHostingStartup ładowania i wykonywania podczas kompilowania IWebHostobiektu . W poniższym przykładzie przestrzeń nazw to StartupEnhancement, a klasa to StartupEnhancementHostingStartup:

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

Klasa implementuje IHostingStartupelement . Metoda klasy Configure używa klasy , IWebHostBuilder aby dodać ulepszenia do aplikacji. IHostingStartup.Configure w zestawie uruchamiania hostingu jest wywoływany przez środowisko uruchomieniowe przed Startup.Configure kodem użytkownika, co umożliwia kodowi użytkownika zastąpienie dowolnej konfiguracji dostarczonej przez zestaw uruchamiania hostingu.

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

Podczas kompilowania IHostingStartup projektu plik zależności (.deps.json) ustawia runtime lokalizację zestawu w folderze bin :

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

Wyświetlana jest tylko część pliku. Nazwa zestawu w przykładzie to StartupEnhancement.

Konfiguracja dostarczana przez uruchamianie hostingu

Istnieją dwa podejścia do obsługi konfiguracji w zależności od tego, czy konfiguracja uruchamiania hostingu ma mieć pierwszeństwo, czy konfiguracja aplikacji ma mieć pierwszeństwo:

  1. Podaj konfigurację aplikacji przy użyciu polecenia ConfigureAppConfiguration , aby załadować konfigurację po wykonaniu delegatów aplikacji ConfigureAppConfiguration . Konfiguracja uruchamiania hostingu ma priorytet nad konfiguracją aplikacji przy użyciu tego podejścia.
  2. Podaj konfigurację aplikacji przy użyciu polecenia UseConfiguration , aby załadować konfigurację przed wykonaniem delegatów aplikacji ConfigureAppConfiguration . Wartości konfiguracji aplikacji mają priorytet nad wartościami dostarczonymi przez startup hostingu przy użyciu tego podejścia.
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);
    }
}

Określanie zestawu uruchamiania hostingu

W przypadku uruchamiania hostingu dostarczonego przez bibliotekę klas lub konsolę określ nazwę zestawu uruchamiania hostingu w zmiennej środowiskowej ASPNETCORE_HOSTINGSTARTUPASSEMBLIES . Zmienna środowiskowa to rozdzielana średnikami lista zestawów.

Dla atrybutu są skanowane tylko zestawy uruchamiania HostingStartup . W przypadku przykładowej aplikacji HostStartupApp w celu odnalezienia opisanych wcześniej startupów hostingu zmienna środowiskowa jest ustawiona na następującą wartość:

HostingStartupLibrary;HostingStartupPackage;StartupDiagnostics

Zestaw startowy hostingu można również ustawić przy użyciu ustawienia konfiguracji hosta Zestawy uruchamiania hostingu.

Gdy istnieje wiele zestawów uruchamiania hostingu, ich Configure metody są wykonywane w kolejności, w których są wyświetlane zestawy.

Aktywacja

Opcje hostingu aktywacji uruchamiania to:

  • Magazyn środowiska uruchomieniowego: aktywacja nie wymaga odwołania do czasu kompilacji na potrzeby aktywacji. Przykładowa aplikacja umieszcza hostowanie plików zestawów startowych i zależności w folderze, wdrożeniu, aby ułatwić wdrażanie uruchamiania hostingu w środowisku wielomaszynowym. Folder wdrożenia zawiera również skrypt programu PowerShell, który tworzy lub modyfikuje zmienne środowiskowe w systemie wdrażania w celu włączenia uruchamiania hostingu.
  • Dokumentacja czasu kompilacji wymagana do aktywacji

Magazyn środowiska uruchomieniowego

Implementacja uruchamiania hostingu jest umieszczana w magazynie środowiska uruchomieniowego. Odwołanie do zestawu w czasie kompilacji nie jest wymagane przez rozszerzoną aplikację.

Po utworzeniu uruchamiania hostingu magazyn środowiska uruchomieniowego jest generowany przy użyciu pliku projektu manifestu i polecenia dotnet store .

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

W przykładowej aplikacji (projekt RuntimeStore ) jest używane następujące polecenie:

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

Aby środowisko uruchomieniowe odnajdywać magazyn środowiska uruchomieniowego, lokalizacja magazynu środowiska uruchomieniowego jest dodawana do zmiennej środowiskowej DOTNET_SHARED_STORE .

Modyfikowanie i umieszczanie pliku zależności uruchamiania hostingu

Aby aktywować rozszerzenie bez odwołania do pakietu do rozszerzenia, określ dodatkowe zależności środowiska uruchomieniowego za pomocą polecenia additionalDeps. additionalDeps umożliwia:

  • Rozszerz graf biblioteki aplikacji, udostępniając zestaw dodatkowych .deps.json plików do scalenia z własnym .deps.json plikiem aplikacji podczas uruchamiania.
  • Umożliwia odnajdywanie i ładowanie zestawu uruchamiania hostingu.

Zalecaną metodą generowania pliku dodatkowych zależności jest:

  1. Wykonaj polecenie dotnet publish w pliku manifestu magazynu środowiska uruchomieniowego, do których odwołuje się poprzednia sekcja.
  2. Usuń odwołanie manifestu z bibliotek i runtime sekcji wynikowego .deps.json pliku.

W przykładowym projekcie właściwość zostanie usunięta store.manifest/1.0.0 z targets sekcji i libraries :

{
  "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"
    }
  }
}

.deps.json Umieść plik w następującej lokalizacji:

{ADDITIONAL DEPENDENCIES PATH}/shared/{SHARED FRAMEWORK NAME}/{SHARED FRAMEWORK VERSION}/{ENHANCEMENT ASSEMBLY NAME}.deps.json
  • {ADDITIONAL DEPENDENCIES PATH}: Lokalizacja dodana do zmiennej środowiskowej DOTNET_ADDITIONAL_DEPS .
  • {SHARED FRAMEWORK NAME}: Platforma udostępniona wymagana dla tego dodatkowego pliku zależności.
  • {SHARED FRAMEWORK VERSION}: Minimalna wersja platformy udostępnionej.
  • {ENHANCEMENT ASSEMBLY NAME}: nazwa zestawu rozszerzenia.

W przykładowej aplikacji (projekt RuntimeStore ) plik dodatkowych zależności jest umieszczany w następującej lokalizacji:

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

Aby środowisko uruchomieniowe wykryło lokalizację magazynu środowiska uruchomieniowego, do zmiennej środowiskowej DOTNET_ADDITIONAL_DEPS zostanie dodana dodatkowa lokalizacja pliku zależności.

W przykładowej aplikacji (projekt RuntimeStore ) kompilowanie magazynu środowiska uruchomieniowego i generowanie dodatkowego pliku zależności odbywa się przy użyciu skryptu programu PowerShell .

Przykłady ustawiania zmiennych środowiskowych dla różnych systemów operacyjnych można znaleźć w temacie Use multiple environments (Używanie wielu środowisk).

Wdrożenie

Aby ułatwić wdrażanie uruchamiania hostingu w środowisku wielomaszynowym, przykładowa aplikacja tworzy folder wdrożenia w opublikowanych danych wyjściowych, które zawierają:

  • Hostowanie magazynu środowiska uruchomieniowego uruchamiania.
  • Plik zależności uruchamiania hostingu.
  • Skrypt programu PowerShell, który tworzy lub modyfikuje ASPNETCORE_HOSTINGSTARTUPASSEMBLIESelement , DOTNET_SHARED_STOREi DOTNET_ADDITIONAL_DEPS w celu obsługi aktywacji uruchamiania hostingu. Uruchom skrypt z administracyjnego wiersza polecenia programu PowerShell w systemie wdrażania.

Pakiet NuGet

Ulepszenia uruchamiania hostingu można udostępnić w pakiecie NuGet. Pakiet ma HostingStartup atrybut. Typy uruchamiania hostingu udostępniane przez pakiet są udostępniane aplikacji przy użyciu jednej z następujących metod:

  • Plik projektu rozszerzonej aplikacji zawiera odwołanie do pakietu dla uruchamiania hostingu w pliku projektu aplikacji (odwołanie do czasu kompilacji). W przypadku odwołania do czasu kompilacji zestaw uruchamiania hostowania i wszystkie jego zależności są włączone do pliku zależności aplikacji (.deps.json). Takie podejście dotyczy pakietu zestawu uruchamiania hostingu opublikowanego w nuget.org.
  • Plik zależności uruchamiania hostingu jest udostępniany rozszerzonej aplikacji zgodnie z opisem w sekcji Magazyn środowiska uruchomieniowego (bez odwołania do czasu kompilacji).

Aby uzyskać więcej informacji na temat pakietów NuGet i magazynu środowiska uruchomieniowego, zobacz następujące tematy:

Folder pojemnika projektu

Ulepszenia uruchamiania hostingu mogą być udostępniane przez zestaw wdrożony w pojemniku w rozszerzonej aplikacji. Typy uruchamiania hostingu udostępniane przez zestaw są udostępniane aplikacji przy użyciu jednego z następujących metod:

  • Plik projektu rozszerzonej aplikacji zawiera odwołanie do zestawu podczas uruchamiania hostingu (odwołanie do czasu kompilacji). W przypadku odwołania do czasu kompilacji zestaw uruchamiania hostowania i wszystkie jego zależności są włączone do pliku zależności aplikacji (.deps.json). Takie podejście ma zastosowanie, gdy scenariusz wdrażania wywołuje odwołanie w czasie kompilacji do zestawu (pliku .dll ) hostingu i przeniesienie zestawu do jednego z następujących elementów:
    • Projekt zużywania.
    • Lokalizacja dostępna dla projektu zużywanego.
  • Plik zależności uruchamiania hostingu jest udostępniany rozszerzonej aplikacji zgodnie z opisem w sekcji Magazyn środowiska uruchomieniowego (bez odwołania do czasu kompilacji).
  • W przypadku określania wartości docelowej programu .NET Framework zestaw jest ładowany w domyślnym kontekście ładowania, co w programie .NET Framework oznacza, że zestaw znajduje się w jednej z następujących lokalizacji:

Przykładowy kod

Przykładowy kod (jak pobrać) demonstruje hostowanie scenariuszy implementacji uruchamiania:

  • Dwa zestawy uruchamiania hostingu (biblioteki klas) ustawiają parę par klucz-wartość konfiguracji w pamięci każdy:
    • Pakiet NuGet (HostingStartupPackage)
    • Biblioteka klas (HostingStartupLibrary)
  • Uruchamianie hostingu jest aktywowane z zestawu wdrożonego w magazynie środowiska uruchomieniowego (StartupDiagnostics). Zestaw dodaje do aplikacji dwa oprogramowanie pośredniczące podczas uruchamiania, które udostępniają informacje diagnostyczne dotyczące:
    • Zarejestrowane usługi
    • Adres (schemat, host, ścieżka podstawowa, ścieżka, ciąg zapytania)
    • Połączenie (zdalny adres IP, port zdalny, lokalny adres IP, port lokalny, certyfikat klienta)
    • Nagłówki żądań
    • Zmienne środowiskowe

Aby uruchomić przykład:

Aktywacja z pakietu NuGet

  1. Skompiluj pakiet HostingStartupPackage za pomocą polecenia dotnet pack .

  2. Dodaj nazwę zestawu pakietu HostingStartupPackage do zmiennej środowiskowej ASPNETCORE_HOSTINGSTARTUPASSEMBLIES .

  3. Skompiluj i uruchom aplikację. Odwołanie do pakietu znajduje się w rozszerzonej aplikacji (odwołanie w czasie kompilacji). Element <PropertyGroup> w pliku projektu aplikacji określa dane wyjściowe projektu pakietu (.. /HostingStartupPackage/bin/Debug) jako źródło pakietu. Dzięki temu aplikacja może używać pakietu bez przekazywania pakietu do nuget.org. Aby uzyskać więcej informacji, zobacz uwagi w pliku projektu HostingStartupApp.

    <PropertyGroup>
      <RestoreSources>$(RestoreSources);https://api.nuget.org/v3/index.json;../HostingStartupPackage/bin/Debug</RestoreSources>
    </PropertyGroup>
    
  4. Zwróć uwagę, że wartości klucza konfiguracji usługi renderowane przez stronę Indeks są zgodne z wartościami ustawionymi przez metodę pakietu ServiceKeyInjection.Configure .

Jeśli wprowadzisz zmiany w projekcie HostingStartupPackage i ponownie skompilujesz go, wyczyść lokalne pamięci podręczne pakietów NuGet, aby upewnić się, że hostStartupApp otrzyma zaktualizowany pakiet, a nie nieaktualny pakiet z lokalnej pamięci podręcznej. Aby wyczyścić lokalne pamięci podręczne NuGet, wykonaj następujące polecenie dotnet nuget locals :

dotnet nuget locals all --clear

Aktywacja z biblioteki klas

  1. Skompiluj bibliotekę klas HostingStartupLibrary za pomocą polecenia dotnet build .

  2. Dodaj nazwę zestawu biblioteki klas HostingStartupLibrary do zmiennej środowiskowej ASPNETCORE_HOSTINGSTARTUPASSEMBLIES .

  3. bin-deploy zestawu biblioteki klas w aplikacji, kopiując plik HostingStartupLibrary.dll z skompilowanych danych wyjściowych biblioteki klas do folderu bin/Debug aplikacji.

  4. Skompiluj i uruchom aplikację. Plik <ItemGroup> projektu aplikacji odwołuje się do zestawu biblioteki klas (.\bin\Debug\netcoreapp2.1\HostingStartupLibrary.dll) (odwołanie do czasu kompilacji). Aby uzyskać więcej informacji, zobacz uwagi w pliku projektu HostingStartupApp.

    <ItemGroup>
      <Reference Include=".\\bin\\Debug\\netcoreapp2.1\\HostingStartupLibrary.dll">
        <HintPath>.\bin\Debug\netcoreapp2.1\HostingStartupLibrary.dll</HintPath>
        <SpecificVersion>False</SpecificVersion>
      </Reference>
    </ItemGroup>
    
  5. Zwróć uwagę, że wartości klucza konfiguracji usługi renderowane przez stronę Indeks są zgodne z wartościami ustawionymi przez metodę biblioteki ServiceKeyInjection.Configure klas.

Aktywacja z zestawu wdrożonego w magazynie środowiska uruchomieniowego

  1. Projekt StartupDiagnostics używa programu PowerShell do modyfikowania jego StartupDiagnostics.deps.json pliku. Program PowerShell jest instalowany domyślnie w systemie Windows, począwszy od systemu Windows 7 z dodatkiem SP1 i Windows Server 2008 R2 z dodatkiem SP1. Aby uzyskać program PowerShell na innych platformach, zobacz Instalowanie różnych wersji programu PowerShell.
  2. Wykonaj skrypt build.ps1 w folderze RuntimeStore. Skrypt:
    • StartupDiagnostics Generuje pakiet w folderze obj\packages.
    • Generuje magazyn środowiska uruchomieniowego dla StartupDiagnostics elementu w folderze store . Polecenie dotnet store w skry skryptzie używa identyfikatora win7-x64 środowiska uruchomieniowego (RID) na potrzeby uruchamiania hostingu wdrożonego w systemie Windows. Podczas udostępniania uruchamiania hostingu dla innego środowiska uruchomieniowego zastąp prawidłowy identyfikator RID w wierszu 37 skryptu. Magazyn środowiska uruchomieniowego programu StartupDiagnostics zostanie później przeniesiony do magazynu środowiska uruchomieniowego użytkownika lub systemu na maszynie, na której będzie używany zestaw. Lokalizacja instalacji magazynu środowiska uruchomieniowego użytkownika dla StartupDiagnostics zestawu to .dotnet/store/x64/netcoreapp2.2/startupdiagnostics/1.0.0/lib/netcoreapp2.2/StartupDiagnostics.dll.
    • Generuje element additionalDeps for StartupDiagnostics w folderze additionalDeps . Dodatkowe zależności zostaną później przeniesione do dodatkowych zależności użytkownika lub systemu. Lokalizacja instalacji dodatkowych zależności użytkownika StartupDiagnostics to .dotnet/x64/additionalDeps/StartupDiagnostics/shared/Microsoft.NETCore.App/2.2.0/StartupDiagnostics.deps.json.
    • Umieszcza plik deploy.ps1 w folderze wdrożenia.
  3. Uruchom skrypt deploy.ps1 w folderze wdrożenia. Skrypt dołącza:
    • StartupDiagnostics do zmiennej środowiskowej ASPNETCORE_HOSTINGSTARTUPASSEMBLIES .
    • Ścieżka zależności uruchamiania hostingu (w folderze wdrażania projektu RuntimeStore) do zmiennej środowiskowejDOTNET_ADDITIONAL_DEPS.
    • Ścieżka magazynu środowiska uruchomieniowego (w folderze wdrożenia projektu RuntimeStore) do zmiennej środowiskowejDOTNET_SHARED_STORE.
  4. Uruchom przykładową aplikację.
  5. Zażądaj punktu końcowego, /services aby wyświetlić zarejestrowane usługi aplikacji. Zażądaj punktu końcowego, /diag aby wyświetlić informacje diagnostyczne.