Usar o modelo de projeto Angular com ASP.NET Core

O Visual Studio fornece modelos de projeto para criar aplicativos de página única (SPAs) com base em tecnologias JavaScript, como Angular, React e Vue , que têm um back-end ASP.NET Core. Estes modelos:

• Crie uma solução do Visual Studio com um projeto de frontend e um projeto de back-end.
• Use o tipo de projeto Visual Studio para JavaScript e TypeScript (.esproj) para o frontend.
• Use um projeto ASP.NET Core para o back-end.

Os projetos criados usando os modelos do Visual Studio podem ser executados a partir da linha de comando no Windows, Linux e macOS. Para executar o aplicativo, use dotnet run --launch-profile https para executar o projeto de servidor. A execução do projeto de servidor inicia automaticamente o servidor de desenvolvimento JavaScript frontend. O perfil de lançamento https é necessário atualmente.

Tutorial do Visual Studio

Para começar com um projeto Angular, siga o tutorial Criar um aplicativo ASP.NET Core com Angular na documentação do Visual Studio.

Para obter mais informações, consulte JavaScript e TypeScript no Visual Studio

ASP.NET Modelos de SPA principais

O Visual Studio inclui modelos para criar aplicativos ASP.NET Core com um front-end JavaScript ou TypeScript. Esses modelos estão disponíveis no Visual Studio 2022 versão 17.8 ou posterior com a carga de trabalho de desenvolvimento ASP.NET e Web instalada.

Os modelos do Visual Studio para criar aplicativos ASP.NET Core com um frontend JavaScript ou TypeScript oferecem os seguintes benefícios:

• Separação limpa do projeto entre o frontend e o backend.
• Mantenha-se up-toatualizado com as versões mais recentes do framework frontend.
• Integre com as mais recentes ferramentas de linha de comando do frontend framework, como o Vite.
• Modelos para JavaScript e TypeScript (apenas TypeScript para Angular).
• Rica experiência de edição de código JavaScript e TypeScript.
• Integre ferramentas de compilação JavaScript com a compilação .NET.
• Interface do usuário de gestão de dependências do npm.
• Compatível com depuração de código do Visual Studio e configuração de inicialização.
• Execute testes de unidade frontend no Test Explorer usando estruturas de teste JavaScript.

Modelos de SPA ASP.NET Core herdados

As versões anteriores do SDK do .NET incluíam o que agora são modelos herdados para criar aplicativos SPA com o ASP.NET Core. Para obter documentação sobre esses modelos mais antigos, consulte a versão .NET 7 da visão geral do SPA e os artigos Angular e React .

O modelo de projeto ASP.NET Core com Angular fornece um ponto de partida conveniente para aplicativos ASP.NET Core usando o Angular e a CLI Angular implementarem uma interface do usuário (UI) avançada do lado do cliente.

O modelo de projeto é equivalente à criação de um projeto ASP.NET Core para atuar como uma API da Web e um projeto Angular CLI para atuar como uma interface do usuário. Esta combinação de projetos oferece a conveniência de hospedar ambos os projetos em um único projeto ASP.NET Core que pode ser construído e publicado como uma única unidade.

O modelo de projeto não se destina à renderização do lado do servidor (SSR).

Criar uma nova aplicação

Crie um novo projeto a partir de um prompt de comando usando o comando dotnet new angular em um diretório vazio. Por exemplo, os comandos a seguir criam o aplicativo em um my-new-app diretório e alternam para esse diretório:

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

Execute o aplicativo do Visual Studio ou da CLI do .NET:

O modelo de projeto cria um aplicativo ASP.NET Core e um aplicativo Angular. O aplicativo ASP.NET Core destina-se a ser usado para acesso a dados, autorização e outras preocupações do lado do servidor. O aplicativo Angular, que reside no ClientApp subdiretório, destina-se a ser usado para todas as questões relacionadas à interface do utilizador.

Adicionar páginas, imagens, estilos e módulos

O ClientApp diretório contém um aplicativo Angular CLI padrão. Consulte a documentação oficial do Angular para obter mais informações.

