Share via


ServerDocument Constructors

Definition

Overloads

ServerDocument(String)

Initializes a new instance of the ServerDocument class using the full path of the document to be loaded.

ServerDocument(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.

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.

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.

ServerDocument(String)

Initializes a new instance of the ServerDocument class using the full path of the document to be loaded.

public:
 ServerDocument(System::String ^ documentPath);
public ServerDocument (string documentPath);
new Microsoft.VisualStudio.Tools.Applications.ServerDocument : string -> Microsoft.VisualStudio.Tools.Applications.ServerDocument
Public Sub New (documentPath As String)

Parameters

documentPath
String

The full path of the document to be loaded.

Exceptions

The documentPath parameter is null or empty or consists entirely of white space characters.

The file specified by documentPath does not exist.

The file specified by documentPath has a customization that was not created with the Visual Studio 2010 Tools for Office Runtime or the Visual Studio Tools for the Microsoft Office system (version 3.0 Runtime).

The file specified by documentPath has a file name extension that is not supported by the Visual Studio Tools for Office runtime.

Examples

The following code example uses the ServerDocument(String) constructor to create a new ServerDocument that loads a specified document. The example 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 the .NET Framework 4.5).

      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 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();
    }
}
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

Remarks

Use this constructor to access the cached data or deployment manifest information in a document that is on disk. When you use this constructor, the specified document is opened with read/write access.

Applies to

ServerDocument(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:
 ServerDocument(cli::array <System::Byte> ^ bytes, System::String ^ fileType);
public ServerDocument (byte[] bytes, string fileType);
new Microsoft.VisualStudio.Tools.Applications.ServerDocument : byte[] * string -> Microsoft.VisualStudio.Tools.Applications.ServerDocument
Public Sub New (bytes As Byte(), fileType As String)

Parameters

bytes
Byte[]

A byte array that represents the document to be loaded.

fileType
String

The file name extension of the document that is stored in the bytes parameter, preceded by a period (.)—for example, ".xlsx" or ".docx".

Exceptions

The bytes parameter is null or empty.-or-The fileType parameter is null or empty or consists entirely of white space characters.

The fileType parameter specifies a file name extension that is not supported by the Visual Studio Tools for Office runtime.

The file specified by documentPath has a customization that was not created with the Visual Studio 2010 Tools for Office Runtime or the Visual Studio Tools for the Microsoft Office system (version 3.0 Runtime).

Examples

The following code example uses the [ServerDocument Constructor (Byte<xref:Microsoft.VisualStudio.Tools.Applications.ServerDocument.%23ctor%28System.Byte%5B%5D%2CSystem.String%29> constructor to create a new [ServerDocument Constructor (Byte<xref:Microsoft.VisualStudio.Tools.Applications.ServerDocument> from a byte array that contains an Excel workbook with the .xlsx file name extension. The example then uses the [ServerDocument Constructor (Byte<xref:Microsoft.VisualStudio.Tools.Applications.ServerDocument.Document%2A> property to display the number of bytes in 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 the .NET Framework 4.5).

      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 [ServerDocument Constructor (Byte<xref:Microsoft.VisualStudio.Tools.Applications?displayProperty=fullName> and [ServerDocument Constructor (Byte<xref:Microsoft.VisualStudio.Tools.Applications.Runtime?displayProperty=fullName> namespaces at the top of your code file.

private void CreateServerDocumentFromByteArray(string documentPath)
{
    int runtimeVersion = 0;
    ServerDocument serverDocument1 = null;
    System.IO.FileStream stream = null;

    try
    {
        runtimeVersion = ServerDocument.GetCustomizationVersion(documentPath);
        if (runtimeVersion == 3)
        {
            // Read the file into a byte array.
            stream = new System.IO.FileStream(
                documentPath, System.IO.FileMode.Open,
                System.IO.FileAccess.Read);
            byte[] buffer = new byte[(int)stream.Length];
            stream.Read(buffer, 0, (int)buffer.Length);

            // Display the number of bytes in the document.
            serverDocument1 = new ServerDocument(buffer,
                "*.xlsx");
            MessageBox.Show("The Document property contains " +
                serverDocument1.Document.Length.ToString() +
                " bytes.");
        }
    }
    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();
        if (stream != null)
            stream.Close();
    }
}
Private Sub CreateServerDocumentFromByteArray(ByVal documentPath As String)
    Dim runtimeVersion As Integer = 0
    Dim serverDocument1 As ServerDocument = Nothing
    Dim stream As System.IO.FileStream = Nothing

    Try
        runtimeVersion = ServerDocument.GetCustomizationVersion(documentPath)
        If runtimeVersion = 3 Then
            ' Read the file into a byte array.
            stream = New System.IO.FileStream(documentPath, System.IO.FileMode.Open, _
                System.IO.FileAccess.Read)
            Dim buffer(Fix(stream.Length)) As Byte
            stream.Read(buffer, 0, Fix(buffer.Length))

            ' Display the number of bytes in the document.
            serverDocument1 = New ServerDocument(buffer, "*.xlsx")
            MessageBox.Show("The Document property contains " & _
                serverDocument1.Document.Length.ToString() & " bytes.")
        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
        If Not (stream Is Nothing) Then
            stream.Close()
        End If
    End Try
End Sub

Remarks

Use this constructor to access the cached data or deployment manifest information in a document that is already in memory. When you use this constructor, the document is opened with read/write access.

The fileType parameter is used only to determine the type of document that is stored in the byte array. The value of fileType is mapped to one of the file types that are supported for document-level customizations. No attempt is made to open the file. You can optionally pass in a complete file name (for example, "Workbook1.xlsx"), but if you do this, only the file name extension is used. For more information about the supported file types, see Architecture of Document-Level Customizations.

To access the byte array for the document after calling this constructor, use the [ServerDocument Constructor (Byte<xref:Microsoft.VisualStudio.Tools.Applications.ServerDocument.Document%2A> property.

Applies to

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:
 ServerDocument(System::IO::Stream ^ stream, System::String ^ fileType);
public ServerDocument (System.IO.Stream stream, string fileType);
new Microsoft.VisualStudio.Tools.Applications.ServerDocument : System.IO.Stream * string -> Microsoft.VisualStudio.Tools.Applications.ServerDocument
Public Sub New (stream As Stream, fileType As String)

Parameters

stream
Stream

A stream that represents the document to be loaded.

fileType
String

The file name extension of the document that is stored in the bytes parameter, preceded by a period (.)—for example, ".xlsx" or ".docx".

Exceptions

The stream parameter is null or empty.-or-The fileType parameter is null or empty or consists entirely of white space characters.

The stream parameter has zero length or its current position is at the stream's end.

The fileType parameter specifies a file name extension that is not supported by the Visual Studio Tools for Office runtime.

The file specified by documentPath has a customization that was not created with the Visual Studio 2010 Tools for Office Runtime or the Visual Studio Tools for the Microsoft Office system (version 3.0 Runtime).

Examples

The following code example uses the ServerDocument(Stream, String) constructor to create a new ServerDocument from a FileStream that contains an Excel workbook with the .xlsx file name extension. The code 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 the .NET Framework 4.5).

      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 void CreateServerDocumentFromStream(string documentPath)
{
    int runtimeVersion = 0;
    ServerDocument serverDocument1 = null;
    System.IO.FileStream stream = null;

    try
    {
        runtimeVersion = ServerDocument.GetCustomizationVersion(documentPath);
        if (runtimeVersion == 3)
        {
            stream = new System.IO.FileStream(
                documentPath, System.IO.FileMode.Open);
            serverDocument1 = new ServerDocument(stream,
                "*.xlsx");
            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();
        if (stream != null)
            stream.Close();
    }
}
Private Sub CreateServerDocumentFromStream(ByVal documentPath As String)
    Dim runtimeVersion As Integer = 0
    Dim serverDocument1 As ServerDocument = Nothing
    Dim stream As System.IO.FileStream = Nothing

    Try
        runtimeVersion = ServerDocument.GetCustomizationVersion(documentPath)
        If runtimeVersion = 3 Then
            stream = New System.IO.FileStream(documentPath, System.IO.FileMode.Open)
            serverDocument1 = New ServerDocument(stream, "*.xlsx")
            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
        If Not (stream Is Nothing) Then
            stream.Close()
        End If
    End Try
End Sub

Remarks

Use this constructor to access the cached data or deployment manifest information in a document that is already in memory. When you use this constructor, the document is opened with read/write access.

The fileType parameter is used only to determine the type of document that is stored in the byte array. The value of fileType is mapped to one of the file types that are supported for document-level customizations. No attempt is made to open the file. You can optionally pass in a complete file name (for example, "Workbook1.xlsx"), but if you do this, only the file name extension is used. For more information about the supported file types, see Architecture of Document-Level Customizations.

To access the byte array for the document after calling this constructor, use the Document property.

Applies to

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.

public:
 ServerDocument(System::String ^ documentPath, System::IO::FileAccess access);
public ServerDocument (string documentPath, System.IO.FileAccess access);
new Microsoft.VisualStudio.Tools.Applications.ServerDocument : string * System.IO.FileAccess -> Microsoft.VisualStudio.Tools.Applications.ServerDocument
Public Sub New (documentPath As String, access As FileAccess)

Parameters

documentPath
String

The full path of the document to be loaded.

access
FileAccess

A value that indicates the file access for the document.

Exceptions

The documentPath parameter is null or empty or consists entirely of white space characters.

The value of access is System.IO.FileAccess.Write.

The file specified by documentPath does not exist.

The file specified by the documentPath parameter does not have a customization, and the value of access is System.IO.FileAccess.Read.

The file specified by documentPath has a customization that was not created with the Visual Studio 2010 Tools for Office Runtime or the Visual Studio Tools for the Microsoft Office system (version 3.0 Runtime).

The file specified by documentPath has a file name extension that is not supported by the Visual Studio Tools for Office runtime.

Examples

The following code example uses the ServerDocument(String, FileAccess) constructor to create a new ServerDocument that loads a specified document with read-only access. The code 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 the .NET Framework 4.5).

      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 void CreateServerDocumentReadOnly(string documentPath)
{
    int runtimeVersion = 0;
    ServerDocument serverDocument1 = null;

    try
    {
        runtimeVersion = ServerDocument.GetCustomizationVersion(documentPath);
        if (runtimeVersion == 3)
        {
            serverDocument1 = new ServerDocument(documentPath,
                System.IO.FileAccess.Read);
            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 (DocumentNotCustomizedException)
    {
        System.Windows.Forms.MessageBox.Show("The specified document does not " +
            "have a customization.");
    }
    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();
    }
}
Private Sub CreateServerDocumentReadOnly(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, System.IO.FileAccess.Read)
            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 DocumentNotCustomizedException
        System.Windows.Forms.MessageBox.Show("The specified document does not " & _
            "have a customization.")
    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

Remarks

Use this constructor to access the cached data or deployment manifest information in a document that is on disk if you want to open the document with read-only or write-only access. By default, the other ServerDocument constructors open the document with read/write access.

Applies to