Posts Tagged XML

C# Short Takes – 1 – XML Comments syntax for the cref attribute to a Generic Type Method


Introduction

For the last couple of blog posts I have been using the XML Documentation feature of C# and Sandcastle to generate chm help files. This has resulted in help for methods I have been developing being available in many parts of the Visual Studio environment. Enabling Intelescensecontext sensitive help have proved to quite useful, and is a good thing to include with the source code I have been posting on the blog.

Things have been going quite well with this approach, until I ran into a problem with the <see/> tag and the cref attribute. This tag generates a hyperlink within the output files, after Sandcastle has processed them. These generated hyperlinks to methods in the documentation were a feature I wanted to enable in a couple of places within the generated documentation.

The Problem

The situation which caused me a headache was trying to make pair of <see/> tag elements in the XML Documentation which referenced each of a pair of generic methods. The method signatures were:

public static IEnumerable<TSource> ToIEnumerable(TSource val)
public static IEnumerable<TSource> ToIEnumerable(TSource val1, TSource val2)

The Solution

After trying a number of things and searching on the net, I discovered the following on stackoverflowC#, XML-Doc: Refering to a generic type of a generic type in C# XML documentation?. The last answer in to the question is the one that gave me the way to solve the problem.

Simply, what is required is the xml escaping of the <>I n the function name. For a full (I would expect) list of the xml escape sequences see: List of XML and HTML character entity references.

The resulting references in the <see/> tag end up as:

        /// <see cref="ToIEnumerable&lt;TSource&gt;(TSource)"/> 
 /// <see cref="ToIEnumerable&lt;TSource&gt;(TSource, TSource)"/> 

Reasoning Why It Works

This makes a degree of logical sense when you consider the resulting context of this attribute. The C# compiler translates the XML Documentation into a XML file. Within an XML file an attribute, or element, which contains a < or > character needs to have those characters translated into XML escape equivalents. Thus, the target of the link will be in an XML escaped form, so also the reference to the target should comply with the same XML escape sequences.

A Visual Studio Handy Hint

There is a built-in paste function, Edit.PasteAlterernate. The following blog post ‘What is Paste Alternate?’ describes what this function does. If you use this to paste a function signature from a C# file into a html file, you get the prototype with xml escapes included, plus a bunch of html. Using this paste variant may prove useful when you need a quick way of generating xml escapes .

In my version of Visual Studio, this function was unbound to a keystroke combination. Yu can use the Tools -> Options menu items to get up the dialogue box that allows setting the keystroke combination. The keystroke combinations are set in the Environment -> Keyboard section of this dialogue box.

Conclusions

I trust that reading to here, you have found blog post useful, or that it has helped solves you XML Documentation problems.

Advertisements

, , , , , , , , ,

5 Comments

Corrigenda, Errata for the “Parallel Load CSV Using SqlBulkCopy”.


Introduction

This post is a “patch up” for the post I made yesterday. The “Parallel Load CSV Data Using SqlBulkCopy” blog posts has one omission.  I have forgotten to post one of the source files. The missing file was the SqlLoadResults class. This file is included below.

