Udostępnij za pośrednictwem

Używanie szablonu projektu Angular z platformą ASP.NET Core

  • Artykuł

Uwaga

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

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz zasady pomocy technicznej platformy .NET i platformy .NET Core. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

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ą, zobacz wersję tego artykułu platformy .NET 9.

Program Visual Studio udostępnia szablony projektów do tworzenia aplikacji jednostronicowych (SPA) opartych na strukturach Języka JavaScript, takich jak Angular, React i Vue , które mają zaplecze platformy ASP.NET Core. Te szablony:

  • Utwórz rozwiązanie programu Visual Studio z projektem frontonu i projektem zaplecza.
  • Użyj typu projektu programu Visual Studio dla języków JavaScript i TypeScript (esproj) dla frontonu.
  • Użyj projektu ASP.NET Core dla zaplecza.

Projekty utworzone przy użyciu szablonów programu Visual Studio można uruchamiać z poziomu wiersza polecenia w systemach Windows, Linux i macOS. Aby uruchomić aplikację, użyj polecenia dotnet run --launch-profile https , aby uruchomić projekt serwera. Uruchomienie projektu serwera powoduje automatyczne uruchomienie serwera programistycznego JavaScript frontonu. Profil uruchamiania https jest obecnie wymagany.

Samouczek programu Visual Studio

Aby rozpocząć pracę z projektem Angular, postępuj zgodnie z samouczkiem Create an ASP.NET Core app with Angular (Tworzenie aplikacji platformy ASP.NET Core przy użyciu platformy Angular ) w dokumentacji programu Visual Studio.

Aby uzyskać więcej informacji, zobacz JavaScript i TypeScript w programie Visual Studio

szablony spa ASP.NET Core

Program Visual Studio zawiera szablony do tworzenia aplikacji ASP.NET Core z frontonem javaScript lub TypeScript. Te szablony są dostępne w programie Visual Studio 2022 w wersji 17.8 lub nowszej z zainstalowanym obciążeniem ASP.NET i tworzenie aplikacji internetowych.

Szablony programu Visual Studio do kompilowania aplikacji ASP.NET Core za pomocą frontonu JavaScript lub TypeScript oferują następujące korzyści:

  • Czyszczenie separacji projektów dla frontonu i zaplecza.
  • Bądź na bieżąco z najnowszymi wersjami platformy frontonu.
  • Integracja z najnowszymi narzędziami wiersza polecenia platformy frontonu, takimi jak Vite.
  • Szablony dla języków JavaScript i TypeScript (tylko TypeScript dla platformy Angular).
  • Rozbudowane środowisko edytowania kodu w języku JavaScript i TypeScript.
  • Integrowanie narzędzi kompilacji języka JavaScript z kompilacją platformy .NET.
  • Interfejs użytkownika zarządzania zależnościami npm.
  • Zgodne z konfiguracją debugowania i uruchamiania programu Visual Studio Code.
  • Uruchamianie testów jednostkowych frontonu w Eksploratorze testów przy użyciu platform testowych JavaScript.

Starsze szablony spa ASP.NET Core

Starsze wersje zestawu .NET SDK zawierały starsze szablony do tworzenia aplikacji SPA za pomocą platformy ASP.NET Core. Aby uzyskać dokumentację dotyczącą tych starszych szablonów, zobacz artykuły ASP.NET Core 7.0 z omówieniem SPA oraz artykułami Angular i React.

Szablon projektu ASP.NET Core z platformą Angular zapewnia wygodny punkt wyjścia dla aplikacji ASP.NET Core korzystających z platformy Angular i interfejsu wiersza polecenia platformy Angular w celu zaimplementowania rozbudowanego interfejsu użytkownika po stronie klienta.

Szablon projektu jest odpowiednikiem tworzenia zarówno projektu ASP.NET Core, aby działał jako internetowy interfejs API, jak i projekt interfejsu wiersza polecenia platformy Angular do działania jako interfejs użytkownika. Ta kombinacja projektu oferuje wygodę hostowania obu projektów w jednym projekcie ASP.NET Core, który można skompilować i opublikować jako pojedynczą jednostkę.

Szablon projektu nie jest przeznaczony do renderowania po stronie serwera (SSR).

Utwórz nową aplikację

