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

Статья
11/30/2023

Примечание.

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

Внимание

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

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

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 Core CLI.

Visual Studio
Интерфейс командной строки .NET Core

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

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

Убедитесь, что у вас существует переменная среда ASPNETCORE_ENVIRONMENT, которой соответствует значение Development. Запустите команду SET ASPNETCORE_ENVIRONMENT=Development в ОС Windows (в приглашениях, отличных от PowerShell). В ОС Linux или macOS используйте команду export ASPNETCORE_ENVIRONMENT=Development.

Чтобы проверить наличие ошибок при создании приложения, запустите команду dotnet-build. При первом запуске процесса создания будут восстановлены зависимости npm, на что может потребоваться несколько минут. Использование последующих сборок может сэкономить много времени.

Запустите dotnet run для запуска приложения.

Шаблон проекта создает приложение 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) сборки клиентского кода. В отличие от сборки в режиме разработки, установка на сервере Node.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.

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

Использование Identity для защиты серверной части веб-API для spAs

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

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

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

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

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

Visual Studio
Интерфейс командной строки .NET Core

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

Запустите dotnet run для запуска приложения. Следующее сообщение будет записано в журнал.

Now listening on: http://localhost:<port>

Перейдите по этому URL-адресу в браузере.

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

Приложение запускает экземпляр сервера Angular CLI в фоновом режиме. Будет записано следующее сообщение: сервер разработки NG Live ожидает вызова localhost:<otherport>, откройте браузер на странице http://localhost:<:otherport>/. Это сообщение необходимо проигнорировать. Оно не является URL-адресом объединенного приложения ASP.NET Core и Angular CLI.

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

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

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

cd ClientApp

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

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

cd ClientApp
npm install --save <package_name>

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

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

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

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

Используйте npm start, а не ng serve для запуска сервера разработки Angular CLI, в результате чего будет учитываться конфигурация в файле package.json. Чтобы передать серверу Angular CLI дополнительные параметры, добавьте их в package.json в нужную строку scripts.
Измените свои приложения ASP.NET Core так, чтобы они использовали внешний экземпляр сервера Angular CLI, а не запускали собственный. В классе Startup замените вызов spa.UseAngularCliServer следующим кодом:
```
spa.UseProxyToSpaDevelopmentServer("http://localhost:4200");
```

Передача данных от .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 существует ряд недостатков. В процесс разработки вносится дополнительная сложность. Код должен быть запущен в двух разных средах как на стороне клиента, так и на стороне сервера (в среде Node.js, вызываемой из ASP.NET Core). Ниже приведены некоторые аспекты, которые необходимо учитывать.

Для SSR необходимо, чтобы на рабочих серверах был установлен Node.js. В некоторых сценариях это происходит автоматически (например, службы приложений Azure), а в других — нет (например, Azure Service Fabric).
Установка флага сборки BuildServerSideRenderer приведет к публикации каталога node_modules. В этой папке находятся более 20 000 файлов, что повлечет за собой увеличение времени развертывания.
Для запуска кода в среде Node.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.

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

Использование Identity для защиты серверной части веб-API для spAs

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Недостатки SSR

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

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

Обратная связь

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