MEL.Flex 0.1.0

MEL.Flex

这是什么？

MEL.Flex (为 Microsoft.Extensions.Logging 提供的 FSharp Logging EXtensions) 通过将插入的字符串透明地转换为 信息模板，在获取结构化记录优势的同时，为强类型字符串添加了使用 字符串插值 的能力。

为什么存在这个？

具有消息模板的结构化记录 是非常好的，除了存在一些问题。

1. 它们通常是位置固定的。如果我有以下代码

   let userName = "KirkJ1701"
   logger.LogWarning("Some user: {UserName} has logged in", userName)
   

   如果我想添加一个 IpAddress

   let userName = "KirkJ1701"
   let ipAddress = "KirkJ1701"
   logger.LogWarning("Some user: {UserName} has logged in from {IpAddress}", ipAddress, userName)
   

   我很容易搞乱参数。这当然看起来很简单，但随着你添加更多的日志来结构化或重新排列日志，它会变得更加困难。

2. 使用语义约定规范化您的密钥可以让您更容易地在日志中搜索。

   let userName = "SpockV"
   logger.LogWarning("Some user: {user_name} has logged in", userName)
   

   将此日志添加到我们的应用程序日志会记录user_name，但之前我们记录的是UserName。如果我要在日志中搜索，就需要知道每个可能的关键字名的变体。（是的，一些工具允许在它们的一侧进行映射，但并非所有都这么做）。

如何使用它？

元组参数

目前支持的一种方式是使用元组。以上面的示例来说明

// Some file that containts your normalized names
module LoggerKeyConsts =
    let [<Literal>] UserName = "UserName"

// .. Some function

let userName = "SpockV"
logger.LogFWarning($"Some user: {(LoggerKeyConsts.UserName, userName)} has logged in")

重要的更改如下

1. LogWarning → LogFWarning
2. 字符串前面的$
3. {Username}变成了{(LoggerKeyConsts.UserName, userName)}
   • 此语法后的部分是一个包含两个值的元组。

稍微好一些的方法是创建生成元组的辅助函数

module LogConsts =
    let [<Literal>] ``user.name`` = "user.name"
    let inline userName (s : string) = struct (``user.name``, s)

// .. Some function
let userName = "SpockV"
logger.LogFWarning($"Some user: {LogConsts.userName userName} has logged in")

这样可以，对日志数据应用任何类型安全或规范化。

注意事项

• 遗憾的是，F#目前不支持DefaultInterpolatedStringHandler，这意味着您仍会遭受被插值创建的打击。然而，此库实现了它自己的日志格式化器，它允许在需要之前或可能根本不需要时对被插值字符串→消息模板进行懒惰构建，这取决于日志级别配置是否大于日志语句的阈值。

构建

GitHub Actions

NuGet

程序包	稳定的	预发行版
MEL.Flex

开发中

请确保您的系统已经安装以下要求

• dotnet SDK 3.0 或更高版本
• 如果您使用Linux或macOS，则需要安装Mono。

或

• VSCode Dev Container

环境变量

• CONFIGURATION将设置dotnet命令的配置。如果没有设置，则默认为发布。
  • CONFIGURATION=Debug ./build.sh会导致向命令如dotnet build -c Debug中添加-c选项
• GITHUB_TOKEN将用于上传发布说明和Nuget程序包到GitHub。
  • 确保在发布之前设置
    
• DISABLE_COVERAGE将禁用运行代码覆盖率指标。AltCover可能会造成严重的性能下降，所以当您希望快速反馈循环时，禁用它是有意义的。
  • DISABLE_COVERAGE=1 ./build.sh

构建

> build.cmd <optional buildtarget> // on windows
$ ./build.sh  <optional buildtarget>// on unix

您的库的bin应该看起来像这样

$ tree src/MEL.Flex/bin/
src/MEL.Flex/bin/
└── Debug
    └── net50
        ├── MEL.Flex.deps.json
        ├── MEL.Flex.dll
        ├── MEL.Flex.pdb
        └── MEL.Flex.xml

构建目标

