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)
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!DotNetNuke C# Compiled Module Starter Kit for DNN 4.x
New Version 1.0.1 for VS2008 and 1.0.3 for VS2005 - 21 July 2008
Fixed edit control to redirect to view control after deleting item.
New Version for Visual Studio 2008 - 13 May 2008
Designed to integrate with Visual Studio 2008
New Version 1.0.2 - 21 May 2007
Updated documentation file
Fix a bug in the .dnn file not updating the module folder name correct
Background
I read Michael Washington's tutorial on using Visual Studio 2005 and Web Application Projects to create compiled DotNetNuke Modules using the DNN Starter Kit but this is only available in Visual Basic.Net in the official starter kit. So I created my own starter kit that installs a template that works for C# that you can download.
Developing your modules using the compiled method means you don't need to give your source code away with your modules. Module development is more like creating modules in DNN 3.x.
You also get a great base from which you develop, with all the common files created and ready for you to modify for your own module.
To use this template you need to have Visual Studio 2005 and either Service Pack 1 or Web Application Project extension. This template won't work for Visual Web Developer.
You should already have DotNetNuke 4.x install on your local development machine.
In Use
Once you have the template installed you can create DotNetNuke 4.x module that you can then customise with your own code to create your module.
The template will create a project that can be compiled and installed in DotNetNuke without any modifications which is an excellent way to understand how modules are created in the first place.
Walk Thro
1. Download the starter kit below and double click to start the install process.
2. Once you have installed the starter kit you just need to start Visual Studio 2005 and you'll have a new template as shown below. Select this template and create a new project. Notice the location of where the module is created and that we have removed the tick to Create a directory for solution, these are very important settings.
3. Will now have a project that will contain the following items.
4. Edit the properties for the newly created project to have a root namespace, feel free to use something meaningful. Then you can start the build of the project.
You'll see the output for the project is placed in the bin folder of the root of the DotNetNuke install.
5. To install the module in your DotNetNuke install copy the text from the 01.00.00.SqlDataProvider file and login as host to the portal, select Host -> Sql paste the text from the file into the text box and tick Run as script then Execute.
6. Next we'll install the module into DotNetNuke, select Host -> Module Definitions select Create New Module for the Module Manifest drop down select your module's DNN file then Install.
7. If you look at the Supported Features options for the newly installed module it won't have picked up the interfaces the first time you install, so to fix this click the Update link which will then update the module and pickup the interfaces.
8. Then just add your module to a page and try it out.
That is it, you're already to develop your own DotNetNuke 4.x compiled modules in C#.
Fixed edit control to redirect to view control after deleting item.
New Version for Visual Studio 2008 - 13 May 2008
Designed to integrate with Visual Studio 2008
New Version 1.0.2 - 21 May 2007
Updated documentation file
Fix a bug in the .dnn file not updating the module folder name correct
Background
I read Michael Washington's tutorial on using Visual Studio 2005 and Web Application Projects to create compiled DotNetNuke Modules using the DNN Starter Kit but this is only available in Visual Basic.Net in the official starter kit. So I created my own starter kit that installs a template that works for C# that you can download.
You also get a great base from which you develop, with all the common files created and ready for you to modify for your own module.
To use this template you need to have Visual Studio 2005 and either Service Pack 1 or Web Application Project extension. This template won't work for Visual Web Developer.
You should already have DotNetNuke 4.x install on your local development machine.
In Use
Once you have the template installed you can create DotNetNuke 4.x module that you can then customise with your own code to create your module.
The template will create a project that can be compiled and installed in DotNetNuke without any modifications which is an excellent way to understand how modules are created in the first place.
Walk Thro
1. Download the starter kit below and double click to start the install process.
2. Once you have installed the starter kit you just need to start Visual Studio 2005 and you'll have a new template as shown below. Select this template and create a new project. Notice the location of where the module is created and that we have removed the tick to Create a directory for solution, these are very important settings.
3. Will now have a project that will contain the following items.
4. Edit the properties for the newly created project to have a root namespace, feel free to use something meaningful. Then you can start the build of the project.
You'll see the output for the project is placed in the bin folder of the root of the DotNetNuke install.
5. To install the module in your DotNetNuke install copy the text from the 01.00.00.SqlDataProvider file and login as host to the portal, select Host -> Sql paste the text from the file into the text box and tick Run as script then Execute.
6. Next we'll install the module into DotNetNuke, select Host -> Module Definitions select Create New Module for the Module Manifest drop down select your module's DNN file then Install.
7. If you look at the Supported Features options for the newly installed module it won't have picked up the interfaces the first time you install, so to fix this click the Update link which will then update the module and pickup the interfaces.
8. Then just add your module to a page and try it out.
That is it, you're already to develop your own DotNetNuke 4.x compiled modules in C#.
Posts
No comments:
Post a Comment