Usar React com 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 começar, siga o tutorial Criar um aplicativo ASP.NET Core com o React 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 ver a documentação sobre esses modelos mais antigos, confira a versão ASP.NET Core 7.0 da visão geral do SPA e os artigos sobre o Angular e o React.

O ASP.NET Core com o modelo de projeto do React fornece um ponto inicial conveniente para aplicativos do ASP.NET Core usando o React e CRA (Criar Aplicativo do React) para implementar uma IU (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 um projeto do React CRA 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 à SSR (renderização do lado do servidor). Para SSR com React e Node.js, considere Next.js ou Razzle.

Criar um novo aplicativo

Crie um novo projeto de um prompt de comando usando o comando dotnet new react 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 react -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 React. 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 React, que reside no subdiretório ClientApp, destina-se a ser usado para todas as questões de interface do usuário.

Adicione páginas, imagens, estilos, módulos, etc.

O diretório ClientApp é um aplicativo do React CRA padrão. Veja a documentação oficial do CRA para obter mais informações.

Há pequenas diferenças entre o aplicativo do React criado por este modelo e um criado pelo CRA propriamente dito; 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.

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-fonte original). O aplicativo observa alterações em arquivos JavaScript, 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 e transpilado do seu código do lado do cliente. Diferentemente do build de desenvolvimento, o build de produção não requer que o Node.js esteja instalado no servidor.

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

Executar o servidor CRA independentemente

O projeto está configurado para iniciar sua própria instância do Development Server do CRA em segundo plano quando o aplicativo ASP.NET Core é iniciado no modo de desenvolvimento. Isso é conveniente, porque significa que 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 CRA será reiniciado também. São necessários alguns segundos para iniciar um backup. Se você estiver fazendo edições frequentes de código C# e não quiser esperar o servidor CRA reiniciar, execute o servidor CRA externamente, independentemente do processo do ASP.NET Core.

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

cd ClientApp
npm start

Quando você iniciar seu aplicativo ASP.NET Core, ele não inicializará um servidor CRA. Em vez disso, a instância que você iniciou manualmente é usada. Isso permite a ele iniciar e reiniciar mais rapidamente. Ele não aguarda mais que o aplicativo do React seja recompilado a cada vez.

Configurar o middleware de proxy para SignalR

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

Recursos adicionais

O modelo de projeto do React atualizado fornece um ponto inicial conveniente para aplicativos do ASP.NET Core usando convenções do React e de CRA (criar-aplicativo-do-React) para implementar uma IU (interface do usuário) avançada do lado do cliente.

O modelo é equivalente à criação de dois projetos: um projeto do ASP.NET Core, para atuar como um back-end de API, e um projeto do React CRA padrão, para atuar como uma interface do usuário, mas com a praticidade de hospedar ambos em um único projeto de aplicativo que pode ser criado e publicado como uma única unidade.

O modelo de projeto do React não se destina à SSR (renderização do lado do servidor). Para SSR com React e Node.js, considere Next.js ou Razzle.

Criar um novo aplicativo

Crie um novo projeto de um prompt de comando usando o comando dotnet new react 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 react -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 React. 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 React, que reside no subdiretório ClientApp, destina-se a ser usado para todas as questões de interface do usuário.

Adicione páginas, imagens, estilos, módulos, etc.

O diretório ClientApp é um aplicativo do React CRA padrão. Veja a documentação oficial do CRA para obter mais informações.

Há pequenas diferenças entre o aplicativo do React criado por este modelo e um criado pelo CRA propriamente dito; 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.

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-fonte original). O aplicativo observa alterações em arquivos JavaScript, 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 e transpilado do seu código do lado do cliente. Diferentemente do build de desenvolvimento, o build de produção não requer que o Node.js esteja instalado no servidor.

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

Executar o servidor CRA independentemente

O projeto está configurado para iniciar sua própria instância do Development Server do CRA em segundo plano quando o aplicativo ASP.NET Core é iniciado no modo de desenvolvimento. Isso é conveniente, porque significa que 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 CRA será reiniciado também. São necessários alguns segundos para iniciar um backup. Se você estiver fazendo edições frequentes de código C# e não quiser esperar o servidor CRA reiniciar, execute o servidor CRA externamente, independentemente do processo do ASP.NET Core. Para fazer isso:

  1. Adicione um arquivo .env ao subdiretório ClientApp com a seguinte configuração:

    BROWSER=none

    Isso impedirá que o navegador da Web seja aberto ao inicializar o servidor CRA externamente.

  2. Em um prompt de comando, vá para o subdiretório ClientApp e inicie o Development Server do CRA:

    cd ClientApp
npm start

  3. Modifique o aplicativo ASP.NET Core para, em vez de iniciar uma instância do servidor CRA própria, usar a externa. Na classe Startup, substitua a invocação spa.UseReactDevelopmentServer pelo seguinte:

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

Quando você iniciar seu aplicativo ASP.NET Core, ele não inicializará um servidor CRA. Em vez disso, a instância que você iniciou manualmente é usada. Isso permite a ele iniciar e reiniciar mais rapidamente. Ele não aguarda mais que o aplicativo do React seja recompilado a cada vez.

Importante

"Renderização do lado do servidor" não é um recurso com suporte deste modelo. Nossa meta com esse modelo é atender à paridade com "create-react-app". Dessa forma, cenários e recursos não incluídos em um projeto "create-react-app" (como SSR) não têm suporte e são deixados como um exercício para o usuário.

Configurar o middleware de proxy para SignalR

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

Recursos adicionais