Installation

Table of Contents

1 - Installation Overview
2 - Choosing a version for download
3 - Fresh Installation
4 - Upgrading From Previous Version
5 - Troubleshooting
6 - IIS 7

1 - Installation Overview

The BlogEngine.NET installation process is fairly straight forward. The information below will guide you through the process and help you with any issues you encounter.

2 - Choosing a version for download

There are two download options for BlogEngine.NET:
  • Web Project: This is an ideal option if you want to use BlogEngine.NET right out of the box and don't have plans to create custom controls or extend the software.
  • Source Code: This is the developer option. If you are interested is seeing how things work or want to add to the functionality, this is your option. Note that although you can look at the source with Visual Studio 2005 Express, you can't rebuild the DLL with it.
Choosing one option over the other doesn't lock you into your decision, but you need to choose a place to start. If you are unsure, just download the web project. You can always download the Source Code later and add your changes in.

3 - Fresh Installation

By fresh installation, we mean that you are creating a new instance (folder with the application) of BlogEngine.NET on your server/hosting space/local pc. If you already have an instance of BlogEngine.NET that you want to upgrade, see the next section. If you already have an instance that you played around with, but you just want to start again, this is the section for you.

Get the web project folder

Now that you have a downloaded zip file, you need to un-zip it. This can be done with a bunch of different utilities and in a bunch of different methods.

If you choose the Web Project download, your newly unzipped folder contains the web project you want to work with. If you download the source code, the web project is buried a little bit. The web project is found under the BlogEngine.NET folder, then the BlogEngine folder.

Load the web project on your web server

Now that you have the web project folder, copy those files and folders out to your web server. This usually involves FTP, but depending on your situation, it might even require a portable storage device (e.g. USB flash drive).

Set folder as a .NET 4.0 application

There isn't much to say about this. If you have direct IIS access, you need to create an application. If you are using a hosted provider, you need to use their control panel to make this happen. It should be a standard option, but if you don't find it, you may need to contact your hosting provider for support. BlogEngine.NET is developed under an "Integrated Mode" application pool. It is recommended your application pool be in Integrated Mode (as opposed to Classic Mode).

Add write permissions for App_Data folder

This is an often forgotten step. If you miss it, you'll notice as soon as you try to make a change. You need to give the application write permissions to the App_Data folder. Again, your hosting provider may have a control panel that allows you to do this. If not, you may need to contact your hosting provider for support.

Setting write permissions could involve up to 3 steps: 1) Using the IIS admin tool or your hosting provider's control panel, set the folder as "Write" capable; 2) If you have direct access to the file system, make sure the account under which the BlogEngine.NET's application pool is running (typically "ASPNET" on XP / 2003 and "Network Service" on Vista / 2008) has write access to the physical folder; 3) After unzipping the web folder, all files have their read-only attribute enabled. Turn that attribute off for the App_Data folder and all files and subfolders.

Navigate to the web page

Ok, now you are ready to navigate to the web site and see how you did. For example, if you installed the web site to your local machine for testing, you would navigate to http://localhost/default.aspx. You can also edit the default document to display to default.aspx using the IIS MMC snap-in. If you do this, you can navigate direcly to http://localhost/ without specifying the page name. If all goes well, you are greeted by the default blog page.

Login and Setup your user name

The last step is to scroll down and find the sign in link on the right side. Click Sign in and then login in the following information.

User Name: admin Password: admin

Once you login, you will see a new menu on the right hand side. Click Users.

Create a new user for yourself. The user name you choose is your display name. See the User Administration page for more information.

Delete the admin account. You don't want everyone who reads this to be able to login to your blog, do you?

Finally, log out, then log back in using the user account you just created for yourself.

4 - Upgrading From Previous Version

Ah, a veteran. You know all the basics so I won't bore you with them. If you do struggle with the basic setup though, don't be afraid to read the Fresh Installation instructions.

4.1 Upgrading to version 2.8


Specific instructions for Upgrading to BlogEngine.NET 2.8

4.2 Upgrading to version 2.7


Specific instructions for Upgrading to BlogEngine.NET 2.7

