Opening Documents

• Mar 14, 2021
• 6 minutes to read

This topic describes how to open and reopen documents within DevExpress office controls.

Important

Specify the ASPxRichEdit.WorkDirectory/ASPxSpreadsheet.WorkDirectory property to make the open and save document operations available.

Open Methods

The method signatures might differ from the platform-specific controls (such as Web Forms or MVC), but they have similar common concepts. Office controls expose the Open methods of the following types:

• Open (string pathToDocument) method

  This method loads a document from the server’s file system. When a document is opened for the first time, it is loaded to the server’s memory with the DocumentId value taken from the pathToDocument argument.

  If the document specified by pathToDocument has already been loaded and is in the DocumentManager‘s list of open documents, the method attaches the office control to the open document and reopens its model (with all unsaved changes) stored in the server’s memory.

  C#

  private void CustomDocumentOpening() {
      string pathToDocument = Server.MapPath("~/App_Data/Documents/doc.xlsx");
      ASPxSpreadsheet1.Open(pathToDocument);
  }
  

  VB

  Private Sub CustomDocumentOpening()
      Dim pathToDocument As String = Server.MapPath("~/App_Data/Documents/doc.xlsx")
      ASPxSpreadsheet1.Open(pathToDocument)
  End Sub
  

• Open (IDocumentInfo documentInfo) method

  This method opens a document from the DocumentManager‘s list of open documents. The IDocumentInfo interface specifies the document to be opened in the office control. This interface exposes a unique DocumentId that identifies which document to open.

  Since only opened documents that are maintained by DocumentManager are defined with IDocumentInfo, this method can only be used to attach the office control to a preloaded document, and reopen its model from server memory. Use the DocumentManager.FindDocument or DocumentManager.GetAllDocuments method to obtain IDocumentInfo.

  C#

  var documentId = GetPreviouslySavedDocumentId();
  var documentInfo = (SpreadsheetDocumentInfo)DocumentManager.FindDocument(documentId);
  ASPxSpreadsheet1.Open(documentInfo);
  

  VB

  Dim documentId = GetPreviouslySavedDocumentId()
  Dim documentInfo = CType(DocumentManager.FindDocument(documentId), SpreadsheetDocumentInfo)
  ASPxSpreadsheet1.Open(documentInfo)
  

• Open (string documentId, Func contentAccessor) method

  This method loads a document from a custom storage and opens it within the office control. You can use the corresponding contentAccessor parameter to get the document from a stream or a byte array. Specify the documentId value to identify the document in the internal dictionary (in DocumentManager).

  If the specified documentId parameter is not unique within all open documents, the method reopens the previously loaded document with the same documentId key.

  If you open a document from a database, it is good practice to use a data row’s key value as the documentId parameter. If you do not wish to utilize the database row key, use the Guid structure to generate a new unique identifier.

  Below is an example that uses the Open method to load a document from a stream:

  C#

  private void CustomDocumentOpening() {
      var uniqueDocumentId = GetUniqueDocumentId();
      // Open a document from a stream 
      using (var stream = GetStreamFromCustomDocumentStorage()) {
          ASPxSpreadsheet1.Open(uniqueDocumentId, DocumentFormat.Xlsx, () => stream);
      }
  }
  
  private string GetUniqueDocumentId() {
      throw new NotImplementedException();
      // Obtain a previously saved DocumentId (for instance, from a database, if you have previously saved it there): 
      // return GetDocumentIdFromDatabase(); 
      // or 
      // Create a new unique identifier: 
      // return Guid.NewGuid().ToString(); 
  }
  
  private FileStream GetStreamFromCustomDocumentStorage() {
      throw new NotImplementedException();
      // Provide your custom logic to obtain a document (for instance, from a database) 
  }
  

  VB

  Private Sub CustomDocumentOpening()
      Dim uniqueDocumentId = GetUniqueDocumentId()
      ' Open a document from a stream 
      Using stream = GetStreamFromCustomDocumentStorage()
          ASPxSpreadsheet1.Open(uniqueDocumentId, DocumentFormat.Xlsx, Function() stream)
      End Using
  End Sub
  
  Private Function GetUniqueDocumentId() As String
      Throw New NotImplementedException()
      ' Obtain a previously saved DocumentId (for instance, from a database, if you have previously saved it there): 
      ' Return GetDocumentIdFromDatabase() 
      ' or 
      ' Create a new unique identifier: 
      ' return Guid.NewGuid().ToString() 
  End Function
  
  Private Function GetStreamFromCustomDocumentStorage() As FileStream
      Throw New NotImplementedException()
      ' Provide your custom logic to obtain a document (for instance, from a database) 
  End Function
  

  The following example uses the Open method to load a document from a byte array:

  C#

  private void CustomDocumentOpening() {
      var uniqueDocumentId = GetUniqueDocumentId();
      // Open a document from a byte array 
      byte[] documentContentAsByteArray = GetByteArrayFromCustomDocumentStorage();
      using (var stream = GetStreamFromCustomDocumentStorage()) {
          ASPxSpreadsheet1.Open(uniqueDocumentId, DocumentFormat.Xlsx, () => documentContentAsByteArray);
      }
  }
  
  private string GetUniqueDocumentId() {
      throw new NotImplementedException();
      // Obtain a previously saved DocumentId (for instance, from a database, if you have previously saved it there): 
      // return GetDocumentIdFromDatabase(); 
      // or 
      // Create a new unique identifier: 
      // return Guid.NewGuid().ToString(); 
  }
  
  private byte[] GetByteArrayFromCustomDocumentStorage() {
      throw new NotImplementedException();
      // Provide your custom logic to obtain a document (for instance, from a database) 
  }
  

  VB

  Private Sub CustomDocumentOpening()
      Dim uniqueDocumentId = GetUniqueDocumentId()
      ' Open a document from a byte array 
      Dim documentContentAsByteArray As Byte() = GetByteArrayFromCustomDocumentStorage()
      Using stream = GetStreamFromCustomDocumentStorage()
          ASPxSpreadsheet1.Open(uniqueDocumentId, DocumentFormat.Xlsx, Function() documentContentAsByteArray)
      End Using
  End Sub
  
  Private Function GetUniqueDocumentId() As String
      Throw New NotImplementedException()
      ' Obtain a previously saved DocumentId (for instance, from a database, if you have previously saved it there): 
      ' Return GetDocumentIdFromDatabase()
      ' or 
      ' Create a new unique identifier: 
      ' Return Guid.NewGuid().ToString() 
  End Function
  
  Private Function GetByteArrayFromCustomDocumentStorage() As Byte()
      Throw New NotImplementedException()
      ' Provide your custom logic to obtain a document (for instance, from a database) 
  End Function
  

Opening Documents as Templates

Certain document management scenarios require that end users open their own copies of a document from its initial state. In this case, the original version of a document is used as a template. Each user can obtain a copy and modify it independently from other users who open the same template.

To implement this scenario, use the Open methods with the documentId parameter (such as Open(string documentId, Func contentAccessor) or Open(string documentId, Func<byte[]> contentAccessor)) to provide a copy of the initial document with a unique DocumentId value to each end user.

Note

Do not use the Open (string pathToDocument) method for this scenario, because it always opens a single document that has the same DocumentId (specified by the pathToDocument parameter).

Note that it might be useful to store DocumentId values of each user’s document copy, which allows an end user to work with documents after the user closes or reopens the application page in a browser.

The example below demonstrates a stream approach, which uses the Open method to open a file system document as a template:

C#

var workDirectory = @"~/App_Data/WorkDirectory/";
var templateFileName = "doc.xlsx";
var templatePath = Server.MapPath(Path.Combine(workDirectory, templateFileName));
var newUniqueDocumentId = Guid.NewGuid().ToString();
using (var stream = new FileStream(templatePath, FileMode.Open)) {
    ASPxSpreadsheet1.Open(newUniqueDocumentId, DocumentFormat.Xlsx, () => stream);
}

VB

Dim workDirectory = "~/App_Data/WorkDirectory/"
Dim templateFileName = "doc.xlsx"
Dim templatePath = Server.MapPath(Path.Combine(workDirectory, templateFileName))
Dim newUniqueDocumentId = Guid.NewGuid().ToString()
Using stream = New FileStream(templatePath, FileMode.Open)
    ASPxSpreadsheet1.Open(newUniqueDocumentId, DocumentFormat.Xlsx, Function() stream)
End Using

The following example demonstrates a byte array approach, which uses the Open method to open a file system document as a template:

C#

var workDirectory = @"~/App_Data/WorkDirectory/";
var templateFileName = "doc.xlsx";
var templatePath = Server.MapPath(Path.Combine(workDirectory, templateFileName));
var newUniqueDocumentId = Guid.NewGuid().ToString();
ASPxSpreadsheet1.Open(newUniqueDocumentId, DocumentFormat.Xlsx, () => File.ReadAllBytes(templatePath));

VB

Dim workDirectory = "~/App_Data/WorkDirectory/"
Dim templateFileName = "doc.xlsx"
Dim templatePath = Server.MapPath(Path.Combine(workDirectory, templateFileName))
Dim newUniqueDocumentId = Guid.NewGuid().ToString()
ASPxSpreadsheet1.Open(newUniqueDocumentId, DocumentFormat.Xlsx, Function() File.ReadAllBytes(templatePath))