Modifying the Guidance Package
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies.
With the Windows Installer of the Smart Client Software Factory, you can choose to install the source code for the guidance package, install the guidance package and register it, or you can choose to both install the source code and register the guidance package. When you choose to register the guidance package, the installer copies the guidance package contents and assemblies to your computer. When you install the source code, you can compile the guidance package to create the assemblies. The guidance package you can register with Windows Installer and the guidance package you can install as source code are identical with the exception of their identifiers. This means you can customize the guidance package source code, register it, and use it side by side with the guidance package that is registered by Windows Installer.
You can modify the existing guidance package, or create new guidance packages, to customize the Smart Client Software Factory. You use Visual Studio 2008, the Guidance Automation Toolkit and the Visual Studio 2008 SDK to modify and create guidance packages. To download the Guidance Automation Toolkit, see Guidance Automation Extensions and Guidance Automation Toolkit Download.
The Guidance Automation Toolkit documentation describes the considerations, design guidelines, and technical details that a developer uses to create a guidance package. This topic describes a few key use cases that you can use to modify the Smart Client Development guidance package. For further considerations and technical details, see the Guidance Automation Toolkit documentation.
This section includes development tips for modifying a guidance package.
Use the Register Guidance Package Recipe and Test the Results in a Second Instance of Visual Studio
You do not have to build the Windows Installer program to test your guidance package changes. Instead, use the Register Guidance Package recipe. After you execute this recipe, launch a second instance of Visual Studio, create a new smart client solution, and test your changes. To make more changes, exit the second instance of Visual Studio and return to the guidance package solution.
Use the Quick Register Recipe When Appropriate
Full registration of a guidance package requires time to process the entire package. After you register your guidance package, you can use the Quick Register recipe if you do not change the HostData elements or add a new recipe. The Quick Register recipe takes much less time than the Register Guidance Package recipe.
Change the Guidance Package Identifiers for Your Custom Version
The Name and Guid attributes in the guidance package configuration file SmartClientDevelopment.xml uniquely identify the guidance package. If you do not change these identifiers, your custom version will replace the original guidance package when you register or install your custom guidance package. It is recommended that you also change the Caption and Description attributes.
<GuidancePackage xmlns="http://schemas.microsoft.com/pag/gax-core" xmlns:xi="http://www.w3.org/2001/XInclude" Name="CustomSmartClientFactoryPackage" Caption="Custom Smart Client Development" Description="Custom Smart Client Development" Guid="4D23D563-803C-43dc-BA99-38223B7C9888" BindingRecipe="BindingRecipe" SchemaVersion="1.0">
Use the Export Template Feature of Visual Studio to Create or Update Your Templates
When you create a template, create your project or item in Visual Studio and then export the project (or item) as a template. To update an existing template, you should also consider modifying the original source project in Visual Studio and then exporting it again. When you do this, you can use Visual Studio to verify your syntax.
|The Build Action property for the template code in the Smart Client Development guidance package solution is Content. This means that the template code is not compiled, and when you build your guidance package, Visual Studio will not report syntax errors in your template code. |
If you add new template files to your guidance package, for each new file, you must set the Build Action property to Content and set the Copy to Output Directory property to Copy if newer.
Update Your Templates to Associate the Recipe Framework
The Visual Studio templates you create for use with the recipe framework contain additional information when compared with the templates normally used by Visual Studio. You must add the following XML to your project's .vstemplate file to transform the template into a Guidance Automation Toolkit solution template.
<WizardExtension> <Assembly>Microsoft.Practices.RecipeFramework.VisualStudio, Version=184.108.40.206, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a</Assembly> <FullClassName>Microsoft.Practices.RecipeFramework.VisualStudio.Templates.UnfoldTemplate</FullClassName> </WizardExtension>
Bind Your Guidance Package After You Modify the Binding Recipe
The Smart Client Development guidance package contains the binding recipe named BindingRecipe. If you change the binding recipe, you must re-execute the binding recipe in your solution. To do this for existing solutions, disable, and then re-enable, the guidance package. When you do this, the Guidance Automation Extensions will execute the binding recipe.
Development Process Overview
To distribute a guidance package, you create and distribute a Windows Installer package. Developers run the setup program and then enable the guidance package. If you distribute a new version of the guidance package, developers must uninstall the previous version of the guidance package before installing the new one. This process works well when you distribute a guidance package. However, it makes it difficult to efficiently test incremental changes as you modify a guidance package. For developers of guidance packages, the Guidance Automation Toolkit provides recipes that make it easier to test changes. These recipes are named Register Guidance Package, Quick Register, and Unregister Guidance Package.
|To use these recipes, you must enable the Guidance Package Development guidance package.|
Registering a Guidance Package
The Guidance Package Development solution contains two recipes associated with the guidance package project:
- Register Guidance Package. This recipe registers the package you are developing on your computer. Registration is a form of installation that you can perform without leaving the Visual Studio development environment.
- Quick Register. This recipe performs a quick registration of the guidance package. You must perform a full registration of the guidance package before you use the Quick Register recipe.
- Unregister Guidance Package. This recipe reverses the registration.
After you register a guidance package, you can open a new instance of Visual Studio to test the functionality of the package. This means that you do not have to continually rebuild the setup project and run the Windows Installer package for the guidance package every time you want to test the progress of your development.
You should unregister the package if you want to do one or both of the following:
- Install the guidance packages using the Windows Installer package.
- Remove the guidance package from your computer.
After you unregister a guidance package (or uninstall it), you can register it again by executing the Register Guidance Package recipe.
Summary of Steps
The following steps describe the process you can use to modify and test the Smart Client Development guidance package:
- Using Visual Studio, open and build the solution file GuidancePackage.sln.
- Use the Guidance Package Manager to enable the Guidance Package Development guidance package. You must do this before you can use the Register Guidance Package recipe, Quick Register recipe, or Unregister Guidance Package recipe.
Note: After you enable the Guidance Package Development guidance package, the Guidance Navigator will appear in Visual Studio. This window displays an overview of the guidance package and available recipes.
- In Solution Explorer, right-click SmartClientFactoryPackage, and then click Register Guidance Package.
- Open a new instance of Visual Studio. In this new instance, use a solution template from the guidance package to create a new solution.
- Run any guidance package recipes and test the results.
- Close this instance of Visual Studio.
- In the GuidanceAutomation solution, make your changes, and then rebuild the solution.
- Repeat steps 3–5 to test your changes. Use the Quick Register recipe instead of Register Guidance Package recipe if you have not made changes to the HostData elements or added new recipes.