本文参考自MSDN的一篇文章,从零开始创建MSBuild C#项目文件。
准备条件
- 一个好用的文本编辑器,例如Atom或者Sublime Text。
- MSBuild命令行工具。如果已经安装了Visual Studio的话,应该可以在开始菜单中找到类似Visual Studio 2015的MSBuild命令提示符 这样的项目。
创建程序
首先打开MSBuild命令提示符,然后切换到你想要创建项目的文件夹,例如我的文档或者桌面。然后,输入md HelloWorld
创建一个名为HelloWorld的文件夹。然后输入cd HelloWorld
切换到这个文件夹。为简便起见,下面所说的命令提示符,都是指这里的MSBuild命令提示符。
使用你最喜欢的文本编辑器,在HelloWorld文件夹中创建一个名为helloworld.cs
的代码文件,文件内容如下:
using System;
class HelloWorld
{
static void Main()
{
#if DebugConfig
Console.WriteLine("WE ARE IN THE DEBUG CONFIGURATION");
#endif
Console.WriteLine("Hello, world!");
}
}
将文件保存之后,就可以在命令提示符中使用C#编译器工具csc编译该文件了。
csc helloworld.cs
然后就可以运行生成的helloworld.exe来查看编译生成的文件了。
helloworld.exe
应该可以在命令提示符中看到程序的输出。然后,删除生成的exe,准备下一步。
创建MSBuild项目文件
用文本编辑器创建名为Helloworld.csproj的文件,文件内容如下:
下面来简单解释一下。
csproj项目文件是一个XML文件,根节点是Project节点,可以包括若干个ItemGroup节点和Target节点。ItemGroup节点是一个容器,用来包括若干个项元素。例如这里就包括了一个项元素Compile,,包括了helloworld.cs文件。这里还可以使用通配符。
Target元素是项目构建的目标,每个文件可以有多个Target,执行不同的任务。这里,名为Build的Target就包括了Csc任务来编译一个文件,使用Source属性来指定要编译的文件。另外还有一些任务,会在下面说明。
这里还有一种语法@(Compile),这里会引用上面定义的项。在这里就是引用上面定义的helloworld.cs文件。如果定义了多个项,Target在执行的时候会以类似foreach的形式迭代执行每一个项。
有了项目文件,就可以使用MSBuild来执行项目的生成了,/t表示执行名为Build的Target。
msbuild helloworld.csproj /t:Build
查看一下是否生成了helloworld.exe,然后将其删除,准备下一步。
添加构建属性
在Project开始标签之后添加一个属性组节点:
MSBuildSample
Bin\
每个项目文件可以包括若干个PropertyGroup节点,其中可以包括若干个属性节点,每一个节点定义一个属性,可以在项目文件中引用。这里就包括了AssemblyName和OutputPath两个属性。之后就可以通过$(属性名)的语法来使用了。
在Csc节点前插入一个节点:
然后再Csc节点中增加一个OutputAssembly属性:
这里增加了一个创建文件夹的任务,创建的文件夹名字由上面的属性组定义。几乎每个任务都可以添加一个Condition属性,指定什么条件下执行该任务。这里是在输出目录不存在的情况下才执行该任务,创建目录。除此之外,还有其他很多任务,例如复制文件、删除文件等等,详细情况可以查看MSBuild任务参考。另外还有一个名字叫做MSBuild Community Tasks的开源项目,包含了其他一些任务,如果有需求的可以参考一下。
另外微软建议我们在定义目录属性的时候,最好将目录后面的反斜杠\定义到属性中,而不是加在引用之后。例如上面的就比下面的更好:
Bin\
OutputAssembly=="$(OutputPath)$(AssemblyName).exe" />
Bin
OutputAssembly=="$(OutputPath)\$(AssemblyName).exe" />
现在项目文件应该类似这样:
MSBuildSample
Bin\
再次运行一下构建命令,查看一下程序出否在输出目录中生成。
msbuild helloworld.csproj /t:Build
增加构建目标
在构建过程中可以指定多个构建目标,可以指定一个目标调用其他目标,还可以指定默认的构建目标。
在Build目标之后添加两个新目标:
这两个构建目标很简单,Clean目标会删除生成的exe文件。Rebuild目标会运行Clean和Build两个目标。
在Project节点中添加一个新属性DefaultTarget,就可以指定一个默认目标。如果运行MSBuild命令的时候没有使用/t指定Target,就会自动执行默认的目标。
运行一下msbuild helloworld.csproj /p:AssemblyName=Greetings
,测试一下。这里通过/p参数传入指定的参数名,这会覆盖项目文件中指定的文件名。如果不指定参数名的话就会使用在项目中已经定义的参数。然后运行msbuild helloworld.csproj /t:clean /p:AssemblyName=Greetings**/p:AssemblyName=Greetings
,删除已经生成的文件。
增量构建
在名为Build的Target中添加如下属性:
Inputs="@(Compile)" Outputs="$(OutputPath)$(AssemblyName).exe"
Inputs属性指定该目标依赖的输入文件,在这里由上面的Compile项所定义。Outputs指定项目的输出文件。指定这两个属性之后,MSBuild就会在运行此目标的时候检查输入和输出文件。如果输入文件相对于输出文件都是最新的,那么MSBuild就会跳过构建过程。如果有部分文件已经修改,MSBuild就会只对这部分文件运行构建目标。
概念总结
MSBuild依据csproj项目文件来进行构建。csproj文件中可以有多种节点。
ItemGroup节点是项目组,可以有多个子节点, 用来包含要处理的一个或多个文件。每个子节点都必须有Include属性指定要包含什么文件,还有一个可选的Exclude节点指定排除什么文件。定义ItemGroup之后,就可以利用@(节点名)来引用Item了。
PropertyGroup节点是属性组,可以有多个节点,用来包含项目构建过程中使用到的属性。定义了属性之后,可以使用$(属性名)语法来访问。
Target是构建目标,是MSBuild的执行目标,每个Target下面可以包含多个任务,还可以引用其他的Target构成一个执行链。微软和C#社区定义了很多任务,可以分别在其MSBuild任务参考和MSBuild Community Tasks中找到。
最后,我在Github上新建了一个项目MSBuildExample,演练了一下上面的概念。这个项目添加了一个AfterBuild目标,在Release状态下构建成功之后,将生成的可执行文件重命名成自定义名称,然后和第三方库以及一个配置文件打包生成zip压缩包。有兴趣的同学可以看一下。