翻译自 Camilo Reyes 2021年2月22日的文章 《Integrate Create React app with .NET Core 5》 1

Camilo Reyes 演示了如何将 Create React app 与 .NET Core 集成,以生成一个移除了几个依赖项的脚手架。

Create React app 是社区中创建一个全新 React 项目的首选方式。该工具生成了基础的脚手架用于开始编写代码,并抽象出了许多具有挑战性的依赖项。webpack 和 Babel 之类的 React 工具被集中到一个单独的依赖项中,使得 React 开发者可以专注于手头的工作,这降低了构建单页应用的必要门槛。

不过问题依然存在,虽然 React 解决了客户端的问题,但服务端呢?.NET 开发者在使用 Razor、服务器端配置,并通过 session cookie 处理 ASP.NET 用户会话(session)方面有着悠久的历史。在本文中,我将向您展示如何通过两者之间的良好集成来实现两全其美的效果。

本文提供了一种动手实践的方式,因此您可以依照自上而下的顺序,获得更佳的阅读效果。如果您更喜欢随着代码学习,可以从 GitHub 上获取源码2,使阅读更愉快。

一般的解决方案涉及两个主要部分——前端和后端。后端是一个典型的 ASP.NET MVC 应用,任何人都可以在 .NET Core 5 中启动。请确保您已安装 .NET Core 5,并将项目的目标设置为 .NET Core 5,只要执行了此操作也便开启了 C# 9 特性。随着集成的进行,我还将添加更多的部分。前端会有 React 项目和输出像 index.html 之类静态资产的 NPM 工具。我将假定您具有 .NET 和 React 的工作知识,因此我不会深究诸如在开发机上设置 .NET Core 或 Node 的基础。也就是说,请注意下面一些有用的 using 语句,以便后面使用:

using Microsoft.AspNetCore.Http;
using System.Net;
using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Authorization;
using System.Text.RegularExpressions;

初始化项目设置

好消息是,微软提供了一个基础的脚手架模板,用于启动新的带有 React 前端的 ASP.NET 项目。该 ASP.NET React 项目具有一个客户端应用,它输出可以托管在任何地方的静态资产;以及一个 ASP.NET 后端应用,它可以通过调用 API Endpoints 获取 JSON 数据。这里的一个优点是,整个解决方案可以作为一个整体同时部署,而无需将前后两端拆分成单独的部署流水线。

要安装基础的脚手架,请执行以下操作:

mkdir integrate-dotnet-core-create-react-app
cd integrate-dotnet-core-create-react-app
dotnet new react --no-https
dotnet new sln
dotnet sln add integrate-dotnet-core-create-react-app.csproj

有了这些,就可以在 Visual Studio 或 VS Code 中打开解决方案文件。您可以运行 dotnet run 来启动项目,看看该脚手架都为您做了些什么。请注意命令 dotnet new react,这是我用于该 React 项目的模板。

下面是初始模板的样子:

initial react template

如果您在使用 React 时遇到任何问题,只需将目录更改为 ClientApp 并运行 npm install,即可启动并运行 Create React App。整个 React 应用程序在客户端渲染,而不需要服务器渲染。它有一个具有三个不同页面的 react-router:一个计数器、一个获取天气数据的页面和一个主页。如果您看一下控制器,会发现 WeatherForecastController 有一个 API Endpoint 来获取天气数据。

该脚手架已经包含了一个 Create React App 项目。为了验证这一点,请打开 ClientApp 文件夹中的 package.json 文件进行检查。

这就是它的证据:

{
  "scripts": {
      "start": "rimraf ./build && react-scripts start",
      "build": "react-scripts build",
    }
}

找到 react-scripts,这是像 webpack 一样封装所有其他 React 依赖项的单一依赖项。若要在将来升级 React 和它的依赖项,您只需升级这一依赖项。它抽象化了可能有潜在危险的升级以保持最新状态,因此这才是 React App 的真正魔力。

ClientApp 中的整个文件夹结构遵循常规的 Create React App 项目,在其周围包裹着 ASP.NET 项目。

文件夹结构如下所示:

dotnet react app folder structure

该 React 应用程序有很多优点,但是它缺少一些重要的 ASP.NET 功能:

  • 没有通过 Razor 进行的服务端渲染,使任何其他 MVC 页面像一个单独的应用程序一样工作
  • 很难从 React 客户端访问 ASP.NET 服务端配置数据
  • 它不会集成由 session cookie 实现的 ASP.NET 用户会话

随着集成的推进,我将逐一解决这些问题。好在这些理想的功能是可以使用 Create React App 和 ASP.NET 实现的。

