Open-source eCommerce platform for C# and ASP.NET Core 10 with MongoDB. Build multi-store shops and multi-vendor marketplaces with B2B/B2C, REST API, plugins, Vue 3 and Docker.
Request Lifecycle
How a storefront or admin HTTP request becomes a rendered page. Read this before adding a controller action, middleware, or anything that depends on "the current customer/store".
Startup
src/Web/Grand.Web/Program.cs is deliberately thin:
var builder = WebApplication.CreateBuilder(args);
builder.Configuration.AddAppSettingsJsonFile(args);
builder.AddServiceDefaults();
StartupBase.ConfigureServices(builder.Services, builder.Configuration);
builder.ConfigureApplicationSettings();
builder.Services.RegisterTasks(builder.Configuration);
var app = builder.Build();
StartupBase.ConfigureRequestPipeline(app, builder.Environment);
await app.RunAsync();
Everything else is discovered. StartupBase (src/Core/Grand.Infrastructure/StartupBase.cs) scans assemblies — including installed plugins and modules — for IStartupApplication and runs them ordered by Priority.
Never add registrations to Program.cs. Add an IStartupApplication in the project that owns the service.
IStartupApplication
public interface IStartupApplication
{
void ConfigureServices(IServiceCollection services, IConfiguration configuration);
void Configure(WebApplication application, IWebHostEnvironment webHostEnvironment);
int Priority { get; }
bool BeforeConfigure { get; }
}
ConfigureServices— DI registrations. Runs for every implementation, ordered byPriority.Configure— middleware. Runs in two passes: allBeforeConfigure == trueimplementations first (ordered byPriority), then allBeforeConfigure == false.Priority— lower runs earlier. Observed values inGrand.Web.Common/Startup/:Priority Startup Purpose -50UrlRewriteStartuprewrites before anything else sees the path -40HostFilteringStartup-20ForwardedHeadersStartupmust run before scheme/IP is read -10ErrorHandlerStartupwraps everything below it 0StartupApplicationcore service registrations 100GrandCommonStartupstatic files, powered-by, common middleware 500AuthenticationStartupauth + context middleware 501LoggerStartup1000GrandMvcStartupendpoints — last 10plugin startups (e.g. Theme.Modern)
Pick a plugin/module priority by copying the nearest comparable component, not by inventing a number.
Per-request pipeline
Ordered by the startups above:
- Host filtering / forwarded headers / URL rewrite — the request's real host, scheme, and path are settled.
- Error handling — wraps everything downstream.
- Static files, powered-by header (
GrandCommonStartup). - Install redirect —
InstallUrlMiddlewaresends traffic to the installer when the DB is not installed. - Authentication —
UseGrandAuthentication(). ContextMiddleware— the important one, see below.CultureSettingMiddleware— setsCultureInfofrom the resolved working language.- Endpoint routing / MVC (
GrandMvcStartup, priority 1000).
ContextMiddleware
src/Web/Grand.Web.Common/Middleware/ContextMiddleware.cs resolves the ambient context for the request and stores it on IContextAccessor:
contextAccessor.StoreContext = await storeContextSetter.InitializeStoreContext();
contextAccessor.WorkContext = await workContextSetter.InitializeWorkContext(
contextAccessor.StoreContext.CurrentStore.Id);
Consequences:
- Store is resolved before customer. Customer resolution depends on the store — see
.ai/knowledge/scoping.md. IWorkContextis not populated for requests whose route matches the skip list:/scalar/{documentName},/openapi/{documentName}.json,install. Code reachable from those endpoints must not assume a current customer.- Anything that runs before
ContextMiddleware(priority < 500) cannot readIWorkContext. - Background work — scheduled tasks, message queue processing — has no HTTP request and therefore no ambient context. Such code must take the store/customer explicitly. See
.ai/skills/scheduled-task.md.
IWorkContext exposes: CurrentCustomer, OriginalCustomerIfImpersonated, CurrentVendor, WorkingLanguage, WorkingCurrency, StoreManager, TaxDisplayType.
Controller → response
Controller action
└─ IMediator.Send(GetSomethingQuery) ← Grand.Web/Features/Handlers/…
└─ handler
└─ business service (Grand.Business.*)
└─ ICacheBase.GetAsync(key, …) ← Grand.Infrastructure/Caching
└─ IRepository<T> ← Grand.Data
└─ MongoDB
└─ View(model)
└─ theme view-location resolution ← IThemeView, see theme-creation skill
└─ Razor view + view components + widget zones
Rules that fall out of this:
- Controllers hold no business logic. They resolve input, send a mediator request, and return a result.
- Query handlers live in
Features/Handlers/, command handlers inCommands/Handler/, mirroring the request type's folder. - Handlers prepare view models. Business services do not know about view models.
- Caching sits in the business service, wrapping the repository call — not in the handler or controller.
- Repository access happens through
IRepository<T>. The business layer never sees aMongoCollection. - After a write, the service publishes an entity event and clears the affected cache prefix. See
.ai/knowledge/domain-events.mdand.ai/knowledge/caching.md.
View resolution
The active theme's IThemeView.GetViewLocations() is consulted before the default locations, so a theme overrides only the views it ships and everything else falls through to Grand.Web/Views. Widget zones are expanded by the core Widget view component, which asks every installed IWidgetProvider whether it renders in that zone.
Where things go
| You are adding | Put it in |
|---|---|
| A page | controller action + mediator query + handler + view model + view |
| A cross-cutting request concern | middleware registered from an IStartupApplication |
| Service registration | IStartupApplication.ConfigureServices in the owning project |
| Something that must run before auth | IStartupApplication with BeforeConfigure = true and a low Priority |
| Something with no HTTP request | IScheduleTask, with explicit store/customer parameters |