Both reading and writing of additional data that is of simple types (like, e.g., boolean, int, long, float, double, or string) is supported transparently. This means, an IMapper that holds long values, for example, can be (de)serialized from/to a GraphML attribute with minimal effort using the convenience functionality provided by GraphMLIOHandler.

For data consisting of structured types, the WPF framework's XAML reader/writer infrastructure is used, i.e., reading and writing also works out-of-the-box provided that the types fulfill the conformance requirements for being XAML-(de)serializable. Similarly, structured types that provide an appropriate markup extension are also supported without further setup necessary.

Namespace handling for data consisting of structured types that is written by the XAML serialization mechanism is discussed in the section called “Namespace Mapping”.

Support for reading and writing of data that consists of structured types which cannot be (de)serialized by the WPF framework's XAML reader/writer infrastructure is provided through serialization/deserialization callbacks as explained in the section called “Custom Serialization and Deserialization”.

Information related to XAML serialization and deserialization can be found in the .NET framework's documentation. For example:

The GraphML framework supports reading additional data most conveniently when using IMappers to store the retrieved data. This functionality is built on top of the general serialization and deserialization support. The following convenience methods of GraphMLIOHandler enable registering IMappers as input data targets:

void AddInputMapper<TKey, TData>(
    string name, IMapper<TKey, TData> mapper)
  where TKey : class

void AddInputMapper<TKey, TData>(
    string name, KeyType type, IMapper<TKey, TData> mapper,
    EventHandler<HandleDeserializationEventArgs> deserializationCallback)
  where TKey : class

The IMapper<K, V> instances bind the data stored in GraphML attributes to their corresponding graph elements. The specified name must correspond to the attr.name of the GraphML attribute's key definition.

The following fragment shows how to register a mapper as input target for a GraphML attribute with node scope that stores long values.

GraphMLIOHandler ioh = new GraphMLIOHandler();
// Create a mapper.
IMapper<INode, long> nodeMapper = new DictionaryMapper<INode, long>();

// Register the mapper with the GraphML I/O handler.
// The deserializer will be looking for data that has attr.name "nodeAttr".
ioh.AddInputMapper<INode, long>("nodeAttr", nodeMapper);

As an alternative to registering already instantiated IMapper instances as the input targets, GraphMLIOHandler also supports registering IMapper "futures" using generic class Future<T>. Basically, "futures" means that IMapper instances are created lazily depending on whether there is actually a GraphML attribute with a matching attr.name specified in the GraphML file that is read. The following methods can be used for declaring IMapper "futures" when reading GraphML:

Future<IMapper<TKey, TData>> AddInputMapperFuture<TKey, TData>(string name)
  where TKey : class
Future<IMapper<TKey, TData>> AddInputMapperFuture<TKey, TData>(string name,
                                                               KeyType type)
  where TKey : class

Future<IMapper<TKey, TData>> AddRegistryInputMapper<TKey, TData>(string name)
  where TKey : class

To write data from an IMapper to a GraphML attribute, GraphMLIOHandler provides a set of methods to register the IMapper instance as an output data source that can be used analogously to the attribute input methods.

void AddOutputMapper<TModelItem, TValue>(
    string name, IMapper<TModelItem, TValue> mapper)
  where TModelItem : class

void AddOutputMapper<TModelItem, TValue>(
    string name, IMapper<TModelItem, TValue> mapper,
    EventHandler<HandleSerializationEventArgs> serializationCallback,
    KeyType declaredKeyType)
  where TModelItem : class

void AddRegistryOutputMapper(string name, object tag)
void AddRegistryOutputMapper<TModelItem, TValue>(string name)
  where TModelItem : class
void AddRegistryOutputMapper<TModelItem, TValue>(string name,
                                                 object tag)
  where TModelItem : class

The general scheme for serialization and deserialization of data types uses so-called output handlers and input handlers. These handlers are responsible for writing out, respectively reading in (structured) data. Event handlers for registering both output handlers and input handlers can be attached to the QueryOutputHandlers and QueryInputHandlers events, respectively. They are invoked by GraphMLIOHandler dynamically, i.e., at the time of writing or reading.

GraphMLIOHandler ioh = new GraphMLIOHandler();
ioh.QueryOutputHandlers += 
    delegate(object sender, QueryOutputHandlersEventArgs args) {
      args.AddOutputHandler(MyGetCustomEdgeOutputHandler(), KeyScope.Edge);
    };

ioh.QueryInputHandlers += 
    delegate(object sender, QueryInputHandlersEventArgs args) {
      String tag = GraphMLIOHandler.GetKeyName(args.KeyDefinition);
      if (args.Handled || !tag.StartsWith("my-custom-edge-data")) {
        return;
      }
      args.AddInputHandler(MyGetCustomEdgeInputHandler());
      args.Handled = true;
    };