4.3 Upgrading to version 2.6


Specific instructions for Upgrading to BlogEngine.NET 2.6

4.4 Upgrading to version 2.5


Specific instructions for Upgrading to BlogEngine.NET 2.5

4.5 Upgrading to version 2.0


Specific instructions for Upgrading to BlogEngine.NET 2.0

4.6 Upgrading to version 1.6


If you're upgrading from an earlier release to version 1.6, there's two important changes to make when upgrading.
  1. Delete the entire "ExtensionManager" sub-folder in the App_Code folder. This code has been moved into the BlogEngine.Core.dll in version 1.6. Not deleting this sub-folder will lead to errors.
  2. For multiple widget zone support, a couple of CSS class names have changed. You may need to update your theme's CSS file. A search and replace should be sufficient.
    1. Replace #widgetzone with .widgetzone
    2. Replace #widgetselector with .widgetselector
  3. As always, please follow the upgrade guidelines described below.
More details on CSS changes and multiple widget zones in general can be found here.

4.6 Upgrading to version 1.4

Checkout this for specific upgrade instructions from previous versions to version 1.4 of BE

Backup your stuff

It is always a good idea to backup your files before starting an upgrade. It's a general recommendation and if you do it right, we guarantee you won't lose any information.

The main things you'll be interested in saving are the entire contents of your App_Data folder, custom themes you may have, and any custom controls you made. Remember that even if you just made a few slight modification to a theme, you will want to back them up so you can put them into the new installation.

Merging your data with the web project

Depending on when you downloaded your pre-release version of BlogEngine, you may have an incomplete settings.xml file. You will want to open the freshly downloaded settings.xml file from the App_Data folder and compare it to your existing settings.xml file. Any entries in the new one that aren't in your existing one, should be added.

If you have a new theme, go ahead and add your theme folder to the new web project themes folder. There have been a lot of changes to the theme process over the course of the project. It would be recommended that you look over the Theme Creation page and make adjustments to your theme accordingly. You could, of course, just try it and see how it works, but then you'd miss out on the fun of reading our Theme documentation.

If you modified an existing theme, it is best to make the changes in the new version of that theme.

Load it up already

Once you have the needed changes, load up your files, and enjoy the latest release. There is lots of good stuff in it!

5 - Troubleshooting

What are you doing here? There couldn't possibly a problem, could there? Ok, these things happen and this is as good a place as any to look for the solution.

When I navigate to my blog, I get a blank page

Make sure your blog folder is set to an Application.

When I navigate to my blog, I get an error page

Check your .NET version. You need to make sure your blog is set to use version 2.0.

I can't edit/change settings/etc

This is caused by not having the correct write permissions on the App_Data folder.

Note: If you use WebHost4Life, the proper settings should be user Network Service has Full Control.

Security/ Permissions

Set up the App_Data folder so that the ASP.NET service and IIS can both read and write to it. In Vista/IIS7.0 this means that you need to set this access up (from within Windows Explorer) for the group "users", and also for the "NETWORK SERVICE" (you have to add this latter through the advanced security dialogs). Make sure that the files within the App_Data folder are not set to read only.

Rename the application directory?

Noooh, don't do that. If you installed Blog Engine in a directory like /BlogEngine, then install a subsequence version in a different directory, say /BlogEngine.NET, everything will be fun except all the image references in your old posts will point to the first directory, not the second. Maybe you can rename all the entries in all the little XML files and that will fix it; or you may just wimp out and rename the new installation to the same directory name as the old one, which definitely fixes this.

6 - IIS 7

Inherited handler settings

If you're getting an error:

404.3 HTTP Error 404.3 - Not Found;
The page you are requesting cannot be served because of the Multipurpose Internet Mail Extensions (MIME) map policy that is configured on the Web server. The page you requested has a file name extension that is not recognized, and is not allowed.
Error Code: 0x80070032

Then it may be that your "handlers" aren't inherited correctly by the site containing the blog. You can check this by looking in the "handler" set up for the web server itself - it should have lots of entries including aspx. Then check the "handler" set for the App_Data folder... if that's much smaller, then as per this link. http://dunnry.com/blog/IIS7And4043Error.aspx you may need to tweak things to force the App_Data folder to inherit the handlers correctly.

HTTP Error 500.0 - Internal Server Error Integrated .NET mode

You may get an error as above, which suggests that you should run: %systemroot%\system32\inetsrv\APPCMD.EXE migrate config "site_name/BlogEngine" For once the instructions are correct... just open an admin command window, paste the command from your error message in there and run it.

web.config

If you have tried everything else and simply can't get the handlers to populate for your App_Data folder, it may be worth looking for a little file called "web.config" in the root of your site. Deleting this and then reinstalling the blog software fixed that problem for me.

VS 2008 with Cassini Web Server

Try running Visual Studio as Administrator. That seems to fix a lot of the permission errors under cassini.

Last edited Apr 20 at 7:44 PM by rtur, version 12

Comments

joannarom May 8 at 7:44 PM 
Just installed the new version of BlogEngine...fresh install on Windows 7 profession 64 bit edition running IIS 7 and using IE10. I tried both the web and source versions of the project and get the following javascript error when I try to access the "Settings" pages.

"Member Not Found"
DOM inspector shows that it is occurring in jquery-1.8.2.min.js line 2 character 32075 and highlights the following line:
return d||(d=e.createAttribute(c),a.setAttributeNode(d)),d.value=b+""

The settings pages display fine but each section withing settings displays this javascript error. I also cannot save any changes within settings, BUT I was able to change my password so I do not think its a permissions issue on the app_data folder, but I could be wrong, I just started this today.

sczerno Feb 4 at 2:14 PM 
If a category has a dash in it, for example "Hyper-V", it is displayed as a child category.

jasonpaulweber Dec 28, 2012 at 5:13 PM 
Helllo! I'm on a Windows 2012 IIS 8.0 server w/ a shared host. I followed the instructions, and I tried putting it the root.org/blog/ directory. When I go to root.org/blog/default.aspx, it brings up the page. But when I try to click "log in", it says in the tab "IIS 8.0 Detailed Error" and specifically says this:

---------------------------------------------------------------------------
HTTP Error 404.0 - Not Found
The resource you are looking for has been removed, had its name changed, or is temporarily unavailable.
Most likely causes:

The directory or file specified does not exist on the Web server.
The URL contains a typographical error.
A custom filter or module, such as URLScan, restricts access to the file.

Things you can try:

Create the content on the Web server.
Review the browser URL.
Create a tracing rule to track failed requests for this HTTP status code and see which module is calling SetStatus. For more information about creating a tracing rule for failed requests, click here.

Detailed Error Information:
Module IIS Web Core
Notification MapRequestHandler
Handler StaticFile
Error Code 0x80070002
Requested URL http://root.org:80/blog/account/login
Physical Path E:\web\controlpanelname\htdocs\blog\account\login
Logon Method BlogEngine.NET Custom Identity
Logon User Anonymous
---------------------------------------------------------------------------

I have IIS7 Manager installed on this computer. I'm guessing it has something to do with handler mappings? I wrote my shared hosting company and they said:

"Your IIS and aspnet users are granted full set of permissions on your site root and all subsequent directories by default. Your and your web applications should be able to write to any directory. The permissions of those users cannot be altered, and that's why they are not listed in permissions manager. Permission manager is for additional users that you create in User/Quota Manager only. "

Any guidance would be greatly appreciated!

tonyatmendina Nov 16, 2012 at 4:36 PM 
To fix .cshtml and .cshtm problems in IIS 6, as well as to get re-written URLs beginning with /blog/post/ and /blog/category to work in IIS 6, the simplest solution is to set up a wildcard application map in your blog application settings. Right-click on on your blog's application folder in IIS manager, choose Properties, highlight the Directory tab and press Configuration. On the mappings tab of the Application Configuration dialog, press Insert to add a wildcard mapping, and enter the path to the framework 4.0 dll, e.g. c:\windows\microsoft.net\framework\v4.0.30319\aspnet_isapi.dll. Be sure to uncheck the box "Verify that file exists." Thank you very much to Scott Forsyth at http://weblogs.asp.net/owscott/archive/2010/07/08/configuring-iis6-for-webmatrix.aspx

