Introduction This is a case study on how to create a new type of project under Microsoft Visual Studio .NET 2003 to support DotNetNuke modules. I'll create a Project Template which will implement the base skeleton of a DNN 2.0 module. With the arrival of DNN 2.0 it would be very interesting to share a base common framework for all developers, so module development could be managed in a more elegant way and to have a reference framework that will help a lot on the ease of sharing code and extending DotNetNuke. The most proper solution would be to implement an Enterprise Project Template, were you have plenty of options and tools to build a base framework. But the problem is you need VS.NET Enterprise, so the solution could be a bit out of range for most developers. Keeping this in mind I've build some wizards to extend Visual Studio to help on the creation of DNN modules. Another great value of this solution is it needs no registry modification, just some files copied to proper locations. 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 this 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. His templates share a common way of doing things (naming conventions, structure, functions,...). This structure was in someway discussen in this thread on 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 improuvement 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 This 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 This 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. To help the installation procedure and don't touch the Windows registry we'll put a full path to a dll. 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 this 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 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 create there 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 that 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 and 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.
What the Template Builds There are three project wizards: DNNModule, DNN SqlDataProvider and DNN AccessDataProvider.
(It's important for the DAL Wizards to follow the DNN naming scheme "[MODULENAME][PROVIDER]DataProvider") 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 uppon the project name, so it's important to name your project in a convenient way. The DNN SqlDataProvider builds (same for Access Provider): ModuleNameSQLDataProvider\
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 Start Visual Studio .NET 2003 and open your DotNetNuke solution. To create a new module project:
- On the New Project dialog box, select 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. 
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 or on the DNN folder of the Add New Item dialog box. 
Adding a data provider To add a data provider for you 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 same name as your module plus the data provider type (ModuleNameSqlDataProvider). 
Installation You should to close VS.NET before installing the templates, if not they'll not be available until you restart it. 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 you Visual Studio.NET 2003 folder, search for dnn*.* files and remove all encountered files. 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. (Install package 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 some installer for your programs)
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 pointed 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. If you want you use the C# templates, look for them under the Visual C# Projects folder of the New Project dialog in Visual Studio.NET. They work in the same way as the VB.NET templates. Since at this moment I'm not very confident of my C# knowledge I based most of the work on the Bonosoft DAL Builder ASP from BonoSoft. I made some changes to the generated code to adjust to my preferences and maintain the structure of the previous templates.
CodeSmith Templates One thing the VS.NET templates cannot do is connect to 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 on the task of writting the 'real' code against a 'real' database CodeSmith can save a lot of time. The templates I provide is a derivative work 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. As you can see there are the corresponding templates for both C# and VB. 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. The code adheres to new DNN 2.0 format so if there's no needed modification you can include this code in your PA install zip. 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.
Note: I use to create database object 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): More information on CodeSmith can be found here.
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 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 to: 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 | 
