Opening Documents

• Mar 14, 2021
• 5 minutes to read

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

Open Methods

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

• Open (string pathToDocument) method

  The method loads a document from the server’s file system. A document is loaded into the server’s memory with the DocumentId value taken from the pathToDocument argument when it is opened for the first time.

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

• 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 using IDocumentInfo, the method can only be used to attach the office control to this preloaded document and reopen its model from server memory. Use the DocumentManager.FindDocument or DocumentManager.GetAllDocuments method to obtain the IDocumentInfo.

  C#

  var documentId = GetPreviouslySavedDocumentId();
      var documentInfo = (SpreadsheetDocumentInfo)DocumentManager.FindDocument(documentId);
      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 get the document from a stream or a byte array using the corresponding contentAccessor parameter. 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 prefer not to use the database row key, generate a new unique identifier using the Guid structure.

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

  C#

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

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

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 their own copy and modify it independently from other users who open the same template.

To implement this scenario, each end-user should have a copy of an initial document with a unique DocumentId value – via the Open methods, exposing the definite documentId parameter (such as Open(string documentId, Func contentAccessor) or Open(string documentId, Func<byte[]> contentAccessor) ).

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 the DocumentId values of each user document copy, which allows end-users to work with documents after a 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);
}

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