在Razor Pages上传图片时如何解决无效ModelState问题？

问题描述 #

开发环境：Visual Studio 2022 + ASP.NET Core Razor Pages（.NET 8），搭配EF Core和MS SQL Server。
实现了文件上传表单（Create.cshtml）用于添加Bootstrap轮播图片，图片上传时会重命名为GUID并写入wwwroot/images目录，此功能正常，但图片相关数据无法写入数据库。
核心问题：执行到if (!ModelState.IsValid)时，ModelState验证不通过，监视窗口显示FileName字段为null，验证状态为无效。

关联代码 #

CarouselItem类 #

public class CarouselItem
{
    public int Id { get; set; }
    public required string Description { get; set; }
    [DisplayName("File Name (GUID)")]
    public required string FileName { get; set; }
    [DisplayName("Alt File Name")]
    public required string AltFileName { get; set; }
    [DisplayName("Display Start Date")]
    public required DateOnly DisplayStartDate { get; set; }
    [DisplayName("Display Stop Date")]
    public required DateOnly DisplayStopDate { get; set; }
}

Create.cshtml.cs代码 #

public class CreateModel : PageModel
{
    private readonly IWebHostEnvironment _webHostEnvironment;
    private readonly ApplicationDbContext _context;

    public CreateModel(IWebHostEnvironment webHostEnvironment, ApplicationDbContext context)
    {
        _webHostEnvironment = webHostEnvironment;
        _context = context;
    }

    [BindProperty]
    public CarouselItem CarouselItem { get; set; }

    [BindProperty]
    public IFormFile Image { get; set; }

    public void OnGet()
    {
    }

    public async Task<IActionResult> OnPostAsync()
    {
        if (Image != null)
        {
            var fileExtension = Path.GetExtension(Image.FileName);
            if (fileExtension.ToLower() == ".jpg")
            {
                var newFileName = $"{Guid.NewGuid()}{fileExtension}";
                var filePath = Path.Combine(_webHostEnvironment.WebRootPath, "images", newFileName);

                using (var fileStream = new FileStream(filePath, FileMode.Create))
                {
                    await Image.CopyToAsync(fileStream);
                }

                CarouselItem.FileName = newFileName;
                CarouselItem.AltFileName = Image.FileName;
            }
            else
            {
                ModelState.AddModelError("Image", "Only .jpg files are allowed.");
            }
        }

        if (string.IsNullOrEmpty(CarouselItem.FileName))
        {
            ModelState.AddModelError("CarouselItem.FileName", "The File Name field is required.");
        }

        if (!ModelState.IsValid)
        {
            return Page();
        }

        _context.CarouselItems.Add(CarouselItem);
        await _context.SaveChangesAsync();

        return RedirectToPage("/Admin/Carousel/Index");
    }
}

Create.cshtml代码 #

<h1>Create Carousel Items</h1>
<hr />

<form method="post" enctype="multipart/form-data">
    <div asp-validation-summary="ModelOnly" class="text-danger"></div>
    <div class="mb-3">
        <label for="Description" class="form-label">Description</label>
        <input type="text" class="form-control" id="Description" name="Description" asp-for="CarouselItem.Description" />
        <span asp-validation-for="CarouselItem.Description" class="text-danger"></span>
    </div>
    <div class="mb-3">
        <label for="AltFileName" class="form-label">Alt File Name</label>
        <input type="text" class="form-control" id="AltFileName" name="AltFileName" asp-for="CarouselItem.AltFileName" />
        <span asp-validation-for="CarouselItem.AltFileName" class="text-danger"></span>
    </div>
    <div class="mb-3">
        <label for="DisplayStartDate" class="form-label">Display Start Date</label>
        <input type="date" class="form-control" id="DisplayStartDate" name="DisplayStartDate" asp-for="CarouselItem.DisplayStartDate" />
        <span asp-validation-for="CarouselItem.DisplayStartDate" class="text-danger"></span>
    </div>
    <div class="mb-3">
        <label for="DisplayStopDate" class="form-label">Display Stop Date</label>
        <input type="date" class="form-control" id="DisplayStopDate" name="DisplayStopDate" asp-for="CarouselItem.DisplayStopDate" />
        <span asp-validation-for="CarouselItem.DisplayStopDate" class="text-danger"></span>
    </div>
    <div class="mb-3">
        <label for="Image" class="form-label">File</label>
        <input type="file" class="form-control" id="Image" name="Image" />
        <span asp-validation-for="Image" class="text-danger"></span>
    </div>
    <button type="submit" class="btn btn-primary">Create</button>
</form>

@section Scripts {
    <partial name="_ValidationScriptsPartial" />
}

原因分析 #

CarouselItem的FileName字段用required修饰，属于必填项，但前端表单无该字段的输入控件，模型绑定阶段会因字段缺失直接标记ModelState无效。虽然后续代码给CarouselItem.FileName赋值，但ModelState中已存在的错误不会自动清除，导致最终验证不通过。

解决方案 #

提供两种可行解决方式：

方式一：标记字段跳过模型绑定 #

给FileName添加[BindNever]属性，让模型绑定时忽略该字段，避免触发不必要的验证：

public class CarouselItem
{
    public int Id { get; set; }
    public required string Description { get; set; }
    [DisplayName("File Name (GUID)")]
    [BindNever] // 添加此属性
    public required string FileName { get; set; }
    [DisplayName("Alt File Name")]
    public required string AltFileName { get; set; }
    [DisplayName("Display Start Date")]
    public required DateOnly DisplayStartDate { get; set; }
    [DisplayName("Display Stop Date")]
    public required DateOnly DisplayStopDate { get; set; }
}

方式二：清除ModelState中的对应错误 #

在给CarouselItem.FileName赋值后，手动清除ModelState中该字段的错误：
修改OnPostAsync方法中赋值后的代码：

if (Image != null)
{
    var fileExtension = Path.GetExtension(Image.FileName);
    if (fileExtension.ToLower() == ".jpg")
    {
        var newFileName = $"{Guid.NewGuid()}{fileExtension}";
        var filePath = Path.Combine(_webHostEnvironment.WebRootPath, "images", newFileName);

        using (var fileStream = new FileStream(filePath, FileMode.Create))
        {
            await Image.CopyToAsync(fileStream);
        }

        CarouselItem.FileName = newFileName;
        CarouselItem.AltFileName = Image.FileName;
        // 清除FileName字段的模型验证错误
        ModelState.Remove("CarouselItem.FileName");
    }
    else
    {
        ModelState.AddModelError("Image", "Only .jpg files are allowed.");
    }
}

额外优化：添加图片上传必填验证 #

当前代码未处理用户未上传图片的情况，建议在OnPostAsync开头添加：

if (Image == null)
{
    ModelState.AddModelError("Image", "Please upload a .jpg image.");
    return Page();
}

确保用户必须上传图片，避免后续CarouselItem.FileName为空的情况。

内容的提问来源于stack exchange，提问作者1 Zero 3 Tech