Introduction

In this page you will find some brief description on how to build Visual Studio.Net Project Templates for DotNetNuke.

The main goal for this project was to provide a simple yet powerful way to extend VS.NET to support DotNetNuke module creation. As the DotNetNuke framework increases its complexity and features being on top of best practices for coding and developing modules can at times a bit difficult. With these templates, VS.NET includes new features directly focussed to DNN developers.

Another great benefit of this solution is it eases the task of starting a new module from a 'blank project':

• what should I do first?
• what files do I need?
• how should I structure the project?
• how a DotNetNuke module is built?

The templates will build a default skeleton for the new project, including the most common files needed, prewritten code in these files with the required structure for a DotNetNuke module, ...

Visual Basic and Visual C#
A template is nothing more than a couple of files of any kind that get created when you select either New Project or Add New Item in VS.NET. Any of the builtin options you find in these dialogs are templates that can be modified and extended at your will. All you need is the proper understanding of its internals. Keep in mind too, that a template that generates code is highly tied to the development language of choice. So for example in a VB template you have to provide the pattern .vb file that will be the base for the generated code.
I started these templates with only a VB.NET version, but due to 'popular' demand there's now a corresponding VC# counterpart. Both VB and C# templates are installed in the same way, and there's no need to remove any of them. Just use what language you prefer. They offer the same functionallity.

Microsoft Visual Studio .NET 2002 Users
The VS.NET 2002 Templates are a conversion of the 2003 version. I'll not maintain this version since I'm not able to test it. Look on the VS.NET 2002 Templates page for the changes needed to make the VS.NET 2003 Templates work on the previous version.

Note that this is not a finished and closed work. As I polish my own framework I'll be upgrading these templates to reflect what I find helpfull. I'm publishing it mainly to get some reactions, suggestions, extensions, modifications, on what I've done. These templates share a common way of doing things (naming conventions, structure, functions,...). This structure was in someway discussen in this thread on the ASP.NET Forums. I recommend you to read the posts in this thread to gain a better understanding of what's going in. If you have any suggestion, question or improvement don't hesitate to contact me. I'll do my best to answer any questions and will be very happy to get some help on this work.

Note. There's also a download of CodeSmith templates to ease on the creation of the code (database and VB.NET). It's based on some modifications from a great work from Scott McCulloch.

Wizards

With Visual Studio .NET you have the option to create templates of any kind of file. The templates can include some parameters which will be substituted on instantiation. All this templates are orchestrated by what they call Wizards. A wizard is comprised of a standard folder structure, plus some javascript files, plus some templates.

The folder structure for VB is shown below (only needed folders):

\Microsoft Visual Studio .NET 2003
    \Vb7
        \VBProjectItems
        \VBProjects
        \VBWizards

Under VBProjects you'll find two diferent types of files: .VSZ and .VSDIR.

VSZ files

These are the files VS.NET looks at to launch Wizards. We will create a file called DNNModule.vsz which will reference our wizard. The format is as follows:

VSWIZARD 6.0
Wizard=VsWizard.VsWizardEngine.7.1
Param="WIZARD_NAME = DNNModule"
Param="WIZARD_UI = FALSE"
Param="PROJECT_TYPE = VBPROJ"

The WIZARD_NAME parameter tells VS.NET the folder under VBWizards where the wizard actually is. For more information on VSZ files look here.

VSDIR files

These are the files VS.NET looks at to configure the "Add Item" and "New Project" dialog boxes. We can have as many vsdir files as you want since VS.NET will look at every one. So we will create a file called dnnprojects.vsdir with this content:

DNNModule.vsz| |DNN Module|1|A project for creating DNN module|
<Full path to dll>DNNIcons.dll|
100| 1|ModuleName|Web
(break lines inserted for clarity)

Here we define the contents of the dialog box. The only trick here is the DNNIcons.dll reference. We have the option to reference a GUID or a full path to a resource file. We'll use a full path to a dll to reference the icons resource library. For more information on VSDIR files look here.

Project Wizard

As we have stated on the VSZ file our wizard will be called DNNModule. Next thing is to create a folder structure like this:

\VBWizards
    \DNNModule
        \Scripts
            \1033
        \Templates
            \1033

Under the Scripts\1033 folder we should create a javascript file called default.js. This file will tell VS.NET what to do with the template files. Under the Templates\1033 folder we will create any template file we want to include in our final project template.

For more information on these files you can look at:
- Building a Custom Web Form Wizard in Visual Studio .NET
- Building a Custom Project Wizard in Visual Studio .NET
- Extending the Visual Studio Environment

Item File Wizards

We've looked at how to create a project wizard, but when it is already created maybe we'll need another copy of any of those files created. So instead of doing a copy-paste-replace we can create some wizards for any kind of file we want.

Under VBProjectItems\Web Project Items folder we'll find the same folder structure of the Add New Item dialog box. We'll add the folder VBProjectItems\Web Project Items\DNN and there we will create a VSDIR file (DNNProjectItems.vsdir) with this content:

..\..\DNNUserControl.vsz| |DNN User Control|1|DNN User Control|
<Full path to dll>DNNIcons.dll|
103| |WebUserControl.ascx

..\..\DNNDAL.vsz| |DNN DataProvider abstract class|1|
DNN DataProvider abstract class (ModuleNameDataProvider.vb)|
<Full path to dll>DNNIcons.dll|
100| |ModuleDataProvider.vb

..\..\DNNInstallFile.vsz| |DNN Install File|1|DNN Install File (ModuleName.dnn)|
<Full path to dll>DNNIcons.dll|
102| |ModuleName.dnn

..\..\DNNBLL.vsz| |DNN Business Logic Layer|1|DNN Business Logic Layer (ModuleNameDB.vb)|
<Full path to dll>DNNIcons.dll|
100| |ModuleDB.vb
(break lines inserted for clarity)

If we want the new DNN file items appear on the main folder of the dialog box, we can add this file to VBProjectItems\Web Project Items and adjust the relative path at the beginning of each line.

Then we should create the vsz files under the main VBProjectItems folder. Here is the DNNBLL.vsz file as an example:

VSWIZARD 6.0
Wizard=VsWizard.VsWizardEngine.7.1
Param="WIZARD_NAME = DNNBLL"
Param="WIZARD_UI = FALSE"
Param="PROJECT_TYPE = VBPROJ"

All we need to do finally is repeat the folder structure we created for the project but now for every file wizard. Then configure the default.js and template files as needed for any file type.

Installation

You should close VS.NET before installing the templates, if not they'll not be available until you restart it.

Since the DotNetNuke framework API has changed a lot from version 2 to version 3, the templates need to cover each version in a different maner. There are two different downloads, one for each version. Install the versions you need, they can coexist in the same machine without problems.

There is no need to uninstall or delete any previous version of the templates, each new version will overwrite older files without problem. If you ever want to uninstall the templates, go to your Visual Studio.NET 2003 folder, search for dnn*.* files and remove all encountered files.

Note: If you had previously installed any version previous to 2.6 I highly recommend that you delete all dnn*.* files in Visual Studio.NET 2003 folder. The new versions support a clear installation that will make both versions work without problems in VS.NET.

Download the installer, save the file to any folder on your disk and run. It will ask for the folder where Microsoft Visual Studio.NET 2003 is installed and for a <CompanyName>. Enter the desired folder and company information and install the templates.

The last page of the installer will show you the Change Log file with all modifications in each version. Read it carefully to know which changes the new version carries.

(The install package was built with Inno Setup, a free installer for Windows programs from Jordan Russell. This is really an impressive tool, take a look if you need an installer for your programs)

What the Template Builds

There are three project wizards: DNNModule, DNN SqlDataProvider and DNN SkinObject (version 2 also has an AccessSqlDataProvider).
The DNN Module builds a folder structure like follows:

ModuleName\
    Components\
       DataProvider.vb          DAL
       ModuleNameBLL.vb         BLL
    Documentation\            Folder for documentation
    Installation\             Folder for PA installation files
       ModuleName.dnn
       ModuleName.zip
    Providers\                 Folder for providers projects
    AssemblyInfo.vb
    ModuleName.ascx             Main user control
    ModuleName.ascs.vb
    ModuleNameEdit.ascx         Edit user control
    ModuleNameEdit.ascx.vb
    ModuleNameOptions.ascx      Options user control
    ModuleNameOptions.ascx.vb
    ModuleName.vbproj           Project file 
    icon_ModuleName_32pix.gif
    ModuleName.css

Note that all files are named based on the project name, so it's important to name your project in a convenient way.

The DNN SqlDataProvider builds (same for Access Provider):

ModuleName.SQLDataProvider\
    AssemblyInfo.vb
    ModuleNameSQLDataProvider.vbproj   Project file
    SQLDataProvider.vb                 Data provider implementation
    01.00.00.SqlDataProvider           Install script file
    Uninstall.SqlDataProvider          Uninstall script file

How to use the wizard

The following steps will be slightly different depending on the DotNetNuke version your module should be. Pictures displayed in this page are for version 3.

Start Visual Studio .NET 2003 and open your DotNetNuke solution.
 If using version 2 the solution MUST contain the main DotNetNuke project.
 If using version 3 the solution MUST contain the main DotNetNuke project and the BuildSupport project. You can use the solution file DotNetNuke\Solutions\DotNetNuke.Core\DotNetNuke.Core.sln as an example.

The wizards need these projects to correctly setup all references and follow the recommended build structure used by the Core solutions.

To create a new module project:
- On the New Project dialog box, select the DotNetNuke folder version you are interested. Then select the DNN Module project type and give the name of your module. This will create a base skeleton for our project to help you start coding. Make sure you select Add to Solution if not you will create a new solution.

Important: As a good practice all modules should be developed under the folder DesktopModules in your main DotNetNuke folder. This guide will assume this folder is used.

This will create a new project on the open solution and add some files to it.

Adding new files to your project

If we want to add any new DNN file to our project we should look under the main Local Project Items folder and then on the desired DNN folder version of the Add New Item dialog box.

Adding a data provider

To add a data provider for your module select the desired data provider project under the New Project dialog box. Navigate to the providers folder under your Module folder and give the project the name:

• if using version 2: the same name as your module plus the data provider type (Example: ModuleNameSqlDataProvider).
• if using version 3: the same name as your module (Example: ModuleName). The wizard will append the provider type to the end of the project name.

Important: DataProviders should be created in the Providers folder under the ModuleName folder. This is a required setting for the providers wizards to work.

VS.NET 2002 Templates

For a template to work under VS.NET 2002 you must make the following changes:
Changes in Project Files (*.vbproj)
From:

ProductVersion = "7.10.3077"
SchemaVersion = "2.0"

To:

ProductVersion = "7.0.9466"
SchemaVersion = "1.0"

Changes in Wizard Files (*.vsz)
From:

Wizard=VsWizard.VsWizardEngine.7.1

To:

Wizard=VsWizard.VsWizardEngine

So if you are using VS.NET 2002 download the latest version for 2003 make the changes indicated here and it should work. If you have any problem, feel free to contact me with detailed information on the error and I'll try to help.
(Thanks to Gaston Vaessen for this information)

C# Templates

From v2.4 I'll provide the corresponding C# templates in the same downloading package. The building process for a C# project template is slightly different from a VB template. So the previous steps and structure may differ a bit for the C# templates, but the essence is the same.

CodeSmith Templates

One thing the VS.NET templates cannot do is connect to your database and generate code according to your real tables information. So all code in the VS.NET templates are given as an example of how things should be done.

To speed up the task of writting the 'real' code against a 'real' database CodeSmith can save a lot of time. The templates I provide are a derivative of some great templates  from Scott McCulloch. Most of my work is based on his initial template. I just added some features and reordered things to adjust to my framework.

How to use CodeSmith.

After you have a module created with the templates you need the real code to connect to you database and tables. So, nearly all code in BLL, DataProvider.vb and SqlDataProvider and AccessDataProvider can be discarded, we'll generate it from CodeSmith. All you need to do is create the tables.

CodeSmith v3.0 templates are for DotNetNuke v3.

CodeSmith v1.2 templates are for DotNetNuke v2.

Start CodeSmith Explorer, navigate to the folder where you have the templates and run them:

• StoredProcedures.cst will generate all code to get, insert, update... data from your database. To run it manually against the DB you'll have to replace {databaseOwner} and {objectQualifier} with proper values.
• SqlDataProvider.cst will generate the code to add to your SqlDataProvider to connect to the previously generated stored procedures.
• DataProvider.cst. This is the module data abstract layer (which goes to DataProvider.vb)
• BusinessObject.cst. This template will generate the BLL for each table your module uses. The code should go to <tablename>BLL.vb. (Version 1.2)
• BLL Controller Class.cst and BLL Info Class.cst. These two templates will generate the two classes that were previously in BusinessObject.cst. They are now separated to follow DotNetNuke v3 standards.

Note: I use to create database objects using a diferent naming convention than the one used by DNN. I name my objects with a module prefix, a table prefix and a operation name suffix. I prefer this solution so all stored procedures related to any given module and table are displayed grouped in SqlServer Manager (or any other tool). So for a module [Test] which includes a table [Testing] I'll have these stored procedures (for example):

