如何引导和创建.NET项目

本文概述

• 创建.NET项目
• 结构体
• 配置解决方案
• 配置项目
• .gitignore
• GitHub徽章
• 自动解决方案结构验证
• 总结

创建.NET项目

从头开始创建.NET项目就像使用Visual Studio向导一样简单。转到File => New Project, 或将New Project添加到现有解决方案。创建新项目后, 你可以立即开始编码。但是, 向导制作的默认项目设置对于专业团队来说几乎是不可接受的, 因为它们设置的质量门槛太低。此外, 没有向导会知道你在特定开发环境中需要执行的其他设置步骤。

在本文中, 我将引导你完成创建新项目后应启用的几个重要设置, 这对于最大程度地减少将来的技术负担非常重要。另外, 我们将回顾许多.NET开发人员在构造解决方案和新项目时采用的一些常见做法。即使你没有应用其中的一些想法, 也很高兴学习并大致了解大多数团队的工作。

结构体

对于复杂的项目, 拥有定义良好的结构至关重要。这可以改善新移民加入团队时的入职体验, 并在支持旧项目时使你的生活更轻松。良好结构有两个关键指标：

• 使用解决方案和项目文件夹
• 一致的命名

资料夹

解决方案文件夹, 有时也称为虚拟文件夹, 是对项目进行分组的非常方便的工具。在解决方案资源管理器视图中, 只需右键单击并选择添加=>新解决方案文件夹, 然后将任何现有项目拖放到该新文件夹中。这些文件夹未在文件系统中进行镜像, 从而使你的物理结构保持不变, 因此将项目从一个”解决方案文件夹”移至另一”解决方案”文件夹不会对其进行物理移动。

不需要编号前缀, 但这会使文件夹在”解决方案资源管理器”窗口中显示为有序。

通过利用分区的单个解决方案或多解决方案模型, Visual Studio可以同时使用多个解决方案。它们很少使用, 因此我将不在本文中介绍。

与解决方案文件夹不同, 项目文件夹与物理文件夹结构匹配, 因此作为真实文件夹保留在磁盘上。此外, 包含C＃代码的Project文件夹应与项目的名称空间匹配。这使得导航非常自然。你甚至可以启用ReSharper规则来警告此类不匹配。

命名

与命名相关的适用建议的规则很少：

• 使用CamelCase。
• 项目名称应与其输出程序集名称匹配。
• 包含自动化测试的项目应具有后缀.Tests。
• 所有项目名称都应具有公共前缀, 例如Company.Product。

几乎没有合理的规则。你应该根据常识(当然还有英语语法)自行决定何时应用它们：

