Walkthrough: Deploying a Domain-Specific Language

After you develop a domain-specific language, you can register the domain-specific language as a Visual Studio package. If you register your domain-specific language, you can then distribute it to your colleagues. Furthermore, you will probably have developed a project that contains templates that generate code or other artifacts from the domain-specific language. You will also want to distribute this project.

In this walkthrough, you create a Windows Installer (.msi) file for distribution to other Visual Studio users. After a user runs the .msi file, that user can create and open files that use your domain-specific language. Each user can use the New Project wizard to create projects that replicate your own.

To create the .msi file, you first create a setup project. The setup project contains a file that is named InstallerDefinition.dslsetup. This file specifies information about the domain-specific language that is required to create the .msi file. It is the only file in the project that you must change: everything else is generated from it. When you build the setup project, you generate the .msi file.

Prerequisites

For this walkthrough, you will need:

• Visual Studio 2008.

  Nota

  For a list of the editions that Domain-Specific Language Tools supports, see Supported Visual Studio Editions for Domain-Specific Language Tools.

• Visual Studio 2008 SDK.

Create a Minimal Language project

The first step in this walkthrough is to find a domain-specific language that you can deploy. Typically, you would use the solution that you have developed. This walkthrough uses the User Interface Process sample. For more information, see User Interface Process Sample.

The User Interface Process sample defines a domain-specific language in which a user can draw the sequence in which the pages of a wizard appear. The project defined in the debugging solution generates the code for a wizard. You can then incorporate the code into a larger application. This walkthrough is written as if you developed this sample and ran it in the Visual Studioexperimental build until the domain-specific language and the code-generating templates were final. You can use the walkthrough to prepare the sample for use in all editions of Visual Studio and for distribution to your team colleagues. They can use this sample whenever they need to include a wizard in their applications.

In this section, you build the solution in the experimental build before you export the solution as a project template.

To find the User Interface Process sample

1. Click Start, point to All Programs, point to Microsoft Visual Studio 2008 SDK, and then click Microsoft Visual Studio 2008 SDK.

2. In the SDK Area list, click DSLTools.

3. Click C# End-End.WizardUIP, and then click Open this sample in Visual Studio.

   Nota

   At this point, you can inspect and become familiar with the sample's DslDefinition.dsl file in the Dsl project.

4. On the Build menu, click Build Solution.

   This step ensures that the assemblies are available, up to date, and ready to be packaged into your .msi file.

Create a Project Template

The .msi file that you provide to your users makes it possible for them to create projects that replicate your own experimental (debugging) project. In this section, you export the experimental project and create a project template.

To create a project template

1. On the Debug menu, click Start Without Debugging.

   An instance of the experimental build opens. For more information about the experimental build, see Experimental Build.

2. In Solution Explorer, expand the WizardUIP project.

   This project contains a file that is named "WizardUIPDefinition.uip" and a GenerateCode folder, which contains several templates that generate code.

   This walkthrough assumes you have authored both the domain-specific language that is used in the .uip file and the contents of the WizardUIP project. When your user runs the .msi file that you are about to create, the user can replicate this project by using the New Project wizard.

3. To check your solution one last time before you distribute it, open the Debug menu of the experimental build, and click Start Debugging. In the Mock Application dialog box that appears, click Start.

   In the wizard that appears, notice that the sequence of pages follows the sequence that is drawn in WizardDefinition.uip.

4. Click or type any string into text boxes that are labeled "required."

5. On the last page of the wizard, click Finish, click OK in the confirmation dialog box that appears, and then close the Mock Application dialog box.

6. On the File menu, click Save All.

7. On the File menu, click Export Template.

   The Export Template Wizard appears.

8. On the Choose Template Type page, verify that Project template is selected, and click Next.

9. On the Select Template Options page, clear the Automatically import the template into Visual Studio check box, and then provide the following information:

   • In Template name, type WizardUIP if it is not present already.

   • In Template description, type A project template for creating wizards.

10. Click Finish.

    Windows Explorer opens, and a folder that contains WizardUIP.zip (Compressed) appears. This file is the project template that the wizard created.

    Nota

    You must provide the path of this file later in this walkthrough.

11. Close the experimental build.

Add a Setup Project

By using just the project template, you can generate Wizard UIP projects from the New Project dialog box. However, you can also enable your users to open and create files in your Wizard UIP domain-specific language. You must therefore integrate the project template and the Dsl and DslPackage assemblies into an .msi file. To integrate these files, you add a setup project to your domain-specific language solution.

To add a setup project

1. Be sure that you are working in the main copy of Visual Studio with the Dsl and DslPackage projects.

   The experimental build should be closed.

2. In Solution Explorer, right-click Solution Wizard UIP, point to Add, and then click New Project.

   The Add New Project dialog box appears.

3. Under Project types, expand the Other Project Types node, and click Extensibility.

4. Under Templates, click Domain Specific Language Setup.

5. Leave the default name, Setup1, and click OK.

   Nota

   When you create a project, the system automatically generates the default text templates. When you generate a text template, you will see a message that warns you not to run text templates from untrusted sources. If you do not want this message to appear again, select the Do not show this message again check box, and click OK. Otherwise, click OK.

Add a Project Template to the Setup Project

When you created the setup project, the system opened a file named InstallerDefinition.dslsetup in the XML editor. This file describes the language to be deployed. It is used to generate the WiX files. In the next step, you modify this file to add the project template that you created earlier.

To add a project template

1. If necessary, in Solution Explorer, expand the Setup1 project node.

2. Right-click the Files folder in the Setup1 project, point to Add, and click Existing Item.

3. In the Add Existing Item dialog box, in Files of type, click All Files (*.*).

4. Browse to the project template file named WizardUIP.zip, which you created earlier, click it, and then click Add.

   Typically, you would modify the other files in the Files folder. The End User License Agreement (EULA) between you and your users will appear when your users install your domain-specific language. The Readme.htm will appear after the installation.

5. If InstallerDefinition.dslsetup does not appear in the XML editor, in Solution Explorer, under the Setup1 project node, double-click InstallerDefinition.dslsetup to open it.

6. Insert the following XML under the </vsItemTemplates> end tag, which is near the end of the file:

   <vsProjectTemplates>
     <vsProjectTemplate localeId="1033" targetDirectories="CSharp" templatePath="Files\WizardUIP.zip" />
   </vsProjectTemplates>
   

   This XML element directs the Setup build to include the project template in the .msi file. For a description of the elements and attributes that are used in this fragment, see Appendix B: DslSetup Schema Description.

7. Insert the following supportingAssembly directive directly underneath the existing one:

   <supportingAssembly name="UIProcess" project="FabrikamFrameworksUIProcess" assemblyPath="Fabrikam.Frameworks.UIProcess.dll"/>
   

   This directive directs the Setup build to include an extra assembly, which you (as the language author) created as the framework on which wizard projects will run.

8. Right-click the following files in the Setup1 project, and click Run Custom Tool to regenerate the WiX file.

   • Files.tt

   • Main.tt

   • Registry.tt

   • UI.tt

   As an option, you can click Transform All Templates on the Solution Explorer toolbar.

9. Verify that the generated files contain material. Click the [+] next to each .tt file, and open the file underneath. If errors are reported, verify the XML that you inserted in the previous step.

Build the Setup Project

Next, you need to build the setup project.

To build a setup project

1. Right-click the Setup1 project, and click Build.

2. On the Project menu, click Show All Files.

   In Solution Explorer, in the Setup1 project, expand the \bin folder, and then expand the \debug folder to display the .msi file you built.

Install and Test the Domain-Specific Language

The next step is to install and test the domain-specific language. You can deploy the language to the same computer on which you developed it. However, the recommended approach is to deploy the language to a second computer. By using this approach, you can avoid conflicts between the deployed version of the language and the version that you are developing. You can also verify whether the installation works outside your own system. If you use the same computer, you should remove the language before you further develop the domain-specific language. See the following section, “Uninstall the Domain-Specific Language,” for details.

Nota

Although these two versions can exist at the same time on the same computer, the version numbers of the Dsl and DslPackage assemblies must be unique.

To install and test the language

1. In Windows Explorer, browse to the output directory of the Setup1 project, which will be:

   SolutionDirectory\Setup1\bin\Debug

   Nota

   To display the full path, in Solution Explorer, click the file name in the Debug folder. The Full Path property appears in the Properties window.

2. Copy all the files in this directory to a directory on a second computer.

   At a minimum, you must have Visual Studio 2005 Standard Edition installed on the second computer.

   Advertencia

   Because you did not obtain a package load key for the language, you must also have the Visual Studio 2005 SDK October 2005 installed on the second computer. If you do not install Visual Studio 2005 SDK, the diagram will display only in XML format and will not display as a diagram in the next procedure. For more information about package load keys, see Appendix A: Visual Studio Package Load Keys.

3. On the second computer, double-click the .msi file to install the language.

4. When the WizardUIP Setup dialog box appears, click OK.

   The system installs the run-time components of Domain-Specific Language Tools, and an installation wizard appears.

5. Click Next, and accept all defaults in subsequent pages in the wizard. On the License Agreement page, you must click I Agree before you can continue.

   When the wizard finishes, a Readme file opens in a separate window because InstallerDefinition.dslsetup specified that the readme file should open automatically after installation. For more information, see Appendix B: DslSetup Schema Description.

6. Close the Readme window, and click Close to close the wizard.

To test the language

1. Open Visual Studio 2008.

2. On the File menu, point to New, and then click Project.

3. Under Project Types, click the Visual C# node.

4. Under Templates, click WizardUIP, and click OK.

   The system creates a project that contains the same content as in your debugging solution.

5. Double-click WizardUIPDefinition.uip in this project to open your domain-specific language.

   The new domain-specific language works in Visual Studio.

To run the installed example

1. Open the ReadMe.htm that is included in the new project to display information about how to run the sample.

   For this sample, you must make some adjustments to namespaces and assembly names before you can run the project.

2. Follow the instructions in ReadMe.htm to run the sample.

   The sample runs as it originally did in your debugging solution.

Uninstall the Domain-Specific Language

You can uninstall the domain-specific language by using Add or Remove Programs in Control Panel.

To uninstall the domain-specific language

1. Open Control Panel, and double-click Add or Remove Programs.

2. In the list of installed programs, click WizardUIP, click Remove, and click Yes.

   Nota

   As an alternative, you can right-click the .msi file in the installation folder and select Uninstall.

   If you installed the domain-specific language on a computer on which Domain-Specific Language Tools was not installed, you might also want to remove the run-time components for the toolkit that were installed with the language.

3. To remove these components, click Microsoft DSL Tools Redistributable in the list of installed programs, click Remove, and click Yes.

   Nota

   For information about how to remove a domain-specific language in addition to the deployment package, see How to: Remove a Domain-Specific Language

See Also

Concepts

Deploying Domain-Specific Language Solutions

User Interface Process Sample

Domain-Specific Language Tools Glossary

VSPackages