DRiley5998 Jul 9, 2012 at 8:29 AM 
scott,

Update your VS2010 with sp1
recbuild the project and it should go away.

I was getting the same error message too.
jjust a few days ago. It went away after I install service pack 1 for VS2010

scottgurvey Jun 30, 2012 at 4:32 AM 
Trying to study source code in VS 2010 and I'm kind of lost.
Build and run with F5 to localhost.
Base page does not load. Error on
WebForm_InitCallback();
Microsoft JScript runtime error: 'WebForm_InitCallback' is undefined
Can anyone help?
Thank you.

seputarsoftware Mar 15, 2012 at 7:30 AM 
You have remarked very interesting details ! ps decent internet site .
http://update-seputar-software.blogspot.com/2011/12/ultrabook-notebook-tipis-harga-murah.html

nitroxn Jan 17, 2011 at 3:07 AM 
I upgraded from 1.6 to 2.0. all the posts are visible in the blog page and the dashboard but when i try to edit the posts. the post list is empty, although the count of posts are correct in the dashboard page please help.

lparker Jan 16, 2011 at 12:59 PM 
I figured it out ..... .Net Framework 3.5 SP1 wasn't installed.

lparker Jan 16, 2011 at 2:15 AM 
I have 3 instances of BE1.6 running on a Windows Server 2003, IIS6. I downloaded BE2.0 and tried to run it and received an error "Server Error in '/' Application.
Runtime Error". I've checked permissions and I have ASP.net 2.0. I first setup the new version and pointed a test domain to it. Then I tried creating a virtual site off one of the existing 1.6 blogs and I get the same results. Anyone have an idea what could cause this? I have a XP Pro test box with both versions running with no problems.

dmaxwell Jan 9, 2011 at 12:57 AM 
I would like to recommend looking at http://rtur.net/blog/post/2010/12/22/Using-BlogEngineNET-20-with-NET-40-framework.aspx for helpful information on getting blogengine.net to work under Asp.Net 4.0.

Patridge Oct 28, 2010 at 8:42 PM 
In Win7 64-bit IIS, I got a permission error when I deleted the admin account. The page loaded fine but the error stack trace made it sound like something in the delete process didn't go as expected. I started over, this time giving modify permission as well as write, and it worked fine. It may have been a fluke, but it made sense and the error didn't show up the second time.

anees Jul 29, 2010 at 9:11 AM 
Installed BlogEngine.Net 1.6.1 in http://localhost:4432/xxxx/blog/ in a sub blog folder. When i add new entry i get following error.

Object reference not set to an instance of an object.
Description: An unhandled exception occurred during the execution of the current web request. Please review the stack trace for more information about the error and where it originated in the code.

Exception Details: System.NullReferenceException: Object reference not set to an instance of an object.

Source Error:

Line 297:
Line 298: ExtensionSettings Settings = ExtensionManager.GetSettings("Recaptcha");
Line 299: publicKey = Settings.GetSingleValue("PublicKey");
Line 300: privateKey = Settings.GetSingleValue("PrivateKey");
Line 301:


Source File: d:\Projects\Sarawat\SarawatNew\SarawatWeb\App_Code\Extensions\Recaptcha\RecaptchaControl.cs Line: 299

ttun76 Jul 5, 2010 at 6:28 PM 
I tried to install fresh copy of v1.6 and using sql provider, but was not successful. Can someone guide me to the right direction on how to configure the blog engine connection strings and default provider? I'm using VS 2008 and Sql 2008. Thanks

dampee May 13, 2010 at 12:31 PM 
@AnthonyGrace You can upgrade at once, if you launce the correct SQL scripts

AnthonyGrace Mar 28, 2010 at 1:43 AM 
I'm on version 1.4.5.0 and wish to upgrade to 1.6. I'm using SQL Server DB. Should I go straight from 1.4.5 to 1.5 ore perform an upgrade to 1.5 first?

