Umbraco 13中如何设置可访问的外部自定义页面目录？

Umbraco 13基于ASP.NET Core，不再支持旧版本通过web.config配置外部自定义页面的方式，需要改用ASP.NET Core的中间件和路由配置，下面分两种场景说明：

一、静态HTML/文件类自定义页面 #

如果你的自定义页面是静态HTML、CSS、JS等文件，按以下步骤配置：

1. 在项目的Program.cs中，在Umbraco中间件之前添加静态文件配置，指定自定义目录的物理路径和访问路径：

var builder = WebApplication.CreateBuilder(args);

// 初始化Umbraco服务
builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
    .AddDeliveryApi()
    .AddComposers()
    .Build();

var app = builder.Build();

// 配置自定义静态文件目录
app.UseStaticFiles(new StaticFileOptions
{
    // 指定FTP上传的/my-custom-pages目录的物理路径
    FileProvider = new PhysicalFileProvider(
        Path.Combine(Directory.GetCurrentDirectory(), "my-custom-pages")),
    // 设置访问该目录的URL路径前缀
    RequestPath = "/my-custom-pages"
});

// 后续保留Umbraco原有中间件配置
if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

app.UseUmbraco()
    .WithMiddleware(u =>
    {
        u.UseBackOffice();
        u.UseWebsite();
    })
    .WithEndpoints(u =>
    {
        u.UseInstallerEndpoints();
        u.UseBackOfficeEndpoints();
        u.UseWebsiteEndpoints();
    });

app.Run();

2. 确保my-custom-pages目录的权限正确，ASP.NET Core进程拥有读取该目录文件的权限。

配置完成后，访问/my-custom-pages/xxx.html即可直接打开对应静态文件。

二、动态自定义页面（Razor页面/控制器） #

如果需要创建带动态逻辑的自定义页面，推荐直接在项目中添加Razor页面或控制器：

方式1：使用属性路由的控制器 #

创建一个自定义控制器，并通过属性路由指定访问路径：

using Microsoft.AspNetCore.Mvc;

public class CustomPagesController : Controller
{
    // 访问路径：/my-custom-pages/dynamic-page
    [Route("my-custom-pages/dynamic-page")]
    public IActionResult DynamicPage()
    {
        // 可在这里添加业务逻辑
        return View();
    }
}

然后在Views目录下创建对应的视图文件CustomPages/DynamicPage.cshtml即可。

方式2：添加自定义路由规则 #

如果需要批量配置自定义路由，可在Program.cs的端点配置中添加自定义路由：

app.UseUmbraco()
    .WithMiddleware(u =>
    {
        u.UseBackOffice();
        u.UseWebsite();
    })
    .WithEndpoints(u =>
    {
        u.UseInstallerEndpoints();
        u.UseBackOfficeEndpoints();
        u.UseWebsiteEndpoints();
        // 添加自定义路由
        u.Endpoints.MapControllerRoute(
            name: "custom-pages",
            pattern: "my-custom-pages/{action}",
            defaults: new { controller = "CustomPages" });
    });

关键注意事项 #

• 中间件顺序：自定义静态文件或路由配置必须放在UseUmbraco()之前，否则Umbraco的路由会优先拦截请求。
• 路径冲突：确保自定义页面的URL路径不会与Umbraco后台或现有页面的路径重复，避免路由冲突。
• 目录权限：若使用FTP上传的外部目录，需确认服务器上该目录的读写权限已开放给ASP.NET Core进程。

内容的提问来源于stack exchange，提问作者Menahem Gil