• Clean - 清理工件和临时目录。
• DotnetRestore - 在解决方案文件上运行dotnet restore。
• DotnetBuild - 在解决方案文件上运行dotnet build。
• DotnetTest - 在解决方案文件上运行dotnet test。
• GenerateCoverageReport - 在ReportGenerator的帮助下生成报告。
• WatchTests - 使用测试项目运行 dotnet watch。适用于快速反馈循环。
• GenerateAssemblyInfo - 为库生成 AssemblyInfo。
• DotnetPack - 运行 dotnet pack。这包括运行 Source Link。
• SourceLinkTest - 运行 Source Link 测试工具以验证源链接是否已正确生成。
• PublishToNuGet - 通过 paket push 将在 DotnetPack 中生成的 NuGet 包发布到 NuGet。
• GitRelease - 使用版本中的 Release Notes 和 git 标签创建提交信息。
• GitHubRelease - 发布包含 Release Notes 和任何 NuGet 包的 GitHub Release。
• FormatCode - 在解决方案文件上运行 Fantomas。
• BuildDocs - 从 docsSrc 和库中的 XML Documentation Comments 生成文档。
• WatchDocs - 生成文档并在本地启动 web 服务器。如果检测到对 docsSrc 文件、src 中的库或 docsTool 本身的更改，将重新构建和热重新加载。
• ReleaseDocs - 将在 BuildDocs 目标中生成的文档暂存、提交和推送。
• Release - 运行所有发布类型任务，如 PublishToNuGet、GitRelease、ReleaseDocs 和 GitHubRelease。请确保正确设置环境以启用发布。

发布

• 开启具有远程的 git 仓库

git add .
git commit -m "Scaffold"
git remote add origin https://github.com/user/MEL.Flex.git
git push -u origin master

• 创建您的 NuGet API 密钥

  • 将您的 NuGet API 密钥添加到 paket

  paket config add-token "https://nuget.net.cn" 4003d786-cc37-4004-bfdf-c4f3e8ef9b3a
  

  • 或设置环境变量 NUGET_TOKEN 为您的密钥

• 创建 GitHub OAuth 令牌

  • 然后您可以设置环境变量 GITHUB_TOKEN 以上传发布说明和工件到 GitHub
  • 否则将回退到用户名/密码

• 然后更新 CHANGELOG.md，添加一个包含按 KeepAChangelog 格式编写的此版本发布说明的 "Unreleased" 部分。

注意：强烈建议在发布说明旁边添加对受影响的 Pull Request 的链接。原因在于当运行 RELEASE 目标时，它将把这些新说明添加到 git 提交的消息体中。GitHub 会注意到这些链接，并将更新 Pull Request，指明哪些提交引用了它，例如 "添加了一个引用此 Pull Request 的提交"。由于构建脚本自动化提交信息，因此它会说 "将版本提升到 x.y.z"。这样做的好处是当用户访问 Pull Request 时，可以清楚地了解哪些代码更改何时以及哪个版本发布。同时，在阅读 CHANGELOG 时，如果有人对如何或为什么做出这些更改感到好奇，他们可以轻松发现工作和讨论。

以下是在 CHANGELOG.md 中添加 "Unreleased" 部分的一个示例，其中已经发布了一个 0.1.0 部分。

## [Unreleased]

### Added
- Does cool stuff!

### Fixed
- Fixes that silly oversight

## [0.1.0] - 2017-03-17
First release

### Added
- This release already has lots of features

[Unreleased]: https://github.com/user/MEL.Flex.git/compare/v0.1.0...HEAD
[0.1.0]: https://github.com/user/MEL.Flex.git/releases/tag/v0.1.0

• 然后您可以使用 Release 目标，指定版本号，可以是环境变量 RELEASE_VERSION 中的，也可以是目标名称后面的参数。这将
  • 更新 CHANGELOG.md，将更改从 Unreleased 部分移动到新的 0.2.0 部分
    • 如果有 0.2.0 的任何预发布版本在更改日志中，它还将将这些更改收集到最终 0.2.0 条目中
  • 将版本号更新并同时添加新的变更日志部分到提交内容中： 将版本提升到 0.2.0
  • 将包发布到 NuGet
  • 推送一个 Git 标签
  • 为该 Git 标签创建 GitHub 发布

macOS/Linux 参数

./build.sh Release 0.2.0

macOS/Linux 环境变量

RELEASE_VERSION=0.2.0 ./build.sh Release