How to create XML comments using C# and [Serialize]

Question

0.00/5 (No votes)

See more:

Hi, I am serializing a class in C# following this example

http://msdn.microsoft.com/en-us/library/2baksw0z(v=vs.110).aspx

Here is my test class


[Serializable]
public class Test
{
   [XmlElement("SomeXmlElementName")]
   public int Something { get; set; }
}



This works well and creates and when the class content is serialized it creates a file with a node named SomeXmlElementName with the right value.

What I would also like is to include a comment in the XML file and I am looking for some .Net attribute I can use to decorate the method to include the comment. The code below does not compile, but it demonstrates the sort of thing I am after

[Serializable]
public class Test
{
   [XmlElement("SomeXmlElementName"), XmlComment("Some comment to include in the XML file when created"]
   public int Something { get; set; }
}


Does something like this exist at all?

Thank you

Posted 4-Feb-14 7:53am

Jon Joeney

Updated 21-Oct-17 14:34pm

Add a Solution

Comments

Sergey Alexandrovich Kryukov 4-Feb-14 14:43pm

I wonder why? Normally, serialization XML should not use any comments. Why?
—SA

Jon Joeney 5-Feb-14 13:03pm

Well I am serialising the XML for use by another application that defines the structure using an XML Schema that I cannot change. I want to add the time generated and other stuff into the XML in comments and so that is still schema valid but have a handle on when the file was created.

Sergey Alexandrovich Kryukov 5-Feb-14 13:14pm

What a second... are you saying there is a schema which defines some comments? Maybe it even supposed to carry some information in comments? "Extending" the schema you cannot extend?
Anyway, I would not do such things and would advise you to rethink it. Way too dirty approach, unsafe, etc...
—SA

rhyous 16-Jul-15 13:18pm

Xml can be displayed on web pages with an XSLT very similar to HTML. Comments might need to be displayed.

Also, an XML might need to be output with a EULA in comments.

Sergey Alexandrovich Kryukov 16-Jul-15 13:27pm

The only right approach is to ignore comments. They should only be used for their intended purpose. Of course, an XML parser can read comments, but this is not for anything like displaying them or interpreting in any way. Why not following the design of XML?
—SA

rhyous 6-Aug-15 17:36pm

I disagree. We are not talking about reading an Xml and ignoring comments. We are talking about writing and Xml and adding comments to the written Xml.

C# is not Xml. Serialization is the ability to generate an Xml file from a C# object. Should a C# object allow for adding comments? I think it should. Comments in Xml are part of the spec for Xml.
http://www.w3.org/TR/REC-xml/#sec-comments

The default Serializer in C# doesn't support adding a comment to an Xml file despite the fact that comments are valid and supported in the Xml spec.

The spec says: They are not part of the document's character data; an XML processor may, but need not, make it possible for an application to retrieve the text of comments.

The verbage is very clear that it is not required for a processor to support comments, but it may. In this case, we aren't even talking about reading the comment, we are talking about writing an Xml with comments.

I didn't see anything about an Xml generator or serializer, but one can assume if comments were not meant to be written, they wouldn't have added them to the spec. Whether we hand craft and xml or generate an Xml, comments are important.

I have had requests to add comments in every Xml I have ever serialized. Either from software testers, tech support, or Eula inclusion reasons.

To accommodate such requests, I have to roll my own serializer.

Sergey Alexandrovich Kryukov 6-Aug-15 18:22pm

Your point is taken. If this is two-way process, you have to preserve comments.
—SA

Andreas Gieriet 4-Feb-14 15:19pm

What are you trying to achieve? Comments are a compile-time construct, serializatin is a runtime concept. You have no source code comments at run-time.
What you might do is add a property named AdditionalRuntimeInfo or alike and pass some string or other agreed data construct.
Cheers
Andi

Jon Joeney 5-Feb-14 13:04pm

The code I want I have found here, it looks very simple, and it works
http://stackoverflow.com/questions/7385921/how-to-write-a-comment-to-an-xml-file-when-using-the-xmlserializer

Andreas Gieriet 5-Feb-14 14:53pm

Well, this is tempting, but the example is crap: if the name of the property needs such a comment, change the name of the property accordingly, e.g. make it ApplicationVersion instead of only Version and the commenting becomes obsolete. If timestamps are relevant information to be transported from A to B, add them to the schema.
I know, reality doesn not always allow to control the whole chain. But if it is under your control, I'd say the comment approach is a hack.
Cheers
Andi

Jon Joeney 6-Feb-14 4:20am

The XML Schema is defined by a third party company. I can't go changing it willy nilly and still expect vendor support

Andreas Gieriet 6-Feb-14 4:48am

I still wonder why you want to have that comments in the XML. Why is it not sufficient to have it as code comment in the class only. Serialized data are hardly read by humans, right? I.e. what is really the purpose of this? Who is supposed to read this comment in the serialized data? You found a way to do it, fine. If it is really useful is another question. You decided for yourself that it is ;-)
Cheers
Andi

rhyous 8-Apr-16 0:40am

Quote: Serialized data are hardly read by humans, right?

Wrong. Xml is read by humans. Hence the need for comments.

Your argument is flawed anyway.

Hardly Ever != never.

By your logic, as most code is only read by one human (so hardly ever), we should remove the comment feature in code. The comments are stripped out when it compiles anyway, right?

Quote: what is really the purpose of this? Who is supposed to read this comment in the serialized data?

I have already answered your question above when I said:

I have had requests to add comments in every Xml I have ever serialized. Either from software testers, tech support, or Eula inclusion reasons.

Do you grasp how many things Xml is used for? It isn't just for code to code.

How often have you opened an xml file (web.config, app.config) in Visual Studio an not seen some default comments?

It is a markup language and is used for many reasons, so many that we as developers couldn't ever list or comprehend all of them. In many of these uses, Xml is often viewed by a human and as such, need comments.

Andreas Gieriet 8-Apr-16 16:30pm

Hm, I wonder why you cook this up after more than two years of the original post...
Be assured that I see many uses of XML in daily work.
In my universe, however, I see the *serialization* feature as a means to transport objects in *some* format over process boundaries and to persist data in *some* format for later retrieval (not necessarily intended for humans to read). There are many serialization formats, one happens to be XML. E.g. a C++ compiler might serialize its objects from memory into an ELF file and the linker de-serializes the ELF files again and works internally with the de-serialized objects to link them.
If I want an XML file that is read by humans, then I want to control far more than just adding comments, e.g. also indentation etc.
In my eyes, *serialization* in its narrower sense is not the tool to create nicely formatted and nicely commented files. So, my point is, if you want to have control that goes beyond the basic serialization, you might need to invent your own (de-)serializer.
BTW: You seem to get me wrong in saying I don't esteem the value of comments.
Regards
Andi

1 solution

Add a Solution

Add your solution here

Treat my content as plain text, not as HTML

Preview 0

…

Existing Members

Sign in to your account

...or Join us

Download, Vote, Comment, Publish.

Your Email
Password
Forgot your password?

Your Email
This email is in use. Do you need your password?
Optional Password

I have read and agree to the Terms of Service and Privacy Policy
Please subscribe me to the CodeProject newsletters

When answering a question please:

Read the question carefully.
Understand that English isn't everyone's first language so be lenient of bad spelling and grammar.
If a question is poorly phrased then either ask for clarification, ignore it, or edit the question and fix the problem. Insults are not welcome.
Don't tell someone to read the manual. Chances are they have and don't get it. Provide an answer or move on to the next question.

Let's work to help developers, not make them feel stupid.

This content, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Andreas Gieriet · Answer 1 · 2014-02-04T09:34:00

Solution 1

See my comment on your question.
If you want to write arbitrary XML code, you might have a look at XMLWriter Tutorial[^] and Writing XML with the XmlWriter[^] as well as XML Document Object Model (DOM)[^].
Cheers
Andi

Posted 4-Feb-14 9:34am

Andreas Gieriet

Comments

Sergey Alexandrovich Kryukov 5-Feb-14 13:22pm

I don't see how can it solve OP's problem, where the intervention is XML serialization is needed. Please see our comments to the question. My response was to give up this as a bad idea; and I cannot suggest anything in replacement; I could probably do it if I knew more about the big picture (writing some other files/streams in parallel, whatever). In the past, I already faced with the vague "requirements" to support some informational extensions to data in comment and denied to do it. There are such things, not doing them is more important then any features...
—SA

Andreas Gieriet 5-Feb-14 14:59pm

I see your point. But I'm not that strict as you are. The OP found another solution that solves his problem, even I consider it a hack if he has the whole chain under his control.
Cheers
Andi

Sergey Alexandrovich Kryukov 5-Feb-14 15:19pm

This is not just about strictness. My first point was: I don't see how your solution could help. OP is not using a stand-along XML generation, but serialization where you don't directly control the XML output. Can you see the point?
—SA

Andreas Gieriet 6-Feb-14 4:03am

See my sentence: "If you want to write **arbitrary** XML code". It is not clear to me if the OP's use of the built-in serializing support is what is adequate for his problem. That's why I write "if you want to write **arbitrary** XML code...". We seem to read and interprete the question in a different way... ;-)
Cheers
Andi

Sergey Alexandrovich Kryukov 6-Feb-14 10:59am

I think OP needs built-in serializing support; and this is the only real problem. If it was just writing some comments somewhere, it would not be a problem at all.
—SA