Upgrading the CSLA templates

The CSLA templates aim to stay backward compatible. Occasionally a change breaks compatibility, when the benefit clearly outweighs the cost. Follow this guide when you upgrade the templates to make the move as smooth as possible.

Upgrade to a newer version of the templates

These steps update an existing solution to use a newer version of the templates. First, download and install the templates.

Update your Visual Studio solution's dependencies

Make sure your solution meets the requirements of the CSLA version you're moving to. For example, to move from CSLA 3.8 to CSLA 4, upgrade your projects to a .NET Framework version that CSLA 4 supports, and use a version of Visual Studio that supports it.

When your projects target the right version of the .NET Framework, update the assembly references: in Solution Explorer, right-click each CSLA assembly reference and select Remove. Do this in every project. Generator adds assembly references that don't exist, but it doesn't update existing ones.

Update your Generator project files

Each Generator project file keeps pointing to the old templates until you update the template path of each output. The fastest way is to open the project file in a text editor and update the template attribute of each propertySet to the new location. Change:

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

to:

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

Then save the file.

Next, open the updated project file in Manage Outputs and make sure everything compiles and every property is set correctly. If it doesn't compile, repeat this step.

Regenerate

Right-click the Generator project file and select Build. Then check the Output window for template compile and generation errors:

• If an error says a template file wasn't found, go back to the previous step and check the template path of that output's propertySet.
• If an error says a template property can't be set, the property may no longer exist. Remove the property's XML node from the project file, then set the properties again in Manage Outputs. This is rare.
• If you still can't compile or generate the templates, report the issue on GitHub with the full stack trace or Output window contents.

If your project then fails to compile:

• If you moved between minor versions of CSLA (for example, from 4.3 to 4.5), you've probably found a bug in the templates. Please report it.
• If you moved between major versions of CSLA (for example, from 3.8 to 4), see the next section.

Upgrade from CSLA 3.8 to CSLA 4

Read the CSLA .NET documentation for the changes between CSLA versions. Then follow the steps above to upgrade the templates, and these steps to make your solution compile with CSLA 4.

Update your Generator project files

Open every project file you updated in Manage Outputs, and change the FrameworkVersion property from v35 to v40 (CSLA 4.3) or v45 (CSLA 4.5). This makes the templates generate CSLA 4 code.

Update your non-generated partial classes

Before you start, make sure you followed the steps above and regenerated. You'll see some build errors: the partial classes you edit aren't regenerated, and CSLA 4 changed how rules work.

CSLA 4 made major changes to rules, so update the non-generated partial class of every business object.

1. Change the imports from Csla.Validation to Csla.Rules.

   C#: change

   using Csla.Validation;
   

   to

   using Csla.Rules;
   

   Visual Basic: change

   Imports Csla.Validation
   

   to

   Imports Csla.Rules
   

2. Update the authorization rules method signature, and the rule logic inside the method.

   C#: change

   protected override void AddAuthorizationRules()
   

   to

   public static void AddObjectAuthorizationRules()
   

   Visual Basic: change

   Protected Overrides Sub AddAuthorizationRules()
   

   to

   Protected Shared Sub AddObjectAuthorizationRules()