Existem pequenas diferenças entre o aplicativo Angular criado por este modelo e o criado pela própria CLI Angular (via ng new), no entanto, os recursos do aplicativo permanecem inalterados. O aplicativo criado pelo modelo contém um layout baseado em Bootstrap e um exemplo de roteamento básico.

Executar comandos ng

Em um prompt de comando, mude para o ClientApp subdiretório:

cd ClientApp

Se você tiver a ng ferramenta instalada globalmente, poderá executar qualquer um de seus comandos. Por exemplo, você pode executar ng lint, ng testou qualquer um dos outros comandos da CLI Angular. No entanto, não há necessidade de executar ng serve porque seu aplicativo ASP.NET Core lida com o atendimento de partes do lado do servidor e do lado do cliente do seu aplicativo. Internamente, usa ng serve no desenvolvimento.

Se você não tiver a ng ferramenta instalada, execute npm run ng em vez disso. Por exemplo, você pode executar npm run ng lint ou npm run ng test.

Instalar pacotes npm

Para instalar pacotes npm de terceiros, use um prompt de comando no ClientApp subdiretório. Por exemplo:

cd ClientApp
npm install <package_name>

Publicar e implantar

No desenvolvimento, o aplicativo é executado em um modo otimizado para conveniência do desenvolvedor. Por exemplo, os pacotes JavaScript incluem mapas de origem (para que, ao depurar, você possa ver seu código TypeScript original). O aplicativo observa as alterações nos arquivos TypeScript, HTML e CSS no disco e recompila e recarrega automaticamente quando vê esses arquivos serem alterados.

Na produção, forneça uma versão do seu aplicativo otimizada para desempenho. Isso é configurado para acontecer automaticamente. Quando publica, a configuração de compilação emite uma build minimizada e compilada antecipadamente (AoT) do seu código do lado do cliente. Ao contrário da compilação de desenvolvimento, a compilação de produção não requer Node.js seja instalada no servidor (a menos que você tenha habilitado a renderização do lado do servidor (SSR)).

Você pode usar métodos padrão de hospedagem e implantação do ASP.NET Core.

Execute "ng serve" de forma independente

O projeto é configurado para iniciar sua própria instância do servidor CLI Angular em segundo plano quando o aplicativo ASP.NET Core é iniciado no modo de desenvolvimento. Isso é conveniente porque você não precisa executar um servidor separado manualmente.

Há uma desvantagem nessa configuração padrão. Sempre que você modificar seu código C# e seu aplicativo ASP.NET Core precisar ser reiniciado, o servidor CLI Angular será reiniciado. Cerca de 10 segundos são necessários para iniciar o backup. Se você estiver fazendo edições frequentes de código C# e não quiser esperar a reinicialização da CLI Angular, execute o servidor da CLI Angular externamente, independentemente do processo ASP.NET Core.

Para executar o servidor Angular CLI externamente, alterne para o ClientApp subdiretório em um prompt de comando e inicie o servidor de desenvolvimento Angular CLI:

cd ClientApp
npm start

Quando você inicia seu aplicativo ASP.NET Core, ele não inicia um servidor CLI Angular. Em vez disso, a instância iniciada manualmente é usada. Isso permite que ele inicie e reinicie mais rapidamente. Já não precisa esperar que o Angular CLI reconstrua a sua aplicação cliente sempre que necessário.

Quando o proxy é iniciado, a URL de destino e a porta são inferidas a partir das variáveis de ambiente sendo definidas pelo .NET, ASPNETCORE_URLS e ASPNETCORE_HTTPS_PORTS. Para definir a porta URLs ou HTTPS, use uma das variáveis de ambiente ou altere o valor em proxy.conf.json.

Configurar middleware de proxy para SignalR

Para obter mais informações, consulte http-proxy-middleware.

Recursos adicionais

• Use Identity para proteger um back-end de API da Web para SPAs

O modelo de projeto Angular atualizado fornece um ponto de partida conveniente para aplicativos ASP.NET Core que usam o Angular e a CLI Angular implementarem uma interface do usuário (UI) avançada do lado do cliente.

O modelo é equivalente à criação de um projeto ASP.NET Core para atuar como um back-end de API e um projeto Angular CLI para atuar como uma interface do usuário. O modelo oferece a conveniência de hospedar ambos os tipos de projeto em um único projeto de aplicativo. Consequentemente, o projeto de aplicativo pode ser criado e publicado como uma única unidade.

