C#讀取注釋的方法

　　友好的注釋能提高代碼的可讀性，幾乎所有的編程語言都支持注釋。

　　在C#中，注釋不是可執行代碼的一部分，因此注釋不會被編譯到程序集中去，但是我們可以提取注釋【右鍵項目】-【屬性】-【生成】-【輸出】-【Xml文檔文件】：

　　

　　如果勾選了輸出注釋，那么VS在沒有注釋的方法、類型、屬性等地方將會拋出警告，提醒添加注釋，而添加1591代碼可以取消這種無注釋警告。

　　一般時候，我們並不會在代碼中操作注釋，但是如果需要，我們可以從這個生成的xml文件中去獲取注釋，swagger也是這么做的。

　　首先，創建一個輔助類：　　

　　

    /// <summary>
    /// 注釋輔助類
    /// </summary>
    public class XmlCommentHelper
    {
        private static Regex RefTagPattern = new Regex(@"<(see|paramref) (name|cref)=""([TPF]{1}:)?(?<display>.+?)"" ?/>");
        private static Regex CodeTagPattern = new Regex(@"<c>(?<display>.+?)</c>");
        private static Regex ParaTagPattern = new Regex(@"<para>(?<display>.+?)</para>", RegexOptions.Singleline);

        List<XPathNavigator> navigators = new List<XPathNavigator>();

        /// <summary>
        /// 從當前dll文件中加載所有的xml文件
        /// </summary>
        public void LoadAll()
        {
            var files = Directory.GetFiles(Directory.GetCurrentDirectory());
            foreach (var file in files)
            {
                if (string.Equals(Path.GetExtension(file), ".xml", StringComparison.OrdinalIgnoreCase))
                {
                    Load(file);
                }
            }
        }
        /// <summary>
        /// 從xml中加載
        /// </summary>
        /// <param name="xmls"></param>
        public void LoadXml(params string[] xmls)
        {
            foreach (var xml in xmls)
            {
                Load(new MemoryStream(Encoding.UTF8.GetBytes(xml)));
            }
        }
        /// <summary>
        /// 從文件中加載
        /// </summary>
        /// <param name="xmlFiles"></param>
        public void Load(params string[] xmlFiles)
        {
            foreach (var xmlFile in xmlFiles)
            {
                var doc = new XPathDocument(xmlFile);
                navigators.Add(doc.CreateNavigator());
            }
        }
        /// <summary>
        /// 從流中加載
        /// </summary>
        /// <param name="streams"></param>
        public void Load(params Stream[] streams)
        {
            foreach (var stream in streams)
            {
                var doc = new XPathDocument(stream);
                navigators.Add(doc.CreateNavigator());
            }
        }

        /// <summary>
        /// 讀取類型中的注釋
        /// </summary>
        /// <param name="type">類型</param>
        /// <param name="xPath">注釋路徑</param>
        /// <param name="humanize">可讀性優化(比如：去掉xml標記)</param>
        /// <returns></returns>
        public string GetTypeComment(Type type, string xPath = "summary", bool humanize = true)
        {
            var typeMemberName = GetMemberNameForType(type);
            return GetComment(typeMemberName, xPath, humanize);
        }
        /// <summary>
        /// 讀取字段或者屬性的注釋
        /// </summary>
        /// <param name="fieldOrPropertyInfo">字段或者屬性</param>
        /// <param name="xPath">注釋路徑</param>
        /// <param name="humanize">可讀性優化(比如：去掉xml標記)</param>
        /// <returns></returns>
        public string GetFieldOrPropertyComment(MemberInfo fieldOrPropertyInfo, string xPath = "summary", bool humanize = true)
        {
            var fieldOrPropertyMemberName = GetMemberNameForFieldOrProperty(fieldOrPropertyInfo);
            return GetComment(fieldOrPropertyMemberName, xPath, humanize);
        }
        /// <summary>
        /// 讀取方法中的注釋
        /// </summary>
        /// <param name="methodInfo">方法</param>
        /// <param name="xPath">注釋路徑</param>
        /// <param name="humanize">可讀性優化(比如：去掉xml標記)</param>
        /// <returns></returns>
        public string GetMethodComment(MethodInfo methodInfo, string xPath = "summary", bool humanize = true)
        {
            var methodMemberName = GetMemberNameForMethod(methodInfo);
            return GetComment(methodMemberName, xPath, humanize);
        }
        /// <summary>
        /// 讀取方法中的返回值注釋
        /// </summary>
        /// <param name="methodInfo">方法</param>
        /// <param name="humanize">可讀性優化(比如：去掉xml標記)</param>
        /// <returns></returns>
        public string GetMethodReturnComment(MethodInfo methodInfo, bool humanize = true)
        {
            return GetMethodComment(methodInfo, "returns", humanize);
        }
        /// <summary>
        /// 讀取參數的注釋
        /// </summary>
        /// <param name="parameterInfo">參數</param>
        /// <param name="humanize">可讀性優化(比如：去掉xml標記)</param>
        /// <returns></returns>
        public string GetParameterComment(ParameterInfo parameterInfo, bool humanize = true)
        {
            if (!(parameterInfo.Member is MethodInfo methodInfo)) return string.Empty;

            var methodMemberName = GetMemberNameForMethod(methodInfo);
            return GetComment(methodMemberName, $"param[@name='{parameterInfo.Name}']", humanize);
        }
        /// <summary>
        /// 讀取方法的所有參數的注釋
        /// </summary>
        /// <param name="methodInfo">方法</param>
        /// <param name="humanize">可讀性優化(比如：去掉xml標記)</param>
        /// <returns></returns>
        public Dictionary<string, string> GetParameterComments(MethodInfo methodInfo, bool humanize = true)
        {
            var parameterInfos = methodInfo.GetParameters();
            Dictionary<string, string> dict = new Dictionary<string, string>();
            foreach (var parameterInfo in parameterInfos)
            {
                dict[parameterInfo.Name] = GetParameterComment(parameterInfo, humanize);
            }
            return dict;
        }
        /// <summary>
        /// 讀取指定名稱節點的注釋
        /// </summary>
        /// <param name="name">節點名稱</param>
        /// <param name="xPath">注釋路徑</param>
        /// <param name="humanize">可讀性優化(比如：去掉xml標記)</param>
        /// <returns></returns>
        public string GetComment(string name, string xPath, bool humanize = true)
        {
            foreach (var _xmlNavigator in navigators)
            {
                var typeSummaryNode = _xmlNavigator.SelectSingleNode($"/doc/members/member[@name='{name}']/{xPath.Trim('/', '\\')}");

                if (typeSummaryNode != null)
                {
                    return humanize ? Humanize(typeSummaryNode.InnerXml) : typeSummaryNode.InnerXml;
                }
            }

            return string.Empty;
        }
        /// <summary>
        /// 讀取指定節點的summary注釋
        /// </summary>
        /// <param name="name">節點名稱</param>
        /// <param name="humanize">可讀性優化(比如：去掉xml標記)</param>
        /// <returns></returns>
        public string GetSummary(string name, bool humanize = true)
        {
            return GetComment(name, "summary", humanize);
        }
        /// <summary>
        /// 讀取指定節點的example注釋
        /// </summary>
        /// <param name="name">節點名稱</param>
        /// <param name="humanize">可讀性優化(比如：去掉xml標記)</param>
        /// <returns></returns>
        public string GetExample(string name, bool humanize = true)
        {
            return GetComment(name, "example", humanize);
        }
        /// <summary>
        /// 獲取方法的節點名稱
        /// </summary>
        /// <param name="method"></param>
        /// <returns></returns>
        public string GetMemberNameForMethod(MethodInfo method)
        {
            var builder = new StringBuilder("M:");

            builder.Append(QualifiedNameFor(method.DeclaringType));
            builder.Append($".{method.Name}");

            var parameters = method.GetParameters();
            if (parameters.Any())
            {
                var parametersNames = parameters.Select(p =>
                {
                    return p.ParameterType.IsGenericParameter
                        ? $"`{p.ParameterType.GenericParameterPosition}"
                        : QualifiedNameFor(p.ParameterType, expandGenericArgs: true);
                });
                builder.Append($"({string.Join(",", parametersNames)})");
            }

            return builder.ToString();
        }
        /// <summary>
        /// 獲取類型的節點名稱
        /// </summary>
        /// <param name="type"></param>
        /// <returns></returns>
        public string GetMemberNameForType(Type type)
        {
            var builder = new StringBuilder("T:");
            builder.Append(QualifiedNameFor(type));

            return builder.ToString();
        }
        /// <summary>
        /// 獲取字段或者屬性的節點名稱
        /// </summary>
        /// <param name="fieldOrPropertyInfo"></param>
        /// <returns></returns>
        public string GetMemberNameForFieldOrProperty(MemberInfo fieldOrPropertyInfo)
        {
            var builder = new StringBuilder(((fieldOrPropertyInfo.MemberType & MemberTypes.Field) != 0) ? "F:" : "P:");
            builder.Append(QualifiedNameFor(fieldOrPropertyInfo.DeclaringType));
            builder.Append($".{fieldOrPropertyInfo.Name}");

            return builder.ToString();
        }

        private string QualifiedNameFor(Type type, bool expandGenericArgs = false)
        {
            if (type.IsArray)
                return $"{QualifiedNameFor(type.GetElementType(), expandGenericArgs)}[]";

            var builder = new StringBuilder();

            if (!string.IsNullOrEmpty(type.Namespace))
                builder.Append($"{type.Namespace}.");

            if (type.IsNested)
            {
                builder.Append($"{string.Join(".", GetNestedTypeNames(type))}.");
            }

            if (type.IsConstructedGenericType && expandGenericArgs)
            {
                var nameSansGenericArgs = type.Name.Split('`').First();
                builder.Append(nameSansGenericArgs);

                var genericArgsNames = type.GetGenericArguments().Select(t =>
                {
                    return t.IsGenericParameter
                        ? $"`{t.GenericParameterPosition}"
                        : QualifiedNameFor(t, true);
                });

                builder.Append($"{{{string.Join(",", genericArgsNames)}}}");
            }
            else
            {
                builder.Append(type.Name);
            }

            return builder.ToString();
        }
        private IEnumerable<string> GetNestedTypeNames(Type type)
        {
            if (!type.IsNested || type.DeclaringType == null) yield break;

            foreach (var nestedTypeName in GetNestedTypeNames(type.DeclaringType))
            {
                yield return nestedTypeName;
            }

            yield return type.DeclaringType.Name;
        }
        private string Humanize(string text)
        {
            if (text == null)
                throw new ArgumentNullException("text");

            //Call DecodeXml at last to avoid entities like &lt and &gt to break valid xml       
            text = NormalizeIndentation(text);
            text = HumanizeRefTags(text);
            text = HumanizeCodeTags(text);
            text = HumanizeParaTags(text);
            text = DecodeXml(text);
            return text;
        }
        private string NormalizeIndentation(string text)
        {
            string[] lines = text.Split('\n');
            string padding = GetCommonLeadingWhitespace(lines);

            int padLen = padding == null ? 0 : padding.Length;

            // remove leading padding from each line
            for (int i = 0, l = lines.Length; i < l; ++i)
            {
                string line = lines[i].TrimEnd('\r'); // remove trailing '\r'

                if (padLen != 0 && line.Length >= padLen && line.Substring(0, padLen) == padding)
                    line = line.Substring(padLen);

                lines[i] = line;
            }

            // remove leading empty lines, but not all leading padding
            // remove all trailing whitespace, regardless
            return string.Join("\r\n", lines.SkipWhile(x => string.IsNullOrWhiteSpace(x))).TrimEnd();
        }
        private string GetCommonLeadingWhitespace(string[] lines)
        {
            if (null == lines)
                throw new ArgumentException("lines");

            if (lines.Length == 0)
                return null;

            string[] nonEmptyLines = lines
                .Where(x => !string.IsNullOrWhiteSpace(x))
                .ToArray();

            if (nonEmptyLines.Length < 1)
                return null;

            int padLen = 0;

            // use the first line as a seed, and see what is shared over all nonEmptyLines
            string seed = nonEmptyLines[0];
            for (int i = 0, l = seed.Length; i < l; ++i)
            {
                if (!char.IsWhiteSpace(seed, i))
                    break;

                if (nonEmptyLines.Any(line => line[i] != seed[i]))
                    break;

                ++padLen;
            }

            if (padLen > 0)
                return seed.Substring(0, padLen);

            return null;
        }
        private string HumanizeRefTags(string text)
        {
            return RefTagPattern.Replace(text, (match) => match.Groups["display"].Value);
        }
        private string HumanizeCodeTags(string text)
        {
            return CodeTagPattern.Replace(text, (match) => "{" + match.Groups["display"].Value + "}");
        }
        private string HumanizeParaTags(string text)
        {
            return ParaTagPattern.Replace(text, (match) => "<br>" + match.Groups["display"].Value);
        }
        private string DecodeXml(string text)
        {
            return System.Net.WebUtility.HtmlDecode(text);
        }
    }

