Share via


ServerDocument Class

Provides access to the cached data and customization information in a document or workbook that is part of a document-level customization created by using the Office development tools in Visual Studio.

Inheritance Hierarchy

System.Object
  Microsoft.VisualStudio.Tools.Applications.ServerDocument

Namespace:  Microsoft.VisualStudio.Tools.Applications
Assembly:  Microsoft.VisualStudio.Tools.Applications.ServerDocument (in Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll)

Syntax

'Declaration
<PermissionSetAttribute(SecurityAction.Demand, Name := "FullTrust")> _
Public NotInheritable Class ServerDocument _
    Implements IDisposable
[PermissionSetAttribute(SecurityAction.Demand, Name = "FullTrust")]
public sealed class ServerDocument : IDisposable

The ServerDocument type exposes the following members.

Constructors

  Name Description
Public method ServerDocument(String) Initializes a new instance of the ServerDocument class using the full path of the document to be loaded.
Public method ServerDocument(array<Byte[], String) Initializes a new instance of the ServerDocument class using a byte array that represents the document to be loaded and the file name extension of the document.
Public method ServerDocument(Stream, String) Initializes a new instance of the ServerDocument class using a stream that represents the document to be loaded and the file name extension of the document.
Public method ServerDocument(String, FileAccess) Initializes a new instance of the ServerDocument class using the full path of the document to be loaded and a value that indicates the file access for the document.

Top

Properties

  Name Description
Public property CachedData Gets a CachedData object that represents the cached data that is contained in the document.
Public property DeploymentManifestUrl Gets or sets the URL of the deployment manifest for the customization that is associated with the document.
Public property Document Gets the byte array of an in-memory document that is loaded into the ServerDocument.
Public property SolutionId Gets a GUID that the Visual Studio Tools for Office runtime uses to identify the solution.

Top

Methods

  Name Description
Public methodStatic member AddCustomization(String, Uri) Attaches a customization to the specified document by using the specified assembly name and deployment manifest.
Public methodStatic member AddCustomization(String, String, Guid, Uri) Attaches a customization to the specified document by using the specified document, assembly name, solution ID, and deployment manifest.
Public methodStatic member AddCustomization(String, String, Guid, Uri, Boolean, array<String[]%) Infrastructure.
Public method Close Closes the ServerDocument object.
Public method Equals Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected method Finalize Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodStatic member GetCustomizationVersion Returns the version of the Visual Studio Tools for Office runtime that was used to create the customization that is associated with the specified document.
Public method GetHashCode Serves as a hash function for a particular type. (Inherited from Object.)
Public method GetType Gets the Type of the current instance. (Inherited from Object.)
Public methodStatic member IsCacheEnabled Gets a value that indicates whether the specified document has a data cache.
Public methodStatic member IsCustomized Gets a value that indicates whether the specified document has a customization that was created by using the Visual Studio 2010 Tools for Office Runtime.
Protected method MemberwiseClone Creates a shallow copy of the current Object. (Inherited from Object.)
Public methodStatic member RemoveCustomization Removes the customization from the document.
Public method Save Saves any changes that were made to the document by using the ServerDocument class.
Public method ToString Returns a string that represents the current object. (Inherited from Object.)

Top

Explicit Interface Implementations

  Name Description
Explicit interface implemetationPrivate method IDisposable.Dispose Releases all resources used by the ServerDocument.

Top

Remarks

Use the ServerDocument class to manage certain aspects of document-level customizations on a computer that does not have Excel or Word installed. You typically use this class in applications that do not integrate with Office, such as Console projects or Windows Forms projects, rather than Office projects.

Use the following members of the ServerDocument class to perform common tasks:

  • To access and modify data in the data cache of a document on a server, use the CachedData property.

  • To programmatically attach a customization to a document or remove a customization from a document, use the AddCustomization and RemoveCustomization methods.

  • To access or change the URL of the deployment manifest that is associated with the document, use the DeploymentManifestUrl property.

There are two different versions of the ServerDocument class in the Visual Studio 2010 Tools for Office Runtime. The version you should use depends on the target .NET Framework of the application in which you want to use the class:

  • For applications that target the .NET Framework 4, use the Microsoft.VisualStudio.Tools.Applications.ServerDocument class in the Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll assembly.

  • For applications that target the .NET Framework 3.5, use the Microsoft.VisualStudio.Tools.Applications.ServerDocument class in the Microsoft.VisualStudio.Tools.Applications.ServerDocument.v10.0.dll assembly.

For more information, see Managing Documents on a Server by Using the ServerDocument Class.

Choosing Which Constructor to Use

To use the ServerDocument class to access the cached data or the deployment manifest URL in a document, you must create a ServerDocument object.

There are two sets of ServerDocument constructors:

  • A set that you can use to access a document that has already been opened in memory.

  • A set that you can use to access a document that is on disk.

Accessing a Document in Memory

To access a document that has already been opened in memory, use one of the following constructors:

These constructors accept a byte array or a Stream that represents the document in memory. This is useful if you want to modify the cached data or application manifest in the document before streaming it to a destination by using the HTTP protocol. To use these constructors, the document must already have a customization; otherwise, these constructors will throw a CannotLoadManifestException exception.

Accessing a Document on Disk

To access a document that is on disk, use one of the following constructors:

These constructors accept the full path of the document that you want to open. By default, the document is opened with read/write access. If you want to open the document with read-only or write-only access, use the constructor that has a FileAccess parameter.

Examples

The following code example creates a new ServerDocument that loads a specified document and then displays the URL of the deployment manifest for the customization that is attached to the document.

This example requires:

  • A console application project or some other non-Office project.

  • References to the following assemblies:

    • Microsoft.VisualStudio.Tools.Applications.ServerDocument.dll and Microsoft.VisualStudio.Tools.Applications.Runtime.dll (if the project targets the .NET Framework 4).

      or

    • Microsoft.VisualStudio.Tools.Applications.ServerDocument.v10.0.dll and Microsoft.VisualStudio.Tools.Applications.Runtime.v9.0.dll (if the project targets the .NET Framework 3.5).

  • Imports (for Visual Basic) or using (for C#) statements for Microsoft.VisualStudio.Tools.Applications and Microsoft.VisualStudio.Tools.Applications.Runtime namespaces at the top of your code file.

Private Sub CreateServerDocumentFromPath(ByVal documentPath As String)
    Dim runtimeVersion As Integer = 0
    Dim serverDocument1 As ServerDocument = Nothing

    Try
        runtimeVersion = ServerDocument.GetCustomizationVersion(documentPath)
        If runtimeVersion = 3 Then
            serverDocument1 = New ServerDocument(documentPath)
            MessageBox.Show("The URL of the deployment manifest is: " & vbLf & _
                serverDocument1.DeploymentManifestUrl.ToString())
        End If

    Catch ex As System.IO.FileNotFoundException
        System.Windows.Forms.MessageBox.Show("The specified document does not exist.")
    Catch ex As UnknownCustomizationFileException
        System.Windows.Forms.MessageBox.Show("The specified document has a file " & _
            "extension that is not supported by Visual Studio Tools for Office.")
    Finally
        If Not (serverDocument1 Is Nothing) Then
            serverDocument1.Close()
        End If
    End Try
End Sub
private void CreateServerDocumentFromPath(string documentPath)
{
    int runtimeVersion = 0;
    ServerDocument serverDocument1 = null;

    try
    {
        runtimeVersion = ServerDocument.GetCustomizationVersion(documentPath);
        if (runtimeVersion == 3)
        {
            serverDocument1 = new ServerDocument(documentPath);
            MessageBox.Show("The URL of the deployment manifest is: \n" +
                serverDocument1.DeploymentManifestUrl.ToString());
        }
    }
    catch (System.IO.FileNotFoundException)
    {
        System.Windows.Forms.MessageBox.Show("The specified document does not exist.");
    }
    catch (UnknownCustomizationFileException)
    {
        System.Windows.Forms.MessageBox.Show("The specified document has a file " +
            "extension that is not supported by Visual Studio Tools for Office.");
    }
    finally
    {
        if (serverDocument1 != null)
            serverDocument1.Close();
    }
}

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

See Also

Reference

Microsoft.VisualStudio.Tools.Applications Namespace

Other Resources

Managing Documents on a Server by Using the ServerDocument Class

Application and Deployment Manifests in Office Solutions

Accessing Data in Documents on the Server

How to: Insert Data into a Workbook on a Server

How to: Retrieve Cached Data from a Workbook on a Server

How to: Change Cached Data in a Workbook on a Server