Deploying to an Intranet Shared Directory or Web Site


Suppose that you are ready to roll out an expense-reporting application using a customized Excel spreadsheet. You plan to put the application up on the http://accounting Web site. Users will download the spreadsheet to their local machines for editing, but the code will live up on the server.

As discussed in Chapter 19, ".NET Code Security," you need to ensure that users have policy that explicitly trusts the customization assembly. The policy should explicitly trust the server; the strong name of the assembly; or, preferably, both. See the last section of Chapter 19 for tips on how to roll out security policy.

Deploying to a Server with the Publish Wizard

Choose Publish from the Build menu to start the Publish Wizard, and give the name of the intranet Web server or network share to which you want to publish the customization, as shown in Figure 20.1.

Figure 20.1. The Visual Studio Publish Wizard.


Click Finish. It is as simple as that; Visual Studio will build the customization and copy the document and customization assembly to the server. As you will see later in this chapter, Visual Studio also creates a deployment manifest for you. We discuss what deployment manifests are for shortly, but first, what if you do not have write access to the server?

Some Security Questions

A few security questions may have just come to mind. What if your security-conscious administrators have not granted you write access to the Website? What if the delay-signed assemblies must be properly strong-named by a signing authority or signed with a publisher certificate before they are deployed?

The Publish Wizard creates a local copy of the files that it deploys up to the network site before it deploys them, but unfortunately, there is no way to get the Publish Wizard to skip attempting to copy them up to the site. It is possible to do this from the command line, however, using the msbuild.exe utility. The syntax is as follows:

MSBuild.exe /target:Publish  /property:PublishUrl=<Url> <Project> 


This produces the files that would be deployed and puts them in the following directory:

<ProjectFolder>\<OutputFolder>\<ProjectName>.publish 


The following would produce the files to be copied to the Web server but not actually copy them there:

MSBuild.exe /target:Publish /property:PublishUrl=http://accounting/ExpenseReport "c:\MyProjects\ExpenseReport\ExpenseReport.vbproj" 


Instead, they would be saved in the following:

c:\MyProjects\ExpenseReport\bin\Release\ExpenseReport.publish 


After you have the files to be deployed on your local machine, you can get them strong-named by your signing authority, send them to the server administrator to be copied onto the Web server, or do whatever else needs to be done before the files become available on a live server.

Examining the Generated Files

Take a look at the contents of the network (or local) directory to which you just deployed the application. (This typically will be a subdirectory of the c:\inetpub\wwwroot directory if you published to a Web site.) You should see a directory structure that looks something like this:

> dir /s /b C:\Inetpub\wwwroot\ExpenseReport\ExpenseReport.application C:\Inetpub\wwwroot\ExpenseReport\ExpenseReport.doc C:\Inetpub\wwwroot\ExpenseReport\ExpenseReport_1.0.0.0 C:\Inetpub\wwwroot\ExpenseReport\ExpenseReport_1.0.0.0\    ExpenseReport.dll C:\Inetpub\wwwroot\ExpenseReport\ExpenseReport_1.0.0.0\    ExpenseReport.dll.manifest C:\Inetpub\wwwroot\ExpenseReport\ExpenseReport_1.0.0.0\    ExpenseReport.doc C:\Inetpub\wwwroot\ExpenseReport\ExpenseReport_1.0.0.0\    ExpenseReport.dll.config 


To understand what is going on here, we need to introduce some jargon. The ExpenseReport.application file is the deployment manifest, and the ExpenseReport.dll.manifest file is the application manifest.

Note

It is somewhat confusing that the ".application" file is not the application manifest; unfortunately, now we are stuck with this poor choice of nomenclature.


The Deployment Manifest

The sole purpose of the deployment manifest is to point the VSTO runtime toward the most current version of the application manifest. The application manifest, by contrast, contains information about where the customization assembly is and which host item classes need to be created when the customization is started. There is always only one deployment manifest, but there can be many application manifests, one for each version of the customization.

A typical automatically generated deployment manifest looks something like Listing 20.1.

Listing 20.1. The Deployment Manifest