Utwórz nowy projekt z poziomu wiersza polecenia przy użyciu polecenia dotnet new angular w pustym katalogu. Na przykład następujące polecenia tworzą aplikację w my-new-app katalogu i przełączają się do tego katalogu:

dotnet new angular -o my-new-app
cd my-new-app

Uruchom aplikację z poziomu programu Visual Studio lub interfejsu wiersza polecenia platformy .NET:

Otwórz wygenerowany .csproj plik i uruchom aplikację normalnie.

Proces kompilacji przywraca zależności npm przy pierwszym uruchomieniu, co może potrwać kilka minut. Kolejne kompilacje są znacznie szybsze.

Szablon projektu tworzy aplikację ASP.NET Core i aplikację Angular. Aplikacja ASP.NET Core ma być używana do uzyskiwania dostępu do danych, autoryzacji i innych problemów po stronie serwera. Aplikacja Angular, która znajduje się w podkatalogu ClientApp , ma być używana we wszystkich problemach interfejsu użytkownika.

Dodawanie stron, obrazów, stylów i modułów

Katalog ClientApp zawiera standardową aplikację interfejsu wiersza polecenia platformy Angular. Aby uzyskać więcej informacji, zobacz oficjalną dokumentację platformy Angular.

Istnieją niewielkie różnice między aplikacją Angular utworzoną przez ten szablon a aplikacją utworzoną przez sam interfejs wiersza polecenia platformy Angular (za pośrednictwem ng newmetody ); jednak możliwości aplikacji pozostają niezmienione. Aplikacja utworzona przez szablon zawiera układ oparty na platformie Bootstrap i podstawowy przykład routingu.

Uruchamianie poleceń ng

W wierszu polecenia przejdź do podkatalogu ClientApp :

cd ClientApp

Jeśli narzędzie jest ng zainstalowane globalnie, możesz uruchomić dowolne z jego poleceń. Można na przykład uruchomić ng lintpolecenie , ng testlub dowolne z innych poleceń interfejsu wiersza polecenia platformy Angular. Nie ma jednak potrzeby uruchamiania ng serve , ponieważ aplikacja ASP.NET Core obsługuje zarówno części po stronie serwera, jak i po stronie klienta aplikacji. Wewnętrznie używa ng serve go w programowania.

Jeśli nie masz zainstalowanego ng narzędzia, uruchom zamiast tego polecenie npm run ng . Można na przykład uruchomić npm run ng lint polecenie lub npm run ng test.

Instalowanie pakietów npm

Aby zainstalować pakiety npm innych firm, użyj wiersza polecenia w podkatalogu ClientApp . Na przykład:

cd ClientApp
npm install <package_name>

Publikowanie i wdrażanie

W programowania aplikacja działa w trybie zoptymalizowanym pod kątem wygody deweloperów. Na przykład pakiety języka JavaScript zawierają mapy źródłowe (dzięki czemu podczas debugowania można zobaczyć oryginalny kod TypeScript). Aplikacja obserwuje zmiany w plikach TypeScript, HTML i CSS na dysku oraz automatycznie ponownie skompilują i załadują ponownie, gdy te pliki się zmieniają.

W środowisku produkcyjnym należy obsługiwać wersję aplikacji zoptymalizowaną pod kątem wydajności. Ta konfiguracja jest konfigurowana automatycznie. Podczas publikowania konfiguracja kompilacji emituje z wyprzedzeniem skompilowana kompilacja kodu po stronie klienta. W przeciwieństwie do kompilacji programistycznej kompilacja produkcyjna nie wymaga środowiska Node.js być zainstalowane na serwerze (chyba że włączono renderowanie po stronie serwera (SSR)).

Można użyć standardowych metod hostingu i wdrażania ASP.NET Core.

Uruchom polecenie "ng serve" niezależnie

Projekt jest skonfigurowany do uruchamiania własnego wystąpienia serwera interfejsu wiersza polecenia platformy Angular w tle, gdy aplikacja ASP.NET Core uruchamia się w trybie programowania. Jest to wygodne, ponieważ nie trzeba ręcznie uruchamiać oddzielnego serwera.

Ta domyślna konfiguracja ma wadę. Za każdym razem, gdy zmodyfikujesz kod języka C#, a aplikacja ASP.NET Core musi ponownie uruchomić serwer interfejsu wiersza polecenia platformy Angular. Do uruchomienia kopii zapasowej wymagane jest około 10 sekund. Jeśli często dokonujesz edycji kodu w języku C# i nie chcesz czekać na ponowne uruchomienie interfejsu wiersza polecenia platformy Angular, uruchom serwer interfejsu wiersza polecenia platformy Angular zewnętrznie, niezależnie od procesu ASP.NET Core.

Aby uruchomić serwer interfejsu wiersza polecenia Platformy Angular zewnętrznie, przejdź do podkatalogu ClientApp w wierszu polecenia i uruchom serwer dewelopera interfejsu wiersza polecenia platformy Angular:

cd ClientApp
npm start

Po uruchomieniu aplikacji ASP.NET Core nie zostanie uruchomiony serwer interfejsu wiersza polecenia platformy Angular. Zamiast tego używane jest wystąpienie, które zostało uruchomione ręcznie. Dzięki temu można szybciej uruchamiać i uruchamiać ponownie. Nie czeka już na ponowne skompilowanie aplikacji klienckiej za każdym razem interfejsu wiersza polecenia platformy Angular.

Po uruchomieniu serwera proxy docelowy adres URL i port są wnioskowane ze zmiennych środowiskowych ustawionych przez platformę .NET ASPNETCORE_URLS i ASPNETCORE_HTTPS_PORTS. Aby ustawić adresy URL lub port HTTPS, użyj jednej ze zmiennych środowiskowych lub zmień wartość w pliku proxy.conf.json.

Konfigurowanie oprogramowania pośredniczącego serwera proxy dla programu SignalR

Aby uzyskać więcej informacji, zobacz http-proxy-middleware.

Dodatkowe zasoby

Zaktualizowany szablon projektu Angular zapewnia wygodny punkt wyjścia dla aplikacji ASP.NET Core korzystających z platformy Angular i interfejsu wiersza polecenia platformy Angular w celu zaimplementowania rozbudowanego interfejsu użytkownika po stronie klienta.

Szablon jest odpowiednikiem tworzenia projektu ASP.NET Core w celu działania jako zaplecza interfejsu API i projektu interfejsu wiersza polecenia platformy Angular do działania jako interfejs użytkownika. Szablon oferuje wygodę hostowania obu typów projektów w jednym projekcie aplikacji. W związku z tym projekt aplikacji można skompilować i opublikować jako pojedynczą jednostkę.

Utwórz nową aplikację

Utwórz nowy projekt z poziomu wiersza polecenia przy użyciu polecenia dotnet new angular w pustym katalogu. Na przykład następujące polecenia tworzą aplikację w my-new-app katalogu i przełączają się do tego katalogu:

dotnet new angular -o my-new-app
cd my-new-app

Uruchom aplikację z poziomu programu Visual Studio lub interfejsu wiersza polecenia platformy .NET:

Otwórz wygenerowany .csproj plik i uruchom aplikację normalnie.

Proces kompilacji przywraca zależności npm przy pierwszym uruchomieniu, co może potrwać kilka minut. Kolejne kompilacje są znacznie szybsze.

Szablon projektu tworzy aplikację ASP.NET Core i aplikację Angular. Aplikacja ASP.NET Core ma być używana do uzyskiwania dostępu do danych, autoryzacji i innych problemów po stronie serwera. Aplikacja Angular, która znajduje się w podkatalogu ClientApp , ma być używana we wszystkich problemach interfejsu użytkownika.

Dodawanie stron, obrazów, stylów i modułów

Katalog ClientApp zawiera standardową aplikację interfejsu wiersza polecenia platformy Angular. Aby uzyskać więcej informacji, zobacz oficjalną dokumentację platformy Angular.

Istnieją niewielkie różnice między aplikacją Angular utworzoną przez ten szablon a aplikacją utworzoną przez sam interfejs wiersza polecenia platformy Angular (za pośrednictwem ng newmetody ); jednak możliwości aplikacji pozostają niezmienione. Aplikacja utworzona przez szablon zawiera układ oparty na platformie Bootstrap i podstawowy przykład routingu.

Uruchamianie poleceń ng

W wierszu polecenia przejdź do podkatalogu ClientApp :

cd ClientApp

Jeśli narzędzie jest ng zainstalowane globalnie, możesz uruchomić dowolne z jego poleceń. Można na przykład uruchomić ng lintpolecenie , ng testlub dowolne z innych poleceń interfejsu wiersza polecenia platformy Angular. Nie ma jednak potrzeby uruchamiania ng serve , ponieważ aplikacja ASP.NET Core obsługuje zarówno części po stronie serwera, jak i po stronie klienta aplikacji. Wewnętrznie używa ng serve go w programowania.

Jeśli nie masz zainstalowanego ng narzędzia, uruchom zamiast tego polecenie npm run ng . Można na przykład uruchomić npm run ng lint polecenie lub npm run ng test.

Instalowanie pakietów npm

Aby zainstalować pakiety npm innych firm, użyj wiersza polecenia w podkatalogu ClientApp . Na przykład:

cd ClientApp
npm install --save <package_name>

Publikowanie i wdrażanie

W programowania aplikacja działa w trybie zoptymalizowanym pod kątem wygody deweloperów. Na przykład pakiety języka JavaScript zawierają mapy źródłowe (dzięki czemu podczas debugowania można zobaczyć oryginalny kod TypeScript). Aplikacja obserwuje zmiany w plikach TypeScript, HTML i CSS na dysku oraz automatycznie ponownie skompilują i załadują ponownie, gdy te pliki się zmieniają.

W środowisku produkcyjnym należy obsługiwać wersję aplikacji zoptymalizowaną pod kątem wydajności. Ta konfiguracja jest konfigurowana automatycznie. Podczas publikowania konfiguracja kompilacji emituje z wyprzedzeniem skompilowana kompilacja kodu po stronie klienta. W przeciwieństwie do kompilacji programistycznej kompilacja produkcyjna nie wymaga środowiska Node.js być zainstalowane na serwerze (chyba że włączono renderowanie po stronie serwera (SSR)).

Można użyć standardowych metod hostingu i wdrażania ASP.NET Core.

Uruchom polecenie "ng serve" niezależnie

Projekt jest skonfigurowany do uruchamiania własnego wystąpienia serwera interfejsu wiersza polecenia platformy Angular w tle, gdy aplikacja ASP.NET Core uruchamia się w trybie programowania. Jest to wygodne, ponieważ nie trzeba ręcznie uruchamiać oddzielnego serwera.

Ta domyślna konfiguracja ma wadę. Za każdym razem, gdy zmodyfikujesz kod języka C#, a aplikacja ASP.NET Core musi ponownie uruchomić serwer interfejsu wiersza polecenia platformy Angular. Do uruchomienia kopii zapasowej wymagane jest około 10 sekund. Jeśli często dokonujesz edycji kodu w języku C# i nie chcesz czekać na ponowne uruchomienie interfejsu wiersza polecenia platformy Angular, uruchom serwer interfejsu wiersza polecenia platformy Angular zewnętrznie, niezależnie od procesu ASP.NET Core. Aby to zrobić:

  1. W wierszu polecenia przejdź do podkatalogu ClientApp i uruchom serwer deweloperów interfejsu wiersza polecenia platformy Angular:

    cd ClientApp
npm start

    Ważne

    Użyj npm start polecenia , aby uruchomić serwer dewelopera interfejsu wiersza polecenia platformy Angular, a nie ng serve, aby konfiguracja była package.json przestrzegana. Aby przekazać dodatkowe parametry do serwera interfejsu wiersza polecenia platformy Angular, dodaj je do odpowiedniego scripts wiersza w package.json pliku.

  2. Zmodyfikuj aplikację ASP.NET Core, aby używać zewnętrznego wystąpienia interfejsu wiersza polecenia platformy Angular zamiast uruchamiać własne. W klasie Startup zastąp spa.UseAngularCliServer wywołanie następującym kodem:

    spa.UseProxyToSpaDevelopmentServer("http://localhost:4200");

Po uruchomieniu aplikacji ASP.NET Core nie zostanie uruchomiony serwer interfejsu wiersza polecenia platformy Angular. Zamiast tego używane jest wystąpienie, które zostało uruchomione ręcznie. Dzięki temu można szybciej uruchamiać i uruchamiać ponownie. Nie czeka już na ponowne skompilowanie aplikacji klienckiej za każdym razem interfejsu wiersza polecenia platformy Angular.

