Project Linker: Synchronization Tool

  • Article

This topic is the starting point to learn how to use and the features available in Visual Studio Tooling Synchronization Package, also known as the Project Linker.

The approach the patterns & practices team is taking for multi-targeting is to provide guidance on structuring application and module code into multiple linked projects. Each project manages all the references, resources, and code specific to the Windows Presentation Foundation (WPF) or Silverlight target environment.

Manually maintaining the links between files in multiple projects using Visual Studio is possible, but it can be time consuming and error prone. For this reason, the Composite Application Guidance for WPF and Silverlight provides the Project Linker tool. This tool helps to automatically create and maintain links from a source project to a target project to share code that is common to Silverlight and WPF. Therefore, shared code can be written once and built for the target environment.

Installing

The follow procedure describes how to install the Project Linker.

To install the Project Linker

  1. Run the file MicrosoftPracticesProjectLinker.msi. The welcome screen appears. Click Next to continue.
  2. After you read and accept the End-User License Agreement (EULA), click Next.
  3. Select the installation folder, and then click Next.
  4. Click Next to confirm the installation. The installation will proceed.
  5. Click Close to exit the installer.

Note

There are no known issues with installing the Project Linker in Visual Studio; however, all scenarios for the Project Linker have not been tested, so you are strongly encouraged to use a recoverable version of Visual Studio.
Alternatively, you can compile and run the Project Linker in the Visual Studio Experimental Hive. For information about how to do this, see the Running the Project Linker in the Visual Studio Experimental Hive section.

Project Linker Features

This section describes the features and operations that can be performed with the Project Linker.

Linking a Source Project to a Target Project

To link a source project to a target project, right-click the target project, and then click Add Project Link. In the Select Project dialog box, click the source project, and then click OK. The Select Project dialog box is shown in Figure 1.

Ff921108.092b9cf2-b0bc-4eae-bdb2-57f363534ae7(en-us,PandP.20).png

Figure 1

Project Linker — Select Project dialog box

To see the current links in Visual Studio, click Edit Links on the Project menu. In the Project Links dialog box, you can also unlink a project; to do this, click the project link, and then click the Unlink button, as illustrated in Figure 2.

Ff921108.82fb0d67-3b32-4f5f-b117-efcb00472db7(en-us,PandP.20).png

Figure 2

Project Linker — Project Links dialog box

Adding a File to the Source Project

When a file is added to the source project, and if the filter does not filter it out, a link to this file will be added on the target solution. (For more information about filters, see the File Filtering section.)

If you are adding a file to a folder that exists only in the source project but not in the target project, and if the file passes the filter conditions, a link to file will be added, and the folders needed to meet that path in the target project will also be added. If the file does not meet the filtering conditions, no changes will be made to the target project.

When a file is added to the source project and a physical file with the same name already exists on the target project's folder (whether or not it is included in the project), no action will be taken. Adding a file to the source project and its results are shown in Figure 3.

Ff921108.6abe4e4f-2a15-4689-b653-2a50a6c426dc(en-us,PandP.20).png

Figure 3

Adding a file to a source project

Adding a Folder to the Source Project

When a folder is added to the source project, and if the filter allows it, a new folder will be created on the target solution.

When a folder is added to the source project and a folder with the same name already exists on the target project but it is not included on it, the Project Linker will include the folder to the project with all its contained files. If the folder is already included on the target project, no action will be taken.

Note

The behavior of including all files contained in a folder is the same behavior that occurs when you right-click an excluded folder and then click the Include in Project option.

Adding a folder to the source project and its results is shown in Figure 4.Ff921108.57c4c10d-8913-4df8-b1f9-00eb2d1a4156(en-us,PandP.20).png

Figure 4

Adding a folder to a source project

Removing a File in the Source Project

When a file is removed on the source project, the linked file associated with it on the target project will also be removed, as illustrated in Figure 5.

Ff921108.4434e21d-c249-44e6-8f6f-2c3ae440d6d3(en-us,PandP.20).png

Figure 5

Removing a file from a source project

Removing a Folder in the Source Project

When a folder is removed on the source project, and if the folder on the target project has no physical files on its substructure (that is, it contains folders or link files), it will be removed.

However, when you delete a folder on the source project, and if the linked folder on the target project contains items in addition to empty folders (that is, files or manually created links to other files), the folder will not be deleted from the target project. Removing a folder in the source projects and its results is shown in Figure 6.

Ff921108.5973d72f-299e-4751-84b0-25e2de276cb4(en-us,PandP.20).png

Figure 6

Removing a folder from a source project

Renaming and Moving Files

When you move or rename files, this is accomplished internally by removing the old file and adding a new one. If the file cannot be removed because the linked file did not exist on the target project, it is still added in the new folder (or with the new name) if the filter allows it, as illustrated in Figure 7.

Ff921108.37b9ca8c-9070-4b87-ac6b-75506ad10314(en-us,PandP.20).png

Figure 7

Moving a file to a different location

Renaming and Moving Folders

Moving a folder first moves all the files that it contains; after that, the folder is deleted, and then the folder addition will be attempted. This is because all rules from additions and deletions apply for renaming and moving. The renaming and moving operations and their results are shown in Figure 8.

Ff921108.ada418a5-f01d-4c99-b33a-84753527e831(en-us,PandP.20).png

Figure 8

Moving a folder to a different location

File Filtering

Filters can be specified to avoid auto-linking every file. This is useful if you are writing code specific to Silverlight or WPF that should not be shared across projects.

Currently, files that fulfill at least one of the following conditions are filtered out:

  • Files that have the file name suffixes .Silverlight.cs or .WPF.cs
  • Files that reside in Silverlight or Desktop folders
  • XAML files

Note

Plans are being made to allow defining custom filters using regular expressions in future versions of the tool.

Uninstalling

The following procedure describes how to uninstall the Project Linker.

To uninstall the Project Linker

  • In Windows Vista, double-click the Programs and Features icon in Control Panel, and then click Uninstall for the MicrosoftPracticesProjectLinker item.
  • In Windows XP, double-click the Add or Remove Programs icon in Control Panel, and then click Remove for the MicrosoftPracticesProjectLinker item.
  • To use the installer to remove the Project Linker, select the Remove the MicrosoftPracticesProjectLinker option, and then click the Finish button.

Running the Project Linker in the Visual Studio Experimental Hive

The following procedure describes how to run the Project Linker in the Visual Studio Experimental Hive.

To run the Project Linker in the Visual Studio Experimental Hive

  1. In Visual Studio, open the solution file ProjectLinker.sln.
  2. Right-click the ProjectLinker project, and then click Properties.
  3. Click the Debug tab. It the Start Actions section, select Start external program, look for the Visual Studio executable file, Devenv.exe (typically, it is located at Program Files\Microsoft Visual Studio 9.0\Common7\IDE\), and then click OK.
  4. In the Command line arguments text box in the Start Options section, type the following arguments: /rootsuffix Exp /RANU.
  5. Save the changes.
  6. Run the solution. To do this, press F5, making sure that the ProjectLinker project is set as the startup project.

Frequently Asked Questions About the Project Linker

It is not possible. This is being validated; therefore, self reference is not allowed.

How do you identify which project is linked to which other project? How do you identify the source project and the destination project in the linking?

On the Project menu, click Edit Links. The Edit Links dialog box shows all the current links, including the source project and the project it is linked to. You can also use this dialog box to unlink projects.

Currently, the Project Linker works with any project type that you want. Keep in mind that linking between incompatible kinds of projects, such as between a Workflow project and a Silverlight project, is allowed, but it might lead to compile errors.

However, linking between C# projects and Visual Basic projects is not allowed. The OK button in the Select Source Project dialog box is not available if the project languages are different.

What happens if the linked files are deleted in the destination projects and the same file is updated in the source project?

If the updates are within the file, the destination project should not be affected.

What happens if the linked files are deleted in the destination projects and the files are renamed in the source project?

Currently, this causes the linked file to appear in the destination project with the new name, by design.

What happens if the destination project already has the file that is being synchronized?

If the destination project already contains the file being synchronized, the Project Linker does not ignore it; therefore, it will not create the link.

Is multi-project linking allowed?

You can have several projects linked to the same source, but each target project can have only one source project associated.

Yes, it is possible. The project starts synchronizing the moment the projects are linked. However, you have to manually synchronize existing files.

Acceptance Tests

The Project Linker solution includes a separate solution that includes acceptance tests. The acceptance tests describe how the application should perform when you follow a series of steps; you can use the acceptance tests to explore the functional behavior of the application in a variety of scenarios.

Some acceptance tests were developed using the testing framework White. To run these tests, you need to have White installed. For more information about White, including download information, see White on CodePlex.

Note

The acceptance tests have been developed and verified with the White 0.1.5.0 release. Although other releases of White might work, it is recommended to use this release to avoid any issues when running the tests.

To run the Project Linker acceptance tests

  1. Place the assemblies required by White in the folder Source\Lib\White. The files are the following:

    • Bricks.dll
    • Bricks.RuntimeFramework.dll
    • Castle.Core.dll
    • Castle.DynamicProxy2.dll
    • Core.dll
    • log4net.config
    • log4net.dll
    • nunit.framework.dll
    • White.NUnit.dll
    • Xstream.Core.dll

  2. In Visual Studio, open the solution file ProjectLinker\ProjectLinker.Tests.AcceptanceTest\ ProjectLinker.Tests.AcceptanceTest.sln.

    Note

    No other tasks or operations should be performed during the acceptance tests because the handle of the Visual Studio is used for performing acceptance testing.
    Solution Explorer should be made visible and should not be dockable in the file ProjectLinker.Tests.AcceptanceTest.sln.

  3. Right-click the project ProjectLinker.Tests.AcceptanceTest, and then click Set as StartUp Project.

  4. Press F5.

More Information

For information about creating multi-targeted applications in WPF and Silverlight, see the following topics:

Home page on MSDN | Community site