Output handlers and input handlers for data types are implementations of interfaces IOutputHandler and IInputHandler, respectively. For both interfaces there are abstract implementations available which serve as convenient base classes:

The predefined generic classes ComplexMapperOutputHandler<TKey, TValue> and ComplexMapperInputHandler<TKey, TValue> provide the default support for writing and reading structured data that is held by IMapper instances.

Example 4.6, “Using data that is not held by an IMapper” shows how structured data that is not held by an IMapper can still be used in conjunction with generic class ComplexMapperOutputHandler by means of the Mappers helper class.

GraphMLIOHandler ioh = new GraphMLIOHandler();
ioh.QueryOutputHandlers += 
    delegate(object sender, QueryOutputHandlersEventArgs args) {
      ComplexMapperOutputHandler<IEdge, MyCustomData> mapperOH = 
          new ComplexMapperOutputHandler<IEdge, MyCustomData>("my-edge-data");
      
      // Get the data from somewhere and "convert" it to IMapper format.
      mapperOH.Mapper = Mappers.CreateMapper<IEdge, MyCustomData>(
          key => MyGetCustomDataFromSomewhere(key));
      
      args.AddOutputHandler(mapperOH, KeyScope.Edge);
    };

The default support for writing and reading structured data relies on the .NET framework's XAML reader/writer infrastructure. Specialized serialization and deserialization logic for structured data that is beyond this infrastructure or cannot be realized through markup extensions, for example, can be provided by means of event handlers.

Generic class ComplexMapperOutputHandler<TKey, TValue> enables custom serialization logic through the Serializer property. It can be used to attach an event handler specifically for the structured data that is held by an IMapper. Similarly, generic class ComplexMapperInputHandler<TKey, TValue> enables custom deserialization logic for an IMapper's data through the Deserializer property.

Example 4.7, “Custom serialization logic for structured data from an IMapper” shows custom serialization for data held in an IMapper.

GraphMLIOHandler ioh = new GraphMLIOHandler();
ioh.QueryOutputHandlers += 
    delegate(object sender, QueryOutputHandlersEventArgs args) {
      ComplexMapperOutputHandler<IEdge, MyTextHolder> mapperOH = 
          new ComplexMapperOutputHandler<IEdge, MyTextHolder>("my-edge-data");

      // Get the IMapper from the graph's mapper registry.
      IMapperRegistry mapperRegistry = args.Context.Graph.MapperRegistry;
      mapperOH.Mapper = 
          mapperRegistry.GetMapper<IEdge, MyTextHolder>("my-edge-data-imapper");

      // Specify the custom serialization logic.
      mapperOH.Serializer = 
          delegate(object serialSender, HandleSerializationEventArgs hsArgs) {
            // Only serialize items that are of the specific type.
            if (hsArgs.Item is MyTextHolder || 
                hsArgs.SourceType == typeof(MyTextHolder)) {
              MyTextHolder myItem = hsArgs.Item as MyTextHolder;
              if (myItem != null) {
                IXmlWriter writer = hsArgs.Writer;
                writer.WriteStartElement("MyReversedString", "MyNamespace");
                writer.WriteCData(MyGetReversedString(myItem.Text));
                writer.WriteEndElement();
                // Signal that this item is serialized.
                hsArgs.Handled = true;
              }
            }
          };
      args.AddOutputHandler(mapperOH, KeyScope.Edge);
    };

Example 4.8, “Custom deserialization logic for structured data” shows custom deserialization logic that corresponds to the serialization above.

// 'ioh' is of type yWorks.yFiles.GraphML.GraphMLIOHandler.

ioh.QueryInputHandlers += 
    // Register a delegate that is called when the <key> definitions of the 
    // GraphML attributes in a GraphML file are parsed.
    delegate(object sender, QueryInputHandlersEventArgs args) {
      String tag = GraphMLIOHandler.GetKeyName(args.KeyDefinition);
      // We are interested in the 'my-edge-data' GraphML attribute only. The
      // <key> definitions for other GraphML attributes are ignored.
      if (args.Handled || !tag.StartsWith("my-edge-data")) {
        return;
      }
      // Create and register an input handler that can read our structured data.
      // The delegate is called for each <data> element that holds a value of 
      // the GraphML attribute.
      ComplexMapperInputHandler<IEdge, MyTextHolder> mapperIH = 
          new ComplexMapperInputHandler<IEdge, MyTextHolder>(
              delegate(object deserialSender, 
                       HandleDeserializationEventArgs hdArgs) {
                  string text =
                      MyGetReversedString(((XmlElement)hdArgs.XmlNode).Value);
                  System.Console.WriteLine(text);
                  hdArgs.Result = new MyTextHolder(text);
                });
      IMapperRegistry mapperRegistry = args.Context.Graph.MapperRegistry;
      mapperIH.Mapper = 
          mapperRegistry.GetMapper<IEdge, MyTextHolder>("my-edge-data-imapper");
      args.AddInputHandler(mapperIH);
      args.Handled = true;
    };

