Home XElement Encoding: Why Is My HTML Link Escaping?

Coding Best Practices

XElement Encoding: Why Is My HTML Link Escaping?

Struggling with strange XML encoding in XElement? Learn why HTML links auto-escape and how to fix value insertion in C#.

byDev Solutions

January 3, 2026

Frustrated developer staring at escaped HTML link code like <a href=...> in XElement, emphasizing XML encoding issue in C#

⚠️ XElement automatically escapes strings. It treats them as text to keep XML valid.
💡 If you pass raw HTML strings directly, they become escaped nodes, not nested XML.
✅ Use XElement.Parse() or child XElement parts to add unescaped HTML/XML.
🚫 CDATA lets you use raw markup, but it can't have ]]>. Also, some parsers have trouble with it.
🧠 How you choose between string encoding, child nodes, or CDATA changes the output and how processors work with it.

Why XElement Escapes XHTML Links: How Encoding Works in C#

If you have tried putting an HTML part, like a link, into an XElement and it shows up as escaped characters like <a> instead of real tags, you are seeing how XML serialization and encoding works. This article explains how and why C# XElement does this. It also tells developers what they can do to fix this when they use content that changes, HTML markup, and XML communication between systems.

XML Today

JSON is often the common format for modern REST APIs and web services. But XML is still used a lot in important areas:

Enterprise Systems & APIs (SOAP): Many organizations, especially older financial or healthcare systems, still use SOAP interfaces. These use XML for messages because of its rules and schema support.
Office File Formats (OpenXML): Microsoft Word (.docx), Excel (.xlsx), and other Office files are ZIP-compressed groups of XML files.
Configuration Files in .NET: The .config files in .NET and app settings use XML.
Feeds (RSS/Atom): RSS 2.0 and Atom are XML feeds. Content collection systems and podcast platforms still use them often.
Working Across Systems: When you work with different technologies, like Java and .NET, XML can be a common language. This is because it has good tools and schema validation.

It is still a required skill in many software jobs to understand how to work with XML using C#'s LINQ to XML. This includes handling content encoding.

What Is C# XElement?

The XElement class is in the System.Xml.Linq namespace. It is one element in an XML tree. It is a main part of LINQ to XML, an API that helps developers make, find, and change XML documents in C#.

Here is a simple example:

var greeting = new XElement("message", "Hello, world!");
Console.WriteLine(greeting);
// Output: <message>Hello, world!</message>

Developers can use XElement to:

Make complex XML structures easily
Add nested elements and attributes
Parse existing XML strings
Convert XML documents to strings or files
Work with web APIs, config files, and data formats

But XElement also assumes some things. When you give it a string, it escapes special characters. This follows XML rules and stops the document from getting corrupted by mistake.

Automatic Encoding: Why It Works This Way

XML is a markup language, like HTML. It uses certain characters for its structure. Characters such as <, >, and & are special. They mean the start of a tag or an entity. If you put them directly into XML without escaping them, the markup would be wrong. This would make parsers fail.

Here is a table that shows how certain characters get encoded automatically in XML:

Character	Encoded As	Reason
`<`	`<`	Marks the beginning of a tag
`>`	`>`	Marks the end of a tag
`&`	`&`	Starts an entity reference (`&name;`)
`"`	`"`	Used in attribute values enclosed in double quotes
`'`	`'`	Used in attribute values enclosed in single quotes

So when you write:

var element = new XElement("note", "<b>Bold Text</b>");

The XML you get will be:

<note>&lt;b&gt;Bold Text&lt;/b&gt;</note>

The  tags are encoded for safety. They are read as text. To get real nested elements, we need a different way.

The Escaped Link Problem With XElement

Suppose you want to make an RSS feed using XElement. You need to put a link in the description. You might try to just pass in an HTML string:

var item = new XElement("description", "<a href='https://example.com'>Read more</a>");

The XML output is:

<description>&lt;a href='https://example.com'&gt;Read more&lt;/a&gt;</description>

But RSS readers expect real markup under the <description> tag, not escaped pieces. This stops styling or links from working in feed readers.

This difference causes a big problem in many real situations. HTML or XHTML needs to be part of an XML message in these cases. We will look at why this happens and how to fix it.

How XElement Reads Strings

To control the output, you need to know how the XElement constructor works:

var element = new XElement("tag", content);

How this constructor acts depends on the kind of content you give it:

1. Give it a String

var el = new XElement("example", "<em>Italic</em>");

The string is handled as plain text.
Output: <example>Italic</example>
It does this by adding an XText node.

2. Give it Another XElement

var child = new XElement("em", "Italic");
var el = new XElement("example", child);

It is treated as a nested part.
Output: <example>Italic</example>
This is right for the structure and lets you nest things.

3. Use .Add()

You can build things up step by step:

var parent = new XElement("content");
parent.Add(new XElement("b", "Bold Section"));

This way gives you more direct control over child node types and their order.

How to Safely Put in Raw HTML or XML

To put raw HTML or structured XML into an element the right way, and to skip the automatic escaping, use one of these ways.

Way 1: Read Existing XML

If you already have an XML string that is well-formed, you can read it into an XElement:

string raw = "<a href='https://example.com'>Click Here</a>";
var parsed = XElement.Parse(raw); // turns into a real node
var wrapper = new XElement("content", parsed);

Way 2: Use a Child XElement

Make your node tree using code:

var link = new XElement("a", new XAttribute("href", "https://example.com"), "Visit");
var parent = new XElement("content", link);

This way is safe and clean, especially with user-made URLs or URLs that change.

Way 3: Use CDATA Sections

CDATA means “Character Data”. It lets you put raw blocks of content into XML without escaping them:

var rawHtml = "<script>alert('test')</script>";
var data = new XElement("htmlContent", new XCData(rawHtml));

Output:

<htmlContent><![CDATA[<script>alert('test')</script>]]></htmlContent>

This works well for:

HTML parts with lots of detail
JavaScript blocks
Preformatted content

But be aware of some problems.

CDATA Warnings and Limits

CDATA helps keep raw content inside XML without breaking its structure. But it does not fix every problem.

CDATA Good Points:

No auto-escaping of characters
Good for HTML, code, or scripts you put inside
Easy to read in editors

CDATA Bad Points:

Cannot have the string ]]> (you must escape or split it)
Some XML parsers remove CDATA blocks or shrink them
Not good for structured content where you need to read or check HTML tags

Also, it is not good to use CDATA when you need strong schema validation or when you work with strict parsers.

Comparing Value and Nested Content in XElement

Here is a table that sums up how different data types act:

Code Sample	Behavior	Encoding	Final Output
`XElement("tag", "<b>text</b>")`	Escaped text	✅ Yes	`<b>text</b>`
`XElement("tag", new XElement("b", "text"))`	Nested element	❌ No	`<b>text</b>`
`XElement("tag", XCDataInstance)`	CDATA block	❌ No	`<![CDATA[...]]>` block
`XElement.Parse(...)`	Structured XML	❌ No	Real XML nodes
`.Value = "<tag>"`	Escaped text	✅ Yes	`<tag>`

Knowing which constructor paths keep the structure, versus treating input as text, will help you not encode things by mistake.

XElement: How It Becomes a String and How It Looks

Serialization is when you turn objects into a format that you can save or send. For XElement, calling .ToString() is the most common way to do this:

var tag = new XElement("tag", "<raw>");
Console.WriteLine(tag.ToString());

Output:

<tag>&lt;raw&gt;</tag>

Do you want the output to look better? You can write to a file or stream using an XmlWriter. This writer has more features:

var writer = XmlWriter.Create("output.xml", new XmlWriterSettings { Indent = true });
element.Save(writer);

This way gives you more control over how things are formatted, escaped, and encoded.

Common Ways to Use XElement

➤ RSS Feeds:

Use XElement("description", new XCData(html)). Or, put in structured HTML tags safely with nested XElements.

➤ Email Templates:

Keep styling and references with CDATA blocks. Do this especially if you use CSS or JavaScript put inside.

➤ Working with Older Systems:

Do APIs expect XHTML? Use XElement.Parse() with hardcoded pieces. But check it to lessen the chance of injection problems.

➤ CMS + Portals:

Keep HTML content formatted while you wrap it in XML containers.

Best Ways to Use XElement and XML Serialization

Use XElement APIs Instead of Raw Strings: Make XML elements and attributes using code. This ensures they are correct.
Check When You Import/Export: Are you reading content from others or users? Run XML validation before you do.
Protect CDATA Blocks: Clean up dangerous parts. Avoid putting in ]]> to stop documents from being wrongly made.
Use XmlWriter for Output You Control: This gives better control over namespace prefixes, how things look, and encoding choices.
Do Not Use XCData Too Much: Only use it when you really need to and when content does not need to be nested.

How to Fix "Why Is This Escaped?" Problems

Here are steps to fix problems when your XML does not look right:

Print the raw output from .ToString() to check the escaping.
Look at the type of data you put into the XElement constructor—string or nested elements.
Test how the output looks in other programs (like browsers or feed readers).
Use XML Linters to check if it is well-formed.
Keep a record of inputs and outputs for changes.

When XML Is Not Enough

When things get too complex, especially with modern content like detailed text, CSS styles, or any HTML/XML, native XML might not work well. In those situations:

Think about using JSON for new APIs or services
Store detailed content outside and link to it
Use mixed messages: XML structure plus CDATA blocks or attachments
Use platforms like Markdown or HTML5 to show the content.

Last Thoughts: Know When to Encode

To use XElement encoding, XML serialization, and content changes well in the C# XElement API, you must understand what each method sees as content and how it is shown. You should now feel more sure about picking between: