Module development with DNN 9 and Visual Studio Community 2017

How to create a module for DNN 9 (DotNetNuke) based on your own C# ASP.NET Web page

I explain to how setup and development environment using Visual Studio Community 2017. The modules will be creating with help of the DNN9 templates. The setup is prepared for development with ASP.NET Core and Razor.

Overview
First I will share some notes on the installation of the required packages.
Then we get DNN9 up and running on a local machine.
Then we setup visual studio for creating and debugging your own modules.

For installation on a local Windows 10 PC you need the following software:

• Internet information service (IIS)
• Visual Studio Community 2017
• SQL Server 2017 Express

Then we download DNN9, configure IIS to create a site based on DNN9 that can run on your local computer and configure DNN9 with help of the DNN installation Wizard.

1. Install IIS

After installing windows, the internet information service (IIS) manager window is not available. In the Control panel, Programs and features, select ‘Turn Windows features on or off’
In the selection tree, enable the following items:

• Internet Information Service
  • Web Management Tools
    • II6 Management compatibility
      • IIS6 Management console
      • IIS6 Metabase and IIS6 configuration compatibility
    • IIS Management Console
  • World Wide Web Service
    • Application Development Features
      • .NET Extensibility 4.6 or 4.7
      • ASP.NET Extensibility 4.6 or 4.7 (includes ISAPI Extensions and filters)
    • Common HTTP Features
      • Default Document
      • Static Content
    • Health and Diagnostics
      • Custom logging
    • Performance features
      • Dynamic Content Compression
      • Static Content Compression
    • Security
      • Basic Authentication
      • Request filtering
      • Windows Authentication

Press [Ok] and wait for the packages to be downloaded and installed.
Verify IIS is running by typing ‘inetmgr’ in the start menu.
Ad item named ‘Internet Information Service (IIS) Manager’ should appear.

2. Visual Studio Community 2017

Download and run the Visual Studio Community 2017 installer.
Select the following components to be installed:

• .NET desktop development
• ASP.NET and web development
• Data storage and processing
• .NET Core cross-platform development

3. SQL Server 2017 Express

The Standard database setup of DNN will probably look for an SQL service named SQLEXPRESS. If you have older installations (instances) of SQL servers you can remove them before you continue the installation. Via mmc.exe (Microsoft Management Tools) you can add a snap-in for SQL Server Contiguration manager to examine the SQL services that are running on the PC.

Download the installer.
Select Basic installation.
Install SSMS. (The button in the SQL Server 2017 Express installation will direct you to download SQL Server Management Studio 1.74.)

4. Download and extract DNN9

In the website https://github.com/dnnsoftware locate the DNN.Platform repository.
Select ‘Releases’.
Download only the install package, for example a file named ‘DNN_Platform_9.1.1.129-232_Install.zip’

Create a folder on your PC where the DNN9 files will be located later, we will configure IIS to run a website from the folder.
The folder can be located in any path but must be named ‘dnndev.me’.

Extract the content of the DNN install zip files into the dnndev.me folder.
The contents of the dnndev.me folder should now show folders like admin, App_Browers, App_Data, etc… These are all the files needed to run a DNN website.

Set the access right for the new folder. Right click on the dnndev.me folder and select ‘Properties’. Go to the ‘Securiy’ tab.
Edit the group or user names list. And add a new user names ‘iis apppool\dnndev.me’. Give this user the modify permission for (the folder) dnndev.me

5. Create WebSite for DNN in IIS

Start the IIS manager by typing ‘inetmgr’ in the start menu. A GUI will open where you can localte the current sites on your PC at the left side.
There will already be an ‘default web site’ and we will add a new website (for DNN) by clicking ‘Add Website…’ on the ‘Sites’ icon.

Configure the new website

• Site name: dnndev.me
• Physical path: C:\…your chosen path here…\dnndev.me
• Host name: dnndev.me

Test the website by navigation with your browser to http://dnndev.me
A DNN website installation page should be shown now.

The DNN website must run in an application pool supported by .NET 4. Select ”Application pools’item at the left site, and make sure the ‘DefaultAppPool’ has the .NET framework v4.30319 selected.

If the DNN installation page is not shown, you can try re-install the ASP.NET framework with a command line (Run as admin):

%windir%\Microsoft.NET\Framework64\v4.0.30319\aspnet_regiis.exe -i

 

6. Installation of DNN9

Let’s continue with the installation and configuration of the DNN9 website.
First enter a password for the host user.

To allow use of SQL Express, select ‘default’ for the Database information option.

