# Migration Guide

## Migrating existing DSL Tools Designer Projects from the September 2005 CTP to the November 2005 CTP

This is a list of instructions for converting a DSL Tools project created with the September 2005 CTP to the November 2005 CTP. To convert between releases, you will need to create a new project from one of the templates included in the November 2005 CTP, and then replace various files in the new project with files from the original project. These instructions assume you have only modified the .dsldd, .dsldm, and resource files associated with your original project. If you’ve added other files (such as additional source files), follow these steps first, and then add those files to the new project as well.

### Step 1: Create a new project using the Minimal Language template:

- Create a new project by choosing the Domain Specific Language Designer project template. This will launch the project wizard.
- On Page 1 of the wizard choose the Minimal Language template .
- On Page 2, set the language name, root namespace, and file extension to the same values used in your original designer.

Tip: Open the <projectname>\Designer\Designer.dsldd file from your original solution, and you will find a line similar to the following at the top of the file:

<designerDefinition namespace="<rootNamespace>.Designer" name="<languageName>" xmlns="http://schemas.microsoft.com/dsltools/dsldd">

The values in place of <rootNamespace> and <languageName> in your Designer.dsldd file are the root namespace and language name values used in your original solution. You can find the file extension you originally provided by locating a file named <extension>.<extension> in the Designer\ItemTemplates folder in your original solution.

- On Page 3, you should see your original designer listed for your file extension. Make sure theDe-register these old DSL tools box is checked, and click Next to unregister your old designer.
- On Page 4, choose the key file used to sign your original designer. This will be a file called Key.snk found in the root directory of your original project.
- On Page 5, set the company name to the same value used in your original designer (if you originally left this blank, do so again). Set other properties on this page as desired.
  Tip: You can find the company name you originally used in the file Constants.cs in the folder Designer\Shell.
- Click Finish to complete the wizard and generate your project.
- Close Visual Studio.

### Step 2: Copy the modified files from your original project into the new project from Step 1 and open the new project

· Use the Windows Explorer to copy the modified .dsldm and .dsldd files from your original project to the new project. The new paths are: <projectname>\DomainModel\DomainModel.dsldm and <projectname>\Designer\Designer.dsldd.

Re-open the new project in Visual Studio.

### Step 3: Add any additional resources from the old solution

If you have modified resources in your designer, you need to replace the corresponding resource files in the new solution with files from the old solution manually. If you did not modify resources then skip this step.

· Use Windows Explorer to replace the resource files (do not use the Solution Explorer in Visual Studio to do this). Copy the old resource files into the file tree of the new project.

The locations of the resource files in the old project are:

- <projectname>\Designer\Properties\Resources.resx
- <projectname>\Designer\Diagram\Designer.Resource.resx
- <projectname>\Designer\Resources\*.*
- <projectname>\DomainModel\Properties\Resources.resx
- <projectname>\DomainModel\DomainModel.Resource.resx

Note: Two strings related to model validation have been added to the file <projectname>\Designer\Diagram\Designer.Resource.resx, which are referenced from the generated code. After replacing this file, you should open it in Visual Studio and add the following strings through the resource editor:

Name | Value
SaveValidationFailed | There were validation errors, continue save?
SaveOperationCancelled | Save operation cancelled.

Please make sure that for each *.resx file the value "ResXFileCodeGenerator" is set for the "Custom Tool" property in the Properties Window.

> Note: Solutions created with the DSL toolkit now use the managed package resource feature provided by the VS SDK. This means that the C++ project named DesignerUI has been removed, and all of its contents merged into the Designer project. If you modified any parts of the DesignerUI project in your original solution, such as resources (DesignerUI.rc) or command definitions (PkgCmd.ctc), these modifications will need to be moved to the Designer project. Resources, such as strings (including package load keys), icons, or other images, should be moved into the file <projectname>\Designer\Shell\VSPackage.resx. CTC file modifications should be made to the file <projectname>\Designer\CtcComponents\CustomCmd.ctc. The structure of CustomCmd.ctc is different from the old PkgCmd.ctc, so PkgCmd.ctc should not be copied directly over the new file. Rather, command definitions added to the original solution should be copied individually to CustomCmd.ctc. For more information on using managed resources in VS packages, see the VS SDK documentation.

### Step 4: Adding a Setup Project to a Migrated Solution

If you migrate a solution from M3 to M4 and then add a Setup project to your solution, it will fail because the M3 version of the designer wizard lacks some required fields in the designer definition. If you plan on adding a setup project to you're solution you first have to add the following attributes to the designerDefinition entry in the dsldd file:

- companyName
- fileExtension
- productVersion
- productName
- packageName

### Step 5: Run your designer

· Open Visual Studio

· Re-generate the code, build, and run your designer.

In the debugging solution, delete the file named “Sample.<extension>”. This file contains serialized data for the original Minimal Language domain model, and will not open properly with your new designer. The file “Test.<extension>” will open properly, and will display a blank design surface.