I'm writing XML documentation for a couple of C# projects. I want to be able to parse the file that comes out into HTML suitable for posting on GitHub Pages. I've got a pretty good handle on the parsing process itself, but I need an idea of all the elements that might show up in documentation.
I thought that a DTD might be the best resource for this, does that exist? Or is this all completely free-form?
I realize there are a few tools that already exist to do this, but I want finer control over the process and honestly it's good practice anyway.
XML validation is a product of some sort of application. The documentation comments in C# are just XML. It is the application that you parse/process the comments with that determines if there are any rules for what elements are allowed. There are multiple applications that can convert XML documentation comments into documentation, and you could even build your own if needed.
As mentioned, MSDN has a list of available elements. These are standardized across most parsers. If you need to add additional elements it is fine if you have a parser that can handle them. You could even add an XSD or DTD if you wanted for that application, if supported.
Related
I'm working on parsing out the XML file that is generated when you pass /doc as a compiler option. We had previously been using VSDocman to handle the parsing and documentation website generation, along with custom topics. We ultimately didn't like the web site generated by VSDocman though and want to do something more robust with MVC.
It's easy enough to parse the XML file, but I'd like to also add custom topics like I can in VSDocman to the XML file. Is that not possible with the built in documentation support in Visual Studio? Will I have to create a custom XML file that manages all of that, writing it manually (or building a custom tool to generate it) and parsing it during my /doc parsing?
Microsoft itself does not define a standard format for extra documentation. Thus, you have to decide what tool to use next and then use the format it supports.
Besides, XML is so flexible that you can try to transform it from one format to another, so I assume it is not a big deal.
For the purposes of unit testing, I would like to validate that two xml files contain the same data, but ignore the order of the elements or attributes.
I am currently using MbUnit.Framework.Xml.XmlAssert.XmlEquals, and it seems to have a few options but I can't find any documentation. It returns false if the element order is different.
This is a c# project.
Try using Microsoft's XML Diff and Patch Tool.
In addition to the XML Diff and Patch API, you may be interested in taking a look at the Windows Forms code sample that implements the tool - XML Diff and Patch GUI Tool (The API's dll is included in this download).
A while back I was happily using xmlunit for these kinds of problems, http://xmlunit.sourceforge.net/, not sure about the .net side of it, or if it is still kept uptodate &c.
I've always assumed XML documents are a convenient way to store information. Now I've found in XML a good way to "instruct" my application. Delicous.
My problem is integrate the XML parsing in application classes. I'm using C# System.Xml interface, I think it's good and portable (right?).
Is there any standard interface which defines methods to organize recursion on xml tags, or methods to implement common xml implementations (maybe in a base class)?
Initially I can think to write an interface which defines
void Read(XmlReader xml);
void Write(XmlREader xml);
What what about nested tags, common tags and so on...
P.S.: I don't think to implement this using LINQ, except in the case it's supported also in Mono (how to determine this)?
Thank you very much! :)
I think you might be looking for Serialization, this is a beginners Tutorial on Serialization
As Binary Worrier mentioned, XML serialization is a simple and efficient option. You can also use Linq to XML, which is supported in Mono since version 2.0 (released in october 2008)
Using xml to "instruct" your app seems backwards to me. I'd be more inclined to use an IronPython script if that was my aim. Xml, normally, is intended to serialize data. Sure you can write a language via xml, but ultimately it is fighting the system. You would also massively struggle to invoke methods (easy enough to set properties etc via XmlSerializer, though).
Here's A 3 minute guide to embedding IronPython in a C# application to show what might, IMO, be a better way to "instruct" a C# application via a separate script file.
What are the best functions, practices, and/or techniques to read/write XML with C#/.NET?
If you are working with .NET 3.5, LINQ to XML is certainly a very good way to interact with XML.
MSDN Link
There are classes to read XML:
XmlDocument is slow and memory-intensive: it parses the XML and loads it into an in-RAM DOM, which is good if you want to edit it.
XmlReader is less memory-intensive: it scans the XML from front to back, never needing to keep all of it in RAM at once.
Similarly, for writing you can construct an XmlDocument and then save it, or use an XmlWriter.
After I wrote the above, there's now a new set of APIs which are easier to use: i.e. for example the XDocument and XElement classes.
By far the simplest method I've found for dealing with XML in C# is to use the XML Serialization tools. For example: http://www.dotnetjohn.com/articles.aspx?articleid=173.
Essentially, you can define C# classes that match your XML file (in fact, you can have them created for you if you have an XML definition file) and then you simply initialize instances of those classes directly from the XML file. Once you have them as instances, you can manipulate them as you wish and rewrite them back into XML files just as easily.
In a performance critical application XmlReader/XmlWriter are a good choice (see here) for the sake of simplicity which is offered by Linq to XML and XmlDocument.
I've found the MvpXml project very useful in past scenarios where performance is a consideration. There's a wealth of knowledge about good practice within their project pages: http://www.codeplex.com/MVPXML
I'm considering Altova MapForce (or something similar) to produce either XSLT and/or a Java or C# class to do the translation. Today, we pull data right out of the database and manually build an XML string that we post to a webservice.
Should it be db -> (internal)XML -> XSLT -> (External)XML? What do you folks do out there in the wide world?
I would use one of the out-of-the-box XML serialization classes to do your internal XML generation, and then use XSLT to transform to the external XML. You might generate a schema as well to enforce that the translation code (whatever will drive your XSLT translation) continues to get the XML it is expecting for translation in case of changes to the object breaks things.
There are a number of XSLT editors on the market that will help you do the mappings, but I prefer to just use a regular XML editor.
ya, I think you're heading down the right path with MapForce. If you don't want to write code to preform the actual transformation, MapForce can do that for you also. THis may be better long term b/c it's less code to maintain.
Steer clear of more expensive options (e.g. BizTalk) unless you really need to B2B integration and orchestration.
What database are you using? Oracle has some nice XML mapping tools. There are some Java binding tools (one is http://java.sun.com/developer/technicalArticles/WebServices/jaxb). However, if you have the luxory consider using Ruby which has nice built-in "to_xml" methods.
Tip #1: Avoid all use of XSLT.
The tool support sucks. The resulting solution will be unmaintainable.
Tip #2: Eliminate all unnecessary steps.
Just translate your resultset (assuming you're using JDBC or equiv) to the outbound XML.
Tip #3: Assume all use of a schema-based tool to be incorrect and plan accordingly.
In other words, just fake it. If you have to squirt out some mutant SOAP (redundant, I know) payload just mock up a working SOAP message and then turn it into a template. Velocity doesn't suck.
That said, the best/correct answer, is to use an "XML Writer" style solution. There's a few.
The best is the one I wrote, LOX (Lightweight Objects for XML).
The public API uses a Builder design pattern. Due to some magic under the hood, it's impossible to create malformed XML.
Please note: If XML is the answer, you've asked the wrong question. Sometimes, we're forced against our will to use it in some way. When that happens, it's crucial to use tools which minimize developer effort and improve code maintainability.