diff --git a/docs/Getting-Started-AspNetCore-Application.md b/docs/Getting-Started-AspNetCore-Application.md new file mode 100644 index 0000000000..32c3de4eab --- /dev/null +++ b/docs/Getting-Started-AspNetCore-Application.md @@ -0,0 +1,153 @@ +## Getting Started ABP With AspNet Core MVC Web Application + +### Create A New Project + +1. Create a new empty AspNet Core Web Application from Visual Studio: + +![](images/create-new-aspnet-core-application.png) + +2. Select Empty Template + +![](images/select-empty-web-application.png) + +You could select another template, but I want to show it from a clear project. + +### Install Volo.Abp.AspNetCore.Mvc Package + +Volo.Abp.AspNetCore.Mvc is AspNet Core MVC integration package for ABP. So, install it to your project: + +```` +Install-Package Volo.Abp.AspNetCore.Mvc +```` + +### Create First ABP Module + +ABP is a modular framework and it requires a **startup (root) module** class derived from ``AbpModule``: + +````C# +using Microsoft.AspNetCore.Builder; +using Microsoft.AspNetCore.Hosting; +using Microsoft.Extensions.DependencyInjection; +using Volo.Abp; +using Volo.Abp.AspNetCore.Modularity; +using Volo.Abp.AspNetCore.Mvc; +using Volo.Abp.Modularity; + +namespace BasicAspNetCoreApplication +{ + [DependsOn(typeof(AbpAspNetCoreMvcModule))] + public class AppModule : AbpModule + { + public override void ConfigureServices(IServiceCollection services) + { + services.AddMvc(); + + services.AddAssemblyOf(); + } + + public override void OnApplicationInitialization(ApplicationInitializationContext context) + { + var app = context.GetApplicationBuilder(); + var env = context.GetEnvironment(); + + if (env.IsDevelopment()) + { + app.UseDeveloperExceptionPage(); + } + + app.UseMvcWithDefaultRoute(); + } + } +} +```` + +``AppModule`` is a good name for the startup module for an application. + +A module class can register services to Dependency Injection by overriding ``ConfigureServices`` method as shown here. ``AddAssemblyOf<...>`` is a special extension method of ABP that registers all services in an assembly by convention (TODO: link to DI document). While this is optional, a module generally registers some services. + +ABP packages define module classes and a module can depend on another module. In the code above, our ``AppModule`` depends on ``AbpAspNetCoreMvcModule`` (defined by Volo.Abp.AspNetCore.Mvc package). It's common to add a ``DependsOn`` attribute after installing a new ABP nuget package. + +Instead of Startup class, we are registering dependencies and configuring AspNet Core pipeline in this module class. + +### The Startup Class + +Next step is to modify Startup class to integrate to ABP module system: + +````C# +using System; +using Microsoft.AspNetCore.Builder; +using Microsoft.Extensions.DependencyInjection; + +namespace BasicAspNetCoreApplication +{ + public class Startup + { + public IServiceProvider ConfigureServices(IServiceCollection services) + { + services.AddApplication(); + + return services.BuildServiceProviderFromFactory(); + } + + public void Configure(IApplicationBuilder app) + { + app.InitializeApplication(); + } + } +} + +```` + +Changed ``ConfigureServices`` method to return ``IServiceProvider`` instead of ``void``. This change allows us to replace AspNet Core's Dependency Injection with another framework (see Autofac integration section below). ``services.AddApplication()`` adds all services defined in all modules beginning from the ``AppModule``. + +``app.InitializeApplication()`` call in ``Configure`` method initializes and starts the application. + +### Hello World! + +The application above does nothing. Let's create an MVC controller does something: + +````C# +using Microsoft.AspNetCore.Mvc; +using Volo.Abp.AspNetCore.Mvc; + +namespace BasicAspNetCoreApplication.Controllers +{ + public class HomeController : AbpController + { + public IActionResult Index() + { + return Content("Hello World!"); + } + } +} + +```` + +If you run the application, you will see a "Hello World!" message on the page. + +Devided ``HomeController`` from ``AbpController`` instead of standard ``Controller`` class. This is not required, but ``AbpController`` class has useful base properties and methods to make your development easier. + +### Using Autofac as Dependency Injection Framework + +While AspNet Core's Dependency Injection (DI) system is fine for basic requirements, Autofac provides advanced features like Property Injection and Method Interception which are required by ABP to perform advanced application framework features. + +Replacing AspNet Core's DI system by Autofac and integrating to ABP is easy. + +1. Install Volo.Abp.Autofac package + +```` +Install-Package Volo.Abp.Autofac +```` + +2. Change ``services.AddApplication();`` line in the ``Startup`` class as shown below: + +````C# +services.AddApplication(options => +{ + options.UseAutofac(); //Integrate to Autofac +}); +```` + +### Source Code + +Get source code of the sample project created in this tutorial from [here](../samples/BasicAspNetCoreApplication). \ No newline at end of file diff --git a/docs/Getting-Started-Console-Application.md b/docs/Getting-Started-Console-Application.md index 30c9d865d2..985a19bc02 100644 --- a/docs/Getting-Started-Console-Application.md +++ b/docs/Getting-Started-Console-Application.md @@ -34,7 +34,9 @@ namespace AbpConsoleDemo } ```` -``AppModule`` is a good name for the startup module for a console application. A module class can register services to Dependency Injection by overriding ``ConfigureServices`` method as shown here. ``AddAssemblyOf<...>`` is a special extension method of ABP that registers all services in an assembly by convention (TODO: link to DI document). While this is optional, a module generally registers some services. +``AppModule`` is a good name for the startup module for an application. + +A module class can register services to Dependency Injection by overriding ``ConfigureServices`` method as shown here. ``AddAssemblyOf<...>`` is a special extension method of ABP that registers all services in an assembly by convention (TODO: link to DI document). While this is optional, a module generally registers some services. ### Initialize The Application diff --git a/docs/Index.md b/docs/Index.md index ae05d01d9c..3f4f6a85cf 100644 --- a/docs/Index.md +++ b/docs/Index.md @@ -6,4 +6,4 @@ * Getting Started * With Console Application - * With ASP.NET Core Web Application \ No newline at end of file + * With ASP.NET Core Web Application \ No newline at end of file diff --git a/docs/images/create-new-aspnet-core-application.png b/docs/images/create-new-aspnet-core-application.png new file mode 100644 index 0000000000..fe78b9051d Binary files /dev/null and b/docs/images/create-new-aspnet-core-application.png differ diff --git a/docs/images/select-empty-web-application.png b/docs/images/select-empty-web-application.png new file mode 100644 index 0000000000..b0cd89a27a Binary files /dev/null and b/docs/images/select-empty-web-application.png differ diff --git a/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication.sln b/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication.sln new file mode 100644 index 0000000000..c5b53dea66 --- /dev/null +++ b/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication.sln @@ -0,0 +1,25 @@ + +Microsoft Visual Studio Solution File, Format Version 12.00 +# Visual Studio 15 +VisualStudioVersion = 15.0.27004.2002 +MinimumVisualStudioVersion = 10.0.40219.1 +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "BasicAspNetCoreApplication", "BasicAspNetCoreApplication\BasicAspNetCoreApplication.csproj", "{FDE52C9E-87E7-485F-B6E1-97C09E8254D7}" +EndProject +Global + GlobalSection(SolutionConfigurationPlatforms) = preSolution + Debug|Any CPU = Debug|Any CPU + Release|Any CPU = Release|Any CPU + EndGlobalSection + GlobalSection(ProjectConfigurationPlatforms) = postSolution + {FDE52C9E-87E7-485F-B6E1-97C09E8254D7}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {FDE52C9E-87E7-485F-B6E1-97C09E8254D7}.Debug|Any CPU.Build.0 = Debug|Any CPU + {FDE52C9E-87E7-485F-B6E1-97C09E8254D7}.Release|Any CPU.ActiveCfg = Release|Any CPU + {FDE52C9E-87E7-485F-B6E1-97C09E8254D7}.Release|Any CPU.Build.0 = Release|Any CPU + EndGlobalSection + GlobalSection(SolutionProperties) = preSolution + HideSolutionNode = FALSE + EndGlobalSection + GlobalSection(ExtensibilityGlobals) = postSolution + SolutionGuid = {BA01D8A1-8D4F-46A4-9BDB-30F327AE4605} + EndGlobalSection +EndGlobal diff --git a/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication/AppModule.cs b/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication/AppModule.cs new file mode 100644 index 0000000000..03b671b995 --- /dev/null +++ b/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication/AppModule.cs @@ -0,0 +1,34 @@ +using Microsoft.AspNetCore.Builder; +using Microsoft.AspNetCore.Hosting; +using Microsoft.Extensions.DependencyInjection; +using Volo.Abp; +using Volo.Abp.AspNetCore.Modularity; +using Volo.Abp.AspNetCore.Mvc; +using Volo.Abp.Modularity; + +namespace BasicAspNetCoreApplication +{ + [DependsOn(typeof(AbpAspNetCoreMvcModule))] + public class AppModule : AbpModule + { + public override void ConfigureServices(IServiceCollection services) + { + services.AddMvc(); + + services.AddAssemblyOf(); + } + + public override void OnApplicationInitialization(ApplicationInitializationContext context) + { + var app = context.GetApplicationBuilder(); + var env = context.GetEnvironment(); + + if (env.IsDevelopment()) + { + app.UseDeveloperExceptionPage(); + } + + app.UseMvcWithDefaultRoute(); + } + } +} \ No newline at end of file diff --git a/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication/BasicAspNetCoreApplication.csproj b/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication/BasicAspNetCoreApplication.csproj new file mode 100644 index 0000000000..0ac0472973 --- /dev/null +++ b/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication/BasicAspNetCoreApplication.csproj @@ -0,0 +1,17 @@ + + + + netcoreapp2.0 + + + + + + + + + + + + + diff --git a/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication/Controllers/HomeController.cs b/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication/Controllers/HomeController.cs new file mode 100644 index 0000000000..aa694a0fae --- /dev/null +++ b/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication/Controllers/HomeController.cs @@ -0,0 +1,13 @@ +using Microsoft.AspNetCore.Mvc; +using Volo.Abp.AspNetCore.Mvc; + +namespace BasicAspNetCoreApplication.Controllers +{ + public class HomeController : AbpController + { + public IActionResult Index() + { + return Content("Hello World!"); + } + } +} diff --git a/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication/Program.cs b/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication/Program.cs new file mode 100644 index 0000000000..380e69c4a7 --- /dev/null +++ b/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication/Program.cs @@ -0,0 +1,25 @@ +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Threading.Tasks; +using Microsoft.AspNetCore; +using Microsoft.AspNetCore.Hosting; +using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.Logging; + +namespace BasicAspNetCoreApplication +{ + public class Program + { + public static void Main(string[] args) + { + BuildWebHost(args).Run(); + } + + public static IWebHost BuildWebHost(string[] args) => + WebHost.CreateDefaultBuilder(args) + .UseStartup() + .Build(); + } +} diff --git a/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication/Properties/launchSettings.json b/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication/Properties/launchSettings.json new file mode 100644 index 0000000000..03755f8e91 --- /dev/null +++ b/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication/Properties/launchSettings.json @@ -0,0 +1,27 @@ +{ + "iisSettings": { + "windowsAuthentication": false, + "anonymousAuthentication": true, + "iisExpress": { + "applicationUrl": "http://localhost:63233/", + "sslPort": 0 + } + }, + "profiles": { + "IIS Express": { + "commandName": "IISExpress", + "launchBrowser": true, + "environmentVariables": { + "ASPNETCORE_ENVIRONMENT": "Development" + } + }, + "BasicAspNetCoreApplication": { + "commandName": "Project", + "launchBrowser": true, + "environmentVariables": { + "ASPNETCORE_ENVIRONMENT": "Development" + }, + "applicationUrl": "http://localhost:63234/" + } + } +} diff --git a/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication/Startup.cs b/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication/Startup.cs new file mode 100644 index 0000000000..fcf3161267 --- /dev/null +++ b/samples/BasicAspNetCoreApplication/BasicAspNetCoreApplication/Startup.cs @@ -0,0 +1,25 @@ +using System; +using Microsoft.AspNetCore.Builder; +using Microsoft.Extensions.DependencyInjection; +using Volo.Abp; + +namespace BasicAspNetCoreApplication +{ + public class Startup + { + public IServiceProvider ConfigureServices(IServiceCollection services) + { + services.AddApplication(options => + { + options.UseAutofac(); + }); + + return services.BuildServiceProviderFromFactory(); + } + + public void Configure(IApplicationBuilder app) + { + app.InitializeApplication(); + } + } +}