<?xml version="1.0" encoding="utf-8"?> <asmv1:assembly   xsi:schemaLocation=   "urn:schemas-microsoft-com:asm.v1 assembly.adaptive.xsd"   manifestVersion="1.0"   xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"   xmlns="urn:schemas-microsoft-com:asm.v2"   xmlns:asmv1="urn:schemas-microsoft-com:asm.v1"   xmlns:asmv2="urn:schemas-microsoft-com:asm.v2"   xmlns:xrml="urn:mpeg:mpeg21:2003:01-REL-R-NS"   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">   <assemblyIdentity     name="ExpenseReport.application"     version="1.0.0.0"     publicKeyToken="0000000000000000"     language="neutral"     processorArchitecture="msil"     xmlns="urn:schemas-microsoft-com:asm.v1" />     <description       asmv2:publisher="Microsoft"       asmv2:product="ExpenseReport"       xmlns="urn:schemas-microsoft-com:asm.v1" />     <deployment install="true" />     <dependency>       <dependentAssembly         dependencyType="install"         codebase=         "ExpenseReport_1.0.0.0\ExpenseReport.dll.manifest"         size="1460">         <assemblyIdentity           name="ExpenseReport.dll"           version="1.0.0.0" />       <hash>         <dsig:Transforms>           <dsig:Transform Algorithm=  "urn:schemas-microsoft-com:HashTransforms.Identity" />         </dsig:Transforms>         <dsig:DigestMethod Algorithm=         "http://www.w3.org/2000/09/xmldsig#sha1" /> <dsig:DigestValue>8cQI8YsGgIUaSSysgK3Ad8do9t0=</dsig:DigestValue>       </hash>     </dependentAssembly>   </dependency> </asmv1:assembly> 


We have emphasized the relevant portions of the deployment manifest. What is all the rest ofthis stuff? There seem to be some confusing things in here. Why is the root element "assembly"? Why are there two inconsistent "assemblyIdentity" elements? And what's that digital signature?

VSTO uses the same deployment manifest format as ClickOnce, a technology designed to facilitate deployment of entire applications, not single customizations; these oddities are a result of backward-compatibility factors from the ClickOnce world.

The oldest of these historical factors is the root element "assembly." Explaining that strange choice requires us to go back to a time before the version 1.0 .NET runtime shipped. When the .NET runtime was being designed, assembly referred to all an application's files and configuration informationthat is, all the bits described by what we now call a manifest. The manifest file format above dates from that time, and its elements were not renamed when assembly came to mean "the smallest unit of versionable executable code."

That explains why there are two inconsistent assemblyIdentity elements. The first assemblyIdentity identifies not a DLL, but the manifest itself. Notice that the first assemblyIdentity element names the manifest. Manifests can have their own version numbers. Deployment manifests usually are versioned along with the customization assembly, but the deployment manifest can haveits own version number distinct from that of the customization assembly, if you so choose; as you will see later, it must be consistent with the application manifest but need not be consistent with the customization assembly. VSTO considers only the name and version attributes in the first assemblyIdentity element.

The second assemblyIdentity element uses assembly in the modern sense and identifies the customization code. Notice that the codebase attribute gives the relative path to the application manifest, and the assemblyIdentity identifies the name and version of the customization code. We discuss the meanings and interactions of the various codebase attributes later in this chapter.

Finally, ClickOnce supports digital signing security features in its manifests; unlike ClickOnce, VSTO does not do any kind of digital signature verification on its manifests. VSTO will ignore these elements.

The Application Manifest

As you have seen, the deployment manifest identifies the location and current version of theapplication manifest. The application manifest identifies the customization assembly and lists the classes that need to be created when the customization starts. The application manifest, shown in Listing 20.2, looks somewhat similar to the deployment manifest.

Listing 20.2. The Application Manifest

<assembly xmlns="urn:schemas-microsoft-com:asm.v1"    xmlns:asmv2="urn:schemas-microsoft-com:asm.v2">   <assemblyIdentity name="ExpenseReport.dll" version="1.0.0.0" />   <asmv2:entryPoint name="Startup" dependencyName="dependency0">     <asmv2:clrClassInvocation       />   </asmv2:entryPoint>   <asmv2:entryPoint name="Startup" dependencyName="dependency0">     <asmv2:clrClassInvocation />   </asmv2:entryPoint>   <asmv2:entryPoint name="Startup" dependencyName="dependency0">     <asmv2:clrClassInvocation />   </asmv2:entryPoint>   <asmv2:entryPoint name="Startup" dependencyName="dependency0">     <asmv2:clrClassInvocation />   </asmv2:entryPoint>   <asmv2:dependency asmv2:name="dependency0">     <asmv2:dependentAssembly>       <assemblyIdentity name="ExpenseReport"         version="1.0.0.0" culture="neutral" />        <asmv2:installFrom            codebase="ExpenseReport_1.0.0.0\ExpenseReport.DLL" />     </asmv2:dependentAssembly>     <asmv2:installFrom codebase= "http://accounting/ExpenseReport/ExpenseReport.application" />   </asmv2:dependency> </assembly> 


Again, we have assembly used in the now-obsolete sense as the root element and an assemblyIdentity element that gives the version number of the application manifest. What is all the rest of the stuff in here?

Clearly, all the information we need to start the customization is in here, but again, the format is somewhat odd because it tries to be similar to the ClickOnce format. We have a collection of entryPoints listing the classes that are to be created when the customization starts. We also have a single dependency (that is, the assembly containing the customization). Because a ClickOnce application manifest describes all the assemblies that make up an application, a ClickOnce manifest can have many dependent assemblies. A VSTO customization always consists of a single assembly and, therefore, has only one dependency in the application manifest.

Notice that the application manifest also refers to the location of the deployment manifest. But is not the point of the deployment manifest to identify the location of the application manifest? What is going on here?

The Relationship Between Application and Deployment Manifests

The easiest way to explain this is to walk through a typical deployment scenario. Suppose that you develop and publish version 1.0.0.0 of the expense-reporting solution above. Now there are four interesting files: the deployment manifest, the application manifest, the assembly, and the document. The deployment manifest points to the application manifest; the application manifest points to the assembly; and the document's data island contains a copy of the application manifest.

Now you e-mail the document, without the assembly, to a user. The user loads the document into Excel. The VSTO runtime reads the copy of the application manifest out of the document and notices a deployment manifest in the installFrom location. The VSTO runtime downloads the deployment manifest and discovers that both the application and deployment manifests are version 1.0.0.0. Therefore, the VSTO runtime knows that the document contains the most recent copy of the application manifest, so it need not update it.

The deployment manifest's codebase refers to the location of the server's copy of the manifest and the customization DLL. The CLR assembly loader downloads the assembly and configuration file, caches them locally, and loads the assembly into memory. (Although the file has been cached locally for convenience, the CLR assembly loader sets the evidence associated with the assembly to match its original location, not its temporary location on the local disk.) Then the VSTO runtime starts the classes named in the entryPoint elements, and the customization runs.

A few days later, you fix some bugs and roll out version 1.0.0.1 to the server, using the Publish Wizard. The next time the user starts the document while online, the VSTO runtime contacts the server to see whether there have been any changes in the deployment manifest.

This time, the document's copy of the application manifest is 1.0.0.0, but the deployment manifest is 1.0.0.1. The VSTO runtime downloads the new application manifest from the server and caches a copy of it in the document. (Note that if the user quits Excel without saving the document, the change to the cached manifest will be lost with all the other changes.)

The CLR loader detects that the assembly's codebase is different and downloads the new assembly. Now the user is running the latest version without ever having to download or install anything manually.

Because the local copy of the application manifest knows where the deployment manifest is, and the deployment manifest knows where the latest application manifest is, the document always can keep itself up to date with the latest bits.

Note

A deployment manifest's version number must match the version number of the application manifest it refers to. If the deployment manifest's version attribute indicates that itis version 1.0.0.1, the referred-to application manifest must also be version 1.0.0.1. If the VSTO runtime detects that the deployment manifest refers to a mismatched application manifest, it assumes that the deployment server has been corrupted and refuses to load the customization.


Determining the Assembly Location from a Deployment Manifest

Did you notice that between the deployment manifest and the application manifest, there were three codebase attributes? The application manifest says this:

   <asmv2:dependency asmv2:name="dependency0">      <asmv2:dependentAssembly>        <assemblyIdentity name="ExpenseReport"          version="1.0.0.0" culture="neutral" />         <asmv2:installFrom codebase=             "ExpenseReport_1.0.0.0\ExpenseReport.DLL" />      </asmv2:dependentAssembly>      <asmv2:installFrom codebase=  "http://accounting/ExpenseReport/ExpenseReport.application" />    </asmv2:dependency> 


Whereas the deployment manifest says this:

codebase="ExpenseReport_1.0.0.0\ExpenseReport.dll.manifest" 


How does the loader determine the codebase from which to load the customization assembly? In the preceding example, the application manifest has an absolute path to the deployment manifest, so the runtime starts there. The absolute path to the deployment manifest is combined with the codebase in the application manifest, which is relative to the deployment manifest path for a published project. So the VSTO runtime looks for the assembly in http://accounting/ExpenseReport/ExpenseReport_1.0.0.0/.

Had the application manifest contained an absolute path to the DLL, the VSTO runtime would ignore the deployment manifest information for the purposes of loading the customization and just use the absolute path. You learn how to edit the codebase and other attributes in the application and deployment manifests later in this chapter.




Visual Studio Tools for Office(c) Using Visual Basic 2005 with Excel, Word, Outlook, and InfoPath
Visual Studio Tools for Office: Using Visual Basic 2005 with Excel, Word, Outlook, and InfoPath
ISBN: 0321411757
EAN: 2147483647
Year: N/A
Pages: 221

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net