Sphere10.Framework.Web.AspNetCore.MVC 3.2.0-ci.163.43664782937.1

Sphere10.Framework.Web.AspNetCore.MVC

This library extends ASP.NET Core MVC applications that use Sphere10 Framework with action results, Razor HTML helpers, AJAX Bootstrap forms and action filters. It builds on the shared ASP.NET Core integration and does not register controllers, routes or client scripts by itself.

Features

Installation

Reference the package from an ASP.NET Core project that targets .NET 10 or later:

dotnet add package Sphere10.Framework.Web.AspNetCore.MVC

Pass --version to match the other Sphere10.Framework packages in the application, and --source to restore from a local folder feed. The root README explains how to build and publish the packages, including to a private folder feed.

To build against the source instead, reference the project. From the repository root, these commands create the host for the examples below, beside the repository:

dotnet new web --name MvcDemo --output ../MvcDemo --framework net10.0
dotnet add ../MvcDemo/MvcDemo.csproj reference src/Sphere10.Framework.Web.AspNetCore.MVC/Sphere10.Framework.Web.AspNetCore.MVC.csproj

Quick start: serve a sitemap

Replace MvcDemo/Program.cs with:

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllersWithViews();
var app = builder.Build();
app.UseStaticFiles();
app.MapControllers();
app.Run();

Add Controllers/SitemapController.cs:

using Microsoft.AspNetCore.Mvc;
using Sphere10.Framework.Web;
using Sphere10.Framework.Web.AspNetCore.MVC;

namespace MvcDemo.Controllers;

public class SitemapController : Controller {
	[HttpGet("sitemap.xml")]
	public IActionResult Index() {
		var sitemap = new SitemapXml();
		sitemap.Add("https://example.com/", frequency: SitemapXml.Frequency.Weekly, priority: 1.0);
		return new XmlResult(sitemap);
	}
}

Run the host from the repository root, then open /sitemap.xml at the address that it prints:

dotnet run --project ../MvcDemo -p:BuildRevision=0

XmlResult is a ContentResult with the application/xml content type and status 200 unless you pass another status code:

XML results do not need the Framework to be started. Add the registration and start calls from the shared hosting quick start when the application needs Framework modules and lifecycle services.

Domains

Every folder of Sphere10.Framework.Web.AspNetCore.MVC is a domain with its own README, which lists all of its public types.

Project root

Types declared in the project folder itself:

Select lists

using System;
using Sphere10.Framework;

var weekdays = Tools.Web.Mvc.ToSelectList<DayOfWeek>(DayOfWeek.Monday, SortDirection.Ascending);

Pass the returned SelectList to Html.DropDownListFor or Html.BootstrapDropDownListFor. Each option's value is the enum member's name, and its label comes from Tools.Enums.GetDescription, which reads a [Description] attribute and falls back to the name. The optional sort orders the labels and keeps the selected value. ToSelectList(Type, ...) takes the enum type at run time instead.

For other collections, the ToSelectList(text, value, defaultOption, selected) extension on IEnumerable<T> builds SelectListItem objects from delegates. A defaultOption becomes the first item, with the value -1.

Bootstrap AJAX forms

BootstrapFormScope<TModel> renders a form that the embedded hydrogen-bootstrap-forms-1.0.0.js script submits with jQuery AJAX. The action answers with a FormResult, and the script then shows a message, redirects, or replaces the page or the form. The steps below add a contact form to the sitemap host.

Prerequisites

The application supplies the client libraries, because this package neither downloads nor serves them:

• jQuery, loaded before Bootstrap. The script calls Bootstrap's jQuery tooltip and popover plugins, which Bootstrap registers only when jQuery is present.
• Bootstrap 5, whose data-bs-* attributes and form-control, form-select and btn-close classes the helpers and the script use.
• Choices.js for any drop-down that BootstrapDropDownListFor renders with its default useChoicesJS: true. Without the library, the form's initialization stops at that element and the form is not converted to AJAX, so pass useChoicesJS: false for a plain select element.
• Font Awesome, optionally, for the fa icons in result alerts.

The example's view loads them from wwwroot/lib/jquery/jquery.min.js, wwwroot/lib/bootstrap/bootstrap.bundle.min.js and wwwroot/lib/bootstrap/bootstrap.min.css.

