Deploying Domain-Specific Language Solutions
Updated: July 2011
You can install a domain-specific language on your own computer or on other computers. Visual Studio must already be installed on the target computer.
In this topic:
There are two methods of deploying a domain-specific language:
VSX (Visual Studio Extension)
Very easy to deploy: Copy and execute the .vsix file from the DslPackage project.
For more information see Installing and Uninstalling a DSL by using the VSX.
MSI (installer file)
You must add a setup project to your solution to create an MSI.
For more information, see Deploying a DSL by using an MSI file.
When your DSL is installed by this method, the user can open a DSL file from within Visual Studio, but the file cannot be opened from Windows Explorer.
To install a DSL by using the VSX
In your computer, find the .vsix file that was built by your DSL Package project.
In Solution Explorer, right-click the DslPackage project, and then click Open Folder in Windows Explorer.
Locate the file bin\*\YourProject.DslPackage.vsix
Copy the .vsix file to the target computer on which you want to install the DSL. This can be your own computer or another one.
The target computer must have one of the editions of Visual Studio that supports DSLs at run time. For more information, see Supported Visual Studio Editions for Visualization & Modeling SDK.
The target computer must have one of the editions of Visual Studio specified in DslPackage\source.extensions.manifest.
On the target computer, double-click the .vsix file.
Visual Studio Extension Installer opens and installs the extension.
Start or restart Visual Studio.
To test the DSL, use Visual Studio to create a new file that has the extension that you defined for your DSL.
To uninstall a DSL that was installed by using VSX
On the Tools menu, click Extension Manager.
Expand Installed Extensions.
Select the extension in which the DSL is defined, and then click Uninstall.
Rarely, a faulty extension fails to load and creates a report in the error window, but does not appear in Extension Manager. In that case, you can remove the extension by deleting the file from:
By defining an MSI (Windows Installer) file for your DSL, you can allow users to open DSL files from Windows Explorer. You can also associate an icon and short description with your file name extension. In addition, the MSI can install an XSD that can be used to validate DSL files. If you want, you can add other components into the MSI that will be installed at the same time.
For more information about MSI files and other deployment options, see Deploying Applications and Components.
To build an MSI, you add a Setup project to your Visual Studio solution. The easiest method of creating a Setup project is to use the CreateMsiSetupProject.tt template, which you can download from the VMSDK site.
To Deploy a DSL in an MSI
Set InstalledByMsi in the extension manifest. This prevents the VSX from being installed and uninstalled except by the MSI. This is important if you will include other components in the MSI.
Insert the following line before <SupportedProducts>:
Create or edit an icon that will represent your DSL in Windows Explorer. For example, edit DslPackage\Resources\File.ico
Make sure that the following attributes of your DSL are correct:
In DSL Explorer click the root node, and in Properties window, review:
Click the Editor node and in the Properties window, click Icon. Set the value to reference an icon file in DslPackage\Resources, such as File.ico
On the Build menu, open Configuration Manager, and select the configuration that you want to build, such as Release or Debug.
Go to Visualization and Modeling SDK home page, and from the Downloads tab, download CreateMsiSetupProject.tt.
Add CreateMsiSetupProject.tt to your Dsl project.
Visual Studio will create a file named CreateMsiSetupProject.vdproj.
In Windows Explorer, copy Dsl\*.vdproj to a new folder named Setup.
(If you want, you can now exclude CreateMsiSetupProject.tt from your Dsl project.)
In Solution Explorer, add Setup\*.vdproj as an existing project.
On the Project menu, click Project Dependencies.
In the Project Dependencies dialog box, select the setup project.
Select the box next to DslPackage.
Rebuild the solution.
In Windows Explorer, locate the built MSI file in your Setup project.
Copy the MSI file to a computer on which you want to install your DSL. Double-click the MSI file. The installer runs.
In the target computer, create a new file that has the file extension of your DSL. Verify that:
In Windows Explorer list view, the file appears with the icon and description that you defined.
When you double-click the file, Visual Studio starts, and opens the DSL file in your DSL editor.
If you prefer, you can create the Setup project manually, instead of using the text template. For a walkthrough that includes this procedure see Chapter 5 of the Visualization and Modeling SDK Lab.
To uninstall a DSL that was installed from an MSI
In Windows, open the Programs and Features control panel.
Uninstall the DSL.
Restart Visual Studio.
You can package several DSLs as part of a single solution so that they are installed together.
You can use several techniques to integrate multiple DSLs. For more information, see Integrating Models by using Visual Studio Modelbus and How to: Add a Drag-and-Drop Handler and Customizing Copy Behavior.
To build more than one DSL in the same solution
Create two or more DSL solutions and a VSIX project, and add all the projects to a single solution.
To create a new VSIX project: In the New Project dialog, select Visual C#, Extensibility, VSIX Project.
Create two or more DSL solutions in the VSIX solution directory.
Make sure that you create each DSL with a different filename extension.
Change the names of the Dsl and DslPackage projects so that they are all different. For example: Dsl1, DslPackage1, Dsl2, DslPackage2.
In each DslPackage*\source.extension.tt, update this line to the correct Dsl project name:
string dslProjectName = "Dsl2";
In the VSIX solution, add the Dsl* and DslPackage* projects.
You might want to place each pair in its own solution folder.
Combine the VSIX manifests of the DSLs:
For each DSL, choose Add Content and add:
Dsl* project as a MEF Component
DslPackage* project as a MEF Component
DslPackage* project as a VS Package
Build the solution.
The resulting VSIX will install both DSLs. You can test them by using F5, or deploy YourVsixProject\bin\Debug\*.vsix.
An isolated shell lets you determine which Visual Studio functionality you need to interact with your domain-specific language and how that solution should appear. For more information about the Visual Studio isolated shell, see Customizing the Isolated Shell. You can find more information about how to customize the isolated shell in Customizing the Isolated Shell.
To set a Visual Studio Shell as the Deployment Target
In the DslPackage project, open source.extension.tt.
Under <SupportedProducts> insert:
Replace MyIsolatedShell with the name of your isolated shell package.