UPDATE 11/23/2010: I've released a new version of these templates that no longer uses the NANT Build scripts, they now use MSBuild. For more info check out this blog post
UPDATE 8/21/2010: I have now released a Visual Basic template, you can use either the C# or VB.net template, with the instructions below. The VB template is available on the same page as the C# version, you will need to change the path of the template location for the VB version.
Two days ago I posted a blog about configuring a DotNetNuke development environment, in preparation for today’s blog post about a C# module development template that I recently released on Codeplex. So today’s blog post is about how to utilize the template, customizing the VSTemplate file to fit your needs with company name, namespace, email, and URL. Installing the template, and then creating a quick and easy module using the template.
- Configuring your development environment
- This post
- Configuring NAnt to package your DotNetNuke Modules
If you haven’t read my post about setting up your development environment I encourage you to do so before proceeding, as the steps I’m going to walk you through below assume you are running a similar environment to me. The following assumes you are using DotNetNuke V5+ and Visual Studio 2008, if you are using an older version of DNN and Visual Studio there are no guarantees that this template will do anything for you except cause pain. It’s time to upgrade folks! DNN 5 rocks!
Ideas behind this template and projects using the template
The Visual Studio Template discussed in this blog post is designed using the WAP model, web application project. This means that your module will be compiled into it’s own DLL, with a simple reference to the DotNetNuke DLL(s). You do not open up the source code of DNN, there is no need, you can easily debug your module, package your module, and deploy your module using this template and the methods discussed in this and the other blog posts in this series. There are other ways to do DNN module development, and other tutorials on how to do module development, but this is the method I choose to use in my own development, and the one I show to people when they are having problems getting their head around module development in DNN.
Intro to Visual Studio Templates
If you’ve never use a visual studio template in your development in the IDE you are missing out! Custom templates are a great way to get specific project types up and running quickly. Installation of these templates is easy, and if you feel like digging into them further than we are going to do in this blog, you can really create some cool templates. The template we are discussing today can be found at http://christoctemplate.codeplex.com, in a later section I’ll actually talk about downloading and using the files, but for now I’ll provide an overview of why the template exists and what it provides.
After many years of module development I’ve come up with my preferred ways of doing things, often times because of struggles along the way, and other times just to make things faster. The template I’ve put together includes a basic shell for creating a DNN module, you get three different User Controls (ASCX files) one for View, one for Edit and one for Settings. These user controls inherit from specific base classes, which themselves inherit from base classes that DotNetNuke itself provides for modules to use, PortalModuleBase and ModuleSettingsBase. In addition to the ASCX files there are Localization files, .RESX files in the app_localresources directory that DNN will utilize for localizing strings within your module.
By utilizing this template in your C# Module development you can easily get a project up, compiling and even packaged (packaging with NANT will be discussed in a blog post later this week) within seconds. With a few minor changes to the project file you can easily get your module running within your DotNetNuke website and debugable. There are some additional files within the template for the Manifest information for DNN, a BUILD script for packaging with NANT, and even a stub’d module.css file. The module that gets created with this package doesn’t have any functionality in terms of displaying information or interacting with the user controls, it wasn’t intended to provide functionality out of the box, but it does provide a great launching point for starting your development for DNN.
Downloading the Visual Studio Template
Downloading and using the template is fairly straight forward, you can go to the project page at http://christoctemplate.codeplex.com/, click on the releases link on the side of the page and you can download the template, it comes as a ZIP file. Now, before we go about installing the template, I will talk about customizing the template for those of you who are interested in doing so.
Customizing the Visual Studio Template
Templates are really pretty easy to customize, and I’ve tried to make this one easier than normal with the instructions here. Out of the box this template will create a module with the namespace of com.christoc.dnn.PROJECTNAME, an email address of modules@christoc.com, website of http://www.christoc.com/ and a company name of Christoc.com. When you create a project all of this information will be spread throughout the files for that project. So rather than you going out and spreading christoc.com love around you can modify these four settings prior to installing the template. When you download the template from http://christoctemplate.codeplex.com/ you get a ZIP file, that ZIP file is actually what you are going to use in Visual Studio, you don’t need to extract the contents of the file.
To customize the template though you do need to open this ZIP file up, the file you are going to customize is “Christoc.com C# Compiled Module.vstemplate”. I recommend extracting the contents of the ZIP file somewhere on your local computer. Once you extract the contents of the ZIP package navigate to the folder where the extracted files exist and open the VSTEMPLATE file in NotePad or some other text editor. If you open up this file you will see some comments in the 27 lines of the file, the comments are wrapped with these comments point out locations in the VSTEMPLATE file that you can customize to match your company name, email, url, and name spaces. I’ve highlighted those fields in the screenshot here
Customization is as easy as modifying that file, saving the changes, and then repackaging the ZIP file. Repackaging the ZIP file is up to you, but I prefer to press Control-A in the folder where all the extracted files are, right click on the VSTEMPLATE file and choose Send to Compressed (zipped) Folder, if you right clicked on the VSTEMPLATE file the ZIP file will be called “Christoc.com C# Compiled Module.ZIP”, you can also change the file name before creating the ZIP file in order to give it a different name. Now that you have a new ZIP file with your custom changes you can proceed on to the next step in the process, installing the template.
Installing the DotNetNuke C# Module Visual Studio Template
Installing the Visual Studio Template is fairly straight forward. You should close all instances of VS2008, then copy the ZIP file, either the one you downloaded from Codeplex, or the one you customized in the previous steps. You are going to paste this ZIP file into a very specific folder. Visual Studio Templates by default are stored in your My Documents\Visual Studio 2008\Templates folder. Within that folder you should go into ProjectTemplates\Visual C#\Web folder. If you don’t have a WEB folder within the Visual C# folder you can simply create a new folder.
Here’s a screenshot of my web folder with the template installed.
Notice that the path for this location is highlighted in yellow. It was that simple, you now have the visual studio template installed and ready for you to use.
Creating A Project with the Template
Because you closed all instances of Visual Studio 2008 prior to installing the template you can now open VS2008, when Visual Studio opens it loads all the templates from the templates folder. If you happened to leave VS2008 open before installing the template the IDE doesn’t know about this new template so you need to open up a new instance of VS2008.
Now that you have Visual Studio open you should click on File>New>Project. In the new project window Navigate to your Visual C#/Web folder under project types, after doing so you should see something like the following.
In that window be sure to choose the new template that you installed, in my case I’m going to access Christoc.com C# Compiled Module. From there I can populate the project properties below. In the screenshow below I’ve populated the key project properties.
The NAME of our project is going to be important going forward, whatever you type in for Name will become the project name, the name of the DLL and part of the namespaces for your project. You can always change the name later, but you’ll have to change it in a large number of places, so I suggest you name your project carefully. In my example here I’m calling the module ModuleName2, not an idea naming convention, but for example purposes it will suffice.
The LOCATION of our project is also very important, notice in the screenshot I placed the project in c:\websites\dnndev\desktopmodules\ DNNDEV is my development environment that I configured in the previous blog post (you read that one right?). So we are creating our project within the DotNetNuke environment, this will aid in our development and debugging for the module, there is no need to move files from one folder to another to start using our module in our development install of DNN. The Project that will be created based on this template requires that you put your project into the website/desktopmodules folder, if you put it elsewhere when you compile the module the DLL will be placed into the website/bin folder, in my case into c:\websites\dnndev\bin\.
The other option you should make sure you follow, uncheck the “Create directory for solution” checkbox on the project creation screen. This will prevent Visual Studio from creating our project inside of c:\websites\dnndev\desktopmodules\ModuleName2\ModuleName2, we want the project and solution files to reside in c:\websites\dnndev\desktopmodules\ModuleName2, not within a sub folder of that folder.
Once you have configured the New Project window click OK and Visual Studio will create the project and all the associated files based on the template for you.
Final Project Configuration and Compilation
After creating your project, inside of Visual Studio you will see a window appear that will display a list of instructions for you
Here is what you need to do. Right click on the Project in your Solution Explorer, and choose Properties. From the Project Properties window we want to go to the Web tab.
In the Web tab we need to configure a couple of settings. For our Start URL we are going to use http://dnndev/ (the URL we created in our environment configuration blog yesterday)
We then need to configure the Use Local Web Server option, the Project URL is http://dnndev/desktopmodules/ModuleName2 and the Override application URL setting should be http://dnndev/
Once you have modified these settings you can save your project and close the project properties window. Now you can compile! Being a keyboard junky I would suggest using Control-Shift-B, this will do a build of your project, and if you haven’t broken anything the build should compile successfully. The process of building the module compiles the code into a DLL and places that DLL into the c:\websites\dnndev\bin folder with the name of ModuleName2.dll
The next blog post in this series will cover the automated packaging process using NANT and getting the module installed into your DotNetNuke instance.
If you have any feedback on the template please let me know. Check it out on Codeplex and add a rating if you like it!
UPDATE 11/23/2010: I've released a new version of these templates that no longer uses the NANT Build scripts, they now use MSBuild. For more info check out this blog post