First, a few caveats:
1. It is not necessary nor recommended that you use the DotNetNuke framework source code when developing modules or other extensions. This is particularly true if you will be distributing the extensions that you create as open source contributions to the DotNetNuke community or commercially. You do not want to develop an extension against a non-standard build of DotNetNuke.
2. Avoid the temptation to make modifications to the DotNetNuke framework source code no matter how minor such modifications may seem. When it comes time to upgrade DotNetNuke framework versions, your modifications stand a very large chance of being overwritten and may interfere with or otherwise block a successful upgrade. At the very least, it will be necessary to reapply, test, and perhaps further revise your modifications to the upgraded DotNetNuke framework.
3. Installation and future upgrades of the Source Package are more difficult and time consuming than those of the install package. If you are new at working with DotNetNuke or just want to give it an evaluation for use in your next website designs, stick to the install or web platform installer packages.
When might I want to install the source package?
1. Once you have mastered the installation and administration of DotNetNuke websites you may want to better understand how the framework is put together by looking at its source code.
2. You are developing modules which make frequent use of the various DotNetNuke API’s and need to better understand what parameters to pass to core methods, how those core methods process those parameters and what objects they may return, and what data is contained in the various entity classes. For example, if you are developing a module which will through code create pages and place modules upon those pages, what better place to start then looking at how the control panel ribbon bar performs its functions.
3. Your own extension code is causing an error to be thrown deep within one of the framework procedures and no amount of debugging of your own code is resolving the issue and you decide that you would like to be able to debug step into core methods.
4. You are a frequent poster to the DotNetNuke forums and need to exam framework source code to better understand and come up with a work-around to what appears to be a core issue. Perhaps you’ll even submit the issue and a proposed patch to the Gemini, the DotNetNuke support and issue tracker.
And now for the prerequisites which must be installed and configured prior to installing DotNetNuke:
1. Information Internet Services (IIS) for Windows XP Professional (IIS 5.1), Windows Vista (IIS 7), or Windows 7 (IIS 7.5) or Windows Server 2003 and later (IIS 6, 7 or 7.5 depending on server version)
2. Microsoft SQL Server 2005 or 2008 (including Express versions) and SQL Server Management Studio (SSMS) (including Express versions).
3. Microsoft ASP.Net 3.5 SP1 or 4.0 (4.0 not recommended for DNN versions earlier than 5.04.04)
4. Microsoft Visual Studio 2008 or 2010
A. Downloading and Extracting the Source Package
1. Download the most recent DotNetNuke source package (New Install + Source Code) found at http://dotnetnuke.codeplex.com/releases. If you need to install an earlier source (or other) package, select the desired version from the Other Downloads box in the upper right of this page.
2. Right-click over the icon for the zip archive package you have just downloaded and select “Properties” from the context menu that will appear. If you see a button marked “Unblock”, click this button to overrides Windows security that will normally block “dangerous” JavaScript and other files from being extracted from a downloaded zip archive.
3. Right-click over the icon for the zip archive package and select “Extract All . . .” then select a new or empty folder into which the zip archive’s folders and files will be extracted.
4. Since I like to keep the contents of this folder untouched for additional installations or study as to the contents of the package prior to installation, I then copy its contents into a new folder which will contain the actual source installation. In my setup I have one folder named “DNN Websites” containing child folders for each client, test, or development website. Let’s call the source install folder into which we copy the extracted package “C:\DNN Websites\DNN561Source”
B. Creating the MS SQL Server Database
1. As you will want to examine the DotNetNuke database as part of your understanding of the DotNetNuke framework and as you will need to access the database outside of DotNetNuke when developing most modules and extensions, do NOT use the App_Data/Database.mdf database file contained in all DotNetNuke packages. Instead, you will be creating a blank MS SQL Server database that DotNetNuke will then populate during the normal install procedure. Until recently I have been using SQL Server Express for all development and testing, treating it as if it were a non-express version when installing DotNetNuke.
2. Open SSMS and connect to the desired instance of MS SQL Server. I recommend that when initially installing MS SQL Server you configure it to allow Mixed Mode Authentication which allows use of both Windows Authentication (automatic login using your Windows user account) and SQL Server Authentication (login using the Username and Password of a SQL Server user that you have created). Typically a local instance of SQL Server will use a Server Name in the format of {computername}\{instancename}, for example “PK5-WES\SQLExpress5” or “PK5-WES\SQLExpress8”. A dot (“.”) can be used instead of the {computername}, for example “.\SQLExpress8”. Select Windows Authentication which will not require entry of username or password and click “Connect”.
3. In the left-hand panel of SSMS, right click over the “Databases” node and select “New Database”. For the Database Name, I use the same name as the install folder above and IIS Site Alias that we will set up in the next section. For example, if these are DNN561Source, use “DNN561Source” for the Database Name as well. As all other options can remain at their default values, simply click “OK” to create the database.
4. Right click over the “Security” node (of the server not your newly created database) and select “New . . . Login”. Enter a new Login Name, for example “DNN5SourceUser”. Select “SQL Server Authentication” and fill in the “Password” and “Confirm Password” fields. Be sure to uncheck “Enforce password expiration”. For the “Default Database” drop-down, select the newly created database. As all other options can be left at their default values, simply click “OK” to create the new database server login.
5. In the left-hand panel of SSMS, double click the “Databases” node to expand it, then locate the node for the newly created database and double click it to expand. Right click on the “Security” node for the new database and select “New . . . User”. Enter the login name that you created in step 4 above in both the User Name and Login Name fields. You may also click on the “…” button to the right of the “Login Name” field to browse for the desired username. In the box “Owned Schemas” check “db_owner”. Likewise in the “Role Members” box check “db_owner”. As all other options can be left at their default values, simply click “OK” to create the new database user.
6. Close SSMS. As an extra check on your work so far, re-open SSMS but in the connection box this time select “SQL Server Authentication” and enter the Login Name and Password for the newly created database user. If you are not able to connect to the database via SSMS using SQL Server Authentication, DotNetNuke will not be able to either.
C. Setting up the Web Application in Internet Information Services (IIS) Manager
Depending on your version of IIS, the actual steps will be similar to but may vary considerably from the following which are for IIS 7.5 (Windows 7):
1. Open IIS Manager from the Windows StartRun command by entering INETMGR. You’ll probably want to create a shortcut on your desktop for this command as you’ll be using it frequently as you create and manage your websites.
2. In the Connections pane to the left of IIS Manager, expand the site tree so that you can see the “Default Web Site” node. Right click on “Default Web Site” and select “Add Application”.
3. Fill in the “Alias” field with the name of the site, in our example, “DNN561Source”.
4. If desired, click on the “Select” button to choose an Application Pool other than “DefaultAppPool”. As I have ASP.Net 4.0 installed, my choices include “DefaultAppPool”, “Classic .Net AppPool” (both of which are ASP.Net 2.0/3.5 SP1) as well as “ASP.Net v4.0” and “ASP.Net v4.0 Classic” and several custom application pools that I have defined. Let’s select the “DefaultAppPool” which will use ASP.Net 2.0/3.5 SP1 in Integrated Pipeline Mode.
5. Click the “…” button to the right of the Physical Path field and find the root folder in which our new DotNetNuke website will reside. For a source installation, this is NOT the folder (DNN561Source) into which we copied the extracted source package but rather the child “Website” (C:\DNN Websites\DNN561Source\Website) folder.
6. As we can leave all of the other values at their defaults for this new Web Application, click “OK” then close IIS Manager.
D. Renaming/Modifying Site’s web.config file
1. Next, open the Website (C:\DNN561Source\Website) folder in Windows File Explorer and find the file web.config. What??!! You say there is no file by that name??! Instead in the source package you will find release.config and a development.config files which are essentially the same with the exceptions that in development.config the debug attribute of the
node is set to “true”, the trust level is forced to “medium”, and the database objectQualifier attribute for the
node is set to “dnn_”
2. Let’s use the development.config file and either rename or copy it to web.config. One of the frequent issues we see when installing the source version of DotNetNuke is that people either do not know or forget to rename development.config or release.config to web.config. Without an ASP.Net configuration file in the , hundreds of errors for missing references, etc. will be displayed when one tries to open and build the DotNetNuke_Community.sln or DotNetNuke_Community_2008.sln solutions in Visual Studio.
E. Setting File System Permissions
1. The ASP.Net worker process (IIS Identity) user account MUST be granted full permissions (including modify) on the root folder of the website and all child folders. So, in Windows File Explorer, locate the Website (C:\DNN Websites\DNN561Source\Website) folder and right click on the folder name.
2. From the context menu, select “Properties” then click on the “Security” tab of the properties dialog box.
3. Click the “Edit” button then the “Add” button to add a new entry for the ASP.Net worker process account. For IIS 5.1 (Windows XP) this is the ASPNET account. For IIS 6 and 7 (Windows Server 2003 and Windows Vista or Windows Server 2008 respectively) this is the Network Service account. For IIS 7.5 (Windows 7 and Windows Server 2008 R2) this is what ever is used as the Process Identity or Application Pool identity that was selected in IIS Manager. In our example we had selected the DefaultAppPool in IIS Manager so we can enter “IIS AppPool\DefaultAppPool” in the “Enter the object names to select” box then click “Check Names”. If the account (actually a pseudo-account in the case of IIS 7.5) is found and no error is shown click “OK” You should now see a new entry for this account in the Security box.Please see here for more details about why windows 2008r2/windows7 are different
4. Select this account name and check the box in the “Allow” column for “Full Control” then click “OK”.
5. If we had selected the “ASP.Net v4.0” application pool in IIS, the IIS Identity account to be entered in step 3 above would have been “IIS AppPool\ASP.Net v4.0”. Likewise for the other standard application pools or for a custom application pool that you have created.
F. Modifying the Visual Studio Solution File
1. If you have Visual Studio 2010, you will be using the “DotNetNuke_Community.sln” file contained in the root folder of the extracted source package. If you have Visual Studio 2008, you will be using the “DotNetNuke_Community_VS2008.sln solution file. Locate the appropriate solution file and open it with a text editor such as Notepad. Do NOT open the solution file in Visual Studio at this time.
2. The solution files included in the source package assume an IIS website located at http://localhost/DotNetNuke_Community which most likely will not be correct for your installation. You must change this reference to the IIS Alias for your installation. In our example, the IIS Alias was DNN561Source so we’ll use that value in the following steps.
3. In the text editor of your choice, find the text “http://localhost/DotNetNuke_Community” and change it to “http://localhost/DNN561Source”.
4. You will also see “DotNetNuke_Community” in several other lines in the solution file following the website reference. While these do not have to be changed, I like to replace “DotNetNuke_Community” with the site alias for consistency:
Debug.AspNetCompiler.VirtualPath = "/DotNetNuke_Community"
Debug.AspNetCompiler.TargetPath = "PrecompiledWeb\DotNetNuke_Community\"
Release.AspNetCompiler.VirtualPath = "/DotNetNuke_Community"
Release.AspNetCompiler.TargetPath = "PrecompiledWeb\DotNetNuke_Community\"
becomes
Debug.AspNetCompiler.VirtualPath = "/DNN561Source"
Debug.AspNetCompiler.TargetPath = "PrecompiledWeb\DNN561Source\"
Release.AspNetCompiler.VirtualPath = "/DNN561Source"
Release.AspNetCompiler.TargetPath = "PrecompiledWeb\DNN561Source\"
8. In the solution file for the DotNetNuke 05.06.01 source package, I noticed for the first time the following physical paths:
Debug.AspNetCompiler.PhysicalPath= "E:\DotNetNuke\Releases\CE\5.6.0\DotNetNuke_Community_5.6.0.129_Source\Website\"
Release.AspNetCompiler.PhysicalPath= "E:\DotNetNuke\Releases\CE\5.6.0\DotNetNuke_Community_5.6.0.129_Source\Website\"
I am not certain if it is necessary but I changed both of these to the correct physical paths to the Website folder. In our example each path would become “C:\DNN Websites\DNN561Source\Website\”
9. Save the modified solution file.
G. Opening and Building the DotNetNuke Source in Visual Studio
1. Now you can open the solution file you just modified in Visual Studio. It is a large and complex multiple-project solution so be patient and allow all of the projects to be loaded. Since project files may import several custom MS Build target files you may receive one or more warnings regarding the security risk of modified build files. If you downloaded your DotNetNuke source package from the CodePlex downloads page, you can safely ignore those warnings. If you have selected an ASP.Net v 4.0 App Pool in IIS, you may see a dialog box indicating that the website is configured for a different (v 4.0) of ASP.Net than the solution and project files (v 2.0/3.5). DO NOT select “Yes” to change the target version of the solution to v 4.0 unless you understand that you will be creating a non-standard build of the DotNetNuke library and other projects and fully understand the consequences of such a change.
2. The DotNetNuke source packages do NOT include compiled assemblies of all of the various projects in the Website\bin folder (and in v 5.06.00 and later do not even include a Website\bin folder). Therefore you must build the solution and its multiple-projects before starting the actual installation procedure. If you take a look in the solution’s Build Configuration Manager you will note that the website itself (http://localhost/ . . .) is not included in the build. This is correct as it is not currently possible to pre-compile the website itself – only the library code and the various support projects. The website code will be just-in-time compiled when it is loaded upon the first visit and on subsequent visits if it the ASP.Net worker process has been unloaded or recycled.
3. Finally, click on Build … Build Solution. All projects in the solution should now build without error – but perhaps with a few warnings regarding methods marked obsolete, etc. which can be ignored.
4. Close Visual Studio and save the solution/project files if so prompted.
H. Installing DotNetNuke
1. At long last you can now proceed with installing DotNetNuke as you would when using the install package.
2. Open your browser and navigate to the site URL which in our example would be http://localhost/DNN561Source and follow the promptings of the Install Wizard for a typical installation. Be sure that you provide the database connection information based upon how you created the database and database user account in section B above.