Editing Manifests

You can use several tools to edit deployment and application manifests.

Using MAGE to Edit Deployment Manifests

The Visual Studio Publish Wizard will automatically generate and update a deployment manifest for you, but should you want to edit the manifest yourself, you have two main options. First, the deployment manifest is nothing more than an XML file sitting on a server; you can use Notepad or any other editor of your choice.

If editing raw XML is not your idea of a good time, you can use the Manifest Generating and Editing (MAGE) tool, mage.exe (see Figure 20.2). MAGE ships with Visual Studio and provides a convenient graphical interface for editing deployment manifests. (Look in the SDK\v2.0\BIN directory of your Visual Studio installation.)

Figure 20.2. Using mage.exe to update a deployment manifest manually torefer to a new version of the customization.

Unfortunately, the VSTO application manifest file format is sufficiently different from the ClickOnce file format that MAGE cannot be used to edit VSTO application manifestsonly deployment manifests. To edit application manifests, you have a couple of options: You can use the VSTO Application Manifest Editor utility, or you can write your own tools using the ServerDocument object model.

Using the VSTO Application Manifest Editor

The VSTO SDK ships with a library of code samples, one of which is a graphical utility for editing application manifests. Load the ApplicationManifestEditor sample solution into Visual Studio, and build it. Then you can use this utility to edit the manifests inside spreadsheets and documents (see Figure 20.3).

Figure 20.3. Using the VSTO Application Manifest Editor to edit the manifest embedded in a spreadsheet file.

Graphical utilities prove handy if you want to change a small number of files, but what if you want to make changes to many customizations at the same time? Then it would be nice to be able to write programs that edit the application manifests directly. Fortunately, the ServerDocument object model can manipulate not just the cached data inside a document, but also the application manifest.

Using the ServerDocument Object Model to Read and Edit Embedded Application Manifests

The ServerDocument object model, discussed in Chapter 18, "Server Data Scenarios," was primarily designed to manipulate the cached data island on the server. You can also use it to read or edit the application manifest stored in a customized document, however. The ServerDocument object can edit the application manifests stored in Word documents saved in either binary or XML format, and Excel documents saved in binary format only.

Listing 20.3 shows how we can modify our cached-data viewer from Chapter 18 to display the application manifest inside a document.

Listing 20.3. Creating an Application Manifest Viewer with ServerDocument

Imports Microsoft.VisualStudio.Tools.Applications.Runtime Imports System.IO Module Module1   Sub Main(ByVal args As String())     If args.Length <> 1 Then       Console.WriteLine("Usage:")       Console.WriteLine("   AppInfoViewer.exe myfile.doc")       Return     End If     Dim filename As String = args(0)     Dim doc As ServerDocument = Nothing     Try       doc = New ServerDocument(filename, False, FileAccess.Read)       Console.WriteLine(vbCrLf & "Application Manifest")       Console.WriteLine(doc.AppManifest.ToXml())     Catch ex As CannotLoadManifestException       Console.WriteLine("Not a customized document:" + filename)       Console.WriteLine(ex.Message)     Catch ex As FileNotFoundException       Console.WriteLine("File not found:" + filename)     Catch ex As Exception       Console.WriteLine("Unexpected Exception:" + filename)       Console.WriteLine(ex.ToString())     Finally       If Not doc Is Nothing Then         doc.Close()       End If     End Try   End Sub End Module 

This section covers all the application-manifest-related properties and methods in the server document object model, describing what they do, their purpose, and why they look the way they do.

Note

As mentioned in Chapter 18, "Server Data Scenarios," because this object model enables you to modify all the information about the customization, it is quite possible to create documents with nonsensical deployment information. The VSTO runtime engine does attempt to detect malformed customization information and throw the appropriate exceptions, but still, exercise caution when using this object model.

Application Manifest Objects, Methods, and Properties

The ServerDocument represents the application manifest as an object of type AppManifest:

Public ReadOnly Property AppManifest As AppManifest 