In addition, the HandleSerialization and HandleDeserialization events available with GraphMLIOHandler can also be used to attach event handlers that provide custom (de)serialization logic. These event handlers can be used to realize support for structured types that are used by multiple IMappers, for example, or to provide general support for structured types in nested XML content of GraphML attribute data.

<?xml version="1.0" encoding="utf-8"?>
<!--Created by yFiles WPF 2.1-->
<graphml ... >
  ...
// The key definition of the shared data section in a GraphML file.
  <key id="d8" for="all" attr.name="SharedData" 
       y:attr.uri="http://www.yworks.com/xml/yfiles-common/2.0/SharedData" />
  ...
// The shared data section.
  <data key="d8">
// An entry in the shared data section: style data that is shared between graph
// elements. The root element of the shared content is added a new XML 
// attribute: 'x:Key'
// The value of this attribute is a unique ID that needs to be matched by any
// 'ResourceKey' values later on in order to share the data.
    <y:SharedData>
      <ywpf:ShapeNodeStyle x:Key="1" Pen="Red" 
                           Brush="#FF0C2238" Shape="Rectangle" />
    </y:SharedData>
  </data>
  ...
  <graph id="G" edgedefault="directed">
    <node id="n1">
      <data key="d2">
// A reference into the shared data section. The value of the 'ResourceKey' 
// attribute specifies the ID of the entry that is actually referenced.
        <y:GraphMLReference ResourceKey="1" />
      </data>
      ...
    </node>
    ...
  </graph>
</graphml>

// Excluding the property from reference sharing.
[GraphML(Shareable = GraphMLSharingMode.Never)]
public string MyComment { ... }

GraphMLIOHandler ioh = new GraphMLIOHandler();
ioh.QueryReferenceId +=
    delegate(object sender, QueryReferenceIdEventArgs args) {
      // If the current object is the same as the default node style, then write
      // "DefaultNodeStyle" instead.
      if (args.Value == args.Context.Graph.NodeDefaults.Style) {
        args.ReferenceId = "DefaultNodeStyle";
      }
    };

<node id="n1">
  <data key="d2">
// An external reference. The value of the 'ResourceKey' attribute is a
// user-defined symbolic name.
    <y:GraphMLReference ResourceKey="DefaultNodeStyle" />
  </data>
  ...
</node>

// 'ioh' is of type yWorks.yFiles.GraphML.GraphMLIOHandler.

ioh.ResolveReference +=
    delegate(object sender, ResolveReferenceEventArgs args) {
      if (args.ReferenceId.Equals("DefaultNodeStyle")) {
        // If we encounter a "DefaultNodeStyle" reference, retrieve an instance
        // from the graph's NodeDefaults.
        args.Value = args.Context.Graph.NodeDefaults.GetStyleInstance();
      }
    };

[assembly:XmlnsDefinition(
    "http://www.yworks.com/yFilesWPF/demos/SimpleCustomStyle/1.0",
    "Demo.yFiles.Graph.SimpleCustomStyle")]
[assembly:XmlnsPrefix(
    "http://www.yworks.com/yFilesWPF/demos/SimpleCustomStyle/1.0", "demo")]

namespace Demo.yFiles.Graph.SimpleCustomStyle { ... }

<?xml version="1.0" encoding="utf-8"?>
<!--Created by yFiles WPF 2.1-->
<graphml
    xmlns:demo="http://www.yworks.com/yFilesWPF/demos/SimpleCustomStyle/1.0"

    xmlns:x="http://www.yworks.com/xml/yfiles-common/markup/2.0"
    xmlns:y="http://www.yworks.com/xml/yfiles-common/2.0"
    xmlns:ywpf="http://www.yworks.com/xml/yfiles-wpf/2.0/xaml"
    xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xsi:schemaLocation="http://graphml.graphdrawing.org/xmlns
          http://www.yworks.com/xml/schema/graphml.net/4.0/ygraphml.xsd"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://graphml.graphdrawing.org/xmlns">
...
<key id="d9" attr.name="SharedData"
     y:attr.uri="http://www.yworks.com/xml/yfiles-common/2.0/SharedData" />
<data key="d9">
  <y:SharedData>
    <demo:MySimpleNodeStyle x:Key="1" />
    <demo:MySimpleLabelStyle x:Key="2" />
    <demo:MySimpleEdgeStyle x:Key="3">
      <demo:MySimpleEdgeStyle.Arrows>
        <demo:MySimpleArrow />
      </demo:MySimpleEdgeStyle.Arrows>
    </demo:MySimpleEdgeStyle>
  </y:SharedData>
</data>
...
</graphml>

For examples how customized writing and parsing logic can be provided, please see the following tutorial demo applications: