System.Xml.Serialization.XmlNamespaceDeclarationsAttribute Class

Assembly: System.Xml.dll
Namespace: System.Xml.Serialization
Summary
Specifies that the target property, parameter, return value or class member contains prefixes associated with namespaces that are used within an XML document.
C# Syntax:
[AttributeUsage(AttributeTargets.Property | AttributeTargets.Field | AttributeTargets.Parameter | AttributeTargets.ReturnValue)]
public class XmlNamespaceDeclarationsAttribute : Attribute
Remarks
The XmlNamespaceDeclarationsAttribute attribute can only be applied once in a class to a field or property that returns an XmlSerializerNamespaces object.

The XmlNamespaceDeclarationsAttribute allows you to store the prefixes, and the associated namespaces, used in an XML document. For example, one common usage of the attribute is to store XPath data, as it is defined by the World Wide Web Consortium (www.w3.org) document named "XML Language (XPath) Version 1.0". In brief, an XPath is a string containing many namespace prefixes and local names, along with some other syntax.

The XPath language allows for the association of a prefix with a path, and using the prefix within the XML document. For example, the following XML document named "select" contains a prefix ("cal") associated with a specific URI (http://www.cohowinery.com/calendar/). The element contains an attribute named "path" that contains the XPath.

          <select xmlns:cal ="http://www.cohowinery.com/calendar/" path="cal:appointments/@startTime" />
        

The schema for this might be:

          <element name="select">
             <complexType>
                <simpleContent>
                   <attribute name="path" />
                </simpleContent>
             </complexType>
          </element>
        

Without the XmlNamespaceDeclarationsAttribute, the association between the prefix and the namespace would be lost.

To retain the association between the prefix and the namespace URI, add a member that returns an XmlSerializerNamespaces object and apply the XmlNamespaceDeclarationsAttribute attribute to the member, as shown in the following C# and Visual Basic code:

          // C#
          public class Select {
            [XmlAttribute] public string path;
            [XmlNamespaceDeclarations] public XmlSerializerNamespaces xmlns;
          }
          ' Visual Basic
          Public Class Select
             <XmlAttribute> Public path As String
             <XmlNamespaceDeclarations> Public xmlns As XmlSerializerNamespaces
          End Class
        

When serialized, the schema for the generated XML document will contain the XML Schema definition (XSD) element named appinfo . The element further contains a metadata element named keepNamespaceDeclarations , set to the name of the member that contains the namespace declarations. The schema for such an XML document is shown below:

          <xs:element name="select">
             <xs:complexType>
                <xs:annotation> 
                   <xs:appinfo>
                    <keepNamespaceDeclarations>xmlns</keepNamespaceDeclarations>
                   </xs:appinfo> 
                </xs:annotation> 
                <xs:simpleContent>
                   <xs:attribute name="path" />
                </xs:simpleContent>
             </xs:complexType>
          </xs:element>
        

On deserialization, the xmlns field will contain an XmlSerializerNamespaces object containing all namespace prefix definitions.

On serialization, the user can add prefix-namespace pairs to the XmlSerializerNamespaces object using the XmlSerializerNamespaces.Add method. This is shown in the C# and Visual Basic code below:

          // C#
          using System;
          using System.IO;
          using System.Xml.Serialization;
          [XmlRoot("select")]
          public class Select {
             [XmlAttribute]
             public string xpath;
             [XmlNamespaceDeclarations]
             public XmlSerializerNamespaces xmlns;
          }
          public class Test {
             public static void Main(string[] args) {
                Select mySelect = new Select();
                mySelect.xpath = "myNS:ref/@common:y";
                mySelect.xmlns = new XmlSerializerNamespaces();
                mySelect.xmlns.Add("MyNS", "myNS.tempuri.org");
                mySelect.xmlns.Add("common", "common.tempuri.org");
                XmlSerializer ser = new XmlSerializer(typeof(Select));
                ser.Serialize(Console.Out, mySelect);
             }
          }
          // Output:
          // <?xml version="1.0" encoding="IBM437"?>
          // <select xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          // xmlns:common="common.tempuri.org" xmlns:MyNS="myNS.tempuri.org" xpath="myNS:ref/@common:y" />
          ' Visual Basic
          Imports System
          Imports System.IO
          Imports System.Xml.Serialization
          <XmlRoot("select")> _
          Public Class SelectPath
             <XmlAttribute> _
             Public xpath As String 
             <XmlNamespaceDeclarations> _
             public xmlns As XmlSerializerNamespaces 
          End Class
          Public Class Test 
             Public Shared Sub Main() 
                Dim mySelect As SelectPath = New SelectPath()
                mySelect.xpath = "myNS:ref/@common:y"
                mySelect.xmlns = New XmlSerializerNamespaces()
                mySelect.xmlns.Add("MyNS", "myNS.tempuri.org")
                mySelect.xmlns.Add("common", "common.tempuri.org")
                Dim ser As XmlSerializer = New XmlSerializer(mySelect.GetType)
                ser.Serialize(Console.Out, mySelect)
             End Sub
          End Class
          'Output:
          ' <?xml version="1.0" encoding="IBM437"?>
          ' <select xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          ' xmlns:common="common.tempuri.org" xmlns:MyNS="myNS.tempuri.org" xpath="myNS:ref/@common:y" />
        

Also note that the member to which the attribute is applied will contain only the prefix-namespace pairs belonging to the XML element defined by the class. For example, in the XML document shown below, only the prefix pair "cal" will be captured, but not the "x" prefix. To get that data, add a member with the XmlNamespaceDeclarationsAttribute to the class representing the root element.

          <?xml version="1.0"?>
          <x:root xmlns:x="http://www.cohowinery.com/x/">
            <x:select xmlns:cal="http://www.cohowinery.com/calendar/" path="cal:appointments/@cal:startTime" />
          </x:root>
        
See also:
System.Xml.Serialization Namespace

System.Xml.Serialization.XmlNamespaceDeclarationsAttribute Member List:

Public Constructors
ctor #1 Default constructor. This constructor is called by derived class constructors to initialize state in this type.
Initializes a new instance of the XmlNamespaceDeclarationsAttribute class.
Public Properties
TypeId
(inherited from System.Attribute)
Read-only

See base class member description: System.Attribute.TypeId


When implemented in a derived class, gets a unique identifier for this Attribute.
Public Methods
Equals
(inherited from System.Object)
See base class member description: System.Object.Equals

Derived from System.Object, the primary base class for all objects.
GetHashCode
(inherited from System.Attribute)
See base class member description: System.Attribute.GetHashCode


Returns the hash code for this instance.
GetType
(inherited from System.Object)
See base class member description: System.Object.GetType

Derived from System.Object, the primary base class for all objects.
IsDefaultAttribute
(inherited from System.Attribute)
See base class member description: System.Attribute.IsDefaultAttribute


When overridden in a derived class, returns an indication whether the value of this instance is the default value for the derived class.
Match
(inherited from System.Attribute)
See base class member description: System.Attribute.Match


When overridden in a derived class, returns a value indicating whether this instance equals a specified object.
ToString
(inherited from System.Object)
See base class member description: System.Object.ToString

Derived from System.Object, the primary base class for all objects.
Protected Methods
Finalize
(inherited from System.Object)
See base class member description: System.Object.Finalize

Derived from System.Object, the primary base class for all objects.
MemberwiseClone
(inherited from System.Object)
See base class member description: System.Object.MemberwiseClone

Derived from System.Object, the primary base class for all objects.

Hierarchy:


System.Xml.Serialization.XmlNamespaceDeclarationsAttribute Member Details

ctor #1
Summary
Initializes a new instance of the XmlNamespaceDeclarationsAttribute class.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.
C# Syntax:
public XmlNamespaceDeclarationsAttribute();
Remarks
The XmlNamespaceDeclarationsAttribute can only be applied to a target that returns an XmlSerializerNamespaces object.

Return to top


Property: TypeId (read-only)
Inherited
See base class member description: System.Attribute.TypeId

Summary
When implemented in a derived class, gets a unique identifier for this Attribute.
C# Syntax:
public virtual object TypeId {get;}
Remarks
As implemented, this identifier is merely the Type of the attribute. However, it is intended that the unique identifier be used to identify two attributes of the same type.

Return to top


Method: Equals(
   object obj
)
Inherited
See base class member description: System.Object.Equals
C# Syntax:
public virtual bool Equals(
   object obj
);

For more information on members inherited from System.Object click on the link above.

Return to top


Method: Finalize()
Inherited
See base class member description: System.Object.Finalize
C# Syntax:
~XmlNamespaceDeclarationsAttribute();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: GetHashCode()
Inherited
See base class member description: System.Attribute.GetHashCode

Summary
Returns the hash code for this instance.
C# Syntax:
public override int GetHashCode();
Return Value:
A 32-bit signed integer hash code.

Return to top


Method: GetType()
Inherited
See base class member description: System.Object.GetType
C# Syntax:
public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: IsDefaultAttribute()
Inherited
See base class member description: System.Attribute.IsDefaultAttribute

Summary
When overridden in a derived class, returns an indication whether the value of this instance is the default value for the derived class.
C# Syntax:
public virtual bool IsDefaultAttribute();
Return Value:
true if this instance is the default attribute for the class; otherwise, false.
Remarks
The default implementation of this class returns false, and must be implemented in the derived class to be useful to that class.

The implementation of this method in a derived class compares the value of this instance to a standard, default value obtained by some means, then returns a Boolean value that indicates whether the value of this instance is equal to the standard. The standard value is typically coded as a constant in the implementation, or stored programmatically in a field used by the implementation.

Return to top


Method: Match(
   object obj
)
Inherited
See base class member description: System.Attribute.Match

Summary
When overridden in a derived class, returns a value indicating whether this instance equals a specified object.
C# Syntax:
public virtual bool Match(
   object obj
);
Parameters:

obj

An Object to compare with this instance of Attribute.

Return Value:
true if this instance equals obj; otherwise, false.
Remarks
This method determines if one Attribute equals another. Its default implementation is the same as Attribute.Equals, which performs a value and reference comparison. Override this method to implement support for attribute values, such as flags or bitfields, that consist of components that are meaningful in themselves. For example, consider an attribute whose value is a binary field divided into a bitfield of flags. Two instances of this attribute have one flag in set in common while all the other flags differ. The Equal method cannot determine that the two instances have the same flag set, but the Match method can.

Return to top


Method: MemberwiseClone()
Inherited
See base class member description: System.Object.MemberwiseClone
C# Syntax:
protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top


Method: ToString()
Inherited
See base class member description: System.Object.ToString
C# Syntax:
public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top


Top of page

Copyright (c) 2002 Microsoft Corporation. All rights reserved.