Usar React com ASP.NET Core
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.
Aviso
Não há mais suporte para essa versão do ASP.NET Core. Para obter mais informações, confira .NET e a Política de Suporte do .NET Core. 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:
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:
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:
Adicione um arquivo
.env
ao subdiretórioClientApp
com a seguinte configuração:BROWSER=none
Isso impedirá que o navegador da Web seja aberto ao inicializar o servidor CRA externamente.
Em um prompt de comando, vá para o subdiretório
ClientApp
e inicie o Development Server do CRA:cd ClientApp npm start
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.