Поделиться через

Использование шаблона проекта Angular с ASP.NET Core

  • Статья

Примечание.

Это не последняя версия этой статьи. В текущем выпуске см . версию .NET 9 этой статьи.

Предупреждение

Эта версия ASP.NET Core больше не поддерживается. Дополнительные сведения см. в статье о политике поддержки .NET и .NET Core. В текущем выпуске см . версию .NET 8 этой статьи.

Внимание

Эта информация относится к предварительному выпуску продукта, который может быть существенно изменен до его коммерческого выпуска. Майкрософт не предоставляет никаких гарантий, явных или подразумеваемых, относительно приведенных здесь сведений.

В текущем выпуске см . версию .NET 9 этой статьи.

Visual Studio предоставляет шаблоны проектов для создания одностраничных приложений (SPAs) на основе платформ JavaScript, таких как Angular, React и Vue с серверной частью ASP.NET Core. Эти шаблоны:

  • Создайте решение Visual Studio с интерфейсным проектом и серверным проектом.
  • Используйте тип проекта Visual Studio для JavaScript и TypeScript (esproj) для внешнего интерфейса.
  • Используйте проект ASP.NET Core для серверной части.

Проекты, созданные с помощью шаблонов Visual Studio, можно запускать из командной строки в Windows, Linux и macOS. Чтобы запустить приложение, используйте dotnet run --launch-profile https для запуска проекта сервера. Запуск проекта сервера автоматически запускает внешний сервер разработки JavaScript. Сейчас https требуется профиль запуска.

Руководство по Visual Studio

Чтобы приступить к работе с проектом Angular, следуйте инструкциям в руководстве по созданию приложения ASP.NET Core с помощью Angular в документации по Visual Studio.

Дополнительные сведения см. в статье JavaScript и TypeScript в Visual Studio

ASP.NET основные шаблоны SPA

Visual Studio включает шаблоны для создания приложений ASP.NET Core с интерфейсом JavaScript или TypeScript. Эти шаблоны доступны в Visual Studio 2022 версии 17.8 или более поздней версии с установленной рабочей нагрузкой ASP.NET и веб-разработки .

Шаблоны Visual Studio для создания приложений ASP.NET Core с интерфейсом JavaScript или TypeScript предоставляют следующие преимущества:

  • Очистка разделения проектов для внешнего интерфейса и серверной части.
  • Будьте в курсе последних версий интерфейсной платформы.
  • Интеграция с новейшими средствами командной строки интерфейсной платформы, такими как Vite.
  • Шаблоны для JavaScript и TypeScript (только TypeScript для Angular).
  • Расширенные возможности редактирования кода JavaScript и TypeScript.
  • Интеграция средств сборки JavaScript с сборкой .NET.
  • Пользовательский интерфейс управления зависимостями npm.
  • Совместим с отладкой и запуском Visual Studio Code.
  • Запустите интерфейсные модульные тесты в обозревателе тестов с помощью платформ тестирования JavaScript.

Устаревшие шаблоны spa ASP.NET Core

В более ранних версиях пакета SDK для .NET добавлены устаревшие шаблоны для создания приложений SPA с ASP.NET Core. Документация по этим старым шаблонам см. в статье ASP.NET Core 7.0 обзора SPA и статьи Angular и React .

ASP.NET Core с шаблоном проекта Angular служит удобной отправной точкой для создания приложений ASP.NET Core с использованием Angular и Angular CLI, позволяющих реализовать многофункциональный пользовательский интерфейс на стороне клиента.

Шаблон проекта является эквивалентом созданию проекта ASP.NET Core в качестве веб-API и проекта Angular CLI в качестве пользовательского интерфейса. Это позволяет легко разместить оба проекта в одном проекте ASP.NET Core, который можно создать и опубликовать как единое целое.

Шаблон проекта не предназначен для серверной обработки.

Создание нового приложения

Создайте из командной строки новый проект в пустом каталоге с помощью команды dotnet new angular. Например, следующие команды создают приложение в каталоге my-new-app и переключаются в этот каталог:

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

Запустите приложение из Visual Studio или .NET CLI:

Откройте созданный .csproj файл и запустите приложение как обычно.

