DamianEdwards
commented
8 years ago Goals
We are trying to:
- Make dynamic HTML and forms with ASP.NET Core easier, e.g. how many files & concepts required to print Hello World in a page, build a CRUD form, etc.
- Reduce the number of files and folder-structure required for page-focused MVC scenarios
- Simplify the code required to implement common page-focused patterns, e.g. dynamic pages, CRUD forms, PRG, etc.
- Enable the ability to return non-HTML responses when necessary, e.g. 404s
- Use and expose the existing MVC primitives as much as possible, e.g.:
- Model binding
- Model validation
- Model meta-data
- Action filters (the ones that make sense)
- Action results
- HTML Helpers
- Tag Helpers
- Existing Razor directives, e.g. @inject
- Layouts & partials
- _ViewStart.cshtml & _ViewImports.cshtml (should we support _PageStart.cshtml & _PageImports.cshtml instead/as well?)
- Allow straightforward migration to traditional MVC structure
- Do this at a reasonable cost, e.g. 1-2 developers during 1.1 release
Non-goals
We are not trying to:
- Create a scripted page framework to compete with PHP, etc.
- Hide C# with a DSL in Razor or otherwise
- Create new primitives that are only applicable here (i.e. they should be usable in traditionally structured MVC apps too)
- Create undue burdens for us with regards to tooling support, etc.
Enabling
Packaging
The "MVC View Pages" feature will ship in a standalone package, e.g. Microsoft.AspNetCore.Mvc.Razor.ViewPages, that will be referenced by the MVC meta-package, Microsoft.AspNetCore.Mvc. Users of the lower-level Microsoft.AspNetCore.Mvc.Core package can bring in the MVC Pages package to enable it without using the meta-package.
Startup
The IServiceCollection.AddMvc() and IApplicationBuilder.UseMvc() extension methods will enable MVC Pages by default. There will be appropriate extension methods to enable MVC Pages explicitly in the cases where these extensions methods are not used, e.g. when using IServiceCollection.AddMvcCore().
@page directive
MVC pages are represented by CSHTML files that use the new @page directive. This directive instructs the MVC Razor host to treat the CSHTML file as a standalone page for the purposes of request handling.
e.g.
@page
Hello, World! It's @DateTime.Now on the server@class block directive
MVC pages can add members to the generated class using the new @class block directive. This directive is effectively an alias of the existing @functions directive. All members added to the class are available to the page during request processing.
Page Actions
Public methods added to the page class in the @class block are candidates for handling request processing, much like action methods on MVC controllers. Methods that match the selection rules become Page Actions, and one (or none) will be selected as the handling Page Action for any given request to the page.
Action Selection
Action selection is based on simple HTTP verb name matching, with support for the prefix On, e.g.: GET requests will match methods called Get or OnGet, POST requests will match methods called Post or OnPost.
Situations that result in more than one action matching are an error should throw an exception (like an ambiguous action selection error in a controller).
If no actions are matched, the page will simply render.
Action Results
Page Actions must return an IActionResult. Typically this will be a ViewResult that renders the current page, e.g. return View();, but any IActionResult is supported. This allows pages to return non-HTML results, e.g. 404 not found, or even JSON or other formats if so desired.
e.g.:
@page
@class {
public IActionResult OnGet()
{
return View();
}
}
Hello, World!Parameter Binding
Parameters of Page Actions will be populated using model-binding, just like action methods are in MVC controllers. As such, it will support binding of simple and complex types from the registered value providers, e.g. query string, form, cookie, route data, etc., and model-binders.
e.g.:
@page
@class {
public IActionResult OnGet(int? id)
{
if (id.HasValue && id < 0)
{
return NotFound();
}
return View();
}
}
Found!Properties & Helper Methods
Members in the @class block are available to the page during execution of the page action and during rendering, making it easy to pass data between the two stages.
e.g.
@page
@class {
public IActionResult OnGet(int? id)
{
if (id.HasValue && id < 0)
{
return NotFound();
}
Id = id;
return View();
}
public int? Id { get; set; }
}
Id = @Id@model directive
The @model directive can be used to declare the model type for the page. It will generate a Model property on the page class of the declared type, as well as using the model type as the generic type argument for the IHtmlHelper<T> instance available to the page.
@page
@model Customer
@class {
public IActionResult OnGet(int? id)
{
if (id.HasValue && id < 0)
{
return NotFound();
}
var model = new Customer { Id = id, FirstName = "Jane", LastName = "Smith" };
return View(model);
}
}
Customer: @Model.FirstName @Model.LastNameInline View Models using @model & @class
Unlike on views, the @model directive will not change the base type of the generated page class to a generic variant. This is to allow the page the ability to declare nested classes in its @class block and use those as the model type with @model.
e.g.
@page
@model ViewModel
@class {
public IActionResult OnGet(int? id)
{
return id.HasValue && id < 0
? NotFound()
: View(new ViewModel {
Customer = new Customer {
Id = id,
FirstName = "Jane",
LastName = "Smith"
}
});
}
public class ViewModel
{
public Customer Customer { get; set; }
}
}
Customer: @Model.Customer.FirstName @Model.Customer.LastNameCode-behind class
IDEA: Class of same-name as page file will be automatically used as base type, not sure if this is a good idea, could be hard to make work in expected way reliably.
@inherits directive
The @inherits directive can be used to change the type that the generated page class will derive from. The type specified can be a POCO, or derive from the page base type in MVC (TBD). This way, code can be separated from the CSHTML file and placed in a CS file that it is compiled with the application (rather than as part of the CSHTML compilation process, either at runtime or as part of view pre-compilation).
In the case the base type is a POCO, the existing contextualizing attributes can be placed on properties of the appropriate types to gain access to relevant context objects from MVC, i.e. they will be set to the current instances during page activation, e.g. [HttpContext]. (We might possibly end up with some new context types, e.g. PageContext, in order to make the members appropriate for pages)
e.g.
public class MyPage : Page
{
public IActionResult OnGet(int? id)
{
Id = id;
return View();
}
public int? Id { get; set; }
}@page
@inherits MyPage
Id was @Id@inject directive
Yeah, you can use the @inject directive to generate properties that have instances injected from the DI container, just like in views., e.g. @inject AppDbContext Db
@{ } code blocks
They work just like they do in views and run as part of page rendering.
Page URLs
The path to the page file from the configured pages root path (defaults to IHostingEnvironment.ContentRootPath), including the file name, but excluding the file extension, becomes the URL that the page will be served in response to. Pages with a file name of "Index.cshtml" will also act as the default page for the sub-path (folder) they are in, e.g.:
| Page Path | URL |
|---|---|
| /Foo.cshtml | /foo |
| /Foo/Bar.cshtml | /foo/bar |
| /Index.cshtml | /index |
| /Index.cshtml | / |
| /Foo/Index.cshtml | /foo/ |
Explicit routing using conventional routes
TODO: routeBuilder.MapPageRoute("customers/{id}", "Customer.cshtml")
Explicit routing using attribute routes
TODO: Using attribute routes on the base class when using @inherits
Anti-forgery (CSRF protection)
TODO
Examples
Hello World
Project Structure
Index.cshtml
Program.cs
project.jsonProgram.cs
using System.IO;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;
namespace HelloWorld
{
public static class Program
{
public static void Main(string[] args)
{
var host = new WebHostBuilder()
.SetContentRoot(Directory.GetCurrentDirectory())
.UseKestrel()
.UseStartup<Startup>()
.Build();
host.Run();
}
public class Startup
{
public void ConfigureServices(IServiceCollection services) => services.AddMvcPages();
public void Configure(IApplicationBuilder app) => app.UseMvcPages();
}
}
}Index.cshtml
@page
Hello, World! It's @DateTime.NowSingle-page CRUD
Project Structure
Data/
AppDbContext.cs
Customer.cs
wwwroot/
[static files]
_Layout.cshtml
_ValidationScripts.cshtml
appsettings.json
Customers.cshtml
Program.cs
project.json
Startup.csProgram.cs
using System.IO;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;
namespace HelloWorld
{
public static class Program
{
public static void Main(string[] args)
{
var host = new WebHostBuilder()
.SetContentRoot(Directory.GetCurrentDirectory())
.UseKestrel()
.UseStartup<Startup>()
.Build();
host.Run();
}
public class Startup
{
public Startup(IHostingEnvironment env)
{
var builder = new ConfigurationBuilder()
.SetBasePath(env.ContentRootPath)
.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true);
Configuration = builder.Build();
}
public IConfigurationRoot Configuration { get; }
public void ConfigureServices(IServiceCollection services)
{
services.AddDbContext<AppDbContext>(options =>
options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection")));
services.AddMvcPages();
}
public void Configure(IApplicationBuilder app)
{
app.UseStaticFiles();
app.UseMvcPages();
}
}
}
}Data/Customer.cs
namespace MyApp.Data
{
public class Customer
{
public string FirstName { get; set; }
public string LastName { get; set; }
public string DateTimeOffset BirthDate { get; set; }
public string FavoriteDrink { get; set; }
}
}Data/AppDbContext.cs
namespace MyApp.Data
{
public class AppDbContext : DbContext
{
public AppDbContext(DbContextOptions<AppDbContext> options)
: base(options)
{
}
public DbSet<Customer> Customers { get; set; }
}
}Customers.cshtml
@page
@using MyApp.Data
@model ViewModel
@inject AppDbContext Db
@class {
public IActionResult OnGet(int? id)
{
var customer = id.HasValue ? await Db.Customers.SingleOrDefaultAsync(c => c.Id == id) : (Customer)null;
return id.HasValue && customer == null ?
NotFound() :
View(new ViewModel {
Customer = customer,
Title = customer != null ? $"Edit Customer {customer?.Id}" : "New Customer"
});
}
public IActionResult OnPost(ViewModel model)
{
if (!ModelState.IsValid())
{
// Model errors, just return the view to show them the errors
model.Title = "Edit Customer";
return View(model);
}
if (!model.Customer.Id.HasValue)
{
// Create
Db.Customers.Add(model.Customer);
ViewModel.AlertMessage = $"New customer {model.Customer.Id} created successfully!";
}
else
{
// Update
Db.Attach(model.Customer, EntityState.Changed);
ViewModel.AlertMessage = $"Customer {model.Customer.Id} updated successfully!";
}
await Db.SaveChangesAsync();
return Reload(new { id = model.Customer.Id });
}
public class ViewModel
{
public string Title { get; set; }
public string AlertMessage
{
get { return TempData[nameof(AlertMessage)]; }
set { TempData[nameof(AlertMessage)] = value; }
}
public bool ShowAlertMessage => !string.IsNullOrEmpty(AlertMessage);
public Customer Customer { get; set; }
public bool ShowAdultOnlyThings => (DateTimeOffset.UtcNow - Customer.BirthDate).TotalYears >= 21;
}
}
@{
Layout = "_Layout.cshtml";
ViewData["Title"] = Model.Title;
}
<form method="post" role="form">
@if (Model.ShowAlertMessage)
{
<div class="alert alert-dismissible" role="alert">
<button type="button" class="close" data-dismiss="alert" aria-label="Close"><span aria-hidden="true">×</span></button>
@Model.AlertMessage
</div>
}
<div asp-validation-summary="All" class="text-danger"></div>
<div class="form-group">
<label asp-for="Model.Customer.FirstName"></label>
<input asp-for="Model.Customer.FirstName" class="form-control" />
<span asp-validation-for="Model.Customer.FirstName" class="help-block text-danger"></span>
</div>
<div class="form-group">
<label asp-for="Model.Customer.LastName"></label>
<input asp-for="Model.Customer.LastName" class="form-control" />
<span asp-validation-for="Model.Customer.LastName" class="help-block text-danger"></span>
</div>
<div class="form-group">
<label asp-for="Model.Customer.BirthDate"></label>
<input asp-for="Model.Customer.BirthDate" class="form-control" />
<span asp-validation-for="Model.Customer.BirthDate" class="help-block text-danger"></span>
</div>
@if (Model.ShowAdultStuff)
{
<div class="form-group">
<label asp-for="Model.Customer.FavoriteDrink"></label>
<input asp-for="Model.Customer.FavoriteDrink" class="form-control" />
<span asp-validation-for="Model.Customer.FavoriteDrink" class="help-block text-danger"></span>
</div>
}
<button type="submit" class="btn btn-primary">Save</button>
</form>
@section "Scripts" {
<partial name="_ValidationScripts" />
}
mikebrind
ctyar
rynowak
sqmgh
JohnMuller44
andrewlock
AbubakarIdris
villanus
sirus-codes
robertboeckel
miloush
dstelow
jnm2
Eilon
dustinmoris
iamzm
We will support a simple model where a user can crate a CSHTML page that can handle requests but still use the primitives of MVC.
| 57 | 10153 | Reported By: Yishai Galatzer |