Ever since OpenForce '07 in Las Vegas last year I have found myself answering more questions regarding module development and being asked to provide training to more individuals.  I have decided that I should start creating more tutorials here that explain the module development process, therefore this article will be the first in a hopefully long series of DotNetNuke module development tutorials.  This article will walk you through the process of creating a new DotNetNuke module using the C# WAP Templates that are available from BiteTheBullet.co.uk.

Pre-Requisites

Prior to starting the items listed in the below tutorial you must have the following items installed and properly configured on your development machine.

• Visual Studio 2005 SP 1 (NOT Express Edition)
• DotNetNuke 4.x (Install OR source version)

To develop modules in DotNetNuke you may use the Install or Source version of DotNetNuke and it will NOT have any effect on your success in development of a custom module.  If you need assistance with installing DotNetNuke please see the tutorials available on this site.

Installing the templates

After you have verified that all pre-requisite installation items have been addressed you will need to install the module templates that are available from BiteTheBullet.co.uk.  You can download the templates using this link.

Simply double-click the .vsi file that is included in the zip package to start the installation.  The following screen will be displayed.

After clicking "Next" on that page you might see the following warning, simply click "Yes" to continue installing the templates.

The final screen will appear and you will then simply need to click "Finish" to complete the installation process.  Once this has completed successfully you are ready to move forward with the creation of the module.

Create the Project

Although a simple process the inital project creation is a common area that can quickly de-rail your attempt at successful DotNetNuke Module Development.  To create a new module project you will select New -> Project from the File menu within Visual Studio.

In the "New Project Window" select the "C# DNN Module Template", you should see a screen similar to the below.

In the name field you simply supply the name of the module that you are looking to create.  The location field is the most important field as this MUST be set to the /DesktopModules folder within your DotNetNuke installation and the checkbox for "Create folder for solution" must be unchecked!  Simply click "Ok" to create your module.

You now have the entire solution created, you will see a small welcome file that provides you with information regarding items that you need to do such as changing the namespaces of the project.

Building the Module

After you have created your project, you must build it before you can install it in your local DotNetNuke solution.  To do this simply select "Build Solution" from the Visual Studio build menu.

If you encounter multiple build errors, open the "References" folder and ensure that the "DotNetNuke.dll" reference was found.  If the reference does not exist successfully, remove it by right clicking on it and selecting "Remove".  Then re-add it using the "Add Resource' option, you will need to "Browse" to find the DotNetNuke.dll file which should be located in the bin directory of your DotNetNuke installation.  Once you have corrected the reference issue simply try the build process again!

Installing the Module

Installing the module is a very simple process.  You will first need to login to your DotNetNuke portal with host permissions.  Then navigate to the Module Definitions page which is available via the Host menu.  From this page, select "Import Module Definition" from the listing.  You will be taken to the following screen:

From the drop down for Manifests select the YourModule.dnn file, where YourModule is the name you used when creating the module project.  Once you have selected your .dnn file click "Install Manifest".  You should receive a long display that shows the installation progress and a success message in the end.

Typically this is the only step needed, however when using the "Import Manifest" method to install a module you must manually execute the SQL Scripts for your module.  This process is very simple.  Simply navigate to the SQL page available under the "Host" menu.  On this page you will be provided a "browse" button, use this button to browse to your folder location and select the "01.00.00.SqlDataProvider" file that was created with the project.  Click "Load" and the script should automatically load for you.  Check the "Run as Script" box, then simply click "Execute".

You should see a "Success" message, if you have the success message the demo module is successfully installed and you can now add it to any page.

Packaging the Module

The fastest method to package your module is to use the "Create Module Package" option within the Module Definitions page.  To access this functionality, go to Module Definitions and select the "edit" link next to your module.  Once in the module, you can select "Create Module Package" from the action menu.

Depending on your version of DotNetNuke your exact options on this page might vary slightly.  The below is an example from DNN 4.5.2.  On this page you can select options for the auto creation of a manifest file (.dnn) as well as supports private assembly Sub Folder.  If you are on a newer version of DNN you will have more options which will allow you to easily create PA installs only.  For the specific examples of a C# Module using WAP we would check the box for "Create Manifest File" and NOT check the PA Sub folder option.  After clicking create it will create your needed zip file, the file will be placed in the /Install/Modules folder of your DNN installation.

Where To Go From Here?

This article discusses the very basics of module development using the C# templates, but there are many things to be considered above and beyond this tutorial.  Below I will discuss some of these items.  If there are specific questions please let me know  I will look at creating follow-up articles in the future to cover some of these more advanced/detailed items.

Modify Namespaces

As mentioned earlier in the article the default module template places a starting namespace of YourCompany before all classes, pages, objects in your code.  This is something that in the long run you should change to represent a namespace that is unique to your business.  You can use the "Find/Replace in Files" option of Visual Studio to do this replacement, but I personally recommend a quick manual process to update this information to ensure that all changes are made successfully.

Modify SQL Script Prefixes

In addition to the default YourCompany prefix to all Namespaces all database tables and stored procedures created in the .SqlDataProvider file are pre-fixed with YourCompany_ before them.  For an actual module that you plan on implementing you should change this prefix to something specific to your organization AND project.  One item to note on this change is that you must not only change the code in the 01.00.00.SqlDataProvider and Uninstall.SqlDataProvider files but you must also change the hard coded prefix value that is stored in the SqlDataProvider.cs file in the Components folder.

Develop your Module

Obviously this tutorial walked you through the default template.  Sadly at this time there are no "blank" module templates so a major part of building your own module will involve removing the template code that does not apply to your project.  The key to continuing the development is to ensure that if you add/remove control files that you remember to update the .dnn file!

Edit Assembly Name

By default the assembly name is simply ProjectName.dll.  This might expose you to a risk with your module and another module having a conflicting name.  I highly recommend modifying the the project properties to have a more unique assembly name.  I personally use ICG.Modules.ModuleName.dll for all of my modules, prefixing the ICG.Modules to identify my company (IowaComputerGurus) and the fact that it is a module.

Summary and Feedback

I hope that this article has served as a good overview of how to use the C# module templates to build a WAP module.  I know that this was covered in a high level manner to ensure that I could keep the length of the article short enough to keep everyone reading.  If you have questions/comments about this article please leave your feedback below, otherwise if you need technical assistance getting started please visit my forum!