ASP.NET Core 1.0 Documentation

725 Pages·2016·9.87 MB·English

ASP.NET Core 1.0 Documentation
Microsoft
706,2016

Contents
1 Topics 3
1.1 IntroductiontoASP.NETCore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 GettingStarted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3 Tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4 Fundamentals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
1.5 MVC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
1.6 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
1.7 WorkingwithData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
1.8 Client-SideDevelopment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
1.9 Mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
1.10 PublishingandDeployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
1.11 GuidanceforHostingProviders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
1.12 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523
1.13 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642
1.14 Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656
1.15 Contribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
2 RelatedResources 717
3 Contribute 719
i
ii
ASP.NETCore1.0Documentation,
: ASP.NET5hasbeenrenamedtoASP.NETCore1.0. Readmore.
: Thisdocumentationisaworkinprogress. Topicsmarkedwitha areplaceholdersthathavenotbeenwrittenyet.
Youcantrackthestatusofthesetopicsthroughourpublicdocumentationissuetracker. Learnhowyoucancontribute
onGitHub.
Contents 1
ASP.NETCore1.0Documentation,
2 Contents
1
CHAPTER
Topics
1.1 Introduction to ASP.NET Core
ByDanielRoth,RickAndersonandShaunLuttin
ASP.NET Core is a significant redesign of ASP.NET. This topic introduces the new concepts in ASP.NET Core and
explainshowtheyhelpyoudevelopmodernwebapps.
Sections:
• WhatisASP.NETCore?
• WhybuildASP.NETCore?
• Applicationanatomy
• Startup
• Services
• Middleware
• Servers
• Contentroot
• Webroot
• Configuration
• Environments
• BuildwebUIandwebAPIsusingASP.NETCoreMVC
• Client-sidedevelopment
• Nextsteps
1.1.1 What is ASP.NET Core?
ASP.NET Core is a new open-source and cross-platform framework for building modern cloud based internet con-
nected applications, such as web apps, IoT apps and mobile backends. ASP.NET Core apps can run on .NET Core
oronthefull.NETFramework. Itwasarchitectedtoprovideanoptimizeddevelopmentframeworkforappsthatare
deployed to the cloud or run on-premises. It consists of modular components with minimal overhead, so you retain
flexibility while constructing your solutions. You can develop and run your ASP.NET Core apps cross-platform on
Windows,MacandLinux. ASP.NETCoreisopensourceatGitHub.
3
ASP.NETCore1.0Documentation,
1.1.2 Why build ASP.NET Core?
The first preview release of ASP.NET came out almost 15 years ago as part of the .NET Framework. Since then
millions of developers have used it to build and run great web apps, and over the years we have added and evolved
manycapabilitiestoit.
ASP.NETCorehasanumberofarchitecturalchangesthatresultinamuchleanerandmodularframework. ASP.NET
CoreisnolongerbasedonSystem.Web.dll. ItisbasedonasetofgranularandwellfactoredNuGetpackages. This
allowsyoutooptimizeyourapptoincludejusttheNuGetpackagesyouneed. Thebenefitsofasmallerappsurface
areaincludetightersecurity,reducedservicing,improvedperformance,anddecreasedcostsinapay-for-what-you-use
model.
WithASP.NETCoreyougainthefollowingfoundationalimprovements:
• AunifiedstoryforbuildingwebUIandwebAPIs
• Integrationofmodernclient-sideframeworksanddevelopmentworkflows
• Acloud-readyenvironment-basedconfigurationsystem
• Built-independencyinjection
• Newlight-weightandmodularHTTPrequestpipeline
• AbilitytohostonIISorself-hostinyourownprocess
• Builton.NETCore,whichsupportstrueside-by-sideappversioning
• ShipsentirelyasNuGetpackages
• Newtoolingthatsimplifiesmodernwebdevelopment
• Buildandruncross-platformASP.NETappsonWindows,MacandLinux
• Opensourceandcommunityfocused
1.1.3 Application anatomy
AnASP.NETCoreappissimplyaconsoleappthatcreatesawebserverinitsMainmethod:
using System;
using Microsoft.AspNetCore.Hosting;
namespace aspnetcoreapp
{
public class Program
{
public static void Main(string[] args)
{
var host = new WebHostBuilder()
.UseKestrel()
.UseStartup<Startup>()
.Build();
host.Run();
}
}
}
MainusesWebHostBuilder,whichfollowsthebuilderpattern,tocreateawebapplicationhost. Thebuilderhas
methodsthatdefinethewebserver(forexampleUseKestrel)andthestartupclass(UseStartup).Intheexample
above,theKestrelwebserverisused,butotherwebserverscanbespecified. We’llshowmoreaboutUseStartup
4 Chapter1. Topics
ASP.NETCore1.0Documentation,
in the next section. WebHostBuilder provides many optional methods including UseIISIntegration for
hosting in IIS and IIS Express and UseContentRoot for specifying the root content directory. The Build and
RunmethodsbuildtheIWebHostthatwillhosttheappandstartitlisteningforincomingHTTPrequests.
1.1.4 Startup
TheUseStartupmethodonWebHostBuilderspecifiestheStartupclassforyourapp.
public class Program
{
public static void Main(string[] args)
{
var host = new WebHostBuilder()
.UseKestrel()
.UseStartup<Startup>()
.Build();
host.Run();
}
}
TheStartupclassiswhereyoudefinetherequesthandlingpipelineandwhereanyservicesneededbytheappare
configured. TheStartupclassmustbepublicandcontainthefollowingmethods:
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
}
public void Configure(IApplicationBuilder app)
{
}
}
• ConfigureServices defines the services (see Services below) used by your app (such as the ASP.NET
MVCCoreframework,EntityFrameworkCore,Identity,etc.)
• Configuredefinesthemiddlewareintherequestpipeline
• SeeApplicationStartupformoredetails
1.1.5 Services
A service is a component that is intended for common consumption in an application. Services are made available
through dependency injection. ASP.NET Core includes a simple built-in inversion of control (IoC) container that
supports constructor injection by default, but can be easily replaced with your IoC container of choice. In addition
to its loose coupling benefit, DI makes services available throughout your app. For example, Logging is available
throughoutyourapp. SeeDependencyInjectionformoredetails.
1.1.6 Middleware
InASP.NETCoreyoucomposeyourrequestpipelineusingMiddleware. ASP.NETCoremiddlewareperformsasyn-
chronouslogiconanHttpContextandtheneitherinvokesthenextmiddlewareinthesequenceorterminatesthe
1.1. IntroductiontoASP.NETCore 5
ASP.NETCore1.0Documentation,
request directly. You generally “Use” middleware by invoking a corresponding UseXYZ extension method on the
IApplicationBuilderintheConfiguremethod.
ASP.NETCorecomeswitharichsetofprebuiltmiddleware:
• Staticfiles
• Routing
• Authentication
Youcanalsoauthoryourowncustommiddleware.
YoucanuseanyOWIN-basedmiddlewarewithASP.NETCore. SeeOpenWebInterfacefor.NET(OWIN)fordetails.
1.1.7 Servers
TheASP.NETCorehostingmodeldoesnotdirectlylistenforrequests;ratheritreliesonanHTTPserverimplemen-
tationtoforwardtherequesttotheapplication. Theforwardedrequestiswrappedasasetoffeatureinterfacesthatthe
application then composes into an HttpContext. ASP.NET Core includes a managed cross-platform web server,
calledKestrel,thatyouwouldtypicallyrunbehindaproductionwebserverlikeIISornginx.
1.1.8 Content root
The content root is the base path to any content used by the app, such as its views and web content. By default the
content root is the same as application base path for the executable hosting the app; an alternative location can be
specifiedwithWebHostBuilder.
1.1.9 Web root
Thewebrootofyourappisthedirectoryinyourprojectforpublic,staticresourceslikecss,js,andimagefiles. The
staticfilesmiddlewarewillonlyservefilesfromthewebrootdirectory(andsub-directories)bydefault. Thewebroot
pathdefaultsto<contentroot>/wwwroot,butyoucanspecifyadifferentlocationusingtheWebHostBuilder.
1.1.10 Configuration
ASP.NETCoreusesanewconfigurationmodelforhandlingsimplename-valuepairs. Thenewconfigurationmodel
is not based on System.Configuration or web.config; rather, it pulls from an ordered set of configuration
providers. Thebuilt-inconfigurationproviderssupportavarietyoffileformats(XML,JSON,INI)andenvironment
variablestoenableenvironment-basedconfiguration. Youcanalsowriteyourowncustomconfigurationproviders.
SeeConfigurationformoreinformation.
1.1.11 Environments
Environments, like“Development”and“Production”, areafirst-classnotioninASP.NETCoreandcanbesetusing
environmentvariables. SeeWorkingwithMultipleEnvironmentsformoreinformation.
6 Chapter1. Topics