jgionet76 Mar 23, 2010 at 2:38 PM 
I just upgrade from 1.5 to 1.6 and ALL my users which were stored in the MSSQL database got removed. The only user I had left was the default Admin account and password.
Also, when I add new users, they are not getting saved/added the XML file in the App_Data folder instead of in the SQL database.
I double checked my settings and the posts are still being pulled from the SQL server.
any ideas?

jrblack10 Mar 22, 2010 at 12:46 PM 
I wrote up a simple step procedure I did to upgrade my 1.5 blog to 1.6. Feel free to comment.
http://jim.blacksweb.com/post/BlogEngineNET-16-upgrade.aspx

Comment moderation alone makes this upgrade worth it. Thanks Team!

mathiasb Mar 22, 2010 at 4:41 AM 
@corobori: I wish I had read your comment before getting started... It would have been nice if the upgrade instructions mentioned that you have to run a database upgrade script!

Innosia Mar 20, 2010 at 8:57 AM 
this engine seems like noone is working on it now... its so long and still no upgrade, and no much extensions for it, and also no much support and help etc compare to PHP joomla, i guess .net CMS/Engine development is very slow

HillPeaceman Mar 5, 2010 at 9:43 AM 
Hello guys,
Don't forget to migrate your sql database using the script in the setup directory
MSSQLUpgradeFrom1.5To1.6.sql if SQLServer and upgrading from 1.5
Thank's for the new features ben.

rchelicopter Mar 4, 2010 at 1:50 PM 
This is good explanation about installing BlogEngineNET

moospot Mar 4, 2010 at 1:23 PM 
My Extensions do not show up in the control panel. Anyone else having this issue?

scottker Feb 23, 2010 at 7:37 AM 
Thanks for the instructions, worked great.

Corobori Feb 19, 2010 at 10:42 PM 
I would add a warning for people using database to make sure check out the db upgrade too in the setup folder

whihathac Feb 6, 2010 at 10:44 AM 
Thanks David for a nice guide :)

dcewynne Feb 4, 2010 at 7:57 PM 
I've written some more comprehensive upgrade (1.5 > 1.6) notes HTH
http://www.david-wynne.com/blog/post/Upgrading-BlogEngineNET-from-15-to-16.aspx

code001 Jan 10, 2010 at 8:22 PM 
I use WebHost4Life
The Networ service is set to Full permission on App_Data folder, yet I still receive the "Exception Details: System.UnauthorizedAccessException: Access to the path 'e:\hosting\member\xxxxx xxxx\blog\App_Data\users.xml' is denied".
the Blog is set to Application and I did everithing is written and shown in your docs/screencasts
What else can be it?

aswinmj Sep 23, 2009 at 6:41 PM 
I have downloaded the code. I tried to open it in Visual Studio 2005 but is not opening as it says it is built with higher version of visual studio.
can any one please give me solution for this?

SpoonySonny Sep 9, 2009 at 5:20 AM 
keledomo
I've fixed that. follow link to download.
http://www.blogyi.net/download

keledomo Sep 9, 2009 at 3:18 AM 
Chinese version may receive a JavaScript error after installation, please fix it.

richarddeeming Aug 11, 2009 at 4:17 PM 
Step 3, "Login and Setup your user name"
The last two steps are in the wrong order. You must log out and log in as the new user before you can delete the default admin account.

dermotjmcl Aug 5, 2009 at 6:16 PM 
On step 3, "Navigate to the web page" where the author says " You can also edit the default document to display to default.aspx using the IIS MMC snap-in...". I'm guessing this is the same as (or equivalent to) "load ISS, click on website>Properties>Documents tab> make sure 'Enable Default document' checked, add 'default.aspx' to list". If so, I found I needed to do this for the "Home" link to work on the blog wesbite - it wasn't optional. Sorry if this is obvious to some folks - maybe this should be a forum comment?

kpetersen Jul 10, 2009 at 2:04 PM 
Regarding Step 3 > Add write permissions for App_Data folder: I feel obliged to point out that ASPNET is not the default application pool account under Windows 2003, it's NETWORK SERVICE. The ASPNET account is only used when running in IIS 5.0 isolation mode (which isn't a very likely configuration and should be avoided anyway).