To test the local instance of the DNN website, click browse from the IIS manager, or start any browser and enter http://dnndev.me/. This URL is mapped for DNN developer to the localhost address 127.0.0.1.

7. Install DNN 9 Extension templates for Visual Studio

The DNN 9 Extension templates can be downloaded from the Visual Studio Online Extensions repository.
From the Tools menu, select ‘Extensions and updates’. Select ‘Online’ at the left side of the window and search for ‘DNN’. Select the ‘DotNetNuke (DNN) Development project templates’. I used version 9.0.1.
They are created by Chris Hammond and you can read about them here.

Press the ‘download’ button that appears on the found entry of the templates and restart Visual Studio.
In the restart, the VSIX installer will detect the new templates and you click ‘modify’.

Options for DNN will now be available under the Visual C# tab of ‘new projects’. Some templates are also available for Visual Basic.

8. Creating an empty DNN module

Open Visual Studio (Run As Administrator).
Create New project, Select the DotNetNuke templates under C#
And select the ‘DNN (DotNetNuke 8/9) C# DAL2 MVC Module’.
The location MUST be inside the ‘desktopmodules\mvc’ folder of the folder of your local website folder. Name used in this example is ‘module_x’
Uncheck the ‘create directory for solution folder’.
Change your information in the Project Setup Wizard. Keep the local dev url ‘dnndev.me’. If you change the namespace, do not forget to add a dot (.) at the end.
Build the project in release mode, it will create an installable package of the module in a new folder called ‘install’. The module_x_install.zip you will find in here can be loaded (as an extension) into the DNN website.

An overview of the folders and files in the created project:
It is made of a general/sample ‘Item’ and Settings for the module.

• AssemblyInfo.cs, version number of the module
• App_LocalResources, resource files, like string tables
• Buildscript, packaging while building the module
• Component, FeatureController (to implement specific DNN interfaces) and ItemManager for a collection of items. Item are the sample data object generated by the template.
• Controllers, ItemController and SettingsController for handle the service calls from the browser.
• Documentation, info about created project (can be deleted)
• Models, classes for Item and Settings
• Providers, SQL scripts needed to access module’s Items and Settings in a database
• Views, Subfolder for views for Items (e.g. Edit), Settings and Shared (e.g. _Layout and _ViewStart are top level objects that render and contain the module)
• License.txt, displayed to end user during installation
• module.css, custom css for this module
• packages.config, NuGet reference
• ReleaseNotes.txt, displayed to end user during installation
• Module_X.dnn, contains names, version, dependencies, references to sql scripts and the module defenitions.
• Web.Config, see description below

What is a web.config file?
A web.config file lets you customize the way your site or a specific directory on your site behaves. For example, if you place a web.config file in your root directory, it will affect your entire site (www.coolexample.com). If you place it in a /content directory, it will only affect that directory (www.coolexample.com/content). However, in order for a web.config file to register in a specific directory, there must be a web.config file in the root directory. Web.config files work on our Windows servers.

Using a web.config file, you can control:

• Database connection strings.
• Error behavior.
• Security.

web.config files are XML documents. “.config” is not an extension like .html or .txt. For more information on how to set up web.config files, visit Microsoft’s Web site.

9. Install the new DNN module as an extension

Login on the DNN website. Choose Extension from the Settings tab.
Click ‘Install Extension’. Locate the module_x_install.zip file inside the ‘desktopmodules\mvc\module_x\’ and install it as any other DNN extension.

To test it (see the content of empty module_x), create a new page in DNN and add the module_x to the page.

During the installation, the module_x.dll files (and config and pdb) is copied into the dnndev.me\bin folder.

10. Debugging the module with Visual Studio

First check if uses the template (or other projects) has not created a virtual directory in the DesktopModules folder of the website. Open IIS and remove any virtual directory. This will not delete the actual files in the DesktopModules.

• Select DEBUG and build your project
• Select a browser
• Click on Start Debugging (or use F5, or click the green arrow)
• The browser will open (and you may have to login to your website) You can also open your browser manually and navigate to dnndev.me
• Attach to the IIS worker process
  • Select Attach to process
  • Enable ‘Show all processes from all users’
  • Locate w3wp.exe in the list of running processed
  • Click ‘Attach’
• Place a breakpoint in your code file. A good start if the Index() function of your controller. The function that will create and return the view.
• The breakpoint must be indicated by a red dot to indicate the debugger is attached correctly.

When you navigate in your DNN website to a page that will contain the module_X of this example, then the breakpoint will trigger. You can now step through your code.

When you repeat your debugging your can select ‘Reattach to process’ as a shortcut. (Shift+Alt+P)