ServerDocument

The ServerDocument allows you to read and write information in the data island of a document without actually opening the file in Excel or Word.
This was introduced in the VSTO Runtime (v2)
The ServerDocument can read and write the following types of documents (Word in binary format, Excel in binary format, Word in XML format).
ServerDocument does not support "In memory" manipulation of "not yet" customised documents.

Functionality

Reading data back out from a document.
Updating deployment information inside a document
Adding / removing VSTO customisations to/from documents
Read / write all deployment information and cached data stored in a customised document.
Adding customised assemblies to uncustomised documents (only on the client as Excel & Word need to be opened)

There are two scenarios:
1) read/write document in memory
2) read/write documents saved on disc (can be either on client or server although this is only important when it is an uncustomised document)

When opening an uncustomised document wanting to add customisation information, the serverDocument has to start the Excel or Word application and manipulate it uising the Office object model.
This is a bad scenario on a server and if attempted on a server will generate an exception.

The document also contins a data cache that is used by the VSTO runtime to store data when the document is offline.
VSTO embeds the application manifest and the data cache into the document by inserting a special ActiveX control called the Runtime Storage Control.
It is this control that the ServerDocument class manipulates.

Manually attach using custom document properties

When the document is opened after the custom properties have been added/changes.
The VSTO runtime attaches the solution to the document.
The runtime embeds the RunTime Storage Control, the application manifest and loads the assembly ???

ServerDocument Class Constructors

This class have seven constructirs although there are two primary ones:
In Memory
New (ByVal bytes As Bytes(),
ByVal fileType As String
reads the entire stream into a byte array.

on disc
New (ByVal documentPath As String, _
ByVal onClient As Boolean, _
ByVal access As FileAccess)
access can be either FileAccess.Read or FileAccess.ReadWrite

Updating the embedded applicaton manifest can be done using the ServerDocument API.

This is version specific
ServerDocument v3 - only works with VSTO runtime v3
ServerDocument v2 - only works with VSTO runtime v2

Installation folder URL
This can be accessed and changed programmatically using the serverdocument

v3 runtime. ServerDocument
sd = New v3runtime.ServerDocument(sfilepath)
sd.DeploymentManifestURL = New URL("http:// .vsto")
sd.save()

AddCustomisation Method

only works with files on disk
Takes an uncustomised document and adds a customisation to it.
It creates (or replaces) a new application manifest and cached data manifest.
Should only be called on clients machine as it always starts Excel or Word.

The document and assembly paths are required
The deployment manifest path can be Nothing or empty if you do not want to use a deployment manifest to manage updating your customisation.

RemoveCustomisation Method

only works with files on disk
Removes all customisation information from a document or workbook including all the cached data in the data island
It also starts Excel and Word.

IsCustomised Method

only works with files on disk

IsCachedEnabled Method

only works with files on disk

Save Method

If opened on the server, changes are made to the application manifest, cached data island or manifest

Close Method

Always close it explicitley when you have finished.

CachedDataHostItem
CashedDataItem
NeedsFill
StartCaching
StopCaching
ICachedType