• Test_TestingGet
• Test_TestingInsert
• Test_TestingDelete
• ...

But, in VB.NET code I reverse the convention so when an object of a given type is created, when you type "." to get the object members, the operation is in front. Note that here tablename is not present. When we instantiate a new object controller we know which table are we working on, so repeating tablename for each method is a bit redundant and unnecessary. So for a TestingController object I'll have (for example):

• Get(...)
• Add(...)
• ...

More information on CodeSmith can be found here.

NOTE: These templates were created for CodeSmith version 2.5 / 2.6. If you download latest version (3.0) you will get some errors. Either you can use the previous version or follow the steps outlined in this thread to modify the templates so they can be run on CodeSmith 3.0

TODO

Here is a list of things I plan to include on the templates:

• Comment style for VBCommentor, NDoc or others
• ...

If you have any other ideas please contact me with some detail on them and we'll try to implement.

Revision History

15-12-2004. v2.6

• VS.NET New folder structure to allow for version 2 and 3 to coexist.

24-05-2004. v2.5

• Updated installation procedure
• New project type: DNN SkinObject
• All methods use new naming convention object.[Operation](params)
• All VB projects with OptionStrict=On
• Update VB DataProviders to use local GetNull function
• Change control names t module.ascx, moduleEdit.ascx, moduleOptions.ascx
• Update .dnn file to use module.ascx, moduleEdit.ascx, moduleOptions.ascx
• Update .dnn install file. Change folder name from "PROJECTNAME" to "COMPANYNAME – PROJECTNAME”
• Include GetNull function in SQLDataProvider
• DotNetNuke project reference copylocal=false to all projects
• PA project reference copylocal=false to DataProvider projects

05/05/2004.

• Added a template for a ModuleCommunicator control and a ModuleListener control
• All code in controls is now in a Try / Catch block so if there's an error it can be traced

04/05/2004. v2.4

• Added C# templates 
• Added install and uninstall files for data providers 
• Icon file moved from installation folder to main module folder (which is where it should stay) 
• Minor changes in some files

01/05/2004.

• Added support for VS.NET 2002.

23/04/2004.

• Updated an issue with the editModule control.

28/03/2004 v2.3.

• Made some clean up to correct sintax errors. Now all should compile without errors. 
• .dnn install file now reflects 2.0 structure 
• .css file renamed to "module.css" so it's correctly referenced by skin engine

26/03/2004 v2.2.

• No excluded folders 
• Collapse references 
• No more desktopmoduletitle 
• Add options control ( with update / cancel ) 
• Add actions registration on main module control 
• Add edit control (with update / delete / cancel ) 
• Refine some code

29/02/2004.

• Corrected issue with install script (it didn't use the appropiate <CompanyName>)

26/02/2004.

• Changed the project type from webproject to classlibrary. 
• All assemblies are built to [DotNetNukefolder]\bin 
• Changes on Namespaces to reflect following style: <YOURCOMPANYNAME>.DNN.Modules.<MODULENAME> <YOURCOMPANYNAME>.DNN.Modules.<MODULENAME>.Data

• Assemblies named accordingly:
  <YOURCOMPANYNAME>.DNN.Modules.<MODULENAME> <YOURCOMPANYNAME>.DNN.Modules.<MODULENAME>.SqlDataProvider

08/02/2004.

• Corrected an issue with the default name of generated assembly on SqlDataProvider and AccessDataProvider project templates. It should build an assembly with name [yourModuleName].AccessDataProvider.dll and [yourModuleName].SqlDataProvider.dll 
• Corrected sintax error on DnnModule project template (on code behind file module.ascx.vb)

28/01/2004.

• Added SqlDataProvider, AccessDataProvider projects 
• Changed namespace from DotNetNuke to DotNetNuke.ModuleName 
• Added edit icon 
• Added blank css file 
• Added foders for documentation, installation and providers 
• Add TODO comments for the Task List window

23/01/2004. Initial version

Revision History

20-01-2005. v3

• Added support to generate code for multiple tables at the same time
• Get method adds moduleid to where clause
• BLL split into controller and Info Classes
• Added support for optional interfaces

31-05-2004.

• corrected an issue with DbType.Binary column type: was byte[] should be byte()

15-05-2004. v1.2

• Method names changes in Business Objects t [operation](params) 
• C# version