Criar uma nova aplicação

Crie um novo projeto a partir de um prompt de comando usando o comando dotnet new angular em um diretório vazio. Por exemplo, os comandos a seguir criam o aplicativo em um my-new-app diretório e alternam para esse diretório:

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

Execute o aplicativo do Visual Studio ou da CLI do .NET:

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

O modelo de projeto cria um aplicativo ASP.NET Core e um aplicativo Angular. O aplicativo ASP.NET Core destina-se a ser usado para acesso a dados, autorização e outras preocupações do lado do servidor. O aplicativo Angular, que reside no ClientApp subdiretório, destina-se a ser usado para todas as questões relacionadas à interface do utilizador.

Adicionar páginas, imagens, estilos e módulos

O ClientApp diretório contém um aplicativo Angular CLI padrão. Consulte a documentação oficial do Angular para obter mais informações.

Existem pequenas diferenças entre o aplicativo Angular criado por este modelo e o criado pela própria CLI Angular (via ng new), no entanto, os recursos do aplicativo permanecem inalterados. O aplicativo criado pelo modelo contém um layout baseado em Bootstrap e um exemplo de roteamento básico.

Executar comandos ng

Em um prompt de comando, mude para o ClientApp subdiretório:

cd ClientApp

Se você tiver a ng ferramenta instalada globalmente, poderá executar qualquer um de seus comandos. Por exemplo, você pode executar ng lint, ng testou qualquer um dos outros comandos da CLI Angular. No entanto, não há necessidade de executar ng serve porque seu aplicativo ASP.NET Core lida com o atendimento de partes do lado do servidor e do lado do cliente do seu aplicativo. Internamente, usa ng serve no desenvolvimento.

Se você não tiver a ng ferramenta instalada, execute npm run ng em vez disso. Por exemplo, você pode executar npm run ng lint ou npm run ng test.

Instalar pacotes npm

Para instalar pacotes npm de terceiros, use um prompt de comando no ClientApp subdiretório. Por exemplo:

cd ClientApp
npm install --save <package_name>

Publicar e implantar

No desenvolvimento, o aplicativo é executado em um modo otimizado para conveniência do desenvolvedor. Por exemplo, os pacotes JavaScript incluem mapas de origem (para que, ao depurar, você possa ver seu código TypeScript original). O aplicativo observa as alterações nos arquivos TypeScript, HTML e CSS no disco e recompila e recarrega automaticamente quando vê esses arquivos serem alterados.

Na produção, forneça uma versão do seu aplicativo otimizada para desempenho. Isso é configurado para acontecer automaticamente. Quando publica, a configuração de compilação emite uma build minimizada e compilada antecipadamente (AoT) do seu código do lado do cliente. Ao contrário da compilação de desenvolvimento, a compilação de produção não requer Node.js seja instalada no servidor (a menos que você tenha habilitado a renderização do lado do servidor (SSR)).

Você pode usar métodos padrão de hospedagem e implantação do ASP.NET Core.

Execute "ng serve" de forma independente

O projeto é configurado para iniciar sua própria instância do servidor CLI Angular em segundo plano quando o aplicativo ASP.NET Core é iniciado no modo de desenvolvimento. Isso é conveniente porque você não precisa executar um servidor separado manualmente.

Há uma desvantagem nessa configuração padrão. Sempre que você modificar seu código C# e seu aplicativo ASP.NET Core precisar ser reiniciado, o servidor CLI Angular será reiniciado. Cerca de 10 segundos são necessários para iniciar o backup. Se você estiver fazendo edições frequentes de código C# e não quiser esperar a reinicialização da CLI Angular, execute o servidor da CLI Angular externamente, independentemente do processo ASP.NET Core. Para tal:

1. Em um prompt de comando, alterne para o ClientApp subdiretório e inicie o servidor de desenvolvimento da CLI Angular:

   cd ClientApp
   npm start
   

   Importante

   Use npm start para iniciar o servidor de desenvolvimento da CLI Angular, não ng serve, para que a configuração em package.json seja respeitada. Para passar parâmetros adicionais para o servidor CLI Angular, adicione-os à linha relevante scripts em seu package.json arquivo.

2. Modifique seu aplicativo ASP.NET Core para usar a instância externa da CLI Angular em vez de iniciar uma de suas próprias. Na classe Startup , substitua a spa.UseAngularCliServer invocação pelo seguinte:

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

Quando você inicia seu aplicativo ASP.NET Core, ele não inicia um servidor CLI Angular. Em vez disso, a instância iniciada manualmente é usada. Isso permite que ele inicie e reinicie mais rapidamente. Já não precisa esperar que o Angular CLI reconstrua a sua aplicação cliente sempre que necessário.

Quando o proxy é iniciado, a URL de destino e a porta são inferidas a partir das variáveis de ambiente sendo definidas pelo .NET, ASPNETCORE_URLS e ASPNETCORE_HTTPS_PORTS. Para definir a porta URLs ou HTTPS, use uma das variáveis de ambiente ou altere o valor em proxy.conf.json.

Passe dados do código .NET para o código TypeScript

Durante o SSR, talvez você queira passar dados por solicitação do seu aplicativo ASP.NET Core para o aplicativo Angular. Por exemplo, podes passar cookie informação ou algo lido de uma base de dados. Para fazer isso, edite sua classe de inicialização . No retorno de chamada para UseSpaPrerendering, defina um valor para options.SupplyData como o seguinte:

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

O SupplyData callback permite passar dados arbitrários, por solicitação, serializáveis em JSON (por exemplo, strings, booleanos ou números). Seu main.server.ts código recebe isso como params.data. Por exemplo, o exemplo de código anterior passa um valor booleano como params.data.isHttpsRequest para dentro da função de retorno createServerRenderer. Você pode passar isso para outras partes do seu aplicativo de qualquer forma suportada pelo Angular. Por exemplo, veja como main.server.ts passa o valor de BASE_URL para qualquer componente cujo construtor é declarado para recebê-lo.

Desvantagens da RSS

Nem todas as aplicações beneficiam do SSR. O principal benefício é o desempenho percebido. Os visitantes que chegam ao seu aplicativo por meio de uma conexão de rede lenta ou em dispositivos móveis lentos veem a interface do usuário inicial rapidamente, mesmo que demore um pouco para buscar ou analisar os pacotes JavaScript. No entanto, muitos SPAs são usados principalmente em redes internas e rápidas da empresa em computadores rápidos, onde o aplicativo aparece quase instantaneamente.

Ao mesmo tempo, existem inconvenientes significativos em permitir a RSS. Adiciona complexidade ao seu processo de desenvolvimento. Seu código deve ser executado em dois ambientes diferentes: do lado do cliente e do lado do servidor (em um ambiente Node.js invocado a partir do ASP.NET Core). Aqui estão algumas coisas a ter em mente:

• O SSR requer uma instalação Node.js em seus servidores de produção. Esse é automaticamente o caso para alguns cenários de implantação, como os Serviços de Aplicativo do Azure, mas não para outros, como o Azure Service Fabric.
• Ativar o BuildServerSideRenderer sinalizador de compilação faz com que seu diretório node_modules publique. Esta pasta contém 20.000+ arquivos, o que aumenta o tempo de implantação.
• Para executar seu código em um ambiente Node.js, ele não pode confiar na existência de APIs JavaScript específicas do navegador, como window ou localStorage. Se o seu código (ou alguma biblioteca de terceiros que você referenciar) tentar usar essas APIs, você receberá um erro durante o SSR. Por exemplo, não use o jQuery porque ele faz referência a APIs específicas do navegador em muitos lugares. Para prevenir erros, deve optar por não usar SSR ou evitar APIs e bibliotecas específicas do navegador. Você pode encapsular quaisquer chamadas para essas APIs em verificações para garantir que elas não sejam invocadas durante o SSR. Por exemplo, use uma verificação como a seguinte no código JavaScript ou TypeScript:

if (typeof window !== 'undefined') {
    // Call browser-specific APIs here
}

Configurar middleware de proxy para SignalR

Para obter mais informações, consulte http-proxy-middleware.

Recursos adicionais

• Use Identity para proteger um back-end de API da Web para SPAs