• 当容器(项目或文件夹)包含相同类型的多个实例(例如Tests或System.Collections)时, 请使用复数形式的主题。
• 当整个容器包含有关单个实体的所有代码(例如System.Collections.ObjectModel`)时, 请使用单数形式。
• 对于简短缩写, 请像System.IO一样使用大写字母。
• 对于长缩写, 请使用Modules.Forex之类的CamelCase。

经验法则：缩写不应超过三个字符。

配置解决方案

配置解决方案就像提供环境所需的所有基础结构文件一样简单。尽管可以稍后添加其中的一些文件(例如CI集成文件), 但是一开始最好还是添加几个文件。

ReSharper设置

如果你是专业的.NET开发人员, 则很可能会使用ReSharper。 ReSharper在管理其设置方面非常灵活。作为团队负责人, 你可以创建和分发将由其他开发人员使用的”团队共享”设置。团队共享设置存储在扩展名为.DotSettings的文件中。如果文件名与Visual Studio解决方案名称匹配, 则ReSharper将自动选择这些设置：

MyCompany.MyProduct.sln
MyCompany.MyProduct.sln.DotSettings

因此, 如果最终要对整个团队应用某些设置, 则应从头开始创建此文件。一个很好的例子是使用(或不使用)var关键字的规则。你的”团队共享”设置文件只能有一个规则, 而其他则是开发人员的偏好。值得一提的是, 可以在每个项目级别设置ReSharper设置的方法相同, 因为你可能有一些无法修改的旧代码(例如, 更改为使用var关键字)。

如示例所示, 如果你正确命名了该文件, 则任何带有全新ReSharper设置的Visual Studio新实例都将自动选择该文件并执行规则。不要忘记将此文件提交到源控件。

StyleCop规则

与ReSharper设置相同, 你可以共享StyleCop设置。如果使用ReSharper, 则可能安装了集成插件, 该插件将利用ReSharper的StyleCop。但是, StyleCop将其设置独立存储在名为Settings.StyleCop的文件中。同样, 你可以将此文件与解决方案文件和项目文件一起使用。

如果你使用的是StyleCop, 请不要忘记运行StyleCop配置工具并禁用你不想执行的检查。默认情况下, 所有检查均已启用。将新设置保存到此文件并提交到源代码管理。

文字档案

如果你要构建公共产品并打算发布源代码, 请不要忘记也创建并提交以下文件：

README.md
LICENSE

我建议对README.md文件使用markdown格式, 因为它已成为工业标准, 并受到GitHub等公共源代码控制服务以及BitBucket(以前的Stash)等内部服务器的支持。

NuGet规格

如果要构建要在NuGet Gallery上分发的库, 则很可能需要创建程序包规范文件, 例如MyProject.nuspec。我更喜欢手动创建这些文件并将它们提交到源代码管理。程序包通常由你的持续集成(简称CI)工作发布, 但也可以随时通过控制台手动构建和发布程序包, 如下所示：

nuget.exe pack MyLibrary.nuspec

只是不要忘记在执行此命令之前增加软件包的版本。

CI专用文件

我们都使用不同的CI服务器, 并且它们都有不同的配置脚本和设置。我只想提到你可以考虑添加的一些常见补充：

• NUnit设置, 用于指定哪些程序集包含要在CI服务器上针对特定作业执行的测试。实际上, 所有测试都分为几类。在每个版本上都应该运行单元测试, 每晚执行性能测试, 而集成测试则基于每个版本执行。
• NCover设置, 该设置指定应分析哪些测试程序集以进行测试覆盖。
• SonarQube设置(确定软件指标)将被收集。
• 作业脚本, 例如NAnt, PowerShell或Windows批处理文件。

适当地进行引导的项目减少了未来的技术负担, 并使产品源代码具有可读性和专业性。

鸣叫

配置项目

项目文件(即.csproj或.vbpro)包含Visual Studio和MSBuild使用的所有设置。但是, 并不是所有的项目都可以从”项目属性”窗口中获得。若要在Visual Studio中手动编辑这些文件, 应执行以下操作：

• 在”解决方案资源管理器”视图中右键单击一个项目。
• 选择卸载项目。
• 再次右键单击以选择操作编辑xyz.csproj。
• 完成编辑。
• 再次右键单击该项目, 然后选择”重新加载项目”。

或者, 你可以在你喜欢的文本编辑器中打开一个项目文件, 对其进行编辑并保存。当你切换回Visual Studio窗口时, 将提示你重新加载更改的项目。

警告控制

构建高质量的软件要求你永远不要忽略构建警告。因此, 你应该启用最大警告级别, 并将所有警告视为错误。请注意, 你应该对拥有的所有构建配置执行此操作, 例如Debug和Release。最好的方法是将以下设置写入通用属性组：

<WarningLevel>4</WarningLevel>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>

并确保你在其他媒体资源组中没有相同的设置。否则, 它们将覆盖公共组中的相应属性。

FxCop

在每个版本上运行FxCop都是实际可行的。大多数团队更喜欢不时运行FxCop(通常在发布前), 以确保没有引入严重的错误。但是, 如果要对每个构建执行最终检查, 请添加以下选项：

<RunCodeAnalysis>true</RunCodeAnalysis>

请注意, FxCop与StyleCop一样, 具有其自己的设置, 可以将其放置在根文件夹中并添加到源控件中。在CI服务器上运行FxCop时, 可能会使用这些设置。

文献资料

这部分是关于XmlDoc的。如果要构建公共API, 则应创建和维护API文档。大多数开发人员从API开发(实际编码)开始, 并且在发布之前, 他们启用项目设置Build / XML文档文件。自然地, 一次又一次的重建会出现一堆错误, 因为每个丢失的XmlDoc都会导致生成错误。为了避免这种情况, 你应该在一开始就启用提及的选项。

如果你懒于编写适当的文档, 或者你不喜欢输入太多文本, 请尝试使该过程自动化的工具, 例如GhostDoc。

代码合同

Code Contracts是Microsoft Research的出色框架, 它允许你在代码中表达前置条件, 后置条件和对象不变式, 以进行运行时检查, 静态分析和文档编制。我在许多关键项目中都使用了此方法, 它起到了很大的作用, 因此我鼓励你尝试一下。

如果决定使用代码合同, 则在刚创建新项目时一开始就启用合同很重要。在开发过程中可以添加合同, 但是需要对许多类进行更改, 以使联系人彼此匹配。因此, 不要忘记启用所有必需的设置(至少要启用CodeContractsEnableRuntimeChecking), 并确保这些设置出现在公共属性组中。

StyleCop执法

之前, 我们讨论了StyleCop配置的开发时间。但是, 当你的项目在CI服务器上构建时, ReSharper在此处不起作用, 因此我们应该启用StyleCop验证以与MSBuild一起运行。

这通常是通过手动修改项目文件来完成的。你需要在Visual Studio中卸载项目, 编辑项目文件, 然后再将项目加载回：

<PropertyGroup>
   <!— add this to the common property group (common to Debug/Release/etc) —>
   <StyleCopTreatErrorsAsWarnings>false</StyleCopTreatErrorsAsWarnings>
</PropertyGroup>

<!— add this Import in the very bottom —>
<Import Project="$(ProgramFiles)\MSBuild\Microsoft\StyleCop\v4.3\Microsoft.StyleCop.targets">

设置StyleCopTreatErrorsAsWarnings将按照其说明进行操作：它将在任何违反StyleCop规则的情况下破坏你的构建。 MSBuild需使用import元素才能将StyleCop任务添加到构建链中。

你可能已经注意到程序文件的路径。因为开发人员可能安装了不同的StyleCop版本, 所以某些团队更喜欢在源代码控制下保留同一StyleCop安装的私有副本。在这种情况下, 路径将是相对的。由于你无需在本地安装StyleCop, 这也使CI计算机的安装更加容易。

AssemblyInfo

由Visual Studio向导创建的每个.NET项目都将自动填充AssemblyInfo.cs文件(请参阅”属性”子文件夹), 该文件包含一些Assembly属性, 但是没有向导可以为你填充所有Assembly属性。确保你至少填充了以下属性：

• AssemblyTitle
• 组装说明
• 组装公司
• 组装产品
• 大会版权
• AssemblyVersion

这是你要分发的所有程序集的最低要求。 NuGet背后的实际原因是：如果要使用从选定的程序集文件中自动创建NuGet规范的方法, 则此工具将从这些属性中获取所需的信息。

你还可以在开始时填充另一个属性：

InternalsVisibleTo

此属性使内部类和接口对指定程序集可见。通常用于要为项目创建的自动化测试。

连接字符串

在堆栈溢出中, 如何管理连接字符串是一个非常普遍的问题。问题在于如何使每个开发人员或CI作业都唯一的连接字符串, 以及在发布源代码时不公开连接详细信息。

在App.config(对于桌面应用程序)或Web.config(对于Web应用程序)中, 进行以下设置, 这些设置将在运行时加载user.config文件。将此置于你的源代码控制下：

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
	<connectionStrings configSource="user.config"></connectionStrings>
</configuration>

显然, 应该从源代码管理中排除user.config文件, 并且每个开发人员都应拥有此文件的本地副本, 以保护连接字符串的私密性：

<connectionStrings>
	<add name="test" connectionString="Server=.;Database=...;"/>
</connectionStrings>

.gitignore

对于那些使用Git作为源代码控件的用户, 将一些文件模式添加到.gitignore文件很重要。但是, 我们的智能社区已经构建了一个通用文件, 可以在这里找到：github.com/github/gitignore/blob/master/VisualStudio.gitignore。

你应该将其作为参考.gitignore文件, 只需添加你可能还需要的自定义排除项。

GitHub徽章

你可能已经在README项目的页面上看到了漂亮的徽章。如果要在GitHub上发布项目, 请考虑将你的项目连接到公共服务, 以进行以下操作：

• 建筑：显示建筑失败或失败。
• 测试：显示测试范围和测试执行状态。
• 发布：显示最新的NuGet软件包版本。

徽章和相关服务的完整列表可以在shields.io上找到。你可能会发现许多有趣的徽章, 这些徽章对开源项目很有用。

使用选定的服务注册项目后, 将为你提供指向图像的链接以及完整的markdown-syntax链接, 你可以将其添加到README.md文件中。顺便说一句, 这就是为什么你应该对自述文件使用markdown的原因之一。

罗斯林项目的降价徽章样本：

[！[构建状态]([http://dotnet-ci.cloudapp.net/job/roslyn_master_win_dbg_unit32/badge/icon)](http://dotnet-ci.cloudapp.net/job/roslyn_master_win_dbg_unit32/)] [http ：// [dotnet-ci.cloudapp.net/job/roslyn_master_win_dbg_unit32/badge/icon)](http://dotnet-ci.cloudapp.net/job/roslyn_master_win_dbg_unit32/))[！[在[https：/加入聊天/gitter.im/dotnet/roslyn](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/dotnet/roslyn?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=徽章)] [https://gitter.im/dotnet/roslyn] [https://badges.gitter.im/Join%20Chat.svg]] [https://gitter.im/dotnet/roslyn?utm_source=badge&utm_medium = badge＆utm_campaign = pr-badge＆utm_content = badge))

自动解决方案结构验证

即使你已经设置了本文中讨论的所有设置, 你的开发人员迟早也可能会更改它们并将更改提交给源控件。有时这是由于错误而发生的, 并且通常在代码审查期间未捕获这些更改。除了这些意外以外, 我们还应注意以下常见错误：

• 错误引用：当某人引用其他人可能没有的本地程序集时, 或者当某人从磁盘上删除文件时, 指向该文件的链接仍保留在.csproj文件中。这肯定会破坏构建, 但是一旦推送更改, 而其他人撤消了更改, 则可能为时已晚。这对于静态Web文件尤其重要, 你无法在构建过程中对其进行验证。
• 命名一致性：StyleCop之类的工具可以控制C＃源代码, 但是没有工具可以对Project文件或Assembly属性强制执行规则。一个很好的例子是：我们要命名项目以匹配输出程序集名称, 并且我们希望项目名称具有通用前缀, 例如MyCompany.MyProduct。

我发现在代码审查中监视这些错误很容易出错, 应该自动进行。因此, 我编写了一个简单的工具来执行这些检查以及许多其他检查, 以验证解决方案的一致性。认识SolutionInspector。这是开源的, 并在MIT许可下分发。你可以从源代码构建它, 也可以从NuGet安装：

Install-Package SolutionInspector

该工具将遍历整个解决方案结构, 并应用许多验证规则。规则由XML文件配置, 并与其他解决方案文件一起放置。要基于每个项目控制设置, 只需将具有不同设置的相同文件添加到相应的项目文件夹中。

默认情况下不需要配置文件。在这种情况下, 该工具将应用所有可用规则并将所有问题发布到控制台。

这是配置文件示例：

<?xml version="1.0" encoding="utf-8"?>

<Settings xmlns:xsi="[http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">](http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">)

<SolutionSettings>
    <MinSolutionFormatVersion>12.00</MinSolutionFormatVersion>
    <MaxSolutionFormatVersion>12.00</MaxSolutionFormatVersion>
    <DetectMissingFiles>true</DetectMissingFiles>
    <ProjectNamePrefix>MyCompany.MyProduct.</ProjectNamePrefix>
    <ProjectNameIsFileName>true</ProjectNameIsFileName>
    <IgnoredProjects>
        AVerySpecialProject1;
        AVerySpecialProject2;
    </IgnoredProjects>
</SolutionSettings>

<ProjectSettings>
    <DetectMissingFiles>true</DetectMissingFiles>
    <AllowBuildEvents>true</AllowBuildEvents>
    <AssemblyNameIsProjectName>true</AssemblyNameIsProjectName>
    <RootNamespaceIsAssemblyName>true</RootNamespaceIsAssemblyName>
    <RequiredImports>StyleCop.MSBuild.Targets</RequiredImports>
    <Properties>
        <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
        <StyleCopTreatErrorsAsWarnings>false</StyleCopTreatErrorsAsWarnings>
    </Properties>
</ProjectSettings>

</Settings>

尽管这些设置具有描述性, 但我将解释其中的一些：

• MinSolutionFormatVersion / MaxSolutionFormatVersion将阻止你的开发人员切换Visual Studio版本。
• DetectMissingFiles对于添加到解决方案或项目中的静态Web内容或其他非代码文件非常有用。
• AllowBuildEvents可以阻止添加自定义生成事件, 这可能会做不必要的事情。
• 属性是最灵活的元素：你可以根据所需值检查任何属性, 无论这些属性是已知属性还是自定义属性。

总结

我们已经审查了一些在开始新项目时可以应用的标准实践, 配置文件和项目设置。从一开始就这样做会减少未来的技术负担, 并使你的产品源代码看起来不错且专业。对于开源项目, 这尤其重要, 因为任何贡献者都可以通过检查解决方案配置和项目文件来了解你的期望。

相关：.NET Core-走向疯狂和开源。微软, 你花了这么长时间吗？