Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Expand]WinForms Controls
[Collapse]ASP.NET Controls and MVC Extensions
 [Expand]Prerequisites
 [Expand]What's Installed
 [Collapse]Common Concepts
  [Expand]Web.config Modifications
  [Expand]Callback Exception Handling
  [Expand]Client-Side Functionality
  [Expand]Cookies Support
  [Expand]Appearance Customization - Theming
   Icon Collection
  [Expand]Performance Optimization
  [Expand]CSS Image Sprites
   Supported Document Types
  [Expand]Accessibility Support
   Right to Left Support
   HTML Encoding
   Binary Storage Configuration
  [Expand]SharePoint Support
   Mobile Support
  [Collapse]Office Document Management
   [Expand]Document Loading
   [Collapse]Document Saving
     Standard and Custom Saving
     Auto-Saving
    Document Hibernation
   Cloud Storage Account Management
  [Expand]Web Farm and Web Garden Support
 [Expand]ASP.NET WebForms Controls
 [Expand]ASP.NET MVC Extensions
 [Expand]Localization
 [Expand]Redistribution and Deployment
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Standard and Custom Saving

This topics describes different saving scenarios that you can implement office controls.

Expanded Simple Saving Scenario

In the simplest application scenarios, office controls perform document save operations without custom coding. For instance, if an office control opens a document from the server's local file system (using the Open(pathToDocument) method), the document is then saved by the office control to the same file from which it was opened (based on the pathToDocument parameter of the Open method). In this case, click the Save ribbon command in the UI or call the Save() method of an office control to save the edited document to its original file.

Expanded Saving Methods

More complex application scenarios might require additional coding and use more specific save methods. You can programmatically initialize document saving via the Save method and SaveCopy method overloads listed below.

Save Method

The Save method initiates a save operation for an office control's active document. In the simple scenario described above, this method successfully saves a document that was opened from the server file system, whose DocumentId equals the document's file path. If the edited document's DocumentId is not specified (if it is a new document or a document opened not from the server's file system), an office control will throw a specific exception.. In this case, implement custom saving logic using the Saving event.

SaveCopy Method

You can use the SaveCopy method overloads to save a copy of an open document to the server file system or to an external storage. Specify the copy's destination by selecting the SaveCopy method overload with the necessary parameters. You can call this method for an active document in an office control (via the control's SaveCopy method) or for any open document currently maintained by DocumentManager (via the SaveCopy method of the IDocumentInfo identifying the document). In certain cases, the SaveCopy method may lead to multi-user conflicts, which arise when end-users try to save to and rewrite another document opened by other end-users. Implement custom saving logic using the Saving event to resolve this conflict.

Expanded Custom Saving - Using the Saving Event

A custom implementation is required when an office control does not have enough information to complete the document save operation automatically. Such situations occur when an office control tries to save a document that was opened from a custom document storage (such as a database) – and not from the server file system – via the following Open method overloads.

Open(string documentId, DocumentFormat format, Func<Stream> contentAccessor)
Open(string documentId, DocumentFormat format, Func<byte[]> contentAccessor)

Office controls expose the Saving server event, which enables you to handle document save operations in a custom manner. The event argument's e.DocumentID property (DocumentSavingEventArgs.DocumentID) identifies the document to be saved. Implement your custom saving logic and set the e.Handled property (DocumentSavingEventArgs.Handled) to true in the Saving event handler.

The example below shows how to save a document as a byte array:

The example below shows how to save a document as a stream:

If a custom saving procedure is required, but is not provided (or e.Handled is not set to true), the save operation tries to proceed and might finish with an exception.

Note

It is recommended that you declare the Saving event handler as a globally available static method. This handler can be used by the Auto-Saving feature if it is enabled for an office control.

See the following examples on how to save and load documents from a database to learn more.

Expanded Resolving Save Operation Conflicts

The Saving event can also be used to solve multi-user conflicts during save operations. These conflicts might arise when an end-user uses the SaveAs UI command (or the SaveCopy method overload is used in code) to save an office control's active document to another open document by overriding it. A conflict occurs when the target document is already opened by DocumentManager and contains unsaved changes made by another user.

The Save event's argument exposes the MultiUserConflict property (DocumentSavingEventArgs.MultiUserConflict), which informs you about a possible reason for the conflict. The property can have the following values:

You can resolve the issue by setting the MultiUserConflictResolve property (DocumentSavingEventArgs.MultiUserConflictResolve) to one of the following values.

  • MultiUserConflictResolve.Override
    Specifies that the target open document should be overridden with the currently processed document.

  • MultiUserConflictResolve.Persist
    Specifies that the target open document should be persisted. A specific exception will be thrown for the processed document: "It is impossible to save to an already opened file."

The example below illustrates how to prevent document override:

Expanded See Also

Is this topic helpful?​​​​​​​