В процессе сборки при первом запуске восстанавливаются зависимости npm. Это может занять несколько минут. Использование последующих сборок может сэкономить много времени.

Шаблон проекта создает приложение ASP.NET Core и приложение Angular. Приложение ASP.NET Core выполняет такие функции, как получение доступа к данным, авторизация и другие процессы на стороне сервера. Приложение Angular, размещенное в ClientApp подкаталоге, предназначено для всех проблем пользовательского интерфейса.

Добавление страниц, изображений, стилей и модулей

Каталог ClientApp содержит стандартное приложение Angular CLI. дополнительные сведения в официальной документации Angular.

Существуют небольшие различия между приложениями Angular, создаваемыми этим шаблоном и создаваемыми непосредственно Angular CLI (командой ng new), однако возможности приложений одинаковые. Приложение, созданное с помощью шаблона, содержит основанный на Bootstrap макет и простой пример маршрутизации.

Выполнение команд ng

В командной строке переключитесь в ClientApp подкаталог:

cd ClientApp

Если средство ng установлено глобально, вы можете запустить любую из его команд. Например, можно запустить ng lint, ng test или любую другую команду Angular CLI. Выполнять ng serve не требуется, так как приложения ASP.NET Core обслуживают как серверную, так и клиентскую части приложения. На внутреннем уровне они используют ng serve в процессе разработки.

Если у вас не установлено средство ng, запустите вместо него npm run ng. Например, можно запустить npm run ng lint или npm run ng test.

Установка пакетов npm

Чтобы установить сторонние пакеты npm, используйте командную строку в подкаталоге ClientApp . Например:

cd ClientApp
npm install <package_name>

Публикация и развертывание

В процессе разработки работа приложения оптимизируется для удобства разработчиков. Например, пакеты JavaScript включают сопоставления с исходным кодом (благодаря чему при отладке вы сможете видеть исходный код TypeScript). Приложение следит за изменениями файлов TypeScript, HTML и CSS на диске и при обнаружении изменений автоматически производит перекомпиляцию и перезагрузку страницы.

На рабочем этапе используйте версию приложения, оптимизированную для производительности. На нее уже настроено автоматическое переключение. При публикации конфигурация сборки выдает уменьшенные, предварительно скомпилированные (AoT) сборки клиентского кода. В отличие от сборки разработки, для рабочей сборки не требуется узел.js для установки на сервере (если вы не включили отрисовку на стороне сервера (SSR)).

Можно использовать стандартные методы размещения и развертывания ASP.NET Core.

Запуск "ng serve" отдельно

Проект настроен запускать свой собственный экземпляр сервера Angular CLI в фоновом режиме, когда приложение ASP.NET Core запускается в режиме разработки. Это удобно, так как нет необходимости вручную запускать отдельный сервер.

Но у этого стандартного режима есть важный недостаток. Каждый раз при изменении кода на C# и необходимости перезапустить приложение ASP.NET Core также перезагружается и сервер Angular CLI. Перезапуск может занять около 10 секунд. Если вы часто вносите изменения в код C# и не хотите ждать перезапуска сервера Angular CLI, запустите сервер Angular CLI отдельно, независимо от процесса ASP.NET Core.

Чтобы отдельно запустить сервер Angular CLI, переключитесь на подкаталог ClientApp в командной строке и запустите сервер разработки Angular CLI:

cd ClientApp
npm start

При запуске приложения ASP.NET Core экземпляр сервера Angular CLI запускаться не будет. Вместо него будет использоваться экземпляр, запускаемый вручную. Это позволит быстрее запускать и перезапускать приложение. Теперь не придется каждый раз дожидаться повторной сборки клиентского приложения в Angular CLI.

При запуске прокси-сервера целевой URL-адрес и порт выводятся из переменных среды, заданных .NET, ASPNETCORE_URLS и ASPNETCORE_HTTPS_PORTS. Чтобы задать URL-адреса или порт HTTPS, используйте одну из переменных среды или измените значение в proxy.conf.json.

Настройка промежуточного слоя прокси-сервера для SignalR

Дополнительные сведения см. по адресу http-proxy-middleware.

Дополнительные ресурсы