The AppManifest object has no public constructors; the only way to get an instance of an AppManifest is to open a ServerDocument object. After you have one, there is an easy way to turn an XML manifest into the programmable object model:

Public Sub Clear() Public Sub FromXml(ByVal manifest As String) Public Function ToXml() As String 

The ToXml method turns the current state of the object model into XML. The Clear method throws away all the information in the manifest, making it a blank slate. The FromXml method clearsthe present state of the document before loading the information from the passed-in XML string. The AppManifest object also has four properties:

Public Property Dependency As Dependency Public Property DeployManifestPath As String Public ReadOnly Property EntryPoints As EntryPointCollection Public Property Identity As AssemblyIdentity 

The AssemblyIdentity property is the "assembly" identity of the manifest, not of the customization assembly. This contains the application manifest's version number. If a deployment manifest is used, the VSTO runtime compares the application manifest and deployment manifest versions to see whether the application manifest is out of date.

The DeployManifestPath property gives the URL to the deployment manifest. This property sets the codebase attribute of the second installFrom element in the application manifest.

Using a deployment manifest is optional; if no deployment manifest path is set, the VSTO runtime assumes that the embedded application manifest is always up to date.

An EntryPointCollection is a straightforward, strongly typed collection class that extends CollectionBase with these methods:

Public Function Add(ByVal className As String) As EntryPoint Public Function Contains(ByVal value As EntryPoint) As Boolean Public Sub CopyTo(ByVal entryPoints As EntryPoint(), _   ByVal index As Integer) Public Function GetEnumerator() As EntryPointEnumerator Public Function IndexOf(ByVal entryPoint As EntryPoint) _   As Integer Public Sub Insert(ByVal index As Integer, _   ByVal value As EntryPoint) Public Sub Remove(ByVal entryPoint As EntryPoint) 

Like the AppManifest, the EntryPointCollection and EntryPoint objects have no public constructors. Use the Add method on the EntryPointCollection if you want to create a new EntryPoint. An EntryPoint has only one public property. It should be the namespace-qualified name of the view class:

Public Property ClassName As String 

The Dependency object has two properties:

Public Property AssemblyIdentity As AssemblyIdentity Public Property AssemblyPath As String 

To load the customization assembly, the runtime needs to know both the full name of the assembly and its location. The AssemblyPath corresponds to the codebase attribute of the first installFrom element in the application manifest. As mentioned previously, it may be either an absolute or a relative URL. If absolute, the assembly is loaded from that location. If relative, the path is relative to the location of the deployment manifest's codebase, if there is one, or the document if there is not.

The AssemblyIdentity object does have a public constructor, unlike every other object in the application manifest object model:

Public Sub New(ByVal name As String, _   ByVal version As FourPartVersion, _   ByVal publicKeyToken As String) Public Property Name As String Public Property PublicKeyToken As String Public Property Version As FourPartVersion 

The Name property gives the name of the assembly, not the name of the file containing it; it should not end in .dll.

The PublicKeyToken property is part of the strong name. A full public key encoded as a string is a rather long and unwieldy string. The public-key token is a much shorter statistically guaranteed-unique key that identifies the public key used to verify a strong-named assembly. (See Chapter 19, ".NET Code Security," for more details on what a strong name is and what the key token is for.) You can use sn.exeT myassembly.dll to give the public-key token of a strong-named assembly.

Finally, the FourPartVersion object is a value type that keeps track of "1.2.3.4"-formatted version numbers. It has the following properties and methods:

Public Sub New(ByVal major As Integer, ByVal minor As Integer, _   ByVal buildNumber As Integer, ByVal revision As Integer) Public Property BuildNumber As Integer Public Property Major As Integer Public Property Minor As Integer Public Property Revision As Integer Public Shared Function Parse(ByVal value As String) _   As FourPartVersion Public Shared ReadOnly Property Empty As FourPartVersion 

The FourPartVersion class also overrides all the comparison operators so that you can easily compare any two.