Serve the embedded script

The script is an embedded resource of the MVC assembly, not a static web asset. Add these imports at the top of Program.cs and the endpoint before app.Run():

using Microsoft.AspNetCore.Http;
using Sphere10.Framework;
using Sphere10.Framework.Web.AspNetCore.MVC;

app.MapGet("/sphere10/forms.js", () => {
	var script = typeof(FormModelBase).Assembly.GetManifestResourceStream(
		"Sphere10.Framework.Web.AspNetCore.MVC.Forms.hydrogen-bootstrap-forms-1.0.0.js"
	);
	Guard.Ensure(script != null, "The embedded forms script was not found.");
	return Results.Stream(script, "text/javascript");
});

Results.Stream disposes the resource stream once the response is written. Load the script in the page head, without defer or async, because each form calls the script's F_Init function from an inline script.

Define the model and controller

Save Models/ContactForm.cs:

using System.ComponentModel;
using System.ComponentModel.DataAnnotations;
using Sphere10.Framework.Web.AspNetCore.MVC;

namespace MvcDemo.Models;

public sealed class ContactForm : FormModelBase {
	[Required]
	[DisplayName("Your name")]
	public string Name { get; set; } = string.Empty;
}

FormModelBase gives each model a random, DOM-safe ID, which becomes the form's element ID, and a SubmitCount that the script increments on every submission.

Save Controllers/ContactController.cs:

using Microsoft.AspNetCore.Mvc;
using MvcDemo.Models;
using Newtonsoft.Json;
using Sphere10.Framework.Web.AspNetCore.MVC;

namespace MvcDemo.Controllers;

[Route("contact")]
public class ContactController : Controller {
	[HttpGet]
	public IActionResult Index() => View(new ContactForm());

	[HttpPost]
	[ValidateAntiForgeryToken]
	public IActionResult Submit(ContactForm model) {
		var result = new FormResult {
			Result = ModelState.IsValid,
			ResultType = FormResultType.ShowMessage,
			Message = ModelState.IsValid ? "Demo submission accepted. No data was stored." : "Enter your name."
		};
		return Content(JsonConvert.SerializeObject(result), "application/json");
	}
}

FormResult carries Newtonsoft.Json attributes, so the action serializes it with JsonConvert to produce the result, message, type, url and content fields that the script reads. ASP.NET Core's default System.Text.Json output would name the type field resultType and write it as a number, so returning Json(result) does not work. No MVC Newtonsoft integration package is needed, because this library already references Newtonsoft.Json.

Render the form

Save Views/Contact/Index.cshtml:

@using Microsoft.AspNetCore.Mvc.Rendering
@using Sphere10.Framework.Web.AspNetCore.MVC
@model MvcDemo.Models.ContactForm
@{
	Layout = null;
}
<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="utf-8" />
	<title>Contact form demo</title>
	<link rel="stylesheet" href="/lib/bootstrap/bootstrap.min.css" />
	<script src="/lib/jquery/jquery.min.js"></script>
	<script src="/lib/bootstrap/bootstrap.bundle.min.js"></script>
	<script src="/sphere10/forms.js"></script>
</head>
<body>
	<main class="container py-4">
		@using (Html.BeginBootstrapForm("/contact", Model, options: FormScopeOptions.UseLoadingOverlay | FormScopeOptions.AddAntiForgeryToken)) {
			@Html.BootstrapLabelFor(model => model.Name)
			@Html.BootstrapTextBoxFor(model => model.Name)
			@Html.BootstrapFormButton(Model, "Submit")
		}
	</main>
</body>
</html>

Stop the host, run it again and open /contact. Submitting the form posts it with AJAX and shows the action's message at the end of the form. The field keeps its value after submission, because the options omit ClearOnSuccess.

The scope writes the <form> tag with the model's ID, the hidden ID and SubmitCount fields, the antiforgery token and, with UseLoadingOverlay, a loading overlay. Disposing the scope writes a {formId}_message_marker element, the F_Init call and the closing tag.

The embedded script shows each result in an alert after that marker, and later results replace the alert. A page can instead supply an element whose ID is {formId}_result, which the script replaces with the alert. Call MessageMarker() to place the scope's marker earlier in the form, and the scope then omits it on disposal.

BootstrapFormScope implements both Dispose and DisposeAsync. DisposeAsync writes the closing markup with asynchronous writes only.

Results and options

BotProtect deters generic form bots only. It does not replace server-side validation or the antiforgery check.

Bootstrap input helpers

The Bootstrap*For helpers wrap the MVC *For helpers with Bootstrap 5 markup. Each takes its label or placeholder text from the member's [DisplayName] attribute and appends * for a [Required] member. When ModelState holds errors for the member, the input gets the is-invalid class and a Bootstrap tooltip that lists the errors.

Render a view to a string

Controller.RenderViewAsync(viewName, model, partial) renders an MVC view into a string, for example as the content of a ReplaceForm result. An empty viewName selects the current action's view, and partial: true renders it as a partial view. When the view engine finds no view, the method returns the text A view with the name <viewName> could not be found instead of throwing, so check for a missing view before you send the result.

To replace the contact form with a thank-you fragment, save Views/Contact/Thanks.cshtml:

@model MvcDemo.Models.ContactForm
<div class="alert alert-success">Thank you, @Model.Name.</div>

Then change the Submit action of ContactController to the version below, and add using System.Threading.Tasks; and using Sphere10.Framework; to the file:

[HttpPost]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Submit(ContactForm model) {
	var nameCheck = model.Name == "admin" ? Result.Error("Choose another name.") : Result.Success;
	ModelState.AddModelError(nameof(ContactForm.Name), nameCheck);

	var result = ModelState.IsValid
		? new FormResult {
			Result = true,
			ResultType = FormResultType.ReplaceForm,
			Content = await this.RenderViewAsync("Thanks", model, partial: true)
		}
		: new FormResult {
			Result = false,
			ResultType = FormResultType.ShowMessage,
			Message = "Correct the highlighted fields."
		};
	return Content(JsonConvert.SerializeObject(result), "application/json");
}

RenderViewAsync is an extension method, so a controller calls it through this. AddModelError(key, Result) adds each error message of a Sphere10.Framework.Result under the key, and a successful Result adds nothing. The other overloads add a Result or a formatted message under the empty key, and Remove(params string[]) removes several keys at once.

Images

ImageResult writes a System.Drawing.Image to the response as JPEG, which is the default, or as PNG or GIF, and throws for any other ImageFormat. It is marked Windows-only and disposes the image after writing, so do not reuse the image. MVC executes it asynchronously: it encodes the image in memory, sets the content length and copies the bytes to the response body with asynchronous writes, so AllowSynchronousIO is not needed. Only a direct call to the synchronous ExecuteResult saves straight to the response body.

This controller draws a small PNG badge on each request:

using System.Drawing;
using System.Drawing.Imaging;
using System.Runtime.Versioning;
using Microsoft.AspNetCore.Mvc;
using Sphere10.Framework.Web.AspNetCore.MVC;

namespace MvcDemo.Controllers;

[SupportedOSPlatform("windows")]
public class BadgeController : Controller {
	[HttpGet("badge.png")]
	public IActionResult Badge() {
		var bitmap = new Bitmap(120, 24);
		using (var graphics = Graphics.FromImage(bitmap)) {
			graphics.Clear(Color.SteelBlue);
			graphics.DrawString("Sphere10", SystemFonts.DefaultFont, Brushes.White, 4, 4);
		}
		return new ImageResult(bitmap, ImageFormat.Png);
	}
}

The result disposes the bitmap after writing it, so the action does not dispose it. The one-argument constructor writes JPEG.

Filters, routing and URLs

Filters example

This controller exports a temporary file, deletes it after the response is written and logs each call through a filter that the service provider creates. Save it as Controllers/ReportsController.cs:

using System;
using System.Collections.Generic;
using System.IO;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.Extensions.Logging;
using Sphere10.Framework.Web.AspNetCore.MVC;

namespace MvcDemo.Controllers;

public sealed class AuditFilter : IActionFilter {
	private readonly ILogger<AuditFilter> _logger;

	public AuditFilter(ILogger<AuditFilter> logger) {
		_logger = logger;
	}

	public void OnActionExecuting(ActionExecutingContext context)
		=> _logger.LogInformation("Running {Action}", context.ActionDescriptor.DisplayName);

	public void OnActionExecuted(ActionExecutedContext context) {
	}
}

public sealed class AuditAttribute : FilterFactoryBase<AuditFilter> {
}

[Route("reports")]
public class ReportsController : Controller {
	[HttpGet("export")]
	[Audit]
	[Cleanup]
	public IActionResult Export() {
		var path = Path.GetTempFileName();
		System.IO.File.WriteAllText(path, "Name,Visits\nAlice,3\n");
		((List<Action>)ViewBag.Cleanup).Add(() => System.IO.File.Delete(path));
		return PhysicalFile(path, "text/csv", "report.csv");
	}
}

Register the filter before builder.Build() in Program.cs, because FilterFactoryBase resolves it from the request services:

builder.Services.AddScoped<MvcDemo.Controllers.AuditFilter>();

ViewBag.Cleanup is dynamic, so cast it to List<Action> before you add a lambda. CleanupAttribute runs the delegates after the file result has been sent, so /reports/export downloads the file before it is deleted.

Custom routes example

CustomRouteAttribute maps conventional routes without attribute routing on the controller. Save Controllers/HelpController.cs:

using Microsoft.AspNetCore.Mvc;
using Sphere10.Framework.Web.AspNetCore.MVC;

namespace MvcDemo.Controllers;

[CustomRoute("help/{topic}", DefaultAction = "Topic", Defaults = "topic=index")]
public class HelpController : Controller {
	public IActionResult Topic(string topic) => Content($"Help topic: {topic}");
}

Then register the routes of every controller in the assembly, before app.Run() in Program.cs:

using Sphere10.Framework.Web.AspNetCore.MVC;

CustomRouteAttribute.RegisterCustomRoutesFromAssembly(app, typeof(MvcDemo.Controllers.HelpController).Assembly);

/help/paging then returns Help topic: paging, and /help uses the default topic index. Defaults takes key=value pairs joined with &, and DefaultAction adds the action default.

Structure and dependencies

The project targets net10.0, and also net11.0 when a .NET 11 SDK builds it. It has a Microsoft.AspNetCore.App framework reference, project references to the shared Web.AspNetCore layer and to Drawing, and a Newtonsoft.Json package reference for the form types. The Drawing reference serves only ImageResult. The host-independent Web library suffices when an application needs only the web models.

Upgrading from the combined library

Releases up to 3.1.2 shipped these types inside Sphere10.Framework.Web.AspNetCore, in the Sphere10.Framework.Web.AspNetCore namespace. Reference this package and import Sphere10.Framework.Web.AspNetCore.MVC for the controller and view helpers, forms, filters, routing and results. Replace Tools.Web.AspNetCore.ToSelectList with Tools.Web.Mvc.ToSelectList. The hosting and HTTP types keep their namespaces in the shared package, and the sitemap, navigation and message models moved to Sphere10.Framework.Web.

The forms script is still an embedded resource rather than a static web asset. It moved from the Sphere10.Framework.Web.AspNetCore assembly, where its name was Sphere10.Framework.Web.AspNetCore.Forms.hydrogen-bootstrap-forms-1.0.0.js, to typeof(FormModelBase).Assembly under the name shown above.

Build and verification

From the repository root:

dotnet build src/Sphere10.Framework.Web.AspNetCore.MVC/Sphere10.Framework.Web.AspNetCore.MVC.csproj -p:BuildRevision=0
dotnet test tests/Sphere10.Framework.Web.AspNetCore.Tests -p:BuildRevision=0

The shared web tests check XmlResult status codes and sitemap output, enum list selection and sorting, the embedded script's resource name, asynchronous ImageResult output, FilterFactoryBase resolution, CustomRouteAttribute registration, and BootstrapFormScope completion, form method and overlay options, including a retry after a failed write and asynchronous disposal. The MVC tester is a minimal MVC host with one landing page for further controller and view demonstrations, and it does not include the contact form above. Package validation serves XmlResult output from an external consumer and checks it over HTTP. -p:BuildRevision=0 stops a local build from allocating the next build number.

Related projects

• Shared ASP.NET Core integration
• Web models and formatting
• Blazor application framework and CRUD grid
• Framework package and build guide