Upgrading the CSLA templates

Owned by Anonymous
Last updated: Jun 27, 2012 by Autumn Wilkins (Unlicensed)Version comment
4 min read

We strive to ensure that the CSLA templates are backwards compatible with previous versions. However, in some circumstances we break backwards compatibility to progress the platform. When we do break backwards compatibility, we ensure that the benefits of breaking compatibility greatly outway the benefits of not breaking compatibility. Please refer to this document when upgrading the CSLA Templates to ensure that you have the smoothest experience possible.

It is highly recommended that you read over the official CSLA Documentation when upgrading between versions of CSLA. This ensures that you are aware of all of the changes that will occur in your application.

It is strongly recommended to check in your solution and/or templates into Source Control or make a backup before continuing.

Upgrading from previous versions of the CSLA Templates

The following steps will guide you through updating your existing project to consume the latest version of the templates.

Please follow the guides for downloading and installing the CSLA Templates before continuing.

 

Updating Visual Studio Solution dependencies

 

The first step is to ensure that your solution meets the requirements of the version you are wanting to upgrade to.

Lets assume your Visual Studio solution targets Visual Studio 2008 and your projects target .NET 3.5 / CSLA 3.x. You are wanting to upgrade to CSLA 4.x. You must first upgrade to a version of Visual Studio that supports .NET 4.0 and upgrade your projects to .NET 4.0.

If you are Installing a new version of Visual Studio, you must rerun the CodeSmith Generator installer to ensure Visual Studio Integration is installed.

After you have verified that your projects are targeting the correct version of the .NET Framework, the next step is to update your assembly dependencies. You can do this by right clicking the CSLA assembly references in Solution Explorer and selecting remove. You must do this for all of your projects. This is required because CodeSmith Generator will not update existing assembly references, it will only add them if they do not exist.

Updating existing CodeSmith Generator Project files

If you extracted the latest version of the templates over the current templates you can skip the first step.

The next step is to update all existing Generator Project files. The Generator Project files will continue to point to the previous version of the templates if you don't update each template output's paths. The fastest way to update a Generator Project file is to open it with notepad. Once you have opened the Generator Project file, you will want to update each propertySet's template node path to point to the current location as shown below.

change:

<propertySet template="C:\PREVIOUS.PATH.TO.OLD.TEMPLATES\Csla\Entities.cst" ....>

to:

<propertySet template="C:\NEW.PATH.TO.LATEST.TEMPLATES\Csla\Entities.cst" ....>

Once, this has been done, save the file.

If you have Visual Studio open and had previously opened Manage Outputs in Visual Studio, then you will need to restart Visual Studio before the next step. You need to do this, because the previous template assemblies will be loaded into the AppDomain.

Next, open the updated Project file with Manage Outputs and ensure everything compiles. If it doesn't, please ensure that you followed the current step, Please contact support if you continue to run into issues.

You will want to ensure that all properties are set correctly.

If you are upgrading between Framework Versions, then you will need to update the FrameworkVersion property!
If your Location property is set to a full path, I recommend setting it to ".\" (without the quotes).

Regenerate

The next step is to regenerate the solution. You can do this by right clicking the Generator Project and selecting build. Next, check for template compile and generation errors in the output window.

  • If you see any errors about template file not found, then you will need to go to the previous step and ensure that the template output mentioned has the correct propertySet template node path.
  • If you are seeing an error that deals with a template property not being able to be set. Please check the release notes to see if a property has been removed. If it has or you are getting an error, you can follow the previous step, but remove the property XML node in question and repopulate it via Manage Outputs. This is very rare if you do encounter this issue.
  • If you are unable to compile or generate the template, please contact support with the full stack trace / output window and we will take a look into the issue.

If you receive any project compile time bugs and are:

  • upgrading from a minor version of CSLA (EG., 4.1 to 4.2), then chances are you are running into a bug with the templates. Please contact support and we will get this taken care of.
  • upgrading to a major versions of CSLA (EG., 3.x to 4.x), then please check the release notes or upgrade documentation below.

Upgrading from CSLA 3.x to 4.x

It is highly recommended that you read over the official CSLA Documentation when upgrading between versions of CSLA. This ensures that you are aware of all the changes that will occur in your application.

In addition to following the steps above for upgrading your templates, you will also need to complete a few steps to ensure everything compiles when upgrading from 3.x to 4.x. Please follow the sections below after upgrading.

Updating existing CodeSmith Generator Project files

You will need to open Manage Outputs for every project file you updated and change the FrameworkVersion property from v35 to v40. This tells the templates to generate CSLA 4.x compliant code.

Update existing non generated partial classes 

Before you continue this step, please ensure that you have followed the previous upgrade guide and have regenerated. You will notice that there are some build errors.  This is due to the entity partial classes not being regenerated and there are some required changes for Rules or for Silverlight when migrating to CSLA 4.x.

If you didn’t make any changes to the non-generated partial classes (E.G. Account.cs or Account.vb), then it is safe to delete the entire class and regenerate. You can then skip the rest of this step.

Update Imported Assemblies

There were major changes to Rules in CSLA 4.0. You will need to update every business object's non generated partial class (E.G., Account.cs or Account.vb).

C#Visual Basic
Change all of your Imports Statements from:
using Csla.Validation;
Imports Csla.Validation
To
using Csla.Rules;
Imports Csla.Rules
C#Visual Basic
Update existing method signatures from (as well as existing rule logic inside of the method):
protected override void AddAuthorizationRules()
Protected Overrides Sub AddAuthorizationRules()
To:
public static void AddObjectAuthorizationRules()
Protected Shared Sub AddObjectAuthorizationRules()
Please note that you will also have to wrap the AddObjectAuthorizationRules methods in a #If Not SILVERLIGHT or #if !SILVERLIGHT directive if you are also Generating Silverlight Support.