Usar o modelo de projeto Angular com o ASP.NET Core

  • Artigo

Observação

Esta não é a versão mais recente deste artigo. Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

Importante

Essas informações relacionam-se ao produto de pré-lançamento, que poderá ser substancialmente modificado antes do lançamento comercial. A Microsoft não oferece nenhuma garantia, explícita ou implícita, quanto às informações fornecidas aqui.

Para informações sobre a versão vigente, confira a Versão do .NET 8 deste artigo.

O Visual Studio fornece modelos de projeto para a criação de SPAs (aplicativos de página única) baseados em estruturas JavaScript, como o Angular, o React e o Vue, que têm um back-end ASP.NET Core. Estes modelos:

  • Criam uma solução do Visual Studio com um projeto de front-end e um projeto de back-end.
  • Usam o tipo de projeto do Visual Studio para JavaScript e TypeScript (.esproj) para o front-end.
  • Usam 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 do servidor. A execução do projeto do servidor inicia automaticamente o servidor de desenvolvimento JavaScript de front-end. O perfil de inicialização https é obrigatório no momento.

Tutorial do Visual Studio

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

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

Modelos ASP.NET Core de SPAs

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

Os modelos do Visual Studio para a criação de aplicativos ASP.NET Core com um front-end JavaScript ou TypeScript oferecem os seguintes benefícios:

  • Separação limpa de projetos para front-end e back-end.
  • Mantenha-se atualizado com as últimas versões da estrutura de front-end.
  • Integre-se às ferramentas mais recentes de linha de comando da estrutura de front-end, como o Vite.
  • Modelos para JavaScript e TypeScript (somente TypeScript para Angular).
  • Experiência sofisticada de edição de códigos JavaScript e TypeScript.
  • Integre as ferramentas de build do JavaScript ao build do .NET.
  • Interface do usuário do gerenciamento de dependências do npm.
  • Compatível com a depuração e a configuração de inicialização do Visual Studio Code.
  • Execute testes de unidade de front-end no Gerenciador de Testes usando estruturas de teste JavaScript.

Modelos ASP.NET Core herdados de SPA

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

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

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

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

Criar um novo aplicativo

Crie um novo projeto de um prompt de comando usando o comando dotnet new angular em um diretório vazio. Por exemplo, os seguintes comandos criam o aplicativo em um diretório my-new-app e mudam 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 Core:

Abra o arquivo .csproj gerado e execute o aplicativo normalmente de lá.

O processo de build restaura dependências npm na primeira execução, o que pode levar vários minutos. Builds subsequentes são muito mais rápidos.

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

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

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

Há pequenas diferenças entre o aplicativo do Angular criado por este modelo e um criado pela CLI do Angular propriamente dita (por meio de ng new); no entanto, os recursos do aplicativo são inalterados. O aplicativo criado pelo modelo contém um layout com base em Bootstrap e um exemplo básico de roteamento.

Executar comandos ng

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

cd ClientApp

Se você tiver a ferramenta ng instalada globalmente, você poderá executar qualquer um dos seus comandos. Por exemplo, você poderá executar ng lint, ng test ou qualquer um dos outros comandos da CLI do Angular. No entanto, não é necessário executar ng serve, porque o seu aplicativo ASP.NET Core dá conta de servir tanto a parte do lado do servidor quanto a do lado do cliente do seu aplicativo. Internamente, ele usa ng serve em desenvolvimento.

Se você não tiver a ferramenta ng instalada, execute npm run ng em vez dela. 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 subdiretório ClientApp. Por exemplo:

cd ClientApp
npm install <package_name>

Publicar e implantar

No desenvolvimento, o aplicativo é executado de um modo otimizado para conveniência do desenvolvedor. Por exemplo, pacotes JavaScript incluem mapas de origem (de modo que durante a depuração, você pode ver o código TypeScript original). O aplicativo observa alterações em arquivos TypeScript, HTML e CSS no disco e recompila e recarrega automaticamente quando as detecta.

Em produção, atende a uma versão de seu aplicativo que é otimizada para desempenho. Isso é configurado para ocorrer automaticamente. Quando você publica, a configuração de build emite um build minificado em compilação AoT (Ahead Of Time) do código do lado do cliente. Diferentemente da compilação de desenvolvimento, a compilação de produção não requer que o Node.js esteja instalado no servidor (a menos que você tenha habilitado a renderização do lado do servidor (RLS)).

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

Executar "ng serve" independentemente

O projeto está configurado para iniciar sua própria instância do servidor da CLI do 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. Cada vez que você modificar seu código C# e o aplicativo ASP.NET Core precisar ser reiniciado, o servidor da CLI do Angular será reiniciado também. São necessários aproximadamente 10 segundos para iniciar um backup. Se você estiver fazendo edições frequentes de código C# e não quiser esperar a CLI do Angular reiniciar, execute o servidor da CLI do Angular externamente, independentemente do processo do ASP.NET Core.

Para executar o servidor da CLI do Angular externamente, vá para o subdiretório ClientApp em um prompt de comando e inicialize o servidor de desenvolvimento da CLI do Angular:

cd ClientApp
npm start

Quando você iniciar seu aplicativo ASP.NET Core, ele não inicializará um servidor da CLI do Angular. Em vez disso, a instância que você iniciou manualmente é usada. Isso permite a ele iniciar e reiniciar mais rapidamente. Ele não está mais aguardando a CLI do Angular recompilar o aplicativo cliente a cada vez.

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

Configurar o middleware de proxy para SignalR

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

Recursos adicionais

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

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

Criar um novo aplicativo

Crie um novo projeto de um prompt de comando usando o comando dotnet new angular em um diretório vazio. Por exemplo, os seguintes comandos criam o aplicativo em um diretório my-new-app e mudam 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 Core:

Abra o arquivo .csproj gerado e execute o aplicativo normalmente de lá.

O processo de build restaura dependências npm na primeira execução, o que pode levar vários minutos. Builds subsequentes são muito mais rápidos.

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

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

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

Há pequenas diferenças entre o aplicativo do Angular criado por este modelo e um criado pela CLI do Angular propriamente dita (por meio de ng new); no entanto, os recursos do aplicativo são inalterados. O aplicativo criado pelo modelo contém um layout com base em Bootstrap e um exemplo básico de roteamento.

Executar comandos ng

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

cd ClientApp

Se você tiver a ferramenta ng instalada globalmente, você poderá executar qualquer um dos seus comandos. Por exemplo, você poderá executar ng lint, ng test ou qualquer um dos outros comandos da CLI do Angular. No entanto, não é necessário executar ng serve, porque o seu aplicativo ASP.NET Core dá conta de servir tanto a parte do lado do servidor quanto a do lado do cliente do seu aplicativo. Internamente, ele usa ng serve em desenvolvimento.

Se você não tiver a ferramenta ng instalada, execute npm run ng em vez dela. 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 subdiretório ClientApp. Por exemplo:

cd ClientApp
npm install --save <package_name>

Publicar e implantar

No desenvolvimento, o aplicativo é executado de um modo otimizado para conveniência do desenvolvedor. Por exemplo, pacotes JavaScript incluem mapas de origem (de modo que durante a depuração, você pode ver o código TypeScript original). O aplicativo observa alterações em arquivos TypeScript, HTML e CSS no disco e recompila e recarrega automaticamente quando as detecta.

Em produção, atende a uma versão de seu aplicativo que é otimizada para desempenho. Isso é configurado para ocorrer automaticamente. Quando você publica, a configuração de build emite um build minificado em compilação AoT (Ahead Of Time) do código do lado do cliente. Diferentemente da compilação de desenvolvimento, a compilação de produção não requer que o Node.js esteja instalado no servidor (a menos que você tenha habilitado a renderização do lado do servidor (RLS)).

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

Executar "ng serve" independentemente

O projeto está configurado para iniciar sua própria instância do servidor da CLI do 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. Cada vez que você modificar seu código C# e o aplicativo ASP.NET Core precisar ser reiniciado, o servidor da CLI do Angular será reiniciado também. São necessários aproximadamente 10 segundos para iniciar um backup. Se você estiver fazendo edições frequentes de código C# e não quiser esperar a CLI do Angular reiniciar, execute o servidor da CLI do Angular externamente, independentemente do processo do ASP.NET Core. Para fazer isso:

  1. Em um prompt de comando, vá para o subdiretório ClientApp e inicie o Development Server da CLI do Angular:

    cd ClientApp
npm start

    Importante

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

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

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

Quando você iniciar seu aplicativo ASP.NET Core, ele não inicializará um servidor da CLI do Angular. Em vez disso, a instância que você iniciou manualmente é usada. Isso permite a ele iniciar e reiniciar mais rapidamente. Ele não está mais aguardando a CLI do Angular recompilar o aplicativo cliente a cada vez.

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

Passar dados de código .NET para código do TypeScript

Durante a SSR, convém passar dados por solicitação, do aplicativo ASP.NET Core para o aplicativo do Angular. Por exemplo, você pode aprovar informações cookie ou algo lido de um banco de dados. Para fazer isso, edite a classe Startup. 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 retorno de chamada de SupplyData permite que você aprove dados serializáveis por JSON arbitrários e por solicitação (por exemplo, cadeias de caracteres, boolianos ou números). Seu código main.server.ts recebe isso como params.data. Por exemplo, o exemplo de código anterior passa um valor booliano como params.data.isHttpsRequest para o retorno de chamada createServerRenderer. Você pode passar isso para outras partes do seu aplicativo de alguma forma compatível com o Angular. Por exemplo, veja como main.server.ts aprova o valor BASE_URL para qualquer componente cujo construtor é declarado para recebê-lo.

Desvantagens da SSR

Nem todos os aplicativos se beneficiam da SSR. O principal benefício é o desempenho percebido. Os visitantes que chegam ao aplicativo por uma conexão de rede lenta ou em dispositivos móveis lentos veem a interface do usuário inicial rapidamente, mesmo que leve algum tempo para buscar ou para analisar os pacotes de JavaScript. No entanto, muitos SPAs são usados principalmente em redes de empresa internas e rápidas, em computadores rápidos nos quais o aplicativo aparece quase instantaneamente.

Ao mesmo tempo, há desvantagens significativas em habilitar a SSR. Ele adiciona complexidade ao seu processo de desenvolvimento. O código deve ser executado em dois ambientes diferentes: no lado do cliente e no do servidor (em um ambiente Node.js invocado do ASP.NET Core). Estes são alguns pontos a considerar:

  • A SSR requer uma instalação de Node.js nos servidores de produção. Isso ocorre automaticamente para alguns cenários de implantação como Serviços de Aplicativos do Azure, mas não para outros como o Azure Service Fabric.
  • Habilitar o sinalizador de build BuildServerSideRenderer faz com que o diretório node_modules seja publicado. Esta pasta contém mais de 20.000 arquivos, o que aumenta o tempo de implantação.
  • Para executar o código em um ambiente Node.js, ele não pode depender da existência de APIs de JavaScript específicas a um navegador, tais como window ou localStorage. Se seu código (ou alguma biblioteca de terceiros à qual você faz referência) tentar usar essas APIs, você obterá um erro durante a SSR. Por exemplo, não use jQuery porque faz referência a APIs específicas a um navegador em vários locais. Para evitar erros, você deve evitar a SSR ou então evitar APIs ou bibliotecas específicas a um navegador. Você pode encapsular todas as chamadas para essas APIs em verificações para garantir que elas não sejam invocadas durante a 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 o middleware de proxy para SignalR

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

Recursos adicionais