XmlConvert.EncodeName Method (System.Xml)

EncodeName Method

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

.NET Framework Class Library

XmlConvert..::.EncodeName Method

Converts the name to a valid XML name.

Namespace: System.Xml
Assembly: System.Xml (in System.Xml.dll)

Syntax

Visual Basic (Declaration)

Public Shared Function EncodeName ( _
    name As String _
) As String

Visual Basic (Usage)

Dim name As String
Dim returnValue As String

returnValue = XmlConvert.EncodeName(name)

public static string EncodeName(
    string name
)

Visual C++

public:
static String^ EncodeName(
    String^ name
)

JScript

public static function EncodeName(
    name : String
) : String

Parameters

name: Type: System..::.String
A name to be translated.

Return Value

Type: System..::.String
Returns the name with any invalid characters replaced by an escape string.

Remarks

This method translates invalid characters, such as spaces or half-width Katakana, that need to be mapped to XML names without the support or presence of schemas. The invalid characters are translated into escaped numeric entity encodings.

The escape character is "_". Any XML name character that does not conform to the W3C Extensible Markup Language (XML) 1.0 specification is escaped as _xHHHH_. The HHHH string stands for the four-digit hexadecimal UCS-2 code for the character in most significant bit first order. For example, the name Order Details is encoded as Order_x0020_Details.

The underscore character does not need to be escaped unless it is followed by a character sequence that together with the underscore can be misinterpreted as an escape sequence when decoding the name. For example, Order_Details is not encoded, but Order_x0020_ is encoded as Order_x005f_x0020_. No shortforms are allowed. For example, the forms _x20_ and __ are not generated.

This method guarantees the name is valid according to the XML specification. It allows colons in any position, which means the name may still be invalid according to the W3C Namespace Specification (www.w3.org/TR/REC-xml-names). To guarantee it is a valid namespace qualified name use EncodeLocalName for the prefix and local name parts and join the result with a colon.

Examples

The following example encodes and decodes names.

Visual Basic

Imports System
Imports System.IO
Imports System.Xml

public class Sample

  public shared sub Main()

     ' Encode and decode a name with spaces.
     Dim name1 as string = XmlConvert.EncodeName("Order Detail")
     Console.WriteLine("Encoded name: " + name1)
     Console.WriteLine("Decoded name: " + XmlConvert.DecodeName(name1))

     ' Encode and decode a local name.
     Dim name2 as string= XmlConvert.EncodeLocalName("a:book")
     Console.WriteLine("Encoded local name: " + name2)
     Console.WriteLine("Decoded local name: " + XmlConvert.DecodeName(name2))

  end sub
end class

using System;
using System.IO;
using System.Xml;

public class Sample
{

  public static void Main()
  {

     // Encode and decode a name with spaces.
     string name1 = XmlConvert.EncodeName("Order Detail");
     Console.WriteLine("Encoded name: " + name1);
     Console.WriteLine("Decoded name: " + XmlConvert.DecodeName(name1));

     // Encode and decode a local name.
     string name2 = XmlConvert.EncodeLocalName("a:book");
     Console.WriteLine("Encoded local name: " + name2);
     Console.WriteLine("Decoded local name: " + XmlConvert.DecodeName(name2));

  }
}

Visual C++

#using <System.dll>
#using <System.XML.dll>

using namespace System;
using namespace System::IO;
using namespace System::Xml;
int main()
{

   // Encode and decode a name with spaces.
   String^ name1 = XmlConvert::EncodeName( "Order Detail" );
   Console::WriteLine( "Encoded name: {0}", name1 );
   Console::WriteLine( "Decoded name: {0}", XmlConvert::DecodeName( name1 ) );

   // Encode and decode a local name.
   String^ name2 = XmlConvert::EncodeLocalName( "a:book" );
   Console::WriteLine( "Encoded local name: {0}", name2 );
   Console::WriteLine( "Decoded local name: {0}", XmlConvert::DecodeName( name2 ) );
}

CPP_OLD

#using <mscorlib.dll>
#using <System.dll>
#using <System.XML.dll>

using namespace System;
using namespace System::IO;
using namespace System::Xml;

int main()
{
   // Encode and decode a name with spaces.
   String* name1 = XmlConvert::EncodeName(S"Order Detail");
   Console::WriteLine( S"Encoded name: {0}", name1);
   Console::WriteLine( S"Decoded name: {0}", XmlConvert::DecodeName(name1));

   // Encode and decode a local name.
   String*    name2 = XmlConvert::EncodeLocalName(S"a:book");
   Console::WriteLine( S"Encoded local name: {0}", name2);
   Console::WriteLine( S"Decoded local name: {0}", XmlConvert::DecodeName(name2));
}

Platforms

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC, Xbox 360, Zune

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Version Information

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 3.5, 2.0, 1.0

XNA Framework

Supported in: 3.0, 2.0, 1.0

Reference