你的位置:首页 > ASP.net教程

[ASP.net教程]我的设计接口总结以及生成帮助文档


  前言:在工作发现接口至关重要,特别需要把接口的注释写清楚,能调用的同事知道这个接口是干嘛用的,要传递什么参数等,在这里我做了一个简单的接口并生成帮助帮助,供大家相互学习,有好的可以提出来我继续改进。

第一步:建立一个用户接口(明确这个接口的作用)

按照Add,Delete,Update,Get模式来定义接口的方法(我个人觉得尽可能的重载)

第二步:方法中写出尽可能详尽的注释

按照方法实现的功能,参数意思,异常,备注,返回值等来写

第三步:接口中如果出现参数为类型的时候千万不要用1,2这样的数值代替尽可能用枚举

为什么用枚举:因为在实际项目中可能做到最后的时候自己都不知道1代表什么2代表什么,通过枚举就能解决这些问题,而且枚举扩展性也很好

现在我们看一下我写的接口

 1 /// <summary> 2   /// 关于用户信息的操作 3   /// </summary> 4   public interface IUser 5   { 6     /// <summary> 7     /// 添加用户信息 8     /// </summary> 9     /// <param name="userInfo">用户实体</param>10     /// <exception cref="ArgumentNullException">userInfo为null</exception>11     /// <exception cref="ArgumentException">userInfo.Id为空字符串</exception>    12     /// <exception cref="ArgumentException">userInfo.UserName为空字符串</exception>13     /// <exception cref="ArgumentException">userInfo.PassWord为空字符串</exception>14     /// <exception cref="Exception">其他未知异常</exception>15     /// <returns>true:添加成功 false:添加失败</returns>16     bool Add(UserInfo userInfo);17 18     /// <summary>19     /// 根据用户名删除用户20     /// </summary>21     /// <param name="userName">用户名</param>22     /// <exception cref="ArgumentException">userName为空字符串</exception>23     /// <exception cref="Exception">其他未知异常</exception>24     /// <returns>true:删除成功 false:删除失败</returns>25     bool Delete(string userName);26 27     /// <summary>28     /// 根据用户名批量删除用户29     /// </summary>30     /// <param name="userNames">用户名(可以单个也可以多个)</param>31     /// <exception cref="ArgumentNullException">userNames为null</exception>32     /// <exception cref="ArgumentException">userNames不是有效参数</exception>33     /// <exception cref="Exception">其他未知异常</exception>34     ///<remarks>加入事物,如果其中一条未能删除成功,所有数据进行回滚</remarks>35     /// <returns>true:删除成功 false:删除失败</returns>36     bool Delete(IList<string> userNames);37 38     /// <summary>39     /// 更新用户信息40     /// </summary>41     /// <exception cref="ArgumentNullException">userInfo为null</exception>42     /// <exception cref="ArgumentException">userInfo.UserName为空字符串</exception>  43     /// <exception cref="Exception">其他未知异常</exception>44     /// <returns>true:更新成功 false:更新失败</returns>45     bool Update(UserInfo userInfo);46 47     /// <summary>48     /// 根据用户名获取用户信息49     /// </summary>50     /// <exception cref="ArgumentException">userName为空字符串</exception>51     /// <exception cref="Exception">其他未知异常</exception>52     /// <returns>返回一条用户信息可为null</returns>53     UserInfo Get(string userName);54 55     /// <summary>56     /// 根据用户名获取批量用户信息57     /// </summary>58     /// <param name="userNames">用户名(可以单个也可以多个)</param>    59     /// <exception cref="ArgumentNullException">userNames为null</exception>60     /// <exception cref="ArgumentException">userNames不是有效参数</exception>61     /// <exception cref="Exception">其他未知异常</exception>62     /// <remarks>如果返回结果为空则返回一条没有任何用户的结果集</remarks>63     /// <returns>获取用户集</returns>64     IList<UserInfo> Get(IList<string> userNames);65 66     /// <summary>67     /// 根据职称类型获取用户信息68     /// </summary>69     /// <param name="professional"></param>70     /// <exception cref="ArgumentOutOfRangeException">professional枚举不在范围内</exception>  71     /// <exception cref="Exception">其他未知异常</exception>72     /// <returns>获取用户集</returns>73     IList<UserInfo> Get(UserEnum.ProfessionalType professional);74   }

用户接口

第四步:实现这个接口

因为项目一上线错误出现以后就很难发现,所以我们一定要加入日志系统,所以在项目中我加入了抛异常,然后通过日志就知道问题出现在哪里(没有实现功能)

 1   /// <summary> 2   /// 实现用户相关操作 3   /// </summary> 4   public class User:IUser { 5  6     public bool Add(UserInfo userInfo) 7     { 8       try 9       { 10         if (userInfo == null) 11           throw new ArgumentNullException("userInfo"); 12         if (string.IsNullOrEmpty(userInfo.Id)) 13           throw new ArgumentException("userInfo.Id无效"); 14         if (string.IsNullOrEmpty(userInfo.UserName)) 15           throw new ArgumentException("userInfo.UserName无效"); 16         if (string.IsNullOrEmpty(userInfo.PassWord)) 17           throw new ArgumentException("userInfo.PassWord无效"); 18         return false; 19       } 20       catch 21       { 22         throw new Exception("其他未知异常"); 23       } 24     } 25  26     public bool Delete(string userName) 27     { 28       try 29       { 30         if (string.IsNullOrEmpty(userName)) 31           throw new ArgumentException("UserName无效"); 32         return false; 33       } 34       catch 35       { 36         throw new Exception("其他未知异常"); 37       } 38     } 39  40     public bool Delete(IList<string> userNames) 41     { 42       try 43       { 44         if (userNames == null) 45           throw new ArgumentNullException("userNames"); 46         if (!userNames.Any()) 47           throw new ArgumentException("userNames无效"); 48         return false; 49       } 50       catch  51       { 52         throw new Exception("其他未知异常");         53       }       54     } 55  56     public bool Update(UserInfo userInfo) 57     { 58       try 59       { 60         if (userInfo == null) 61           throw new ArgumentNullException("userInfo"); 62         if (string.IsNullOrEmpty(userInfo.UserName)) 63           throw new ArgumentException("userInfo.UserName无效"); 64         return false; 65       } 66       catch 67       { 68         throw new Exception("其他未知异常"); 69       } 70        71     } 72  73     public UserInfo Get(string userName) 74     { 75       try 76       { 77         if (string.IsNullOrEmpty(userName)) 78           throw new ArgumentException("UserName无效"); 79         return null; 80       } 81       catch { 82         throw new Exception("其他未知异常"); 83       }   84     } 85  86     public IList<UserInfo> Get(IList<string> userNames) 87     { 88       try 89       { 90         if (userNames == null) 91           throw new ArgumentNullException("userNames"); 92         if (!userNames.Any()) 93           throw new ArgumentException("userNames无效"); 94         return null; 95       } 96       catch { 97         throw new Exception("其他未知异常"); 98       }   99       100     }101 102     public IList<UserInfo> Get(UserEnum.ProfessionalType professional)103     {104       try105       {106         if (professional >= (UserEnum.ProfessionalType)4)107           throw new ArgumentOutOfRangeException("professional");108         return null;109       }110       catch {111         throw new Exception("其他未知异常");112       }  113       114     }115   }

实现接口

第五步:点击项目属性,找到生成勾选

第六步:下载一个Sandcastle Help File Builder 然后安装,安装成功以后,找到Sandcastle Help File Builder新建一个项目如下图

 

第七步:找到生成的dll和

第八步:点击生成按钮就可以生成一篇帮助文档了

生成帮助文档的效果

 

以上就是整个效果,大家有好的欢迎相互讨论。