为了跟踪集成更改,我将使用 Git 提交初始脚手架。假设 Git 已安装,请执行 git initgit addgit commit 来提交这个初始项目。查看提交历史是跟踪集成所需更改的一种很好的方法。

现在,创建以下对此集成很有用的文件夹和文件。我建议使用 Visual Studio 右键单击创建控制器 、类或 View:

  • /Controllers/HomeController.cs:服务端主页,它将覆盖 Create React App 的 index.html 入口页
  • /Views/Home/Index.cshtml:Razor 视图,它渲染服务端组件和来自 React 项目的解析过的 index.html
  • /CreateReactAppViewModel.cs:主要的集成视图模型,它将抓取 index.html 静态资产并将其解析出来以供 MVC 使用

有了这些文件夹和文件后,请终止当前正在运行的应用程序,并通过 dotnet watch run 以监视模式启动该应用程序。此命令跟踪前端和后端的更改,甚至在需要时刷新页面。

其余的必要更改将放入脚手架现有的文件中。这好极了,因为可以最大限度地减少必要的代码调整来充实这个集成。

是时候擼起袖子,做个深呼吸,处理这个集成的主要部分了。

CreateReactAppViewModel 集成

我将从创建一个执行大部分集成工作的视图模型开始。打开 CreateReactAppViewModel 并放入以下代码:

public class CreateReactAppViewModel
{
    private static readonly Regex _parser = new(
        @"<head>(?<HeadContent>.*)</head>\s*<body>(?<BodyContent>.*)</body>",
        RegexOptions.IgnoreCase | RegexOptions.Singleline);

    public string HeadContent { getset}
    public string BodyContent { getset}

    public CreateReactAppViewModel(HttpContext context)
    {
        var request = WebRequest.Create(
            context.Request.Scheme + "://" + context.Request.Host +
            context.Request.PathBase + "/index.html");

        var response = request.GetResponse();
        var stream = response.GetResponseStream();
        var reader = new StreamReader(
            stream ?? throw new InvalidOperationException(
            "The create-react-app build output could not be found in " +
            "/ClientApp/build. You probably need to run npm run build. " +
            "For local development, consider npm start."));

        var htmlFileContent = reader.ReadToEnd();
        var matches = _parser.Matches(htmlFileContent);

        if (matches.Count != 1)
        {
            throw new InvalidOperationException(
                "The create-react-app build output does not appear " +
                "to be a valid html file.");
        }

        var match = matches[0];

        HeadContent = match.Groups["HeadContent"].Value;
        BodyContent = match.Groups["BodyContent"].Value;
    }
}

这段代码乍一看可能有点吓人,但它只做了两件事:从开发服务器获取输出的 index.html 文件,并解析出 headbody 标签。这使得 ASP.NET 中的消费方应用程序可以访问 HTML,该 HTML 链接到来自 Create React App 的静态资产。这些资产是静态文件,其中包含带有 JavaScript 和 CSS 的代码包。例如,JavaScript 包 js\main.3549aedc.chunk.js 或 CSS 包 css\2.ed890e5e.chunk.css。这就是在 React 中 webpack 接收所编写的代码并将其呈现到浏览器的方式。

我选择直接向开发服务器发起一个 WebRequest,是因为在开发模式下,Create React App 不会生成 ASP.NET 可访问的任何实际文件。这对于本地开发来说足够了,因为它可以与 webpack 开发服务器很好地配合。客户端上的任何更改都将自动更新到浏览器。在监视模式下进行的任何后端更改也会刷新到浏览器。因此,您可以在两全其美的环境中获得最佳的生产力。

在生产环境中,将会通过 npm run build 创建静态资产。我建议执行文件 IO,并从 ClientApp/build 中的实际位置读取 index 文件。另外,在生产模式下,最好在静态资产部署到托管服务器之后缓存该文件的内容。

为了让您有一个更好的概念,下面是一个 build 后的 index.html 文件的样子:

built index.html looks like

我高亮显示了消费方 ASP.NET 应用需要解析的 headbody 标签。有了这些原始的 HTML,剩下的就简单多了。

视图模型就绪后,就该花点时间处理 home 控制器了,它将覆盖来自 React 的 index.html

打开 HomeController 并添加以下代码:

public class HomeController : Controller
{
    public IActionResult Index()
    {
        var vm = new CreateReactAppViewModel(HttpContext);

        return View(vm);
    }
}

在 ASP.NET 中,该控制器是默认路由,它会在服务端渲染的支持下覆盖 Create React App。这就是解锁集成的诀窍,从而可以两全其美。

接着,把下面的 Razor 代码放入 Home/Index.cshtml 中:

@model integrate_dotnet_core_create_react_app.CreateReactAppViewModel
 
<!DOCTYPE html>
<html lang="en">
<head>
  @Html.Raw(Model.HeadContent)
</head>
<body>
  @Html.Raw(Model.BodyContent)
 
  <div class="container ">
    <h2>Server-side rendering</h2>
  </div>
</body>
</html>

React 应用程序使用 react-router 来定义客户端的路由。如果在浏览器处于非 home 路由时刷新页面,它将恢复为静态的 index.html

要解决这种不一致性,请在 Startup 中定义下面的服务端路由,路由是在 UseEndpoints 中定义的:

endpoints.MapControllerRoute(
  "default",
  "{controller=Home}/{action=Index}");
endpoints.MapControllerRoute(
  "counter",
  "/counter",
  new { controller = "Home", action = "Index"});
endpoints.MapControllerRoute(
  "fetch-data",
  "/fetch-data",
  new { controller = "Home", action = "Index"});

此时,看一下浏览器,现在它将通过 h2 显示这个服务端“组件”。这看起来似乎有点愚蠢,因为它只是在页面上渲染的一些简单 HTML,但其潜力是无穷的。ASP.NET Razor 页面可以具有完整的应用程序外壳,其中包含菜单、品牌和导航,它可以在多个 React 应用之间共享。如果有任何旧版 MVC Razor 页面,这个闪亮的新 React 应用能够无缝集成。

服务器端应用程序配置

接下来,假如我想显示此应用上来自 ASP.NET 的服务端配置,比如 HTTP 协议、主机名和 base URL。我选择这些主要是为了保持简单,不过这些配置值可以来自任何地方,它们可以是 appsettings.json 设置,或者甚至可以是来自配置数据库中的值。

要使服务端设置可以被 React 客户端访问,请将其放在 Index.cshtml 中:

<script>
  window.SERVER_PROTOCOL = '@Context.Request.Protocol';
  window.SERVER_SCHEME = '@Context.Request.Scheme';
  window.SERVER_HOST = '@Context.Request.Host';
  window.SERVER_PATH_BASE = '@Context.Request.PathBase';
</script>
 
<p>
  @Context.Request.Protocol
  @Context.Request.Scheme://@Context.Request.Host@Context.Request.PathBase
</p>

这里在全局 window 浏览器对象中设置来自服务器的任意配置值。React 应用可以轻而易举地检索这些值。我选择在 Razor 中渲染这些相同的值,主要是为了演示它们与客户端应用将看到的是相同的值。

在 React 中,打开 components\NavMenu.js 并添加下面的代码段;其中大部分将放在 Navbar 中:

import { NavbarText } from 'reactstrap';
 
<NavbarText>
  {window.SERVER_PROTOCOL}
   {window.SERVER_SCHEME}://{window.SERVER_HOST}{window.SERVER_PATH_BASE}
</NavbarText>

这个客户端应用现在将显示通过全局 window 对象设置的服务器端配置。它不需要触发 Ajax 请求来加载这些数据,也不需要以某种方式让 index.html 静态资产可以访问它。

假如您使用了 Redux,这会变得更加容易,因为可以在应用程序初始化 store 时进行设置。初始化状态值可以在客户端渲染任何内容之前传递到 store 中。

例如:

const preloadedState = {
  config: {
    protocol: window.SERVER_PROTOCOL,
    scheme: window.SERVER_SCHEME,
    host: window.SERVER_HOST,
    pathBase: window.SERVER_PATH_BASE
  }
};
 
const store = createStore(reducers, preloadedState, 
    applyMiddleware(...middleware));

为了简洁起见,我选择不使用 Redux store,而是通过 window 对象的方式实现,这只是一个粗略的想法。这种方法的好处是,整个应用都可以保持单元可测试的状态,而不会受到类似 window 对象的浏览器依赖项的污染。

.NET Core 用户会话集成

最后,作为主菜,现在我将这个 React 应用与 ASP.NET 用户会话(Session)集成在一起。我将锁定获取天气数据的后端 API,并仅在使用有效会话时显示此信息。这意味着当浏览器触发 Ajax 请求时,它必须包含一个 ASP.NET session cookie。否则,该请求将被拒绝,并重定向以指示浏览器必须先登录。

要在 ASP.NET 中启用用户会话支持,请打开 Startup 文件并添加:

public void ConfigureServices(IServiceCollection services)
{
    services
        .AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
        .AddCookie(options =>
        {
            options.Cookie.HttpOnly = true;
        });
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // 将下面代码放在 UseRouting 和 UseEndpoints 之间
    app.UseAuthentication();
    app.UseAuthorization();
}

请务必保留其余的脚手架代码,只是在恰当的方法中添加上面的代码段。启用了身份验证和授权后,转到 WeatherForecastController 并给该控制器添加一个 Authorize 属性。这将有效地将其锁定,从而需要由 cookie 实现的 ASP.NET 用户会话来获取数据。

Authorize 属性假定用户可以登录到该应用。回到 HomeController 并添加 Login 和 Logout 方法,记得添加 using Microsoft.AspNetCore.AuthenticationMicrosoft.AspNetCore.Authentication.CookiesMicrosft.AspNetCore.Mvc

这是建立然后终止用户会话的一种方法:

public async Task<ActionResult> Login()
{
    var userId = Guid.NewGuid().ToString();
    var claims = new List<Claim>
    {
        new(ClaimTypes.Name, userId)
    };

    var claimsIdentity = new ClaimsIdentity(claims,
            CookieAuthenticationDefaults.AuthenticationScheme);
    var authProperties = new AuthenticationProperties();

    await HttpContext.SignInAsync(
        CookieAuthenticationDefaults.AuthenticationScheme,
        new ClaimsPrincipal(claimsIdentity),
        authProperties);

    return RedirectToAction("Index");
}

public async Task<ActionResult> Logout()
{
    await HttpContext.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);

    return RedirectToAction("Index");
}

请注意,通常使用重定向和 ASP.NET session cookie 来建立用户会话。我添加了一个 ClaimsPrincipal,它带有一个设置为随机 Guid 的用户 ID,使其看起来更加真实。3 在实际应用中,这些 Claims 可能来自数据库或者 JWT。

要将此功能公开给客户端,请打开 components\NavMenu.js 并将下面的链接添加到 Navbar

<NavItem>
  <a class="text-dark nav-link" href="/home/login">Log In</a>
</NavItem>
<NavItem>
  <a class="text-dark nav-link" href="/home/logout">Log Out</a>
</NavItem>

最后,我希望客户端应用处理请求失败的情况,并给最终用户提供一些提示,指出出了点问题。打开 components\FetchData.js 并用下面的代码段替换 populateWeatherData

async populateWeatherData() {
    try {
        const response = await fetch(
            'weatherforecast',
            { redirect: 'error' });
        const data = await response.json();
        this.setState({ forecasts: data, loading: false });
    } catch {
        this.setState({
            forecasts: [{ date: 'Unable to get weather forecast' }],
            loading: false
        });
    }
}

我调整了一下 fetch,以使它不会用重定向跟踪失败的请求,而是返回一个错误响应。当 Ajax 请求获取数据失败时,ASP.NET 中间件将以重定向到登录页的方式响应。在实际的应用中,我建议将其自定义为 401 (Unauthorized) 状态码,以便客户端可以更优雅地处理此问题;或者,设置某种方式来轮询后端并检查活动会话,然后通过 window.location 进行相应地重定向。

完成后,dotnet 监视程序应该会在刷新浏览器时跟踪前后两端的更改。为了进行测试,我将首先访问 Fetch Data 页,请注意会请求失败,然后登录,并使用有效的会话再次尝试获取天气数据。我将打开“Network”选项卡,以在浏览器中显示 Ajax 请求。

ajax request with valid session

请注意当我第一次获取天气数据时的 302 重定向,它失败了。接着,来自登录页的后续重定向建立了一个会话。查看一下浏览器的 cookies,会显示这个名为 AspNetCore.Cookies 的 cookie,它是一个 session cookie,正是它让后面的 Ajax 请求工作正常了。

结论

.NET Core 5 和 React 不必独立存在。通过出色的集成,便可以在 React 中解锁服务端渲染、服务端配置数据和 ASP.NET 用户会话。


作者 : Camilo Reyes
译者 : 技术译民
出品 : 技术译站
链接 : 英文原文

  1. https://www.red-gate.com/simple-talk/dotnet/net-tools/integrate-create-react-app-with-net-core-5/ Integrate Create React app with .NET Core 5 

  2. https://github.com/beautifulcoder/integrate-dotnet-core-create-react-app.git 示例代码 

  3. 用 Cookie 代表一个通过验证的主体,它包含 Claims, ClaimsIdentity, ClaimsPrincipal 三部分信息,其中 ClaimsPrincipal 相当于持有证件的人,ClaimsIdentity 就是持有的证件,Claims 是证件上的信息。https://andrewlock.net/introduction-to-authentication-with-asp-net-core/