Example: Creating a Plug-In With Razor Pages

docs/en/PlugIn-Modules.md

@@ -55,7 +55,7 @@ There are two more built-in Plug-In Source implementations:
 
 If you need, you can create your own `IPlugInSource` implementation and add to the `options.PlugInSources` just like the others.
 
-## Creating a Simple Plug-In
+## Example: Creating a Simple Plug-In
 
 Create a simple **Class Library Project** in a solution:
 
@@ -120,4 +120,94 @@ Build the project, open the build folder, find the `MyPlugIn.dll`:
 
 Copy `MyPlugIn.dll` into the plug-in folder (`D:\Temp\MyPlugIns` for this example).
 
-If you have configured the main application like described above (see Basic Usage section), you should see the `MyService has been initialized` log in the application startup.
+If you have configured the main application like described above (see Basic Usage section), you should see the `MyService has been initialized` log in the application startup.
+
+## Example: Creating a Plug-In With Razor Pages
+
+Creating plug-ins with views inside requires a bit more attention.
+
+> This example assumes you've [created a new web application](https://abp.io/get-started) using the application startup template and MVC / Razor Pages UI.
+
+Create a new **Class Library** project in a solution:
+
+![simple-razor-plugin](images/simple-razor-plugin.png)
+
+Edit the `.csproj` file content:
+
+````xml
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+    <PropertyGroup>
+        <TargetFramework>net5.0</TargetFramework>
+        <OutputType>Library</OutputType>
+        <IsPackable>true</IsPackable>
+    </PropertyGroup>
+
+    <ItemGroup>
+      <PackageReference Include="Volo.Abp.AspNetCore.Mvc.UI.Theme.Shared" Version="4.0.1" />
+    </ItemGroup>
+
+</Project>
+````
+
+* Changed `Sdk` to `Microsoft.NET.Sdk.Web`.
+* Added `OutputType` and `IsPackable` properties.
+* Added `Volo.Abp.AspNetCore.Mvc.UI.Theme.Shared` NuGet package.
+
+> Depending on [Volo.Abp.AspNetCore.Mvc.UI.Theme.Shared](https://www.nuget.org/packages/Volo.Abp.AspNetCore.Mvc.UI.Theme.Shared) package is not required. You can reference to a more base package like [Volo.Abp.AspNetCore.Mvc](https://www.nuget.org/packages/Volo.Abp.AspNetCore.Mvc/). However, if you will build a UI page/component, it is suggested to reference to the [Volo.Abp.AspNetCore.Mvc.UI.Theme.Shared](https://www.nuget.org/packages/Volo.Abp.AspNetCore.Mvc.UI.Theme.Shared) package since it is the most high-level package without depending on a particular [theme](UI/AspNetCore/Theming.md). If there is no problem to depend on a particular theme, you can directly reference to the theme's package to be able to use the theme-specific features in your plug-in.
+
+Then create your module class in the plug-in:
+
+````csharp
+using System.IO;
+using System.Reflection;
+using Microsoft.AspNetCore.Mvc.ApplicationParts;
+using Microsoft.Extensions.DependencyInjection;
+using Volo.Abp.AspNetCore.Mvc.UI.Theme.Shared;
+using Volo.Abp.Modularity;
+
+namespace MyMvcUIPlugIn
+{
+    [DependsOn(typeof(AbpAspNetCoreMvcUiThemeSharedModule))]
+    public class MyMvcUIPlugInModule : AbpModule
+    {
+        public override void PreConfigureServices(ServiceConfigurationContext context)
+        {
+            PreConfigure<IMvcBuilder>(mvcBuilder =>
+            {
+                //Add plugin assembly
+                mvcBuilder.PartManager.ApplicationParts.Add(new AssemblyPart(typeof(MyMvcUIPlugInModule).Assembly));
+
+                //Add views assembly
+                var viewDllPath = Path.Combine(Path.GetDirectoryName(typeof(MyMvcUIPlugInModule).Assembly.Location), "MyMvcUIPlugIn.Views.dll");
+                var viewAssembly = new CompiledRazorAssemblyPart(Assembly.LoadFrom(viewDllPath));
+                mvcBuilder.PartManager.ApplicationParts.Add(viewAssembly);
+            });
+        }
+    }
+}
+````
+
+* Depending on the `AbpAspNetCoreMvcUiThemeSharedModule` since we added the related NuGet package.
+* Adding the plug-in's assembly to the `PartManager` of ASP.NET Core MVC. This is required by ASP.NET Core. Otherwise, your controllers inside the plug-in doesn't work.
+* Adding the plug-in's views assembly to the `PartManager` of ASP.NET Core MVC. This is required by ASP.NET Core. Otherwise, your views inside the plug-in doesn't work.
+
+You can now add a razor page, like `MyPlugInPage.cshtml` inside the `Pages` folder:
+
+````html
+@page
+@model MyMvcUIPlugIn.Pages.MyPlugInPage
+<h1>Welcome to my plug-in page</h1>
+<p>This page is located inside a plug-in module! :)</p>
+````
+
+Now, you can build the plug-in project. It will produce the following output:
+
+![simple-razor-plug-in-dll-file](images/simple-razor-plug-in-dll-file.png)
+
+Copy the `MyMvcUIPlugIn.dll` and `MyMvcUIPlugIn.Views.dll` into the plug-in folder (`D:\Temp\MyPlugIns` for this example).
+
+If you have configured the main application like described above (see Basic Usage section), you should be able to visit the `/MyPlugInPage` URL when your application:
+
+![simple-plugin-output](images/simple-plugin-output.png)
+