Po uruchomieniu serwera proxy docelowy adres URL i port są wnioskowane ze zmiennych środowiskowych ustawionych przez platformę .NET ASPNETCORE_URLS i ASPNETCORE_HTTPS_PORTS. Aby ustawić adresy URL lub port HTTPS, użyj jednej ze zmiennych środowiskowych lub zmień wartość w pliku proxy.conf.json.

Przekazywanie danych z kodu platformy .NET do kodu TypeScript

Podczas usługi SSR możesz przekazać dane poszczególnych żądań z aplikacji ASP.NET Core do aplikacji Angular. Można na przykład przekazać cookie informacje lub coś odczytanego z bazy danych. W tym celu zmodyfikuj klasę Startup . W wywołaniu zwrotnym dla UseSpaPrerenderingparametru ustaw wartość, options.SupplyData na przykład następujące:

options.SupplyData = (context, data) =>
{
    // Creates a new value called isHttpsRequest that's passed to TypeScript code
    data["isHttpsRequest"] = context.Request.IsHttps;
};

Wywołanie SupplyData zwrotne umożliwia przekazywanie dowolnych, per-request, danych z możliwością serializacji JSON (na przykład ciągów, wartości logicznych lub liczb). Kod main.server.ts otrzymuje ten kod jako params.data. Na przykład powyższy przykładowy kod przekazuje wartość logiczną jako params.data.isHttpsRequest do wywołania zwrotnego createServerRenderer . Tę funkcję można przekazać do innych części aplikacji w dowolny sposób obsługiwany przez usługę Angular. Zobacz na przykład, jak main.server.ts przekazuje BASE_URL wartość do dowolnego składnika, którego konstruktor jest zadeklarowany do odbierania.

Wady usługi SSR

Nie wszystkie aplikacje korzystają z usługi SSR. Główną korzyścią jest postrzegana wydajność. Osoby odwiedzające aplikację za pośrednictwem powolnego połączenia sieciowego lub na powolnych urządzeniach przenośnych szybko zobaczą początkowy interfejs użytkownika, nawet jeśli pobieranie lub analizowanie pakietów języka JavaScript zajmuje trochę czasu. Jednak wiele umów SPA jest używanych głównie w szybkich, wewnętrznych sieci firmowych na szybkich komputerach, na których aplikacja pojawia się niemal natychmiast.

Jednocześnie istnieją znaczące wady włączania funkcji SSR. Zwiększa to złożoność procesu programowania. Kod musi działać w dwóch różnych środowiskach: po stronie klienta i po stronie serwera (w środowisku Node.js wywoływanym z ASP.NET Core). Oto kilka rzeczy, które należy wziąć pod uwagę:

  • Usługa SSR wymaga węzła.js instalacja na serwerach produkcyjnych. Dzieje się tak automatycznie w przypadku niektórych scenariuszy wdrażania, takich jak usługi aplikacja systemu Azure, ale nie w przypadku innych, takich jak Usługa Azure Service Fabric.
  • Włączenie flagi BuildServerSideRenderer kompilacji powoduje opublikowanie katalogu node_modules . Ten folder zawiera 20 000 plików i więcej, co zwiększa czas wdrażania.
  • Aby uruchomić kod w węźle.js środowisko nie może polegać na istnieniu interfejsów API języka JavaScript specyficznych dla przeglądarki, takich jak window lub localStorage. Jeśli kod (lub odwołanie do biblioteki innej firmy) próbuje użyć tych interfejsów API, wystąpi błąd podczas wykonywania instrukcji SSR. Na przykład nie używaj trybu jQuery, ponieważ odwołuje się do interfejsów API specyficznych dla przeglądarki w wielu miejscach. Aby zapobiec błędom, należy unikać funkcji SSR lub unikać interfejsów API lub bibliotek specyficznych dla przeglądarki. Możesz opakowować wszystkie wywołania do takich interfejsów API w sprawdzaniu, aby upewnić się, że nie są wywoływane podczas usługi SSR. Na przykład użyj sprawdzania, takiego jak w kodzie JavaScript lub TypeScript:
if (typeof window !== 'undefined') {
    // Call browser-specific APIs here
}

Konfigurowanie oprogramowania pośredniczącego serwera proxy dla programu SignalR

Aby uzyskać więcej informacji, zobacz http-proxy-middleware.

Dodatkowe zasoby