Tuesday, June 14, 2011

Upgrading your gallery to .NET 4.0

Gallery Server Pro 2.0 – 2.4 runs on any version of .NET from 2.0 - 4.0. Beginning with version 2.5, Gallery Server Pro requires .NET 4.0 or higher. This change allows GSP to take advantage of new features such as Entity Framework Code First development for SQL Compact CE and LINQ, while also simplifying the packaging and documentation requirements. (You may have noticed that 2.4 ships with six versions of web.config!)

If you are currently running GSP 2.3.* or 2.4.*, I recommend upgrading your gallery to .NET 4.0 *before* upgrading the gallery code to GSP 2.5. Technically, you could perform the .NET 4 upgrade and the GSP 2.5 upgrade at the same time, but why complicate things? By separating it into two steps, if anything goes wrong, it will be easier to troubleshoot.

What if you are using GSP 2.0 – 2.2? Those versions never shipped with a .NET 4.0 version of web.config, and I don’t think it is worth the trouble trying to get them working under .NET 4.0 only to immediately upgrade to GSP 2.5. For these versions, I recommend performing the upgrade to .NET 4.0 and GSP 2.5 at the same time. The Admin Guide has instructions for how to do this.

The rest of this post is intended to help you get your GSP 2.3 – 2.4 gallery running under .NET 4.0. This basically involves two steps:

1. Configure IIS to run the application under .NET 4.
2. Update web.config to conform to .NET 4.

Configure IIS to run the application under .NET 4.

This step is performed with IIS Manager (type inetmgr in a Start-Run box). For IIS 6, right click the gallery web application and choose Properties. Then click the ASP.NET tab and select 4.0 in the ASP.NET version dropdown box.

For IIS 7 and higher, the .NET version is associated with the application pool the application is running under. In IIS Manager, select the Application Pools node in the treeview, then double-click the relevant application pool in the grid. A dialog appears where you can change the .NET Framework version to 4.0. If you don't know which app pool the gallery is running under, right-click the name of the application in the treeview and select Manage Application - Advanced Settings. This brings up a dialog window that shows the app pool.

If you are using a hosting provider, look in your host’s control panel for this setting.

Update web.config to conform to .NET 4.

The web.config file, stored in the root of the web application, contains several references to a specific version of .NET. These must be updated to .NET 4.0 references or, in some cases, removed since they are now present in the machine-wide web.config file. Follow these steps:

  1. Rename your existing web.config to web_old.config.
  2. Grab the relevant web.config from this download and copy to your web application. For example, if you have version 2.3 with SQLite as your database, use web.config from the “Files for upgrading from 2.3\SQLite” directory.
  3. (SQL Server only) Update the connection string to your SQL Server database in web.config with the one from your previous one (now named web_old.config). It should be named SqlServerDbConnection.


  • If you made any changes to your web.config file, you must manually migrate them to the new web.config file.
  • If your version is 2.3.3421 to 2.3.3512, you should also migrate the <location path="gs/services/Gallery.asmx"> section from your old web.config file. (This section is not required in 2.3.3512 and later, as there is a web.config file in the services directory that performs this task.)
  • You are on your own if you want to get GSP 2.0 – 2.2 working on .NET 4.0. It can be done, but you have to carefully upgrade your web.config to the .NET 4.0 version. As I said before, for these versions I recommend upgrading to .NET 4.0 and GSP 2.5 in a single step. Instructions are provided in the Admin Guide.

No comments: