WangShuXian6
commented
1 year ago 入门指南
创建新的Cake .NET工具项目
这是一个使用Cake .NET工具入门并向您展示Cake工作原理的指南。
选择您的运行环境
选择适合您情况的运行环境。有关运行Cake构建的其他可能方式，请参阅运行环境。
在本教程中，我们将在.NET Core 3.1及更高版本上使用Cake .NET工具。
确保在您的存储库中有一个工具清单可用，或者使用以下命令创建一个：
dotnet new tool-manifest使用dotnet tool命令将Cake安装为本地工具（您可以将3.1.0替换为您要使用的不同Cake版本）：
dotnet tool install Cake.Tool --version 3.1.0有关引导过程的详细信息，请参阅引导Cake .NET工具。
创建初始构建脚本
创建一个名为
build.cake的文件，其内容如下：
var target = Argument("target", "Test");
var configuration = Argument("configuration", "Release");
//////////////////////////////////////////////////////////////////////
// 任务
//////////////////////////////////////////////////////////////////////
Task("Clean")
.WithCriteria(c => HasArgument("rebuild"))
.Does(() =>
{
CleanDirectory($"./src/Example/bin/{configuration}");
});
Task("Build")
.IsDependentOn("Clean")
.Does(() =>
{
DotNetBuild("./src/Example.sln", new DotNetBuildSettings
{
Configuration = configuration,
});
});
Task("Test")
.IsDependentOn("Build")
.Does(() =>
{
DotNetTest("./src/Example.sln", new DotNetTestSettings
{
Configuration = configuration,
NoBuild = true,
});
});
//////////////////////////////////////////////////////////////////////
// 执行
//////////////////////////////////////////////////////////////////////
RunTarget(target);运行构建脚本
使用.NET CLI运行构建脚本：
dotnet cake创建新的Cake Frosting项目
这是一个入门指南，介绍了如何开始使用Cake Frosting，并向您展示Cake Frosting的工作原理。
安装和搭建
本教程使用Cake Frosting，它允许您将构建作为标准控制台应用程序的一部分编写，作为您解决方案的一部分。有关运行Cake构建的其他可能方式，请参阅运行环境。
以下说明要求Cake Frosting 1.0.0或更新版本，在.NET Core 3.1.301或更新版本上运行。您可以在https://dotnet.microsoft.com/download上找到.NET SDK。
要创建一个新的Cake Frosting项目，您需要安装Frosting模板：
dotnet new install Cake.Frosting.Template创建一个新的Frosting项目：
dotnet new cakefrosting这将创建Cake Frosting项目和引导脚本。
有关Cake Frosting引导过程的详细信息，请参阅Cake Frosting的引导。
初始构建项目
Program类包含配置和运行Cake主机的代码：
public static class Program
{
public static int Main(string[] args)
{
return new CakeHost()
.UseContext<BuildContext>()
.Run(args);
}
}
BuildContext类可用于添加额外的自定义属性。默认模板包含一个示例属性Delay，可以通过--delay参数进行设置。您可以删除此属性并根据您的特定需求自定义属性。
public class BuildContext : FrostingContext
{
public bool Delay { get; set; }
public BuildContext(ICakeContext context)
: base(context)
{
Delay = context.Arguments.HasArgument("delay");
}
}该文件还包含了三个任务的类：
[TaskName("Hello")]
public sealed class HelloTask : FrostingTask<BuildContext>
{
public override void Run(BuildContext context)
{
context.Log.Information("Hello");
}
}
[TaskName("World")]
[IsDependentOn(typeof(HelloTask))]
public sealed class WorldTask : AsyncFrostingTask<BuildContext>
{
// 任务可以是异步的
public override async Task RunAsync(BuildContext context)
{
if (context.Delay)
{
context.Log.Information("等待...");
await Task.Delay(1500);
}
context.Log.Information("World");
}
}
[TaskName("Default")]
[IsDependentOn(typeof(WorldTask))]
public class DefaultTask : FrostingTask
{
}默认任务依赖于World任务，而World任务依赖于Hello任务。如果设置了Delay属性，World任务是一个异步任务，会等待1.5秒。
示例构建流程
以下示例创建一个简单的构建流程，包括清理任务、编译MsBuild解决方案的任务以及测试解决方案的任务。
以下示例期望存储库根文件夹中有一个名为
src/Example.sln的Visual Studio解决方案。您需要根据您的解决方案来调整路径。添加所需的 using 语句：
using Cake.Common;
using Cake.Common.IO;
using Cake.Common.Tools.DotNet;
using Cake.Common.Tools.DotNet.Build;
using Cake.Common.Tools.DotNet.Test;从BuildContext类中删除Delay属性，并添加一个MsBuildConfiguration属性，用于存储应该构建的解决方案的配置：
public class BuildContext : FrostingContext
{
public string MsBuildConfiguration { get; set; }
public BuildContext(ICakeContext context)
: base(context)
{
MsBuildConfiguration = context.Argument("configuration", "Release");
}
}可以删除HelloTask和WorldTask类。
为清理目录创建一个名为CleanTask的新类：
[TaskName("Clean")]
public sealed class CleanTask : FrostingTask<BuildContext>
{
public override void Run(BuildContext context)
{
context.CleanDirectory($"../src/Example/bin/{context.MsBuildConfiguration}");
}
}为构建解决方案创建一个名为BuildTask的新类：
[TaskName("Build")]
[IsDependentOn(typeof(CleanTask))]
public sealed class BuildTask : FrostingTask<BuildContext>
{
public override void Run(BuildContext context)
{
context.DotNetBuild("../src/Example.sln", new DotNetBuildSettings
{
Configuration = context.MsBuildConfiguration,
});
}
}为测试解决方案创建一个名为TestTask的新类：
[TaskName("Test")]
[IsDependentOn(typeof(BuildTask))]
public sealed class TestTask : FrostingTask<BuildContext>
{
public override void Run(BuildContext context)
{
context.DotNetTest("../src/Example.sln", new DotNetTestSettings
{
Configuration = context.MsBuildConfiguration,
NoBuild = true,
});
}
}更新DefaultTask类以调用新任务：
[IsDependentOn(typeof(TestTask))]
public sealed class Default : FrostingTask
{
}运行构建脚本
Windows
./build.ps1Linux
build.sh
>MacOSbuild.sh
>有关如何运行Cake Frosting构建的详细信息，请参阅Cake Frosting https://cakebuild.net/docs/running-builds/runners/cake-frosting
***
## 常见问题
>如何锁定正在使用的Cake版本？
>请查看锁定Cake版本。[Pinning Cake Version](https://cakebuild.net/docs/writing-builds/reproducible-builds/pinning-cake-version).
>如何锁定正在使用的插件（Addin）版本？
>请查看锁定插件版本。 [Pinning Addin Version](https://cakebuild.net/docs/writing-builds/reproducible-builds/pinning-addin-version).
>如何锁定正在使用的工具（Tool）版本？
>请查看锁定工具版本。 [Pinning Tool Version](https://cakebuild.net/docs/writing-builds/reproducible-builds/pinning-tool-version).
>如何锁定正在使用的模块（Module）版本？
>请查看锁定模块版本。 [Pinning Module Version](https://cakebuild.net/docs/writing-builds/reproducible-builds/pinning-module-version).
>如何在Cake中启用不同的日志详细程度？
>这个问题已经在Stack Overflow的一个问题中得到了回答。[Stack Overflow question](https://stackoverflow.com/questions/38658660).
***
## 支持生命周期
### 版本管理
>Cake使用语义化版本控制（Semantic Versioning）。这意味着1.0.1版本只包含与1.0版本相比的错误修复，而1.1版本只包含向后兼容的新功能。2.0版本将包含与1.0版本相比的破坏性变更。
### 支持生命周期
>我们支持当前主要版本，提供最新版本的bug修复支持。
>主要版本将在下一个主要版本发布之前得到支持。一旦发布了更新的主要版本，对先前版本的支持就结束了。这意味着一旦2.0版本发布，我们将不再发布任何1.x版本的修复。
>Cake支持生命周期
***
## 升级说明
>要更新Cake，请按照以下说明进行操作：
>Cake .NET工具
>使用.NET工具作为本地工具时：
```bash
dotnet tool install --local Cake.Tool使用.NET工具作为全局工具时：
dotnet tool install --global Cake.ToolCake Frosting 更新
Cake.FrostingNuGet包的版本。.NET Framework的Cake运行时 更新
tools\packages.config文件中Cake包的版本。.NET Core的Cake运行时 更新
tools\packages.config文件中的Cake.CoreCLR包版本。
从Cake 2.x升级到Cake 3.0
Cake 3.0是一个包含破坏性变更的主要版本。
所需的.NET版本
Cake将不再在.NET Core 3.1或.NET 5上运行，但Cake将继续支持构建.NET Framework项目以及针对.NET 5.0或更早版本的项目。
Cake 3.0.0的支持平台矩阵如下：
| 运行时 | .NET 7 | .NET 6 |
|---|---|---|
| Cake .NET工具 | 支持 | 支持 |
| Cake Frosting | 支持 | 支持 |
DotNet别名
已删除
DotNetCore*别名，并替换为DotNet*别名。
Frosting生命周期
现在，Cake Frosting生命周期还需要一个
ISetupContext实例。
将FrostingLifetime实现从
public class BuildLifetime : FrostingLifetime<BuildContext>
{
public override void Setup(BuildContext context)
{}
}更改为
public class BuildLifetime : FrostingLifetime<BuildContext>
{
public override void Setup(BuildContext context, ISetupContext info)
{}
}从Cake 1.x升级到Cake 2.0
Cake 2.0是一个包含破坏性变更的主要版本。
支持的运行时和所需的.NET版本
为了使Cake能够利用现代平台功能、为扩展作者简化工作并简化用户的决策过程，我们决定停止在2.0中发布.NET Framework的Cake运行时以及已经弃用的.NET Core的Cake运行时。此外，我们还取消了对Cake.NET工具和Cake Frosting中运行.NET Core 2.1和.NET Core 3.0的支持。
这意味着，从Cake 2.0开始，您需要在构建机器上安装.NET SDK，至少需要.NET Core 3.1，但建议使用.NET 6，以便运行Cake。换句话说，Cake本身将不再在.NET Framework、Mono和.NET Core 3.0或更早版本上运行。Cake将继续支持构建.NET Framework项目以及针对.NET Core 3.0或更早版本的项目。
Cake 2.0的支持平台矩阵如下：
| 运行时 | .NET 6 | .NET 5 | .NET Core 3.1 |
|---|---|---|---|
| Cake .NET工具 | 支持 | 支持 | 支持 |
| Cake Frosting | 支持 | 支持 | 支持 |
由于不再发布Cake运行.NET Framework的版本，我们还将停止发布Cake.Portable Chocolatey包和Homebrew Cake公式。
自Cake.NET工具的1.0版本起，已弃用Cake运行.NET Core，并建议使用Cake.NET工具作为替代。对于使用Cake运行.NET Framework的用户，建议切换到Cake.NET工具，并在.NET Core 3.1或更新版本上运行构建。对于依赖于扩展或其他依赖项，需要.NET Framework或.NET Core 3.0或更早版本的用户，建议保持在Cake 1.x上。
有关详细信息，请参阅Cake 2.0中.NET Framework和.NET Core运行时的淘汰。
Cake Frosting
已删除的ReverseDependencyAttribute和DependencyAttribute。ReverseDependencyAttribute可以替换为IsDependeeOfAttribute，DependencyAttribute可以替换为IsDependentOnAttribute。
有关详细信息，请参见＃3003和＃3577。
Azure Pipelines构建提供程序更新
IsRunningOnAzurePipelines和IsRunningOnAzurePipelinesHosted属性 使用Cake 1.x时，IAzurePipelinesProvider.IsRunningOnAzurePipelines如果在自托管代理上运行构建，则返回true。要检查构建是否在Azure Pipelines上运行，无论使用哪种类型的代理，需要检查两个属性：
var isRunningOnAzurePipelines =
BuildSystem.AzurePipelines.IsRunningOnAzurePipelines || BuildSystem.AzurePipelines.IsRunningOnAzurePipelinesHosted;使用Cake 2.0后，IAzurePipelinesProvider.IsRunningOnAzurePipelines和BuildSystem.IsRunningOnAzurePipelines属性的含义已更改，仅用于检查构建是否在Azure Pipelines上运行。
要检查构建是否在Microsoft托管的或自托管的代理上运行，可以使用IsHosted属性：
var isMicrosoftHostedAgent =
BuildSystem.AzurePipelines.Environment.Agent.IsHosted;已删除IAzurePipelinesProvider.IsRunningOnAzurePipelinesHosted和BuildSystem.IsRunningOnAzurePipelinesHosted属性，需要用上述代码替换它们。此外，已删除了BuildProvider.AzurePipelinesHosted枚举值。
有关详细信息，请参见＃3654。
AzurePipelinesBuildInfo属性数据类型
AzurePipelinesBuildInfo.ArtifactStagingDirectory、AzurePipelinesBuildInfo.BinariesDirectory、>AzurePipelinesBuildInfo.SourcesDirectory、AzurePipelinesBuildInfo.StagingDirectory和>AzurePipelinesBuildInfo.TestResultsDirectory的数据类型已从FilePath更改为DirectoryPath。
有关详细信息，请参见＃3590。
删除的TFBuildProvider
已弃用的TFBuildProvider已删除。它可以替换为AzurePipelinesProvider。
有关详细信息，请参见＃3610。
MsBuild和dotnet支持
新的dotnet别名
已弃用现有的DotNetCore别名，并应替换为新的DotNet别名。
有关详细信息，请参见＃3341。
Xamarin.iOS平台目标支持
已向MSBuildSettings.PlatformTarget添加了PlatformTarget.ARMv6、PlatformTarget.ARMv7和PlatformTarget.ARMv7s，以支持Xamarin.iOS。
有关详细信息，请参见＃3222。
工具支持
GitVersion
GitVersionVerbosity已更新，以与当前版本的GitVersion中的详细程度匹配。
有关详细信息，请参见＃3282。
OpenCover
在Cake 1.x中，OpenCoverSettings具有类型为string的Register属性，可以为空以进行管理员模式、用户模式或DLL的路径：
OpenCover(x => {
x.NUnit3(tests);
},
coverageFile,
new OpenCoverSettings{
Register = "some-path-to-dll"
}
);在Cake 2.0中，OpenCoverSettings.Register已更改为OpenCoverRegisterOption类型。还有额外的OpenCoverSettings扩展方法：
OpenCover(x => {
x.NUnit3(tests);
},
coverageFile,
new OpenCoverSettings()
.WithoutRegister() //省略注册设置
.WithRegisterAdmin() // -register
.WithRegisterUser() // -register:user <--这是默认值
.WithRegisterDll(someFilePath) // -register:path-to-dll
);有关详细信息，请参见＃2788。
从Cake 1.0.0升级到Cake 1.1.0
Cake.DotNetTool.Module
从这个版本开始，Cake.DotNetTool.Module将始终与Cake一起发布，并且只与当前版本兼容。
如果您已经在构建中使用了Cake.DotNetTool.Module，请从构建脚本中删除Cake.DotNetTool.Module，因为它不再需要。
从Cake 0.38.x升级到Cake 1.0.0
Cake 1.0是一个包含破坏性变更的主要版本。
替换已弃用的成员
在先前版本中标记为已弃用的成员已在Cake 1.0中删除。请更新为已弃用消息中建议的成员。
Cake Frosting
删除了CakeHostBuilder 已删除CakeHostBuilder。在Cake Frosting 1.0中，可以直接使用CakeHost来创建CakeHost对象。
在Cake Frosting 0.38.x中：
// 创建主机。
var host =
new CakeHostBuilder()
.WithArguments(args)
.UseStartup<Program>()
.Build();
// 运行主机。
return host.Run();在Cake Frosting 1.0中：
// 创建和运行主机。
return
new CakeHost()
.UseContext<BuildContext>()
.Run(args);删除ICakeServices
已删除ICakeServices。在Cake Frosting 1.0中，您不再需要在Program类中实现IFrostingStartup接口。配置可以直接在CakeHost对象上完成。
在Cake Frosting 0.38.x中：
public class Program : IFrostingStartup
{
public static int Main(string[] args)
{
// 创建主机。
var host =
new CakeHostBuilder()
.WithArguments(args)
.UseStartup<Program>()
.Build();
// 运行主机。
return host.Run();
}
public void Configure(ICakeServices services)
{
services.UseContext<BuildContext>();
services.UseLifetime<Lifetime>();
services.UseWorkingDirectory("..");
}
}在Cake Frosting 1.0中：
public class Program : IFrostingStartup
{
public static int Main(string[] args)
{
// 创建和运行主机。
return
new CakeHost()
.UseContext<BuildContext>()
.UseLifetime<Lifetime>()
.UseWorkingDirectory("..")
.Run(args);
}
}工具安装改进
不再需要手动注册Cake Frosting的nuget模块。在Cake Frosting中安装工具的方法也已从UseTool更名为InstallTool：
在Cake Frosting 0.38.x中：
public class Program : IFrostingStartup
{
public static int Main(string[] args)
{
// 创建主机。
var host =
new CakeHostBuilder()
.WithArguments(args)
.UseStartup<Program>()
.Build();
// 运行主机。
return host.Run();
}
public void Configure(ICakeServices services)
{
// 注册NuGet模块。
var module = new NuGetModule(new CakeConfiguration(new Dictionary<string, string>()));
module.Register(services);
// 注册工具。
services.UseTool(new Uri("nuget:?package=NUnit.ConsoleRunner&version=3.11.1"));
}
}在Cake Frosting 1.0中：
public class Program : IFrostingStartup
{
public static int Main(string[] args)
{
// 创建和运行主机。
return
new CakeHost()
.InstallTool(new Uri("nuget:?package=NUnit.ConsoleRunner&version=3.11.1"));
.Run(args);
}
}Cake CLI更新
作为Cake 1.0的一部分，CLI的重写使得开关的解析现在更严格。
参数语法
在Cake 1.0中，参数应始终使用多破折号语法调用（例如--target=Foo）。当使用单破折号语法（例如-target=Foo）时，将显示类似以下的错误消息：
Error: Unknown command 'Foo'.
build.cake -target=Foo
^^^^^^ No such command传递空参数
在以前的Cake版本中，可以定义一个空参数（例如--foo=）或传递一个空值（例如--foo=""）。
在Cake 1.0中，将显示类似以下的错误消息：
Error: Expected an option value.与Cake 1.0的一个关键差异是，除了键/值参数（--key=value），它还支持标志（--flag）以及具有相同名称的多个参数（--key=value1 --key=value2），这比以前更灵活。
在Cake 1.0中，如果值可以为空或null，则使用空格代替=：
--foo ""如果使用此语法从CI系统传递变量，可以在参数和值之间使用空格作为分隔符：
--foo %myvariable%Azure DevOps构建任务扩展
确保使用至少版本2.1的Azure DevOps构建任务扩展和版本2.*的任务与Cake 1.0一起使用。
Cake（C# Make）
入门 - 快速入门的教程 基础知识 - 关于Cake的基础知识 运行构建 - 如何运行您的Cake构建的信息 编写构建 - 如何编写构建的信息 集成 - 与编辑器、IDE和构建服务器的集成 扩展Cake - 如何使用自定义功能扩展Cake的文档 团队 - 维护团队为您提供Cake的团队
这些是关于Cake的文档资源，可帮助您深入了解和使用这个构建自动化工具。
以下文档为 Cake 3.1.0 翻译自官网 2023/10/3