SqlLoadResults.cs:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace ParallelLoader
{
    /// <summary>
    /// Internal class, could be public of you wanted to pass the results out further
    /// </summary>
    internal class SqlLoadResults
    {
        #region FileName being loaded
        private string _fileName;
        public string FileName
        {
            get { return _fileName; }
            set { _fileName = value; }
        }
        #endregion
        #region Start Time
        private DateTime _startTime;
        public DateTime StartTime
        {
            get { return _startTime; }
            set { _startTime = value; }
        }
        #endregion
        #region End Time
        private DateTime _endTime;

        public DateTime EndTime
        {
            get { return _endTime; }
            set { _endTime = value; }
        }
        #endregion
        #region Rows Loaded
        private long _rowsLoaded;
        public long RowsLoaded
        {
            get { return _rowsLoaded; }
            set { _rowsLoaded = value; }
        }
        #endregion
        #region Rows Skipped
        private long _rowsSkipped;
        public long RowsSkipped
        {
            get { return _rowsSkipped; }
            set { _rowsSkipped = value; }
        }
        #endregion
        #region Elapsed time
        private long _elapsed;
        public long Elapsed
        {
            get { return _elapsed; }
            set { _elapsed = value; }
        }
        #endregion
        #region Rows Returned
        private long _rowsReturned;
        public long RowsReturned
        {
            get { return _rowsReturned; }
            set { _rowsReturned = value; }
        }
        #endregion
        /// <summary>
        /// Constructor for the class
        /// </summary>
        /// <param name="fileName">File which was loaded</param>
        /// <param name="start">Date Time the load started</param>
        /// <param name="end">Data Time the load ended
        /// rowsLoaded">Count of the rows loaded
        /// rowsSkipped">Count of rows skipped</param>
        /// <param name="elapsed">Clock ticks for the duration
        /// rowsReturned">Rows returned from the Data Reader</param>
        public SqlLoadResults(
            string fileName, DateTime start, DateTime end,
            long rowsLoaded, long rowsSkipped, long elapsed,
            long rowsReturned)
        {
            this._fileName = fileName;
            this._startTime = start;
            this._endTime = end;
            this._rowsLoaded = rowsLoaded;
            this._rowsSkipped = rowsSkipped;
            this._elapsed = elapsed;
            this._rowsReturned = rowsLoaded;
        }
    }
}

, , , , , , , ,

3 Comments

Visual Studio 2010 XML Schema Errors–xsd:import


Introduction

I’ve been looking at the option for a Publish and Subscribe web service model for a development project which is starting up at work. The research into the Publish and Subscribe model has had me looking at closely at the WS-BaseNotification specification.

To take a closer look at the standard, and what would be involved in implementing this for the project I downloaded the xml schemas (XSD’s) and web service definition language (WSDL) files for the standard. These files I then loaded up into Visual Studio 2010, and that’s when the “fun started”. These files were including (xsd:import) schemas from over the web, and Visual Studio was getting errors doing this. After a quick browse on the internet, it seemed like a common problem, with some complex solutions.  So, thinking there must be a better way, I started solving the problem, my way.

The Errors

Warning          2          Request for the permission of type ‘System.Net.WebPermission, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089’ failed.

Warning          3          Request for the permission of type ‘System.Security.Permissions.FileIOPermission, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089’ failed.

The “Fix”

I have found that the simplest way to solve these types of errors is to do the following:

  • Download the xsd file being referenced.
    • Paste the URL into IE and get the xsd file up in the browser.
    • Use File –> Save As. To save a copy of the xsd file into the Visual Studio project directory which you are keeping your source code in.
  • Add the xsd file you just downloaded to the project, and open the xml editor for that file.
  • Right click the editor tab for file you just downloaded, and select the “Copy Full Path”.
  • Then change the xsd:import from:
  <xsd:import namespace="http://www.w3.org/2005/08/addressing"
    schemaLocation="http://www.w3.org/2005/08/addressing/ws-addr.xsd"
  />

To

  <xsd:import namespace="http://www.w3.org/2005/08/addressing"
    schemaLocation="file://visual studio 2010/Projects/Project1/DummyShell/ws-addr.xsd"
  />

  • Tip: You have the file location in the clipboard from the “Copy Full Path”, so you only need to swap the \’s to /’s.
  • This makes the reference to a local copy of the schema file.

I’ve had situations where Visual Studio still gives the System.Security.Permissions.FileIOPermission exception/error after making this change. Restarting Visual Studio seemed to “clean out” the error and everything was fine after the restart.

Conclusion

Importing schemas into other schemas is a very powerful feature of xml schema language, but a real pain with Visual Studio. I’m not sure why things get so difficult, the schema cache which Visual Studio maintains seems to, in part, cause extra confusion. This approach ignores the schema cache altogether. Although I did “copy” the xml schema (xml.xsd) from the cache, into the project as well (one of the consequential dependencies required it).

, , , , , , ,

7 Comments

%d bloggers like this: