Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -22,15 +22,15 @@ ms.workload:
- dotnet
---
# Document Serialization and Storage
Microsoft .NET Framework provides a powerful environment for creating and displaying high quality documents. Enhanced features that support both fixed-documents and flow-documents, advanced viewing controls, combined with powerful 2D and 3D graphic capabilities take [!INCLUDE[TLA2#tla_winfx](../../../../includes/tla2sharptla-winfx-md.md)] applications to a new level of quality and user experience. Being able to flexibly manage an in-memory representation of a document is a key feature of [!INCLUDE[TLA2#tla_winfx](../../../../includes/tla2sharptla-winfx-md.md)], and being able to efficiently save and load documents from a data store is a need of almost every application. The process of converting a document from an internal in-memory representation to an external data store is termed serialization. The reverse process of reading a data store and recreating the original in-memory instance is termed deserialization.
Microsoft .NET Framework provides a powerful environment for creating and displaying high quality documents. Enhanced features that support both fixed-documents and flow-documents, advanced viewing controls, combined with powerful 2D and 3D graphic capabilities take .NET Framework applications to a new level of quality and user experience. Being able to flexibly manage an in-memory representation of a document is a key feature of .NET Framework, and being able to efficiently save and load documents from a data store is a need of almost every application. The process of converting a document from an internal in-memory representation to an external data store is termed serialization. The reverse process of reading a data store and recreating the original in-memory instance is termed deserialization.



<a name="AboutSerialization"></a>
## About Document Serialization
Ideally the process of serializing and deserializing a document from and then back into memory is transparent to the application. The application calls a serializer "write" method to save the document, while a deserializer "read" method accesses the data store and recreates the original instance in memory. The specific format that the data is stored in is generally not a concern of the application as long as the serialize and deserialize process recreates the document back to its original form.

Applications often provide multiple serialization options which allow the user to save documents to different medium or to a different format. For example, an application might offer "Save As" options to store a document to a disk file, database, or web service. Similarly, different serializers could store the document in different formats such as in HTML, RTF, XML, XPS, or alternately to a third-party format. To the application, serialization defines an interface that isolates the details of the storage medium within the implementation of each specific serializer. In addition to the benefits of encapsulating storage details, the [!INCLUDE[TLA2#tla_winfx](../../../../includes/tla2sharptla-winfx-md.md)] <xref:System.Windows.Documents.Serialization> [!INCLUDE[TLA2#tla_api#plural](../../../../includes/tla2sharptla-apisharpplural-md.md)] provide several other important features.
Applications often provide multiple serialization options which allow the user to save documents to different medium or to a different format. For example, an application might offer "Save As" options to store a document to a disk file, database, or web service. Similarly, different serializers could store the document in different formats such as in HTML, RTF, XML, XPS, or alternately to a third-party format. To the application, serialization defines an interface that isolates the details of the storage medium within the implementation of each specific serializer. In addition to the benefits of encapsulating storage details, the .NET Framework <xref:System.Windows.Documents.Serialization> [!INCLUDE[TLA2#tla_api#plural](../../../../includes/tla2sharptla-apisharpplural-md.md)] provide several other important features.

### Features of .NET Framework 3.0 Document Serializers

Expand All @@ -40,7 +40,7 @@ Microsoft .NET Framework provides a powerful environment for creating and displa

- Support for plug-in serializers with enhanced capabilities:

- System-wide access for use by all [!INCLUDE[TLA2#tla_winfx](../../../../includes/tla2sharptla-winfx-md.md)] applications.
- System-wide access for use by all .NET Framework applications.

- Simple application plug-in discoverability.

Expand All @@ -58,7 +58,7 @@ Microsoft .NET Framework provides a powerful environment for creating and displa
Plug-in serializers aid application developers by providing extensibility to new storage designs and file formats without having to code directly for every potential format at build time. Plug-in serializers also benefit third-party developers by providing a standardized means to deploy, install, and update system accessible plug-ins for custom or proprietary file formats.

### Using a Plug-in Serializer
Plug-in serializers are simple to use. The <xref:System.Windows.Documents.Serialization.SerializerProvider> class enumerates a <xref:System.Windows.Documents.Serialization.SerializerDescriptor> object for each plug-in installed on the system. The <xref:System.Windows.Documents.Serialization.SerializerDescriptor.IsLoadable%2A> property filters the installed plug-ins based on the current configuration and verifies that the serializer can be loaded and used by the application. The <xref:System.Windows.Documents.Serialization.SerializerDescriptor> also provides other properties, such as <xref:System.Windows.Documents.Serialization.SerializerDescriptor.DisplayName%2A> and <xref:System.Windows.Documents.Serialization.SerializerDescriptor.DefaultFileExtension%2A>, which the application can use to prompt the user in selecting a serializer for an available output format. A default plug-in serializer for [!INCLUDE[TLA2#tla_xps](../../../../includes/tla2sharptla-xps-md.md)] is provided with [!INCLUDE[TLA2#tla_winfx](../../../../includes/tla2sharptla-winfx-md.md)] and is always enumerated. After the user selects an output format, the <xref:System.Windows.Documents.Serialization.SerializerProvider.CreateSerializerWriter%2A> method is used to create a <xref:System.Windows.Documents.Serialization.SerializerWriter> for the specific format. The <xref:System.Windows.Documents.Serialization.SerializerWriter>.<xref:System.Windows.Documents.Serialization.SerializerWriter.Write%2A> method can then be called to output the document stream to the data store.
Plug-in serializers are simple to use. The <xref:System.Windows.Documents.Serialization.SerializerProvider> class enumerates a <xref:System.Windows.Documents.Serialization.SerializerDescriptor> object for each plug-in installed on the system. The <xref:System.Windows.Documents.Serialization.SerializerDescriptor.IsLoadable%2A> property filters the installed plug-ins based on the current configuration and verifies that the serializer can be loaded and used by the application. The <xref:System.Windows.Documents.Serialization.SerializerDescriptor> also provides other properties, such as <xref:System.Windows.Documents.Serialization.SerializerDescriptor.DisplayName%2A> and <xref:System.Windows.Documents.Serialization.SerializerDescriptor.DefaultFileExtension%2A>, which the application can use to prompt the user in selecting a serializer for an available output format. A default plug-in serializer for [!INCLUDE[TLA2#tla_xps](../../../../includes/tla2sharptla-xps-md.md)] is provided with .NET Framework and is always enumerated. After the user selects an output format, the <xref:System.Windows.Documents.Serialization.SerializerProvider.CreateSerializerWriter%2A> method is used to create a <xref:System.Windows.Documents.Serialization.SerializerWriter> for the specific format. The <xref:System.Windows.Documents.Serialization.SerializerWriter>.<xref:System.Windows.Documents.Serialization.SerializerWriter.Write%2A> method can then be called to output the document stream to the data store.

The following example illustrates an application that uses the <xref:System.Windows.Documents.Serialization.SerializerProvider> method in a "PlugInFileFilter" property. PlugInFileFilter enumerates the installed plug-ins and builds a filter string with the available file options for a <xref:Microsoft.Win32.SaveFileDialog>.

Expand All @@ -70,14 +70,14 @@ Microsoft .NET Framework provides a powerful environment for creating and displa

<a name="InstallingPluginSerializers"></a>
### Installing Plug-in Serializers
The <xref:System.Windows.Documents.Serialization.SerializerProvider> class supplies the upper-level application interface for plug-in serializer discovery and access. <xref:System.Windows.Documents.Serialization.SerializerProvider> locates and provides the application a list of the serializers that are installed and accessible on the system. The specifics of the installed serializers are defined through registry settings. Plug-in serializers can be added to the registry by using the <xref:System.Windows.Documents.Serialization.SerializerProvider.RegisterSerializer%2A> method; or if [!INCLUDE[TLA2#tla_winfx](../../../../includes/tla2sharptla-winfx-md.md)] is not yet installed, the plug-in installation script can directly set the registry values itself. The <xref:System.Windows.Documents.Serialization.SerializerProvider.UnregisterSerializer%2A> method can be used to remove a previously installed plug-in, or the registry settings can be reset similarly by an uninstall script.
The <xref:System.Windows.Documents.Serialization.SerializerProvider> class supplies the upper-level application interface for plug-in serializer discovery and access. <xref:System.Windows.Documents.Serialization.SerializerProvider> locates and provides the application a list of the serializers that are installed and accessible on the system. The specifics of the installed serializers are defined through registry settings. Plug-in serializers can be added to the registry by using the <xref:System.Windows.Documents.Serialization.SerializerProvider.RegisterSerializer%2A> method; or if .NET Framework is not yet installed, the plug-in installation script can directly set the registry values itself. The <xref:System.Windows.Documents.Serialization.SerializerProvider.UnregisterSerializer%2A> method can be used to remove a previously installed plug-in, or the registry settings can be reset similarly by an uninstall script.

### Creating a Plug-in Serializer
Both plug-in serializers and linked serializers use the same exposed public methods and events, and similarly can be designed to operate either synchronously or asynchronously. There are three basic steps normally followed to create a plug-in serializer:

1. Implement and debug the serializer first as a linked serializer. Initially creating the serializer compiled and linked directly in a test application provides full access to breakpoints and other debug services helpful for testing.

2. After the serializer is fully tested, an <xref:System.Windows.Documents.Serialization.ISerializerFactory> interface is added to create a plug-in. The <xref:System.Windows.Documents.Serialization.ISerializerFactory> interface permits full access to all [!INCLUDE[TLA2#tla_winfx](../../../../includes/tla2sharptla-winfx-md.md)] objects which includes the logical tree, <xref:System.Windows.UIElement> objects, <xref:System.Windows.Documents.IDocumentPaginatorSource>, and <xref:System.Windows.Media.Visual> elements. Additionally <xref:System.Windows.Documents.Serialization.ISerializerFactory> provides the same synchronous and asynchronous methods and events used by linked serializers. Since large documents can take time to output, asynchronous operations are recommended to maintain responsive user interaction and offer a "Cancel" option if some problem occurs with the data store.
2. After the serializer is fully tested, an <xref:System.Windows.Documents.Serialization.ISerializerFactory> interface is added to create a plug-in. The <xref:System.Windows.Documents.Serialization.ISerializerFactory> interface permits full access to all .NET Framework objects which includes the logical tree, <xref:System.Windows.UIElement> objects, <xref:System.Windows.Documents.IDocumentPaginatorSource>, and <xref:System.Windows.Media.Visual> elements. Additionally <xref:System.Windows.Documents.Serialization.ISerializerFactory> provides the same synchronous and asynchronous methods and events used by linked serializers. Since large documents can take time to output, asynchronous operations are recommended to maintain responsive user interaction and offer a "Cancel" option if some problem occurs with the data store.

3. After the plug-in serializer is created, an installation script is implemented for distributing and installing (and uninstalling) the plug-in (see above, "[Installing Plug-in Serializers](#InstallingPluginSerializers)").

Expand Down
4 changes: 2 additions & 2 deletions docs/framework/wpf/advanced/printing-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ With Microsoft .NET Framework, application developers using [!INCLUDE[TLA#tla_wp

- Native support of advanced color profiles, which include 32 bits per channel (bpc), CMYK, named-colors, n-inks, and native support of transparency and gradients.

- Improved print performance for both [!INCLUDE[TLA2#tla_winfx](../../../../includes/tla2sharptla-winfx-md.md)] and [!INCLUDE[TLA#tla_win32](../../../../includes/tlasharptla-win32-md.md)] based applications.
- Improved print performance for both .NET Framework and [!INCLUDE[TLA#tla_win32](../../../../includes/tlasharptla-win32-md.md)] based applications.

- Industry standard [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] format.

Expand All @@ -68,7 +68,7 @@ With Microsoft .NET Framework, application developers using [!INCLUDE[TLA#tla_wp
- Extensible Filter Pipeline. The [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] printer driver (XPSDrv) filter pipeline was designed to enable both direct and scalable printing of [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] documents. (Lookup "XPSDrv" in the [Windows Driver Kit](https://msdn.microsoft.com/library/windows/hardware/ff557573.aspx).)

### Print Path Architecture
While both [!INCLUDE[TLA2#tla_win32](../../../../includes/tla2sharptla-win32-md.md)] and [!INCLUDE[TLA2#tla_winfx](../../../../includes/tla2sharptla-winfx-md.md)] applications support [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)], [!INCLUDE[TLA2#tla_win32](../../../../includes/tla2sharptla-win32-md.md)] and Windows Forms applications use a [!INCLUDE[TLA2#tla_gdi](../../../../includes/tla2sharptla-gdi-md.md)] to [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] conversion in order to create [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] formatted content for the [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] printer driver (XPSDrv). These applications are not required to use the [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] print path, and can continue to use [!INCLUDE[TLA#tla_emf](../../../../includes/tlasharptla-emf-md.md)] based printing. However, most [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] features and enhancements are only available to applications that target the [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] print path.
While both [!INCLUDE[TLA2#tla_win32](../../../../includes/tla2sharptla-win32-md.md)] and .NET Framework applications support [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)], [!INCLUDE[TLA2#tla_win32](../../../../includes/tla2sharptla-win32-md.md)] and Windows Forms applications use a [!INCLUDE[TLA2#tla_gdi](../../../../includes/tla2sharptla-gdi-md.md)] to [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] conversion in order to create [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] formatted content for the [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] printer driver (XPSDrv). These applications are not required to use the [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] print path, and can continue to use [!INCLUDE[TLA#tla_emf](../../../../includes/tlasharptla-emf-md.md)] based printing. However, most [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] features and enhancements are only available to applications that target the [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] print path.

To enable the use of XPSDrv-based printers by [!INCLUDE[TLA2#tla_win32](../../../../includes/tla2sharptla-win32-md.md)] and Windows Forms applications, the [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] printer driver (XPSDrv) supports conversion of [!INCLUDE[TLA2#tla_gdi](../../../../includes/tla2sharptla-gdi-md.md)] to [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] format. The XPSDrv model also provides a converter for [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] to [!INCLUDE[TLA2#tla_gdi](../../../../includes/tla2sharptla-gdi-md.md)] format so that [!INCLUDE[TLA2#tla_win32](../../../../includes/tla2sharptla-win32-md.md)] applications can print [!INCLUDE[TLA2#tla_xps](../../../../includes/tla2sharptla-xps-md.md)] Documents. For [!INCLUDE[TLA2#tla_wpf](../../../../includes/tla2sharptla-wpf-md.md)] applications, conversion of [!INCLUDE[TLA2#tla_metro](../../../../includes/tla2sharptla-metro-md.md)] to [!INCLUDE[TLA2#tla_gdi](../../../../includes/tla2sharptla-gdi-md.md)] format is done automatically by the <xref:System.Windows.Xps.XpsDocumentWriter.Write%2A> and <xref:System.Windows.Xps.XpsDocumentWriter.WriteAsync%2A> methods of the <xref:System.Windows.Xps.XpsDocumentWriter> class whenever the target print queue of the write operation does not have an XPSDrv driver. (Windows Forms applications cannot print [!INCLUDE[TLA2#tla_xps](../../../../includes/tla2sharptla-xps-md.md)] Documents.)

Expand Down
Loading