How to develop a simple EPiServer 7.5 MVC BlockType Add-On

The goal of this post is to explain how to develop a very simple BlockType Add-On for EPiServer 7.5 which uses ASP.Net MVC to render its template(s).

This post won't be covering more complex Add-Ons which comprise of PageTypes, Media and Properties.

The example in this post is to create a BlockType Add-On which can be added to the content area of existing pages in the target EPiServer site.

If you're interested in developing PageType Add-Ons (or any other content type), then I can only suggest that Google is your friend :-)

This post assumes that you have set-up your development environment as per my previous post How to setup a EpiServer 7.5 Add-On Development Environment.

If you haven't, you can still follow along with this tutorial but will need to make some adjustments here and there - I will try to make it obvious where.

---

The first thing to do is to create a new project in Visual Studio for your Add-On.

I have personally found it is best to start with an empty Web Application project and build from there - this helps avoid unneccessary DLLs bloating your Add-On.

I have written this post by following the below steps in Visual Studio 2013:

1. Assuming you already have an EPiServer Site solution open (as per the '' solution in my Dev Env Setup post referenced aboave), add a new project to it:
• Right click in Solution Explorer > Add > New Project > Web > ASP.Net Web Application
• Name the project as you would like your Add-On to be called e.g. "AwesomeWidget"
• In the 'New ASP.Net Project' dialog:
• Choose 'Empty'
• Tick 'MVC' to include folders and core references for an MVC site (this is necessary in order to develop a Add-On which conforms to EPiServer 7's MVC pattern)
• It is quite likely that the MVC template will download the latest MVC NuGet packages (version 5.0.0.0 at the time of writing). However, the EPiServer Website templates use MVC 4. 
• So, it is advisable to change the version of MVC for your Add-On project back to version 4 (via the NuGet Package Manager for your solution) - otherwise, when you go to install your Add-On, it will fail because the Add-On will require MVC version 5.
2. In order to keep your Add-On project focussed solely on the development of a BlockType Add-On:
• Delete the following from the project:
• The 'Models' folder
• The 'AppStart' folder
• The 'Web.Debug.config' and 'Web.Release.config' files
3. To enable the development of EPiServer Add-Ons, the new project needs to reference some EPiServer DLLs.
• You can either:
1. Use NuGet to include the required Packages/DLLs
• Assuming you have a target EPiServer Website setup already in your solution (as per my post How to setup a EpiServer 7.5 Add-On Development Environment), then you should be able to reference the required packages from a solution level.
• It is advisable to make sure you have the latest EPiServer packages:
• Right click the Solution in VS > Manauge NuGet Packages For Solution > Updates > EPiServer Feed > Update All
• If you don't see the EPiServer Feed, select 'All' under Updates and just selectively update all the EPiServer packages
• Right click the Solution in VS > Manage NuGet Packages For Solution
• Find the following packages and add them to your Add-On project:
• EPiServer.CMS.Core
• EPiServer.Framework
  
  OR
2. Reference them directly:
1. Open your Solution folder in Windows Explorer
2. Create a 'lib' folder and add the following EPiServer DLLs (you can copy them from any EPiServer site setup via the Visual Studio EPiServer Extenstion templates)
1. EPiServer.BaseLibrary
2. EPiServer.Data
3. EPiServer
4. EPiServer.Shell
• Not sure if this step should be included in case people want to reference DLLs via Nuget???
• To add a reference to the EPiServer DLLs via the Nuget packages:
• Right click the Solution > Manage NuGet Packages for Solution
• Select EPiServer.CMS.Core > Manage
• Tick the box for your Add-On project to have it reference the EPiServer.CMS.Core package
4. Create a new BlockType:
• Add a new folder at the root called 'BlockTypes'
• New class under 'BlockTypes' called 'AwesomeBlockType'
• NOTE: Name should correspond to the name of the project i.e. 'MyGreatWidget' should have a BlockType called 'MyGreatBlockType'
• Make the new BlockType inherit from 'EPiServer.Core.BlockData'
• Decorate the new BlockType with the 'EPiServer.DataAnnotations.ContentType' attribute and give it a new GUID value like:
  [ContentType(GUID = "new-guid-goes-here")]
• Add whatever properties your Add-On BlockType should have. For example, my Awesome widgets will be displaying an 'Awesome Image' and some 'Awesome Text' below it. So my AwesomeBlockType class will have two properties and look like:
• NOTE: Ensure you properties are declared as 'virtual' - required by EPiServer
5. Now add a Razor view to render your BlockType. 
• Within the 'Views' folder, add a new folder with the name of your Add-On e.g. 'AwesomeBlockType'
• Add a view in that folder with the same name e.g. 'AwesomeBlockType.cshtml'
• Set the model of the view to be the BlockType class you created earlier:
  e.g. @model AwesomeWidget.BlockTypes.AwesomeBlockType
• Now markup the View as you would like your Add-On to render...
• I want my AwesomeWidget to display the image stored at the 'AwesomePicUrl' and then display the 'AwesomeText' below it. So my view markup is:
• If you want more help with EPiServer Helpers and view markup, I'd suggest Google is your friend
• Now add a Controller to serve up your view for your BlockType
• Add an MVC controller with the name of your BlockType e.g. AwesomeBlockTypeController
• Make the controller inherit from 'asdf'
• Add an Index action method like this:
• Important things to note:
• The input parameter MUST be called 'currentBlock' - this is an EPiServer convention, if mis-spelled EPiServer will not populate the parameter correctly and it will be null
• The Paths.ToResource method is provided by EPiServer to enable Views to be located relative to the Add-On installation folder
• Now you need to package up your Add-On into a NuGet package ready for installation in your target EPiServer site
• To get your environment setup for creating NuGet packages, follow these guidelines:
  Creating and Publishing a Package on http://docs.nuget.org 
• To conform to NuGet package specifications, fill in values for the Description and Company in AssemblyInfo.cs, for example:
  [assembly: AssemblyDescription("The most awesome of Widgets")]
  [assembly: AssemblyCompany("SYZYGY")]
• Rebuild the Add-On project
• Once thats done create the nuget spec by running the following nuget command:
  nuget spec
• It is required that you now edit the .spec file to include a special EPiServer tag to indicate that the package is an EPiServer Add-On
• You choose from either:
• EPiServerPublicModulePackage- this tag should be added for public add-ons
• EPiServerModulePackage - should be added in the tag list of protected add-ons
• Place the tag within the <tags> element in the *.spec file.
• Save the *.spec file and Clean/Rebuild the Add-On prject
• Now create the nuget package:
  nuget pack {projectname}
• Note that the version of the package is taken from the AssemblyVersion of the Add-On project
• Now you can attempt to install your Add-On in your target site via the CMS GUI:
• Start the target site and login
• From the Dashboard select 'Add-Ons' > 'Manual Upload' > 'Browse files'
• Select the newly created package and then click 'Install'
• If you get any seemingly stupid error messages such as:
  "Add-on 'AwesomeWidget 1.0.0.0' requires 'Some.Package (≥ 9.9.9)' to be installed." even though that package is installed in your target site, then the easiest thing to do is edit the .nupkg file in the NuGet Package Explorer and remove the dependencies. To learn more about this problem, see this post in the EPiServer Forum and again, Google is your friend.
• Now you can put your new BlockType to use:
• Create a new Block by clicking on the folder icon in top right hand corner
• Under 'Global Assets' select the drop down menu then 'New Block'
• If you already have some BlockTypes, then you should hopefully see your new BlockType available in the list, otherwise, if it's the only BlockType EPiServer will select it automatically and prompt you to give it a name.
• Fill in whatever properties you have for your Block i.e. I filled in the AwesomeUrl and AwesomeText.
• Save and Publish your new block
• Now add it to an existing page and watch the magic happen! (If you need help on how to create/publish a page and add Blocks to it, please refer to the EPiServer Documentation)

If you'd like another guideline on developing simple EPiServer Add-Ons (including WebForms views) see this article:

Developing simple add-on for EPiServer 7 Preview