　　比如有下面的類注釋：　　

    /// <summary>
    /// MyClass注釋
    /// </summary>
    public class MyClass
    {
        /// <summary>
        /// FieldName1字段注釋
        /// </summary>
        int FieldName1;
        /// <summary>
        /// FieldName2字段注釋
        /// </summary>
        string FieldName2;

        /// <summary>
        /// PropertyName1屬性注釋
        /// </summary>
        public int PropertyName1 { get; set; }
        /// <summary>
        /// PropertyName2屬性注釋
        /// </summary>
        public string PropertyName2 { get; set; }

        /// <summary>
        /// MyMethod方法注釋
        /// </summary>
        /// <param name="intParameter">整型參數<see cref="int"/></param>
        /// <param name="stringParameter">字符串類型參數<see cref="string"/></param>
        /// <returns>返回值類型是字符串</returns>
        public string MyMethod(int intParameter, string stringParameter)
        {
            return string.Empty;
        }
    }

　　首先，安裝上面的操作，將注釋輸出到xml文檔中，然后使用這個XmlCommentHelper類來加載讀取注釋：　　

    static void Main(string[] args)
    {
        var xmlCommentHelper = new XmlCommentHelper();
        xmlCommentHelper.LoadAll();

        Type type = typeof(MyClass);
        var typeComment = xmlCommentHelper.GetTypeComment(type);
        Console.WriteLine($"{type.Name}的注釋：{typeComment}");

        var fields = type.GetFields(bindingAttr: System.Reflection.BindingFlags.NonPublic);
        foreach (var field in fields)
        {
            var fieldComment = xmlCommentHelper.GetFieldOrPropertyComment(field);
            Console.WriteLine($"{field.Name}字段的注釋：{fieldComment}");
        }

        var properties = type.GetProperties();
        foreach (var property in properties)
        {
            var propertyComment = xmlCommentHelper.GetFieldOrPropertyComment(property);
            Console.WriteLine($"{property.Name}屬性的注釋：{propertyComment}");
        }

        var method = type.GetMethod(nameof(MyClass.MyMethod));
        var methodComment = xmlCommentHelper.GetMethodComment(method);
        Console.WriteLine($"{nameof(MyClass.MyMethod)}方法的注釋：{methodComment}");

        var dict = xmlCommentHelper.GetParameterComments(method);
        foreach (var pair in dict)
        {
            Console.WriteLine($"{nameof(MyClass.MyMethod)}方法的參數{pair.Key}注釋：{pair.Value}");
        }
    }

　　輸出結果：