Editing Manifests





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.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.)

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.3).

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.

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.



 Python   SQL   Java   php   Perl 
 game development   web development   internet   *nix   graphics   hardware 
 telecommunications   C++ 
 Flash   Active Directory   Windows