Обновленный шаблон проекта Angular обеспечивает удобную отправную точку для приложений ASP.NET Core с использованием Angular и Angular CLI для реализации богатого пользовательского интерфейса (UI) на стороне клиента.

Шаблон является эквивалентом созданию проекта ASP.NET Core, выступающего в качестве серверного API, и проекта Angular CLI в качестве пользовательского интерфейса. В шаблоне предлагается удобное размещения обоих типов проектов в проекте отдельного приложения. Что в свою очередь позволит создать и опубликовать проект приложения как единое целое.

Создание нового приложения

Создайте из командной строки новый проект в пустом каталоге с помощью команды dotnet new angular. Например, следующие команды создают приложение в каталоге my-new-app и переключаются в этот каталог:

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

Запустите приложение из Visual Studio или .NET CLI:

Откройте созданный .csproj файл и запустите приложение как обычно.

В процессе сборки при первом запуске восстанавливаются зависимости npm. Это может занять несколько минут. Использование последующих сборок может сэкономить много времени.

Шаблон проекта создает приложение ASP.NET Core и приложение Angular. Приложение ASP.NET Core выполняет такие функции, как получение доступа к данным, авторизация и другие процессы на стороне сервера. Приложение Angular, размещенное в ClientApp подкаталоге, предназначено для всех проблем пользовательского интерфейса.

Добавление страниц, изображений, стилей и модулей

Каталог ClientApp содержит стандартное приложение Angular CLI. дополнительные сведения в официальной документации Angular.

Существуют небольшие различия между приложениями Angular, создаваемыми этим шаблоном и создаваемыми непосредственно Angular CLI (командой ng new), однако возможности приложений одинаковые. Приложение, созданное с помощью шаблона, содержит основанный на Bootstrap макет и простой пример маршрутизации.

Выполнение команд ng

В командной строке переключитесь в ClientApp подкаталог:

cd ClientApp

Если средство ng установлено глобально, вы можете запустить любую из его команд. Например, можно запустить ng lint, ng test или любую другую команду Angular CLI. Выполнять ng serve не требуется, так как приложения ASP.NET Core обслуживают как серверную, так и клиентскую части приложения. На внутреннем уровне они используют ng serve в процессе разработки.

Если у вас не установлено средство ng, запустите вместо него npm run ng. Например, можно запустить npm run ng lint или npm run ng test.

Установка пакетов npm

Чтобы установить сторонние пакеты npm, используйте командную строку в подкаталоге ClientApp . Например:

cd ClientApp
npm install --save <package_name>

Публикация и развертывание

В процессе разработки работа приложения оптимизируется для удобства разработчиков. Например, пакеты JavaScript включают сопоставления с исходным кодом (благодаря чему при отладке вы сможете видеть исходный код TypeScript). Приложение следит за изменениями файлов TypeScript, HTML и CSS на диске и при обнаружении изменений автоматически производит перекомпиляцию и перезагрузку страницы.

На рабочем этапе используйте версию приложения, оптимизированную для производительности. На нее уже настроено автоматическое переключение. При публикации конфигурация сборки выдает уменьшенные, предварительно скомпилированные (AoT) сборки клиентского кода. В отличие от сборки разработки, для рабочей сборки не требуется узел.js для установки на сервере (если вы не включили отрисовку на стороне сервера (SSR)).

Можно использовать стандартные методы размещения и развертывания ASP.NET Core.

Запуск "ng serve" отдельно

Проект настроен запускать свой собственный экземпляр сервера Angular CLI в фоновом режиме, когда приложение ASP.NET Core запускается в режиме разработки. Это удобно, так как нет необходимости вручную запускать отдельный сервер.

Но у этого стандартного режима есть важный недостаток. Каждый раз при изменении кода на C# и необходимости перезапустить приложение ASP.NET Core также перезагружается и сервер Angular CLI. Перезапуск может занять около 10 секунд. Если вы часто вносите изменения в код C# и не хотите ждать перезапуска сервера Angular CLI, запустите сервер Angular CLI отдельно, независимо от процесса ASP.NET Core. Для этого:

  1. В командной строке перейдите в ClientApp подкаталог и запустите сервер разработки Angular CLI:

    cd ClientApp
npm start

    Внимание

    Используйте npm start, а не ng serve для запуска сервера разработки Angular CLI, в результате чего будет учитываться конфигурация в файле package.json. Чтобы передать серверу Angular CLI дополнительные параметры, добавьте их в package.json в нужную строку scripts.

  2. Измените свои приложения ASP.NET Core так, чтобы они использовали внешний экземпляр сервера Angular CLI, а не запускали собственный. В классе Startup замените вызов spa.UseAngularCliServer следующим кодом:

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

При запуске приложения ASP.NET Core экземпляр сервера Angular CLI запускаться не будет. Вместо него будет использоваться экземпляр, запускаемый вручную. Это позволит быстрее запускать и перезапускать приложение. Теперь не придется каждый раз дожидаться повторной сборки клиентского приложения в Angular CLI.

При запуске прокси-сервера целевой URL-адрес и порт выводятся из переменных среды, заданных .NET, ASPNETCORE_URLS и ASPNETCORE_HTTPS_PORTS. Чтобы задать URL-адреса или порт HTTPS, используйте одну из переменных среды или измените значение в proxy.conf.json.

Передача данных от .NET к TypeScript

Во время работы SSR может возникнуть необходимость передать данные отдельных запросов из ASP.NET Core в Angular. Например, можно передать сведения из файла cookie или данные, полученные из базы данных. Чтобы это сделать, необходимо внести изменения в класс Startup. В обратном вызове UseSpaPrerendering для options.SupplyData установите указанное ниже значение.

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

С помощью обратного вызова SupplyData можно передавать произвольные данные, отдельные запросы, а также JSON-сериализируемые данные (например, строки, логические значения или числа). Для кода в файле main.server.ts эти данные будут получены в качестве params.data. Например, в предыдущем примере кода логическое значение передается как params.data.isHttpsRequest в обратный вызов createServerRenderer. Также эти данные можно передавать другим частям приложения любым способом, поддерживаемым Angular. Например, ознакомьтесь с тем, как main.server.ts передает значение BASE_URL любому компоненту, конструктор которого объявлен получателем.

Недостатки SSR

Не все приложения получают преимущество от использования SSR. Основное преимущество — воспринимаемая производительность. При использовании вашего приложения посетители, у которых низкая скорость сетевого подключения или медленные мобильные устройства, быстро обнаруживают первоначальный пользовательский интерфейс, даже если для получения или анализа пакетов JavaScript требуется некоторое время. Тем не менее в основном многие одностраничные приложения (SPA) используются в быстрых внутренних сетях компании на быстрых компьютерах, где приложение появляется почти мгновенно.

В тоже время при использовании SSR существует ряд недостатков. В процесс разработки вносится дополнительная сложность. Код должен выполняться в двух разных средах: на стороне клиента и на стороне сервера (в узле.js Среда, вызываемая из ASP.NET Core). Ниже приведены некоторые аспекты, которые необходимо учитывать.

  • Для SSR требуется узел.js установка на рабочих серверах. В некоторых сценариях это происходит автоматически (например, службы приложений Azure), а в других — нет (например, Azure Service Fabric).
  • Установка флага сборки BuildServerSideRenderer приведет к публикации каталога node_modules. В этой папке находятся более 20 000 файлов, что повлечет за собой увеличение времени развертывания.
  • Выполнение кода на узле.js среда не может полагаться на существование api JavaScript для конкретного браузера, window например или localStorage. Если во время выполнения SSR для кода (или некоторых используемых библиотек сторонних разработчиков) будут использованы эти API, выполнение SSR завершится сбоем. Например, не используйте jQuery, так как часто он использует на браузерные API. Чтобы предотвратить возникновение ошибки, необходимо избегать использовать SSR или браузерных API-интерфейсов и библиотек. Любые вызовы могут быть перенесены в проверки API, чтобы гарантировать, что они не будут вызваны во время SSR. Например, в коде JavaScript или TypeScript можно использовать следующую проверку:
if (typeof window !== 'undefined') {
    // Call browser-specific APIs here
}

Настройка промежуточного слоя прокси-сервера для SignalR

Дополнительные сведения см. по адресу http-proxy-middleware.

Дополнительные ресурсы