walterlv

将美化进行到底，把 PowerShell 做成 oh-my-zsh 的样子

Sat, 28 Aug 2021 08:56:59 +0000

不知你有没有看过 Linux 上 oh-my-zsh 的样子？看过之后你一定会惊叹，原来命令行还能这么玩！然而 Windows 下能这么玩吗？答案是可行的，接下来就来看看怎么玩。

Windows 下我们用 oh-my-posh 在 PowerShell 中实现这样的效果。分以下三步走：

安装 oh-my-posh

我们需要先以管理员权限启动 PowerShell，以便执行安装操作。（具体是在开始按钮上点击右键，选择“Windows PowerShell (管理员)”。）

然后，运行命令以安装 posh-git，这是 oh-my-posh 的依赖。

Install-Module posh-git -Scope CurrentUser

如果此前没有安装 NuGet 提供程序，则此时会提示安装 NuGet；如果此前没有开启执行任意脚本，此处也会提示执行脚本。如果没有权限执行脚本，可能需要先执行 Set-ExecutionPolicy Bypass。

接下来，运行命令以安装 oh-my-posh 本身。

Install-Module oh-my-posh -Scope CurrentUser

自此，oh-my-posh 安装完毕。

启用模组并设置主题

接下来，我们需要启用安装的模组。启用模组的命令是：

Import-Module oh-my-posh

其实写本文主要就是想体验 zsh 的操作，并看看 git 文件夹的视觉效果。现在我们就试试，输入：

Set-PoshPrompt

（注意，oh-my-posh 更新后，命令从 Set-Theme 变成了 Set-PoshPrompt。）

然后按一下空格，按一下 Tab。会发现这时已经可以用方向键来选择参数了！原生 PowerShell 可没有这个功能啊！

我们选择 Agnoster 主题。（这些主题都是 oh-my-posh 带给我们的。）

接下来我们看看 git 文件夹下的显示：

并没有 zsh 那样的效果。——因为我们缺少专用的字体！

下一节我们会讲如何安装专为 zsh 效果设计的字体。

现在，我们需要让 PowerShell 每次启动的时候都能够加载这个模组，所以我们需要设置 profile 文件让它自动启用。

敲 $profile 可以让 PowerShell 告诉我们这个文件的路径是什么。当然下图是我的路径，读者的默认在文档路径里的 PowerShell 文件夹下。

我们需要编辑这个文件（如果没有，手动创建一个），然后在里面写下那一句话：

Import-Module oh-my-posh
Set-PoshPrompt Paradox

接下来，新打开 PowerShell（不需要管理员权限）时就会提示加载了这个文件：

安装字体/安装第三方 PowerShell

！！！重要说明：给 PowerShell 定制字体是一件非常困难的事情，非常困难！！！ 可参见自定义 Windows PowerShell 和 cmd 的字体感受一下。 所以，这里更倾向于在安装了字体的情况下使用第三方 PowerShell。

比如下图是我用 vscode 中带的 PowerShell 的效果。

推荐的其他 PowerShell：

但是，如果你执意要跑原生 PowerShell，那也不是没有办法，你可以使用 PowerLine 专为 PowerShell 和 zsh 设计的字体，它们的字体是可以完美跑到 PowerShell 和 PowerShell Core 中的。

下图是我在 PowerShell Core 中的运行效果：

请在这里下载 PowerLine 字体：

powerline/fonts: Patched fonts for Powerline users.

方法是克隆这个仓库，然后在克隆出来的文件夹中找到 Install.ps1 文件，执行它，会发现它会自动为我们安装所有的 PowerLine 字体。

安装完成之后，在 PowerShell 或者 PowerShell Core 的标题栏上右击选择“属性”，然后选择你想要设置的字体就可以立刻看到效果了。注意，PowerLine 字体都是带有 for PowerLine 后缀的。

PowerLine 字体官方文档在这里：Overview — Powerline beta documentation。

▲ 官方文档中的 PowerLine 字体截图

官方字体的下载链接：powerline/fonts: Patched fonts for Powerline users.
官方字体的看图预览：fonts/All.md at master · powerline/fonts

参考资料

使用 WPF 做一个可以逼真地照亮你桌面的高性能阳光

Thu, 05 Aug 2021 09:20:04 +0000

本文想要做的，可不是随便弄一点阳光的半透明形状，然后简单地放到桌面上，而是真真正正地要照亮桌面上的窗口元素！并且，全程使用 GPU 加速，而且代码超简单。

效果预览

先放上两张动图看看效果，GIF 比较大，如果博客里看不到可以点击下面的小标题下载下来看。

阳光扫过云层：

阳光扫过 Visual Studio：

可以看到，阳光经过云层时，强烈的光芒与云层的光光部分叠加起来了，让人感觉云层的照亮部分十分刺眼。阳光经过 Visual Studio 的界面时，纯色部分可以看出阳光的外形，高饱和度部分在阳光的照耀下显得格外亮眼。

代码实现

实现本文效果的代码其实很少，只有以下几步：

制作一个全透明窗口
编写一个像素着色器
画一个简单的阳光形状

不过在开始之前，我们先创建一个空白的 WPF 项目吧：

第一步：制作一个全透明窗口

网上广为流传的 AllowsTransparency="True" 的方式就可以，不过我个人不喜欢，因为性能不好。我更推荐大家使用我另一篇博客里推荐的高性能透明窗口的实现方案：WPF 制作高性能的透明背景异形窗口

如果现在不想看的，我可以直接把 MainWindow.xaml.cs 的代码贴出来（放心，其他地方不需要写代码）：

<Window x:Class="Walterlv.DesktopSunshine.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        xmlns:local="clr-namespace:Walterlv.DesktopSunshine"
        mc:Ignorable="d" Title="Walterlv.DesktopSunshine" Width="240" Height="240"
        Background="Transparent" WindowStyle="None" ResizeMode="NoResize">
    <WindowChrome.WindowChrome>
        <WindowChrome GlassFrameThickness="-1" ResizeBorderThickness="0" CornerRadius="0" CaptionHeight="240" />
    </WindowChrome.WindowChrome>
    <Grid>
    </Grid>
</Window>

最重要的，是 Background="Transparent"、WindowStyle="None"、ResizeMode="NoResize" 和 GlassFrameThickness="-1" 这四个属性。

其他的代码，我只是在做一个普通的窗口而已。大小 240 是为了容纳一个太阳的大小。

第二步：编写一个像素着色器

想了解怎么写像素着色器的，可以阅读我的另一篇博客：WPF 像素着色器入门：使用 Shazzam Shader Editor 编写 HLSL 像素着色器代码。

需要在像素着色器里编写此代码（不想学像素着色器的可以忽略此代码直接往后看）：

sampler2D  inputSampler : register(S0);
float Threshold : register(C0);

float4 main(float2 uv : TEXCOORD) : COLOR
{
    float4 color = tex2D(inputSampler, uv);
    float a = color.a;

    if(a < Threshold)
    {
   	    color.a  = 0;
    }
    else
    {
        color.a  = 1;
    }

    return color;
}

如果不想自己编写并编译像素着色器，可以直接下载我已经编译好的 .ps 文件：

BinaryAlphaEffect.ps

下载下来的文件（或者你自己编译出来的文件）放到解决方案中的任意位置（本示例中放到了 Assets 文件夹中）：

重要：接着，将 .ps 文件加入到编译。请双击项目（Walterlv.DesktopSunshine）以编辑其项目文件（.csproj）。需要增加的行我已经在下面高亮出来了。

    <Project Sdk="Microsoft.NET.Sdk">

      <PropertyGroup>
        <OutputType>WinExe</OutputType>
        <TargetFramework>net6.0-windows</TargetFramework>
        <Nullable>enable</Nullable>
        <UseWPF>true</UseWPF>
      </PropertyGroup>

++    <ItemGroup>
++      <Resource Include="Assets\**\*.ps" />
++    </ItemGroup>

    </Project>

然后，编写一个使用此 .ps 文件的 C# 类型。我取名为 BinaryAlphaEffect.cs。

using System;
using System.Windows;
using System.Windows.Media;
using System.Windows.Media.Effects;

namespace Walterlv.DesktopSunshine
{
    public class BinaryAlphaEffect : ShaderEffect
    {
        public static readonly DependencyProperty InputProperty = RegisterPixelShaderSamplerProperty(
            "Input", typeof(BinaryAlphaEffect), 0);

        public static readonly DependencyProperty ThresholdProperty = DependencyProperty.Register(
            "Threshold", typeof(double), typeof(BinaryAlphaEffect),
            new UIPropertyMetadata(1.0d, PixelShaderConstantCallback(0)));

        public BinaryAlphaEffect()
        {
            PixelShader = new PixelShader
            {
                UriSource = new Uri("/Assets/BinaryAlphaEffect.ps", UriKind.Relative),
            };

            UpdateShaderValue(InputProperty);
            UpdateShaderValue(ThresholdProperty);
        }

        public Brush Input
        {
            get => (Brush)GetValue(InputProperty);
            set => SetValue(InputProperty, value);
        }

        public double Threshold
        {
            get => (double)GetValue(ThresholdProperty);
            set => SetValue(ThresholdProperty, value);
        }
    }
}

这个 Threshold 是个二值化的阈值，可用来调阳光效果。我把默认值设为了 1，这样阳光效果最强烈。（实际上其他值的效果惨不忍睹。因为这段代码我本来编写的目的不是在做阳光，只是中间不小心做出了阳光效果，觉得很有意思就教大家一下。）

第三步：画一个简单的阳光形状

我只画一个圆来表示阳光的形状（想用其他形状的，自己发挥创意）。于是在 MainWindow.xaml 里添加一点点代码：

        </WindowChrome.WindowChrome>
++      <Border>
++          <Ellipse Fill="White" Width="160" Height="160">
++              <UIElement.Effect>
++                  <BlurEffect Radius="40" />
++              </UIElement.Effect>
++          </Ellipse>
++      </Border>
    </Window>

这里，给圆加了一些模糊效果，这是必要的。

然后，把我们在第二步里写的像素着色器用上：

    <Border>
++      <UIElement.Effect>
++          <local:BinaryAlphaEffect />
++      </UIElement.Effect>
        <Ellipse Fill="White" Width="160" Height="160">
            <UIElement.Effect>
                <BlurEffect Radius="40" />
            </UIElement.Effect>
        </Ellipse>
    </Border>

那么至此，所有代码已经完成。

总结一下，我们写了这些代码：

一个新创建的 WPF 项目模板（包含模板自带的 App.xaml App.xaml.cs MainWindow.xaml MainWindow.xaml.cs AssemblyInfo.cs）
下载或编译的 BinaryAlphaEffect.ps 像素着色器文件，和用来使用它的 BinaryAlphaEffect.cs 文件
使用 BinaryAlphaEffect 类的 MainWindow.xaml 中的几个 Border 和 Ellipse

是不是代码量非常少？接下来，就是见证奇迹的时刻。

效果与性能

阳光扫过 Windows 11 自带壁纸。在太阳附近，与太阳融为一体；在森林中，阳光被树叶遮挡；在水面，阳光跟随着波光闪耀；在岩石上，阳光把岩石照得通亮。

你可以把这个阳光放到任何地方，就算是正在播放的视频前面也依然在每帧中都有实时效果。

最重要的是——它几乎不消耗性能！因为它在图形渲染管线的像素着色器部分运行，其所有代码都在 GPU 中并行执行，且每次执行仅需不到 10 条指令。你可以看到任务管理器中，它的 CPU 和 GPU 消耗都是 0。

路径标记语法（Path Markup Syntax）完全教程

Fri, 30 Jul 2021 00:50:07 +0000

无论是 WPF、UWP 还是 Xamarin、MAUI、WinUI，都有可以绘制任意形状的 Geometry 类型，它支持一种路径标记语法，可以拟合各种形状。同时，SVG 格式使用的也是完全相同的路径语法，你用文本编辑器打开一个 SVG 格式时也会看到这样的字符串。

你只需要阅读本文，即可从零开始了解并最终学会路径标记语法。

示例

一开始，我们用一张 SVG 图来看看一个典型的路径字符串是什么样子的：

你可以点击上面这张图以单独打开它，然后查看网页源代码来观察它的字符串内容。我这里也贴一份：

<?xml version="1.0" encoding="UTF-8" standalone="no"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg width="100%" height="100%" viewBox="0 0 20 20" version="1.1"
    xmlns="http://www.w3.org/2000/svg"
    xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve"
    xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
    <g id="控件">
        <g id="ic-备课端-主窗口-工具栏-文字" serif:id="ic/备课端/主窗口/工具栏/文字">
            <g>
                <rect id="bounds" x="0" y="0" width="20" height="20" style="fill:#f00;fill-opacity:0;"/>
                <path id="形状结合" d="M17,11c-1.342,-0 -3.872,1.385 -4.872,2.385c0.958,1.151 1.381,2.186 1.872,3.615l3,-0l0,-6Zm-5,6c-1.568,-3.869 -4.674,-6 -9,-6l0,6l9,-0Zm-9,-8c4,0 6,1 8,3c2,-2 4,-3 6,-3l0,-5l0.206,0c0.439,0 0.794,0.366 0.794,0.818l-0,12.364c-0.003,0.45 -0.356,0.814 -0.794,0.818l-14.412,0c-0.439,-0 -0.794,-0.366 -0.794,-0.818l-0,-12.364c0.003,-0.45 0.356,-0.814 0.794,-0.818l14.206,-0l0,1l-14,-0l0,4Zm10,-1c-0.663,-0 -1,-0.318 -1,-1c0,-0.682 0.337,-1 1,-1c0.663,-0 1,0.318 1,1c0,0.682 -0.337,1 -1,1Z" style="fill:#666;fill-opacity:0.8;fill-rule:nonzero;"/>
            </g>
        </g>
    </g>
</svg>

这里，path/@d 里的，就是我们即将学习的路径标记字符串。

XAML 系的路径标记语法与之只有一点点不同。

名称

在 SVG 的解释文档中，对此语法的称呼为“SVG Path Syntax”（SVG 路径语法）。在 XAML 系语言中，称其为“Path Markup Syntax”（路径标记语法），官方也称其为“Mini-Language”。

由于 SVG 和 XAML 的路径语法几乎一样，所以学会本文可以直接学会两者的语法。

语法（Syntax）

路径标记语法从前往后写下来，遵循“命令-参数-命令-参数-命令-参数-……”这样的要求。让我们再来一个更简单的例子：

M 10,100 C 10,300 300,-200 300,100

把解释放进这个字符串的话，是这样：M（命令）10,100（点坐标） C（命令）10,300 300,-200 300,100（三个点坐标）。

在 SVG 路径语法中，一共有如下命令可以使用：

M m L l H h V v C c Q q S s T t A a Z z

额外的，XAML 系的路径标记语法还有一个 F。

看起来很多，但实际上我们可以做一个分类，这样理解起来会更容易一些：

起点
- M m
直线
- L l、H h、V v
贝塞尔曲线
- C c、Q q、S s、T t
椭圆弧
- A a
封闭
- Z z

先来说说一些共性的知识：

一个路径可以由多段组成，用 M m 来指定一个新段的开始
大写字母后面跟的参数中，点坐标是绝对坐标；小写字母后面跟的参数中，点坐标是相对坐标
如果连续几段都是相同的命令，那么后续可以只写参数而省略命令
字符串中间的空格 ` ` 和逗号 , 是用来分隔参数和点的 X、Y 坐标的，可以混用也可以多写

下面，我们一个一个说：

`F`

相比于 SVG 来说，F 是 XAML 系路径标记语法唯一一个特有的语法。

带上参数一起，F 只有三种写法：

省略不写
F0 表示 EvenOdd
F1 表示 Nonzero

省略不写和 F0 是相同的含义，即 EvenOdd。

SVG 中如果要实现相同的效果，需要设置 path/@style 属性，即style="fill-rule:nonzero;"。

起点和终点

`M` `m` 移动命令

M m（Move，移动）

含义：开始一段新的路径，然后将起点移到 M m 后面的参数中
参数：startPoint（起点坐标）
示例：M10,100

M 后面的 startPoint 参数是绝对点坐标，而 m 后面的 startPoint 参数是相对上一个命令中端点坐标的相对点坐标。

`L` `l` `H` `h` `V` `v` 直线命令

L l（Line，直线）

含义：从上一个点开始，连一条直线到此命令的端点
参数：endPoint（端点坐标）
示例：L100,200

H h（Horizontal Line，水平线）

含义：从上一个点开始，连一条水平直线到此命令的横坐标
参数：x（横坐标）
示例：H100

V v（Vertical Line，垂直线）

含义：从上一个点开始，连一条垂直直线到此命令的纵坐标
参数：y（纵坐标）
示例：V200

与前面一样，大写字符后面的坐标和数值是绝对坐标，小写字符后面的坐标和数值是相对坐标。

`C` `c`、`Q` `q`、`S` `s`、`T` `t` 贝塞尔曲线命令

C c（Cubic Bezier Curve，三次贝塞尔曲线）

含义：从上一个点开始，连一条三次贝塞尔曲线到此命令的端点
参数：controlPoint1 controlPoint2 endPoint（控制点坐标1 控制点坐标2 端点坐标）
示例：C10,300 300,-200 300,100

Q q（Quadratic Bezier Curve，二次贝塞尔曲线）

含义：从上一个点开始，连一条二次贝塞尔曲线到此命令的端点
参数：controlPoint endPoint（控制点坐标端点坐标）
示例：Q300,-200 300,100

S s（Smooth Cubic Bezier Curve，平滑三次贝塞尔曲线）

含义：从上一个点开始，连一条平滑的三次贝塞尔曲线到此命令的端点，确保在上一个点的曲线是连续的
参数：controlPoint2 endPoint（控制点坐标2 端点坐标）
示例：S300,-200 300,100

所谓“平滑”，即保证曲线在上一个端点处的的曲线连续而没有突变（一次可导）。而平滑的方法，便是将上一个命令在端点处的贝塞尔控制点相对上一个点进行一次镜像。

下面这张图可以说明是如何做到平滑的：

你也可以注意到一个有趣的事情，S s 的参数中只有 controlPoint2 和 endPoint，这是因为 controlPoint 完全是根据上一个点的控制点的镜像来计算得到的，无需传入。

T t（Smooth Quadratic Bezier Curve，平滑二次贝塞尔曲线）

含义：从上一个点开始，连一条平滑的二次贝塞尔曲线到此命令的端点，确保在上一个点的曲线是连续的
参数：endPoint（端点坐标）
示例：T300,100

与 S s 一样，T t 也是确保在上一个点处平滑。控制点的计算方法也是一样对上一个点的控制点进行镜像。由于二次贝塞尔曲线只有一个控制点，所以它是无需传入控制点的，完全是算出来的。

`A` `a` 椭圆弧命令

A a（Elliptical Arc，椭圆弧）

含义：在上一个点和此命令的端点之间，连一条椭圆弧
参数：size rotationAngle isLargeArcFlag sweepDirectionFlag endPoint（包含宽高两个值的尺寸以度数计量的角度值大于平角或小于平角标识顺时针或逆时针标识端点坐标）
示例：A18.621,18.621,0,0,1,18.621,0.000

isLargeArcFlag 标识，如果角度大于 180° 则为 1，否则为 0；sweepDirectionFlag 标识，如果顺时针则为 1，如果逆时针则为 0。

`Z` `z` 闭合命令

含义：如果有此命令，那么图形将闭合形成填充区域；如果没有此命令，那么图形将只有线而不填充
没有参数
示例：z

此命令不区分大小写。

解析

在这里挖一个坑，稍后贴出我用“访问者”模式编写的高性能高扩展性的路径语法解析代码。

参考资料

用 WiX 制作安装包：创建一个简单的 exe 安装包

Tue, 20 Jul 2021 01:11:05 +0000

本文是 WiX Toolset 安装包制作入门教程系列中的一篇，可前往阅读完整教程。

本文将带大家制作一个简单的 exe 安装包。

本文开始前，请确保你已经可以生成一个最简单的 msi 安装包了：

用 WiX 制作安装包：创建一个简单的 msi 安装包

由于 exe 格式的安装包自己带了 UI，所以 msi 中的 UI 怎么样都是可以不用管的（不用纠结 msi 做成了扫什么样，能像上文结尾一样正常安装就好）。

创建 WiX EXE 项目

在解决方案上右键，“添加”->“新建项目…”，然后在“添加新项目”窗口中搜索“WiX”，找到“Bootstrapper Project for WiX v3”。按“下一步”取个名字，然后“创建”。

注意，选择的模板要注意这些要点：

图标上标记了“wix”，标签上标记了“WiX”
模板简介中说明这是在创建“EXE”文件

创建完后，记得去项目属性里改一下输出的文件名。例如可以改成主项目的名称，也可以改成“XXX_Setup”这些大家喜欢用的名称。

引用 MSI 项目

我们现在的这个项目生成的是捆绑包（Bundle），是为了将多个安装包集合到一起进行安装的。

我们需要在这个捆绑包里面安装我们上一篇教程中创建的 MSI 安装包，所以我们需要引用这个创建 MSI 的项目。

编辑 Bundle.wxs 文件

在 Bundle.wxs 文件中，找到放 MSI 文件的注释处，将其替换成我们想安装的 MSI 文件。

    <Chain>
--    <!-- TODO: Define the list of chained packages. -->
--    <!-- <MsiPackage SourceFile="path\to\your.msi" /> -->
++    <MsiPackage Compressed="yes"
++                SourceFile="$(var.Walterlv.Installer.Msi.TargetPath)"/>
    </Chain>

注意：

这里的 Walterlv.Installer.Msi 是前一篇教程中引用的项目的名称，你可以改成你自己的生成 MSI 的项目的名称。
Compressed="yes" 表示此 MSI 包会被嵌入到最终生成的 exe 文件中（反之则会松散地放到外部文件中）。可选值为 yes no default，对于 MSI 文件会默认嵌入，所以也可以不指定。

编辑基本的安装包信息

与 MSI 包一样，不填写基本的安装信息也会报编译错误：

▲ 缺少厂商信息

    <Product Id="*"
--           Name="Walterlv.Installer.Msi"
++           Name="Walterlv.Demo.MainApp"
             Language="1033"
             Version="1.0.0.0"
--           Manufacturer=""
++           Manufacturer="walterlv"
             UpgradeCode="2aeffe1a-8bb6-4b06-b1c0-feca18e17cf7">
--  <Bundle Name="Walterlv.Installer.Exe"
++  <Bundle Name="Walterlv.Demo.MainApp"
            Version="1.0.0.0"
--          Manufacturer=""
++          Manufacturer="walterlv"
--          UpgradeCode="528f80ca-a8f5-4bd4-8131-59fdcd69a411">
++          UpgradeCode="2aeffe1a-8bb6-4b06-b1c0-feca18e17cf7">

这里的 UpgradeCode 如果改成和之前的 MSI 文件的一样，那么无论是做成 MSI 还是 EXE 格式的安装包，他们都是可以互相被升级的。

当然，对于一个 Bundle 来说可以集合多个安装包。当要一次安装多个 MSI 包的时候，建议选不一样的 UpgradeCode。

关于设置 MSI 和 EXE 安装包的 UpgradeCode 的更多细节，可以阅读我的另一篇博客：

MSI 和 EXE 的 UpgradeCode 应该设置成相同还是不同？

测试效果

现在，我们完成了一个最简单的 EXE 安装包，测试安装一下。

前往 EXE 文件的输出目录（在项目目录的 bin\Debug 下）：

▲ 前往 EXE 文件的输出目录

双击安装，可以出现默认的安装界面：

▲ 默认的安装界面

安装完后，可以在系统设置“应用和功能”以及“Program Files”目录中找到它：

▲ 系统设置应用和功能

测试完成后，记得及时卸载掉这个包。虽然这次没什么影响，但后续我们会学到的某个操作可能导致未及时卸载的包再也无法通过正常途径卸载，所以请保持良好的习惯。（虚拟机调试的小伙伴可无视）。

▲ 卸载包

另外，觉得不错可以提交一下代码，方便后续章节的学习。

附源代码

附上必要的源码，避免你在阅读教程时因模板文件的版本差异造成一些意料之外的问题。

Bundle.wxs

// 除了本文所说的改动外，本文件的其他内容均保持模板文件的原始模样。

<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
  <Bundle Name="Walterlv.Demo.MainApp"
          Version="1.0.0.0"
          Manufacturer="walterlv"
          UpgradeCode="528f80ca-a8f5-4bd4-8131-59fdcd69a411">
    <BootstrapperApplicationRef Id="WixStandardBootstrapperApplication.RtfLicense" />

    <Chain>
      <MsiPackage Compressed="yes"
                  SourceFile="$(var.Walterlv.Installer.Msi.TargetPath)"/>
    </Chain>
  </Bundle>
</Wix>

0x800b0109 - 已处理证书链，但是在不受信任提供程序信任的根证书中终止。

Fri, 16 Jul 2021 09:51:20 +0000

有时在安装程序时无法安装出现错误，或者在更新某些系统组件时也遇到同样的错误：“已处理证书链，但是在不受信任提供程序信任的根证书中终止。”。

本文介绍其原因和解决方法。

错误

▲ 错误提示 - 来自 .NET Framework

▲ 错误提示 - 来自WiX 入门教程

错误码：0x800b0109。

已处理证书链，但是在不受信任提供程序信任的根证书中终止。

A certificate chain processed, but terminated in a root certificate which is not trusted by the trust provider.

使用 err 工具来查询此错误码也能得到相同的提示：

❯ err 800b0109
# for hex 0x800b0109 / decimal -2146762487
  CERT_E_UNTRUSTEDROOT                                           winerror.h
# A certificate chain processed, but terminated in a root
# certificate which is not trusted by the trust provider.
# 1 matches found for "800b0109"

原因

操作系统中不含此 .NET Framework 版本需要验证的在有效时间内的微软根证书（Microsoft Root Certificate Authority 2011）。

目前已知最新版的 Windows 7 SP1 (x86) 系统在未安装系统所需补丁的情况下不带此证书，而 Windows 7 SP1 (x64) 系统的最新版带有此证书。其他更(gèng)新的 Windows 8、Windows 10 全系都带有此证书。

解决

为系统安装有效的微软证书即可。

第一步：下载证书 MicrosoftRootCertificateAuthority2011.zip，下载完后解压得到 MicrosoftRootCertificateAuthority2011.cer 文件。（你也可以从其他已安装证书的电脑上导出。）

第二步：双击安装证书。

点击“安装证书”，下一步；
选择“将所有的证书放入下列存储”，然后选择“浏览…”；
选择“受信任的证书办法机构”，然后选择“下一步”；
在“安全性警告”中，点击“是”。

最后，重新安装 .NET Framework 或者其他程序即可。

WiX Toolset 安装包制作入门教程（目录篇）

Fri, 16 Jul 2021 09:48:46 +0000

WiX 全称为 Windows Installer XML，是使用 XML 文件创建 Windows 安装程序的一组工具集。它开源且完全免费。

虽然这一组工具集功能非常强大，但学习曲线较陡峭，在没有人指导的情况下独立完成完整的安装包制作会比较困难。对安装包技术零基础的开发者，甚至仅凭阅读官方文档的教程系列也难以完成 Hello World 级别的安装包制作。所以本系列博客的出现旨在填补官方教程系列的这一空缺，希望零基础的开发者也能在本教程的帮助下独立完成整套安装包的制作。

系列教程说明

截至 2021 年 7 月，WiX 4 尚处在预览阶段，所以本系列教程基于 WiX 3 进行。
本系列教程所需的所有源代码都已在 GitHub 上开源，你可以克隆下来学习和试验，也可以选择性忽略。
如果你在阅读教程时发现有些步骤不对（或者按步骤完成后依然无法跑通，或者遇到了各种奇葩问题），欢迎在评论区留言，或加我的 QQ 交流（450711383）。

分类 Hello World

WiX 能制作不同种类的安装包，各类安装包的制作方法不同，做 Hello World 所需的步骤也不一样。所以这里分一下类，每个类别都可从零开始完成整个类别的 Hello World。

你可以挑自己想做的安装包类型，然后直接在这个类别里面从第一篇读至最后一篇。

msi 格式安装包的 Hello World

exe 格式安装包的 Hello World

要求 .NET Framework 前置的 Hello World

使用 WPF 制作安装界面的 Hello World

你可能在 Hello World 系列中遇到的问题和解决办法汇总

方法与汇总

具体问题

基本概念和原则

在完成了前面的 Hello World 系列教程后，你需要跑完整个流程才算真正做了一个安装包。然而，由于 WiX 本身的入门并不容易，你可能需要了解一些基本的概念才能更容易地完成整个安装流程。

不用担心，这里只会涉及到完成最简流程需要用到的那些概念，更深入的概念我会在其他系列的教程里再说明。

// 未完待续…

WiX 安装包制作最佳实践：Id、UpgradeCode 应该怎么设置？

完成主要安装流程

// 未完待续…

可供查阅的资料汇总

可在 wxs 中编写的项目引用变量 $(var.ProjectName.Xxx) 系列)

其他 WiX Toolset 教程系列

WiX Toolset 安装包制作中级教程

参考资料

如何调试 WiX Burn 制作的自定义托管引导程序的 exe 安装包

Fri, 16 Jul 2021 08:47:57 +0000

WiX 本身很强大，使用本来也没那么难。奈何 WiX 3 的官方文档可读性极差且长期不更新，于是新手在使用 WiX 制作安装包时极容易出问题，导致制作的安装包各种行为不正常。

虽然我写了一系列的 WiX 安装包入门教程来帮助大家避坑，还写了一些常见问题的解决方法，但大家遇到的问题总会比我整理的要多。所以教大家

查看日志

很多时候，看日志能帮助你快速找到原因。以下是查看日志的方法：

如何查看用 WiX 制作的安装包的日志

`Debugger.Launch()`

如果安装过程能执行到你编写的 C# 代码中，那么可以在入口处加上 Debugger.Launch() 来启动调试器。

    public class Program : BootstrapperApplication
    {
        protected override void Run()
        {
++          if (Environment.GetCommandLineArgs().Contains("-debug", StringComparer.OrdinalIgnoreCase))
++          {
++              Debugger.Launch();
++          }

            // 省略其他启动代码。
        }
    }

这里我加上了一个命令行参数的判断，即如果启动安装包 exe 的时候带上了 -debug 参数，那么就启动调试器。（我用一个 - 而不是 -- 或者 / 的原因是 burn 引擎用的就是单个短线。）

对比测试

如果出现的问题日志上说明不明显，代码也没执行到自定义引导程序部分，那么可以考虑对照正常状态的 WiX 项目替换组件调查。这可以快速将问题范围定位到某个文件甚至是某行代码上。

例如在制作 WPF 安装包界面的教程中，我们有四个项目。这个示例已经开源到 GitHub 上了。于是我们可以尝试将出问题的项目中的部分模块替换成这个正常的项目对应部分。当最终能正常工作时，最近替换的模块便最有可能是问题模块。

用 WiX Burn 制作托管安装包：出现 0x80131508 错误

Fri, 16 Jul 2021 06:24:33 +0000

使用 WiX 的 Burn 引擎制作自定义托管引导程序的 exe 安装包时，双击生成的安装包没有反应。如果查看日志可以发现有 0x80131508 错误。本文介绍其调查和解决方法。

现象

双击制作的自定义引导程序的 exe 安装包没有反应，通过查看 Burn 引擎的输出日志可以发现如下关键的错误码：

...
[BCD8:B4DC][2021-07-16T11:47:32]i000: Loading managed bootstrapper application.
[BCD8:B4DC][2021-07-16T11:47:32]e000: Error 0x80131508: Failed to create the managed bootstrapper application.
[BCD8:B4DC][2021-07-16T11:47:32]e000: Error 0x80131508: Failed to create UX.
[BCD8:B4DC][2021-07-16T11:47:32]e000: Error 0x80131508: Failed to load UX.
[BCD8:B4DC][2021-07-16T11:47:32]e000: Error 0x80131508: Failed while running 
...
[BCD8:B4DC][2021-07-16T11:47:32]e000: Error 0x80131508: Failed to run per-user mode.
[BCD8:B4DC][2021-07-16T11:47:32]i007: Exit code: 0x80131508, restarting: No

调查

通过查询 HRESULT 错误码 0x80131508 可以得知它代表的意思是“INDEXOUTOFRANGE”。啊这……说明是 Burn 引擎出现了内部因为某些原因出现了错误，并且没有正确把错误原因标记出来。

然而对我们简单的托管安装包界面来说，更可能是我们自己的某些配置或代码不正确，导致 Burn 引擎内部代码炸掉的。

解决

这样的错误几乎不具有可调试性。因此，我直接将我偶然发现的原因和解决办法贴出来。

参考这篇入门教程中的代码，如果 AssemblyInfo.cs 文件中缺少标记 BootstrapperApplication 类型的特性，那么就会出现此错误。

...
++  using Microsoft.Tools.WindowsInstallerXml.Bootstrapper;

++  using Walterlv.InstallerUI;

++  [assembly: BootstrapperApplication(typeof(Program))]
...

然而呀，官方在教大家写托管引导程序的时候，翻遍了整个文档都没有提醒过要写这个特性！所以特别容易被官方文档带偏，这里记录此文章避免大家踩坑。

用 WiX 制作安装包：设置的 .NET Framework 前置会始终安装，即使目标电脑已经自带或装好

Fri, 16 Jul 2021 04:08:39 +0000

使用 WiX 的 Burn 引擎制作自定义托管引导程序的 exe 安装包时，你可能会遇到这种情况：明明目标电脑上已经装好了 .NET Framework，但无论如何就是会提示安装，始终不启动自定义的安装界面。

现象

即使是在开发机上（.NET Framework 已经装好），双击制作的 exe 安装包也依然会提示安装 .NET Framework：

如果强行安装，装完也依然不会启动自定义的引导程序。

小提示

这个错误其实非常有误导性！

看起来不断提示要安装 .NET Framework，会让人误以为是 .NET Framework 的安装判断条件写出了问题，然后朝着 Product.wxs 中的 Condition、Bundle.wxs 中的 InstallCondition、DetectCondition 去调查。然而这是捆绑包中的判断，与 Product.wxs 无关；我们默认用的是 WixNetFxExtension.dll 中的判断，这很靠谱，也不会出问题，所以也与 InstallCondition 和DetectCondition 无关。

正确的调查方法是去看错误日志，看真实的错误原因是什么。

当停留在这个“安装 .NET Framework”的界面时，查看 Burn 引擎的输出日志：

[14A4:9F04][2021-07-16T11:13:57]i001: Burn v3.11.2.4516, Windows v10.0 (Build 22000: Service Pack 0), path: C:\Users\lvyi\AppData\Local\Temp\{4310ECA0-6A28-4BE6-922D-570EAA81C0CD}\.cr\Walterlv.Demo.MainApp.exe
[14A4:9F04][2021-07-16T11:13:57]i009: Command Line: '-burn.clean.room=D:\WIP\Desktop\Walterlv.WixInstallerDemo\Walterlv.Installer.Exe\bin\Debug\Walterlv.Demo.MainApp.exe -burn.filehandle.attached=464 -burn.filehandle.self=460 -l debug.log'
[14A4:9F04][2021-07-16T11:13:57]i000: Setting string variable 'WixBundleOriginalSource' to value 'D:\WIP\Desktop\Walterlv.WixInstallerDemo\Walterlv.Installer.Exe\bin\Debug\Walterlv.Demo.MainApp.exe'
[14A4:9F04][2021-07-16T11:13:57]i000: Setting string variable 'WixBundleOriginalSourceFolder' to value 'D:\WIP\Desktop\Walterlv.WixInstallerDemo\Walterlv.Installer.Exe\bin\Debug\'
[14A4:9F04][2021-07-16T11:13:57]i000: Setting string variable 'WixBundleLog' to value 'D:\WIP\Desktop\Walterlv.WixInstallerDemo\Walterlv.Installer.Exe\bin\Debug\debug.log'
[14A4:9F04][2021-07-16T11:13:57]i000: Setting string variable 'WixBundleName' to value 'Walterlv.Demo.MainApp'
[14A4:9F04][2021-07-16T11:13:57]i000: Setting string variable 'WixBundleManufacturer' to value 'walterlv'
[14A4:9F04][2021-07-16T11:13:57]i000: Loading prerequisite bootstrapper application because managed host could not be loaded, error: 0x80070490.
[14A4:A444][2021-07-16T11:13:58]i000: Setting numeric variable 'WixStdBALanguageId' to value 2052
[14A4:A444][2021-07-16T11:13:58]i000: Setting version variable 'WixBundleFileVersion' to value '1.0.0.0'
[14A4:9F04][2021-07-16T11:13:58]i100: Detect begin, 2 packages
[14A4:9F04][2021-07-16T11:13:58]i000: Setting string variable 'NETFRAMEWORK45' to value '528449'
[14A4:9F04][2021-07-16T11:13:58]i052: Condition 'NETFRAMEWORK45 >= 394802' evaluates to true.
[14A4:9F04][2021-07-16T11:13:58]i101: Detected package: NetFx462Web, state: Present, cached: None
[14A4:9F04][2021-07-16T11:13:58]i101: Detected package: Walterlv.Demo.MainApp.msi, state: Absent, cached: None
[14A4:9F04][2021-07-16T11:13:58]i199: Detect complete, result: 0x0

调查

可以注意到唯一的一行错误：

Loading prerequisite bootstrapper application because managed host could not be loaded, error: 0x80070490.

加载安装前置的引导程序，因为托管宿主无法被加载，错误代码 0x80070490。所以导致弹出 .NET Framework 安装界面的原因是引导程序无法加载我们的自定义界面，误认为前置没有装好，所以弹出了前置安装界面。

查询一下错误码：

❯ err 80070490
# No results found for hex 0x4c5c75a / decimal 80070490
# for hex 0x80070490 / decimal -2147023728
  PEER_E_NOT_FOUND                                               p2p.h
  E_PROP_ID_UNSUPPORTED                                          vfwmsgs.h
# The specified property ID is not supported for the
# specified property set.%0
  WER_E_NOT_FOUND                                                werapi.h
  DRM_E_NOT_FOUND                                                windowsplayready.h
# as an HRESULT: Severity: FAILURE (1), FACILITY_WIN32 (0x7), Code 0x490
# for hex 0x490 / decimal 1168
  ERROR_NOT_FOUND                                                winerror.h
# Element not found.
# 5 matches found for "80070490"

“Not Found”，并不能给我们带来什么有价值的信息。

虽然错误码无法给我们带来有价值的信息，但那句提示至少可以让我们知道问题出在“无法加载托管宿主”这个范围。

这可能是两个范围：

我们自定义的 BootstrapperApplication 的第一行代码 Run 之前
我们自定义的 BootstrapperApplication 的第一行代码 Run 之后

这很好区分，在 Run 的第一句加上一个 “Debugger.Launch()”，看看再启动安装包的时候是否会弹出调试器选择框即可。

    protected override void Run()
    {
++      Debugger.Launch();
    }

我们就这样试一下，可以发现不会弹出调试器选择框。所以以上的两个范围只能是范围 1。

小提示

实际上按目前的日志输出，已经足以确定是范围 1 了，不过这需要一些先验知识，即托管引导程序能捕获 Run 方法中的所有异常。也就是说无论你的代码怎么写，托管引导程序都能把你引导起来，而不会出现此日志中输出的那样“无法加载托管宿主”。前面这个调查模拟没有此先验知识的情况，你可以从中学习到更多的 Burn MBA（Managed Bootstrapper Application）调试技巧。

有哪些东西会在 Run 之前？

BootstrapperCore.config 文件的配置
程序集元数据

对于 1，如果你能看出来 BootstrapperCore.config 配置出现了哪些问题更好，看不出来的话可以把现成的例子拿出来对比（例如我在入门教程里写的 DEMO 程序，记得要改项目名）。确保里面的 assemblyName 和 supportedRuntime 属性赋值正确（可参见我入门教程中写的配置和可用值说明）。

对于 2，通过实验可以得知程序集元数据出现错误时的错误码不是这个（参见：0x80131508 错误）。

于是我们也能得出问题出在 BootstrapperCore.config 配置里。

解决

可按下面的配置作为参考，将你的配置改到正确（参见我的 WiX 入门教程）：

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <sectionGroup name="wix.bootstrapper" type="Microsoft.Tools.WindowsInstallerXml.Bootstrapper.BootstrapperSectionGroup, BootstrapperCore">
      <section name="host" type="Microsoft.Tools.WindowsInstallerXml.Bootstrapper.HostSection, BootstrapperCore" />
    </sectionGroup>
  </configSections>
  <wix.bootstrapper>
    <host assemblyName="Walterlv.InstallerUI">
      <supportedFramework version="v4\Full" />
    </host>
  </wix.bootstrapper>
</configuration>

另外多说一句，官方文档对 BootstrapperCore.config 的描述非常具有误导性：

官方文档示例的注释中要大家改 host/@assemblyName，但实际上按官方文档的改法改好了就会出现本文所述的错误。

参考资料

installation - Wix ExePackage always installs regardless of DetectCondition, InstallCondition, on install, or uninstall - Stack Overflow

使用 WiX 创建最简单的安装包过程中可能出现的问题和解决方案汇总

Fri, 16 Jul 2021 03:50:15 +0000

本文是 WiX Toolset 安装包制作入门教程系列中的番外篇，可前往阅读完整教程。

用 WiX 制作安装包还是有些门槛的。如果你没有完全按照我教程中提供的步骤来执行（例如你用了自己的项目名，却在复制关键代码时没有改成自己的），那么极有可能在最终生成安装包后无法运行。

本文记录一些跟着教程做时可能遇到的常见问题，帮助你在遇到问题后能及时找到解决方案。如果看完还没有解决你的问题，欢迎留言探讨，也可以尝试调试 WiX 制作的安装包。

无法启动 exe 安装包

.NET Framework 始终会安装

用 WiX 制作安装包：设置的 .NET Framework 前置会始终安装，即使目标电脑已经自带或装好

用 WiX Burn 制作托管安装包：出现 0x80070002 错误

Fri, 16 Jul 2021 02:48:59 +0000

使用 WiX 的 Burn 引擎制作自定义托管引导程序的 exe 安装包时，双击生成的安装包没有反应。如果查看日志可以发现有 0x80070002 错误。本文介绍其调查和解决方法。

现象

双击制作的自定义引导程序的 exe 安装包没有反应，通过查看 Burn 引擎的输出日志可以发现如下关键的错误码：

...
[1874:8D8C][2021-07-15T19:28:29]i000: Loading managed bootstrapper application.
[1874:8D8C][2021-07-15T19:28:29]e000: Error 0x80070002: Failed to create the managed bootstrapper application.
[1874:8D8C][2021-07-15T19:28:29]e000: Error 0x80070002: Failed to create UX.
[1874:8D8C][2021-07-15T19:28:29]e000: Error 0x80070002: Failed to load UX.
[1874:8D8C][2021-07-15T19:28:29]e000: Error 0x80070002: Failed while running 
...
[1874:8D8C][2021-07-15T19:28:29]e000: Error 0x80070002: Failed to run per-user mode.
[1874:8D8C][2021-07-15T19:28:29]i007: Exit code: 0x80070002, restarting: No

调查

通过查询 HRESULT 错误码 0x80070002 可以得知它代表的意思是“文件不存在”。

❯ err 0x80070002
# for hex 0x80070002 / decimal -2147024894
  COR_E_FILENOTFOUND                                             corerror.h
  DIERR_NOTFOUND                                                 dinput.h
  DIERR_OBJECTNOTFOUND                                           dinput.h
  STIERR_OBJECTNOTFOUND                                          stierr.h
  DRM_E_WIN32_FILE_NOT_FOUND                                     windowsplayready.h
  E_FILE_NOT_FOUND                                               wpc.h
# as an HRESULT: Severity: FAILURE (1), FACILITY_NTWIN32 (0x7), Code 0x2
# for hex 0x2 / decimal 2
  STATUS_WAIT_2                                                  ntstatus.h
# as an HRESULT: Severity: FAILURE (1), FACILITY_WIN32 (0x7), Code 0x2
  ERROR_FILE_NOT_FOUND                                           winerror.h
# The system cannot find the file specified.
# 8 matches found for "0x80070002"

所以到底是什么不存在呢？

这篇入门教程中，涉及到找不到托管引导程序（WiX 官方喜欢称之为 MBA，Managed Bootstrapper Application）的地方可能有这些：

Bundle.wxs 文件中将托管引导程序加入到负载的地方
BootstrapperCore.config 文件中，设置的 assemblyName 属性

对于 1，如果加入到负载时文件不存在，那么这个 Bundle.wxs 所在的项目都无法编译通过，所以 1 原因可以排除。那么只剩下原因 2 了，如果发现其名称与实际程序集名称不一样（例如改了项目名，或者从教程中复制了代码却没有对应改成自己项目中的名字），那么原因就是这个了。

解决

修改 BootstrapperCore.config 文件（在这篇教程中是 App.config 文件），将 assemblyName 的值改为正确的托管引导程序（MBA）的名字。

如何查看用 WiX 制作的安装包的日志

Thu, 15 Jul 2021 12:18:52 +0000

如果你使用 WiX 制作安装包，并且遇到了问题，一定需要一个趁手的调试方案。本文介绍如何查看 WiX 制作的安装包的日志。

WiX 使用 Burn 引擎来制作 exe 捆绑包，默认情况下 Burn 引擎使用自带的安装界面来执行安装。Burn 引擎提供了自定义引导程序的功能，于是你可以利用 Burn 引擎做出自己的 UI 来。比如用 WPF 来制作安装包界面。

因此，我们有通用的方法来查看安装日志，只需要在启动安装程序时传入参数：

> .\Walterlv.Demo.MainApp.exe -l "debug.log"

其中，Walterlv.Demo.MainApp.exe 是我在 WiX 入门教程系列中使用的安装包名。-l "debug.log" 表示在当前目录下使用“debug.log”文件记录日志。

以下是一个成功运行的自定义捆绑包的日志：

[476C:2F20][2021-07-15T19:35:43]i001: Burn v3.11.2.4516, Windows v10.0 (Build 22000: Service Pack 0), path: C:\Users\lvyi\AppData\Local\Temp\{AC43FA57-2BC7-45FA-8A6C-B8ADABB376C7}\.cr\Walterlv.Demo.MainApp.exe
[476C:2F20][2021-07-15T19:35:44]i009: Command Line: '-burn.clean.room=D:\WIP\Desktop\Walterlv.WixInstallerDemo\Walterlv.Installer.Exe\bin\Debug\Walterlv.Demo.MainApp.exe -burn.filehandle.attached=684 -burn.filehandle.self=692 -l debug.log'
[476C:2F20][2021-07-15T19:35:44]i000: Setting string variable 'WixBundleOriginalSource' to value 'D:\WIP\Desktop\Walterlv.WixInstallerDemo\Walterlv.Installer.Exe\bin\Debug\Walterlv.Demo.MainApp.exe'
[476C:2F20][2021-07-15T19:35:44]i000: Setting string variable 'WixBundleOriginalSourceFolder' to value 'D:\WIP\Desktop\Walterlv.WixInstallerDemo\Walterlv.Installer.Exe\bin\Debug\'
[476C:2F20][2021-07-15T19:35:44]i000: Setting string variable 'WixBundleLog' to value 'D:\WIP\Desktop\Walterlv.WixInstallerDemo\Walterlv.Installer.Exe\bin\Debug\debug.log'
[476C:2F20][2021-07-15T19:35:44]i000: Setting string variable 'WixBundleName' to value 'Walterlv.Demo.MainApp'
[476C:2F20][2021-07-15T19:35:44]i000: Setting string variable 'WixBundleManufacturer' to value 'walterlv'
[476C:2F20][2021-07-15T19:35:44]i000: Loading managed bootstrapper application.
[476C:2F20][2021-07-15T19:35:44]i000: Creating BA thread to run asynchronously.
[476C:A250][2021-07-15T19:35:44]i000: Running the Walterlv.InstallerUI.
[476C:A250][2021-07-15T19:35:59]i000: Exiting the Walterlv.InstallerUI.
[476C:A250][2021-07-15T19:35:59]i000: The Walterlv.InstallerUI has exited.
[476C:2F20][2021-07-15T19:35:59]i500: Shutting down, exit code: 0x0
[476C:2F20][2021-07-15T19:35:59]i410: Variable: WixBundleAction = 5
[476C:2F20][2021-07-15T19:35:59]i410: Variable: WixBundleElevated = 0
[476C:2F20][2021-07-15T19:35:59]i410: Variable: WixBundleLog = D:\WIP\Desktop\Walterlv.WixInstallerDemo\Walterlv.Installer.Exe\bin\Debug\debug.log
[476C:2F20][2021-07-15T19:35:59]i410: Variable: WixBundleManufacturer = walterlv
[476C:2F20][2021-07-15T19:35:59]i410: Variable: WixBundleName = Walterlv.Demo.MainApp
[476C:2F20][2021-07-15T19:35:59]i410: Variable: WixBundleOriginalSource = D:\WIP\Desktop\Walterlv.WixInstallerDemo\Walterlv.Installer.Exe\bin\Debug\Walterlv.Demo.MainApp.exe
[476C:2F20][2021-07-15T19:35:59]i410: Variable: WixBundleOriginalSourceFolder = D:\WIP\Desktop\Walterlv.WixInstallerDemo\Walterlv.Installer.Exe\bin\Debug\
[476C:2F20][2021-07-15T19:35:59]i410: Variable: WixBundleProviderKey = {87942d31-3870-42ca-8100-4e381772c7d6}
[476C:2F20][2021-07-15T19:35:59]i410: Variable: WixBundleSourceProcessFolder = D:\WIP\Desktop\Walterlv.WixInstallerDemo\Walterlv.Installer.Exe\bin\Debug\
[476C:2F20][2021-07-15T19:35:59]i410: Variable: WixBundleSourceProcessPath = D:\WIP\Desktop\Walterlv.WixInstallerDemo\Walterlv.Installer.Exe\bin\Debug\Walterlv.Demo.MainApp.exe
[476C:2F20][2021-07-15T19:35:59]i410: Variable: WixBundleTag = 
[476C:2F20][2021-07-15T19:35:59]i410: Variable: WixBundleUILevel = 4
[476C:2F20][2021-07-15T19:35:59]i410: Variable: WixBundleVersion = 1.0.0.0
[476C:2F20][2021-07-15T19:35:59]i007: Exit code: 0x0, restarting: No

用 WiX 制作安装包：制作 WPF 安装包界面（入门篇）

Thu, 15 Jul 2021 11:52:35 +0000

本文是 WiX Toolset 安装包制作入门教程系列中的一篇，可前往阅读完整教程。

前面我们制作完成了一个可自动安装 .NET Framework 依赖的 exe 安装包，下面我们将学习制作自己的安装界面。本文使用 WPF 制作安装包界面。

本文准备做什么？

本文将继续在前一篇文章的解决方案基础上继续学习。

我们将做这些事情：

创建一个 WPF 项目，用来做安装包的 UI
处理一下这个 WPF 项目，使其对接 WiX 的捆绑包
修改用来生成 exe 格式安装包的捆绑包项目，使其接入 WPF UI 项目

创建 WPF 项目

为我们的解决方案新建一个 WPF 项目。

创建好后，我们需要双击这个 WPF 项目名，以编辑其项目文件，把框架改为 .NET Framework。

--  <Project Sdk="Microsoft.NET.Sdk">
++  <Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">

      <PropertyGroup>
        <OutputType>WinExe</OutputType>
--      <TargetFramework>net5.0-windows</TargetFramework>
++      <TargetFramework>net462</TargetFramework>
        <UseWPF>true</UseWPF>
      </PropertyGroup>

    </Project>

为了后面能适配 WiX 捆绑包，我们先建一个 Program.cs 文件作为启动文件。（名字随便取，我用 Program 只是为了体现出它是一个入口。）

在 Program.cs 里写一个 Main 方法替代 App.xaml 自动生成的 Main：

namespace Walterlv.InstallerUI
{
    public class Program
    {
        [STAThread]
        public static int Main(string[] args)
        {
            // 这里的代码仅为调试使用，在最终的项目中无任何用途。
            var app = new App();
            return app.Run();
        }
    }
}

然后，设置此 WPF UI 项目的属性，将启动对象修改成我们新建的 Program 类：

因为 App.xaml 里面有实质上的有效代码（StartupUri="MainWindow.xaml"），所以我们需要调用 InitializeComponent 来使这段代码生效。打开 App.xaml.cs 文件，我们加一个构造函数：

    public partial class App : Application
    {
++      public App()
++      {
++          InitializeComponent();
++      }
    }

至此，我们便能直接启动我们的 Walterlv.InstallerUI 项目了。这对后续的调试很有用。

小提示

实际上，这个 WPF UI 项目本应该做成 dll 而不是 exe，然后 App.xaml 和 App.xaml.cs 应该被删掉。这样，这个 WPF UI 项目就是一个纯 UI 库，用于后面被捆绑包调用。

但是，为了让这个项目与普通的 WPF 应用程序项目目录结构一样，也为了后续方便直接从 Visual Studio 启动调试，所以我刻意做成一个 exe，并保留了 App.xaml 和 App.xaml.cs 文件。

将 WPF UI 项目对接 WiX 捆绑包

1. 添加“BootstrapperCore.dll”引用

现在，为此 WPF UI 项目添加“BootstrapperCore.dll”引用：

在项目的“依赖项”上右键，“添加引用…”；
点击“浏览…”；
找到 Wix Toolset 的安装目录（如果没改，那么应该在 C:\Program Files (x86)\WiX Toolset v3.11\SDK 这样的地方），找到 BootstrapperCore.dll 文件选中然后添加；
点击“确定”。

注意，WPF 项目并不像 WiX 项目一样针对引用的绝对路径进行了属性引用处理，因此我们需要自己来做这件事。双击 WPF UI 的项目名称以修改项目文件，将绝对路径改成环境变量引用 $(WIX)（注意这里引用的是环境变量，而不是之前的 MSBuild 属性，虽然写法一模一样）：

    <ItemGroup>
      <Reference Include="BootstrapperCore">
--      <HintPath>C:\Program Files (x86)\WiX Toolset v3.11\SDK\BootstrapperCore.dll</HintPath>
++      <HintPath>$(WIX)\SDK\BootstrapperCore.dll</HintPath>
      </Reference>
    </ItemGroup>

小提示

本教程前面为了不引入过多的复杂度，没有使用 NuGet 包中的工具集而是单独下载了；所以实际上大家已经有了现成的工具集可供引用，我们才能使用此方法修改引用路径。并且此方法也能确保 WiX 打包项目使用的工具集版本和 WPF UI 项目使用的工具集版本一致。然而使用 WiX 的 NuGet 包有额外的好处，可以使得团队成员无需每人单独安装 Wix 工具集即可完整编译安装包。不过这涉及到一些 NuGet 相关的高级操作，我在其他博客里有说到。为了保证教程依然便于入门，所以我使用单独安装 WiX 工具集的方式来讲解。如果大家感兴趣使用 NuGet 的方式来完成整个打包项目的构建，替代现在单独安装的方式，我可以单独再写一篇高级教程。

2. 实现自己的引导程序（Bootstrapper）

修改 Program.cs 文件，我们要实现自己的引导程序（Bootstrapper）：

++  using Microsoft.Tools.WindowsInstallerXml.Bootstrapper;

    namespace Walterlv.InstallerUI
    {
--      public class Program
++      public class Program : BootstrapperApplication
        {
            private static int Main(string[] args)
            {
                // 这里的代码仅为调试使用，在最终的项目中无任何用途。
                var app = new App();
                return app.Run();
            }
++
++          protected override void Run()
++          {
++              // 稍后要在这里添加安装流程控制。
++          }
        }
    }

在引导程序的入口代码（就是 Run 方法）里，我们要实现基本的安装流程控制。最重要的，当然是向本文第一节那样，把 App 跑起来。

++  using System;
++  using System.Reflection;
++  using System.Windows;
...
        protected override void Run()
        {
--          // 稍后要在这里添加安装流程控制。
++          Engine.Log(LogLevel.Standard, "Running the Walterlv.InstallerUI.");
++          try
++          {
++              LaunchUI();
++              Engine.Log(LogLevel.Standard, "Exiting the Walterlv.InstallerUI.");
++              Engine.Quit(0);
++          }
++          catch (Exception ex)
++          {
++              Engine.Log(LogLevel.Error, $"The Walterlv.InstallerUI is failed: {ex}");
++              Engine.Quit(-1);
++          }
++          finally
++          {
++              Engine.Log(LogLevel.Standard, "The Walterlv.InstallerUI has exited.");
++          }
        }
++
++      private int LaunchUI()
++      {
++          // 设置 WPF Application 的资源程序集，避免 WPF 自己找不到。
++          Application.ResourceAssembly = Assembly.GetExecutingAssembly();
++
++          // 正常启动 WPF Application。
++          var app = new App();
++          return app.Run();
++      }
...

在这段代码中，我们做了这些事情：

在 Run 方法中全程记录日志（使用 BootstrapperApplication 基类 Engine 属性的 Log 方法来记）；
做了全局异常处理（避免因出现未知异常导致安装程序无法退出又看不到界面）；
正常退出安装过程（通过调用 Engine.Quit）；
设置 WPF 资源程序集（默认情况下 WPF 会去入口程序集中找，但在 WiX 引导启动后入口程序集为 null，所以我们需要手动指定资源程序集为本程序集）；
正常启动 WPF 的 Application。

接下来，在 AssemblyInfo.cs 文件中，我们将 Program 类标记为自定义的引导程序：

...
++  using Microsoft.Tools.WindowsInstallerXml.Bootstrapper;

++  using Walterlv.InstallerUI;

++  [assembly: BootstrapperApplication(typeof(Program))]
...

至此，WPF UI 项目的纯 WPF 代码部分已经完成。

3. 添加 BootstrapperCore.config 文件

WiX 要引导到我们自己写的 WPF UI 上启动需要一个关键的配置文件 BootstrapperCore.config。在最终生成的捆绑包中，这个配置文件必须严格使用此名称。

一个典型的 BootstrapperCore.config 文件的完整内容如下：

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <sectionGroup name="wix.bootstrapper" type="Microsoft.Tools.WindowsInstallerXml.Bootstrapper.BootstrapperSectionGroup, BootstrapperCore">
      <section name="host" type="Microsoft.Tools.WindowsInstallerXml.Bootstrapper.HostSection, BootstrapperCore" />
    </sectionGroup>
  </configSections>
  <startup useLegacyV2RuntimeActivationPolicy="true">
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.6.2" />
  </startup>
  <wix.bootstrapper>
    <host assemblyName="Walterlv.InstallerUI">
      <supportedFramework version="v4\Full" />
    </host>
  </wix.bootstrapper>
</configuration>

这个文件并不是 WPF UI 项目必须的文件，却是最终捆绑包所必须的文件。所以这个文件即可放到 WPF UI 项目中，也可放到 exe 的打包项目中。但是我们可以留意到 <startup> 元素的全部内容跟一个标准 .NET Framework 应用程序的配置文件中的 <startup> 元素一模一样，所以实际上我推荐把此文件放到 WPF UI 项目中，以提升代码复用性。

于是，我们来创建这个文件：

在 WPF UI 项目上右键，“添加”，“新建项…”；
在模板中找到“应用程序配置文件”，然后点“添加”。

通过模板生成的文件里有个空的 configuration 元素，我们可以无视；然后将以下内容复制到你的 App.config 文件中：

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <sectionGroup name="wix.bootstrapper" type="Microsoft.Tools.WindowsInstallerXml.Bootstrapper.BootstrapperSectionGroup, BootstrapperCore">
      <section name="host" type="Microsoft.Tools.WindowsInstallerXml.Bootstrapper.HostSection, BootstrapperCore" />
    </sectionGroup>
  </configSections>
  <wix.bootstrapper>
    <host assemblyName="Walterlv.InstallerUI">
      <supportedFramework version="v4\Full" />
    </host>
  </wix.bootstrapper>
</configuration>

请特别注意 1：请加上述 assemblyName 的值改成你的程序集名称（注意是程序集名称，不一定等于项目名）。

请注意 2，相比于 BootstrapperCore.config 的典型内容，我们删除了 <startup> 元素，这是因为 .NET Framework 生成应用程序配置文件时，此元素会自动生成。

还请注意 3，无论你使用 .NET Framework 4.x 的哪个版本，wix.bootstrapper->host->supportedFramework 中的 version 值请始终设为 v4\Full！不要设置成任何类似 v4.6.2、v4.8、.NETFramework,Version=v4.5 之类的值。虽然官方文档有提到可以设置成 v3.5、v4/Client 之类，但那会增加 WiX 打包项目配置的复杂程度，完成基本的打包需要配置更多（例如编写安装 .NET Framework 3.5 的代码）。

至此，WPF UI 项目的所有代码已全部完成。

在捆绑包项目里接入 WPF UI 项目

现在回到我们的 Bundle.wxs 文件，我们需要做四件事情：

设置捆绑包打包项目引用 WPF UI 项目；
将捆绑包引导程序设置成托管引导程序（ManagedBootstrapperApplicationHost）；
将此 WPF UI 作为捆绑包负载放入捆绑包中；
将前面编写的 BootstrapperCore.config 文件作为捆绑包负载放入捆绑包中。

还是像之前一样添加项目引用：

接下来我们一次性把对 Bundle.wxs 的所有改变代代码贴到下面：

--  <BootstrapperApplicationRef Id="WixStandardBootstrapperApplication.RtfLicense" />
++  <BootstrapperApplicationRef Id="ManagedBootstrapperApplicationHost">
++    <Payload Name="BootstrapperCore.config" SourceFile="$(var.Walterlv.InstallerUI.TargetDir)\$(var.Walterlv.InstallerUI.TargetFileName).config"/>
++    <Payload SourceFile="$(var.Walterlv.InstallerUI.TargetPath)" />
++  </BootstrapperApplicationRef>

解读：

我们把 BootstrapperApplicationRef 的 Id 换成了 ManagedBootstrapperApplicationHost（含义为将引导程序引用的 Id 设置为托管引导程序宿主）。
我们把 WPF UI 项目中生成的配置文件用 BootstrapperCore.config 这个名字放入到了负载中。（注意，WPF UI 项目中的 App.config 编译完成后生成的文件名为“程序集名.config”，在本教程中，为“Walterlv.InstallerUI.exe.config”，而我们通过引用项目变量的方式避免 WPF UI 项目的修改对这里的代码造成影响。）
我们把 WPF UI 项目中生成的文件加入到了负载中。（在本教程中，是“Walterlv.InstallerUI.exe”。另外，如果你的 WPF UI 项目有依赖的 dll，请一并在这里加入到负载，方法是依次写多个 <Payload> 元素，将依赖的 dll 设置到 SourceFile 属性中。）

至此，拥有 WPF UI 的最简单的 exe 安装包全部完成，你可以开始调试体验了。

测试效果

现在编译 EXE 项目，然后双击运行看一下。

如果发现无法运行，请前往此篇文章调试和解决问题：

使用 WiX 创建最简单的安装包过程中可能出现的问题和解决方案汇总

如果可以正常运行，那么恭喜你，完成了 WiX 安装包入门教程的 Hello World 部分，可以进阶到入门教程的后续内容了。请回到目录：

WiX Toolset 安装包制作入门教程

运行效果：

关闭这个界面后，安装程序也将退出。

附源代码

附上必要的源码，避免你在阅读教程时因模板文件的版本差异造成一些意料之外的问题。

由于本文最终得到的源码较多，所以也同时放了一份到 GitHub 上：

walterlv/Walterlv.WixInstallerDemo at 1b6600bb694c593894fc20cea76154b61ccf0c1f

Bundle.wxs

<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
  <Bundle Name="Walterlv.Demo.MainApp"
          Version="1.0.0.0"
          Manufacturer="walterlv"
          UpgradeCode="528f80ca-a8f5-4bd4-8131-59fdcd69a411">
    <BootstrapperApplicationRef Id="ManagedBootstrapperApplicationHost">
      <Payload SourceFile="$(var.Walterlv.InstallerUI.TargetPath)" />
      <Payload Name="BootstrapperCore.config" SourceFile="$(var.Walterlv.InstallerUI.TargetDir)\$(var.Walterlv.InstallerUI.TargetFileName).config"/>
    </BootstrapperApplicationRef>

    <Chain>
      <PackageGroupRef Id="NetFx462Web"/>
      <MsiPackage Compressed="yes"
                  SourceFile="$(var.Walterlv.Installer.Msi.TargetPath)"/>
    </Chain>
  </Bundle>
</Wix>

App.config

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <sectionGroup name="wix.bootstrapper" type="Microsoft.Tools.WindowsInstallerXml.Bootstrapper.BootstrapperSectionGroup, BootstrapperCore">
      <section name="host" type="Microsoft.Tools.WindowsInstallerXml.Bootstrapper.HostSection, BootstrapperCore" />
    </sectionGroup>
  </configSections>
  <wix.bootstrapper>
    <host assemblyName="Walterlv.InstallerUI">
      <supportedFramework version="v4\Full" />
    </host>
  </wix.bootstrapper>
</configuration>

App.xaml

<Application x:Class="Walterlv.InstallerUI.App"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:local="clr-namespace:Walterlv.InstallerUI"
             StartupUri="MainWindow.xaml">
    <Application.Resources>

    </Application.Resources>
</Application>

App.xaml.cs

using System;
using System.Collections.Generic;
using System.Configuration;
using System.Data;
using System.Linq;
using System.Threading.Tasks;
using System.Windows;

namespace Walterlv.InstallerUI
{
    /// <summary>
    /// Interaction logic for App.xaml
    /// </summary>
    public partial class App : Application
    {
        public App()
        {
            InitializeComponent();
        }
    }
}

AssemblyInfo.cs

using System.Windows;

using Microsoft.Tools.WindowsInstallerXml.Bootstrapper;

using Walterlv.InstallerUI;

[assembly: BootstrapperApplication(typeof(Program))]

[assembly: ThemeInfo(
    ResourceDictionaryLocation.None, //where theme specific resource dictionaries are located
                                     //(used if a resource is not found in the page,
                                     // or application resource dictionaries)
    ResourceDictionaryLocation.SourceAssembly //where the generic resource dictionary is located
                                              //(used if a resource is not found in the page,
                                              // app, or any theme specific resource dictionaries)
)]

Program.cs

using System;
using System.Diagnostics;
using System.Reflection;
using System.Windows;

using Microsoft.Tools.WindowsInstallerXml.Bootstrapper;

namespace Walterlv.InstallerUI
{
    public class Program : BootstrapperApplication
    {
        [STAThread]
        public static int Main(string[] args)
        {
            // 这里的代码仅为调试使用，在最终的项目中无任何用途。
            var app = new App();
            return app.Run();
        }

        protected override void Run()
        {
            Engine.Log(LogLevel.Standard, "Running the Walterlv.InstallerUI.");
            try
            {
                LaunchUI();
                Engine.Log(LogLevel.Standard, "Exiting the Walterlv.InstallerUI.");
                Engine.Quit(0);
            }
            catch (Exception ex)
            {
                Engine.Log(LogLevel.Error, $"The Walterlv.InstallerUI is failed: {ex}");
                Engine.Quit(-1);
            }
            finally
            {
                Engine.Log(LogLevel.Standard, "The Walterlv.InstallerUI has exited.");
            }
        }

        private int LaunchUI()
        {
            // 设置 WPF Application 的资源程序集，避免 WPF 自己找不到。
            Application.ResourceAssembly = Assembly.GetExecutingAssembly();

            // 正常启动 WPF Application。
            var app = new App();
            return app.Run();
        }
    }
}

用 WiX 制作安装包：为 WiX 制作的 msi 安装包添加 .NET Framework 环境检查

Thu, 15 Jul 2021 11:46:48 +0000

本文是 WiX Toolset 安装包制作入门教程系列中的一篇，可前往阅读完整教程。

前面我们制作完成了一个简单的 msi 安装包。如果我们要安装的程序运行需要 .NET Framework 环境，那么也可以先进行 .NET Framework 版本检查。

本文将指导你在 msi 安装前检查 .NET Framework 的版本。

本文基于前一篇文章已经建好的项目继续：

用 WiX 制作安装包：创建一个简单的 msi 安装包

添加 WixNetFxExtension 引用

在 msi 安装包项目的“Reference”上右键，“添加引用…”；
在打开的“Add Reference”窗口中确保选中的是“浏览”标签，然后在查找范围中找到 Wix Toolset 的安装目录（如果没改，那么应该在 C:\Program Files (x86)\WiX Toolset v3.11\bin 这样的地方）；
在文件列表中找到“WixNetFxExtension.dll”；
点击“添加”；
点击“确定”。

小提示

你不用担心绝对路径问题。

虽然我们前面选择的 C:\Program Files (x86)\WiX Toolset v3.11\bin 看起来是个绝对路径，但实际上在 wixproj 项目里记录的是一个属性引用，因此可以很容易在团队成员之间共享和跨版本迁移。

如下是 Walterlv.Installer.Msi.wixproj 项目文件中对 WixNetFxExtension 的引用代码：
<WixExtension Include="WixNetFxExtension">
  <HintPath>$(WixExtDir)\WixNetFxExtension.dll</HintPath>
  <Name>WixNetFxExtension</Name>
</WixExtension>

添加完 WixNetFxExtension 的引用后，还需要把它的命名空间添加到 Product.wxs 中。打开 Product.wxs 文件，在里面添加一行：

--  <Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
++  <Wix xmlns="http://schemas.microsoft.com/wix/2006/wi"
         xmlns:netfx="http://schemas.microsoft.com/wix/NetFxExtension">

注意，添加此命名空间不是必要操作，因为本教程后续没有用到此命名空间。

编辑 Product.wxs

现在，我们需要编辑 Product.wxs 文件。做两件事情：

得知当前系统环境是否已具备 .NET Framework 某版本；
根据判断结果决定此 MSI 包是否能被安装。

小提示

MSI 包只能判断 .NET Framework 是否存在，无法在不存在时执行 .NET Framework 的安装操作。如果需要安装 .NET Framework，你需要继续阅读本教程系列的 exe 打包部分。

判断 .NET Framework 是否已满足要求

因为我们已经引用了 WixNetFxExtension.dll，那里面已经写好了 .NET Framework 各版本是否存在的判断逻辑，所以我们只需要引用一下它的判断结果就好了。

在 WiX 的配置文件 wxs 里，引用一个属性的方法是使用 <PropertyRef> 元素。所以，我们在 Product.wxs 里添加这样的一行：

    <Package InstallerVersion="200" Compressed="yes" InstallScope="perMachine" />

++  <PropertyRef Id="WIX_IS_NETFRAMEWORK_462_OR_LATER_INSTALLED"/>
++
    <MajorUpgrade DowngradeErrorMessage="A newer version of [ProductName] is already installed." />

注意：

<PropertyRef> 元素必须是 <Product> 元素的直接子级；
<Package> 元素必须是 <Product> 元素的第一个子级（也就是说，<PropertyRef> 必须在 <Package> 的后面）。

决定此 MSI 包是否能被安装

紧接在刚刚那句的后面，我们再添加一句：

    <PropertyRef Id="WIX_IS_NETFRAMEWORK_462_OR_LATER_INSTALLED"/>

++  <Condition Message="This application requires .NET Framework 4.6.2. Please install the .NET Framework then run this installer again.">
++      <![CDATA[WIX_IS_NETFRAMEWORK_462_OR_LATER_INSTALLED]]>
++  </Condition>
++
    <MajorUpgrade DowngradeErrorMessage="A newer version of [ProductName] is already installed." />

这句话的意思是：

此 MSI 包安装需要满足指定条件
中间的判断条件我们用了 <![CDATA[ 和 ]]> 包裹起来了，避免判断条件中出现了一些会破坏 XML 语法的字符（如 < > 等）出现导致意外的问题（但实际上在本例中，我们只用了字母和下划线，所以你也可以直接写 WIX_IS_NETFRAMEWORK_462_OR_LATER_INSTALLED）；
如果不满足指定条件，则弹出提示信息，在 Message 属性中指定不满足条件时要弹出的信息。

不过，考虑到在卸载程序时无需检查 .NET Framework（反正也不会再运行了），所以我们可以在判断条件里加上 OR：

    <Condition Message="This application requires .NET Framework 4.6.2. Please install the .NET Framework then run this installer again.">
--      <![CDATA[WIX_IS_NETFRAMEWORK_462_OR_LATER_INSTALLED]]>
++      Installed OR WIX_IS_NETFRAMEWORK_462_OR_LATER_INSTALLED
    </Condition>

因为我们的判断条件里没有使用到 XML 特殊字符，所以我刻意删掉了 <![CDATA[ 和 ]]> 以提升可读性。有的团队为避免出错要求强制加上此包裹，有的团队为了提升可读性建议如无必要则不要加上包裹。你也可以定义你的团队规范。

Installed 属性表示当前此产品是否已安装。也就是说新的判断条件的意思是：如果当前产品已安装，或者 .NET Framework 已安装有 4.6.2 或更高版本，则满足安装条件，准许安装，否则弹出错误提示。

可供判断的 .NET Framework 版本

WiX 已开源，其中 wix3 的代码在这里：

wixtoolset/wix3: WiX Toolset v3.x

在 /src/ext/NetFxExtension/wixlib 目录下有已定义好的各种 .NET Framework 版本的判断逻辑。我整理成下表，方便大家根据自己的需要查阅：

.NET Framework 版本	对应判断属性
4.8	`WIX_IS_NETFRAMEWORK_48_OR_LATER_INSTALLED`
4.7.2	`WIX_IS_NETFRAMEWORK_472_OR_LATER_INSTALLED`
4.7.1	`WIX_IS_NETFRAMEWORK_471_OR_LATER_INSTALLED`
4.7	`WIX_IS_NETFRAMEWORK_47_OR_LATER_INSTALLED`
4.6.2	`WIX_IS_NETFRAMEWORK_462_OR_LATER_INSTALLED`
4.6.1	`WIX_IS_NETFRAMEWORK_461_OR_LATER_INSTALLED`
4.6	`WIX_IS_NETFRAMEWORK_46_OR_LATER_INSTALLED`
4.5.2	`WIX_IS_NETFRAMEWORK_452_OR_LATER_INSTALLED`
4.5.1	`WIX_IS_NETFRAMEWORK_451_OR_LATER_INSTALLED`
4.5	`WIX_IS_NETFRAMEWORK_45_OR_LATER_INSTALLED`
4	`WIX_IS_NETFRAMEWORK_40_OR_LATER_INSTALLED`

更低版本的 .NET Framework 没有直接的“是否安装”判断方法，需要根据版本号比较来判断，所以我不在此入门教程中列出。

WiX 3 不支持 .NET Core 3.x、.NET 5 以及 .NET 6 的判断。如需检查这些环境，要么需要自己写判断方法（不属于此新手教程内容），要么需要升级到 WiX 4（本教程基于 WiX 3）。见：Support .NET Standard and/or .NET Core custom Bootstrapper · Issue #6108 · wixtoolset/issues。

测试效果

现在，编译 MSI 项目，然后运行输出目录下的 msi 文件，你会……呃……看不到任何效果……因为我们的开发机上具备 .NET Framework 4.8 的环境，可完美运行 .NET Framework 4.6.2 需求的应用。

下图是我魔改了 DEMO 后在 Windows 11 上的截图（放上来就是为了平衡美感的）：

不过为了真实性，我还是找了台 Windows 7 纯净系统来测试：

如果点击“OK”，安装程序将直接退出，不会执行任何安装操作。

附源代码

附上必要的源码，避免你在阅读教程时因模板文件的版本差异造成一些意料之外的问题。

Product.wxs

// 除了本文所说的改动外，本文件的其他内容均保持模板文件的原始模样。

<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi"
     xmlns:netfx="http://schemas.microsoft.com/wix/NetFxExtension">
  <Product Id="*"
           Name="Walterlv.Demo.MainApp"
           Language="1033"
           Version="1.0.0.0"
           Manufacturer="walterlv"
           UpgradeCode="2aeffe1a-8bb6-4b06-b1c0-feca18e17cf7">
    <Package InstallerVersion="200" Compressed="yes" InstallScope="perMachine" />

    <PropertyRef Id="WIX_IS_NETFRAMEWORK_462_OR_LATER_INSTALLED"/>

    <Condition Message="This application requires .NET Framework 4.6.2. Please install the .NET Framework then run this installer again.">
      <![CDATA[WIX_IS_NETFRAMEWORK_462_OR_LATER_INSTALLED]]>
    </Condition>

    <MajorUpgrade DowngradeErrorMessage="A newer version of [ProductName] is already installed." />
    <MediaTemplate />

    <Feature Id="ProductFeature" Title="Walterlv.Installer.Msi" Level="1">
      <ComponentGroupRef Id="ProductComponents" />
    </Feature>
  </Product>

  <Fragment>
    <Directory Id="TARGETDIR" Name="SourceDir">
      <Directory Id="ProgramFilesFolder">
        <Directory Id="INSTALLFOLDER" Name="Walterlv.Installer.Msi" />
      </Directory>
    </Directory>
  </Fragment>

  <Fragment>
    <ComponentGroup Id="ProductComponents" Directory="INSTALLFOLDER">
      <Component Id="ProductComponent">
        <File Source="$(var.Walterlv.Demo.MainApp.TargetPath)" />
      </Component>
    </ComponentGroup>
  </Fragment>
</Wix>

参考资料

用 WiX 制作安装包：创建一个简单的 msi 安装包

Thu, 15 Jul 2021 11:46:48 +0000

本文是 WiX Toolset 安装包制作入门教程系列中的一篇，可前往阅读完整教程。

本文将带大家制作一个简单的 msi 安装包。

本文操作基于系列教程中的一个最简项目，见准备一个用于学习 WiX 安装包制作的 Visual Studio 解决方案。如果你没准备这样的项目，拿一个现成的项目也行，毕竟打包对目标程序的形式没有任何要求，只要是一个能跑起来的程序即可。

创建 WiX MSI 项目

在解决方案上右键，“添加”->“新建项目…”，然后在“添加新项目”窗口中搜索“WiX”，找到“Setup Project for WiX v3”。按“下一步”取个名字，然后“创建”。

注意，选择的模板要注意这些要点：

图标上标记了“wix”，标签上标记了“WiX”
模板简介中说明这是在创建“MSI”文件

引用目标项目

在 WiX MSI 项目（在本教程中，我取的名字为 Walterlv.Installer.Msi）的“References”上右键，选“添加引用…”；
在打开的“Add Reference”窗口中选择“项目”标签；
选中希望打包的项目；
点“添加”；
点“确定”。

编辑 Product.wxs 文件

添加要打包的文件

在 Product.wxs 文件中，找到提示你放文件、注册表项和其他资源的注释“”：

把周围的“Component”解除注释（因为我们真的要加打包的文件了）；
删除“TODO”注释（本教程会继续教你如何完成打包，不需要 TODO 提示了）；
在“Component”块中添加一行 <File Source="$(var.Walterlv.Demo.MainApp.TargetPath)" />。

   <Fragment>
     <ComponentGroup Id="ProductComponents" Directory="INSTALLFOLDER">
--     <!-- TODO: Remove the comments around this Component element and the ComponentRef below in order to add resources to this installer. -->
--     <!-- <Component Id="ProductComponent"> -->
++     <Component Id="ProductComponent">
--       <!-- TODO: Insert files, registry keys, and other resources here. -->
++       <File Source="$(var.Walterlv.Demo.MainApp.TargetPath)" />
--     <!-- </Component> -->
++     </Component>
     </ComponentGroup>
   </Fragment>

注意：

这里的 Walterlv.Demo.MainApp 是上一个步骤中引用的项目的名称（不是程序集或 exe 的名称）！如果你有自己的项目名，则在此改成你自己的项目名称。
本例的目标程序只有一个文件，因此我们只放了一行，如果你要打包多个文件，可返回本教程目录页查阅其他文章。

编辑基本的安装包信息

此时，我们距离完成 msi 打包只剩最后一步了，就是填写基本的安装包信息。因为如果你不填，编译会报错：

▲ 缺少厂商信息

这个信息在 Product 标签的特性上更改：

    <Product Id="*"
--           Name="Walterlv.Installer.Msi"
++           Name="Walterlv.Demo.MainApp"
             Language="1033"
             Version="1.0.0.0"
--           Manufacturer=""
++           Manufacturer="walterlv"
             UpgradeCode="2aeffe1a-8bb6-4b06-b1c0-feca18e17cf7">

除了改了厂商（Manufacturer）之外，我还额外改了一下 Name，这个名字是最终出现在系统设置“应用和功能”中的名字，当然也是控制面板“卸载程序”中的名字。毕竟谁也不希望系统“应用和功能”里显示的名字不是真正的产品名吧……

另外，其他属性的值也值得留意。但在你明白他们的真实含义之前，不建议修改其值。

关于这些值的含义，你可以阅读我的另一篇博客：

Windows 安装包制作最佳实践：ProductCode、UpgradeCode、PackageCode 应该怎么设置？

修改输出文件名

以上 Product.wxs 修改的是安装包的信息。如果希望更改 MSI 安装包的文件名，则需要去项目的属性页里去修改，如下图：

测试效果

现在，我们完成了一个最简单的 MSI 安装包，测试安装一下。

前往 MSI 文件的输出目录（在项目目录的 bin\Debug 下）：

▲ 前往 MSI 文件的输出目录

安装完后，可以在系统设置“应用和功能”以及“Program Files”目录中找到它：

▲ 系统设置应用和功能

▲ Program Files 文件夹

另外，觉得不错可以提交一下代码，方便后续章节的学习。

附源代码

附上必要的源码，避免你在阅读教程时因模板文件的版本差异造成一些意料之外的问题。

Product.wxs

// 除了本文所说的改动外，本文件的其他内容均保持模板文件的原始模样。

<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
  <Product Id="*"
           Name="Walterlv.Demo.MainApp"
           Language="1033"
           Version="1.0.0.0"
           Manufacturer="walterlv"
           UpgradeCode="2aeffe1a-8bb6-4b06-b1c0-feca18e17cf7">
    <Package InstallerVersion="200" Compressed="yes" InstallScope="perMachine" />

    <MajorUpgrade DowngradeErrorMessage="A newer version of [ProductName] is already installed." />
    <MediaTemplate />

    <Feature Id="ProductFeature" Title="Walterlv.Installer.Msi" Level="1">
      <ComponentGroupRef Id="ProductComponents" />
    </Feature>
  </Product>

  <Fragment>
    <Directory Id="TARGETDIR" Name="SourceDir">
      <Directory Id="ProgramFilesFolder">
        <Directory Id="INSTALLFOLDER" Name="Walterlv.Installer.Msi" />
      </Directory>
    </Directory>
  </Fragment>

  <Fragment>
    <ComponentGroup Id="ProductComponents" Directory="INSTALLFOLDER">
      <Component Id="ProductComponent">
        <File Source="$(var.Walterlv.Demo.MainApp.TargetPath)" />
      </Component>
    </ComponentGroup>
  </Fragment>
</Wix>

用 WiX 制作安装包：为 WiX 制作的 exe 安装包添加 .NET Framework 前置的安装步骤

Thu, 15 Jul 2021 11:46:34 +0000

本文是 WiX Toolset 安装包制作入门教程系列中的一篇，可前往阅读完整教程。

前面我们制作完成了一个简单的 exe 安装包。如果我们要安装的程序运行需要 .NET Framework 环境，那么可以检查 .NET Framework 是否安装，如果未安装则可将其装上。

小提示

Bundle（exe 格式）的判断方法和 Product（msi 格式）的不一样，因此为 WiX 制作的 msi 安装包添加 .NET Framework 环境检查一文中所编写的代码对本文没有任何影响。因此即使跳过了那篇文章也丝毫不影响本文的学习。

本文基于前一篇文章已经建好的项目继续：

用 WiX 制作安装包：创建一个简单的 exe 安装包

背景知识

在开始给我们的 exe 安装包增加 .NET Framework 环境检查之前，我们先了解一点背景知识，以便后续步骤可以使用更专业的词汇来准确描述我们正在做的事情。

注意到我们解决方案里面的两个 wxs 文件了吗？他们分别是用来打 msi 包的 Product.wxs 和用来打 exe 包的 Bundle.wxs。这两个文件的结构分别像这样：

<!-- Product.wxs -->
<Wix>
  <Product>
    <Package />
    <!-- 其他元素 -->
  </Product>
</Wix>

<!-- Bundle.wxs -->
<Wix>
  <Bundle>
    <BootstrapperApplicationRef />
    <!-- 其他元素 -->
  </Product>
</Wix>

这里引入了两个很重要的概念：产品（Product）和捆绑包（Bundle）。<Product> 元素负责定义如何安装一个产品，而 <Bundle> 元素负责定义如何安装一组包。在 wxs 文件中，他们分别是 <Wix> 元素的直接子级，彼此拥有不同的元素特性（Attribute）和子级（Child）——相互之间不可通用。也就是说，如果哪天你在网上某处扒出来某份 WiX 安装包代码，你需要清楚到底应该把这份代码放到哪个文件中。

WiX 的官方文档中明确说明了这两个元素分别具有的不同特性和子级：

添加 WixNetFxExtension 引用

在 exe 安装包项目的“Reference”上右键，“添加引用…”；
在打开的“Add Reference”窗口中确保选中的是“浏览”标签，然后在查找范围中找到 Wix Toolset 的安装目录（如果没改，那么应该在 C:\Program Files (x86)\WiX Toolset v3.11\bin 这样的地方）；
在文件列表中找到“WixNetFxExtension.dll”；
点击“添加”；
点击“确定”。

与之前添加引用一样，虽然我们选的路径是绝对路径，但实际上写入到 wixproj 文件中的是一个属性引用，所以不会存在团队协作和跨版本迁移问题。

上次我们添加 WixNetFxExtension.dll 的引用是为了引用一个属性。而这次，我们是为了引用一个 .NET Framework 的安装包。

编辑 Bundle.wxs

现在，我们需要编辑 Bundle.wxs 文件。做两件事情：

将 .NET Framework 的安装加入到捆绑包的安装过程中；
将 .NET Framework 的安装包文件嵌入到捆绑包中或随包放到单独的文件中（可选）。

将 .NET Framework 的安装加入到捆绑包的安装过程中

WixNetFxExtension.dll 中已经自带好了各种版本的 .NET Framework 安装方法，其中每个版本都含在线安装和离线安装两种方法。

对于小型项目，我们可以考虑在线安装 .NET Framework。于是，我们在 Bundle.wxs 文件中添加一行：

    <Chain>
++    <PackageGroupRef Id="NetFx462Web"/>
      <MsiPackage Compressed="yes"
                  SourceFile="$(var.Walterlv.Installer.Msi.TargetPath)"/>
    </Chain>

对于面向大量用户的产品，我们可能需要考虑本地安装 .NET Framework。于是，我们在 Bundle.wxs 文件中添加另一行：

    <Chain>
++    <PackageGroupRef Id="NetFx462Redist"/>
      <MsiPackage Compressed="yes"
                  SourceFile="$(var.Walterlv.Installer.Msi.TargetPath)"/>
    </Chain>

以上两种方式选择一种即可，看你的需要。

WiX 已开源，其中 wix3 的代码在这里：

wixtoolset/wix3: WiX Toolset v3.x

在 /src/ext/NetFxExtension/wixlib 目录下有已定义好的各种 .NET Framework 版本的安装逻辑。我整理成下表，方便大家根据自己的需要查阅：

.NET Framework 版本	在线安装	本地安装
4.8	`NetFx48Web`	`NetFx48Redist`
4.7.2	无	`NetFx472Redist`
4.7.1	无	无
4.7	无	无
4.6.2	`NetFx462Web`	`NetFx462Redist`
4.6.1	`NetFx461Web`	`NetFx461Redist`
4.6	`NetFx46Web`	`NetFx46Redist`
4.5.2	`NetFx452Web`	`NetFx452Redist`
4.5.1	`NetFx451Web`	`NetFx451Redist`
4.5	`NetFx45Web`	`NetFx45Redist`
4 Full	`NetFx40Web`	`NetFx40Redist`
4 Client Profile	`NetFx40ClientWeb`	`NetFx40ClientRedist`

其他版本未提供安装逻辑，如果需要，你得自己写。鉴于这部分需要用到更多代码，所以我不在本入门教程内说明。如果需要的话，我单独写一篇。

将 .NET Framework 的安装包文件嵌入到捆绑包中

如果你在前一个步骤中选择的是通过 Web 的方式来安装 .NET Framework，那么此步骤就不需要了。而如果你打算将 .NET Framework 的安装包嵌入到捆绑包中或者随包放到单独的文件中，那么请继续操作。

根据 WiX 3 已开源的源码我们可以得知，本地安装 .NET Framework 时选取的目录为 redist\。对于 Bundle 捆绑包来说，这个目录指代了两种意思：

跟捆绑包的 exe 同一目录下的“redist”文件夹中；
捆绑包打包后包内的虚拟目录“redist”中。

这对应了两种本地安装时，.NET Framework 安装包的两种再分发（redistribute）方法。

来看看怎么做：

下载 .NET Framework 的离线安装包（官方下载地址（含各种版本）；
将下载好的 .NET Framework 安装包拖入到 exe 安装包项目中的根目录或任一文件夹下（也可以通过右键添加文件的方式添加）；
编辑 Bundle.wxs 文件，在 <BootstrapperApplicationRef> 内加入负载；
编辑 Bundle.wxs 文件，把 NetFx462Web 改成 NetFx462Redist。

▲ 下载 .NET Framework

--  <BootstrapperApplicationRef Id="WixStandardBootstrapperApplication.RtfLicense" />
++  <BootstrapperApplicationRef Id="WixStandardBootstrapperApplication.RtfLicense">
++    <Payload Name="redist\NDP462-KB3151800-x86-x64-AllOS-ENU.exe"
++             SourceFile="Assets\ndp462-kb3151800-x86-x64-allos-enu.exe"/>
    </BootstrapperApplicationRef>

--    <PackageGroupRef Id="NetFx462Web"/>
++    <PackageGroupRef Id="NetFx462Redist"/>

以上四个步骤完成后，你的解决方案应该像下面这样：

解释一下：

我创建了一个“Assets”文件夹用于存放刚下载好的 .NET Framework 的离线安装包（为了避免读者在概念上产生混淆，我刻意避开使用 redist 这个名字，以示说明解决方案内的文件夹结构仅为开发文件夹结构，不代表最终捆绑包内的虚拟目录结构）。
我在 <BootstrapperApplicationRef> 元素内新建了一个子元素 <Payload>（负载），其中 Name 设为 redist\NDP462-KB3151800-x86-x64-AllOS-ENU.exe（这个对应的就是最终捆绑包的虚拟目录结构），SourceFile 设为 Assets\ndp462-kb3151800-x86-x64-allos-enu.exe（这个对应的是开发时项目中的文件结构）。
每个 .NET Framework 版本都有自己对应的文件名称，如果还想继续用 WixNetFxExtension.dll 中提供的安装 .NET Framework 的功能，那么从官网下载文件后就不能改名字（WiX 中定义这些文件名是全大写的，下载下来的是全小写的，虽然实际上大小写并不影响）。

编译这个项目，去输出目录下插件，可以发现几百 KB 的安装包现在变成了 59.6MB。很明显，.NET Framework 已经嵌入到了捆绑包中。

而如果你跳过前面加 <Payload> 的步骤，那么最终生成的的 exe 将不含 .NET Framework 的安装包。如果用户此时双击这个 exe 安装文件并且当前的 .NET Framework 版本不满足要求，则会弹出一个文件选择对话框，要求用户选择正确的 .NET Framework 安装文件以继续安装过程。如果你希望避免用户选择文件，那么就需要把安装包放到 exe 文件同级目录下的 redist 文件夹中。

测试效果

现在，编译 MSI 项目，然后去没有 .NET Framework 4.6.2 的电脑上运行输出目录下的 exe 文件，可以看到已经在安装 .NET Framework 了。

附源代码

附上必要的源码，避免你在阅读教程时因模板文件的版本差异造成一些意料之外的问题。

Bundle.wxs

// 除了本文所说的改动外，本文件的其他内容均保持模板文件的原始模样。

<?xml version="1.0" encoding="UTF-8"?>
<Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
  <Bundle Name="Walterlv.Demo.MainApp"
          Version="1.0.0.0"
          Manufacturer="walterlv"
          UpgradeCode="528f80ca-a8f5-4bd4-8131-59fdcd69a411">
    <BootstrapperApplicationRef Id="WixStandardBootstrapperApplication.RtfLicense">
      <Payload Name="redist\NDP462-KB3151800-x86-x64-AllOS-ENU.exe"
               SourceFile="Assets\ndp462-kb3151800-x86-x64-allos-enu.exe"/>
    </BootstrapperApplicationRef>

    <Chain>
      <PackageGroupRef Id="NetFx462Redist"/>
      <MsiPackage Compressed="yes"
                  SourceFile="$(var.Walterlv.Installer.Msi.TargetPath)"/>
    </Chain>
  </Bundle>
</Wix>

用 WiX 制作安装包：安装 WiX Toolset 系列 Visual Studio 插件

Wed, 14 Jul 2021 09:47:10 +0000

本文是 WiX Toolset 安装包制作入门教程系列中的一篇，可前往阅读完整教程。

本文介绍安装 WiX Toolset 的两款 Visual Studio 插件，以便你能直接在 Visual Studio 里完整整套安装包的制作，无需使用命令行工具。对初学 WiX 的开发者来说比较友好。

关于插件

Wix Toolset Visual Studio Extension 为 Visual Studio 带来了这些功能：

通过模板创建 WiX 项目
支持 .wixproj 这个 WiX 专属的项目格式（只是新扩展名，里面的内容还是其他各种项目格式都用的那种）
为 WiX 打包项目提供专属的属性面板页，可供设置一些基本的属性

反正，装了这款插件能让你更容易编写和管理 WiX 安装包相关文件。

安装插件

截至目前（2021年7月），WiX Toolset 的 Visual Studio 扩展最高支持到 VS2019，因此你需要在不高于 VS2019 的扩展管理里面下载插件。

方法是：

启动 Visual Studio 2019，选“继续但无需代码”；
选菜单“扩展”->“管理扩展”；
在“联机”页中搜索“WiX”，找到“Wix Toolset Visual Studio 2019 Extension”，然后点“下载”；
接下来，关闭所有已经打开的 Visual Studio，等待自动弹出的插件安装界面；
在 VSIX Installer 界面中，点击“Modify”以应用插件的安装。

其他说明

WiX 插件暂不支持 Visual Studio 2022，毕竟到了 Visual Studio 2022 开始 VS 使用 AMD64 架构了。

如果你有自己的插件需要升级到支持 VS2022，可阅读我的另一篇博客：

Visual Studio 2022 出来啦！教你如何将 VS2019 的 VSIX 扩展/插件项目迁移到 VS2022

用 WiX 制作安装包：安装 WiX Toolset 工具集

Wed, 14 Jul 2021 09:47:10 +0000

本文是 WiX Toolset 安装包制作入门教程系列中的首篇，可前往阅读完整教程。

WiX 提供一组工具集，我们的安装包正是通过这一组工具集来编译生成的。你可以通过很多方式来安装这组工具集，本文会提到多种方案，但仅会详细说其中一种，以便让教程尽可能简单。

从官网下载安装 WiX Toolset

请前往其 GitHub 发布页下载：

Releases · wixtoolset/wix3

为了简单，可下载其中的 wix311.exe 文件。这份安装包可帮助我们更简单地部署好 WiX Toolset 的构建环境。

点击中间最大的那个按钮“Install”即可开始安装：

安装完成之后，在中间的按钮上它会提示可以安装 Visual Studio 集成：

点击这个按钮后可安装 Visual Studio 插件。关于安装此插件的详细信息，可阅读下一篇入门博客：

安装 WiX Toolset Visual Studio 插件

另特别说明一下，这个安装包界面是用 WPF 做的。是后续入门教程系列博客里也会说到如何做一个 WPF 界面的安装包。

其他安装途径

此段非新手教程部分，如果不关心可略过。

scoop 安装

如果你安装有 scoop 包管理器，可直接输入以下命令安装：

scoop install wixtoolset

这套工具是在 scoop 的 main bucket 里面的，所以无需添加新的 bucket。安装完成后会自动添加环境变量，所以即便是 scoop 安装后，也可以直接在 Visual Studio 里面正常构建安装包。

nuget 安装

以上方式均为全局安装，如果是团队合作，要求所有维护 WiX 安装包的开发人员都安装好 WiX Toolset。你也可以考虑将 WiX 安装到你的某个 Visual Studio 项目中，这样打开此项目的所有开发人员在还原 NuGet 包后都自动拥有了 WiX 全套工具集。

使用 NuGet 的方式是按项目安装的，仅此解决方案（sln）有效。安装了此 NuGet 包的项目将可完全使用 WiX 工具集（因为包里包含了构建安装包需要的 MSBuild 属性）。

以下是 NuGet 包中自带的属性一览：

<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <WixInstallPath>$(MSBuildThisFileDirectory)..\tools</WixInstallPath>
    <WixExtDir>$(WixInstallPath)\</WixExtDir>

    <WixTargetsPath>$(WixInstallPath)\wix.targets</WixTargetsPath>
    <LuxTargetsPath>$(WixInstallPath)\lux.targets</LuxTargetsPath>

    <WixTasksPath>$(WixInstallPath)\WixTasks.dll</WixTasksPath>
    <WixSdkPath>$(WixInstallPath)\sdk\</WixSdkPath>
    <WixCATargetsPath>$(WixSdkPath)wix.ca.targets</WixCATargetsPath>
  </PropertyGroup>
</Project>

如果感兴趣通过 NuGet 的方式来安装 WiX Toolset，我可以再写一篇专门使用此方式安装并在团队所有人电脑上可直接构建安装包的博客。

用 WiX 制作安装包：准备一个用于学习 WiX 安装包制作的 Visual Studio 解决方案

Wed, 14 Jul 2021 09:47:10 +0000

本文是 WiX Toolset 安装包制作入门教程系列中的一篇，可前往阅读完整教程。

严格来说，本文算不得教程，只是带大家创建一个需要被打包的项目。如果你本身对使用 Visual Studio 开发非常得心应手，本文完全可以跳过，你可以用你的任何一个现成的项目进行练手。

创建示例项目

我这里拿一个控制台项目示例，当作被打包的对象。

▲ 启动 Visual Studio 创建新项目

▲ 选择控制台应用程序作为模板

▲ 输入好项目和解决方案名称

▲ 选好目标框架

那么，我们就创建好了一个最简单的项目：

我们后续学习打包时，就需要打包这个项目生成的应用。

加入 git 版本管理

为了避免学习过程中各种修改导致文件无法还原，建议大家将此新项目加入到 git 版本管理中。

▲ 创建 Git 存储库

▲ 仅限本地

现在，我们已经准备了一个最简单的项目，可以开始后续 WiX 打包的正式学习了。

WiX 安装包制作最佳实践：Id、UpgradeCode 应该怎么设置？

Wed, 14 Jul 2021 09:46:49 +0000

在 WiX 安装包制作时，Product.wxs 文件中的 Product 标签中存在一些属性，这些属性应该如何设置才是比较合适的呢？

本文是对我另一篇入门教程博客的一点补充：

用 WiX 制作安装包：创建一个简单的 msi 安装包

Id、Version

Id：产品 Id。
Version：产品版本。

关于这两个值的变化：

如果这两个值都没有更改而构建出一个新的 MSI 安装包，那么 Windows Installer 会认为这两个包之间属于“小型更新”（Update）。
如果 Version 属性更改，而 Id 属性没有更改，那么 Windows Installer 会认为这两个包之间属于“次要升级”（Upgrade）。
如果这两个值都更改了，那么 Windows Installer 会认为这两个包之间属于“主要升级”（MajorUpgrade）。

特别把这几种升级类型的英文名称拿出来说，是因为我们在 Product.wxs 中配置升级策略时会使用到这些名称。了解这些升级方式有助于我们写出符合预期的升级策略。

如果保持 Product.wxs 文件的 Product 元素的 Id 属性为 *，那么每次构建一个 MSI 文件都会视为一次“主要升级”（MajorUpgrade）。

在没有配置升级策略的情况下，如果有两个不同的 MSI 包设置了相同的 Id 和 Version，那么当安装了其中一个之后，另一个将无法安装。双击 msi 文件时，Windows Installer 将弹出错误框：

UpgradeCode

对于同一个产品，无论其产品 Id、Version 如何变化，都应该保持 UpgradeCode 不变，以便 Windows Installer 能准确认为这是同一个产品的“主要升级”（MajorUpgrade）。

参考资料

WPF 窗口和控件的 Unloaded 事件什么情况下不会触发

Wed, 30 Jun 2021 08:11:02 +0000

WPF 中如果监听窗口或者控件的的 Unloaded 事件，那么这个事件会触发吗？答案是不确定的。

示例代码

<Window x:Class="Walterlv.TempDemo.Wpf.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        Unloaded="Window_Unloaded" Closed="Window_Closed">
    <Grid Unloaded="Grid_Unloaded">
    </Grid>
</Window>

private void Window_Unloaded(object sender, RoutedEventArgs e)
{
    // 断点 1
}

private void Grid_Unloaded(object sender, RoutedEventArgs e)
{
    // 断点 2
}

private void Window_Closed(object sender, EventArgs e)
{
    // 断点 3
}

你觉得以上事件中，断点都会进入吗？

不确定的答案

在微软的官方文档中说：

Note that the Unloaded event is not raised after an application begins shutting down. Application shutdown occurs when the condition defined by the ShutdownMode property occurs. If you place cleanup code within a handler for the Unloaded event, such as for a Window or a UserControl, it may not be called as expected.

如果应用程序正在关闭，那么 Unloaded 时间将不会触发。WPF 通过设置在 Application 上的 ShutdownMode 来决定是否在关闭窗口后关闭应用程序。因此，如果你试图通过在 Unloaded 事件中执行清理操作，那么可能不会如预期般完成。

因此，一般情况下，Unloaded 事件是会触发的，但满足如下任一情况时，此事件将不不会触发：

Application.ShutdownMode="OnLastWindowClose" 且最后一个窗口关闭时；
Application.ShutdownMode="OnMainWindowClose" 且主窗口关闭时。

顺序

当触发 Unloaded 事件时，以上事件的触发顺序为：

断点 3
断点 1
断点 2

参考资料

编译并体验 .NET MAUI 官方示例代码

Fri, 25 Jun 2021 09:36:03 +0000

在微软的 Build 2021 大会上，微软发布了 .NET 6 Preview 4，同时发布了于它的 MAUI 第四个预览版。在 MAUI 成为 Visual Studio 2022 的官方工作负载之前，成功编译并运行 MAUI 的示例程序会比较麻烦，本文旨在帮助大家完成示例程序的编译运行和体验。

更新：现在已经 .NET 6 Preview 5 了，配上 Visual Studio 2022 17.0 Preview 1 依然如本文这般麻烦。

TL;DR

本段属太长不读系列。完整版请看下一段。

截至 2021 年 5 月 31 日，要成功编译并运行 .NET MAUI 官方示例项目，你需要准备如下环境：

安装 Visual Studio 2019 16.11 Preview 1 或更高版本（否则只能编译而无法运行，旧版 VS 不知道如何调试这种项目）
安装 .NET 6 Preview 4（MAUI 示例项目要求的最低 .NET 版本）
安装 maui-check，检查并修复所有环境问题（包含各类 SDK、模拟器等）
增加 NuGet 源 https://aka.ms/maui-preview/index.json（否则无法识别用到的 MAUI 类型）

在以上都准备就绪的情况下，你只需要使用 Visual Studio 2019 16.11 Preview 1 创建 MAUI 项目或打开官方 MAUI 示例项目即可调试 MAUI 项目。

当然，预计 .NET 6 和 Visual Studio 2022 发布后，MAUI 将成为 Visual Studio 工作负载的一部分。届时，只需要在 Visual Studio 2022 里勾选 MAUI 就够了，其他什么也不用管。

安装 Visual Studio 2019 16.11 Preview 1 或更高版本

如果你电脑上已经安装过预览版的 Visual Studio，那么直接去开始菜单搜索并打开 Visual Studio Installer，然后把预览版更新到最新就好了。但如果你电脑上只有正式版的 Visual Studio，那么你需要前往预览版的下载地址下载一个预览版的在线安装包来安装。

下载 Visual Studio 预览版（常年不变的地址）

安装 .NET 6 Preview 4

你还需要将你电脑上的 .NET 更新到 .NET 6 Preview 4 或者以上的版本。

下载 .NET 6（常年不变的地址）

安装 maui-check 工具

打开你喜爱的终端，然后输入如下命令：

dotnet tool install -g redth.net.maui.check

这将在全局安装 maui-check 工具，辅助你完成 MAUI 开发环境的搭建。

工具安装完成后，直接输入命令 maui-check 然后回车运行，工具将自动检查你的电脑上是否已完成 MAUI 开发环境的搭建。它会在检查到问题之后发出轻轻的一声“嘟”，然后问你：“要尝试修复吗？（! Attempt to fix?）”你只需要打 y 告诉它要修复就好了。

这样的问题会问很多次，你都需要答 y 修复，甚至可能还需要多次运行 maui-check 工具来进行修复。

到最后，当你再次运行 maui-check 时，它会兴奋地告诉你：“Congratulations, everything looks great!”这意味着，MAUI 所需的环境已全部搭建完成。

如果 maui-check 不断失败，可阅读本文末尾一节。

增加 NuGet 源

我有另一篇博客介绍如何添加 NuGet 源，详细的方法你可以去那里看：

全局或为单独的项目添加自定义的 NuGet 源 - walterlv

要简单一点，你只需要在命令行中输入：

dotnet nuget add source -n maui-preview https://aka.ms/maui-preview/index.json

这会直接修改 %AppData%\NuGet\NuGet.Config 文件，并在其中添加一行 NuGet 源。

MAUI 官方示例仓库

在以上所有步骤执行完成之后，以下项目就能直接在 Visual Studio 2019 16.11 Preview 1 或更高版本中编译并调试了。

例如，以 maui-samples 项目举例，将 HelloMaui 项目设为启动项目，在 Visual Studio 中将启动框架设置为 .net6.0-android，就可以在 Android 模拟器中运行 HelloMaui 应用了。

以下是 HelloMaui 在 Android 模拟器中的运行效果。

另外，Visual Studio 2019 16.11 Preview 1 中已经内置了 MAUI 的项目模板，你也可以直接新建 MAUI 项目自行调试。

其他问题

无法创建 Android 模拟器

Android Emulator - x86 - API30 - Google API's not created.

如果 maui-check 时出现 Android 模拟器无法创建的错误（就像下图这样），可尝试在 Visual Studio 里手工创建一个 Android 模拟器。

在 Visual Studio 里手工创建 Android 模拟器的方法如下：

第一步：打开 Android 设备管理器

第二步：创建新设备

创建时，要注意操作系统必须选择“R 11.0 - API 30”，这是 MAUI 示例应用要求的最低版本。其他随意，然后点“创建 ”。

创建完后，等待下载、解压直至安装完成。

第三步：重新使用 maui-check 检查

这时，应该就能全部通过检查了。

无法调试 WinUI3 项目

调试官方示例中的 HelloMauiWinUI3 项目时，你可能会遇到 COM 异常“没有注册类”：

原因是，你应该将“HelloMauiWinUI3 (Package)”后缀的 WinUI 项目设为启动项，而不应该将“HelloMauiWinUI3”设为启动项。并且，调试启动时，应该选 Local Machine。

以下是我运行另一个“Weather TwentyOne”官方示例应用的截图：

参考资料

Visual Studio 2022 出来啦！教你如何将 VS2019 的 VSIX 扩展/插件项目迁移到 VS2022

Fri, 25 Jun 2021 06:05:52 +0000

从 Visual Studio 2022 开始，Visual Studio 正式启用了 amd64 架构。为了确保扩展的兼容性，Visual Studio 2022 不会启用以前编译过的扩展，即使以前编译过的扩展把支持的 Visual Studio 版本号加到了 17.0（对应 VS2022）也不行。毕竟 x64 的进程真加载一个 x86 的程序集时，会炸得体无完肤。

因为保证安全，Visual Studio 2022 仅加载专门为它开发和编译过的插件。

如果你正好有一个为 Visual Studio 2019（或更早）开发的插件，那么可以通过阅读本文完成对插件项目的升级，以支持 Visual Studio 2022。

TL;DR 最简改法

如果你赶时间，只想马上把项目改好，那么阅读这一小节就够了。

首先我们确认一下，你原来的项目至少是这样的结构：

是一个 Visual Studio 扩展项目
有一个 Visual Studio 扩展清单文件 source.extension.vsixmanifest

在此基础上，你需要修改两个文件。

source.extension.vsixmanifest：

请将原来的安装目标改成 17.0 以前和以后两个，以前的用 x86 架构，以后的用 amd64 架构。

    <Installation>
--    <InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[16.0,)" />
++    <InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[16.0, 17.0)">
++      <ProductArchitecture>x86</ProductArchitecture>
++    </InstallationTarget>
++    <InstallationTarget Id="Microsoft.VisualStudio.Community" Version="[17.0, 18.0)">
++      <ProductArchitecture>amd64</ProductArchitecture>
++    </InstallationTarget>
    </Installation>

*.csproj 文件：

必须将 VS 构建工具升级到 17.0 或以上版本。

--  <PackageReference Include="Microsoft.VSSDK.BuildTools" Version="16.9.1050" />
++  <PackageReference Include="Microsoft.VSSDK.BuildTools" Version="17.0.2140-preview2" />

如果你还有引用其他的 VS 构建工具，请一并升级到 17.0 或以上版本。升级时，此 VSIX 项目引用的其他项目（例如基于 .NET Standard 的分析器项目）无需升级 NuGet 包。

至此，你再编译这个 Visual Studio 扩展项目，即可正常在旧的 Visual Studio 2019 和新的 Visual Studio 2022 上安装：

完整改法

如果你比较强迫症，我还是建议你完整改完整个项目。完整改完后，你将获得如下好处：

在 Visual Studio 2022 里双击 source.extension.vsixmanifest 后能打开专属的清单编辑器，避免手写容易出现明显错误
csproj 项目文件里不会有之前版本为了解决一些特定的 bug 而额外写的 bugfix 代码

完整改法，即使用 Visual Studio 2022 来创建新的 VSIX 扩展项目。

第一步：请确保已安装 SDK

在开始菜单找到并启动 Visual Studio Installer，然后确保勾选 Visual Studio 扩展开发的工作负载，并将右边的 .NET Compiler Platform SDK 勾选。前者提供编写和调试扩展的能力，而后者提供了新建模板和 Roslyn 相关工具。

第二步：重新创建 VSIX 项目

新建一个 VSIX 项目：

第三步：复制并替换整个扩展文件

你可以把新创建项目的 csproj 文件和 source.extension.vsixmanifest 文件替换掉原项目的这两个文件，然后保留原项目。也可以考虑反过来操作，将原项目里的代码（如果有的话）放到新项目里来，然后保留新项目。

合并这两个项目时，记得 source.extension.vsixmanifest 文件里的清单信息要与原来的保持一致，这样才能对原来的扩展进行升级（而不会创建出新的扩展来）。

如果需要一个修改示例，你可以看我的一个 Pull Request（拉取请求）：

为插件添加 Visual Studio 2022 的支持 by walterlv · Pull Request #28 · walterlv/Walterlv.Packages

重新上传扩展到市场

前往 Visual Studio 扩展市场的管理界面 https://marketplace.visualstudio.com/manage，需要登录。

在你需要升级的扩展旁边的“…”里点“Edit”编辑。重新上传你新编译出来的 VSIX 文件，等待审核即可。

参考资料

visualstudio-docs/update-visual-studio-extension.md at master · MicrosoftDocs/visualstudio-docs

两个方法，让 WPF 绘制的笔迹更加平滑

Mon, 21 Jun 2021 09:38:14 +0000

在 WPF 中绘制笔迹的时候，你可能会注意到绘制的笔迹非常的……呃……棱角分明。这在鼠标绘制的时候大家基本都能接受，但如果遇到一些触摸框报告触摸点也那么稀疏，那么写的字很不好看。另外，还有可能绘制的笔迹点来源于其他设备，通过网络传输而来，这时更容易遇到稀疏的点。

本文将用两种方法来让 WPF 的笔迹更加平滑。

两种方法

我们有两种方法来解决这样的问题：

点插值
曲线拟合

点插值

如果导致不平滑的主要原因是点太稀疏，那么采用点插值算法可以解决很大的问题。常用的点插值算法是贝赛尔插值算法。

通过贝赛尔插值算法的具体算法和代码，可参考这篇博客：一种简单的贝塞尔拟合算法_Iron 的博客-CSDN博客。

使用以上插值算法后的效果如下（两次分别绘制，因此笔迹不一样）：

▲ 插值前

▲ 插值后

曲线拟合

WPF 的 Stroke 类型的 DrawingAttributes.FitToCurve 属性可开启或关闭笔迹的曲线拟合。

这个属性是实时生效的，所以你可以在绘制笔迹的任何时刻设置它。例如一开始绘制时设置，你将可以在书写的过程中实时得到平滑的曲线，但用户可以明显看到绘制笔迹的过程中曲线拟合的过程（可看到笔迹在来回摆动）；你也可以在笔迹绘制结束插入到画布时再设置，这样在插入时用户只会看到一次笔迹的突变。

使用以上曲线拟合后的效果如下（两次分别绘制，因此笔迹不一样）：

▲ 拟合前

▲ 拟合后

综合使用

正常情况下，仅“点插值”就足够让笔记看起来很平滑了。但如果你要求笔迹看不出棱角（例如此笔迹非用户直接书写，而是从其他平台传输过来呈现），那么你可能需要采用“曲线拟合”。然而，如果你觉得无法忍受“曲线拟合”带来的笔迹来回摆动，那么可考虑将两个方法结合起来使用。

参考资料

一种简单的贝塞尔拟合算法_Iron 的博客-CSDN博客

C# 的事件，一般你不需要担心它的线程安全问题！

Fri, 18 Jun 2021 07:42:18 +0000

时不时会有小伙伴跟我提到在 C# 写事件 += -= 以及 Invoke 时可能遇到线程安全问题。然而实际上这些操作并不会有线程安全问题，所以我特别写一篇博客来说明一下，从原理层面说说为什么不会有线程安全问题。

顺便再提一下哪种情况下你却可能遇到线程安全问题。

委托是不可变类型

委托是不可变类型。

这点很重要，这是 C# 事件一般使用场景不会发生线程安全问题的关键！

那既然委托是不可变类型，那我们在写 += -= 以及引发事件的时候，是如何处理最新注册或注销的事件呢？

`+=` 和 `-=` 的本质

我们随便写一个类型，里面包含一个事件：

using System;

namespace Walterlv.TempDemo
{
    class DemoClass
    {
        public event EventHandler SomeEvent;
    }
}

从外表上，这个事件就像一个字段一样的不线程安全。但实际上，他像一个属性一样能处理好线程安全问题。

众所周知，这个事件会编译成以下两个方法：

add_SomeEvent
remove_SomeEvent

// Methods
// Token: 0x06000001 RID: 1 RVA: 0x00002050 File Offset: 0x00000250
.method public hidebysig specialname 
    instance void add_SomeEvent (
        class [System.Runtime]System.EventHandler 'value'
    ) cil managed 
{
    .custom instance void [System.Runtime]System.Runtime.CompilerServices.CompilerGeneratedAttribute::.ctor() = (
        01 00 00 00
    )
    // Header Size: 12 bytes
    // Code Size: 41 (0x29) bytes
    // LocalVarSig Token: 0x11000001 RID: 1
    .maxstack 3
    .locals init (
        [0] class [System.Runtime]System.EventHandler,
        [1] class [System.Runtime]System.EventHandler,
        [2] class [System.Runtime]System.EventHandler
    )

    /* 0x0000025C 02           */ IL_0000: ldarg.0
    /* 0x0000025D 7B01000004   */ IL_0001: ldfld     class [System.Runtime]System.EventHandler Walterlv.TempDemo.DemoClass::SomeEvent
    /* 0x00000262 0A           */ IL_0006: stloc.0
    // loop start (head: IL_0007)
        /* 0x00000263 06           */ IL_0007: ldloc.0
        /* 0x00000264 0B           */ IL_0008: stloc.1
        /* 0x00000265 07           */ IL_0009: ldloc.1
        /* 0x00000266 03           */ IL_000A: ldarg.1
        /* 0x00000267 280D00000A   */ IL_000B: call      class [System.Runtime]System.Delegate [System.Runtime]System.Delegate::Combine(class [System.Runtime]System.Delegate, class [System.Runtime]System.Delegate)
        /* 0x0000026C 740D000001   */ IL_0010: castclass [System.Runtime]System.EventHandler
        /* 0x00000271 0C           */ IL_0015: stloc.2
        /* 0x00000272 02           */ IL_0016: ldarg.0
        /* 0x00000273 7C01000004   */ IL_0017: ldflda    class [System.Runtime]System.EventHandler Walterlv.TempDemo.DemoClass::SomeEvent
        /* 0x00000278 08           */ IL_001C: ldloc.2
        /* 0x00000279 07           */ IL_001D: ldloc.1
        /* 0x0000027A 280100002B   */ IL_001E: call      !!0 [System.Threading]System.Threading.Interlocked::CompareExchange<class [System.Runtime]System.EventHandler>(!!0&, !!0, !!0)
        /* 0x0000027F 0A           */ IL_0023: stloc.0
        /* 0x00000280 06           */ IL_0024: ldloc.0
        /* 0x00000281 07           */ IL_0025: ldloc.1
        /* 0x00000282 33DF         */ IL_0026: bne.un.s  IL_0007
    // end loop
    /* 0x00000284 2A           */ IL_0028: ret
} // end of method DemoClass::add_SomeEvent

// Token: 0x06000002 RID: 2 RVA: 0x00002088 File Offset: 0x00000288
.method public hidebysig specialname 
    instance void remove_SomeEvent (
        class [System.Runtime]System.EventHandler 'value'
    ) cil managed 
{
    .custom instance void [System.Runtime]System.Runtime.CompilerServices.CompilerGeneratedAttribute::.ctor() = (
        01 00 00 00
    )
    // Header Size: 12 bytes
    // Code Size: 41 (0x29) bytes
    // LocalVarSig Token: 0x11000001 RID: 1
    .maxstack 3
    .locals init (
        [0] class [System.Runtime]System.EventHandler,
        [1] class [System.Runtime]System.EventHandler,
        [2] class [System.Runtime]System.EventHandler
    )

    /* 0x00000294 02           */ IL_0000: ldarg.0
    /* 0x00000295 7B01000004   */ IL_0001: ldfld     class [System.Runtime]System.EventHandler Walterlv.TempDemo.DemoClass::SomeEvent
    /* 0x0000029A 0A           */ IL_0006: stloc.0
    // loop start (head: IL_0007)
        /* 0x0000029B 06           */ IL_0007: ldloc.0
        /* 0x0000029C 0B           */ IL_0008: stloc.1
        /* 0x0000029D 07           */ IL_0009: ldloc.1
        /* 0x0000029E 03           */ IL_000A: ldarg.1
        /* 0x0000029F 280F00000A   */ IL_000B: call      class [System.Runtime]System.Delegate [System.Runtime]System.Delegate::Remove(class [System.Runtime]System.Delegate, class [System.Runtime]System.Delegate)
        /* 0x000002A4 740D000001   */ IL_0010: castclass [System.Runtime]System.EventHandler
        /* 0x000002A9 0C           */ IL_0015: stloc.2
        /* 0x000002AA 02           */ IL_0016: ldarg.0
        /* 0x000002AB 7C01000004   */ IL_0017: ldflda    class [System.Runtime]System.EventHandler Walterlv.TempDemo.DemoClass::SomeEvent
        /* 0x000002B0 08           */ IL_001C: ldloc.2
        /* 0x000002B1 07           */ IL_001D: ldloc.1
        /* 0x000002B2 280100002B   */ IL_001E: call      !!0 [System.Threading]System.Threading.Interlocked::CompareExchange<class [System.Runtime]System.EventHandler>(!!0&, !!0, !!0)
        /* 0x000002B7 0A           */ IL_0023: stloc.0
        /* 0x000002B8 06           */ IL_0024: ldloc.0
        /* 0x000002B9 07           */ IL_0025: ldloc.1
        /* 0x000002BA 33DF         */ IL_0026: bne.un.s  IL_0007
    // end loop
    /* 0x000002BC 2A           */ IL_0028: ret
} // end of method DemoClass::remove_SomeEvent

于是 += 和 -= 本质上是调用了 Delegate.Combine 方法和 Delegate.Remove 方法。而 Delegate.Combine 和 Delegate.Remove 不会修改原委托，只会生成新的委托。

于是，任何时候当你拿到这个事件的一个实例，并将它存在一个变量里之后，只要不给这个变量额外赋值，这个变量包含的已注册的委托数就已经完全确定了下来。之后无论什么时候再 += 或 -= 这个事件，已经跟这个变量无关了。

`Delegate.Combine` 和 `Delegate.Remove`

现在让我们再来看看 Delegate.Combine 的实现（Remove 就不举例了，相反操作）。

[return: NotNullIfNotNull("a")]
[return: NotNullIfNotNull("b")]
public static Delegate? Combine(Delegate? a, Delegate? b)
{
    if (a is null)
        return b;

    return a.CombineImpl(b);
}

最终调用了实例的 CombineImpl 方法，不过 Delegate 基类的 CombineImpl 方法没有实现（只有个异常）。

为了实现事件的 += 和 -=，事件实际上是 MultiCastDelegate 类型，其实现如下：

// This method will combine this delegate with the passed delegate
//    to form a new delegate.
protected sealed override Delegate CombineImpl(Delegate? follow)
{
    if (follow is null)
        return this;

    // Verify that the types are the same...
    if (!InternalEqualTypes(this, follow))
        throw new ArgumentException(SR.Arg_DlgtTypeMis);

    MulticastDelegate dFollow = (MulticastDelegate)follow;
    object[]? resultList;
    int followCount = 1;
    object[]? followList = dFollow._invocationList as object[];
    if (followList != null)
        followCount = (int)dFollow._invocationCount;

    int resultCount;
    if (!(_invocationList is object[] invocationList))
    {
        resultCount = 1 + followCount;
        resultList = new object[resultCount];
        resultList[0] = this;
        if (followList == null)
        {
            resultList[1] = dFollow;
        }
        else
        {
            for (int i = 0; i < followCount; i++)
                resultList[1 + i] = followList[i];
        }
        return NewMulticastDelegate(resultList, resultCount);
    }
    else
    {
        int invocationCount = (int)_invocationCount;
        resultCount = invocationCount + followCount;
        resultList = null;
        if (resultCount <= invocationList.Length)
        {
            resultList = invocationList;
            if (followList == null)
            {
                if (!TrySetSlot(resultList, invocationCount, dFollow))
                    resultList = null;
            }
            else
            {
                for (int i = 0; i < followCount; i++)
                {
                    if (!TrySetSlot(resultList, invocationCount + i, followList[i]))
                    {
                        resultList = null;
                        break;
                    }
                }
            }
        }

        if (resultList == null)
        {
            int allocCount = invocationList.Length;
            while (allocCount < resultCount)
                allocCount *= 2;

            resultList = new object[allocCount];

            for (int i = 0; i < invocationCount; i++)
                resultList[i] = invocationList[i];

            if (followList == null)
            {
                resultList[invocationCount] = dFollow;
            }
            else
            {
                for (int i = 0; i < followCount; i++)
                    resultList[invocationCount + i] = followList[i];
            }
        }
        return NewMulticastDelegate(resultList, resultCount, true);
    }
}

计算好新委托所需的委托列表和个数后，创建一个新的委托实例，然后用计算所得的结果初始化它。这座实了委托不变，于是不存在线程安全问题。

线程安全的事件引发

从 C# 6.0 开始，大家引发事件都喜欢使用下面这样的方式：

SomeEvent?.Invoke(this, EventArgs.Empty);

不用担心，这就是线程安全的写法！

以上这个写法是空传递写法，相当于：

var handler = SomeEvent;
if (handler != null)
{
    handler.Invoke(this, EventArgs.Empty);
}

我们前面已经通过原理证实了“委托不变”，所以这里我们用变量存这个事件的时候，这个变量就完全确认了此时此刻已经注册的所有委托，后面的判空和引发都不会受与之发生在同一时刻的 += 和 -= 的影响。

有人说以上写法有可能会被编译器优化掉（《CLR via C#》说的），造成意料之外的线程安全问题，于是推荐写成下面这样：

var handler = Volatile.Read(ref SomeEvent);
if (handler != null)
{
    handler.Invoke(this, EventArgs.Empty);
}

这样写当然是没有问题的。可是这样就没有 C#6.0 带来的一句话写下来的畅快感了！实际上，你根本无需担心编译器会对你引发事件带来线程不安全的优化，因为现在的 C# 编译器和 .NET 运行时很聪明，非常清楚你是在引发事件，于是不会随便优化掉你这里的逻辑。

归根结底，只需要用 C# 6.0 的空传递操作符写引发事件就没有问题了。

是否可能出现线程不安全的情况呢？

从前面原理层面的剖析，我们可以明确知道，普通的事件 +=、-= 和引发是不会产生线程安全问题的；但这不代表任何情况你都不会遇到线程安全问题。

如果你引发事件的代码逻辑比较复杂，涉及到多次读取事件成员（例如前面例子中的 SomeEvent），那么依然会出现线程安全问题，因为你无法保证两次读取事件成员时，期间没有发生过事件的 += 和 -=。

关于 `+=` `-=` 的额外说明

在上文写完之后，有小伙伴说，C# 里面 += -= 不是线程安全的，并举了以下例子：

private int _value;

public void AddValue(int i)
{
    _value += i;
}

当并发调用 AddValue 时，可能导致部分调用的结果被另一部分覆盖，从而出现线程安全问题。

因为 _value += i 这个语法糖相当于以下句子：

var temp = _value + i;
_value = temp;

然而，事件没有这样的问题，因为事件的 += 语法糖相当于以下句子：

// demo.SomeEvent += DemoClass_SomeEvent;
// 相当于：
demo.add_SomeEvent(new EventHandler(DemoClass_SomeEvent));

注意这是一次函数调用，并没有像普通的数值运算一样执行两步计算；所以至少这一次方法调用不会有问题。

那么，add_SomeEvent 里面是线程安全的吗？如果只是单纯 Delegate.Combine 然后赋值当然不是线程安全，但它不是简单赋值，而是通过 Interlocked.CompareExchange 原子操作赋值，在保证线程安全的同时还确保了性能：

/* 0x000002B2 280100002B   */ IL_001E: call      !!0 [System.Threading]System.Threading.Interlocked::CompareExchange<class [System.Runtime]System.EventHandler>(!!0&, !!0, !!0)

转换成容易理解的 C# 代码大约是这样：

while (true)
{
    var originalValue = _value;
    var value = originalValue + add;
    var resultValue = Interlocked.CompareExchange(ref _value, value, originalValue);
    if (resultValue == value)
    {
        break;
    }
}

当 CompareExchange 的返回值与第三个参数相同，说明本次原子操作成功完成，那么赋值有效，退出循环。
当 CompareExchange 的返回值与第三个参数不同，说明本次原子操作冲突，在下一次循环中重试赋值。
因为赋值是很迅速的，所以即使大量并发，也只会有少数冲突，整体是非常快的。

完整的 IL 代码可以在本文前面看到。这里的 !!0 是引用第 0 号泛型类型，即找到 CompareExchange(!!T$, !!T, !!T):!!T 重载。

Windows 中的 HRESULT

Wed, 16 Jun 2021 02:51:05 +0000

Windows 协议文档中所描述的协议规范中，错误码使用 HRESULT、Win32 错误码和 NTSTATUS 来描述。本文科普一下 HRESULT。

一个简单的例子

我们先举一个大家可能常用的 HRESULT 例子，这样后面的介绍能更简单一点。

0x80070070

将它改写成二进制：

1000 0000 0000 0111 0000 0000 0111 0000

它的意思是“There is not enough space on the disk.”即“磁盘空间不足。”

规范中的 HRESULT

按照规范，HRESULT 的格式如下，其中首行的数字代表第几位（bit）：

0	1	2	3	4	5~15	16~31
S	R	C	N	X	Facility	Code

S: 1 位，表示严重性。为 1 表示此结果为失败，为 0 表示此结果为成功。
R: 1 位，保留位。如果 N 位是 0，那么此位必须也是 0。如果 N 位是 1，那么此位由 NTSTATUS 定义的数字范围决定。
C: 1 位，自定义位。为 1 表示由微软定义，为 0 表示由其他厂商定义。
N: 1 位。为 1 表示此结果为 NTSTATUS 错误码。
X: 1 位。保留位，应设为 0。
Facility: 11 位。设施代码。指定错误来源。后面的列表中有已定义的错误源，微软偶尔会添加新的种类。
Code: 16 位（2 字节）。错误码的其他部分，指定错误的具体细节。

其中，Facility 设施代码的详细列表可以参见这里：[MS-ERREF]: HRESULT - Microsoft Docs。对 Win32 开发来说，0x7 是很常见的，表示 FACILITY_WIN32。

Win32 错误码

现在再来看我们前面的例子：

1000 0000 0000 0111 0000 0000 0111 0000

严重性：1，表示失败
设施代码：0x7，表示 FACILITY_WIN32
错误码：0x70，表示 ERROR_DISK_FULL

所有的 Win32 错误码应该仅使用 16 位来表示，即范围从 0x0000 到 0xFFFF。关于 Win32 错误码的详细列表可以参见这里：[MS-ERREF]: Win32 Error Codes - Microsoft Docs

微软错误查询工具

如果你遇到了某个 Win32 错误码，或者 HRESULT 值，那么可以使用微软错误查询工具（The Microsoft Error Lookup Tool）查询其含义。

下载地址：Download Microsoft Error Lookup Tool from Official Microsoft Download Center

在 .NET/C# 代码中的使用

例如，我们可能需要在一些 IO 操作中处理好磁盘空间已满的情况：

try
{
    SaveFile(fileContent, filePath);
}
catch (IOException ex)
{
    if (ex.IsDiskFullException())
    {
        // 磁盘空间已满。
        break;
    }
}

由于磁盘空间已满没有对应的 .NET Exception，所以我们只能通过提取 IOException 中的 HResult 属性来判断操作的 HRESULT 值。

我们定义了一个扩展方法 IsDiskFullException，实现如下：

/// <summary>
/// There is not enough space on the disk.
/// 磁盘空间不足。
/// </summary>
private static readonly int ERROR_DISK_FULL = 0x0070;

/// <summary>
/// 判断某个 <see cref="IOException"/> 是否是“磁盘空间不足”的异常。
/// </summary>
/// <param name="ex">IO 异常。</param>
/// <returns></returns>
public static bool IsDiskFullException(this IOException ex)
{
    var errorCode = ex.HResult & 0xFFFF;
    return errorCode == ERROR_DISK_FULL;
}

参考资料

无法加载为扩展“Microsoft.VisualStudio.Diagnostics.ServiceModelSink.Behavior”注册的类型

Fri, 11 Jun 2021 06:34:28 +0000

一天，某用户反馈过来说我们的软件无法运行，我一看异常信息看到了这个：“System.Configuration.ConfigurationErrorsException: 无法加载为扩展“Microsoft.VisualStudio.Diagnostics.ServiceModelSink.Behavior”注册的类型“Microsoft.VisualStudio.Diagnostics.ServiceModelSink.Behavior, Microsoft.VisualStudio.Diagnostics.ServiceModelSink, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a”。 (C:\Windows\Microsoft.NET\Framework\v4.0.30319\Config\machine.config line 232)”。

异常

异常的完整堆栈如下：

System.Configuration.ConfigurationErrorsException: 无法加载为扩展“Microsoft.VisualStudio.Diagnostics.ServiceModelSink.Behavior”注册的类型“Microsoft.VisualStudio.Diagnostics.ServiceModelSink.Behavior, Microsoft.VisualStudio.Diagnostics.ServiceModelSink, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a”。 (C:\Windows\Microsoft.NET\Framework\v4.0.30319\Config\machine.config line 232)
   在 System.Configuration.BaseConfigurationRecord.EvaluateOne(String[] keys, SectionInput input, Boolean isTrusted, FactoryRecord factoryRecord, SectionRecord sectionRecord, Object parentResult)
   在 System.Configuration.BaseConfigurationRecord.Evaluate(FactoryRecord factoryRecord, SectionRecord sectionRecord, Object parentResult, Boolean getLkg, Boolean getRuntimeObject, Object& result, Object& resultRuntimeObject)
   在 System.Configuration.BaseConfigurationRecord.GetSectionRecursive(String configKey, Boolean getLkg, Boolean checkPermission, Boolean getRuntimeObject, Boolean requestIsHere, Object& result, Object& resultRuntimeObject)
   在 System.Configuration.BaseConfigurationRecord.GetSectionRecursive(String configKey, Boolean getLkg, Boolean checkPermission, Boolean getRuntimeObject, Boolean requestIsHere, Object& result, Object& resultRuntimeObject)
   在 System.Configuration.BaseConfigurationRecord.GetSectionRecursive(String configKey, Boolean getLkg, Boolean checkPermission, Boolean getRuntimeObject, Boolean requestIsHere, Object& result, Object& resultRuntimeObject)
   在 System.Configuration.BaseConfigurationRecord.GetSectionRecursive(String configKey, Boolean getLkg, Boolean checkPermission, Boolean getRuntimeObject, Boolean requestIsHere, Object& result, Object& resultRuntimeObject)
   在 System.Configuration.BaseConfigurationRecord.GetSection(String configKey)
   在 System.Configuration.ClientConfigurationSystem.System.Configuration.Internal.IInternalConfigSystem.GetSection(String sectionName)
   在 System.Configuration.ConfigurationManager.GetSection(String sectionName)
   在 System.ServiceModel.Activation.AspNetEnvironment.UnsafeGetSectionFromConfigurationManager(String sectionPath)
   在 System.ServiceModel.Activation.AspNetEnvironment.UnsafeGetConfigurationSection(String sectionPath)
   在 System.ServiceModel.Configuration.ConfigurationHelpers.UnsafeGetAssociatedSection(ContextInformation evalContext, String sectionPath)
   在 System.ServiceModel.Description.ConfigLoader.LookupCommonBehaviors(ContextInformation context)
   在 System.ServiceModel.Description.ConfigLoader.LoadServiceDescription(ServiceHostBase host, ServiceDescription description, ServiceElement serviceElement, Action`1 addBaseAddress, Boolean skipHost)
   在 System.ServiceModel.ServiceHostBase.LoadConfigurationSectionInternal(ConfigLoader configLoader, ServiceDescription description, ServiceElement serviceSection)
   在 System.ServiceModel.ServiceHostBase.ApplyConfiguration()
   在 System.ServiceModel.ServiceHost.ApplyConfiguration()
   在 System.ServiceModel.ServiceHostBase.InitializeDescription(UriSchemeKeyedCollection baseAddresses)
   在 System.ServiceModel.ServiceHost.InitializeDescription(Type serviceType, UriSchemeKeyedCollection baseAddresses)
   在 System.ServiceModel.ServiceHost..ctor(Type serviceType, Uri[] baseAddresses)
   在 Walterlv.DemoLib.IPC.WCF.Duplex.Pipe.Server..ctor(Uri address, String serverId, IClientInfoBuilder clientInfoBuilder)
   在 Walterlv.DemoApp.IPCLinks.IPCCloudLinkProvider..ctor(String identity, IClientInfoBuilder clientInfoBuilder)
   在 Walterlv.DemoApp.IPCLinks.IPCLinkProviderFactory.Build(IIPCLinkEnvironment environment, IClientInfoBuilder clientInfoBuilder)
   在 Walterlv.DemoApp.Tasks.IPCLinkInitializeStartup.RunAsync(IStartupContext context)
   在 Walterlv.DemoApp.Startup.Core.StartupTask.<>c__DisplayClass0_0.<<JoinAsync>b__0>d.MoveNext()
--- 引发异常的上一位置中堆栈跟踪的末尾 ---
   在 System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
   在 System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   在 Walterlv.DemoApp.Startup.Core.StartupTask.<JoinAsync>d__0.MoveNext()
--- 引发异常的上一位置中堆栈跟踪的末尾 ---
   在 System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
   在 System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   在 Walterlv.DemoApp.Startup.Core.StartupTaskWrapper.<>c__DisplayClass36_0.<<ExecuteTask>b__1>d.MoveNext()

初步探索

这个异常消息提示基本已经把表层原因说得很明白了：

System.Configuration.ConfigurationErrorsException: 无法加载为扩展“Microsoft.VisualStudio.Diagnostics.ServiceModelSink.Behavior”注册的类型“Microsoft.VisualStudio.Diagnostics.ServiceModelSink.Behavior, Microsoft.VisualStudio.Diagnostics.ServiceModelSink, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a”。 (C:\Windows\Microsoft.NET\Framework\v4.0.30319\Config\machine.config line 232)

即“C:\Windows\Microsoft.NET\Framework\v4.0.30319\Config\machine.config”文件的 232 行有一个关于 Microsoft.VisualStudio.Diagnostics.ServiceModelSink.Behavior 注册的类型无法加载。我打开那个文件，看到了相关行：

<commonBehaviors><endpointBehaviors><Microsoft.VisualStudio.Diagnostics.ServiceModelSink.Behavior/></endpointBehaviors><serviceBehaviors><Microsoft.VisualStudio.Diagnostics.ServiceModelSink.Behavior/></serviceBehaviors></commonBehaviors></system.serviceModel>

修复方法

将这一行里面的 Microsoft.VisualStudio.Diagnostics.ServiceModelSink.Behavior 部分删除后问题即解决。

也就是说，这一行会变成：

<commonBehaviors><endpointBehaviors></endpointBehaviors><serviceBehaviors></serviceBehaviors></commonBehaviors></system.serviceModel>

至于元素开闭不匹配的问题不用关心，放到整个文件中是匹配的。（不知道是什么程序写成这样的格式化乱的 XML 文件。）

记得要以管理员权限保存。如果目标电脑没有好用的编辑器，可将其复制到桌面等低权限的目录下，编辑好再放回去。

额外说明

无需担心删除这一行会造成什么不良影响，因为正常情况下没有装 Visual Studio 的电脑上，这个文件本就不应该有这一行的。（感谢 @kkwpsv 在 Win7/10 虚拟机中的试验。）

至于目标电脑上究竟是为什么会导致没有 Visual Studio 时注册了一个 WCF 的行为扩展，这就不得而知了……（如果你知道，欢迎评论区教教我！）

参考资料

[ServiceModel Registration Tool (ServiceModelReg.exe) - WCF

Microsoft Docs](https://docs.microsoft.com/en-us/dotnet/framework/wcf/servicemodelreg-exe?redirectedfrom=MSDN)

What is Microsoft.VisualStudio.Diagnostics.ServiceModelSink.dll?
.net - microsoft.visualstudio.diagnostics.servicemodelsink.dll – present on most systems, missing on new system - Stack Overflow
visual studio 2010 - ‘Microsoft.VisualStudio.Diagnostics.ServiceModelSink.Behavior’ could not be loaded - Stack Overflow
c# - WCF and Windows Store apps, ConfigurationErrorsException - Stack Overflow
iis 7 - WCF: Routing service and “Unable to automatically debug ‘service name’. The remote procedure could not be debugged - Stack Overflow

.NET 单个异步任务如何同时监听多个取消请求（CancellationToken）

Fri, 11 Jun 2021 01:13:06 +0000

异步编程中，并不是所有时候 await 等的都是新的异步任务；有时候同一个异步任务可能被多次等待，并且每个等待都可以有自己的取消请求，即 CancellationToken。那么如何在一个异步任务中同时响应多个取消请求呢？

可被多次 `await` 的单个任务

我们先来列举一个最简单的例子，用来作为多次取消请求的示例。

class WalterlvDemoClass
{
    private readonly CancellationToken _currentCancellationToken = default;

    public async Task DoSomethingAsync(CancellationToken cancellationToken)
    {
        // 省略真正的异步代码。
    }
}

现在，DoSomethingAsync 可能被调用多次，但执行的都是同一件事情。当任务完成时所有 await 全部等待完成，当任务取消时所有 await 全部取消。

合并 `CancellationToken`

合并 CancellationToken 的方法是：

var token = CancellationTokenSource.CreateLinkedTokenSource(token1, token2)

合并完成后的 CancellationToken 在两者任一个取消时都会被取消。

于是我们前面的 DoSomethingAsync 加一行即可：

    class WalterlvDemoClass
    {
        private readonly CancellationToken _currentCancellationToken = default;

        public async Task DoSomethingAsync(CancellationToken cancellationToken)
        {
++          _currentCancellationToken = CancellationTokenSource.CreateLinkedTokenSource(_currentCancellationToken, cancellationToken);
++
            // 省略真正的异步代码，需要判断取消请求时，判断 _currentCancellationToken。
        }
    }

参考资料

How to: Listen for Multiple Cancellation Requests - Microsoft Docs

从零开始制作 NuGet 源代码包（全面支持 .NET Core / .NET Framework / WPF 项目）

Mon, 07 Jun 2021 07:14:39 +0000

默认情况下，我们打包 NuGet 包时，目标项目安装我们的 NuGet 包会引用我们生成的库文件（dll）。除此之外，我们也可以专门做 NuGet 工具包，还可以做 NuGet 源代码包。然而做源代码包可能是其中最困难的一种了，目标项目安装完后，这些源码将直接随目标项目一起编译。

本文将从零开始，教你制作一个支持 .NET 各种类型项目的源代码包。

前置知识

在开始制作一个源代码包之间，建议你提前了解项目文件的一些基本概念：

理解 C# 项目 csproj 文件格式的本质和编译流程

当然就算不了解也没有关系。跟着本教程你也可以制作出来一个源代码包，只不过可能遇到了问题的时候不容易调试和解决。

制作一个源代码包

接下来，我们将从零开始制作一个源代码包。

我们接下来的将创建一个完整的解决方案，这个解决方案包括：

一个将打包成源代码包的项目
一个调试专用的项目（可选）
一个测试源代码包的项目（可选）

第一步：创建一个 .NET 项目

像其他 NuGet 包的引用项目一样，我们需要创建一个空的项目。不过差别是我们需要创建的是控制台程序。

当创建好之后，Main 函数中的所有内容都是不需要的，于是我们删除 Main 函数中的所有内容但保留 Main 函数。

这时 Program.cs 中的内容如下：

namespace Walterlv.PackageDemo.SourceCode
{
    class Program
    {
        static void Main(string[] args)
        {
        }
    }
}

双击创建好的项目的项目，或者右键项目 “编辑项目文件”，我们可以编辑此项目的 csproj 文件。

在这里，我将目标框架改成了 net48。实际上如果我们不制作动态源代码生成，那么这里无论填写什么目标框架都不重要。在这篇博客中，我们主要篇幅都会是做静态源代码生成，所以你大可不必关心这里填什么。

提示：如果 net48 让你无法编译这个项目，说明你电脑上没有装 .NET Framework 4.8 框架，请改成 net473, net472, net471, net47, net462, net 461, net46, net45, netcoreapp3.0, netcoreapp2.1, netcoreapp2.0 中的任何一个可以让你编译通过的目标框架即可。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net48</TargetFramework>
  </PropertyGroup>

</Project>

第二步：组织项目的目录结构

接下来，我们会让这个项目像一个 NuGet 包的样子。当然，是 NuGet 源代码包。

请在你的项目当中创建这些文件和文件夹：

- Assets
    - build
        + Package.props
        + Package.targets
    - buildMultiTargeting
        + Package.props
        + Package.targets
    - src
        + Foo.cs
    - tools
+ Program.cs

在这里，- 号表示文件夹，+ 号表示文件。

Program.cs 是我们一开始就已经有的，可以不用管。src 文件夹里的 Foo.cs 是我随意创建的一个类，你就想往常创建正常的类文件一样创建一些类就好了。

比如我的 Foo.cs 里面的内容很简单：

using System;

namespace Walterlv.PackageDemo.SourceCode
{
    internal class Foo
    {
        public static void Print() => Console.WriteLine("Walterlv is a 逗比.");
    }
}

props 和 targets 文件你可能在 Visual Studio 的新建文件的模板中找不到这样的模板文件。这不重要，你随便创建一个文本文件，然后将名称修改成上面列举的那样即可。接下来我们会依次修改这些文件中的所有内容，所以无需担心模板自动为我们生成了哪些内容。

为了更直观，我将我的解决方案截图贴出来，里面包含所有这些文件和文件夹的解释。

我特别说明了哪些文件和文件夹是必须存在的，哪些文件和文件夹的名称一定必须与本文说明的一样。如果你是以教程的方式阅读本文，建议所有的文件和文件夹都跟我保持一样的结构和名称；如果你已经对 NuGet 包的结构有一定了解，那么可自作主张修改一些名称。

第三步：编写项目文件 csproj

现在，我们要双击项目名称或者右键“编辑项目文件”来编辑项目的 csproj 文件

我们编辑项目文件的目的，是让我们前一步创建的项目文件夹结构真正成为 NuGet 包中的文件夹结构。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net48</TargetFramework>

    <!-- 要求此项目编译时要生成一个 NuGet 包。-->
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>

    <!-- 这里为了方便，我将 NuGet 包的输出路径设置在了解决方案根目录的 bin 文件夹下，而不是项目的 bin 文件夹下。-->
    <PackageOutputPath>..\bin\$(Configuration)</PackageOutputPath>

    <!-- 创建 NuGet 包时，项目的输出文件对应到 NuGet 包的 tools 文件夹，这可以避免目标项目引用我们的 NuGet 包的输出文件。
         同时，如果将来我们准备动态生成源代码，而不只是引入静态源代码，还可以有机会运行我们 Program 中的 Main 函数。-->
    <BuildOutputTargetFolder>tools</BuildOutputTargetFolder>

    <!-- 此包将不会传递依赖。意味着如果目标项目安装了此 NuGet 包，那么安装目标项目包的项目不会间接安装此 NuGet 包。-->
    <DevelopmentDependency>true</DevelopmentDependency>
    
    <!-- 包的版本号，我们设成了一个预览版；当然你也可以设置为正式版，即没有后面的 -alpha 后缀。-->
    <Version>0.1.0-alpha</Version>
    
    <!-- 设置包的作者。在上传到 nuget.org 之后，如果作者名与 nuget.org 上的账号名相同，其他人浏览包是可以直接点击链接看作者页面。-->
    <Authors>walterlv</Authors>

    <!-- 设置包的组织名称。我当然写成我所在的组织 dotnet 职业技术学院啦。-->
    <Company>dotnet-campus</Company>
  </PropertyGroup>

  <!-- 在生成 NuGet 包之前，我们需要将我们项目中的文件夹结构一一映射到 NuGet 包中。-->
  <Target Name="IncludeAllDependencies" BeforeTargets="_GetPackageFiles">
    <ItemGroup>

      <!-- 将 Package.props / Package.targets 文件的名称在 NuGet 包中改为需要的真正名称。
           因为 NuGet 包要自动导入 props 和 targets 文件，要求文件的名称必须是 包名.props 和 包名.targets；
           然而为了避免我们改包名的时候还要同步改四个文件的名称，所以就在项目文件中动态生成。-->
      <None Include="Assets\build\Package.props" Pack="True" PackagePath="build\$(PackageId).props" />
      <None Include="Assets\build\Package.targets" Pack="True" PackagePath="build\$(PackageId).targets" />
      <None Include="Assets\buildMultiTargeting\Package.props" Pack="True" PackagePath="buildMultiTargeting\$(PackageId).props" />
      <None Include="Assets\buildMultiTargeting\Package.targets" Pack="True" PackagePath="buildMultiTargeting\$(PackageId).targets" />

      <!-- 我们将 src 目录中的所有源代码映射到 NuGet 包中的 src 目录中。-->
      <None Include="Assets\src\**" Pack="True" PackagePath="src" />

    </ItemGroup>
  </Target>

</Project>

第四步：编写编译文件 targets

接下来，我们将编写编译文件 props 和 targets。注意，我们需要写的是四个文件的内容，不要弄错了。

如果我们做好的 NuGet 源码包被其他项目使用，那么这四个文件中的其中一对会在目标项目被自动导入（Import）。在你理解理解 C# 项目 csproj 文件格式的本质和编译流程一文内容之前，你可能不明白“导入”是什么意思。但作为从零开始的入门博客，你也不需要真的理解导入是什么意思，只要知道这四个文件中的代码将在目标项目编译期间运行就好。

buildMultiTargeting 文件夹中的 Package.props 文件

你只需要将下面的代码拷贝到 buildMultiTargeting 文件夹中的 Package.props 文件即可。注意将包名换成你自己的包名，也就是项目名。

<Project>

  <PropertyGroup>
    <MSBuildAllProjects>$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>
  </PropertyGroup>
  
  <!-- 为了简单起见，如果导入了这个文件，那么我们将直接再导入 ..\build\Walterlv.PackageDemo.SourceCode.props 文件。
       注意到了吗？我们并没有写 Package.props，因为我们在第三步编写项目文件时已经将这个文件转换为真实的包名了。-->
  <Import Project="..\build\Walterlv.PackageDemo.SourceCode.props" />

</Project>

buildMultiTargeting 文件夹中的 Package.targets 文件

你只需要将下面的代码拷贝到 buildMultiTargeting 文件夹中的 Package.targets 文件即可。注意将包名换成你自己的包名，也就是项目名。

<Project>

  <PropertyGroup>
    <MSBuildAllProjects>$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>
  </PropertyGroup>
  
  <!-- 为了简单起见，如果导入了这个文件，那么我们将直接再导入 ..\build\Walterlv.PackageDemo.SourceCode.targets 文件。
       注意到了吗？我们并没有写 Package.targets，因为我们在第三步编写项目文件时已经将这个文件转换为真实的包名了。-->
  <Import Project="..\build\Walterlv.PackageDemo.SourceCode.targets" />

</Project>

build 文件夹中的 Package.props 文件

下面是 build 文件夹中 Package.props 文件的全部内容。可以注意到我们几乎没有任何实质性的代码在里面。即便我们在此文件中还没有写任何代码，依然需要创建这个文件，因为后面第五步我们将添加更复杂的代码时将再次用到这个文件完成里面的内容。

现在，保持你的文件中的内容与下面一模一样就好。

<Project>

  <PropertyGroup>
    <MSBuildAllProjects>$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>
  </PropertyGroup>

</Project>

build 文件夹中的 Package.targets 文件

下面是 build 文件夹中的 Package.targets 文件的全部内容。

我们写了两个编译目标，即 Target。_WalterlvDemoEvaluateProperties 没有指定任何执行时机，但帮我们计算了两个属性：

_WalterlvDemoRoot 即 NuGet 包的根目录
_WalterlvDemoSourceFolder 即 NuGet 包中的源代码目录

另外，我们添加了一个 Message 任务，用于在编译期间显示一条信息，这对于调试来说非常方便。

_WalterlvDemoIncludeSourceFiles 这个编译目标指定在 CoreCompile 之前执行，并且执行需要依赖于 _WalterlvDemoEvaluateProperties 编译目标。这意味着当编译执行到 CoreCompile 步骤时，将在它执行之前插入 _WalterlvDemoIncludeSourceFiles 编译目标来执行，而 _WalterlvDemoIncludeSourceFiles 依赖于 _WalterlvDemoEvaluateProperties，于是 _WalterlvDemoEvaluateProperties 会插入到更之前执行。那么在微观上来看，这三个编译任务的执行顺序将是：_WalterlvDemoEvaluateProperties -> _WalterlvDemoIncludeSourceFiles -> CoreCompile。

_WalterlvDemoIncludeSourceFiles 中，我们定义了一个集合 _WalterlvDemoCompile，集合中包含 NuGet 包源代码文件夹中的所有 .cs 文件。另外，我们又定义了 Compile 集合，将 _WalterlvDemoCompile 集合中的所有内容添加到 Compile 集合中。Compile 是 .NET 项目中的一个已知集合，当 CoreCompile 执行时，所有 Compile 集合中的文件将参与编译。注意到我没有直接将 NuGet 包中的源代码文件引入到 Compile 集合中，而是经过了中转。后面第五步中，你将体会到这样做的作用。

我们也添加一个 Message 任务，用于在编译期间显示信息，便于调试。

<Project>

  <PropertyGroup>
    <MSBuildAllProjects>$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>
  </PropertyGroup>

  <Target Name="_WalterlvDemoEvaluateProperties">
    <PropertyGroup>
      <_WalterlvDemoRoot>$(MSBuildThisFileDirectory)..\</_WalterlvDemoRoot>
      <_WalterlvDemoSourceFolder>$(MSBuildThisFileDirectory)..\src\</_WalterlvDemoSourceFolder>
    </PropertyGroup>
    <Message Text="1. 初始化源代码包的编译属性" />
  </Target>

  <!-- 引入 C# 源码。 -->
  <Target Name="_WalterlvDemoIncludeSourceFiles"
          BeforeTargets="CoreCompile"
          DependsOnTargets="_WalterlvDemoEvaluateProperties">
    <ItemGroup>
      <_WalterlvDemoCompile Include="$(_WalterlvDemoSourceFolder)**\*.cs" />
      <Compile Include="@(_WalterlvDemoCompile)" />
    </ItemGroup>
    <Message Text="2 引入源代码包中的所有源代码：@(_WalterlvDemoCompile)" />
  </Target>

</Project>

这四个文件分别的作用

我们刚刚花了很大的篇幅教大家完成 props 和 targets 文件，那么这四个文件是做什么的呢？

如果安装我们源代码包的项目使用 TargetFramework 属性写目标框架，那么 NuGet 会自动帮我们导入 build 文件夹中的两个编译文件。如果安装我们源代码包的项目使用 TargetFrameworks（注意复数形式）属性写目标框架，那么 NuGet 会自动帮我们导入 buildMultiTargeting 文件夹中的两个编译文件。

如果你对这个属性不熟悉，请回到第一步看我们一开始创建的代码，你会看到这个属性的设置的。如果还不清楚，请阅读博客：

让一个 csproj 项目指定多个开发框架

体验和查看 NuGet 源代码包

也许你已经从本文拷贝了很多代码过去了，但直到目前我们还没有看到这些代码的任何效果，那么现在我们就可以来看看了。这可算是一个阶段性成果呢！

先编译生成一下我们一直在完善的项目，我们就可以在解决方案目录的 bin\Debug 目录下找到一个 NuGet 包。

现在，我们要打开这个 NuGet 包看看里面的内容。你需要先去应用商店下载 NuGet Package Explorer，装完之后你就可以开始直接双击 NuGet 包文件，也就是 nupkg 文件。现在我们双击打开看看。

我们的体验到此为止。如果你希望在真实的项目当中测试，可以阅读其他博客了解如何在本地测试 NuGet 包。

第五步：加入 WPF 项目支持

截至目前，我们只是在源代码包中引入了 C# 代码。如果我们需要加入到源代码包中的代码包含 WPF 的 XAML 文件，或者安装我们源代码包的目标项目包含 WPF 的 XAML 文件，那么这个 NuGet 源代码包直接会导致无法编译通过。至于原因，你需要阅读我的另一篇博客来了解：

WPF 程序的编译过程

即便你不懂 WPF 程序的编译过程，你也可以继续完成本文的所有内容，但可能就不会明白为什么接下来我们要那样去修改我们之前创建的文件。

接下来我们将修改这些文件：

build 文件夹中的 Package.props 文件
build 文件夹中的 Package.targets 文件

build 文件夹中的 Package.props 文件

自微软在 .NET SDK 5.0.2 开始修复了 WPF 项目中 NuGet 代码生成器的 bug 后，已经不需要在这里新增属性了。当然，如果你想增加其他的属性则可以在这里加。

关于这个 bug，详见：[release/5.0] Support Source Generators in WPF projects by ryalanms · Pull Request #3846 · dotnet/wpf

~~在这个文件中，我们将新增一个属性 ShouldFixNuGetImportingBugForWpfProjects。这是我取的名字，意为“是否应该修复 WPF 项目中 NuGet 包自动导入的问题”。~~

我做一个开关的原因是怀疑我们需要针对 WPF 项目进行特殊处理是 WPF 项目自身的 Bug，如果将来 WPF 修复了这个 Bug，那么我们将可以直接通过此开关来关闭我们在这一节做的特殊处理。另外，后面我们将采用一些特别的手段来调试我们的 NuGet 源代码包，在调试项目中我们也会将这个属性设置为 False 以关闭 WPF 项目的特殊处理。

<Project>

    <PropertyGroup>
      <MSBuildAllProjects>$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>

--      <!-- 当生成 WPF 临时项目时，不会自动 Import NuGet 中的 props 和 targets 文件，这使得在临时项目中你现在看到的整个文件都不会参与编译。
--           然而，我们可以通过欺骗的方式在主项目中通过 _GeneratedCodeFiles 集合将需要编译的文件传递到临时项目中以间接参与编译。
--           WPF 临时项目不会 Import NuGet 中的 props 和 targets 可能是 WPF 的 Bug，也可能是刻意如此。
--           所以我们通过一个属性开关 `ShouldFixNuGetImportingBugForWpfProjects` 来决定是否修复这个错误。-->
--      <ShouldFixNuGetImportingBugForWpfProjects Condition=" '$(ShouldFixNuGetImportingBugForWpfProjects)' == '' ">True</ShouldFixNuGetImportingBugForWpfProjects>
    </PropertyGroup>

  </Project>

build 文件夹中的 Package.targets 文件

请按照下面的差异说明来修改你的 Package.targets 文件。实际上我们几乎删除任何代码，所以其实你可以将下面的所有内容作为你的新的 Package.targets 中的内容。

    <Project>

      <PropertyGroup>
        <MSBuildAllProjects>$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>
      </PropertyGroup>

++    <PropertyGroup>
++      <!-- 我们增加了一个属性，用于处理 WPF 特殊项目的源代码之前，确保我们已经收集到所有需要引入的源代码。 -->
++      <_WalterlvDemoImportInWpfTempProjectDependsOn>_WalterlvDemoIncludeSourceFiles</_WalterlvDemoImportInWpfTempProjectDependsOn>
++    </PropertyGroup>

      <Target Name="_WalterlvDemoEvaluateProperties">
        <PropertyGroup>
          <_WalterlvDemoRoot>$(MSBuildThisFileDirectory)..\</_WalterlvDemoRoot>
          <_WalterlvDemoSourceFolder>$(MSBuildThisFileDirectory)..\src\</_WalterlvDemoSourceFolder>

++    <!-- 修复旧版本的 Microsoft.NET.Sdk 中，WPF 项目不支持在临时项目中通过 NuGet 包生成源代码的问题。
++         微软自称从 .NET 5.0.2 开始，可通过 IncludePackageReferencesDuringMarkupCompilation 属性来支持在 NuGet 包中生成源代码，该值默认为 true。
++         不过，在低版本的 .NET 中，或者用户主动设置此值为 false 时，依然需要修复此问题。
++         以下是此问题的描述：-->
++    <!-- 当生成 WPF 临时项目时，不会自动 Import NuGet 中的 props 和 targets 文件，这使得在临时项目中你现在看到的整个文件都不会参与编译。
++        然而，我们可以通过欺骗的方式在主项目中通过 _GeneratedCodeFiles 集合将需要编译的文件传递到临时项目中以间接参与编译。
++        WPF 临时项目不会 Import NuGet 中的 props 和 targets 可能是 WPF 的 Bug，也可能是刻意如此。
++        所以我们通过一个属性开关 `ShouldFixNuGetImportingBugForWpfProjects` 来决定是否修复这个错误。-->
++    <ShouldFixNuGetImportingBugForWpfProjects Condition=" '$(IncludePackageReferencesDuringMarkupCompilation)' != 'True' And '$(ShouldFixNuGetImportingBugForWpfProjects)' == '' ">True</ShouldFixNuGetImportingBugForWpfProjects>

        </PropertyGroup>
        <Message Text="1. 初始化源代码包的编译属性" />
      </Target>

      <!-- 引入 C# 源码。 -->
      <Target Name="_WalterlvDemoIncludeSourceFiles"
              BeforeTargets="CoreCompile"
              DependsOnTargets="_WalterlvDemoEvaluateProperties">
        <ItemGroup>
          <_WalterlvDemoCompile Include="$(_WalterlvDemoSourceFolder)**\*.cs" />
++        <_WalterlvDemoAllCompile Include="@(_WalterlvDemoCompile)" />
          <Compile Include="@(_WalterlvDemoCompile)" />
        </ItemGroup>
--      <Message Text="2 引入源代码包中的所有源代码：@(_WalterlvDemoCompile)" />
++      <Message Text="2.1 引入源代码包中的所有源代码：@(_WalterlvDemoCompile)" />
      </Target>

++    <!-- 引入 WPF 源码。 -->
++    <Target Name="_WalterlvDemoIncludeWpfFiles"
++            BeforeTargets="MarkupCompilePass1"
++            DependsOnTargets="_WalterlvDemoEvaluateProperties">
++      <ItemGroup>
++        <_WalterlvDemoPage Include="$(_WalterlvDemoSourceFolder)**\*.xaml" />
++        <Page Include="@(_WalterlvDemoPage)" Link="%(_WalterlvDemoPage.FileName).xaml" />
++      </ItemGroup>
++      <Message Text="2.2 引用 WPF 相关源码：@(_WalterlvDemoPage)" />
++    </Target>

++    <!-- 当生成 WPF 临时项目时，不会自动 Import NuGet 中的 props 和 targets 文件，这使得在临时项目中你现在看到的整个文件都不会参与编译。
++         然而，我们可以通过欺骗的方式在主项目中通过 _GeneratedCodeFiles 集合将需要编译的文件传递到临时项目中以间接参与编译。
++         WPF 临时项目不会 Import NuGet 中的 props 和 targets 可能是 WPF 的 Bug，也可能是刻意如此。
++         所以我们通过一个属性开关 `ShouldFixNuGetImportingBugForWpfProjects` 来决定是否修复这个错误。-->
++    <Target Name="_WalterlvDemoImportInWpfTempProject"
++            AfterTargets="MarkupCompilePass1"
++            BeforeTargets="GenerateTemporaryTargetAssembly"
++            DependsOnTargets="$(_WalterlvDemoImportInWpfTempProjectDependsOn)"
++            Condition=" '$(ShouldFixNuGetImportingBugForWpfProjects)' == 'True' ">
++      <ItemGroup>
++        <_GeneratedCodeFiles Include="@(_WalterlvDemoAllCompile)" />
++      </ItemGroup>
++      <Message Text="3. 正在欺骗临时项目，误以为此 NuGet 包中的文件是 XAML 编译后的中间代码：@(_WalterlvDemoAllCompile)" />
++    </Target>

    </Project>

我们增加了 _WalterlvDemoImportInWpfTempProjectDependsOn 属性，这个属性里面将填写一个到多个编译目标（Target）的名称（多个用分号分隔），用于告知 _WalterlvDemoImportInWpfTempProject 这个编译目标在执行之前必须确保执行的依赖编译目标。而我们目前的依赖目标只有一个，就是 _WalterlvDemoIncludeSourceFiles 这个引入 C# 源代码的编译目标。如果你有其他考虑有引入更多 C# 源代码的编译目标，则需要把他们都加上（当然本文是不需要的）。为此，我还新增了一个 _WalterlvDemoAllCompile 集合，如果存在多个依赖的编译目标会引入 C# 源代码，则需要像 _WalterlvDemoIncludeSourceFiles 一样，将他们都加入到 Compile 的同时也加入到 _WalterlvDemoAllCompile 集合中。

为什么可能有多个引入 C# 源代码的编译目标？因为本文我们只考虑了引入我们提前准备好的源代码放入源代码包中，而我们提到过可能涉及到动态生成 C# 源代码的需求。如果你有一两个编译目标会动态生成一些 C# 源代码并将其加入到 Compile 集合中，那么请将这个编译目标的名称加入到 _WalterlvDemoImportInWpfTempProjectDependsOn 属性（注意多个用分号分隔），同时将集合也引入一份到 _WalterlvDemoAllCompile 中。

_WalterlvDemoIncludeWpfFiles 这个编译目标的作用是引入 WPF 的 XAML 文件，这很容易理解，毕竟我们的源代码中包含 WPF 相关的文件。

请特别注意：

我们加了一个 Link 属性，并且将其指定为 %(_WalterlvDemoPage.FileName).xaml。这意味着我们会把所有的 XAML 文件都当作在项目根目录中生成，如果你在其他的项目中用到了相对或绝对的 XAML 文件的路径，这显然会改变路径。但是，我们没有其他的方法来根据 XAML 文件所在的目录层级来自定指定 Link 属性让其在正确的层级上，所以这里才写死在根目录中。
- 如果要解决这个问题，我们就需要在生成 NuGet 包之前生成此项目中所有 XAML 文件的正确的 Link 属性（例如改为 Views\%(_WalterlvDemoPage.FileName).xaml），这意味着需要在此项目编译期间执行一段代码，把 Package.targets 文件中为所有的 XAML 文件生成正确的 Link 属性。本文暂时不考虑这个问题，但你可以参考 dotnet-campus/SourceYard 项目来了解如何动态生成 Link。
我们使用了 _WalterlvDemoPage 集合中转地存了 XAML 文件，这是必要的。因为这样才能正确通过 % 符号获取到 FileName 属性。

而 _WalterlvDemoImportInWpfTempProject 这个编译目标就不那么好理解了，而这个也是完美支持 WPF 项目源代码包的关键编译目标！这个编译目标指定在 MarkupCompilePass1 之后，GenerateTemporaryTargetAssembly 之前执行。GenerateTemporaryTargetAssembly 编译目标的作用是生成一个临时的项目，用于让 WPF 的 XAML 文件能够依赖同项目的 .NET 类型而编译。然而此临时项目编译期间是不会导入任何 NuGet 的 props 或 targets 文件的，这意味着我们特别添加的所有 C# 源代码在这个临时项目当中都是不存在的——如果项目使用到了我们源代码包中的源代码，那么必然因为类型不存在而无法编译通过——临时项目没有编译通过，那么整个项目也就无法编译通过。但是，我们通过在 MarkupCompilePass1 和 GenerateTemporaryTargetAssembly 之间将我们源代码包中的所有源代码加入到 _GeneratedCodeFiles 集合中，即可将这些文件加入到临时项目中一起编译。而原本 _GeneratedCodeFiles 集合中是什么呢？就是大家熟悉的 XAML 转换而成的 xxx.g.cs 文件。

测试和发布源代码包

现在我们再次编译这个项目，你将得到一个支持 WPF 项目的 NuGet 源代码包。

完整项目结构和源代码

至此，我们已经完成了编写一个 NuGet 源代码包所需的全部源码。接下来你可以在项目中添加更多的源代码，这样打出来的源代码包也将包含更多源代码。由于我们将将 XAML 文件都通过 Link 属性指定到根目录了，所以如果你需要添加 XAML 文件，你将只能添加到我们项目中的 Assets\src 目录下，除非做 dotnet-campus/SourceYard 中类似的动态 Link 生成的处理，或者在 Package.targets 文件中手工为每一个 XAML 编写一个特别的 Link 属性。

另外，在不改变我们整体项目结构的情况下，你也可以任意添加 WPF 所需的图片资源等。但也需要在 Package.targets 中添加额外的 Resource 引用。如果没有 dotnet-campus/SourceYard 的自动生成代码，你可能也需要手工编写 Resource。

接下来我会贴出更复杂的代码，用于处理更复杂的源代码包的场景。

目录结构

更复杂源代码包的项目组织形式会是下面这样图这样：

我们在 Assets 文件夹中新增了一个 assets 文件夹。由于资源在此项目中的路径必须和安装后的目标项目中一样才可以正确用 Uri 的方式使用资源，所以我们在项目文件 csproj 和编译文件 Package.targets 中都对这两个文件设置了 Link 到同一个文件夹中，这样才可以确保两边都能正常使用。

我们在 src 文件夹的不同子文件夹中创建了 XAML 文件。按照我们前面的说法，我们也需要像资源文件一样正确在 Package.targets 中设置 Link 才可以确保 Uri 是一致的。注意，我们接下来的源代码中没有在项目文件中设置 Link，原则上也是需要设置的，就像资源一样，这样才可以确保此项目和安装此 NuGet 包中的目标项目具有相同的 XAML Uri。此例子只是因为没有代码使用到了 XAML 文件的路径，所以才能得以幸免。

我们还利用了 tools 文件夹。我们在项目文件的末尾将输出文件拷贝到了 tools 目录下，这样，我们项目的 Assets 文件夹几乎与最终的 NuGet 包的文件夹结构一模一样，非常利于调试。但为了防止将生成的文件上传到版本管理，我在 tools 中添加了 .gitignore 文件：

/net*/*

项目文件

--  <Project Sdk="Microsoft.NET.Sdk">
++  <Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">
    
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>net48</TargetFramework>
++      <UseWpf>True</UseWpf>
    
        <!-- 要求此项目编译时要生成一个 NuGet 包。-->
        <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
    
        <!-- 这里为了方便，我将 NuGet 包的输出路径设置在了解决方案根目录的 bin 文件夹下，而不是项目的 bin 文件夹下。-->
        <PackageOutputPath>..\bin\$(Configuration)</PackageOutputPath>
    
        <!-- 创建 NuGet 包时，项目的输出文件对应到 NuGet 包的 tools 文件夹，这可以避免目标项目引用我们的 NuGet 包的输出文件。
             同时，如果将来我们准备动态生成源代码，而不只是引入静态源代码，还可以有机会运行我们 Program 中的 Main 函数。-->
        <BuildOutputTargetFolder>tools</BuildOutputTargetFolder>
    
        <!-- 此包将不会传递依赖。意味着如果目标项目安装了此 NuGet 包，那么安装目标项目包的项目不会间接安装此 NuGet 包。-->
        <DevelopmentDependency>true</DevelopmentDependency>
    
        <!-- 包的版本号，我们设成了一个预览版；当然你也可以设置为正式版，即没有后面的 -alpha 后缀。-->
        <Version>0.1.0-alpha</Version>
    
        <!-- 设置包的作者。在上传到 nuget.org 之后，如果作者名与 nuget.org 上的账号名相同，其他人浏览包是可以直接点击链接看作者页面。-->
        <Authors>walterlv</Authors>
    
        <!-- 设置包的组织名称。我当然写成我所在的组织 dotnet 职业技术学院啦。-->
        <Company>dotnet-campus</Company>
      </PropertyGroup>
    
++    <!-- 我们添加的其他资源需要在这里 Link 到一个统一的目录下，以便在此项目和安装 NuGet 包的目标项目中可以用同样的 Uri 使用。 -->
++    <ItemGroup>
++      <Resource Include="Assets\assets\Icon.ico" Link="Assets\Icon.ico" Visible="False" />
++      <Resource Include="Assets\assets\Background.png" Link="Assets\Background.png" Visible="False" />
++    </ItemGroup>
      
      <!-- 在生成 NuGet 包之前，我们需要将我们项目中的文件夹结构一一映射到 NuGet 包中。-->
      <Target Name="IncludeAllDependencies" BeforeTargets="_GetPackageFiles">
        <ItemGroup>
    
          <!-- 将 Package.props / Package.targets 文件的名称在 NuGet 包中改为需要的真正名称。
               因为 NuGet 包要自动导入 props 和 targets 文件，要求文件的名称必须是 包名.props 和 包名.targets；
               然而为了避免我们改包名的时候还要同步改四个文件的名称，所以就在项目文件中动态生成。-->
          <None Include="Assets\build\Package.props" Pack="True" PackagePath="build\$(PackageId).props" />
          <None Include="Assets\build\Package.targets" Pack="True" PackagePath="build\$(PackageId).targets" />
          <None Include="Assets\buildMultiTargeting\Package.props" Pack="True" PackagePath="buildMultiTargeting\$(PackageId).props" />
          <None Include="Assets\buildMultiTargeting\Package.targets" Pack="True" PackagePath="buildMultiTargeting\$(PackageId).targets" />
    
          <!-- 我们将 src 目录中的所有源代码映射到 NuGet 包中的 src 目录中。-->
          <None Include="Assets\src\**" Pack="True" PackagePath="src" />

++        <!-- 我们将 assets 目录中的所有源代码映射到 NuGet 包中的 assets 目录中。-->
++        <None Include="Assets\assets\**" Pack="True" PackagePath="assets" />
    
        </ItemGroup>
      </Target>
    
++    <!-- 在编译结束后将生成的可执行程序放到 Tools 文件夹中，使得 Assets 文件夹的目录结构与 NuGet 包非常相似，便于 Sample 项目进行及时的 NuGet 包调试。 -->
++    <Target Name="_WalterlvDemoCopyOutputToDebuggableFolder" AfterTargets="AfterBuild">
++        <ItemGroup>
++        <_WalterlvDemoToCopiedFiles Include="$(OutputPath)**" />
++        </ItemGroup>
++        <Copy SourceFiles="@(_WalterlvDemoToCopiedFiles)" DestinationFolder="Assets\tools\$(TargetFramework)" />
++    </Target>

    </Project>

编译文件

    <Project>

      <PropertyGroup>
        <MSBuildAllProjects>$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>
      </PropertyGroup>

      <PropertyGroup>
        <!-- 我们增加了一个属性，用于处理 WPF 特殊项目的源代码之前，确保我们已经收集到所有需要引入的源代码。 -->
        <_WalterlvDemoImportInWpfTempProjectDependsOn>_WalterlvDemoIncludeSourceFiles</_WalterlvDemoImportInWpfTempProjectDependsOn>
      </PropertyGroup>

      <Target Name="_WalterlvDemoEvaluateProperties">
        <PropertyGroup>
          <_WalterlvDemoRoot>$(MSBuildThisFileDirectory)..\</_WalterlvDemoRoot>
          <_WalterlvDemoSourceFolder>$(MSBuildThisFileDirectory)..\src\</_WalterlvDemoSourceFolder>
        </PropertyGroup>
        <Message Text="1. 初始化源代码包的编译属性" />
      </Target>

      <!-- 引入主要的 C# 源码。 -->
      <Target Name="_WalterlvDemoIncludeSourceFiles"
              BeforeTargets="CoreCompile"
              DependsOnTargets="_WalterlvDemoEvaluateProperties">
        <ItemGroup>
          <_WalterlvDemoCompile Include="$(_WalterlvDemoSourceFolder)**\*.cs" />
          <_WalterlvDemoAllCompile Include="@(_WalterlvDemoCompile)" />
          <Compile Include="@(_WalterlvDemoCompile)" />
        </ItemGroup>
        <Message Text="2.1 引入源代码包中的所有源代码：@(_WalterlvDemoCompile)" />
      </Target>

      <!-- 引入 WPF 源码。 -->
      <Target Name="_WalterlvDemoIncludeWpfFiles"
              BeforeTargets="MarkupCompilePass1"
              DependsOnTargets="_WalterlvDemoEvaluateProperties">
        <ItemGroup>
--        <_WalterlvDemoPage Include="$(_WalterlvDemoSourceFolder)**\*.xaml" />
--        <Page Include="@(_WalterlvDemoPage)" Link="Views\%(_WalterlvDemoPage.FileName).xaml" />
++        <_WalterlvDemoRootPage Include="$(_WalterlvDemoSourceFolder)FooView.xaml" />
++        <Page Include="@(_WalterlvDemoRootPage)" Link="Views\%(_WalterlvDemoRootPage.FileName).xaml" />
++        <_WalterlvDemoThemesPage Include="$(_WalterlvDemoSourceFolder)Themes\Walterlv.Windows.xaml" />
++        <Page Include="@(_WalterlvDemoThemesPage)" Link="Views\%(_WalterlvDemoThemesPage.FileName).xaml" />
++        <_WalterlvDemoIcoResource Include="$(_WalterlvDemoRoot)assets\*.ico" />
++        <_WalterlvDemoPngResource Include="$(_WalterlvDemoRoot)assets\*.png" />
++        <Resource Include="@(_WalterlvDemoIcoResource)" Link="assets\%(_WalterlvDemoIcoResource.FileName).ico" />
++        <Resource Include="@(_WalterlvDemoPngResource)" Link="assets\%(_WalterlvDemoPngResource.FileName).png" />
        </ItemGroup>
--      <Message Text="2.2 引用 WPF 相关源码：@(_WalterlvDemoPage);@(_WalterlvDemoIcoResource);@(_WalterlvDemoPngResource)" />
++      <Message Text="2.2 引用 WPF 相关源码：@(_WalterlvDemoRootPage);@(_WalterlvDemoThemesPage);@(_WalterlvDemoIcoResource);@(_WalterlvDemoPngResource)" />
      </Target>

      <!-- 当生成 WPF 临时项目时，不会自动 Import NuGet 中的 props 和 targets 文件，这使得在临时项目中你现在看到的整个文件都不会参与编译。
           然而，我们可以通过欺骗的方式在主项目中通过 _GeneratedCodeFiles 集合将需要编译的文件传递到临时项目中以间接参与编译。
           WPF 临时项目不会 Import NuGet 中的 props 和 targets 可能是 WPF 的 Bug，也可能是刻意如此。
           所以我们通过一个属性开关 `ShouldFixNuGetImportingBugForWpfProjects` 来决定是否修复这个错误。-->
      <Target Name="_WalterlvDemoImportInWpfTempProject"
              AfterTargets="MarkupCompilePass1"
              BeforeTargets="GenerateTemporaryTargetAssembly"
              DependsOnTargets="$(_WalterlvDemoImportInWpfTempProjectDependsOn)"
              Condition=" '$(ShouldFixNuGetImportingBugForWpfProjects)' == 'True' ">
        <ItemGroup>
          <_GeneratedCodeFiles Include="@(_WalterlvDemoAllCompile)" />
        </ItemGroup>
        <Message Text="3. 正在欺骗临时项目，误以为此 NuGet 包中的文件是 XAML 编译后的中间代码：@(_WalterlvDemoAllCompile)" />
      </Target>

    </Project>

开源项目

本文涉及到的所有代码均已开源到：

walterlv.demo/Walterlv.PackageDemo at master · walterlv/walterlv.demo

.NET 扩展编译用的文件有 .props 文件和 .targets 文件。不给我选择还好，给了我选择之后我应该使用哪个文件来编写扩展编译的代码呢？

如果你不了解 .props 文件或者 .targets 文件，可以阅读下面的博客：

理解 C# 项目 csproj 文件格式的本质和编译流程 - walterlv

具体的例子有下面这些博客。不过大概阅读一下就好，这只是 .props 和 .targets 文件的一些应用。文章比较长，你可以考虑稍后阅读。

当我们创建的 NuGet 包中包含 .props 和 .targets 文件的时候，我们相当于在项目文件 csproj 的两个地方添加了 Import 这些文件的代码。

<Project Sdk="Microsoft.NET.Sdk">

  <!-- 本来是没有下面这一行的，我只是为了说明 NuGet 相当于帮我们添加了这一行才假装写到了这里。 -->
  <Import Project="$(NuGetPackageRoot)walterlv.samplepackage\0.8.3-alpha\build\Walterlv.SamplePackage.props" Condition="Exists('$(NuGetPackageRoot)walterlv.samplepackage\0.8.3-alpha\build\Walterlv.SamplePackage.props')" />

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFrameworks>netcoreapp3.0</TargetFrameworks>
  </PropertyGroup>

  <!-- 本来是没有下面这一行的，我只是为了说明 NuGet 相当于帮我们添加了这一行才假装写到了这里。 -->
  <Import Project="$(NuGetPackageRoot)walterlv.samplepackage\0.8.3-alpha\build\Walterlv.SamplePackage.targets" Condition="Exists('$(NuGetPackageRoot)walterlv.samplepackage\0.8.3-alpha\build\Walterlv.SamplePackage.targets')" />

</Project>

如果你安装的多份 NuGet 包都带有 .props 和 .targets 文件，那么就相当于帮助你 Import 了多个：

<Project Sdk="Microsoft.NET.Sdk">

  <!-- 本来是没有下面这一行的，我只是为了说明 NuGet 相当于帮我们添加了这一行才假装写到了这里。 -->
  <Import Project="$(NuGetPackageRoot)walterlv.samplepackage1\0.8.3-alpha\build\Walterlv.SamplePackage1.props" Condition="Exists('$(NuGetPackageRoot)walterlv.samplepackage1\0.8.3-alpha\build\Walterlv.SamplePackage1.props')" />
  <Import Project="$(NuGetPackageRoot)walterlv.samplepackage2\0.5.1-beta\build\Walterlv.SamplePackage2.props" Condition="Exists('$(NuGetPackageRoot)walterlv.samplepackage2\0.5.1-beta\build\Walterlv.SamplePackage2.props')" />

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFrameworks>netcoreapp3.0</TargetFrameworks>
  </PropertyGroup>

  <!-- 本来是没有下面这一行的，我只是为了说明 NuGet 相当于帮我们添加了这一行才假装写到了这里。 -->
  <Import Project="$(NuGetPackageRoot)walterlv.samplepackage1\0.8.3-alpha\build\Walterlv.SamplePackage1.targets" Condition="Exists('$(NuGetPackageRoot)walterlv.samplepackage1\0.8.3-alpha\build\Walterlv.SamplePackage1.targets')" />
  <Import Project="$(NuGetPackageRoot)walterlv.samplepackage2\0.5.1-beta\build\Walterlv.SamplePackage2.targets" Condition="Exists('$(NuGetPackageRoot)walterlv.samplepackage2\0.5.1-beta\build\Walterlv.SamplePackage2.targets')" />

</Project>

于是，什么代码写到 .props 里而什么代码写到 .targets 里就一目了然了：

如果你是定义属性或者为属性设置初值，那么请写到 .props 里面
- 这样，所有的 NuGet 包或者扩展的编译流程都将可以访问到你设置的属性的值
如果你是使用属性，或者按条件设置属性，那么请写到 .targets 里面
- 因为这个时候多数的属性已经初始化完毕，你可以使用到属性的值了
如果你写的是编译目标（Target），那么请写到 .targets 里面
- 编译目标是扩展编译的，通常都是使用属性
- 也会有一些产生属性的，但那都是需要在编译期间产生的属性，其他依赖需要使用 DependsOn 等属性来获取

例如下面的属性适合写到 .props 里面。这是一个设置属性初始值的地方：

<Project>

  <PropertyGroup>
    <MSBuildAllProjects>$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>

    <!-- 当生成 WPF 临时项目时，不会自动 Import NuGet 中的 props 和 targets 文件，这使得在临时项目中你现在看到的整个文件都不会参与编译。
       然而，我们可以通过欺骗的方式在主项目中通过 _GeneratedCodeFiles 集合将需要编译的文件传递到临时项目中以间接参与编译。
       WPF 临时项目不会 Import NuGet 中的 props 和 targets 可能是 WPF 的 Bug，也可能是刻意如此。
       所以我们通过一个属性开关 `ShouldFixNuGetImportingBugForWpfProjects` 来决定是否修复这个错误。-->
    <ShouldFixNuGetImportingBugForWpfProjects Condition=" '$(ShouldFixNuGetImportingBugForWpfProjects)' == '' ">True</ShouldFixNuGetImportingBugForWpfProjects>

  </PropertyGroup>

</Project>

这个属性的含义你可以在我的另一篇博客中找到：从零开始制作 NuGet 源代码包（全面支持 .NET Core / .NET Framework / WPF 项目）

而下面的属性适合写到 .targets 里面，因为这里使用到了其他的属性：

<Project>

  <PropertyGroup>
    <MSBuildAllProjects>$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>

    <!-- 因为这里使用到了 `Configuration` 属性，需要先等到此属性已经初始化完成再使用，否则我们会拿到非预期的值。 -->
    <ShouldOptimizeDebugging> Condition=" '$(Configuration)' == 'Debug' ">True</ShouldOptimizeDebugging>

  </PropertyGroup>

</Project>

Windows 系统上如何揪出阻止你屏幕关闭的程序

Mon, 07 Jun 2021 05:42:18 +0000

使用 Win32 API SetThreadExecutionState 可以阻止进入屏幕保护程序，也能阻止屏幕关闭、阻止系统睡眠。这很方便，这也就可能造成各种参差不齐的程序都试图阻止你的屏幕关闭，于是来一个一整晚亮瞎眼就很难受。

本文教大家如何揪出阻止你屏幕关闭的程序。

我们主要使用系统自带的 powercfg 来查询相关的应用。因此，你需要以管理员权限打开你喜欢的终端。

命令 `powercfg /requests`

在终端中输入命令：

powercfg /requests

/requests 参数的作用是‎“列举应用程序和驱动程序的电源请求。电源请求可防止计算机自动关闭显示屏或进入低功耗睡眠模式。‎”官方文档对此的描述是：

Enumerates application and driver Power Requests. Power Requests prevent the computer from automatically powering off the display or entering a low-power sleep mode.

于是，如果有某个应用或驱动设置了阻止屏幕关闭，那么就会出现在此命令执行的结果里面。

比如下面是我的例子：

SteamVR 的几个进程试图阻止屏幕关闭，另外一些进程试图阻止系统睡眠

结束掉 SteamVR 后重新执行此命令，可以发现已经没有进程在阻止屏幕关闭和系统睡眠了：

命令 `powercfg -energy -trace`

在终端中输入命令：

powercfg -energy -trace

有时，应用并没有直接阻止你的屏幕关闭，而是在一段时间之内试图不断重置睡眠计时器，这种情况，前面的命令不能完全帮助你找到问题所在，于是你需要使用这个新命令。

运行这个命令，你需要等待 60 秒，就像下面这样：

注意：等待期间不要碰电脑，因为鼠标和键盘事件也会影响到追踪结果！

等待完成后，它会提示你“跟踪完成”，但不会直接告诉你任何结果。结果都存在了你个账户目录下的 energy-trace.etl 日志文件里面，例如 C:\Users\lvyi\energy-trace.etl。

这个文件要用事件查看器打开。

第一步：右键开始按钮，选择“事件查看器”。

第二步：操作→打开保存的日志

去用户文件夹中寻找“energy-trace.etl”文件，例如“C:\Users\lvyi\energy-trace.etl”，然后打开。

第三步：在保存的日志中找到可疑记录

由于日志太多（几十万条），建议右击日志选择“筛选当前日志(L)…”，在筛选器里将事件来源选成“Kernel-Power”，事件 ID 设为 63。

可以看到，即便我设置完成，也还有 7,852 个条目。不过这时也比较容易找到问题在哪里了。提示的是：

The application or service 0x0 is attempting to update the system timer resolution to a value of 0x0.

即有程序试图重置系统计时器。

在详细信息里，可以找到是哪个程序：

可以看到，在这条记录里，是“msedge.exe”。所以，可以去 Edge 浏览器标签里找找，是否有正在播放的视频或音频等。

常用阻止关闭屏幕的程序

发现电脑屏幕总是不自动关闭？看看你是否打开了这些程序……

参考资料

Powercfg command-line options - Microsoft Docs

发现电脑屏幕总是不自动关闭？看看你是否打开了这些程序……

Mon, 07 Jun 2021 05:39:27 +0000

本文收集一些已知的导致电脑屏幕不关闭的程序。如果你发现无论你设置多短的屏幕关闭超时时间但一直都不关闭，那么可以参考本文检查是否打开了这些程序。

系统设置

电源和睡眠

先检查一下你系统设置中的电源和睡眠选项，时间不应该太长。一定要先看看这里，别到时候折腾了半天发现是自己设错了就亏了……

另外，找程序的时候，不要第一眼看过去没有就忽略它了。因为你可能像我一样有很多个桌面。最好还是用任务管理器找，不会漏掉。

程序和游戏列表

大多数游戏

如果你有游戏没关，你第一个就应该怀疑它！

我不想把我正在玩的游戏列举出来，因为容易过时还会暴露些什么……

FEZ
RiME

应用

Microsoft PowerPoint 在演示模式下
金山 WPS 演示 在演示模式下
Wallpaper Engine

工具

GPU-Z 只要打开就会

为什么我想整理这份名单

因为我总是时不时发现某一天电脑屏幕一直亮着。到了晚上很刺眼的，而且费电……

所以，每发现一个就补充一个好了。如果你有已知的，麻烦在评论区告诉我哟！如果看不到评论区，可以前往这里评论，或者给我发邮件。

列表之外

如何揪出阻止屏幕关闭的程序？

可以看我的另一篇博客：Windows 系统上如何揪出阻止你屏幕关闭的程序

编写你的专属 MSBuild C# 代码生成器：在保存文件时自动实时生成你的代码

Tue, 01 Jun 2021 12:34:17 +0000

我之前的博客中有介绍如何在项目中生成额外的代码，也有介绍制作一个生成代码的 NuGet 包。而本文是在此基础上更进一步，可以让生成代码变成实时的；更准确的说，是在保存文件时即生成代码，而无需完整编译一次项目。

一天，头像全白昵称空格的“wuweilai”童鞋问我为什么 GRPC 的 NuGet 包能自动在 .proto 文件保存时更新生成的代码，怎么才能做到像它那样。然后，我研究了下 Grpc.Tools 包里的代码，外加跟他反复讨论，摸清了自动生成代码的方法。

背景知识

本文的知识非常简单，如果只是希望知道怎么实时生成代码的话，把本文后面的代码复制一下就可以了。但如果希望完整了解基于 MSBuild 生成代码的原理，你可以需要了解以下知识或教程：

准备项目

我们创建一个全新的项目，用来了解如何实时生成代码。

如下图，就是个普通的控制台应用程序。我额外生成了一个 Test.txt 文件，里面什么也没有。我们即将实现的是：在保存 Test.txt 文件时，会立即执行我们的编译流程，这样，我们便能基于 Test.txt 来实时生成一些代码。

最简单的自动生成代码的逻辑

现在，我们打开项目 csproj 文件（双击项目名称即可打开编辑这个文件）：

  <Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
      <OutputType>Exe</OutputType>
      <TargetFramework>net5.0</TargetFramework>
    </PropertyGroup>

+   <!-- 将项目中的所有 txt 文件搜集起来，用 WalterlvDemoFile 集合存起来。-->
+   <ItemGroup>
+     <WalterlvDemoFile Include="**\*.txt" Generator="MSBuild:Compile" />
+   </ItemGroup>

+   <!-- 注册 WalterlvDemoFile 项为一个 Item，这样它的通用属性就能被识别了。 -->
+   <ItemGroup>
+     <AvailableItemName Include="WalterlvDemoFile" />
+   </ItemGroup>

+   <!-- 随便写一个 Target，在编译之前做些什么。 -->
+   <Target Name="WalterlvDemoTarget" BeforeTargets="BeforeCompile">
+     <Exec Command="winver" />
+   </Target>

  </Project>

我把新增的代码高亮出来了。如果你想复制到你的项目里，记得去掉行首的所有 + 号。

等你复制到项目里之后，试着在 Test.txt 文件里面随便写点什么，然后保存。你会发现……呃……弹出了一个 Windows 版本号窗口……

最简代码解读

我们定义了一个 Target，名为 WalterlvDemoTarget（随便取的名字），并要求在 BeforeCompile 这个 Target 执行之前执行。
- 关于时机，可以阅读：
  - 通过重写预定义的 Target 来扩展 MSBuild / Visual Studio 的编译过程
  - 在制作多框架项目的 NuGet 包时应该注意的问题（buildMultiTargeting/TargetFrameworks
- 我们做了一个有趣的事情，在这个 Target 里面，显示了“系统版本号”（因为我想让实时编译过程变得更直观）
我们定义了一个 WalterlvDemoFile 项，这是随便取的名字，是为了搜集 *.txt 文件。
我们在 WalterlvDemoFile 里指定 Generator 为 MSBuild:Compile。
- 对于已知的项（Item）来说，Generator 属性是 MSBuild 编译时的一个已知元数据（Metadata），其作用为当此文件改变时，会执行一个指定的 Target
- 我们将其指定为 MSBuild:Compile，即指定为 MSBuild 内置的一个 Target Compile，意为执行一次编译
然而，WalterlvDemoFile 并不是已知的项，所以我们还需要额外将 WalterlvDemoFile 添加到 AvailableItemName 集合里。
- 关于已知的项，可以阅读：
  - Common MSBuild Project Items - Visual Studio - Microsoft Docs
- 加完之后，WalterlvDemoFile 的 Generator 属性就可以被自动启用了

延伸

在上面那个最简的 Demo 中，我们弹出了个 Windows 版本号，这真的只是为了让你立刻注意到某个代码执行了。当然真正生成代码肯定不会是这样的弹窗。

不过，你可以从我的其他博客里找到很多生成代码的方法，比如这篇……还有这篇……还有这这这篇……

参考资料

Unity OpenVR 虚拟现实入门六：通过摇杆控制玩家移动

Mon, 17 May 2021 00:31:31 +0000

在 Unity 的帮助下，虚拟现实应用的开发非常容易。不过国内竟然还是没有什么教程，所以这里就来一点入门的，适合新手。

本文将基于第四篇的简单场景，通过摇杆的方式控制玩家移动。

系列博客：

准备场景

如果你是基于本系列第四篇来做的摇杆移动，那么直接开始本篇。如果是基于第五篇（传送），那么，在本文开始之前，我们需要先把第五篇里传送相关的游戏对象禁用。

如下图，选择所有与传送相关的游戏对象，右键然后“切换激活状态”。

▲ 禁用传送相关的对象

编写移动玩家的脚本

选中“Player”，在检查器中添加组件。我们添加一个名为“PlayerMovementScript”的脚本。双击新添加的脚本文件，会用 Visual Studio 打开这个脚本文件，我们需要添加一点点的代码。

using UnityEngine;

using Valve.VR;
using Valve.VR.InteractionSystem;

public class PlayerMovementScript : MonoBehaviour
{
    public SteamVR_Action_Vector2 input;
    public float speed;

    void Update()
    {
        var localMovement = new Vector3(input.axis.x, 0, input.axis.y);
        var worldMovement = Player.instance.hmdTransform.TransformDirection(localMovement);
        var worldMovementOfPlane = Vector3.ProjectOnPlane(worldMovement, Vector3.up);
        transform.position += speed * Time.deltaTime * worldMovementOfPlane;
    }
}

这里，我们定义了两个属性：

SteamVR_Action_Vector2 类型的 input
float 类型的 speed

我们现在定义的这个 SteamVR_Action_Vector2 类型是 SteamVR 输入的一种类型，当使用 VR 控制器产生一个二维向量类型的数据时，就会生成 SteamVR_Action_Vector2 类型的数据。例如推动摇杆会产生这样的二维向量。我们稍后也会将这个类型绑定到摇杆上。

关于 SteamVR 能产生的其他输入类型，可以参考林德熙的博客：Unity3D OpenVR SteamVR Input Action 动作。

而 float 类型则跟所有编程语言一样，只是一个浮点数而已。

在 Update 函数中：

input.axis.x、input.axis.y 是我们从 SteamVR 的二维向量中取得的 X、Y 分量；但是，我们将它转换成一个三维向量。这样，我们就能得到一个摇杆映射到三维坐标中与地面平行的平面上的坐标（相对坐标）。
这个坐标是相对坐标，而要移动玩家，我们需要一个世界坐标下的移动向量，于是我们拿头显的变换量，将这个本地坐标转换到世界坐标中。最终得到的世界坐标，我们保存到了 worldMovement 变量中。
为了避免让玩家移动到空中或地面以下，我们将 worldMovement 向量投影到与地面平行的二维平面上。
最终，我们用速度、经过的时间和之前计算得到的二维平面上的世界三维坐标相乘，便得到了这一帧的移动向量，将其叠加到玩家的位置坐标上即得到了新一帧的玩家坐标。

设置 SteamVR 输入

现在，回到 Unity 编辑器中，在“Player”对象的检查器中，找到我们刚刚添加的“PlayerMovementScript”脚本，我们需要设置这个 input 属性应该由什么进行输入。

▲ 选择输入

在这个下拉列表中，我们点击“Add”（添加）。我们添加一个新的（默认名字是 NewAction）：

▲ 添加新的输入

这是一个抽象的，二维向量类型的输入，我将其取名为“DirectMovement”（意为直接移动，与之相对的是本系列第五篇说的传送移动 Teleport）。SteamVR 的这种抽象的输入可以很好地将编写代码时的输入与各种各样不同类型的 VR 控制器隔离开来，避免 VR 应用绑死某个控制器的按键。

以下是我为此添加的“DirectMovement”：

名字是“DirectMovement”
类型是 Vector2
必要性为“suggested”（suggested 表示开发者定义的，但允许用户修改的按键绑定设置；而 mandatory 表示开发者强制定义不允许用户修改的按键绑定设置）
我额外添加了中文和英文的两个不同本地化语言（这会在 SteamVR 的按键绑定设置时显示给开发者和用户看）

▲ DirectMovement 的动作设置

添加完成之后，点击“SteamVR Input”窗口左下角的“Save and generate”按钮，等待编译完成后，关闭这个窗口。

特别注意：default 的动作组不建议删除，因为 SteamVR 组件里很多组件都用到了 default 动作组里的动作，删除会导致无法看见手和手柄。

再回到“Player”游戏对象的检查器中找到“PlayerMovementScript”脚本，我们可以为输入选择我们刚刚添加的“DirectMovement”动作了。

▲ 选择 DirectMovement 动作

设置控制器按键绑定

现在，我们需要重新打开“SteamVR Input”窗口来设置按键绑定。这个窗口在“窗口”->“SteamVR Input”菜单里。

▲ SteamVR Input 菜单

在这个“SteamVR Input”窗口中，选择右下角的“Open binding UI”按钮。

▲ Open binding UI

稍等片刻，会打开“控制器按键设置”界面（这是 SteamVR 的界面，以后玩家去改键的时候看到的也是这个界面）。

▲ 控制器按键设置

首屏会显示这些信息：

当前正在开发的应用的按键设置（我们即将选择编辑它）
当前控制器（我用的是 Index Controller）
官方按键设置（对玩家来说，可通过这个设置还原成开发者的官方按键；而对我们开发者来说，也就是代码仓库里的那个按键设置）

我们点击“编辑”以编辑当前的按键设置。

▲ 编辑按键设置

将鼠标放到“Thumb Stick”上可以看到摇杆高亮了，这就是我们即将要绑定的那个按键。

点击旁边的“➕”号，会弹出这个键的各种不同用法：

摇杆：像摇杆一样使用这个键，会产生 X、Y 坐标（这正好产生我们刚刚新建的动作里需要的 Vector2 类型的输入数据）
十字键：像“上”“下”“左”“右”四个按键一样使用这个键
滚动：像滚轮一样使用这个键，报告水平和垂直滚动量
径向菜单：像一个圆形菜单一样使用这个键
按键：像按键一样使用这个键，可以处理触摸、点击、按下、双击和长按。
切换按键：像切换一样使用这个键，按一下为开启，再按一下为关闭。

我们需要的是“摇杆”用法，因为这样才能产生我们需要的移动玩家的“Vector2”类型的输入数据。于是我们选择“摇杆”。

现在，以摇杆的方式使用这个键可以产生三种不同的输入：

点击：按下这个摇杆键时触发
触摸：摇杆键被触摸时触发
位置：推动摇杆时触发，产生位置输入（这是我们需要的输入）

▲ 三种不同的输入

我们在“位置”上点击，在打开的新界面中，我们可以看到它产生“矢量2”类型的数据，并且还能发现我们刚刚在 Unity 编辑器中定义的“Direct Movement”动作。我们选择它。

点击“✔️”来确定对这个摇杆键的设置。

▲ 确认摇杆键的设置

为了使我们的按键设置直接修改到我们的源代码，我们点击整个界面右下角的“替换默认按键设置”按钮，这将直接修改我们代码中的按键绑定文件。

▲ 替换默认按键设置

运行

现在，回到 Unity 编辑器，运行一下。可以看到，已经可以通过摇杆来控制玩家移动了。

Unity OpenVR 虚拟现实入门四：通过脚本控制手与控制器

Sun, 16 May 2021 09:50:13 +0000

在 Unity 的帮助下，虚拟现实应用的开发非常容易。不过国内竟然还是没有什么教程，所以这里就来一点入门的，适合新手。

本文将基于第三篇的简单场景，打开和关闭控制器的显示。

系列博客：

添加脚本

本文继续第三篇的内容。

在“Player”上添加脚本。我们在“Update”中简单添加一些代码：

using UnityEngine;

using Valve.VR;
using Valve.VR.InteractionSystem;

public class PlayerDemoScript : MonoBehaviour
{
    public bool showControllers;

    void Update()
    {
        foreach (var hand in Player.instance.hands)
        {
            if (showControllers)
            {
                hand.ShowController();
                hand.SetSkeletonRangeOfMotion(EVRSkeletalMotionRange.WithController);
            }
            else
            {
                hand.HideController();
                hand.SetSkeletonRangeOfMotion(EVRSkeletalMotionRange.WithoutController);
            }
        }
    }
}

这样，当 showControllers 被设置为 true 时，可以同时显示手与控制器，当设置为 false 时，则只显示手。

这里 ShowController 是显示控制器，HideController 是隐藏控制器。后面的 SetSkeletonRangeOfMotion 是让手的骨骼动画适配控制器，如果指定为 WithController 则会在运动手指的时候握紧时只会握住控制器，而不会穿模到控制器里面；反之，握紧的时候则不考虑控制器的位置，会穿模。

▲ 手握住控制器

运行

运行场景，当我们在“检查器”中勾选“showControllers”时，会在场景中看到手握住控制器。

Unity OpenVR 虚拟现实入门五：通过传送控制玩家移动

Sun, 16 May 2021 09:47:41 +0000

在 Unity 的帮助下，虚拟现实应用的开发非常容易。不过国内竟然还是没有什么教程，所以这里就来一点入门的，适合新手。

本文将基于第四篇的简单场景，通过传送的方式控制玩家移动。

系列博客：

搭建一个简单的场景

基于之前第四篇中我们添加的“Player”和控制器，我们这里简单打建一个场景。于是我们添加一个 3D 物体——“平面”——这足够简单。当然这不是必要的，只是会让我们后续的玩家移动看起来是踩在地面上，而不是悬在空中。

▲ 创建平面

创建完记得在检查器里面将平面的位置设置到 (0,0,0)。

▲ 设置平面的位置

创建传送动作

在资源中定位到“SteamVR”->“InteractionSystem”->“Teleport”->“Prefabs”，找到“Teleporting”然后将它拖拽到场景中。

只需要运行场景，你就能发现在推动手柄摇杆时就能传送了：

▲ 传送

不过，我们只能做出这个传送的动作，而不会真正地传送出去，因为我们还没有传送的“目的地”。

创建传送目的地

依然是在“SteamVR”->“InteractionSystem”->“Teleport”->“Prefabs”中。这次，我们拖拽“TeleportPoint”进入场景。

▲ 拖拽 TeleportPoint 进入场景

我们拖拽多个这样的传送目的地到场景中，运行看看效果。

可传送到目的地

在这张图片中，白色的地面让传送点很难看清，我们随便找一个非白色的材质拖拽到平面上。这里我直接使用“SteamVR”->“InteractionSystem”->“Teleport”->“Textures”里的“TeleportArea”材质（偷懒）。

创建传送目的区域

不过，只是传送到某个点的话，更像是看某场全景电影。要实现更加沉浸的体验，我们需要能让场景中的大多数地面都可被传送。

创建一个新的平面，同样将位置调整到 (0,0,0)，再调整大小，将其与之前的白色“地面”重叠在一起。不过这个新的平面，我们要添加一个“TeleportArea”的脚本。

▲ 添加脚本 Teleport Area

运行看看，发现并不能传送（如下图）：

无法传送

这是因为，我们创建的这两的平面完全重叠了。我们只需要将“TeleportArea”那个平面的 Y 坐标稍微向上移动一点点（例如 0.1 个单位）就可以了。

▲ Y 移动一点点

▲ 可以传送了

Unity OpenVR 虚拟现实入门二：一个最简单的虚拟现实游戏/程序

Sun, 16 May 2021 08:51:42 +0000

在 Unity 的帮助下，虚拟现实应用的开发非常容易。不过国内竟然还是没有什么教程，所以这里就来一点入门的，适合新手。

本文将开发一个最简单的虚拟现实应用。

系列博客：

安装 SteamVR

出于性能考虑，Unity 编辑器已经把“资源商店”（Assets Store）从编辑器里面移到了浏览器。所以大家可以去 https://assetstore.unity.com/ 下载资源。

搜索“Steam VR”，找到“SteamVR Plugin”插件（https://assetstore.unity.com/packages/tools/integration/steamvr-plugin-32647），直接点“添加至我的资源”。（如果需要登录，就登录一下。）然后，顶部会弹出在 Unity 编辑器中打开的提示，选“是”就好了。

▲ SteamVR Plugin

在 Unity 编辑器中，如果网络状况不太好，可能需要等待非常久的时间才能刷出 SteamVR 插件的导入界面。

▲ 下载导入 SteamVR Plugin

当成功显示了 SteamVR 下载界面后，点击右下角的“下载”按钮。等待下载完成后，点击“导入”按钮。这样，你的项目中就有了 SteamVR 的插件了。

接下来，我们将利用 SteamVR 插件来开发我们的第一个虚拟现实应用。

第一个虚拟现实应用

因为我们刚刚安装了 SteamVR 插件，所以我们可以在界面的资产面板中看到“SteamVR”文件夹，定位到“SteamVR”-“InteractionSystem”->“Core”->“Prefabs”，找到“Player”，然后将它拖入到场景中（如图）。

▲ 拖入 Player 预制件

然后，点击顶部的“▶”按钮开始调试你的第一个虚拟现实应用。

▲ 开始调试

如果询问你还没有生成 SteamVR 的输入行为，是否要打开输入窗口时，点“是”。并在最后点击“Save and generate”。

▲ SteamVR 输入窗口

随后，拿起你的头戴式显示器（HMD，Head-mounted display），享受你的第一个虚拟现实应用（也许是游戏）吧！

可以点开下面的视频看看我运行的效果：

▲ 实机运行效果

Unity OpenVR 虚拟现实入门三：最简单的五指交互

Sun, 16 May 2021 08:06:12 +0000

在 Unity 的帮助下，虚拟现实应用的开发非常容易。不过国内竟然还是没有什么教程，所以这里就来一点入门的，适合新手。

本文将基于前两篇搭建的环境，做一个简单的五指交互。

系列博客：

前提

你需要有一个在第二篇中做出的“Player”。

▲ Unity 编辑器中的 Player

将控制器换成手

找到场景中的“Player”->“SteamVRObjects”，选择“LeftHand”，在“检查器”中找到“Render Model Prefab”。

▲ Render Model Prefab

将前面在“SteamVR”->“InteractionSystem”->“Core”->“Prefabs”中的其他种类的左手拖拽到检查器的“Render Model Prefab”中。例如，我们拖入了“LeftRenderModel”。

▲ 拖入 LeftRenderModel

SteamVR 中自带的其他几种控制器模型有：

▲ SteamVR 自带的手模型

同样，我们将右手也替换一个模型。

运行

运行我们刚刚替换过手模型的场景，看看效果：

▲ RenderModel

▲ RenderModel Floppy

Unity OpenVR 虚拟现实入门一：安装配置 Unity + OpenVR 环境

Sun, 16 May 2021 08:06:12 +0000

在 Unity 的帮助下，虚拟现实应用的开发非常容易。不过国内竟然还是没有什么教程，所以这里就来一点入门的，适合新手。

本文将搭建好虚拟现实的开发环境。

系列博客：

第一步：安装 Unity Hub

去官网 https://unity.cn/releases 下载 Unity Hub。这是必要的，因为 Unity 编辑器的运行一定要先安装有 Unity Hub，且必须始终保持最新版，否则可能还会导致无法连接。

下载完成后安装即可。

▲ Unity Hub 界面

第二步：安装最新版本的 Unity 编辑器

启动 Unity Hub，然后选择左侧的“安装”，再选择右上角的“安装”选择你当前最新版本的 Unity，点“下一步”，选“安装”。然后等就好了。

▲ 安装最新版本 Unity 编辑器 1/2

▲ 安装最新版本 Unity 编辑器 2/2

第三步：安装 XR 插件管理器

在 Unity Hub 中，新建一个项目，然后等这个项目被 Unity 编辑器打开。首次创建项目或第一次打开某个项目会等很久，在恢复项目中所需的包。耐心等待吧。

▲ 等待创建项目

▲ XR 插件管理

等你看到 Unity 编辑器的界面后，选择“编辑”->“项目设置”，在打开的项目设置窗格中，拉到最下面的“XR 插件管理”然后选择它。在里面，你可以看到“安装 XR 插件管理”的按钮，点击它，然后等上几分钟到数小时，直到安装完成。安装完成后，需要重启 Unity 编辑器。

▲ Unity 编辑器界面

重启完编辑器后，再进入到最底部的“XR Plug-in Management”则可以看到已经加载完成的“XR Plug-in Management”插件。勾选你打算适配的虚拟现实设备。

▲ XR Plug-in Management

WPF 制作高性能的透明背景异形窗口（使用 WindowChrome 而不要使用 AllowsTransparency=True）

Sat, 16 Jan 2021 00:30:49 +0000

在 WPF 中，如果想做一个背景透明的异形窗口，基本上都要设置 WindowStyle="None"、AllowsTransparency="True" 这两个属性。如果不想自定义窗口样式，还需要设置 Background="Transparent"。这样的设置会让窗口变成 Layered Window，WPF 在这种类型窗口上的渲染性能是非常糟糕的。

本文介绍如何使用 WindowChrome 而不设置 AllowsTransparency="True" 制作背景透明的异形窗口，这可以避免异形窗口导致的低渲染性能。

背景透明的异形窗口

如下是一个背景透明异形窗口的示例：

此窗口包含很大的圆角，还包含 DropShadowEffect 制作的阴影效果。对于非透明窗口来说，这是不可能实现的。

如何实现

要实现这种背景透明的异形窗口，需要为窗口设置以下三个属性：

WindowStyle="None"
ResizeMode="CanMinimize" 或 ResizeMode="NoResize"
WindowChrome.GlassFrameThickness="-1" 或设置为其他较大的正数（可自行尝试设置之后的效果）

如下就是一个最简单的例子，最关键的三个属性我已经高亮标记出来了。

    <Window x:Class="Walterlv.Demo.MainWindow"
            xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
            xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
++          WindowStyle="None" ResizeMode="CanMinimize"
            Title="walterlv demo" Height="450" Width="800">
++      <WindowChrome.WindowChrome>
++          <WindowChrome GlassFrameThickness="-1" />
++      </WindowChrome.WindowChrome>
        <Window.Template>
            <ControlTemplate TargetType="Window">
                <Border Padding="64" Background="Transparent">
                    <Border CornerRadius="16" Background="White">
                        <Border.Effect>
                            <DropShadowEffect BlurRadius="64" />
                        </Border.Effect>
                        <ContentPresenter ClipToBounds="True" />
                    </Border>
                </Border>
            </ControlTemplate>
        </Window.Template>
        <Grid>
            <TextBlock FontSize="20" Foreground="#0083d0"
                   TextAlignment="Center" VerticalAlignment="Center">
                <Run Text="欢迎访问吕毅的博客" />
                <LineBreak />
                <Run Text="blog.walterlv.com" FontSize="64" FontWeight="Light" />
            </TextBlock>
        </Grid>
    </Window>

网上流传的主流方法

在网上流传的主流方法中，AllowsTransparency="True" 都是一个必不可少的步骤，另外也需要 WindowStyle="None"。但是我一般都会极力反对大家这么做，因为 AllowsTransparency="True" 会造成很严重的性能问题。

如果你有留意到我的其他博客，你会发现我定制窗口样式的时候都在极力避开设置此性能极差的属性：

WPF 使用 WindowChrome，在自定义窗口标题栏的同时最大程度保留原生窗口样式（类似 UWP/Chrome）

性能对比

既然特别说到性能，那也是口说无凭，我们要拿出数据来说话。

以下是我用来测试渲染性能所使用的例子：

相比于上面的例子来说，主要就是加了背景动画效果，这可以用来测试帧率。

    <Window x:Class="Walterlv.Demo.MainWindow"
            xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
            xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
            WindowStyle="None" ResizeMode="CanMinimize"
            Title="walterlv demo" Height="450" Width="800">
        <WindowChrome.WindowChrome>
            <WindowChrome GlassFrameThickness="-1" />
        </WindowChrome.WindowChrome>
        <Window.Template>
            <ControlTemplate TargetType="Window">
                <Border Padding="64" Background="Transparent">
                    <Border CornerRadius="16" Background="White">
                        <Border.Effect>
                            <DropShadowEffect BlurRadius="64" />
                        </Border.Effect>
                        <ContentPresenter ClipToBounds="True" />
                    </Border>
                </Border>
            </ControlTemplate>
        </Window.Template>
        <Grid>
++          <Rectangle x:Name="BackgroundRectangle" Margin="0 16" Fill="#d0d1d6">
++              <Rectangle.RenderTransform>
++                  <TranslateTransform />
++              </Rectangle.RenderTransform>
++              <Rectangle.Triggers>
++                  <EventTrigger RoutedEvent="FrameworkElement.Loaded">
++                      <BeginStoryboard>
++                          <BeginStoryboard.Storyboard>
++                              <Storyboard RepeatBehavior="Forever">
++                                  <DoubleAnimation Storyboard.TargetName="BackgroundRectangle"
++                                                   Storyboard.TargetProperty="(UIElement.RenderTransform).(TranslateTransform.X)"
++                                                   From="800" To="-800" />
++                              </Storyboard>
++                          </BeginStoryboard.Storyboard>
++                      </BeginStoryboard>
++                  </EventTrigger>
++              </Rectangle.Triggers>
++          </Rectangle>
            <TextBlock FontSize="20" Foreground="#0083d0"
                   TextAlignment="Center" VerticalAlignment="Center">
                <Run Text="欢迎访问吕毅的博客" />
                <LineBreak />
                <Run Text="blog.walterlv.com" FontSize="64" FontWeight="Light" />
            </TextBlock>
        </Grid>
    </Window>

那么性能数据表现如何呢？我们让这个窗口在 2560×1080 的屏幕上全屏渲染，得出以下数据：

方案	WindowChrome	AllowsTransparency
帧率（fps）数值越大越好，60 为最好	59	19
脏区刷新率（rects/s）数值越大越好	117	38
显存占用（MB）数值越小越好	83.31	193.29
帧间目标渲染数（个）数值越大越好	2	1

另外，对于显存的使用，如果我在 7680×2160 的屏幕上全屏渲染，WindowChrome 方案依然保持在 80+MB，而 AllowsTransparency 已经达到惊人的 800+MB 了。

可见，对于渲染性能，使用 WindowChrome 制作的背景透明异形窗口性能完虐使用 AllowsTransparency 制作的背景透明异形窗口，实际上跟完全没有设置透明窗口的性能保持一致。

此性能差异的原理解读，请参阅：

WPF 从最底层源代码了解 AllowsTransparency 性能差的原因

功能对比

既然 WindowChrome 方法在性能上完虐网上流传的设置 AllowsTransparency 方法，那么功能呢？

值得注意的是，由于在使用 WindowChrome 制作透明窗口的时候设置了 ResizeMode="None"，所以你拖动窗口在屏幕顶部和左右两边的时候，Windows 不会再帮助你最大化窗口或者靠边停靠窗口，于是你需要自行处理。不过窗口的标题栏拖动功能依然保留了下来，标题栏上的右键菜单也是可以继续使用的。

方案	WindowChrome	AllowsTransparency
拖拽标题栏移动窗口	保留	自行实现
最小化最大化关闭按钮	丢失	丢失
拖拽边缘调整窗口大小	丢失	丢失
移动窗口到顶部可最大化	丢失	自行实现
拖拽最大化窗口标题栏还原窗口	保留	自行实现
移动窗口到屏幕两边可侧边停靠	丢失	自行实现
拖拽摇动窗口以最小化其他窗口	保留	自行实现
窗口打开/关闭/最小化/最大化/还原动画	丢失	丢失

表格中：

保留 表示此功能无需任何处理即可继续支持
自行实现 表示此功能已消失，但仅需要一两行代码即可补回功能
丢失 表示此功能已消失，如需实现需要编写大量代码

另外，以上表格仅针对鼠标操作窗口。如果算上使用触摸来操作窗口，那么所有标记为 自行实现 的都将变为 丢失。因为虽然你可以一句话补回功能，但在触摸操作下各种 Bug，你解不完……

WPF 程序无法触摸操作？我们一起来找原因和解决方法！

这两种实现的窗口之间还有一些功能上的区别：

方案	WindowChrome	AllowsTransparency
点击穿透	在完全透明的部分点击依然点在自己的窗口上	在完全透明的部分点击会穿透到下面的其他窗口

然而，如果你希望在使用高性能的 WindowChrome 时也依然能点击穿透，那么你需要使用到一点点的小技巧来绕过 WPF 对 WS_EX_LAYERED 窗口样式的锁定。请参见：WPF 制作支持点击穿透的高性能的透明背景异形窗口。

Windows 下的高 DPI 应用开发（UWP / WPF / Windows Forms / Win32）

Mon, 04 Jan 2021 12:33:15 +0000

本文将介绍 Windows 系统中高 DPI 开发的基础知识。由于涉及到坐标转换，这种转换经常发生在计算的不知不觉中；所以无论你使用哪种 Windows 下的 UI 框架进行开发，你都需要了解这些内容，以免不断踩坑。

各种不同的 Windows 桌面 UI 框架

微软主推的 Windows 桌面 UI 框架有：

UWP
WPF
Windows Forms
Win32 与 C++
DirectX

后两者实际上并不是 UI 框架，是 UI 框架的底层不同实现。当然你单纯凭借 Win32 和 DirectX 去开发 GUI 应用也没有人拦你，只不过如果你试图只用 Win32 和 DirectX 而不进行各种 UI 组件封装的话，最终会非常痛苦的。

UWP 只支持 Windows 10（当然也分不同的小版本，兼容起来有些小麻烦）。

WPF 和 Windows Forms 的最新版本只支持 Windows 7 SP1 及以上系统。如果要支持 Windows 7 和更早的系统，你需要降低 .NET Framework 的版本至 4.5.2 及以下；如果要 XP 支持，还需要到 4.0 及以下。

对普通用户而言的 DPI 级别

DPI 值有两种：系统 DPI (System DPI) 和屏幕 DPI (Monitor DPI)。自 Windows Vista 开始引入系统 DPI 概念，自 Windows 8.1 开始引入屏幕 DPI 概念。

在 Windows Vista / 7 / 8 中，操作系统提供了真正的 DPI 的设置：

▲ Windows 7 的 DPI 设置（控制面板 -> 外观与个性化 -> 显示）

这里的设置改的就是系统的 DPI 值。

Windows 7 中还额外提供了传统 Windows XP 风格 DPI 缩放比例的选项（此选项在 Windows 8 之后就删掉了），这也是在修改 DPI 值，只不过可以选择非 1/4 整数倍的 DPI 值。

▲ 自定义 DPI 设置

自 Windows 8.1 开始，操作系统开始可以设置不同屏幕的 DPI 值了：

▲ Windows 10 中的多个屏幕选择

▲ Windows 10 中针对每个屏幕的 DPI 设置

如果用户在设置中更改了系统 DPI 值或屏幕 DPI 值，那么 Windows 系统会提示需要注销才会应用修改。

对于 Windows 8.1 以下的系统，注销是必要的。因为系统 DPI 值如果不注销就不会改变，应用需要在系统重新登录后有了新的 DPI 值时才会正常根据新的系统 DPI 值进行渲染。否则就是系统进行的位图缩放。

对于 Windows 8.1 及以上的系统，注销通常也是必要的。虽然屏幕 DPI 值已经更新，并且已向应用窗口发送了 Dpi Change 消息，但系统 DPI 值依然没变。应用必须处理 Dpi Change 消息才会正常渲染。如果应用不支持屏幕 DPI 感知，那么使用的就是系统 DPI 值，于是一样的会被系统进行位图缩放。

但事情到 Windows 10 (1803) 之后，事情又有了转机。现在，你可以通过在设置中打开一个开关，使得无需注销，只要重新打开应用即可让此应用获取到最新的系统 DPI 的值。

方法是：打开“设置” -> “系统” -> “显示器” -> “高级缩放设置”，在“高级缩放设置”上，打开“允许 Windows 尝试修复应用，使其不模糊”。

额外的，对于 Windows 8.1 及以上的系统，系统 DPI 值等于主屏在系统启动时的屏幕 DPI 值。

对 Windows 应用而言的 DPI 感知级别（Dpi Awareness）

Windows 的 DPI 感知级别经过历代升级，已经有四种了。

无感知 (Unaware)
- DPI 值就是一个常量 96。
- 如果在系统中设置缩放，那么就会采用位图拉伸（会模糊）。
- 更多信息请看本文末尾的故事。
系统级感知 (System DPI Awareness)
- Vista 系统引入。
- 所有显示器上的应用共用这一个 DPI 值。
- 每个用户会话固定一个 DPI 值，修改 DPI 后不需要重启系统而只需要注销当前用户重新登录即可。
- 如果在设置中修改了 DPI，那么就会采用位图拉伸（会模糊）。
屏幕级感知 (Per-Monitor DPI Awareness)
- 随 Windows 8.1 引入
- 应用的 DPI 值会随着所在屏幕的不同而改变。
- 当多个屏幕 DPI 不一样，而应用从一个屏幕切换到另一个屏幕的时候，应用会收到 DPI 改变的消息
- 只有应用的顶层 HWND 会收到 DPI 改变消息
屏幕级感知第二代 (Per-Monitor V2 DPI Awareness)
- 随 Windows 10 (1607) 引入
- 应用的 DPI 值会随着所在屏幕的不同而改变。
- 当多个屏幕 DPI 不一样，而应用从一个屏幕切换到另一个屏幕的时候，应用会收到 DPI 改变的消息
- 应用的顶层和子 HWND 都会收到 DPI 改变消息
- 以下 UI 元素也会在 DPI 改变时缩放
  - 非客户区（Non-client Area）
  - 系统通用控件中的位图（comctl32V6）
  - 对话框（CreateDialog）

在 Windows 10 19H1 中，可以直接在任务管理器中查看到进程的 DPI Awareness：

▲ 在任务管理器中查看 DPI Awareness

方法是在任务管理器中 Details 的标题栏右键，选择列，然后找到 DPI Awareness。

可以看到，目前仅文件资源管理器是 Per-Monitor V2 的。

关于在任务管理器中查看 DPI，可以阅读我的另一篇博客：

Windows 系统上使用任务管理器查看进程的各项属性（命令行、DPI、管理员权限等） - 吕毅

任务管理器上关于 DPI 的中文翻译也是蛮有意思的。

不同 UI 框架对 DPI 的支持情况

UWP

UWP 当然支持最新的各种 DPI 感知级别，而且是完全支持。

WPF

WPF 的最新版支持最新的 DPI 感知级别，不过依然有限制：

Native WPF applications will DPI scale WPF hosted in other frameworks and other frameworks hosted in WPF do not automatically scale

即原生 WPF 应用支持 DPI 缩放，在其他 UI 框架中的 WPF 也支持 DPI 缩放；但是 WPF 中嵌入的其他 UI 框架不支持自动 DPI 缩放。

WPF 第一个版本（随 .NET Framework 3.5 发布）就已支持系统级 DPI 感知。

.NET Framework 4.6.2 开始的 WPF 才开始支持屏幕级 DPI 感知。而 Per-Monitor V1 和 Per-Monitor V2 的支持在操作系统级别是兼容的，所以只需要修改 WPF 中的应用程序清单即可兼容第二代屏幕级 DPI 感知。

Windows Forms

Windows Forms 也是在 .NET Framework 4.7 才开始支持屏幕级 DPI 感知的。不过部分控件不支持自动随屏幕 DPI 切换。

其他 UI 框架

原生 Win32 是支持最新 DPI 感知的，其他如 GDI/GDI+/MFC 等都不支持，除非开发者手工编写。

混合 DPI 感知级别

当项目足够大的时候，一个或几个项目成员可能很难了解所有的窗口逻辑。让一个进程的所有窗口开启 DPI 缩放对应用的高 DPI 迁移来说比较困难。不过好在我们可以开启混合 DPI 缩放。

Windows 10 (1604) 开始引入顶级窗口（Top-level Window）级别的 DPI 感知，而 Windows 10 (1703) 开始引入每一个 HWND 的 DPI 感知，包括顶级窗口和非顶级窗口。这里的顶级窗口指的是没有父级的窗口，指的是 Parent，而不是 Owner。（实际上 API 在更早版本就引入了，这里有故事，详见本文末尾。）

在创建一个窗口的前后分别调用 SetThreadDpiAwarenessContext 函数可以让创建的这个窗口具有单独的 DPI 感知级别。前一次是为了让窗口在创建时有一个对此线程的新的 DPI 感知级别，而后一次调用是恢复此线程的 DPI 感知级别。

关于混合 DPI 感知级别的其他内容，可以阅读官网：Mixed-Mode DPI Scaling and DPI-aware APIs - Microsoft Docs。

微软的 Office 系列就是典型的使用了混合 DPI 感知级别的应用。在以下实验中，我组成了一个 96 DPI 的主屏和 144 DPI 的副屏，先在 96 DPI 的屏幕上截一张图，再将窗口移动到 144 DPI 的屏幕中再截一张图。

Microsoft PowerPoint 使用的是系统 DPI 感知级别：

▲ 96 DPI 下的主界面

▲ 144 DPI 下的主界面

你可以通过点开图片查看原图来比较这两幅图在原图尺寸下的模糊程度。

Microsoft PowerPoint 的演示页面使用的是屏幕 DPI 感知级别：

▲ 96 DPI 下的演示页面

▲ 144 DPI 下的演示页面

可以看到，演示页面在多屏 DPI 下是没有产生缩放的模糊，即采用了屏幕 DPI 感知级别。

而以上的主界面和演示页面属于同一个进程。

▲ 只有一个 PowerPoint 进程

DPI 相关的 Windows API 的迁移

GetSystemMetrics -> GetSystemMetricsForDpi
AdjustWindowRectEx -> AdjustWindowRectExForDpi
SystemParametersInfo -> SystemParametersInfoForDpi
GetDpiForMonitor -> GetDpiForWindow

关于 DPI 相关 API 变化的故事

感谢 Mouri_Naruto（毛利）提供的故事，API 的具体使用也可参考他的文章：【原创】实现每显示器高DPI识别(Per-Monitor DPI Aware)的注意事项。

关于 Windows 10

前文提到 Per-Monitor V2 是 Windows 10 (1703) 引入的，微软官方文档 High DPI Desktop Application Development on Windows - Win32 apps 也是这么写的。但实际上更早的 Windows 10 (1607) 就引入了相关 API，包括 SetThreadDpiAwarenessContext 和 PerMonitorV2 应用程序清单。并且更早的，V2 带来的非客户区缩放和子窗口 DPI 变更消息的 API 在 1507 和 1511（分别是 Windows 10 的第一和第二个正式版本）就已经有了，不过是未公开的（可参阅【原创】实现每显示器高DPI识别(Per-Monitor DPI Aware)的注意事项）。1607 开始这两个非公开 API 不能使用了，因为换成了新的 API，参见 Setting the default DPI awareness for a process (Windows) - Win32 apps。

可以发现微软实际上宣称 1607 已经支持 Per-Monitor V2 了，而完整支持是在 1703。所谓的“完整”体现在这些地方：

comctl32 从 1703 开始完整支持缩放（参见 High DPI Scaling Improvements for Desktop Applications and “Mixed Mode” DPI Scaling in the Windows 10 Anniversary Update (1607) - Windows Developer Blog）
如果你指定了 PerMonitor 但没指定 PerMonitorV2，那么 1607 默认是 PerMonitor，1703 默认是 PerMonitorV2。

关于 Windows Vista 之前的系统

感谢 Mouri_Naruto（毛利）提供的历史：

Windows Vista 之前的系统不代表就对 DPI 无感知，事实上 Windows Vista 之前的版本，大概是 Windows 98 开始就支持通过 GDI 相关的 API 获取当前系统的 DPI 值（当时 Windows Phone 之前的 Windows 移动端 OS 通过这种 API 支持 PPI 高达 280 的手机屏幕，毕竟我也算是 2008 年就入手 HTC Touch Diamond 的用户，那个屏幕的 PPI 值（PPI 280）直到 iPhone Retina 概念（PPI 320）出现后才超过）。

只是 Windows Vista 提供了对不明确表示 DPI 支持的应用的暴力缩放（通过 Desktop Window Manager 合成实现），毕竟那个时代除了手机之外，基本没有什么屏幕涉及到高 DPI。

倒是 Windows Vista 之前的系统的 DPI 修改是需要重启机器的……所以当时我作死给我的手机修改 DPI 也是要重启的（Windows CE 5.2 内核）

Vista 之前的版本，系统中设置缩放，如果你做到了 System Aware 的要求位图是不会模糊的（Vista 引入 DWM 虚拟化强制拉伸，主要是当时的引用没有做相关支持，在高 DPI 情况下会控件会变得非常小且布局大概率会乱掉）。

参考资料

适合 .NET 开发者用的 GitHub Actions（时不时更新）

Thu, 03 Dec 2020 09:44:51 +0000

本文制作并长期更新适合 .NET 开发者用的 GitHub Actions。整理方式为整个文件而不是单个可用的模块，这样可以方便大家以最快的速度为自己的项目添加 GitHub Actions。当然自己改改也可。

.NET 编译与单元测试（全平台）

功能：编译你的 .NET 项目，并进行单元测试。

适用：如果你的项目是纯 .NET 项目，无论项目是 .NET Core 还是 .NET Framework，无论是 Asp.NET Core 还是 WPF / Windows Forms，都可以用这个文件来编译和单元测试。

要求：仓库的根目录有且仅有一个 sln 文件，且这个文件包含了所有重要的项目和单元测试。

name: .NET Build & Test

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

jobs:
  build:
    strategy:
      matrix:
        configuration: [Debug, Release]
    runs-on: windows-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Setup
        uses: actions/setup-dotnet@v1
      - name: Build
        run: dotnet build --configuration $env:Configuration
        env:
          Configuration: ${{ matrix.configuration }}
      - name: Test
        run: dotnet test --configuration $env:Configuration
        env:
          Configuration: ${{ matrix.configuration }}

.NET 编译与单元测试（仅限 Windows 系统下的编译）

功能：编译你的 .NET 项目，并进行单元测试。

要求：仓库的根目录有且仅有一个 sln 文件，且这个文件包含了所有重要的项目和单元测试。

name: .NET Build & Test

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

jobs:

  build:

    strategy:
      matrix:
        configuration: [Debug, Release]

    runs-on: windows-latest

    steps:
    - name: Checkout
      uses: actions/checkout@v2
      with:
        fetch-depth: 0

    # 安装 .NET Core
    - name: Install .NET Core
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: 3.1.202

    # 添加 MSBuild.exe 到环境变量: https://github.com/microsoft/setup-msbuild
    - name: Add msbuild to PATH
      uses: microsoft/setup-msbuild@v1.0.2

    # 安装 NuGet（如果后面需要，可以使用它）
    - name: Setup NuGet
      uses: nuget/setup-nuget@v1
      with:
        nuget-api-key: ${{ secrets.NuGetAPIKey }}
        nuget-version: '5.x'

    # 编译整个项目
    - name: Build the solution
      run: msbuild /p:Configuration=$env:Configuration -restore
      env:
        Configuration: ${{ matrix.configuration }}

    # 执行单元测试
    - name: Execute unit tests
      run: dotnet test -c $env:Configuration
      env:
        Configuration: ${{ matrix.configuration }}

在这个文件中：

我们测试编译了 DEBUG 和 Release 两个不同的环境
我们使用的是 msbuild 来编译，因为这样对旧项目的兼容性最好，当然也就失去了跨平台的能力

NuGet Push

功能：如果你的项目是要推送 NuGet 包的，那么可以使用此工作流推送 NuGet 包。

适用：任何 .NET 项目。

要求：仓库的根目录有且仅有一个 sln 文件。

name: NuGet Push

on:
  push:
    branches:
      - master

jobs:
  build:
    runs-on: windows-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Setup
        uses: actions/setup-dotnet@v1
      - name: Pack
        run: dotnet build --configuration Release
      - name: Push
        run: dotnet nuget push .\bin\Release\*.nupkg --source https://api.nuget.org/v3/index.json --api-key ${{ secrets.NuGetAPIKey }} --skip-duplicate --no-symbols 1

关于最后的那个参数 1，很魔性，只要有任何一个值都行。参见：dotnet nuget push - Missing value for option · Issue #4864 · NuGet/Home。

自带环境

GitHub Actions 自带了很多环境可以用，这些自带的环境不需要再去配了：

virtual-environments/Windows2019-Readme.md at master · actions/virtual-environments

各个版本 Windows 10 的名称、完整版本号、开发代号和系统自带的 .NET Framework 版本

Mon, 30 Nov 2020 06:55:30 +0000

Windows 10 名称	Windows 版本	开发代号	自带的 .NET Framework 版本
预览中	预览中	—	—
October 2020 Update	10.0.19042 (20H2)	20H2	.NET Framework 4.8
May 2020 Update	10.0.19041 (2004)	20H1	.NET Framework 4.8
November 2019 Update	10.0.18363 (1909)	19H2	.NET Framework 4.8
Windows 10 May 2019 Update	10.0.18362 (1903)	19H1	.NET Framework 4.8
Windows 10 October 2018 Update	10.0.17763 (1809)	RS5	.NET Framework 4.7.2
Windows 10 April 2018 Update	10.0.17134 (1803)	RS4	.NET Framework 4.7.2
Windows 10 Fall Creators Update	10.0.16299 (1709)	RS3	.NET Framework 4.7.1
Windows 10 Creators Update	10.0.15063 (1703)	RS2	.NET Framework 4.7
Windows 10 Anniversary Update	10.0.14393 (1607)	RS1	.NET Framework 4.6.2
Windows 10 November Update	10.0.10586 (1511)	TH2	.NET Framework 4.6.1
Windows 10	10.0.10240 (1507)	TH1	.NET Framework 4.6

Windows Server 名称	自带的 .NET Framework 版本
Windows Server 1803	.NET Framework 4.7.2
Windows Server 1709	.NET Framework 4.7.1
Windows Server 2016	.NET Framework 4.6.2

参考资料

使用 Xamarin 在 iOS 真机上部署应用进行调试

Sat, 31 Oct 2020 01:00:51 +0000

虽然 Xamarin 可以在 Windows 操作系统上编写和调试，但如果开发 iOS 应用，那么我们依然需要一台安装有 XCode 和 Visual Studio for Mac 的 Mac 电脑。做真机部署不是像平时使用太阳系第一 IDE Visual Studio 那样方便。

所以本文需要介绍如何使用 Xamarin 在 iOS 真机上部署应用进行调试，然后顺便说一些注意事项。

准备一台 Mac 电脑

如果你没有 Mac 电脑，那我只能很不幸地告诉你：本文读下去已经没有什么用了，你不会成功的……当然你也可以考虑使用 Mac OS 虚拟机，但成功率太低，本文不会涉及。

在 Mac 电脑上安装以下两款必备应用：

XCode：从苹果应用商店安装
Visual Studio for Mac：在这里下载 https://visualstudio.microsoft.com/vs/mac/

这两款应用的体积都很大，如果你没有很好的网络代理设置，安装一整天都是可能的。所以还是强烈建议你有一个稳定的代理网络来下载。

本文接下来的内容都假设你已经安装好了这两款应用。

背景知识

你需要知道一些背景知识，不然后面真机部署的时候失败了都不知道怎么回事。

你的账号必须是苹果开发者账号
- 只需要注册 Apple Developer Portal，不需要注册 Apple Developer Program
只有 XCode 才能生成开发者的 provisioning profiles
只有 XCode 才能在 iOS 真机上部署全新的应用

也就是说，你必须有一些操作是在 XCode 中完成；只使用 Visual Studio for Mac 是无法完成部署任务的。

在 XCode 中准备

在 XCode 中新建一个空白 iOS 项目（什么类型都可以），这个项目随时可以丢弃。
选择你新建的项目，会出现这个项目的信息可以填，默认在 General 标签中。
*[重要] 修改 Bundle Identifier。
- 将这个 Bundle Identifier 修改为你希望部署的应用的 Bundle Identifier。比如你在 Xamarin 的 Info.plist 中写的 Bundle Identifier 是 com.walterlv.CloudKeyboard，那么这里也必须写 com.walterlv.CloudKeyboard。
*[重要] 一定要让这个 Bundle Identifier 文本框失焦（比如按下 Tab 或在其他文本框中点一下）。
- 这个时候下面的 Signing Certificate 会出现一个加载中的动画，大概持续不到一秒钟，就会生成 iPhone Developer 的信息，这个就是包含 provisioning profiles 的信息（可以在 Provisioning Profile 旁边的感叹号中看到详细信息）
在 Mac 上插入你的 iPhone，解锁 iPhone，等待左上角出现你 iPhone 的名称和图标。
点击 XCode 左上角的运行按钮，等待这个空白的应用部署到你的手机上。

更新：XCode 新版本的界面布局和本文略有不同，可前往以下链接查看变化：

*[重要] 额外的，如果你开发的是 iOS 扩展，有两个或者更多的包，那么你需要重复步骤 3 到 6。也就是不断地修改 Bundle Identifier，等待生成新的 Developer 信息，然后部署这个空的应用

在 Visual Studio for Mac 中部署

*[重要] 请回到你的 iPhone 手机，删除刚刚部署的应用
- 如果你刚刚部署了多个空白应用，那么都要删除
回到 Visual Studio for Mac 并打开你的 Xamarin 项目，然后打开准备部署的应用的 Info.plist 文件
检查 Bundle Identifier，一定要确认跟前面 XCode 中填入的是同一个 Bundle Identifier
- 额外的，如果你是开发 iOS 扩展，有两个或更多包，那么每个包都需要进入 Info.plist 文件检查 Bundle Identifier
点击 Bundle Signing Options，选择刚刚使用 XCode 生成的开发者信息（如果你看不到，那么就是前面 XCode 的步骤没有执行正确）

在 Mac 上插入你的 iPhone，解锁 iPhone，等待左上角出现你 iPhone 的名称和图标。

如果没有出现，你可能需要点击一下 Debug

iPhone 区域，一定要确保选中了 iPhone 而不是 iPhone Simulator

点击 Visual Studio for Mac 左上角的运行按钮，等待你 Xamarin 的应用部署到你的手机上（可能需要数十秒到数分钟）。

理论上经过以上步骤，你就可以在你的 iPhone 上看到你用 Xamarin 开发的应用了。但其实是无法运行的。

如果部署过程中发生了任何错误，请：

检查你的步骤与本文是否有出入；
参考：使用 Xamarin 开发 iOS 应用中需要注意的若干个问题

在 iPhone 上操作

打开设置 -> 通用 -> 设备管理
点开 [自己的开发者账号]，点击 [信任]

如果你是首次进行此操作（实际上阅读本文操作的应该也就是首次了），那么信任自己的开发者账号可能会花比较长的时间，Visual Studio for Mac 的部署调试可能会因为等待超时而调试失败。不过这不重要，你只需要在 Visual Studio for Mac 上点击停止调试，然后再次重来就可以了。

还需要注意，如果你删除了你部署的应用，那么下次部署的时候在 iPhone 上的操作部分需要重新进行。

还需要注意，可能每过 6 天，本文所述的所有步骤都需要重新进行一遍。

设置进程的 RedirectStandardOutput 重定向输出后，如果不将输出读出来，会卡死此进程

Tue, 04 Aug 2020 03:00:19 +0000

设置进程的 RedirectStandardOutput 重定向输出后，必须将其读出来。本文带你做一个实验并得出结论。

重定向输出

一个简单的尝试重定向输出的代码如下：

using var process = new Process
{
    StartInfo = new ProcessStartInfo("Walterlv.Demo.Output.exe")
    {
        UseShellExecute = false,
        CreateNoWindow = true,
        RedirectStandardOutput = true,
    },
};
process.Start();
Console.ReadLine();

正常跑起来的话不会出什么问题。不过对于 Walterlv.Demo.exe 那个进程来说，就比较危险了……

卡死！

Walterlv.Demo.Output.exe 是什么程序呢？自己写的测试程序，如下：

namespace Walterlv.Demo.Output
{
    class Program
    {
        static void Main(string[] args)
        {
            for (var i = 0; i < int.MaxValue; i++)
            {
                System.Console.WriteLine($"[{i.ToString().PadLeft(7)}] Console.WriteLine();");
            }
        }
    }
}

用 Visual Studio 附加到两个进程后，点击“暂停”按钮，会发现

这个 for 循环并没有像平常的其他循环一样瞬间炸裂，而是停在了一个神奇的数字“128”上。点击“继续”按钮，过一会儿再点击“暂停”，依然显示的是“128”。

说明–现在卡死了！

缓冲区已满

因为我们前面的代码使用 Console.ReadLine() 等待用户输入，我们在下一行打一个断点，可以在按下回车后进入断点，于是可以观察到 process 里面的各种字段和属性。

可以注意到，StandardOutput 属性中是存在缓冲区的，大小只有 4096 字节。打开 charBuffer 字段，可观察到每一个字节的值。

我们的输出程序，总共输出 128 次即死掉，而每次输出的行（就是那个 [ 1] Console.WriteLine();）我正好安排到 32 个字符。乘起来刚好 4096 大小。

开发注意

如果你重定向了输出流，那么一定记得取出输出数据，否则会导致被启动的程序卡死在下一个 Console.WriteLine 中。

三种方法设置 .NET/C# 项目的编译顺序，而不影响项目之间的引用

Wed, 24 Jun 2020 01:40:36 +0000

当 A 项目引用 B 项目，那么使用 Visual Studio 或者 MSBuild 编译 A 项目之前就会确保 B 项目已经编译完毕。通常我们指定这种引用是因为 A 项目确实在运行期间需要 B 项目生成的程序集。

但是，现在 B 项目可能仅仅只是一个工具项目，或者说 A 项目编译之后的程序集并不需要 B，仅仅只是将 B 打到一个包中，那么我们其实需要的仅仅是 B 项目先编译而已。

本文介绍如何影响项目的编译顺序，而不带来项目实际引用。

方法一：设置 ReferenceOutputAssembly

<ItemGroup>
  <ProjectReference Include="..\Walterlv.Demo.Analyzer\Walterlv.Demo.Analyzer.csproj" ReferenceOutputAssembly="false" />
  <ProjectReference Include="..\Walterlv.Demo.Build\Walterlv.Demo.Build.csproj" ReferenceOutputAssembly="false" />
</ItemGroup>

详见通过 ReferenceOutputAssembly=False 在引用项目时，不额外引入依赖文件 - walterlv。

方法二：设置解决方案级别的项目依赖

此方法可能会是更加常用的方法，但兼容性不那么好，可能在部分旧版本的 Visual Studio 或者 .NET Core 版本的 dotnet build 命令下不容易工作起来。

在解决方案上右键，然后选择“设置项目依赖”：

然后在弹出的项目依赖对话框中选择一个项目的依赖：

详见：通过设置 sln 解决方案依赖，确保不引用的两个项目之间有明确的编译顺序 - walterlv。

方法三：使用 MSBuild 编译任务来编译其他项目

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFramework>net48</TargetFramework>
    </PropertyGroup>

    <Target Name="BuildTheCompilerProject" BeforeTargets="BeforeBuild">
        <MSBuild Projects="..\Walterlv.Packages.Compiler\Walterlv.Packages.Compiler.csproj" Targets="Build" Properties="Configuration=$(Configuration);Platform=$(Platform)" />
    </Target>

</Project>

详见 Visual Studio 在编译 A 项目时，确保 B 项目已编译 - walterlv。

使用哪一种？

	ReferenceOutputAssembly	解决方案依赖	MSBuild 编译任务
位置	项目文件（csproj）或编译文件（`.props` / `.targets`）	解决方案文件（sln）	项目文件（csproj）或编译文件（`.props` / `.targets`）
编译项目	✔️生效	❌无效	✔️生效
编译解决方案	✔️生效	✔️生效	✔️生效
拷贝依赖项目的输出文件	否	⚠是	否
要求匹配目标框架 TargetFramework	⚠是	否	否
占用一个编译时机	否	否	⚠是
兼容性	✔️	⚠早期版本的 `dotnet build` 不支持	✔️

✔️优势
❌劣势
⚠可能优可能劣（但在本文场景是劣势）

位置：代码可以写到哪些文件中
编译项目：使用 dotnet build 或者 msbuild 命令来编译时，传入项目文件
编译解决方案：使用 dotnet build 或者 msbuild 命令来编译时，传入解决方案文件
拷贝依赖项目的输出文件：如果 A 项目引用 B 项目，那么 B 项目的输出文件会被自动拷贝到 A 项目的输出目录中
要求匹配目标框架：必须匹配的框架才能引用，例如 net48 能引用 net45，netcoreapp3.1 能引用 netstandard2.0，但 net45 不能引用 netcoreapp3.1
占用一个编译时机：在此编译时机之前的依赖是无效的（详见：Visual Studio 在编译 A 项目时，确保 B 项目已编译）

参考资料

Question about Visual Studio *.sln file format - Stack Overflow

通过设置 sln 解决方案依赖，确保不引用的两个项目之间有明确的编译顺序

Wed, 24 Jun 2020 01:04:14 +0000

有时在编译解决方案的时候，希望两个项目有明确的编译顺序，而不是自动决定，或者在并行编译的时候同时编译。

本文介绍通过设置 sln 解决方案依赖来解决编译顺序问题。

设置解决方案级别的项目依赖

在解决方案上右键，然后选择“设置项目依赖”：

然后在弹出的项目依赖对话框中选择一个项目的依赖：

这时，如果看看解决方案文件（.sln）则可以看到多出了 ProjectDependencies 区：

Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Walterlv.Demo", "Walterlv.Demo\Walterlv.Demo.csproj", "{DC0B1D44-5DF4-4590-BBFE-072183677A78}"
	ProjectSection(ProjectDependencies) = postProject
		{98FF9756-B95A-4FDB-9858-5106F486FBF3} = {98FF9756-B95A-4FDB-9858-5106F486FBF3}
	EndProjectSection
EndProject

更多关于 sln 文件的理解，可以阅读我的另一篇博客：

理解 Visual Studio 解决方案文件格式（.sln）

其他方法

本文的方法已加入到此类型解法的方法列表中，详情请看：

三种方法设置 .NET/C# 项目的编译顺序，而不影响项目之间的引用 - walterlv

通过 ReferenceOutputAssembly=False 在引用项目时，不额外引入依赖文件

Wed, 24 Jun 2020 00:42:26 +0000

正常当两个 .NET 项目有引用的时候，会将一个的输出拷贝到另一个的输出目录下。但有时我们只是希望通过引用建立一个依赖关系而已，最终两个项目的输出是独立的。

通过本文的方法，你可以在 A 项目编译时，确保 B 项目已经编译，而无需引用 B。

ReferenceOutputAssembly=False

依然在项目中使用往常习惯的方法设置项目引用：

但是，在项目引用设置完成之后，需要打开项目的项目文件（.csproj）给 ProjectReference 节点加上 ReferenceOutputAssembly 的属性设置，将其值设置为 false。这表示仅仅是项目引用，而不将项目的任何输出程序集作为此项目的依赖。

<ItemGroup>
  <ProjectReference Include="..\Walterlv.Demo.Analyzer\Walterlv.Demo.Analyzer.csproj" ReferenceOutputAssembly="false" />
  <ProjectReference Include="..\Walterlv.Demo.Build\Walterlv.Demo.Build.csproj" ReferenceOutputAssembly="false" />
</ItemGroup>

上面的 ProjectReference 是 Sdk 风格的 csproj 文件中的项目引用。即便不是 Sdk 风格，也是一样的加这个属性。

当然，你写多行也是可以的：

<ItemGroup>
  <ProjectReference Include="..\Walterlv.Demo.Analyzer\Walterlv.Demo.Analyzer.csproj">
    <ReferenceOutputAssembly>false</ReferenceOutputAssembly>
  </ProjectReference>
  <ProjectReference Include="..\Walterlv.Demo.Build\Walterlv.Demo.Build.csproj">
    <ReferenceOutputAssembly>false</ReferenceOutputAssembly>
  </ProjectReference>
</ItemGroup>

这种做法有两个非常棒的用途：

生成代码
- 依赖的项目（如上面的 Walterlv.Demo.Build）编译完成之后会生成一个可执行程序，它的作用是为我们当前的项目生成新的代码的。
- 于是我们仅仅需要在编译当前项目之前先把这个依赖项目编译好就行，并不需要生成运行时的依赖。
NuGet 包中附带其他文件
- 如果要生成 NuGet 包，我们有时需要多个项目生成的文件来共同组成一个 NuGet 包，这个时候我们需要的仅仅是把其他项目生成的文件放到 NuGet 包中，而不是真的需要在 NuGet 包级别建立对此项目的依赖。
- 当使用 ReferenceOutputAssembly 来引用项目，最终生成的 NuGet 包中就不会生成对这些项目的依赖。

其他方法

本文的方法已加入到此类型解法的方法列表中，详情请看：

三种方法设置 .NET/C# 项目的编译顺序，而不影响项目之间的引用 - walterlv

WPF 使用 WindowChrome，在自定义窗口标题栏的同时最大程度保留原生窗口样式（类似 UWP/Chrome）

Tue, 23 Jun 2020 07:16:39 +0000

WPF 自定义窗口样式有多种方式，不过基本核心实现都是在修改 Win32 窗口样式。然而，Windows 上的应用就应该有 Windows 应用的样子嘛，在保证自定义的同时也能与其他窗口样式保持一致当然能最大程度保证 Windows 操作系统上的体验一致性。

本文将使用 WindowChrome 来自定义窗口样式，使其既保留原生窗口样式和交互习惯，又能够具备一定的自定义空间。

使用 Windows 原生窗口体验的应用

在自定义窗口样式的同时保证一致的 Windows 窗口风格体验的优秀应用有这些：

Windows 10 UWP 应用
- 当然少不了 UWP 应用，毕竟这就是 Windows 10 窗口体验的代表
Google Chrome
- 如果我不提第三方应用，你们肯定会说微软都是自己拿内部 API，拿黑科技做的
Windows 文件资源管理器
- Windows 文件资源管理器也有一些自定义（例如在标题栏上放按钮，虽然实际做得很丑），不过整体来说还没 Chrome 做得精致呢

▲ Chrome 普通窗口

▲ Chrome 最大化窗口

为什么不做无边框窗口？

WPF 自定义窗口可是非常容易的，完全自定义样式、异形都不在话下。

<Window x:Class="Walterlv.Whitman.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        xmlns:local="clr-namespace:Walterlv.Whitman"
        mc:Ignorable="d" Title="Whitman" Width="800" Height="450"
        WindowStyle="None" AllowsTransparency="True">
</Window>

然而，这就不贴近原生窗口体验了，有这么多事情都不好模拟：

最小化、最大化、关闭按钮
- 按钮要多大？位置在哪里？图标边距又是多少，颜色值又是什么？鼠标滑入划出的动画效果如何？
窗口标题栏交互
- 标题栏上有右键菜单，如果自己模拟，基本上这个就要自己重新实现了。
窗口的位置和尺寸
- 你需要自己实现一套窗口的拖拽调整位置功能，需要自己实现一套拖拽调整大小的功能。而自己实现的方式在触摸屏下还很容易出现失效的情况。
窗口的阴影
- 要完全模拟 Windows 10 上的窗口阴影效果实在是一件头疼的事情，因为并不知道各种阴影参数是多少；就算模拟出来，性能也是个严重的问题。
窗口的边框颜色
- 虽然窗口边框是被广为吐槽的一点，但为了保证一致的窗口体验，这也是需要模拟的；正常情况和失焦的情况颜色还不一样。
第三方应用集成
- 第三方截图应用可以毫无障碍地捕捉到标准窗口的外框范围，但如果我们没有模拟好（而是拿一个 WPF 无边框窗口模拟），那么第三方截图应用就截不准（可能会超出窗口本来的大小）。

开始使用 WindowChrome

你也许需要先阅读 Window 的 UI 元素及行为 - dino.c 了解一些基本概念。

理论上 WindowChrome 的使用是非常简单的（呃……理论上）。你只需要在 <Window /> 节点里写如下代码便能够完成客户区（Client Area）到非客户区（Non-client Area）的覆盖：

<WindowChrome.WindowChrome>
    <WindowChrome />
</WindowChrome.WindowChrome>

然而，默认的行为却并不那么像原生 Windows 10 窗口。事实上，这样的写法只是简单地把窗口的客户区覆盖到非客户区，原生窗口中的交互还在，但样式都已经被遮挡了。

▲ 样式已经被遮挡

不止是样式被遮挡，我们应该能注意相比于原生还有这些不同：

我们的边框是白色的，原生的边框是系统主题色
鼠标划入我们窗口内才开始拖拽改变大小，但原生的在阴影区域就能开始调整大小了

现在，为了能够观察到 WindowChrome 各种属性设置的效果，我们为 Window 定义一个新的 Template，里面就是空的，这样就没有什么内容能够遮挡我们设置的样式了。

<Window.Template>
    <ControlTemplate TargetType="Window">
        <Border />
    </ControlTemplate>
</Window.Template>

▲ 没有遮挡的窗口

然而即便如此，我们也只解决了系统主题色边框的问题，没有解决调整窗口的拖拽热区问题。而且边框还如此之丑。

GlassFrameThickness

在官方文档 WindowChrome.GlassFrameCompleteThickness Property (System.Windows.Shell) 中有说，如果指定 GlassFrameThickness 值为 -1，那么可以做到整个窗口都遮挡，但实际上全遮挡的效果也是不对劲的，就像下面这样：

<WindowChrome.WindowChrome>
    <WindowChrome GlassFrameThickness="-1" />
</WindowChrome.WindowChrome>

▲ GlassFrameThickness 为 -1

不止边框颜色不见了，连右上角的三个按钮的位置都跟原生不同，这个窗口的位置不贴边。

显然，GlassFrameThickness 属性我们不能指定为 -1。

也不能指定为 0，你可以试试，会发现连阴影都不见了，这更不是我们想要的效果。

▲ GlassFrameThickness 为 0

那我们指定为其他正数呢？

▲ 指定为其他正数

显然，没有一个符合我们的要求。

NonClientFrameEdges

但好在我们还有一个属性可以尝试 —— NonClientFrameEdges。官方文档 WindowChrome.NonClientFrameEdges Property (System.Windows.Shell) 对此的解释是：

Gets or sets a value that indicates which edges of the window frame are not owned by the client.

即指定哪一边不属于客户区。

考虑到我们前面的尝试中发现左、下、右的边框都是不符合要求的，所以我们现在将值设置为 Left,Bottom,Right：

<WindowChrome.WindowChrome>
    <WindowChrome NonClientFrameEdges="Left,Bottom,Right" />
</WindowChrome.WindowChrome>

▲ 比较接近的效果

这回我们终于看到了比较接近原生窗口的效果了，除了窗口的边框效果在激活和非激活状态下与原生窗口一致，连右上角三个按钮的位置也是贴近原生窗口的。甚至拖拽调整窗口大小时的光标热区也是类似的：

▲ 拖拽光标热区

唯一不符合要求的是标题栏高度，这时我们可以继续设置 GlassFrameThickness，把顶部设置得更高一些。

然而设置到多少呢？我测量了一下 Microsoft Store 应用的按钮高度，是 32。

但是，这 32 包括了顶部 1 像素的边框吗？我使用放大镜查看，发现是包含的。

而我们的 GlassFrameThickness 属性也是包含这个 1 像素边框的。所以含义一致，我们可以考虑直接将 32 设置到属性中：

<WindowChrome.WindowChrome>
    <WindowChrome GlassFrameThickness="0 32 0 0" NonClientFrameEdges="Left,Bottom,Right" />
</WindowChrome.WindowChrome>

然而实测结果是 —— 又被耍了，虽然标题栏有 32 的高度，但按钮只有 30 而已：

而且在最大化窗口之后，按钮高度继续压缩。标题栏只剩下 24 的高度，按钮只剩下 22 的高度了。

这显然也模拟得不像。于是，我们霸气一点，直接把顶部边距改得更大。为了凑个整，我写 64 好了。

<WindowChrome.WindowChrome>
    <WindowChrome GlassFrameThickness="0 64 0 0" NonClientFrameEdges="Left,Bottom,Right" />
</WindowChrome.WindowChrome>

虽然正常状态下的按钮依然是 30 高度，但最大化时还是 30 高度这一点与原生 UWP 窗口和 Chrome 的行为是类似的。（UWP 窗口按钮 32 高度，最大化 32 高度；Google Chrome 窗口按钮 30 高度，最大化 27 高度。）

所以，截至这里，我们算是模拟得比较像了。

其他的属性需要尝试吗？CornerRadius, ResizeBorderThickness, ResizeGripDirection, UseAeroCaptionButtons 在默认情况下的行为就已经够了；而 IsHitTestVisibleInChrome 是个与 WPF 相关的附加属性，与模拟窗口样式没有关系。所以基本模拟就靠前面的两个属性了。

定制 Window 的控件模板

WindowChrome 提供客户区内容覆盖到非客户区的能力，所以我们通过定制 Window 的 ControlTemplate 能够在保证原生窗口体验的同时，尽可能定制我们的窗口样式。

在按照以上的方式设置了 WindowChrome 之后，我们能够定制的客户区已经有下图所示的这么多了：

▲ 可定制的客户区

特别注意：可定制区域中顶部是包含那 1 像素的边距的，但其他三边不包含。

下面的窗口是我在冷算法：自动生成代码标识符（类名、方法名、变量名）中所述算法的一个应用，除了右上角的一个白色块，在保证接近原生窗口的情况下，定制了一些内容。

▲ 一个试验品

为了保证标题栏的标题文字也尽可能地接近原生窗口，我也通过测量得出了用于显示标题的 <TextBlock /> 的各种参数。整理之后，写成了下面的样式：

<Window.Template>
    <ControlTemplate TargetType="Window">
        <Border Padding="0 30 0 0">
            <Grid x:Name="RootGrid" Background="{TemplateBinding Background}">
                <Border Background="{TemplateBinding Background}"
                        VerticalAlignment="Top" Height="30" Margin="0 -29 140 0">
                    <TextBlock Foreground="White" Margin="16 0" VerticalAlignment="Center"
                               FontSize="12" Text="{TemplateBinding Title}" />
                </Border>
                <ContentPresenter />
            </Grid>
        </Border>
        <ControlTemplate.Triggers>
            <Trigger Property="WindowState" Value="Maximized">
                <Setter TargetName="RootGrid" Property="Margin" Value="6" />
            </Trigger>
        </ControlTemplate.Triggers>
    </ControlTemplate>
</Window.Template>

需要注意，我写了一个触发器，当窗口最大化时根元素边距值设为 6。如果不设置，最大化时窗口边缘的像素将看不见。这是反复尝试的经验值，且在多种 DPI 下验证是依然有效的。实际上即便是最合适此时设置的 SystemParameters.WindowResizeBorderThickness 属性依然无法让窗口最大化时边缘距离保持为 0。

标题栏上的三大金刚

我们发现，在以上所有方法尝试完成后，还剩下右上角的三颗按钮的背景色无法定制。如果依然采用非客户区控件覆盖的方法，这三个按钮就会被遮挡，只能自己区模拟了，那是不小的工作量。

然而我们还发现，Google Chrome 是定制了这三个按钮的背景色的，正在研究它的做法。

不过 Win32 原生的方法顶多只支持修改标题栏按钮的背景色，而不支持让标题栏按钮全透明。也就是说，Win32 原生方法也许能达到 Google Chrome 的效果，但不可能达到 UWP 中的效果。

为了完全模拟 UWP，标题栏上的按钮只能自绘了。关于自绘标题栏按钮以模拟 UWP 原生按钮，可以阅读我的另一篇文章（代码太长，还是分开了好）：WPF 应用完全模拟 UWP 的标题栏按钮。

原生 Windows 窗口体验

UWP 应用对窗口样式的定制能力是非常小的，远远小于传统 Win32 应用。但因为其与系统原生集成，如果要求保证原生窗口体验，UWP 的定制能力又是各种方法里面最大的，而且 API 非常简单。

如果你正在使用 UWP 开发应用，可参考林德熙的博客 win10 uwp 标题栏来定制标题栏。

参考资料

.NET 程序集/项目/包的版本号设置有最大范围，最大不能超过 65534

Thu, 18 Jun 2020 16:05:08 +0000

试过给 .NET Core 项目设置一个大于 65535 的版本号吗？可能没有，因为设置了会炸！

最简问题项目

用最普通的项目模板创建一个 .NET 项目（要求是 SDK 风格的），于是，你会得到两个文件：项目文件 Walterlv.Demo.csproj 和代码文件 Class1.cs。

Walterlv.Demo.csproj：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>
</Project>

Class1.cs 应该不用贴出来了，因为没啥关系。

现在，我们加个版本号：

    <Project Sdk="Microsoft.NET.Sdk">
      <PropertyGroup>
++      <Version>1.0.0.65535</Version>
        <TargetFramework>netcoreapp3.1</TargetFramework>
      </PropertyGroup>
    </Project>

一编译就立刻编译错误：

然而，只要把版本号改到 65534 或者更小的值就没有问题。

因为我们可以知道，在 SDK 风格的项目当中，版本号的任何一位的范围只能是 0~65534。

传统项目没问题

你可能会说，创建了一个 .NET Framework 的项目，并没有出现问题。

那是因为此问题的复现要求：

必须是 SDK 风格的项目（.NET Core 默认的风格，也可用于 .NET Framework）；
必须是通过 .csproj 或者 .props / .targets 文件来指定的版本号。

这两个条件缺一不可。而通过模板创建的 .NET Framework 项目默认使用的是传统风格的 csproj 项目文件。

如果是传统风格的项目，必须使用 AssemblyInfo.cs 来指定版本号；新的 SDK 风格的版本号也可以使用 AssemblyInfo.cs 来指定版本号。而这两种情况的版本号范围是整个 int 范围（0~2G）。

附，在 SDK 风格项目中使用 AssemblyInfo.cs 来指定版本号前，你需要先用以下属性关闭默认自动生成 AssemblyInfo.cs 功能：

    <Project Sdk="Microsoft.NET.Sdk">
      <PropertyGroup>
        <TargetFramework>netcoreapp3.1</TargetFramework>
++      <GenerateAssemblyInfo>False</GenerateAssemblyInfo>
      </PropertyGroup>
    </Project>

谁的限制？

实际上，版本号限制是 Windows 系统带来的，Windows 系统限制到 65535 了。

虽然你可以通过以上 AssemblyInfo 的方法绕过编译错误，但实际上生成的文件版本会溢出：

.NET 运行时是可以支持 int 范围的版本号的，无奈兼容 Windows 的部分却不行。

参考资料

Visual Studio 在编译 A 项目时，确保 B 项目已编译

Thu, 18 Jun 2020 00:53:17 +0000

如果考虑在你的某个项目中安插一个专门用来做编译的项目，这个项目要求最先编译，那么你会考虑用什么方法呢？

本文讲述在编译 A 项目时，确保 B 项目已编译的方法。

使用 MSBuild 编译目标来编译

A 在编译的时候，需要确保 B 项目已经编译（因为可能用到 B 的输出）。

然而 A 项目并不需要引用 B，因为仅仅是编译需要用到 B 而已，不需要在最终产品中带上 B。

那么在 A 项目中，使用 MSBuild 编译任务来编译 B：

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFramework>net48</TargetFramework>
    </PropertyGroup>

    <Target Name="BuildTheCompilerProject" BeforeTargets="BeforeBuild">
        <MSBuild Projects="..\Walterlv.Packages.Compiler\Walterlv.Packages.Compiler.csproj" Targets="Build" Properties="Configuration=$(Configuration);Platform=$(Platform)" />
    </Target>

</Project>

而 B 项目，则可能是框架完全不兼容的另一种项目：

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFramework>netcoreapp3.1</TargetFramework>
    </PropertyGroup>

</Project>

其他方法

本文的方法已加入到此类型解法的方法列表中，详情请看：

三种方法设置 .NET/C# 项目的编译顺序，而不影响项目之间的引用 - walterlv

理解 Visual Studio 解决方案文件格式（.sln）

Thu, 18 Jun 2020 00:34:02 +0000

一般情况下我们并不需要关心 Visual Studio 解决方案文件格式（.sln），因为 Visual Studio 对解决方案文件的自动修复能力是非常强的。但是如果遇到自动解冲突错误或者编译不通过了，那么此文件还是需要手工修改的。

本文介绍 Visual Studio 解决方案（.sln）文件的格式。

基本概念

Visual Studio 的解决方案文件由这三个部分组成：

版本信息
- Microsoft Visual Studio Solution File, Format Version 12.00
- # Visual Studio Version 16
- VisualStudioVersion = 16.0.28606.126
- MinimumVisualStudioVersion = 10.0.40219.1
项目信息
- Project
- EndProject
全局信息
- Global
- EndGlobal

虽然看起来是三个独立的部分，但其实除了版本号之外，项目信息和全局信息还是有挺多耦合部分的。

比如我们来看一个 sln 文件的例子，是一个最简单的只有一个项目的 sln 文件：

Microsoft Visual Studio Solution File, Format Version 12.00
# Visual Studio Version 16
VisualStudioVersion = 16.0.29102.190
MinimumVisualStudioVersion = 10.0.40219.1
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Walterlv.Demo", "Walterlv.Demo\Walterlv.Demo.csproj", "{DC0B1D44-5DF4-4590-BBFE-072183677A78}"
EndProject
Global
	GlobalSection(SolutionConfigurationPlatforms) = preSolution
		Debug|Any CPU = Debug|Any CPU
		Release|Any CPU = Release|Any CPU
	EndGlobalSection
	GlobalSection(ProjectConfigurationPlatforms) = postSolution
		{DC0B1D44-5DF4-4590-BBFE-072183677A78}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{DC0B1D44-5DF4-4590-BBFE-072183677A78}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{DC0B1D44-5DF4-4590-BBFE-072183677A78}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{DC0B1D44-5DF4-4590-BBFE-072183677A78}.Release|Any CPU.Build.0 = Release|Any CPU
	EndGlobalSection
	GlobalSection(SolutionProperties) = preSolution
		HideSolutionNode = FALSE
	EndGlobalSection
	GlobalSection(ExtensibilityGlobals) = postSolution
		SolutionGuid = {F2F1AD1B-207B-4731-ABEB-92882F89B155}
	EndGlobalSection
EndGlobal

下面我们来一一说明。

结构

版本信息

Microsoft Visual Studio Solution File, Format Version 12.00
# Visual Studio Version 16
VisualStudioVersion = 16.0.29102.190
MinimumVisualStudioVersion = 10.0.40219.1

记录文件的格式版本是 12.0。使用 Visual Studio 2019 编辑/创建。

这里有一个小技巧，这里的 VisualStudioVersion 版本号设置为 15.0 会使得打开 sln 文件的时候默认使用 Visual Studio 2017，而设置为 16.0 会使得打开 sln 文件的时候默认使用 Visual Studio 2019。

项目信息

Project

Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Walterlv.Demo", "Walterlv.Demo\Walterlv.Demo.csproj", "{DC0B1D44-5DF4-4590-BBFE-072183677A78}"
EndProject

项目信息至少由两行组成，第一行标记项目信息开始，而最后一行表示信息结束。

其格式为：

Project("{项目类型}") = "项目名称", "项目路径", "项目 Id"
EndProject

你可以在我的另一篇博客中找到项目类型：

解决方案文件 sln 中的项目类型 GUID

但是本文列举几个 .NET/C# 项目中的常见类型：

9A19103F-16F7-4668-BE54-9A1E7A4F7556 SDK 风格的 C# 项目文件
FAE04EC0-301F-11D3-BF4B-00C04F79EFBC 传统风格的 C# 项目文件
2150E333-8FDC-42A3-9474-1A3956D46DE8 解决方案文件夹

关于 SDK 风格的项目文件，可以阅读我的另一篇博客：

将 WPF、UWP 以及其他各种类型的旧 csproj 迁移成 Sdk 风格的 csproj - walterlv

项目名称和项目路径不必多说，都知道。对于文件夹而言，项目名称就是文件夹的名称，而项目路径也是文件夹的名称。

项目 Id 是在解决方案创建项目的过程中生成的一个新的 GUID，每个项目都不一样。对于 SDK 风格的 C# 项目文件，csproj 中可以指定项目依赖，而如果没有直接的项目依赖，而只是解决方案编译级别的依赖，那么也可以靠 sln 文件中的项目 Id 来指定项目的依赖关系。另外，也通过项目 Id 来对项目做一些编译上的解决方案级别的配置。

ProjectSection

Project 和 EndProject 的内部还可以放 ProjectSection。

比如对于解决方案文件夹，可以包含解决方案文件：

Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{B002382D-4C9E-4F08-85E5-F12E2C061F5A}"
	ProjectSection(SolutionItems) = preProject
		.gitattributes = .gitattributes
		.gitignore = .gitignore
		README.md = README.md
		build\Version.props = build\Version.props
	EndProjectSection
EndProject

这个解决方案文件夹中包含了四个文件，其路径分别记录在了 ProjectSection 节点里面。

ProjectSection 还可以记录项目依赖关系（非项目之间的真实依赖，而是解决方案级别的编译依赖）：

Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Walterlv.Demo", "Walterlv.Demo\Walterlv.Demo.csproj", "{DC0B1D44-5DF4-4590-BBFE-072183677A78}"
	ProjectSection(ProjectDependencies) = postProject
		{98FF9756-B95A-4FDB-9858-5106F486FBF3} = {98FF9756-B95A-4FDB-9858-5106F486FBF3}
	EndProjectSection
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Walterlv.Demo2", "Walterlv.Demo2\Walterlv.Demo2.csproj", "{98FF9756-B95A-4FDB-9858-5106F486FBF3}"
EndProject

在这一段节点里面，我们的 Walterlv.Demo 项目依赖于另外一个 Walterlv.Demo2 项目。依赖是以 项目 Id = 项目 Id 的方式写出来的；如果有多个依赖，那么就写多行。不用吐槽为什么一样还要写两遍，因为这是一个固定的格式，后面我们会介绍一些全局配置里面会有两个不一样的。

关于设置项目依赖关系的方法，除了 sln 文件里面的设置之外，还有通过设置项目依赖属性的方式，详情可以阅读：

三种方法设置 .NET/C# 项目的编译顺序，而不影响项目之间的引用

全局信息

一个全局信息的例子如下：

Global
	GlobalSection(SolutionConfigurationPlatforms) = preSolution
		Debug|Any CPU = Debug|Any CPU
		Release|Any CPU = Release|Any CPU
	EndGlobalSection
	GlobalSection(ProjectConfigurationPlatforms) = postSolution
		{DC0B1D44-5DF4-4590-BBFE-072183677A78}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{DC0B1D44-5DF4-4590-BBFE-072183677A78}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{DC0B1D44-5DF4-4590-BBFE-072183677A78}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{DC0B1D44-5DF4-4590-BBFE-072183677A78}.Release|Any CPU.Build.0 = Release|Any CPU
		{98FF9756-B95A-4FDB-9858-5106F486FBF3}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{98FF9756-B95A-4FDB-9858-5106F486FBF3}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{98FF9756-B95A-4FDB-9858-5106F486FBF3}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{98FF9756-B95A-4FDB-9858-5106F486FBF3}.Release|Any CPU.Build.0 = Release|Any CPU
	EndGlobalSection
	GlobalSection(SolutionProperties) = preSolution
		HideSolutionNode = FALSE
	EndGlobalSection
	GlobalSection(ExtensibilityGlobals) = postSolution
		SolutionGuid = {F2F1AD1B-207B-4731-ABEB-92882F89B155}
	EndGlobalSection
EndGlobal

在这个全局信息的例子中，为解决方案指定了两个配置（Configuration），Debug 和 Release，平台都是 Any CPU。同时也为每个项目指定了单独的配置种类，可供选择，每一行都是 项目的配置 = 解决方案的配置 表示此项目的此种配置在解决方案的某个全局配置之下。

如果我们将这两个项目放到文件夹中，那么我们可以额外看到一个新的全局配置 NestedProjects 字面意思是说 {DC0B1D44-5DF4-4590-BBFE-072183677A78} 和 {98FF9756-B95A-4FDB-9858-5106F486FBF3} 两个项目在 {20B61509-640C-492B-8B33-FB472CCF1391} 项目中嵌套，实际意义代表 Walterlv.Demo 和 Walterlv.Demo2 两个项目在 Folder 文件夹下。

GlobalSection(NestedProjects) = preSolution
    {DC0B1D44-5DF4-4590-BBFE-072183677A78} = {20B61509-640C-492B-8B33-FB472CCF1391}
    {98FF9756-B95A-4FDB-9858-5106F486FBF3} = {20B61509-640C-492B-8B33-FB472CCF1391}
EndGlobalSection

上图解决方案下的整个解决方案全部内容如下：

Microsoft Visual Studio Solution File, Format Version 12.00
# Visual Studio Version 16
VisualStudioVersion = 16.0.29102.190
MinimumVisualStudioVersion = 10.0.40219.1
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Walterlv.Demo", "Walterlv.Demo\Walterlv.Demo.csproj", "{DC0B1D44-5DF4-4590-BBFE-072183677A78}"
	ProjectSection(ProjectDependencies) = postProject
		{98FF9756-B95A-4FDB-9858-5106F486FBF3} = {98FF9756-B95A-4FDB-9858-5106F486FBF3}
	EndProjectSection
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Walterlv.Demo2", "Walterlv.Demo2\Walterlv.Demo2.csproj", "{98FF9756-B95A-4FDB-9858-5106F486FBF3}"
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Folder", "Folder", "{20B61509-640C-492B-8B33-FB472CCF1391}"
EndProject
Global
	GlobalSection(SolutionConfigurationPlatforms) = preSolution
		Debug|Any CPU = Debug|Any CPU
		Release|Any CPU = Release|Any CPU
	EndGlobalSection
	GlobalSection(ProjectConfigurationPlatforms) = postSolution
		{DC0B1D44-5DF4-4590-BBFE-072183677A78}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{DC0B1D44-5DF4-4590-BBFE-072183677A78}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{DC0B1D44-5DF4-4590-BBFE-072183677A78}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{DC0B1D44-5DF4-4590-BBFE-072183677A78}.Release|Any CPU.Build.0 = Release|Any CPU
		{98FF9756-B95A-4FDB-9858-5106F486FBF3}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
		{98FF9756-B95A-4FDB-9858-5106F486FBF3}.Debug|Any CPU.Build.0 = Debug|Any CPU
		{98FF9756-B95A-4FDB-9858-5106F486FBF3}.Release|Any CPU.ActiveCfg = Release|Any CPU
		{98FF9756-B95A-4FDB-9858-5106F486FBF3}.Release|Any CPU.Build.0 = Release|Any CPU
	EndGlobalSection
	GlobalSection(SolutionProperties) = preSolution
		HideSolutionNode = FALSE
	EndGlobalSection
	GlobalSection(NestedProjects) = preSolution
		{DC0B1D44-5DF4-4590-BBFE-072183677A78} = {20B61509-640C-492B-8B33-FB472CCF1391}
		{98FF9756-B95A-4FDB-9858-5106F486FBF3} = {20B61509-640C-492B-8B33-FB472CCF1391}
	EndGlobalSection
	GlobalSection(ExtensibilityGlobals) = postSolution
		SolutionGuid = {F2F1AD1B-207B-4731-ABEB-92882F89B155}
	EndGlobalSection
EndGlobal

从 “x is null 和 x == null” 的区别看 C# 7 模式匹配中常量和 null 的匹配

Tue, 16 Jun 2020 02:39:41 +0000

尝试过写 if (x is null)？它与 if (x == null) 相比，孰优孰劣呢？

x is null 还有 x is constant 是 C# 7.0 中引入的模式匹配（Pattern Matching）中的一个小细节。阅读本文将了解 x is constant 和 x == constant 之间的差别，并给出一些代码编写建议。

🤓 C# 7 的模式匹配

说到 C# 中新增的模式匹配，想必大家一定不会忘了变量的匹配。以下例子来自于微软官方 C# 7.0 的介绍文档 What’s New in C# 7 - C# Guide - Microsoft Docs：

public static int DiceSum2(IEnumerable<object> values)
{
    var sum = 0;
    foreach(var item in values)
    {
        if (item is int val)
            sum += val;
        else if (item is IEnumerable<object> subList)
            sum += DiceSum2(subList);
    }
    return sum;
}

public static int DiceSum3(IEnumerable<object> values)
{
    var sum = 0;
    foreach (var item in values)
    {
        switch (item)
        {
            case int val:
                sum += val;
                break;
            case IEnumerable<object> subList:
                sum += DiceSum3(subList);
                break;
        }
    }
    return sum;
}

其实，官方文档中也顺带提及了常量的匹配：

public static int DiceSum5(IEnumerable<object> values)
{
    var sum = 0;
    foreach (var item in values)
    {
        switch (item)
        {
            case 0:
                break;
            case int val:
                sum += val;
                break;
            case PercentileDie die:
                sum += die.Multiplier * die.Value;
                break;
            case IEnumerable<object> subList when subList.Any():
                sum += DiceSum5(subList);
                break;
            case IEnumerable<object> subList:
                break;
            case null:
                break;
            default:
                throw new InvalidOperationException("unknown item type");
        }
    }
    return sum;
}

然而，微软居然只在 switch-case 里面说了常量的匹配，而且 case 0、case null 这不本来就是我们以前熟悉的写法吗！（只不过以前只能判断一个类型的常量）

🤔 `x is null` Vs. `x == null`

好了，回到正题。我们想说的是 x is null 和 x == null。为了得知它们的区别，我们写一段代码：

private void TestInWalterlvDemo(object value)
{
    if (value is null)
    {
    }
    if (value == null)
    {
    }
}

反编译看看：

.method private hidebysig instance void 
    TestInWalterlvDemo(
      object 'value'
    ) cil managed 
{
    .maxstack 2
    .locals init (
      [0] bool V_0,
      [1] bool V_1
    )

    // [37 9 - 37 10]
    IL_0000: nop          

    // [38 13 - 38 31]
    IL_0001: ldarg.1      // 'value'
    IL_0002: ldnull       
    IL_0003: ceq          
    IL_0005: stloc.0      // V_0

    IL_0006: ldloc.0      // V_0
    IL_0007: brfalse.s    IL_000b

    // [39 13 - 39 14]
    IL_0009: nop          

    // [40 13 - 40 14]
    IL_000a: nop          

    // [41 13 - 41 31]
    IL_000b: ldarg.1      // 'value'
    IL_000c: ldnull       
    IL_000d: ceq          
    IL_000f: stloc.1      // V_1

    IL_0010: ldloc.1      // V_1
    IL_0011: brfalse.s    IL_0015

    // [42 13 - 42 14]
    IL_0013: nop          

    // [43 13 - 43 14]
    IL_0014: nop          

    // [44 9 - 44 10]
    IL_0015: ret          

} // end of method MainPage::Test

x is null 对应的是：

IL_0001: ldarg.1      // 'value'
IL_0002: ldnull       
IL_0003: ceq          
IL_0005: stloc.0      // V_0

先 ldarg.1 将第 1 号参数压到评估栈（为什么不是第 0 号？因为第 0 号是 this）。然后将 ldnull 将 null 压到评估栈上。随后，ceq 比较压入的两个值是否相等。（注意是比较栈中的值哦，不会看引用的对象的！所以如果是引用类型，则比较的是引用本身哦，类似于指针！） 此处划重点，因为考试要考！咳咳……哦不，是后面要用到……

x == null 对应的是：

IL_000b: ldarg.1      // 'value'
IL_000c: ldnull       
IL_000d: ceq          
IL_000f: stloc.1      // V_1

于是发现两个完全一样！！！-_- 本文完，全剧终。

然而，如果那个 x 是一个重写了 == 的自定义类型就不一样了（感谢 TimAndy 提供的示例）：

private void TestInWalterlvDemo(Foo value)
{
    if (value is null)
    {
    }
    if (value == null)
    {
    }
}

public class C
{
    bool M1(C x) => x is null;
	bool M2(C x) => x == null;

    int x;
    public C(int x) => this.x=x;
    public static bool operator== (C o1, C o2) => o1.x == o2.x;
    public static bool operator!= (C o1, C o2)=> o1.x != o2.x;
    public override bool Equals(object o2) => ((C)o2).x == x;
    public override int GetHashCode() => x.GetHashCode();
}

x is null 对应的是：

IL_0000: ldarg.1
IL_0001: ldnull
IL_0002: ceq
IL_0004: ret

x == null 对应的是：

IL_0000: ldarg.1
IL_0001: ldnull
IL_0002: call bool C::op_Equality(class C, class C)
IL_0007: ret

这时，调用了重写的 == 运算符。

TimAndy 提供的示例详情在如下链接：

https://sharplab.io/#v2:EYLgZgpghgLgrgJwgZwLQGUCWBbADgGwgAUEB7AcwSm2QBoYRN8AfAAQCYBGAWACg/WAZgAEHYQGFhAbz7C5w4KVL5hAWU4AKSQA8AlMIC8APmHbhmZMIB2cfPgDcfAJCLla9ltP7jpwweu2DrLywXKYVjCmjrzyoiLiGuGRelIwABYWAHTaBtr2AL6hcaKcAGwKSiqkuBBUMKQIBv6epJy0EsKk7N4mrdl+nezZ0bFCJeWuVTV1DQCEzZKt7YvdPn1m84PDRWOkAG61CJgAJhAVbgCiAI5wUPjIGqTAAFYQAMaRXT3CGlq6X/0mlEdiJ9ocTmcksIAOIQGAACSgyDS4lIpw0320mVhCKRKLREAx0XyQA===。

😏 `x is 常量` Vs. `x == 常量`

现在我们把 null 换成其它常量：

private void TestInWalterlvDemo(object value)
{
    if (value is 1)
    {
    }
    if (value == 1)
    {
    }
}

😲呀……编译不通过！改改……

private void TestInWalterlvDemo(object value)
{
    if (value is 1)
    {
    }
    if (value == (object) 1)
    {
    }
}

于是再看看反编译出来的结果。

value is 1：

IL_0001: ldc.i4.1     
IL_0002: box          [mscorlib]System.Int32
IL_0007: ldarg.1      // 'value'
IL_0008: call         bool [mscorlib]System.Object::Equals(object, object)
IL_000d: stloc.0      // V_0

value == (object) 1：

IL_0013: ldarg.1      // 'value'
IL_0014: ldc.i4.1     
IL_0015: box          [mscorlib]System.Int32
IL_001a: ceq          
IL_001c: stloc.1      // V_1

现在已经不一样了，前者再比较时用的是 call，调用了 bool [mscorlib]System.Object::Equals(object, object) 方法；而后者依然用的是 ceq。

区别已经很明显了，前者会根据具体类型具体判断相等，也就是说引用类型会调用引用类型自己的方法判断相等，值类型也会调用值类型的方法判断相等。而后者依然是比较评估栈中的两个值是否相等。关键是这两者均出现了装箱！也就是说——因为装箱的存在，对后者而言，ceq 会压入 0，即永远返回 false，这就是 BUG 所在。这就是不一样的地方！

🧐如果重写了 `==` 或者 `Equals` 呢？

using System;

namespace Walterlv.EqualsTest
{
    class Program
    {
        static void Main(string[] args)
        {
            var foo = new Foo();
            Console.WriteLine(foo == null);
            Console.WriteLine(foo.Equals(null));
            Console.WriteLine(foo is null);
            Console.WriteLine(Equals(foo, null));
            Console.ReadLine();
        }
    }

    public class Foo
    {
        public override bool Equals(object obj)
        {
            return true;
        }

        public static bool operator ==(Foo left, Foo right)
        {
            return true;
        }

        public static bool operator !=(Foo left, Foo right)
        {
            return !(left == right);
        }
    }
}

这段代码的执行结果是：

True
True
False
False

他们的 IL 代码如下。可以看到 == 和 Equals 会调用重载的运算符和方法；而使用 is 判断和前面是一样的，不受重载影响，可以和 Object 的 Equals 静态方法一样正常完成判空。

// foo == null
IL_0005: dup
IL_0006: ldnull
IL_0007: call         bool Walterlv.EqualsTest.Foo::op_Equality(class Walterlv.EqualsTest.Foo, class Walterlv.EqualsTest.Foo)
IL_000c: call         void [System.Console]System.Console::WriteLine(bool)

// foo.Equals(null)
IL_0011: dup
IL_0012: ldnull
IL_0013: callvirt     instance bool [System.Runtime]System.Object::Equals(object)
IL_0018: call         void [System.Console]System.Console::WriteLine(bool)

// foo is null
IL_001d: dup
IL_001e: ldnull
IL_001f: ceq
IL_0021: call         void [System.Console]System.Console::WriteLine(bool)

// Equals(foo, null)
IL_0026: ldnull
IL_0027: call         bool [System.Runtime]System.Object::Equals(object, object)
IL_002c: call         void [System.Console]System.Console::WriteLine(bool)

你可以阅读 Object.Equals Method (System) - Microsoft Docs 了解到静态 Equals 方法的实现。

回顾模式匹配中的常量匹配

在 C# 7 的模式匹配中，null 和常量其实都一样是常量，本来都是会调用 Object.Equals(object, object) 静态方法进行比较的；但 null 因为其特殊性，被编译器优化掉了，于是 x is null 和 x == null 完全一样；x is constant 和 x == constant 依然有区别。

从反编译的 MSIL 代码中我们也可以得出一些代码编写上的建议。在比较常量的时候，如果可能，尽量使用 is 进行比较，而不是 ==。好处多多：

如果是 null，写 x is null 很符合英语的阅读习惯，代码阅读起来比较舒适。
如果是值常量，可以避免装箱带来的相等判断错误问题

参考资料

如何根据一个绝对文件路径生成一个相对文件路径

Mon, 15 Jun 2020 09:23:04 +0000

日常的开发中，获取绝对文件路径才是主流吧！连 Path.GetFullPath 这种生成绝对路径的方法都已经成为 .NET Standard 的一部分了。

然而，生成相对路径依然有用——比如你的配置文件是相对于工作目录的，必须这个路径是输出给用户看的……

.NET Core 2.0 开始，提供了 Path.GetRelativePath 这样的方法来获取两个路径之间的相对路径，但是 .NET Framework 却没有这样的方法可以用。

那么，在旧版本的 .NET Core 或者 .NET Framework 中 Path 没有生成相对路径的方法，还能怎么生成相对路径呢？别跟我说自己去做字符串比较……

Uri 提供了 MakeRelativeUri 方法，可以生成一个路径到另一个路径的相对路径。于是我们可以写出这样的代码：

public static string MakeRelativePath(string fromPath, string toPath)
{
    var fromUri = new Uri(fromPath);
    var toUri = new Uri(toPath);
    var relativeUri = fromUri.MakeRelativeUri(toUri);
    return Uri.UnescapeDataString(relativeUri.ToString());
}

运行传入 C:\Users\walterlv\OpenSource\Demo 和 C:\Users\walterlv\OpenSource\Demo\build\config.xml。结果，竟然得到的相对路径是：Demo/build/config.xml。

那个 Demo 明明是两者共有的路径部分，却存在于相对路径中；
生成的路径使用 /，而不是 Windows 系统使用的 \。

于是我们需要分别进行这两个处理。对于前者，我们必须让 Uri 意识到这是一个文件夹才能让最终生成的路径不带这个重复的部分；对于后者，我们需要进行路径连接符转换。于是最终的代码我整理成了如下方法：

public static string MakeRelativePath(string fromPath, string toPath)
{
    if (string.IsNullOrEmpty(fromPath)) throw new ArgumentNullException(nameof(fromPath));
    if (string.IsNullOrEmpty(toPath)) throw new ArgumentNullException(nameof(toPath));

    var fromUri = new Uri(fromPath);
    var toUri = new Uri(toPath);

    if (fromUri.Scheme != toUri.Scheme)
    {
        // 不是同一种路径，无法转换成相对路径。
        return toPath;
    }

    if (fromUri.Scheme.Equals("file", StringComparison.InvariantCultureIgnoreCase)
        && !fromPath.EndsWith("/", StringComparison.OrdinalIgnoreCase)
        && !fromPath.EndsWith("\\", StringComparison.OrdinalIgnoreCase))
    {
        // 如果是文件系统，则视来源路径为文件夹。
        fromUri = new Uri(fromPath + Path.DirectorySeparatorChar);
    }

    var relativeUri = fromUri.MakeRelativeUri(toUri);
    var relativePath = Uri.UnescapeDataString(relativeUri.ToString());

    if (toUri.Scheme.Equals("file", StringComparison.InvariantCultureIgnoreCase))
    {
        relativePath = relativePath.Replace(Path.AltDirectorySeparatorChar, Path.DirectorySeparatorChar);
    }

    return relativePath;
}

现在重新传入 C:\Users\walterlv\OpenSource\Demo 和 C:\Users\walterlv\OpenSource\Demo\build\config.xml。结果，已经能够得到：build\config.xml 了。

关于 .NET Core 中的 Path.GetRelativePath 方法，可以参考：GetRelativePath

参考资料

.NET/C# 使用 SetWindowsHookEx 监听鼠标或键盘消息以及此方法的坑

Sat, 13 Jun 2020 09:39:12 +0000

一般来说，大家在需要监听全局消息的时候会考虑 SetWindowsHookEx 这个 API。或者需要处理一些非自己编写的窗口的消息循环的时候，也会考虑使用它。

如果要知道如何使用这个 API，你可以在网上搜到大量这样的文章/博客/教程/文档，然而大多不会提及使用此 API 时遇到的一些坑。阅读本文，你当然也可以知道应该如何使用这个 API，但同时也能了解如何正确使用以避免一些奇怪的问题。

基本使用

如果你在阅读本文的时候遇到了一些问题，可考虑去 GitHub 上克隆我的源码，跑一跑试试。在这里：walterlv/Walterlv.Demo.SetWindowsHookEx。

简单一点，先贴出一部分可以工作起来的代码，你直接可以放到你的项目当中运行测试：

public partial class MainWindow : Window
{
    private readonly HookProc _mouseHook;
    private IntPtr _hMouseHook;

    public MainWindow()
    {
        InitializeComponent();
        _mouseHook = OnMouseHook;
        Loaded += OnLoaded;
    }

    private void OnLoaded(object sender, RoutedEventArgs e)
    {
        var hModule = GetModuleHandle(null);
        // 你可能会在网上搜索到下面注释掉的这种代码，但实际上已经过时了。
        //   下面代码在 .NET Core 3.x 以上可正常工作，在 .NET Framework 4.0 以下可正常工作。
        //   如果不满足此条件，你也可能可以正常工作，详情请阅读本文后续内容。
        // var hModule = Marshal.GetHINSTANCE(Assembly.GetExecutingAssembly().GetModules()[0]);

        _hMouseHook = SetWindowsHookEx(
            HookType.WH_MOUSE_LL,
            _mouseHook,
            hModule,
            0);
        if (_hMouseHook == IntPtr.Zero)
        {
            int errorCode = Marshal.GetLastWin32Error();
            throw new Win32Exception(errorCode);
        }
    }

    private IntPtr OnMouseHook(int nCode, IntPtr wParam, IntPtr lParam)
    {
        // 在这里，你可以处理全局鼠标消息。
        return CallNextHookEx(new IntPtr(0), nCode, wParam, lParam);
    }
}

本文讨论使用 .NET/C# 来完成 SetWindowsHookEx 的调用，所以自然少不了 P/Invoke（平台调用）。因此你必须将以下代码也添加到你的代码仓库中：

[DllImport("kernel32.dll")]
public static extern IntPtr GetModuleHandle(string lpModuleName);

[DllImport("kernel32", SetLastError = true)]
static extern IntPtr LoadLibrary(string lpFileName);

[DllImport("user32.dll")]
static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint lpdwProcessId);

[DllImport("user32.dll", SetLastError = true)]
static extern IntPtr SetWindowsHookEx(HookType hookType, HookProc lpfn, IntPtr hMod, uint dwThreadId);

[DllImport("user32.dll")]
static extern IntPtr CallNextHookEx(IntPtr hhk, int nCode, IntPtr wParam, IntPtr lParam);

private delegate IntPtr HookProc(int nCode, IntPtr wParam, IntPtr lParam);

public enum HookType : int
{
    WH_JOURNALRECORD = 0,
    WH_JOURNALPLAYBACK = 1,
    WH_KEYBOARD = 2,
    WH_GETMESSAGE = 3,
    WH_CALLWNDPROC = 4,
    WH_CBT = 5,
    WH_SYSMSGFILTER = 6,
    WH_MOUSE = 7,
    WH_HARDWARE = 8,
    WH_DEBUG = 9,
    WH_SHELL = 10,
    WH_FOREGROUNDIDLE = 11,
    WH_CALLWNDPROCRET = 12,
    WH_KEYBOARD_LL = 13,
    WH_MOUSE_LL = 14
}

SetWindowsHookEx

SetWindowsHookEx 的签名如下：

HHOOK SetWindowsHookExA(
  int       idHook,
  HOOKPROC  lpfn,
  HINSTANCE hmod,
  DWORD     dwThreadId
);

当方法执行成功时，返回值是钩子处理函数的句柄，用于在钩子的消息处理中调用 CallNextHookEx 方法。当方法执行失败时，这里返回 0。
idHood 参数表示需要处理的消息类型（我们前面定义成了枚举类型 HookType）
lpfn 是自己定义的钩子的消息处理方法（对应我们前面定义的委托）
hmod 是模块的句柄，在本机代码中，对应 dll 的句柄（可在 dll 的入口函数中获取）；而我们是托管代码
dwThreadId 是线程 Id，传入 0 则为全局所有线程，否则传入特定的线程 Id

需要注意的坑

模块句柄传什么？

本文一开始被注释掉的代码中，我使用 Marshal 直接从托管程序集中获取了模块句柄。

这里需要说明，托管程序集不能注入到其他进程，因此也不可以挂接钩子。但有例外，WH_KEYBOARD_LL 或者 WH_MOUSE_LL 这两个是不需要注入 dll 的，因此可以挂接钩子。

对于 WH_KEYBOARD_LL 和 WH_MOUSE_LL，SetWindowsHookEx 方法里面根本没有使用这个模块做什么真正的事情，它只是验证一下一个模块而已。只要存在于你的进程中。

所以，传入其他的模块都是可以的：

var hModule = LoadLibrary("user32.dll");

传入口模块也是可以的：

var hModule = Marshal.GetHINSTANCE(Assembly.GetEntryAssembly().GetModules()[0]);

var hModule = GetModuleHandle(null);

这也是一开始我在 P/Invoke 的方法里面预留了 LoadLibrary 和 GetModuleHandle 方法的原因。

通过调试也能发现这两个的入口模块是相同的：

至于为什么可以用 user32.dll。嗯，反正我们创建窗口监听消息都已经大量调用 user32.dll 的 API 了，这 dll 肯定已经加入到我们的进程中了，所以我们把这个传入到参数中是可以通过验证的。

错误 126：找不到指定的模块。

The specified module could not be found.

如果你只是拿代码做做 demo 可能一切顺利，但放到实际项目里面就挂得一塌糊涂：

这也是我在一开始的 P/Invoke 里面加上了 SetLassError 的重要原因，因为这 API 容易挂。

检查的错误码是 126（0x0000007E）。

然而我的 dll 是存在的呀！

让我们再来看我一开始预留的注释：

// 下面代码在 .NET Core 3.x 以上可正常工作，在 .NET Framework 4.0 以下可正常工作。
// 如果不满足此条件，你也可能可以正常工作，详情请阅读本文后续内容。
var hModule = Marshal.GetHINSTANCE(Assembly.GetExecutingAssembly().GetModules()[0]);

是的，你遇到这样的异常，多半意味着你落入 .NET Framework 4.x 版本的运行时了。

.NET Framework 4.0 相比于之前的 CLR 发生了很大的更改，不再假装 JIT 代码存在一非托管模块中，因此 Marshal.GetHINSTANCE 将不再起作用。

对于低级钩子来说，SetWindowsHookEx 需要一个有效的模块句柄进行检查，但实际上此 API 执行时根本没有使用这个模块。所以更推荐使用前一小节中提供的 LoadLibrary 函数来获取模块句柄，而不是获取当前托管模块的句柄。

解决方法，两/三个：

方法一：使用 LoadLibrary("user32.dll") 获取模块句柄代替 Marshal.GetHINSTANCE
方法二：将获取句柄的模块改为入口程序集（exe），即 Assembly.GetEntryAssembly()。
方法三：升级成纯 .NET Core 程序

错误 1428：没有模块句柄无法设置非本机的挂接。

Cannot set nonlocal hook without a module handle.

对于前面说的 126 错误，你可能从 Assembly.GetExecutingAssembly 改成 Assembly.GetEntryAssembly() 之后会出现此异常。

解决方法：

使用 LoadLibrary("user32.dll") 获取模块句柄代替 Marshal.GetHINSTANCE

错误 1429：此挂接程序只可整体设置。

This hook procedure can only be set globally.

估计找到这里的方式可能是搜索，因为这段中文读起来真的是太晦涩了。不过我把英文贴到上一行了，相信你差不多就知道是怎么回事了。

因为你给 SetWindowsHookEx 方法中传入的 HookType 参数指定了低级类型（Low Level，HookType 枚举后面带了 LL 后缀的），这时只能全局设置钩子。意味着你的第四个参数必须传入 0。

如何只处理特定窗口的消息？

消息循环属于“线程”，而不是属于某个窗口或者进程。在 CreateWindowEx 创建窗口时传入的消息处理函数会仅处理特定窗口的消息，然而当通过钩子的方式来处理消息的话，无法精确定位到某个特定的窗口，只能针对消息循环所在的线程。因此，要处理特定窗口的消息，只能先拿到此窗口所在的线程。

前面的 P/Invoke 中我也预留了获取窗口所在线程的方法。因此，可以直接使用以下调用来获取 hWnd 句柄窗口所在的线程。

var threadId = GetWindowThreadProcessId(hWnd, out _);

本来在 SetWindowsHookEx 最后一个参数传入 0 表示全局钩子的，那么现在传入 threadId 即仅监听此线程的消息。

另外，如果只是打算处理单个窗口的消息，而不是这个线程里的所有消息，那么建议使用子类化的方式来实现。详情可阅读我的另一篇博客：

通过子类化窗口（SubClass）来为现有的某个窗口添加新的窗口处理程序（或者叫钩子，Hook） - walterlv

为什么会导致其他进程闪退？

你可能会发现，明明按照本文所述的方法挂接了钩子，但一运行起来后，其他程序（被挂接的程序）出现了闪退现象。

接下来说明：

在 HookType 的所有种类中，只有 WH_MOUSE_LL 和 WH_KEYBOARD_LL 是不需要注入到目标进程的，其他都必须将 dll 注入到目标进程才可以完成挂接。然而 .NET 程序集无法被注入到其他进程；随便用一个其他 dll 时，里面没有被挂接的函数地址，在注入后就会导致目标进程崩溃。

所以：

如果需要挂接的进程就在本进程内（最后参数指定的线程是本进程内的线程），那么所有种类都可以挂接；
如果需要全局挂接，或者要挂接别的进程，那么 .NET 程序只能使用 WH_MOUSE_LL 和 WH_KEYBOARD_LL 两种挂接类型；

如果就是要挂接其他类型的钩子怎么办？办法总还是有的：

可以考虑做非托管 dll，专门用来挂接；
可以考虑使用 SetWinEventHook，这个是不用注入到目标进程的；
可以考虑使用 System.Windows.Automation 抓取一部分有限的信息。

其他问题

如果你在各种折腾之后还是有问题，可考虑去 GitHub 上克隆我的源码，跑一跑试试。在这里：walterlv/Walterlv.Demo.SetWindowsHookEx。或者通过本文后面附带的联系方式与我联系。

参考资料

WPF / Windows Forms 检测窗口在哪个屏幕

Thu, 11 Jun 2020 10:39:48 +0000

使用 Windows Forms 自带的 System.Windows.Forms.Screen 类可以从一个窗口句柄获取到对应的屏幕。随后可以使用此 Screen 类获取各种屏幕信息。

System.Windows.Forms.Screen

通过句柄获取屏幕类：

System.Windows.Forms.Screen.FromHandle(hWnd)

这里我做了一个 DEMO 程序，画出了窗口的位置和大小，以及当前窗口所在的屏幕的位置和大小。

附代码

MainWindow.xaml

<Window x:Class="Walterlv.Issues.Dpi.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        xmlns:local="clr-namespace:Walterlv.Issues.Dpi"
        mc:Ignorable="d"
        Title="欢迎阅读吕毅的博客 blog.walterlv.com" Height="450" Width="800">
    <Grid x:Name="RootPanel">
        <Canvas SnapsToDevicePixels="True">
            <UIElement.RenderTransform>
                <ScaleTransform ScaleX="0.2" ScaleY="0.2" />
            </UIElement.RenderTransform>
            <Border x:Name="ScreenBorder" Background="#E4E4E6">
                <UIElement.RenderTransform>
                    <TranslateTransform x:Name="ScreenTranslateTransform" />
                </UIElement.RenderTransform>
                <TextBlock x:Name="ScreenTextBlock" FontSize="240" TextAlignment="Right" />
            </Border>
            <Border x:Name="WindowBorder" Background="#949499">
                <UIElement.RenderTransform>
                    <TranslateTransform x:Name="WindowTranslateTransform" />
                </UIElement.RenderTransform>
                <TextBlock x:Name="WindowTextBlock" FontSize="240" Margin="0 0 -1000 -1000" />
            </Border>
        </Canvas>
    </Grid>
</Window>

MainWindow.xaml.cs

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Data;
using System.Windows.Documents;
using System.Windows.Input;
using System.Windows.Interop;
using System.Windows.Media;
using System.Windows.Media.Imaging;
using System.Windows.Navigation;

namespace Walterlv.Issues.Dpi
{
    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();
            LocationChanged += MainWindow_LocationChanged;
            SizeChanged += MainWindow_SizeChanged;
        }

        private void MainWindow_LocationChanged(object sender, EventArgs e)
        {
            UpdateScreenInfo(this);
        }

        private void MainWindow_SizeChanged(object sender, SizeChangedEventArgs e)
        {
            UpdateScreenInfo(this);
        }

        private void UpdateScreenInfo(Window window)
        {
            var hwndSource = (HwndSource)PresentationSource.FromVisual(window);
            if (hwndSource is null)
            {
                return;
            }
            var hWnd = hwndSource.Handle;
            var screen = System.Windows.Forms.Screen.FromHandle(hWnd).Bounds;

            if (User32.GetWindowRect(hWnd, out var rect))
            {
                ScreenTranslateTransform.X = screen.X;
                ScreenTranslateTransform.Y = screen.Y;
                ScreenBorder.Width = screen.Width;
                ScreenBorder.Height = screen.Height;
                ScreenTextBlock.Text = $@"{rect.left},{rect.top}
{screen.Width}×{screen.Height}";
                WindowTranslateTransform.X = rect.left;
                WindowTranslateTransform.Y = rect.top;
                WindowBorder.Width = rect.right - rect.left;
                WindowBorder.Height = rect.bottom - rect.top;
                WindowTextBlock.Text = $@"{rect.left},{rect.top}
{rect.right - rect.left}×{rect.bottom - rect.top}";
            }
        }
    }
}

准确判断一个 WPF 控件 / UI 元素当前是否显示在屏幕内

Thu, 11 Jun 2020 09:40:47 +0000

你的 WPF 窗口是可以拖到屏幕外面去的，所以拉几个元素到屏幕外很正常。你的屏幕可能有多个。你的多个屏幕可能有不同的 DPI。你检测的元素可能带有旋转。

各种各样奇怪的因素可能影响你检查此元素是否在屏幕内，本文包你一次性解决，绝对准确判断。

本文将说三种不同的判定方法，分偷懒版、日常版和苛刻版：

如果你只是写个 demo 啥的，用偷懒版就够了，代码少性能高。
如果你在项目/产品中使用，使用日常版就好。
如果你的用户群体天天喷你 bug 多，那么用苛刻版更好。

偷懒版

如果你只想写个 demo，那么此代码足以。

判断 UI 元素的位置，其右侧是否在屏幕最左侧，其底部是否在屏幕最上面；或者其左侧是否在屏幕最右侧，其顶部是否在屏幕最下面。

private static bool IsOutsideOfScreen(FrameworkElement target)
{
    var topLeft = target.PointToScreen(new Point());
    var bottomRight = target.PointToScreen(new Point(target.ActualWidth, target.ActualHeight));
    return bottomRight.X < SystemParameters.VirtualScreenLeft
        || bottomRight.Y < SystemParameters.VirtualScreenTop
        || topLeft.X > SystemParameters.VirtualScreenLeft + SystemParameters.VirtualScreenWidth
        || topLeft.Y > SystemParameters.VirtualScreenTop + SystemParameters.VirtualScreenHeight;
}

日常版（推荐）

如果你检测的元素自带了旋转，那么以上方法就不能准确判断了。

现在，我们需要检查这个元素的整个边界区域，即便是旋转后。于是，现在，我们要判断元素边界点所在的矩形区域了。

/// <summary>
/// 判断一个可视化对象是否在屏幕外面无法被看见。
/// </summary>
/// <param name="target">要判断的可视化元素。</param>
/// <returns>如果元素在屏幕外面，则返回 true；如果元素在屏幕里或者部分在屏幕里面，则返回 false。</returns>
private static bool IsOutsideOfScreen(FrameworkElement target)
{
    try
    {
        var bounds = GetPixelBoundsToScreen(target);
        var screenBounds = GetScreenPixelBounds();
        var intersect = screenBounds;
        intersect.Intersect(bounds);
        return intersect.IsEmpty;
    }
    catch (InvalidOperationException)
    {
        // 此 Visual 未连接到 PresentationSource。
        return true;
    }

    Rect GetPixelBoundsToScreen(FrameworkElement visual)
    {
        var pixelBoundsToScreen = Rect.Empty;
        pixelBoundsToScreen.Union(visual.PointToScreen(new Point(0, 0)));
        pixelBoundsToScreen.Union(visual.PointToScreen(new Point(visual.ActualWidth, 0)));
        pixelBoundsToScreen.Union(visual.PointToScreen(new Point(0, visual.ActualHeight)));
        pixelBoundsToScreen.Union(visual.PointToScreen(new Point(visual.ActualWidth, visual.ActualHeight)));
        return pixelBoundsToScreen;
    }

    Rect GetScreenPixelBounds()
    {
        return new Rect(SystemParameters.VirtualScreenLeft, SystemParameters.VirtualScreenTop, SystemParameters.VirtualScreenWidth, SystemParameters.VirtualScreenHeight);
    }
}

苛刻版

现在，更复杂的场景来了。

如果用户有多台显示器，而且大小还不一样，那么依前面的判定方法，下图中 C 控件虽然人眼看在屏幕外，但计算所得是在屏幕内。

更复杂的，是多台显示器还不同 DPI 时，等效屏幕尺寸的计算更加复杂。更恐怖的是，WPF 程序声明支持的 DPI 级别不同，计算也会有一些差别。想要写一种支持所有支持级别的代码更加复杂。但本文可以。

/// <summary>
/// 判断一个可视化对象是否在屏幕外面无法被看见。
/// </summary>
/// <param name="target">要判断的可视化元素。</param>
/// <returns>如果元素在屏幕外面，则返回 true；如果元素在屏幕里或者部分在屏幕里面，则返回 false。</returns>
private bool IsOutsideOfScreen(FrameworkElement target)
{
    var hwndSource = (HwndSource)PresentationSource.FromVisual(target);
    if (hwndSource is null)
    {
        return true;
    }
    var hWnd = hwndSource.Handle;
    var targetBounds = GetPixelBoundsToScreen(target);

    var screens = System.Windows.Forms.Screen.AllScreens;
    return !screens.Any(x => x.Bounds.IntersectsWith(targetBounds));

    System.Drawing.Rectangle GetPixelBoundsToScreen(FrameworkElement visual)
    {
        var pixelBoundsToScreen = Rect.Empty;
        pixelBoundsToScreen.Union(visual.PointToScreen(new Point(0, 0)));
        pixelBoundsToScreen.Union(visual.PointToScreen(new Point(visual.ActualWidth, 0)));
        pixelBoundsToScreen.Union(visual.PointToScreen(new Point(0, visual.ActualHeight)));
        pixelBoundsToScreen.Union(visual.PointToScreen(new Point(visual.ActualWidth, visual.ActualHeight)));
        return new System.Drawing.Rectangle(
            (int)pixelBoundsToScreen.X, (int)pixelBoundsToScreen.Y,
            (int)pixelBoundsToScreen.Width, (int)pixelBoundsToScreen.Height);
    }
}

在下面这段代码中，即便是 WPF 项目，我们也需要引用 Windows Forms，用于获取屏幕相关的信息。

如果是 SDK 风格的项目，则在 csproj 中添加如下代码：

    <Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">

    <PropertyGroup>
        <OutputType>WinExe</OutputType>
        <TargetFramework>net5.0</TargetFramework>
        <UseWPF>true</UseWPF>
++      <UseWindowsForms>true</UseWindowsForms>
    </PropertyGroup>

    </Project>

如果是传统风格的项目，则直接添加 System.Windows.Forms 程序集的引用就好。

因为 WPF 的坐标单位是“设备无关单位”（我更倾向于叫有效像素，见有效像素（Effective Pixels）），所以在系统对窗口有缩放行为的时候，多屏不同 DPI 的计算相当复杂，所以这里我们使用纯 Win32 / Windows Forms 方法在来计算屏幕与 UI 元素之间的交叉情况，并且避免在任何时候同时将多个屏幕的坐标进行加减乘除（避免单位不一致的问题）。所以这段代码对任何 WPF 的 DPI 配置都是有效且准确的。

关于 DPI 感知设置的问题，可阅读我的其他博客：

此代码的唯一的缺点是，在 WPF 项目里面要求引用 Windows Forms。

功能比较

不知道用哪个？看下表吧！

代码版本	偷懒版	日常版	苛刻版
基础判断屏幕内外	✔️	✔️	✔️
高分屏（非 96 DPI）	✔️	✔️	✔️
整齐排列的多屏	✔️	✔️	✔️
元素带有旋转	❌	✔️	✔️
多屏尺寸不统一	❌	❌	✔️
多屏有不同 DPI（WPF 感知系统 DPI）	❌	❌	✔️
多屏有不同 DPI（WPF 感知屏幕 DPI）	❌	❌	✔️
多屏有不同 DPI（WPF 感知屏幕 DPI V2）	❌	❌	✔️
纯 WPF 代码（无需引用 Windows Forms）	✔️	✔️	❌
元素形状不规则	❌	❌	❌
性能	好	较好	一般

Compare four different file (folder) links on Windows (NTFS hard links, junction points, symbolic links, and well-known shortcuts)

Thu, 11 Jun 2020 01:28:00 +0000

It is well-known that mklink is a command to create a variety of links on NTFS disk. But if you don’t know much about it or even never hear of it, it doesn’t matter because you know shortcuts at least. This post help you to lean more about mklink and know the differences among the difference command options.

This post is written in multiple languages. Please select yours:

Different ways of linking

Windows Vista announced the NTFS symbolic links, Windows 2000 began to have NTFS Reparse Point, and earlier Windows 95 introduced the shortcut. Backing to Windows 3.5 There are hard links. All of them provide you the power to access a same folder or file in difference paths.

`mklink`

Using mklink command, you can create a “hard link”, “junction points” and “symbolic link”.

> mklink
Creates a symbolic link.

MKLINK [[/D] | [/H] | [/J]] Link Target

        /D      Creates a directory symbolic link.  Default is a file
                symbolic link.
        /H      Creates a hard link instead of a symbolic link.
        /J      Creates a Directory Junction.
        Link    Specifies the new symbolic link name.
        Target  Specifies the path (rel

e.g:

mklink /J current %APPDATA%\walterlv\packages\1.0.0

That is to create a junction point linking to %APPDATA%\walterlv\packages\1.0.0.

Shortcuts

Shortcuts is a Windows feature which is different to those introduced by the NTFS.

Shortcut is a file with a lnk file extension. This file contains the info indicates how to open the linking file or directory. Maybe most applications use this lnk file to execute their programs.

Others

Reparse Point has been in the Windows operating system since NTFS v3.0 (introduced with Windows 2000). In addition to our previously mentioned three types of reparse points made by mklink, there are other types:

Volume Mount Ppoints
Distributed Link Tracking（DLT）
Data Deduplication
Hierarchical Storage Management（HSM）
Native Structured Storage（NSS）
Unix Doman Socket（socket）
System Compression
OneDrive

Comparison

Reading those words above, you may know the usage of mklink but don’t know the difference between them. Then I’ve post them below:

	Hard Link	Junction Point	Symbolic Link
Command	`mklink /H Link Target`	`mklink /J Link Target`	`mklink /D Link Target`
Description	Create an alias for a file so that different paths correspond to the data of the same file.
Linking to files	✔️	❌	❌
Linking to directories	❌	✔️	✔️
Needs to run as Administrator	Yes	No	Mostly Yes `[Tip1]`
Supports linking across volumes	❌	✔️(Local Machine only)	✔️(including remote path such as SMB)
Introduced since	Supports since Windows NT 3.1 API supports since Windows 2000 by `CreateHardLink()` Supports since Windows NT 6.0 by command `mklink /H`	Windows 2000+	Windows Vista+
Supports targets which is not exist	❌	✔️	✔️
Link to relative directory	❌	❌(You can create one with relative path but it will change to absolute path automatically.)	✔️
How to remove	del	rd	rd / del
When the reparse point is removed	Only after all hard links to the original file and the original file have been deleted will the file data be deleted.	The original folder is not affected after Windows Vista but is will be deleted in Windows 2000 / XP / 2003.	The original file/folder is not affected.
When the original file/folder is removed	The hard link can still access the data of the file normally.	Directory connection failed, pointing to a directory that does not exist.	The symbolic link is invalid and points to a directory that does not exist.

[Tip1]: A post of Microsoft says, Starting with Windows 10 Insiders build 14972, symlinks can be created without needing to elevate the console as administrator. This will allow developers, tools and projects, that previously struggled to work effectively on Windows due to symlink issues, to behave just as efficiently and reliably as they do on Linux or OSX. (Below picture shows how to open the developer’s mode.)

Extras

If you create shortcuts in your start menu, and the shortcuts are linking to files that are in junction points. All the shortcuts will disappear after a Windows 10 updates. I’m reporting this bug to Microsoft, but before Microsoft resolve this bug we have to work around to avoid this bug. See the bug in scoop below:

After the windows 10 updates, all shortcuts of scoop will disappear. · Issue #3941 · lukesampson/scoop

References

比较 Windows 上四种不同的文件（夹）链接方式（NTFS 的硬链接、目录联接、符号链接，和大家熟知的快捷方式）

Thu, 11 Jun 2020 01:27:34 +0000

可能有很多小伙伴已经知道通过 mklink 命令来创建 NTFS 磁盘上的各种链接；当然，就算不知道 mklink 的链接，快捷方式应该每个人都知道吧。mklink 的选项有很多种，但你可能在其他文章中难以找到对这些不同选项的不同效果和使用限制的准确和统一描述。本文将介绍 Windows 系统中所有的链接方式，它们的优缺点、使用条件和坑。

This post is written in multiple languages. Please select yours:

不同的链接方式

Windows Vista 开始带来了 NTFS 符号链接（Symbolic Link），Windows 2000 开始就有了 NTFS 重解析点（Reparse Point），更早的 Windows 95 就有了快捷方式（Shortcut），再往前到 Windows 3.5 还有硬链接（Hard Link），他们都能实现给你不同的路径访问同一个文件或文件夹的功能。

`mklink`

使用 mklink 命令，你可以创建“硬链接（Hard Link）”、“目录联接（Junction Point）”和“符号链接（Symbolic Link）”。

> mklink
创建符号链接。

MKLINK [[/D] | [/H] | [/J]] Link Target

        /D      创建目录符号链接。默认为文件
                符号链接。
        /H      创建硬链接而非符号链接。
        /J      创建目录联接。
        Link    指定新的符号链接名称。
        Target  指定新链接引用的路径
                (相对或绝对)。

例如：

mklink /J current %APPDATA%\walterlv\packages\1.0.0

即在当前目录创建了一个指向 %APPDATA%\walterlv\packages\1.0.0 的目录联接。

因为创建目录联接不需要管理员权限，所以特别适合给桌面应用程序用来按版本管理某些包/工具集。有关使用 .NET/C# 来创建目录联接的方法，可以阅读我的另一篇博客：

.NET 实现 NTFS 文件系统的硬链接 mklink /J（Junction） - walterlv

快捷方式

快捷方式是一个单纯 Windows 操作系统用户层面的功能，与 NTFS 文件系统没有什么关系。不过其也能实现链接到另一个文件的功能。使用快捷方式的程序太多了，几乎每个安装包都会考虑往桌面或开始菜单扔几个快捷方式。

快捷方式的本质是一个 lnk 后缀的文件，这个文件里面指向了如何打开目标文件或文件夹的一些参数，于是当在文件资源管理器中打开快捷方式时，就直接打开了目标文件或文件夹（当然，启动一个程序可能是大多数用法）。

其他

重解析点（Reparse Point）自 NTFS v3.0（随 Windows 2000 推出）开始便一直存在于 Windows 操作系统中。除了我们前面提到的可通过 mklink 创建的那三种外，还有其他种类：

Volume Mount Ppoints
Distributed Link Tracking（DLT）
Data Deduplication
Hierarchical Storage Management（HSM）
Native Structured Storage（NSS）
Unix Doman Socket（socket）
System Compression
OneDrive

比较

可能单单说名字，你不一定能明白什么时候要用哪一种。于是我将这些链接的不同整理了出来贴在下面。

	硬链接（Hard Link）	目录联接（Junction Point）	符号链接（Symbolic Link）
命令	`mklink /H Link Target`	`mklink /J Link Target`	`mklink /D Link Target`
作用	为某文件创建别名，可让不同的路径对应同一个文件的数据。
链接到文件	✔️	❌	❌
链接到文件夹	❌	✔️	✔️
需要提升为管理员权限	需要	不需要	通常需要 `[坑1]`
跨驱动器卷（盘符）	❌	✔️（仅本地计算机）	✔️（包括 SMB 文件或路径）
操作系统支持	Windows NT 3.1 开始支持 Windows 2000 开始有 API `CreateHardLink()` Windows NT 6.0 开始能使用 `mklink /H`	Windows 2000+	Windows Vista+
可链接到不存在的目标	❌	✔️	✔️
可链接到相对目录	❌	❌（可以使用相对路径创建，但创建完即变绝对路径）	✔️
删除方法	del	rd	rd / del
当链接被单独删除后	只有所有指向原始文件的硬链接和原始文件全部删除后文件数据才会被删除。	Windows Vista 之后原始文件夹不受影响；Windows 2000/XP/2003 会导致原始子文件夹被删除。	原始文件夹不受影响。
当原始文件被单独删除后	硬链接依然能正常访问到文件的数据。	目录联接失效，指向不存在的目录。	符号链接失效，指向不存在的目录。

[坑1]: 在微软的官方博客中已有说明：从 Windows 10 Insiders build 14972 开始，符号链接对开发者将不再需要管理员权限，这可以让开发者像在 Linux 或 macOS 上一样高效地工作。（通过如下图所示的开关来决定此操作是否需要管理员权限，打开则无需管理员权限。）

额外的坑

如果你在开始菜单里面有快捷方式指向了一个目录联接（Junction Point）中的文件，那么在 Windows 10 操作系统更新后这个快捷方式便会消失。目前正在调查消失的原因，如果确认是目录联接的 bug 或者开始菜单的 bug，就将进展报告给微软。

关于这个 bug，详见：

After the windows 10 updates, all shortcuts of scoop will disappear. · Issue #3941 · lukesampson/scoop

一般来说，阅读本文应该就理解了 mklink 的正确用法，也不应该会出现我另一篇博客中的情况：

解决 mklink 使用中的各种坑（硬链接，软链接/符号链接，目录链接） - walterlv

另外，附我使用目录联接/符号链接的一些用途：

通过 mklink 收集本地文件系统的所有 NuGet 包输出目录来快速调试公共组件代码 - walterlv

参考资料

支持 Windows 10 最新 PerMonitorV2 特性的 WPF 多屏高 DPI 应用开发

Wed, 10 Jun 2020 08:41:39 +0000

Windows 10 自 1703 开始引入第二代的多屏 DPI 机制（PerMonitor V2），而 WPF 框架可以支持此第二代的多屏 DPI 机制。

本文将介绍 WPF 框架利用第二代多屏 DPI 机制进行高 DPI 适配的方法。同时，也介绍低版本的 WPF 或者低版本的操作系统下如何做兼容。

添加应用程序清单文件

在你现有 WPF 项目的主项目中需要添加两个文件以支持第二代的多屏 DPI 机制。

app.manifest (决定性文件)
app.config (修复 Bug, .NET Framework 4.6.2 及以上可忽略)

▲ 项目中新增的两个文件

默认情况下，app.config 在你创建 WPF 项目的时候就会存在，而 app.manifest 则不是。如果你的项目中已经存在这两个文件，就不需要添加了。

如果你没有 app.config，如何添加？

打开项目属性，然后在属性中选择 .NET Framework 的版本，无论你选择哪个，app.config 都会自动为你添加。

当然，正统的方法是跟下面的 app.manifest 的添加方法相同，你会在下面看到 Visual Studio 新建项中 app.manifest 和 app.config 文件是挨在一起的。

如果你没有 app.manifest，如何添加？

▲ 新建文件的时候选择应用程序清单文件（应用程序配置文件就在旁边）

了解 WPF 清单文件中的 DPI 感知设置

DpiAware

在你打开了 app.manifest 文件后，找到以下代码，然后取消注释：

<!-- Indicates that the application is DPI-aware and will not be automatically scaled by Windows at higher
    DPIs. Windows Presentation Foundation (WPF) applications are automatically DPI-aware and do not need 
    to opt in. Windows Forms applications targeting .NET Framework 4.6 that opt into this setting, should 
    also set the 'EnableWindowsFormsHighDpiAutoResizing' setting to 'true' in their app.config. -->
<!--
<application xmlns="urn:schemas-microsoft-com:asm.v3">
<windowsSettings>
    <dpiAware xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">true</dpiAware>
</windowsSettings>
</application>
-->

上面这一段代码是普通的 DPI 感知的清单设置，开启后获得系统 DPI 感知级别（System DPI Awareness）。

如果要开启 Per-Monitor DPI 感知，将上面的 true 改成 true/pm（pm 表示 per-monitor）。

不过这只是兼容性的设计而已，感谢老版本的系统使用字符串包含的方式，于是可以老版本的系统可以兼容新的 DPI 感知值：

什么都不填
- 如果你额外也没做什么 DPI 相关的操作，那么就是 Unaware。
- 如果你在程序启动的时候调用了 SetProcessDpiAwareness 或 SetProcessDPIAware 函数，那么就会按照调用此函数的效果来感知 DPI。
包含 true 字符串
- 当前进程设置为系统级 DPI 感知（System DPI Awareness）。
包含 false 字符串
- 在 Windows Vista / 7 / 8 中，与什么都不填的效果是一样的。
- 在 Windows 8.1 / 10 中，当前进程设置为不感知 DPI（Unaware），就算你调用了 SetProcessDpiAwareness 和 SetProcessDPIAware 也是没有用的。
包含 true/pm 字符串
- 在 Windows Vista / 7 / 8 中，当前进程设置为系统级 DPI 感知（System DPI Awareness）。
- 在 Windows 8.1 / 10 中，当前进程设置为屏幕级 DPI 感知（Per-Monitor DPI Awareness）。
包含 per monitor 字符串
- 在 Windows Vista / 7 / 8 中，与什么都不填的效果是一样的。
- 在 Windows 8.1 / 10 中，当前进程设置为屏幕级 DPI 感知（Per-Monitor DPI Awareness）。
其他任何字符串
- 在 Windows Vista / 7 / 8 中，与什么都不填的效果是一样的。
- 在 Windows 8.1 / 10 中，当前进程设置为不感知 DPI（Unaware），就算你调用了 SetProcessDpiAwareness 和 SetProcessDPIAware 也是没有用的。

说明一下，SetProcessDpiAwareness 是新 API，要求的最低系统版本是 Windows 8.1，调用这个才能指定为 Per-Monitor 的 DPI 感知。而 SetProcessDPIAware 是 Vista 开始引入的老 API，没有参数可以传。

DpiAwareness

<asmv3:application>
  <asmv3:windowsSettings xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">
    <dpiAwareness>PerMonitorV2, unaware</dpiAwareness>
  </asmv3:windowsSettings>
</asmv3:application>

注意：只有 Windows 10 (1607) 及以上版本才会识别此节点的 DPI 设置。如果你设置了 dpiAwareness 节点，那么 dpiAware 就会被忽略。

建议你可以两个节点都指定，这样既可以使用到 Windows 10 1607 的新特性，又可以兼容老版本的 Windows 操作系统。

dpiAwareness 节点支持设置一个或多个 DPI 感知级别，用逗号分隔。如果你指定了多个，那么操作系统会从第一个开始识别，如果能识别就使用，否则会找第二个。用这种方式，未来的应用可以指定当前系统不支持的 DPI 感知级别。

鉴于此，在目前 Windows 7 还大行其道的今天，为了兼容，dpiAwareness 和 dpiAware 都设置是比较靠谱的。

dpiAwareness 节点目前支持的值有：

什么都不设置
- 按 dpiAware 节点的结果来
整个逗号分隔的序列都没有能识别的 DPI 感知级别
- 如果你额外也没做什么 DPI 相关的操作，那么就是 Unaware。
- 如果你在程序启动的时候调用了 SetProcessDpiAwareness 或 SetProcessDPIAware 函数，那么就会按照调用此函数的效果来感知 DPI。
第一个能识别的感知级别是 system
- 当前进程设置为系统级 DPI 感知（System DPI Awareness）。
第一个能识别的感知级别是 permonitor
- 当前进程设置为屏幕级 DPI 感知（Per-Monitor DPI Awareness）。
第一个能识别的感知级别是 permonitorv2
- 当前进程设置为第二代屏幕级 DPI 感知（Per-Monitor V2 DPI Awareness）。
- 仅在 Windows 10 (1703) 及以上版本才可被识别
第一个能识别的感知级别是 unaware
- 当前进程设置为不感知 DPI（Unaware），就算你调用了 SetProcessDpiAwareness 和 SetProcessDPIAware 也是没有用的。

使 WPF 程序支持 Per-Monitor V2 级 DPI 感知

前面我们分析 App.Manifest 文件中 DPI 的设置后，几乎得到一个信息，dpiAware 和 dpiAwareness 都是要设置的，除非以后绝大多数用户的系统版本都到达 Windows 10 (1607) 及以上。

以下是推荐的 DPI 感知级别设置：

<application xmlns="urn:schemas-microsoft-com:asm.v3">
  <windowsSettings>
    <!-- The combination of below two tags have the following effect : 
         1. Per-Monitor for >= Windows 10 Anniversary Update
         2. System < Windows 10 Anniversary Update -->
    <dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">PerMonitorV2</dpiAwareness>
    <dpiAware xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">true</dpiAware>
  </windowsSettings>
</application>

需要注意：系统版本在 Windows 10 (1703) 或以上，V2 的感知级别才会生效，否则就直接使用系统级 DPI 感知。

这里我们其实偷懒了，这种写法方便我们仅处理两种不同的 DPI 缩放规则：

Windows 10 (1703) 之后的系统，全按最全支持来做兼容；
其他系统，全按 Windows 7 的支持级别来做兼容。

你可能注意到本文文末的参考文章中有微软的官方博客，里面推荐的是支持所有级别的 DPI 感知。这看你的需求，因为部分 DPI 相关的模块如果你打算都支持，可能需要更加复杂的判定和计算。本文推荐的少一些，省一点开发量（反正 Windows 8.1 和 Windows 10 早期版本的用户量太少，这部分用户体验不比 Windows 7 差，又不是不能用）。

第一代和第二代的 Per-Monitor 感知之间的差异，可以参考：Windows 下的高 DPI 应用开发（UWP / WPF / Windows Forms / Win32） - walterlv

额外的，如果你的 .NET Framework 版本在 .NET Framework 4.6.2 以下，但操作系统在 Windows 10 及以上，你还需要修改 App.config 文件（在 <configuration /> 节点）。

<runtime>
  <AppContextSwitchOverrides value = "Switch.System.Windows.DoNotScaleForDpiChanges=false"/>
</runtime>

注意：

这个值要设为 false。（微软官方吐槽：Yes, set it to false. Double negative FTW!）
AppContextSwitchOverrides 不能被设置两次，如果一已经设置了其他值，需要用分号分隔多个值。

特别说明，当面向 .NET Framework 4.6.2 以下版本编译，但运行于 Windows 10 (1607) 和以上版本时，只需要添加 Switch.System.Windows.DoNotScaleForDpiChanges=false 即可让 WPF 程序处理 Dpi Change 消息，此时 WPF 程序就像高版本的 .NET Framework 中一样能够正常处理多屏下的 DPI 缩放。

以上，划重点 你并不需要编译为高版本的 .NET Framework 即可获得 Per-Monitor 的 DPI 缩放支持。

WPF 程序在特殊清单设置下的效果

dpiAwareness 不设置，dpiAware 节点设置为 true/pm：

▲ 100% DPI

▲ 150% DPI

注意到标题栏（非客户区）没有缩放，而 WPF 区域（客户区）清晰地缩放了。

dpiAwareness 不设置，dpiAware 节点设置为 true：

▲ 100% DPI

▲ 150% DPI

注意到标题栏（非客户区）被缩放了，而 WPF 区域（客户区）被 DPI 虚拟化进行了位图拉伸（模糊）。

dpiAwareness 不设置，dpiAware 节点设置为 true/pm12345：

此时，WPF 程序无法启动！！！而你只需要减少一位数字，例如写成 true/pm1234 即可成功启动，效果跟 true 是一样的，注意效果不是 true/pm。也就是说，/pm 并没有显示出它的含义来。额外的，如果设为 false 但后面跟随那么长的字符串，WPF 程序是可以启动的。

dpiAwareness 设置为 PerMonitorV2：

▲ 150% DPI

注意到标题栏（非客户区）被缩放了，而 WPF 区域（客户区）也能清晰地缩放（仅 Windows 10 1703 及以上系统才是这个效果）。

低版本 .NET Framework 和低版本 Windows 下的 WPF DPI 缩放

由于 Windows 8.1 操作系统用户存量不多，主要是 Windows 7 和 Windows 10。所以我们要么兼容完全不支持 Per-Monitor 的 Windows 7，要么使用具有新特性的 Windows 10 即可获得最佳的开发成本平衡。使用以上的 DPI 缩放方法足以让你的 WPF 应用在任何一个 .NET Framework 版本下获得针对屏幕的 DPI 清晰缩放（Per-Monitor DPI Awareness）。

所以仅针对 Windows 8.1 做特殊的 DPI 缩放是不值得的，把 Windows 8.1 当做 Windows 7 来做那种不支持 Per-Monitor 的处理就好了。当然你硬要支持也有相关文档可以看：Developing a Per-Monitor DPI-Aware WPF Application - Microsoft Docs 了解实现方法。具体是使用 DisableDpiAwareness 特性和 Windows Per-Monitor Aware WPF Sample 中的源码。

参考资料

VMware Workstation 与 Device/Credential Guard 不兼容。在禁用 Device/Credential Guard 后，可以运行 VMware Workstation

Wed, 10 Jun 2020 00:58:01 +0000

VMware Workstation 与 Device/Credential Guard 不兼容。在禁用 Device/Credential Guard 后，可以运行 VMware Workstation。有关更多详细信息，请访问 http://www.vmware.com/go/turnoff_CG_DG。

我在系统升级到 Windows 10 2004 后，启动 VMware 的任一台虚拟机时会弹出错误提示框：

嗯，图标题中的“lindexi”就是小伙伴林德熙；他在我的电脑上运行了一台虚拟机远程使用。然而怎么能随随便便就让虚拟机挂掉呢？得在他醒来之前偷偷修好。

提示框中的 Device/Credential Guard 就是 Windows 10 系统的“内核隔离”。

按照以下步骤逐一执行，直到修复。

特别前提

VMware 从 15.5.5 版本开始，已支持在启用了 Hyper-V 的 Windows 10 主机上运行：

使用 WSL 和 Device/Credential Guard 等功能时，用户仍可运行 VMware Workstation 虚拟机
需要 Windows 10 20H1 版本及以上系统

因此，如果你觉得不想折腾，直接将 VMware 升级到 15.5.5 以上即可。

图来自于 kkwpsv（李少珺）。

第一步：关闭内核隔离，然后重启

要找到“内核隔离”开关，直接在开始菜单搜索“内核隔离”或者“Credential Guard”即可。如果搜不到，去任务栏右下角找到“Windows 安全中心”双击打开。

第二步：禁用设备防护

打开“组策略”，进入本地计算机策略 -> 计算机配置 -> 管理模板 -> 系统 -> Device Guard -> 基于虚拟化的安全性。

选择已禁用。

第三步：关闭 Hyper-V

在“启用或关闭 Windows 功能”里，关闭掉 Hyper-V 虚拟机（也需要重启）。

第四步：运行命令

以管理员身份运行以下命令：

bcdedit /set hypervisorlaunchtype off

然后重启计算机。

参考资料

Windows沙盒和vmware workstation似乎只能存在一个-远景论坛-微软极客社区

Visual Studio 智能感知提示里的奇妙行为一览

Tue, 09 Jun 2020 07:52:22 +0000

本文就是个吐槽，感兴趣一一去报给微软。

自动完成与建议完成

作为本文的背景，你可能需要了解 Visual Studio 有一个设置：“在建议完成模式和标准完成模式之间切换”。就是下面这个按钮，你可以在工具条上找到。

你一定很差异，看着这翻译，你知道“选中”对应“建议完成模式”还是“标准完成模式”呢？你知道什么是建议完成模式，什么是标准完成模式吗？

不要紧，这不是翻译的问题，因为英文原文也一样令人摸不着头脑。

那么这件事就交给本文来处理吧！

如上图所示，如果不选中那个图标，那么智能感知会更智能，默认回车即上屏，而不用再打字母了。所以我更倾向于不要选中那个图标。至于那个图标到底哪个是建议完成模式哪个是标准完成模式，已经不重要了（反正就算知道了，名字也不直观）。

奇妙行为

接下来我们的讨论中，前面所述的图标都不选中，这样能最大程度体现智能感知的智能程度。

带星 V.S. 不带星

大家知道 Visual Studio 2019 开始，微软开始基于机器学习来训练智能感知的建议。凡通过机器学习建议的项都会用“★”（星号）标注。

然而，一旦没有任何项带星，那么就没有项被选中。

奇妙行为：有机器学习带星的项才会自动选中，没有带星的项就不会自动选中。

全小写 V.S. 部分大写

注意看下面的图片中的提示：

使用 preso 能自动选中 PresentationSource 而使用 Preso 则不会自动选中 PresentationSource。

奇妙行为：如果完全用小写字母打字，则可以按词匹配前几位字母；如果出现了大写字母，那么出现的小写字母就默认不算做新单词。

直接输入 V.S. 删除后输入

看看下面的动图：

注意到了什么？如果是输入单词，那么会默认选中；但删除了字母后再输入单词，就不会默认选中了。

奇妙行为：直接输入和删除后再输入，默认选中的行为不同；删除后再输入不会默认选中。

输入单词 V.S. 输入点

从前面的示例可以看到，如果能满足 Visual Studio 的输入要求输入单词（鬼知道是什么要求），那么基本能直接选中。但按要求输入点“.”却不一定能直接选中。

所以，如果你能熟练摸透 VS 单词的补全逻辑，那么可能仅在输入点“.”的时候才会遇到有时选中有时不选中的问题。

奇妙行为：？

不同种类的空格

当即将输入的代码是枚举这种很封闭的语句时，直接自动选中（虽然自动提示的经常不是想要的）：

然而当输入的代码是命名这种比较开放的语句时，不会自动选中（虽然自动提示的名字很想要）：

奇妙行为：同样是空格，有时会自动选中，有时不会自动选中。

吐槽

可以发现，虽然 Visual Studio 提供了一个是否自动选中智能感知提示选项的开关，但这个开关的行为并不总能反映出实际的使用效果。

如果选中了按钮（见本文开头所述），则一定不会自动选中智能感知提示
如果没选中按钮，则是否自动选中智能感知提示简直随缘

你要说，Visual Studio 猜得准的时候会自动选中，猜不准的时候不会自动选中。但实际使用效果却是，你自认为猜得准的时候，我却不需要你的提示；你自认为猜不准的时候，给出的建议却非常完美。不如直接按照开关来，简单利索，还不用在开发的时候琢磨到底该不该按上下来一轮选择。

Chrome 窗口全黑了，不怕，有招

Mon, 08 Jun 2020 00:22:55 +0000

Chrome 的窗口偶尔会出现全黑掉的情况。从轻微的到严重的，本文都有解决方案。

偶然全黑

Chrome 全黑的状态看起来像下图这样：

通常发生在这些时间点后：

锁屏解锁后
突然间显卡驱动崩溃了一下
显卡驱动刚刚升完级
远程桌面连接后

这时，通常还伴随着基于 Chromium 内核的应用全部黑屏，比如：

Visual Studio Code (VSCode)
Microsoft Edge

解决方法是：

开一个新窗口

开的方法有（任选其一，适用与所有 Chromium 内核应用）：

在任务栏上右键，重新点开程序（看下图）
直接鼠标中键点击任务栏上的图标
去开始菜单或者其他入口处点开程序

一直黑

有时，前面的方法并不能帮你解决问题——新开程序也依然是黑屏的。

通常发生在这些时间点后：

Windows 10 系统更新完后

这时，你可能发现其他基于 Chromium 内核的应用是正常的。也就说明此时的问题仅仅是 Chrome 浏览器的问题。

解决方法是：

删除 %LOCALAPPDATA%\Google\Chrome\User Data\ShaderCache\GPUCache 下的全部文件
重新启动 Chrome 浏览器

例如，我的文件夹是 C:\Users\lvyi\AppData\Local\Google\Chrome\User Data\ShaderCache\GPUCache，全部删除后重新启动即恢复。

拿别人的 Program Files 文件夹？别忘了考虑 x86/x64 路径

Wed, 03 Jun 2020 00:13:44 +0000

要拿适用于自己进程的 Program Files 文件夹很简单，无脑拿就好了。不过，如果涉及到拿其他程序的，那么就会涉及到与其他程序不同架构时路径不同的问题。

Environment.GetFolderPath(Environment.SpecialFolder.ProgramFiles) 即可用来获取 Program Files 文件夹的路径。从 .NET Framework 4.0 开始，还增加了一个 ProgramFilesX86 枚举可用。

在官方文档中，ProgramFiles 枚举拿的是当前进程架构下的 Program Files 文件夹，ProgramFilesX86 拿的是 x86 进程架构下的 Program Files 文件夹。

为了具体说明，可以用下面的示例程序：

using System;

namespace Walterlv.Demo
{
    class Program
    {
        static void Main(string[] args)
        {
            var is64Bit = Environment.Is64BitProcess;
            var pfx86 = Environment.GetFolderPath(Environment.SpecialFolder.ProgramFilesX86);
            var pf = Environment.GetFolderPath(Environment.SpecialFolder.ProgramFiles);

            Console.WriteLine($"process = {(is64Bit ? "x64" : "x86")}");
            Console.WriteLine($"x86     = {pfx86}");
            Console.WriteLine($"current = {pf}");
        }
    }
}

在 x64 系统下，输出是：

process = x64
x86     = C:\Program Files (x86)
current = C:\Program Files

在 x86 系统下，输出是：

process = x86
x86     = C:\Program Files (x86)
current = C:\Program Files (x86)

所以，只是通过此属性的话，x86 进程不能获取到 x64 进程的目录。

参考资料

在 .NET 对象和 JSON 互相序列化的时候，枚举类型如何设置成字符串序列化，而不是整型？

Tue, 02 Jun 2020 23:57:07 +0000

默认情况下，Newtonsoft.Json 库序列化和反序列化 JSON 到 .NET 类型的时候，对于枚举值，使用的是整数。然而，在公开 JSON 格式的 API 时，整数会让 API 不易于理解，也不利于扩展和兼容。

那么，如何能使用字符串来序列化和反序列化 JSON 对象中的枚举呢？

—— 使用转换器（JsonConverter）。

Newtonsoft.Json 中自带了一些转换器，在 Newtonsoft.Json.Converters 命名空间下。其中枚举的转换是 StringEnumConverter，我们只需要将其标记在属性上即可。

如下面的代码所示：

using Newtonsoft.Json;
using Newtonsoft.Json.Converters;

namespace Walterlv.Models
{
    public class Foo
    {
        [JsonConverter(typeof(StringEnumConverter), true)]
        public DoubiLevel Level { get; set; }
    }

    public enum DoubiLevel
    {
        None,
        ABit,
        Normal,
        Very,
        Extreme,
    }
}

对于“逗比程度”枚举，增加了转换器后，这个对象的序列化和反序列化将成：

{
    "Level": "very"
}

那个 StringEnumConverter 后面的参数 true 表示使用 camelCase 来格式化命名，即首字母小写。

当然，如果你希望属性名也小写的化，需要加上额外的序列化属性：

++  using System.Runtime.Serialization;
    using Newtonsoft.Json;
    using Newtonsoft.Json.Converters;
    ……

++      [DataContract]
        public class Foo
        {
++          [DataMember(Name = "level")]
            [JsonConverter(typeof(StringEnumConverter), true)]
            public DoubiLevel Level { get; set; }
        }
    ……

将序列化和反序列化成：

{
    "level": "very"
}

如何在保留原本所有样式/绑定和用户设置值的情况下，设置和还原 WPF 依赖项属性的值

Tue, 02 Jun 2020 23:13:24 +0000

WPF 备份某控件的一些属性，做一些神奇的操作，然后再还原这些属性。多么司空见惯的操作呀！然而怎么备份却是值得研究的问题。直接赋值？那一定是因为你没踩到一些坑。

场景和问题

现在，我们假想一个场景（为了编代码方便）：

有一个窗口，设置了一些样式属性
现在需要将这个窗口设置为全屏，这要求修改一些原来的属性（WPF 自带那设置有 bug，我会另写一篇博客说明）
取消设置窗口全屏后，之前修改的那些属性要“完美”还原

一般可能会这么写：

private Window _window;
private WindowStyle _oldStyle;

private void OnEnterFullScreen()
{
    _oldStyle = _window.WindowStyle;
    _window.WindowStyle = WindowStyle.None;
}

private void OnExitFullScreen()
{
    _window.WindowStyle = _oldStyle;
}

然而：

如果某人在 WindowStyle 上设了个动态的样式怎么办？——那当然是不再动态了呀（因为覆盖了样式值）
如果某人在 WindowStyle 上设置了绑定怎么办？——那当然也是不再生效了呀（因为绑定被你覆盖了）

解决方法和原理

因为各大 WPF 入门书籍都说到了 WPF 依赖项属性的优先级机制，所以大家应该基本都知道这个。不了解的，可以立刻去这里看看：[依赖项属性值优先级 - WPF

Microsoft Docs](https://docs.microsoft.com/zh-cn/dotnet/framework/wpf/advanced/dependency-property-value-precedence#dependency-property-setting-precedence-list)。

是这样的优先级：强制 > 动画 > 本地值 > 模板 > 隐式样式 > 样式触发器 > 模板触发器 > 样式 > 默认样式 > 属性继承 > 元数据默认值。

而我们通过在 XAML 或 C# 代码中直接赋值，设置的是“本地值”。因此，如果设置了本地值，那么更低优先级的样式当然就全部失效了。

那么绑定呢？绑定在依赖项属性优先级中并不存在。绑定实际上是通过“本地值”来实现的，将一个绑定表达式设置到“本地值”中，然后在需要值的时候，会 ProvideValue 提供值。所以，如果再设置了本地值，那么绑定的设置就被覆盖掉了。

但是，SetCurrentValue 就是干这件事的！

SetCurrentValue 设计为在不改变依赖项属性任何已有值的情况下，设置属性当前的值。

_window.SetCurrentValue(Window.WindowStyleProperty, WindowStyle.None);

那么，只需要还原 SetCurrentValue 所做的修改，就还原了此依赖项属性的一切设置的值：

_window.InvalidateProperty(Window.WindowStyleProperty);

注意不是 ClearValue，那会清除本地值。

然而还差一点，绑定如果在你应用 SetCurrentValue 期间有改变，那么这次的赋值并不会让绑定立即生效，所以我们还需要手工再让绑定重新更新值：

BindingOperations.GetBindingExpression(_window, Window.WindowStyleProperty)?.UpdateTarget();

那么，综合起来，本文一开始的代码将更新成如下形式：

private Window _window;

private void OnEnterFullScreen()
{
    _window.SetCurrentValue(Window.WindowStyleProperty, WindowStyle.None);
}

private void OnExitFullScreen()
{
    _window.InvalidateProperty(Window.WindowStyleProperty);
    BindingOperations.GetBindingExpression(_window, Window.WindowStyleProperty)?.UpdateTarget();
}

延伸

将代码变得通用一点：

static void ApplyTempProperty(DependencyObject d, DependencyProperty dp, object tempValue)
{
    d?.SetCurrentValue(dp, tempValue);
}

static void RestoreProperty(DependencyObject d, DependencyProperty dp)
{
    d.InvalidateProperty(dp);
    BindingOperations.GetBindingExpression(d, dp)?.UpdateTarget();
}

Unity3D 入门：如何管理 Unity 项目中的 NuGet 包？使用第三方 NuGet 包管理器——NuGetForUnity

Mon, 01 Jun 2020 01:21:30 +0000

Unity 项目虽然可使用 C# 项目作为脚本，却并没有提供一种类似 NuGet 的第一方包管理器。不过，还是有第三方包管理器可以用，为 C# 脚本应用现有的库提供方便。

NuGetForUnity

第三方适用于 Unity 的 NuGet 包管理器推荐：

GlitchEnzo/NuGetForUnity: A NuGet Package Manager for Unity

去它的 Release 页面，可以下载到 NuGetForUnity.2.0.0.unitypackage 的 Unity 包文件。

安装 NuGetForUnity

NuGetForUnity 是按项目安装的，所以你需要先打开一个项目（否则双击安装只会进到项目选择界面）。

打开了一个 Unity 的项目后，双击下载下来的 NuGetForUnity.2.0.0.unitypackage 文件，你会看到包导入界面：

点击 Import 按钮即可将 NuGetForUnity 安装到你刚刚打开的项目中。

使用 NuGetForUnity

安装完 NuGetForUnity 后，你能在 Unity 编辑器的主菜单上面看到 NuGet 入口了。这很像是 Visual Studio 中自带的 NuGet 包管理器，不过这是适用于 Unity 的第三方 NuGet 包管理器。

安装 NuGet 包

就从上面所述的菜单那里打开，你可以进入 NuGet 包的搜索与安装界面。输入并找到你想安装的 NuGet 包，然后点击 Install 即可。

还原 NuGet 包

正常情况下，你打开别人上传到版本管理中的仓库后，仅仅启动 Unity 编辑器就可以完成 NuGet 包的还原。因为 NuGetForUnity 是安装到项目当中的，Unity 编辑器启动的时候也会运行 NuGetForUnity，这时就会自动还原项目当中所安装过的 NuGet 包了。

还有没有其他包管理方案？

在微软的文档中，描述 NuGet 包安装的方法是手工的，对于普通的没有依赖的 NuGet 包来说问题不大，不过如果 NuGet 包包含依赖的话，那手工处理的工作量就有点大了，尤其是依赖有嵌套，出现层层嵌套的依赖的时候，几乎可以不用考虑手工安装 NuGet 包的方式了。

关于手工安装 NuGet 包的方式，我在另一篇入门文档当中也有说到过：

Unity3D 入门：为 Unity 的 C# 项目添加 dll 引用或安装 NuGet 包 - walterlv

参考资料

GlitchEnzo/NuGetForUnity: A NuGet Package Manager for Unity

Unity3D 入门：Unity 项目版本管理建议使用的 .gitignore 忽略文件和 .gitattributes 文件（2020年4月更新）

Mon, 01 Jun 2020 01:21:30 +0000

Unity3D 项目虽然说使用 C# 脚本开发，但毕竟不是 .NET/C# 项目。今天一位小伙伴告诉我说用错了 .gitignore 文件，结果管理仓库时丢了很多重要的文件。

实际上，GitHub 官方提供了大量不同项目类型的 .gitignore 文件，并且有广大的社区支持时时更新，直接前往 GitHub 官网下载是最好的选择了。

适用于 Unity 项目的 .gitignore 模板：

gitignore/Unity.gitignore at master · github/gitignore

# This .gitignore file should be placed at the root of your Unity project directory
#
# Get latest from https://github.com/github/gitignore/blob/master/Unity.gitignore
#
/[Ll]ibrary/
/[Tt]emp/
/[Oo]bj/
/[Bb]uild/
/[Bb]uilds/
/[Ll]ogs/
/[Uu]ser[Ss]ettings/

# MemoryCaptures can get excessive in size.
# They also could contain extremely sensitive data
/[Mm]emoryCaptures/

# Asset meta data should only be ignored when the corresponding asset is also ignored
!/[Aa]ssets/**/*.meta

# Uncomment this line if you wish to ignore the asset store tools plugin
# /[Aa]ssets/AssetStoreTools*

# Autogenerated Jetbrains Rider plugin
/[Aa]ssets/Plugins/Editor/JetBrains*

# Visual Studio cache directory
.vs/

# Gradle cache directory
.gradle/

# Autogenerated VS/MD/Consulo solution and project files
ExportedObj/
.consulo/
*.csproj
*.unityproj
*.sln
*.suo
*.tmp
*.user
*.userprefs
*.pidb
*.booproj
*.svd
*.pdb
*.mdb
*.opendb
*.VC.db

# Unity3D generated meta files
*.pidb.meta
*.pdb.meta
*.mdb.meta

# Unity3D generated file on crash reports
sysinfo.txt

# Builds
*.apk
*.unitypackage

# Crashlytics generated file
crashlytics-build.properties

# Packed Addressables
/[Aa]ssets/[Aa]ddressable[Aa]ssets[Dd]ata/*/*.bin*

# Temporary auto-generated Android Assets
/[Aa]ssets/[Ss]treamingAssets/aa.meta
/[Aa]ssets/[Ss]treamingAssets/aa/*

注意到 sln 和 csproj 都是忽略的文件吗？这是 Unity 的项目，其他 .NET 项目经常使用的 sln 解决方案管理方式在这里只是辅助手段而已，你可以阅读我的另一篇博客了解更多：

Unity3D 入门：使用 Visual Studio 开发 Unity C# 脚本，说说根目录的那些 sln 和 csproj 文件 - walterlv

额外的，你可能注意到 Unity 项目里面有大量的 *.meta 文件，是自动生成的，这个要加入到版本管理吗？答案是需要。Unity 创建这些文件是为了给导入的文件添加额外的元数据信息的，毕竟不能直接修改原来的文件。这些信息包含：

描述如何导入这个资产文件
如何在项目中准备资产

如果你删除了这些文件，那么 Unity 会用默认的元数据信息生成一个对应的 .meta 文件。

其他类型的 .gitignore 文件前往 GitHub 的 gitignore 仓库：

github/gitignore: A collection of useful .gitignore templates

另外，开启一个新的 Unity 项目时，放一个适用于大多数场景的 .gitattributes 也可以一开始规避一些坑。你可以从下面这位大佬拿到他整理的一个 .gitattribute 文件。

.gitattributes for Unity3D with git-lfs

参考资料

unity5 - What is a .meta file and why does Unity create them for all of my assets? - Stack Overflow

解决包含 GitHub Actions Workflow 的分支无法推送的问题

Tue, 26 May 2020 13:48:42 +0000

refusing to allow an OAuth App to create or update workflow {0} without workflow scope.

GitHub 推送失败？试试本文方法。

问题

试图向 GitHub 推送一个分支的时候，出现错误 refusing to allow an OAuth App to create or update workflow {0} without workflow scope。

这个错误是说，因为 OAuth 的应用没有指定 workflow 范围，所以无法推送带有更新 workflow 的分支。

虽然我实际上没有对 workflow 做任何更新，但也被拒绝了。所以这个问题必须直接解决，绕不开。

git.exe push self master:t/walterlv/trigger
Enumerating objects: 17, done.
Counting objects: 100% (17/17), done.
Delta compression using up to 8 threads
Compressing objects: 100% (9/9), done.
Writing objects: 100% (9/9), 754 bytes | 754.00 KiB/s, done.
Total 9 (delta 8), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (8/8), completed with 8 local objects.
To https://github.com/dotnet-campus/HandyControl.git
! [remote rejected]   master -> t/walterlv/trigger (refusing to allow an OAuth App to create or update workflow `.github/workflows/build.yml` without `workflow` scope)
error: failed to push some refs to 'https://github.com/dotnet-campus/HandyControl.git'

解决

去 GitHub Personal Access Tokens 页面：

Personal Access Tokens

生成一个新的 Token。特别注意在生成的时候要勾选 workflow（如果不确定勾选哪些的话，就全部勾选）：

然后复制新的 Token：

打开凭据管理器：

在 Windows 凭据标签下，找到 GitHub 的几个凭据，然后编辑：

git:https://github.com
git:https://walterlv@github.com

把密码改成刚刚复制的那个 Token，然后保存：

如果你那里有很多 GitHub 相关的凭据而不确定是哪一个的话，可以考虑全部删掉。这样下次推送的时候就会要求你输入账号密码，输入那个 Token 作为密码即可。

现在，你就能推送成功了。

杂谈 System.Drawing.Common 的跨平台性（关键词：libgdiplus / .NET Core / Mono / Win32 / Linux / ……）

Mon, 25 May 2020 01:00:15 +0000

经过 Mono 团队的不懈努力，原本专属于 Win32 平台的 GDI+ 终于可以跨平台了，不过这中间还有好多的故事和好多的坑。

本文带你了解 System.Drawing 命名空间的跨平台。

System.Drawing、System.Drawing.Common 以及 GDI+

在了解本文的后续内容之前，你可能需要先了解一些基本的名词，不然后面极可能看得云里雾里。

System.Drawing 有两个意思，第一个是 System.Drawing.dll 程序集，第二个是 System.Drawing 命名空间。

如果进行 .NET Framework 项目的开发，那么对 System.Drawing 一定不陌生，框架自身对位图的处理基本都是用的这套库，很多第三方图像处理库也都基于 System.Drawing 程序集进行二次封装。比如 JimBobSquarePants/ImageProcessor 库实际上就是对 System.Drawing 的封装，AForge.NET 库作为计算机视觉库也对 System.Drawing 有较大的依赖。

Mono 是一个诞生以来就为了让 .NET Framework 跨平台的开源项目。开发基于 Mono 运行时的项目时，使用的框架 API 也是兼容 .NET Framework 的，因此也可以在 Mono 中直接依赖 System.Drawing 程序集进行开发。

System.Drawing 固然强大，但它却只是 Win32 GDI+ 的一层很薄很薄的封装。然而其他平台上没有原生对 GDI+ 的实现，所以跨平台是一个比较棘手的问题（本文后面会说到如何做到跨平台）。

.NET Core 也是为跨平台而生，不过它走的路线与 Mono 有些不同。它从 API 级别就分离出 .NET Framework 中不跨平台的部分，然后把它们从 .NET 的核心仓库中移除，换成 .NET 的扩展框架（如 WPF / Windows Forms）。那么面对 System.Drawing 部分的 API 时 .NET Core 是怎么做的呢？一开始做了一个兼容库 CoreCompat.System.Drawing（仓库在这里和这里）做了一部分的兼容，而后由于 Mono 的努力做出了 GDI+ 在其他平台上的实现（mono/libgdiplus），.NET Core 就有幸将 System.Drawing 纳入 .NET Core 中作为一个扩展库存在。而这个库就是 System.Drawing.Common（仓库在这里）。

我们小结一下：

GDI+ 是 Windows 上的图形设备接口（Graphics Device Interface），用来完成一些和绘制有关的工作，用以解决不同应用程序开发者需要面向具体的硬件绘图造成的兼容负担（类似的有 GTK 的 GDK/Xlib 还有 Mac 设备的 Quartz）。
System.Drawing 命名空间里包含了封装 GDI+ 的一层薄薄的封装，System.Drawing.dll 是 .NET Framework 下这层封装的实现，System.Drawing.Common 库是 .NET Core 下这层封装的实现。

跨平台的关键 libgdiplus

libgdiplus 是在非 Windows 操作系统上提供 GDI+ 兼容 API 的 Mono 库，而其跨平台图形绘制的大部分关键实现靠的是 Cairo 库。

libgdiplus 的开源仓库：

mono/libgdiplus: C-based implementation of the GDI+ API

目前，其几乎就是为 System.Drawing 命名空间下的位图处理作为实现的。System.Drawing 的跨平台的能力几乎完全靠的是 libgdiplus 库。

安装方法见仓库 README。

目前 libgdiplus 还有一些没能完全实现的部分：

文本
- libgdiplus 目前是自己实现的一套文本引擎，但 GDI+ 提供了 libgdiplus 不支持或不正确支持的许多（很少使用的）选项
- 目前也正考虑使用 pango 引擎来替代自己的实现，可通过 –with-pango 选项开启 pango 引擎，但没实现的功能更多
其他
- 还有其他一些没实现的功能
- 可在这里看到尚未实现的功能列表 libgdiplus/TODO at master · mono/libgdiplus
- Mono 官方欢迎社区广大小伙伴帮忙完成这些任务

System.Drawing 各平台目前的支持情况

Mono 和 .NET Core 目前均已完成基于 libgdiplus 的 System.Drawing 命名空间的跨平台。当然，这个跨平台迁移的唯一目的是“兼容”，是为了让现有的基于 System.Drawing 的代码能够跨平台跑起来。仅此而已，不会有任何的性能优化或者设计优化。（想要优化的版本可以参考本文最后推荐的其他图形库）。

但依然值得注意的是，这个跨平台依然不是完全的跨所有平台：

一是因为前面我们说到的 libgdiplus 尚未完全实现 GDI+ 的所有功能
二是因为 Windows 自己的 UWP 平台无法完成 System.Drawing 的实现

这里将其他的基于 .NET / Windows 平台的图形实现放到一起来做对比：

	Win32	UWP	macOS	Linux / 其他
.NET Framework (GDI+)	✔️	❌	❌	❌
Direct2D / Win2D	✔️	✔️	❌	❌
Mono / .NET Core (libgdiplus)	✔️	❌	✔️	✔️
Xamarin (CoreGraphics)	❌	❌	✔️	❌
其他第三方 .NET 库	✔️	✔️	✔️	✔️

.NET Framework 中的实现也就是本文一直在说的重点，即 System.Drawing，即对 GDI+ 那非常薄的封装。
Direct2D / Win2D 只能在 Windows 平台使用；如果不使用 UWP 桥，那么 Win2D 也只能局限在 UWP 平台，而且要求系统版本 Windows 8 及以上。
Mono / .NET Core 基于 libgdiplus 实现跨平台，但需要注意在 Win32 平台上，它用的也是现成的 GDI+ 实现，而不是 libgdiplus。
Xamarin / CoreGraphics 这是使用原生系统组件做的图形实现，仅支持 macOS 平台。
其他第三方库因为不强依赖系统组件，所以能做到更好的跨平台特性。（可见本文末尾推荐的图像库。）

选择 System.Drawing.dll 还是选择 System.Drawing.Common

问题

回到 System.Drawing 上，现在我们知道应该使用 System.Drawing.dll 还是使用 System.Drawing.Common 库了吗？

盲猜应该使用 System.Drawing.Common 库吧？因为这个库里面既带了 Windows 平台下的实现（对 GDI+ 做一层很薄的封装），又带了 Linux 和 macOS 下的实现（使用 libgdiplus）。

然而事情并没有那么简单！我来问几个问题：

.NET Framework 里面已经自带了 System.Drawing.dll 了，那么 System.Drawing.Common 包里带的 System.Drawing.Common.dll 是否会与之冲突？
- 例如是否会导致同一个类型分属两个不同的程序集导致分别依赖两个不同程序集的不同代码之前无法传递 System.Drawing 命名空间中的参数呢？
所有种类的项目都能正常使用 System.Drawing.Common 库吗？
- 例如 Unity3D 项目

首先来看看问题一。我们新建一个 .NET Framework 的项目，一个 .NET Core 的项目，两者都安装 System.Drawing.Common 包，然后调用一下这个包里面的方法：

class Program
{
    private static void Main()
    {
        var bitmap = new Bitmap(@"D:\walterlv\test.png");
    }
}

反编译

会发现，两者都是可以正常运行的。

将 net48 框架项目下引用的 System.Drawing.Common.dll 反编译来看，可以发现，这是一个空的程序集，里面几乎没有任何实质上的类型。里面所有的类型都通过 TypeForwardedTo 特性转移到 System.Drawing.dll 程序集了，现在剩下的只是一个垫片。关于 TypeForwarding 可以阅读这篇博客了解：C# dotnet TypeForwarding 的用法，微软也有其他通过此方式做的 NuGet 包，可参见微软官方的 NuGet 包是如何做到同时兼容新旧框架的？ - walterlv。

将 netcoreapp3.1 框架项目下引用的 System.Drawing.Common.dll 反编译来看，可以发现，这个程序集里面所有的类型所有的方法实现都是抛出 PlatformNotSupportedException。

这就有些奇怪了，如果所有的方法都抛出 PlatformNotSupportedException 那如何才能正常运行呢？

打开 netcoreapp3.1 输出目录下的 *.deps.json 文件，可以注意到，里面记录了在不同的运行目标下应该使用的真实的 System.Drawing.Common.dll 的文件路径：

"runtimeTargets": {
        "runtimes/unix/lib/netcoreapp3.0/System.Drawing.Common.dll": {
        "rid": "unix",
        "assetType": "runtime",
        "assemblyVersion": "4.0.2.0",
        "fileVersion": "4.700.19.56404"
    },
        "runtimes/win/lib/netcoreapp3.0/System.Drawing.Common.dll": {
        "rid": "win",
        "assetType": "runtime",
        "assemblyVersion": "4.0.2.0",
        "fileVersion": "4.700.19.56404"
    }
}

去相应的路径下找，可以找到 win 版本的 System.Drawing.Common.dll 和 unix 版本的 System.Drawing.Common.dll。

这些指定的依赖，在发布此程序之后会换成真实的依赖，而不再包含多个不同平台下的 dll 了：

dotnet publish -c Release -f netcoreapp3.1 -r win10-x64 --self-contained true

拆包

我们去 nuget.org 上下载下来 System.Drawing.Common 包拆开来看，会发现这个包有两个很关键的文件夹：

lib
runtimes

其中，lib 里面包含这些不同的目标框架：

MonoAndroid10
MonoTouch10
net461
netstandard2.0
xamarinios10
xamarinmac20
xamarintvos10
xamarinwatchos10

net461 里包含的 dll 就是前面我们说到的“垫片”，所有的类型都通过 TypeForwardedTo 转移到 .NET Framework 版本的 System.Drawing.dll。

netstandard2.0 适用于 .NET Core 框架，里面包含的 dll 就是前面我们说到的所有方法都抛出 PlatformNotSupportedException 的版本。

其他所有框架里都是 . 文件，是个空的文件，仅用来告诉 NuGet 这个包支持这些框架安装，但不引用任何 dll。

另外，NuGet 包的 runtimes 文件夹里面包含了前面我们说到的 win 和 unix 不同实现版本的 System.Drawing.Common.dll。前面已经给出了反编译的截图，应该足够了解了。你也可以自己去解包，了解里面的目录结构，去反编译看。

决定

现在，是时候来决定应该使用 System.Drawing.dll 还是使用 System.Drawing.Common 包了。那么，这里我整理一张表：

	System.Drawing.dll	System.Drawing.Common
.NET Framework 4.6 及以下版本	✔️	❌
.NET Framework 4.6.1 及以上版本	✔️	✔️
.NET Core 1.x	❌	❌无法安装包
.NET Core 2.0 - .NET Core 2.1	❌	❌运行时抛出 `PlatformNotSupportedException`
.NET Core 3.0 及以上版本	❌	✔️
Mono / Xamarin	✔️	❌

✔️表示可以使用，没有问题；❌表示不支持此引用方式。

另外，这里还要额外说一下 Unity 的支持情况。

Unity 有两种不同的 C# 脚本后端可选：Mono 和 IL2CPP。然而 Unity 不能原生支持 NuGet 包，而 System.Drawing.Common 包要能够在编译时自动选择正确的 dll 去引用，是需要 3.4 版本以上的 NuGet 程序来支持的。如果不能完全实现此版本 NuGet 的功能，那么编译时是无法将正确的 dll 拷贝到输出目录的。不幸的是，目前流行于 Unity 的第三方 NuGet 管理器不能正确拷贝此包的 dll 到输出目录。

更具体的，是受以下设置的影响（在编译设置里面）：

	脚本后端	Api 兼容级别	System.Drawing.dll	System.Drawing.Common
组合1	Mono	.NET 4.x	✔️	❌相当于没引用
组合2	Mono	.NET Standard 2.0	❌相当于没引用	❌第三方 NuGet 包管理器会拷贝错误的 dll
组合3	IL2CPP	.NET 4.x	❌可在编辑器运行，但打包后会出现异常	❌未引用任何库
组合4	IL2CPP	.NET Standard 2.0	❌相当于没引用	❌第三方 NuGet 包管理器会拷贝错误的 dll

是不是很悲惨？只有 Mono / .NET 4.x 这个组合可以正常使用 System.Drawing。当然，如果你愿意用部分手工或自己的脚本/工具来代替第三方 NuGet 包的部分功能，选择出正确的 dll 的话，那么对应的方案也是能行的。

表中的“❌相当于没引用”指的是引用此 dll 相当于没引用 dll，安装此包相当于没有引用此包：

// .NET 4.x 的 Api 兼容级别报此错误
The type name '{0}' could not be found in the namespace 'System.Drawing'. This type has been forwarded to assembly 'System.Drawing, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a' Consider adding a reference to that assembly.

// .NET Standard 2.0 的 Api 兼容级别报此错误
The type or namespace name 'Imaging' does not exist in the namespace 'System.Drawing' (are you missing an assembly reference?)

IL2CPP 里在编辑器里可以正常使用（当然能正常，因为编辑器又没用 IL2CPP），打包后出现的异常如下（所有的 System.Drawing 方法调用都有异常）：

NotSupportedException: System.Drawing.Image::FromHbitmap
System.Drawing.Image.FromHbitmap (System.IntPtr hbitmap) (at <00000000000000000000000000000000>:0)

关于 Unity 的部分，本文不打算细说。如果你有其他疑问，我就挖个坑，再写一篇来填。

不依赖 System.Drawing 的其他免费开源库

如果你当前的开发平台依然无法使用到 System.Drawing 命名空间，那么可以考虑使用另外的一些替代品。这里给出一些推荐：

如果你需要的是图像处理，而不需要与 Windows API 有太多关联的话，那么使用这些库会比使用 System.Drawing 带来更优秀的用法、更好的性能以及更现代化的维护方式。

参考资料

微软官方的 NuGet 包是如何做到同时兼容新旧框架的？例如 System.ValueTuple 是如何做到在新旧版本的框架都能使用的？

Sun, 24 May 2020 08:27:16 +0000

不知你是否好奇，System.ValueTuple 是新框架（.NET Core 3.0）开始引入的类型，但可以通过 NuGet 包向旧框架提供这些类型的使用。并且，这些包即便安装到本来就有此类型的新框架上也能正常运行而不会出现多处类型定义的问题。

这些类型是如何做到框架内定义了，包里也定义了，却能像同一个类型一样作为参数和返回值传递？本文带你了解其中的奥秘。

示例项目

首先，我们需要有一个示例项目，用来观察 System.ValueTuple 在框架内和 NuGet 包内的一些行为。

创建一个 .NET Core 控制台项目。然后我们需要修改两个地方：

Program.cs 文件
项目文件（*.csproj）文件

class Program
{
    static void Main()
    {
        var (a, b) = Foo();
        System.Console.WriteLine($"欢迎阅读{a}的博客 {b}");
    }

    static (string a, string b) Foo() => ("吕毅", "blog.walterlv.com");
}

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFrameworks>net462;net48;netstandard2.0;netcoreapp2.0;netcoreapp3.1</TargetFrameworks>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="System.ValueTuple" Version="4.5.0" />
  </ItemGroup>

</Project>

接下来，我们的研究都将基于此项目。

研究开始

System.ValueTuple 对旧框架的支持体现在三个方面：

旧框架中也能写出新框架中的这种语法；
旧框架中也能正常使用此类型；
新框架中此类型不会与包中的类型冲突。

我们分别来看看这三个都是如何实现的。

语法支持

C# 从 7.0 开始支持元组类型的语法，即可以写出这样的代码：

var (a, b) = Foo();

关于此新增功能，可以前往这里查看：

C# 7.0 中的新增功能 - C# 指南 - Microsoft Docs

C# 从 8.0 开始，各种原本需要实现特定接口才能写出的语法，现在也可以不用实现接口了，只要有对应的方法存在即可，比如：

IDisposable
IEnumerable
Deconstruct

另外，从 C# 5.0 开始引入的 async/await 也是如此，无需实现任何接口，有 GetAwaiter 方法就够了。也是一样的情况，详见：

.NET 中什么样的类是可使用 await 异步等待的？ - walterlv

也就是说，只要你的项目使用的 C# 版本在 7.0 以上，就可以使用元组解构这样的语法。即便在 C# 7.0 以下，也能使用 System.ValueTuple，只是不能使用此语法而已。

旧框架兼容

System.ValueTuple 对旧框架的兼容，单纯的就是通过 NuGet 包引入了这些类型，以及这些类型的实现而已。

我们在示例项目的 net462 的输出目录下找到 System.ValueTuple.dll 进行反编译可以看出来这一点：

新框架不冲突

我们再去新框架里面看看 System.ValueTuple 的情况。

例如先看看 net48 目录下的 System.ValueTuple.dll：

可以发现，net48 下的 System.ValueTuple 已经全部使用 TypeForwardedTo 特性转移到了 mscorelib 程序集。

.NET Core 3.1 版本和 .NET Standard 2.0 版本的输出目录里是没有 System.ValueTuple.dll 的，那么它们的依赖是如何决定的呢？

答案是——不需要依赖！

我们来拆开 System.ValueTuple 的 NuGet 包看看。可在这里下载：NuGet Gallery - System.ValueTuple 4.5.0。

可发现它提供了这些不同框架的支持：

其中：

net47 框架使用的是 TypeForwardedTo 的垫片
net461 / netstandard1.0 / portable-net40+sl4+win8+wp8 框架使用的是完整版本的 System.ValueTuple
netcoreapp2.0 / netstandard2.0 / mono 全系列 / xamarin 全系列 / uap 里面是 _._ 占位文件，表示支持此框架且无需任何引用（因为框架已经自带支持）

原生支持 System.ValueTuple 的框架，其 NuGet 包中的框架内的文件是 _._，这个文件的出现仅仅是为了能让 zip 里面有一个对应框架的文件夹。而 zip 对空文件夹的支持并不好，所以加一个这样的文件可以避免文件夹消失，造成 NuGet 认为不支持这样的框架。

结论

框架（.NET）和语言（C#）现在已是独立升级了，因此在使用旧框架的情况下，也可以使用新语言的特性；
旧框架使用的是完整功能的 dll（由 NuGet 包来决定使用正确的 dll）；
新框架使用的是 TypeForwardedTo 特性作为垫片，重定向类型到新框架中（由 NuGet 包来决定使用正确的 dll）。

额外的，我写过另一个通过此方式获得新旧框架兼容的包：

杂谈 System.Drawing.Common 的跨平台性 - walterlv

参考资料

What do mean . files in nuget packages? · Issue #744 · dotnet/aspnetcore

Unity3D (Mono/IL2CPP) 中 P/Invoke 平台调用代码应该如何传委托

Sun, 24 May 2020 02:21:31 +0000

IL2CPP does not support marshaling delegates that point to instance methods to native code. 你可能平时在 .NET Core / Framework 的代码中写得很正常的托管代码的委托调用，在 Unity3D 中变得不可行。

本文举个例子，并且将其改正。

举例：查找所有可见窗口

本文的例子会使用到 NuGet 包 Lsj.Util.Win32，这是个非常棒的 Win32 调用的 API 包装，可以免去大量自己可能写不对的 [DllImport]。

引入命名空间：

using Lsj.Util.Win32;
using Lsj.Util.Win32.BaseTypes;

然后查找所有的可见窗口。

public static IReadOnlyList<HWND> FindVisibleWindows()
{
    var found = new List<HWND>();
    User32.EnumWindows(OnWindowEnum, IntPtr.Zero);
    return found;

    BOOL OnWindowEnum(HWND hWnd, LPARAM lparam)
    {
        if (User32.GetParent(hWnd) == IntPtr.Zero && User32.IsWindowVisible(hWnd))
        {
            found.Add(HWND);
        }
        return true;
    }
}

Mono / IL2CPP

Unity 编译的时候可以选择脚本后端是 Mono 还是 IL2CPP。不幸的是，没有 .NET Core 或者未来的 .NET 5/6，因此很多 .NET Core 的特性不能用。

关于脚本后端的选择，可以参见我的另一篇博客：

Unity3D 入门：为 Unity 的 C# 项目添加 dll 引用或安装 NuGet 包 - walterlv

在编译时不会有什么问题，但是在运行时会发生异常（如果你去捕捉，或者用 VS 调试就可以看到）：

NotSupportedException:
        IL2CPP does not support marshaling delegates that point to instance methods to native code.
        The method we're attempting to marshal is: Win32WindowExtensions+<>c__DisplayClass0_0::<FindVisibleWindows>g__OnWindowEnum|0
    at Lsj.Util.Win32.User32.EnumWindows (Lsj.Util.Win32.User32+WNDENUMPROC lpEnumFunc, Lsj.Util.Win32.BaseTypes.LPARAM lParam)
    at Win32WindowExtensions.FindVisibleWindows ()

“IL2CPP 不支持封送实例方法到本机代码”。

修正代码

Mono/IL2CPP 要求封送到本机的代码必须是静态方法，且必须标 MonoPInvokeCallback 特性。

因此，我们不得不把上面的代码改成这样：

using System;
using System.Collections.Generic;
using System.Text;
using AOT;
using Lsj.Util.Win32;
using Lsj.Util.Win32.BaseTypes;

public class WindowsEnumerator
{
    private static List<HWND> _currentList;

    public IReadOnlyList<HWND> FindVisibleWindows()
    {
        _currentList = new List<HWND>();
        User32.EnumWindows(OnWindowEnum, IntPtr.Zero);
        return _currentList;
    }

    [MonoPInvokeCallback(typeof(User32.WNDENUMPROC))]
    static BOOL OnWindowEnum(HWND hWnd, LPARAM lparam)
    {
        if (User32.GetParent(hWnd) == IntPtr.Zero && User32.IsWindowVisible(hWnd))
        {
            _currentList?.Add(HWND);
        }
        return true;
    }
}

当然上述代码不是线程安全的。所以如果你希望在多线程环境下使用，请自行修改为线程安全的版本。

参考资料

MonoPInvokeCallbackAttribute Class (ObjCRuntime) - Microsoft Docs

Windows/Linux 系统中获取端口被哪个应用程序占用

Sat, 23 May 2020 12:21:49 +0000

管理服务程序的时候，可能会查询某个端口当前被哪个进程占用。不仅能找出有问题的进程将其处理掉，也可以用来辅助检查某个程序是否开启了服务并在监听端口。

Windows 系统

Windows 系统上可以使用 PowerShell 命令来查询占用某个端口的程序。

比如，我们需要查询 5000 端口被占用的进程是谁，可以在 PowerShell 中输入命令：

Get-Process -Id (Get-NetTCPConnection -LocalPort 5000).OwningProcess

Linux 系统

在终端中输入命令 lsof 可以查询占用某个端口的进程。

lsof -i:端口号

比如，我们需要查询 5000 端口被占用的进程是谁，可以在中断中输入命令：

walterlv@localhost:~# lsof -i:5000
COMMAND        PID USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
dotnet_serve   731 root    3u  IPv6  12890      0t0  TCP *:5000

或者使用 netstat 查询。

netstat -tunpl | grep 端口号

举例：

walterlv@localhost:~# netstat -tunpl | grep 35412
tcp6   0   0 :::5000     :::*             731/dotnet_serve

如何在 Unity3D 场景中显示帧率（FPS）

Sat, 23 May 2020 08:37:08 +0000

本文介绍如何在 Unity3D 场景中显示帧率。

插入 UI：Text

做 FPS 帧率显示需要用到 UI 对象 Text，因此你需要有一个 Canvas。关于在 Unity3D 中插入 UI 对象的方法可见我的另一篇博客：

Unity3D 入门：如何为游戏添加 UI - walterlv

当添加了 Canvas 后，再在 Canvas 里添加 Text：

设置文本的属性和布局

选中文本对象，在 Inspector 窗格中有很多需要设置的属性。如下图所示。

锚点对齐

上图中，我把点击对齐格子的弹出框放到了场景空间中（截图而已，实际不能放），不然会遮挡窗口中的其他属性。

这里在水平和垂直方向上都分别可以设置 4 种对齐方式：

左/上对齐
居中对齐
右/下对齐
拉伸对齐

默认是水平垂直居中，于是 UI 对象会以场景的中心为参考点布局。如果你强行把文本对象拉到左上角，那么你会失去分辨率自适应的特性。

由于本文期望 FPS 显示到左上角，所以我把锚点设置成左上角。

相对位置，大小

接着，使用鼠标拖拽文本到合适的位置。也可以直接在 Inspector 窗口中设置 PosX 和 PosY 属性，这样更精确。

也许你注意到还有一个 PosZ 属性可以设置。如果你在 2D 视图中，那么你会发现设置这个属性是“无效”的，但只要切回 3D 视图，你就能发现还是有深度变化的。不过，在设置 Canvas 的 Render Mode 属性之前（保持默认值），这个设置依然还是没有意义，因为默认情况下 UI 在最终显示的时候是始终保持 2D 视图的。

可以拖拉鼠标调整文本框的大小，也可以设置 Width 和 Height 属性。

设置文本的文字内容、字体大小和颜色

在下面的 Text 组件里面，你还可以设置通常本文应该有的属性，调整到你觉得合适的值就好。

添加帧率计算脚本

接下来我们开始添加帧率计算脚本。

创建脚本

在 Inspector 窗口中添加 AddComponent 添加组件，选择新脚本，取个名字。

设计脚本属性

using UnityEngine;
using UnityEngine.UI;

public class FpsUpdater : MonoBehaviour
{
    public Text fpsText;

    void Update()
    {
    }
}

我们在脚本中公开一个属性 fpsText，用来在 Inspector 窗口中制定要更新的文本 UI。

然后，将文本对象拖到脚本的 Fps Text 属性上，这样我们就可以在脚本中直接使用 fpsText 字段拿到要更新文本的 Text 对象了。

当然，直接用 gameObject 也是可以的，不过需要自己再做类型转换。

编写代码

最简单的

最简单的获取 FPS 的方式是直接用 1 除以当前帧所经历的时间。

void Update()
{
    var fps = 1.0f / Time.deltaTime;
    fpsText.text = $"FPS: {fps}";
}

然而当你实际使用的时候你就会觉得——嗯……眼睛会瞎的。

你也有可能发现文字一时出现一时消失，那可能是因为你文本框的宽度设小了。于是当小数点后位数多了一些之后，显示不下去，文字就会消失。

至少，取个整还是需要的吧，谁愿意看小数帧数呢？

var fps = 1.0f / Time.deltaTime;
fpsText.text = $"FPS: {Mathf.Ceil(fps)}";

更稳定的

加了取整还是变化很快，看不清。那么可以如何更稳定呢？

可以考虑累加多帧再一次性更新。比如这里 60 帧更新一次：

using UnityEngine;
using UnityEngine.UI;

public class FpsUpdater : MonoBehaviour
{
    public Text fpsText;

    private int count;
    private float deltaTime;

    void Update()
    {
        count++;
        deltaTime += Time.deltaTime;

        if (count % 60 == 0)
        {
            count = 1;
            var fps = 60f/deltaTime;
            deltaTime = 0;
            fpsText.text = $"FPS: {Mathf.Ceil(fps)}";
        }
    }
}

或者考虑 0.5 秒更新一次：

public Text fpsText;

private int count;
private float deltaTime;

void Update()
{
    count++;
    deltaTime += Time.deltaTime;

    if (deltaTime >= 0.5f)
    {
        var fps = count/deltaTime;
        count = 0;
        deltaTime = 0;
        fpsText.text = $"FPS: {Mathf.Ceil(fps)}";
    }
}

Unity3D 入门：如何为游戏添加 UI

Sat, 23 May 2020 07:21:49 +0000

早期的 Unity3D 做 UI 并不容易，以至于大家习惯于使用 NGUI 插件来开发。后来 NGUI 的开发者加入开发了 Unity UI，现在就有了一套更好用的 Unity UI 可用了。

本文简单介绍如何添加 UI 作为入门，不会深入介绍各种 UI 和细节。

添加 Canvas

Unity UI 都需要放到 Canvas 上才能工作。你可以像如下图这样插入一个 Canvas。

当然，你也可以插入其他的 UI 对象，不过最终 Unity 编辑器都会帮你插入一个 Canvas，然后把你插入的对象放到这个 Canvas 里面。

EventSystem

当你开始向场景中插入 Unity 后，同时也会插入一个 EventSystem 游戏对象。EventSystem 的作用是接收系统中的输入事件，以便 UI 元素能够接受到这些事件处理用户的输入。

Canvas 的属性

在 Inspector 窗口中，表示 Canvas 在场景中位置的对象是 RectTransform 对象了，不再是 Transform 对象。这是定位 UI 的坐标而设计的新的类型。

你无法修改 Canvas 的 RectTransform 对象的任何属性，这样 Unity 才可以让这个 Canvas 能根据分辨率自适应。

其他 UI

关于 Unity UI 的其他细节，我将在单独的博客中说明。

如何在 Unity3D 场景中显示帧率（FPS） - walterlv

切换成 2D 视图

在开发（2D）UI 的时候，建议将场景视图切换成 2D，这样比较容易做布局。

当然，如果你不像我这样能看得到整个 Canvas 的话，可以考虑调整下视角或者直接双击 F。

关于操作视角和快捷键，可以参考我的其他博客：

Unity3D 入门：Unity Editor 编辑器常用快捷键 - walterlv

Unity3D 入门：为 Unity 的 C# 项目添加 dll 引用或安装 NuGet 包

Sat, 23 May 2020 06:38:45 +0000

因为 Visual Studio 有强大的包管理器插件，所以即便是不熟悉 NuGet 命令的小伙伴也能轻松安装和管理 NuGet 包。不过，对 Unity C# 项目来说，你并不能直接引用 dll，也不能直接使用自带的 NuGet 包管理器完成 NuGet 包安装。

本文介绍原因和真正的引用方法。

背景

对于传统 .NET/C# 的开发者来说，在解决方案中管理 NuGet 包，在 C# 项目中引用 dll 或 NuGet 包是家常便饭。但在 Unity 项目里面，你可能要改变这一观念——因为 Unity 项目里面实际上并不存在 sln 和 csproj 文件。

简单了解项目根目录的 sln 文件和 csproj 文件将有助于你理解为什么要像本文一样引用 dll 和安装 NuGet 包，因此如果你不了解，建议先阅读：

Unity3D 入门：使用 Visual Studio 开发 Unity C# 脚本，说说根目录的那些 sln 和 csproj 文件 - walterlv

如何引用 dll 或者安装 NuGet 包

在 Unity 中，是给 C# 脚本引用 dll 或者安装 NuGet 包，而不能给 C# 项目做 dll 引用。

Unity 中引用 dll 有两种官方途径：

Assets\csc.rsp 文件，用于指定引用 .NET 运行时的 dll
Assets\Plugins 文件夹，用于指定引用单独的 dll 文件

当然，这两个能否正常使用，以及扔到 Plugins 文件夹中的 dll 应该是什么平台，取决于 Unity 项目的配置。

当然，引用 NuGet 包的话更推荐非官方的方法，详见：

如何管理 Unity 项目中的 NuGet 包？使用第三方 NuGet 包管理器——NuGetForUnity

配置运行时和 API 兼容性级别

在 Unity 编辑器中，打开“Edit”->“Project Settings…”->“Player”->“Other Settings”->“Configuration”。

这里我们关心脚本后端（相当于运行时部分），以及 API 兼容性级别。

脚本后端设置的是脚本如何运行，而 API 兼容性级别设置的是编译时应该使用哪一套 API。

选 Mono 那么使用 Mono 虚拟机运行，选 IL2CPP 那么会编译 IL 到静态的 cpp 文件不依靠 Mono VM。

如果选 .NET 4.x 那么你能引用到 .NET Framework 4.x 子集的 API，如果是 .NET Standard 那么能引用到 .NET Standard 程序集。

你可以通过 Unity将来时：IL2CPP是什么？ - 知乎简单了解 IL2CPP 是什么。

mcs.rsp

如果你的 API 兼容性级别是 .NET Standard 2.0，那么你不应该使用此 mcs.rsp 文件。因为当你选择 .NET Standard 2.0 的 API 级别后，.NET Standard 2.0 中的所有依赖就全部引入了，如果还缺，那也不会在 .NET Standard 2.0 里面，你应该考虑后面“Plugins”的引用方式。

接下来，我们说说当你使用 .NET 4.x 的 API 级别时，应该如何使用 mcs.rsp 来引用 dll。

例如对于下图（图来自微软官方文档），希望使用 .NET 4.x 自带的 HttpClient 类型。

向 Unity 项目的 Assets 文件夹新建一个 mcs.rsp 文件，里面添加以下内容：

-r:System.Net.Http.dll

这表示此 Unity 项目中的 C# 脚本引用 .NET Framework 中的 System.Net.Http 程序集。之后，你就能使用诸如 HttpClient 这些类型。

你也可以使用同样的方式引用其他的 dll，每行一个。

默认情况下，Unity 会帮我们引用这些 .NET 4.x 的程序集：

mscorlib.dll
System.dll
System.Core.dll
System.Runtime.Serialization.dll
System.Xml.dll
System.Xml.Linq.dll

因此，你不需要手工将它们加入到 mcs.rsp 文件中。

Plugins

对于 .NET 4.x 或者 .NET Standard 2.0 中不带的类型，那么你应该使用 Plugins 文件夹来解决。

在 Assets 文件夹中新建 Plugins 文件夹，然后将你希望引用的 dll 丢进去就完成了。

引用 dll

因此，如果你已经拥有了 dll 了，那么直接往 Plugins 文件夹扔就好了。但是你需要注意，扔进去的 dll 需要兼容目标运行时（如 Mono 虚拟机）以及目标平台（例如 iOS）。

安装 NuGet 包

原生 Unity 项目不能直接安装 NuGet 包，但可以通过第三方插件实现。

原生

原生 Unity 项目并不能直接安装 NuGet 包，所以实际上对于 NuGet 包的引用是通过把包里的 dll 丢到 Plugins 文件夹来实现的。

既然如此，那就看如何丢进去更有效率了。

微软官方文档的方法是直接从 nuget.org 上直接把包下载下来，解压，然后将对应平台的 dll 从 lib 文件夹中取出来（例如 API 兼容性级别是 .NET Standard 2.0 的项目，请拷贝 lib/netstandard2.0 中的 dll 出来）。

因为 Unity 编辑器生成了 sln 和 csproj，所以在 Visual Studio 里安装也是可以的，不过这里的安装并不会真实生效，而是我们在 Unity 项目的根目录的 Packages 文件夹中能找到我们安装的 NuGet 包，也是从对应的文件夹中取出来 dll 丢到 Plugins 文件夹中。

第三方

更推荐非官方的方法，详见：

如何管理 Unity 项目中的 NuGet 包？使用第三方 NuGet 包管理器——NuGetForUnity

特别注意：反射需要额外支持

如果你前面的脚本后端（Script Backend）选择了 IL2CPP，那么小心 dll 的元数据会丢失，依赖于反射的功能也将崩溃。例如大量依赖于反射的 Newtonsoft.Json 库就会在此情况下无法正常工作。

如果你需要用到反射，或者你用到的某库中需要依赖反射功能，那么请在 Assets 文件夹中添加 link.xml 文件，内容如下：

<linker>
  <assembly fullname="System.Core">
    <type fullname="System.Linq.Expressions.Interpreter.LightLambda" preserve="all" />
  </assembly>
</linker>

这将确保 Unity 的字节码剥离过程在导出到 IL2CPP 平台时不会删除必要的数据。

参考资料

Unity - Manual: Referencing additional class library assemblies

Win32/C# 应用使用 PrintWindow 对窗口截图（PrintWindow）

Sat, 23 May 2020 06:32:26 +0000

相比于 Windows 2000 引入到 GDI+ 中的 BitBlt 方法截取窗口图片，Windows XP 时也引入了 PrintWindow 方法来专门截取窗口，截取的原理也不同。

微软 Office 系列里的截取窗口，用的就是 PrintWindow 方法。

开始截图

相比于使用 BitBlt 方法，使用 PrintWindow 截取窗口的代码少得多。

你需要引用如下命名空间：

using System.Drawing;
using System.Drawing.Imaging;
using System.Drawing.Graphics;

public static byte[] CaptureWindow(HWND hWnd, int width, int height)
{
   using (var bmp = new Bitmap(width, height))
   {
       using (Graphics memoryGraphics = Graphics.FromImage(bmp))
       {
           IntPtr dc = memoryGraphics.GetHdc();
           PrintWindow(hWnd, dc, 0);
           memoryGraphics.ReleaseHdc(dc);

           using (MemoryStream ms = new MemoryStream())
           {
               bmp.Save(ms, ImageFormat.Png);
               ms.Seek(0, SeekOrigin.Begin);
               return ms.ToArray();
           }
       }
   }
}

[DllImport("User32.dll", SetLastError = true)]
static extern bool PrintWindow(IntPtr hwnd, IntPtr hdc, uint nFlags);

原理、效果和问题

使用 PrintWindow 来截图时，目标窗口会收到一次 WM_PRINT 或 WM_PRINTCLIENT 消息以完成一次绘图。并且，此过程是同步进行的，如果目标窗口在处理消息时没有返回，那么这里的调用将一直挂起。

使用此方法截图时，DWM 绘制的窗口部分在真实窗口中和实际截出来的会不一样，是关掉了 Aero 效果时的窗口样式。

当然，还有可能把目标窗口截挂：

Win32/C# 应用不依赖任何库使用纯 GDI+ 对窗口截图（BitBlt）

Sat, 23 May 2020 05:52:28 +0000

在 Windows 上有 GDI+ 来操作位图，不止能完成很多的位图操作，还提供了与 Win32 窗口的互操作，可以截到 Win32 窗口的图片。

如果你希望对窗口截图，那么可使用本文提供的方法。

没有依赖

本文对窗口的截图几乎不需要任何额外的依赖（当然，都 GDI 了，Windows 系统还是要的）。

不过，你可以考虑使用 Lsj.Util.Win32 来简化代码，所以如果不介意的话也推荐安装，避免手工写一大堆的 P/Invoke。如果打算自己写 P/Invoke 又不熟的话，你可以参考使用 PInvoke.net Visual Studio Extension 辅助编写 Win32 函数签名 - walterlv。

如果你的项目可以使用 System.Drawing.Bitmap 类的话，那更推荐直接使用 Bitmap，那样更简单。请参考 Win32/C# 应用不依赖任何库使用纯 GDI+ 对窗口截图（BitBlt） - walterlv。

开始截图

如果你使用了 Lsj.Util.Win32 库，那么需要引用一些命名空间：

using Lsj.Util.Win32;
using Lsj.Util.Win32.BaseTypes;
using Lsj.Util.Win32.Enums;
using Lsj.Util.Win32.Structs;

这个命名空间中已经带了很多我们需要用到的 Win32 互操作需要用到的数据结构，所以本文代码中只会列出库中暂时没有的（不然代码太多了）。

代码如下：

public static byte[] CaptureWindow(HWND hWnd, int width, int height)
{
    // 创建兼容内存 DC。
    var wdc = User32.GetWindowDC(hWnd);
    var cdc = Gdi32.CreateCompatibleDC(wdc);
    // 创建兼容位图 DC。
    var hBitmap = Gdi32.CreateCompatibleBitmap(wdc, width, height);
    // 关联兼容位图和兼容内存，不这么做，下面的像素位块（bit_block）转换不会生效到 hBitmap。
    var oldHBitmap = Gdi32.SelectObject(cdc, (IntPtr)hBitmap);
    // 注：使用 GDI+ 截取“使用硬件加速过的”应用时，截取到的部分是全黑的。
    var result = Gdi32.BitBlt(cdc, 0, 0, width, height, wdc, 0, 0, RasterCodes.SRCCOPY);

    try
    {
        // 保存图片。
        if (result)
        {
            var data = GetImageFromHBitmap(wdc, hBitmap, width, height);
            return data;
        }
        else
        {
            var error = Kernel32.GetLastError();
            throw new Win32Exception((int)error);
        }
    }
    finally
    {
        // 回收资源。
        Gdi32.SelectObject(cdc, oldHBitmap);
        Gdi32.DeleteObject((IntPtr)hBitmap);
        Gdi32.DeleteDC(cdc);
        User32.ReleaseDC(hWnd, wdc);
    }
}

其中，GetImageFromHBitmap 方法的实现就比较麻烦了——我们需要手工写图片文件的文件头！

分成三个部分写入：

BMP 位图文件头
BMP 信息
位图数据

实现如下：

private static unsafe byte[] GetImageFromHBitmap(HDC hdc, HBITMAP hBitmap, int width, int height)
{
    var data = new byte[sizeof(BITMAPFILEHEADER) + sizeof(BITMAPINFOHEADER) + width * height * 3];
    var bitmapInfoHeader = new BITMAPINFOHEADER
    {
        biSize = (uint)sizeof(BITMAPINFOHEADER),
        biWidth = width,
        biHeight = height,
        biPlanes = 1,
        biBitCount = 24,
        biCompression = Compression.BI_PNG,
        biSizeImage = 0,
        biXPelsPerMeter = 0,
        biYPelsPerMeter = 0,
        biClrUsed = 0,
        biClrImportant = 0,
    };
    fixed (void* lpvBits = data)
    {
        var lpvBitsOnData = new IntPtr((long)lpvBits + sizeof(BITMAPFILEHEADER) + sizeof(BITMAPINFOHEADER));
        var got = Gdi32.GetDIBits(hdc, hBitmap, 0, height, lpvBitsOnData, new BITMAPINFO
        {
            bmiColors = new RGBQUAD[1],
            bmiHeader = bitmapInfoHeader
        }, (uint)DIBColorTableIdentifiers.DIB_RGB_COLORS);
    }
    var fileHeader = new BITMAPFILEHEADER
    {
        bfOffBits = (uint)sizeof(BITMAPFILEHEADER) + (uint)sizeof(BITMAPINFOHEADER),
        bfSize = (uint)data.Length,
        bfType = 0x4D42, // BM
    };
    GetBytes(fileHeader).CopyTo(data, 0);
    GetBytes(bitmapInfoHeader).CopyTo(data, sizeof(BITMAPFILEHEADER));
    return data;
}

private static byte[] GetBytes<T>(T @struct) where T : struct
{
    int size = Marshal.SizeOf(@struct);
    byte[] data = new byte[size];

    IntPtr ptr = Marshal.AllocHGlobal(size);
    Marshal.StructureToPtr(@struct, ptr, true);
    Marshal.Copy(ptr, data, 0, size);
    Marshal.FreeHGlobal(ptr);
    return data;
}

[StructLayout(LayoutKind.Sequential, Pack = 2)]
private struct BITMAPFILEHEADER
{
    public ushort bfType;
    public uint bfSize;
    public ushort bfReserved1;
    public ushort bfReserved2;
    public uint bfOffBits;
}

这里代代码不涉及到格式转换，因此你只能生成 BMP 格式。

Win32/C# 应用使用 GDI+ 对窗口截图（BitBlt）

Sat, 23 May 2020 05:52:14 +0000

在 Windows 上有 GDI+ 来操作位图，不止能完成很多的位图操作，还提供了与 Win32 窗口的互操作，可以截到 Win32 窗口的图片。

如果你希望对窗口截图，那么可使用本文提供的方法。

依赖，或者没有依赖

在本文的代码中，你可以考虑引用以下这些库来简化代码。

对于 .NET Core：

对于 .NET Framework / Mono：

System.Drawing.dll
Lsj.Util.Win32

以上所有库都是可选的。

如果你打算不引用 Lsj.Util.Win32，那么下面代码中涉及到的 Win32 API 调用你需要自己写 P/Invoke。如果你不熟悉 P/Invoke 的写法，你可以参考使用 PInvoke.net Visual Studio Extension 辅助编写 Win32 函数签名 - walterlv。

如果你不打算引用 System.Drawing.Common，那么可以考虑使用裸的 GDI+ 来完成，可以参考 Win32/C# 应用不依赖任何库使用纯 GDI+ 对窗口截图（BitBlt） - walterlv。

开始截图

如果你使用了 Lsj.Util.Win32 库，那么需要引用一些命名空间：

using Lsj.Util.Win32;
using Lsj.Util.Win32.BaseTypes;
using Lsj.Util.Win32.Enums;
using Lsj.Util.Win32.Structs;

代码如下：

public static byte[] CaptureWindow(HWND hWnd, int width, int height)
{
    // 创建兼容内存 DC。
    var wdc = User32.GetWindowDC(hWnd);
    var cdc = Gdi32.CreateCompatibleDC(wdc);
    // 创建兼容位图 DC。
    var hBitmap = Gdi32.CreateCompatibleBitmap(wdc, width, height);
    // 关联兼容位图和兼容内存，不这么做，下面的像素位块（bit_block）转换不会生效到 hBitmap。
    var oldHBitmap = Gdi32.SelectObject(cdc, (IntPtr)hBitmap);
    // 注：使用 GDI+ 截取“使用硬件加速过的”应用时，截取到的部分是全黑的。
    var result = Gdi32.BitBlt(cdc, 0, 0, width, height, wdc, 0, 0, RasterCodes.SRCCOPY);

    try
    {
        // 保存图片。
        if (result)
        {
            using (var bmp = Image.FromHbitmap(hBitmap))
            {
                using (var ms = new MemoryStream())
                {
                    bmp.Save(ms, ImageFormat.Png);
                    ms.Seek(0, SeekOrigin.Begin);
                    var data = ms.ToArray();
                    return data;
                }
            }
        }
        else
        {
            var error = Kernel32.GetLastError();
            throw new Win32Exception((int)error);
        }
    }
    finally
    {
        // 回收资源。
        Gdi32.SelectObject(cdc, oldHBitmap);
        Gdi32.DeleteObject((IntPtr)hBitmap);
        Gdi32.DeleteDC(cdc);
        User32.ReleaseDC(hWnd, wdc);
    }
}

示例代码只是单纯返回 PNG 格式的位图数据。你还可以按你的需要改造成其他数据。

提高使用 Visual Studio 开发效率的键盘快捷键

Sat, 23 May 2020 03:25:59 +0000

Visual Studio 的功能可谓真是丰富，再配合各种各样神奇强大的插件，Visual Studio 作为太阳系最强大的 IDE 名副其实。

如果你能充分利用起 Visual Studio 启用这些功能的快捷键，那么效率也会很高。

建议记住

功能	快捷键	建议修改成
重构	`Ctrl + .`	`Alt + Enter`
转到所有	`Ctrl + ,`	`Ctrl + N`
重命名	`F2`
打开智能感知列表	`Ctrl + J`	`Alt + 右`
注释	`Ctrl + K, Ctrl + C`
取消注释	`Ctrl + K, Ctrl + U`
保存全部文档	`Ctrl + K, S`
折叠成大纲	`Ctrl + M, Ctrl + O`
展开所有大纲	`Ctrl + M, Ctrl + P`
加入书签	`Ctrl + K, Ctrl + K`
上一书签	`Ctrl + K, Ctrl + P`
下一书签	`Ctrl + K, Ctrl + N`
切换自动换行	`Alt + Z`

万能重构

你可以不记住本文的其他任何快捷键，但这个你一定要记住，那就是：

当然，因为中文输入法会占用这个快捷键，所以我更喜欢将这个快捷键修改一下，改成：

修改方法可以参见：如何快速自定义 Visual Studio 中部分功能的快捷键。

它的功能是“快速操作和重构”。你几乎可以在任何代码上使用这个快捷键来快速修改你的代码。

比如修改命名空间：

比如提取常量或变量：

比如添加参数判空代码：

还有更多功能都可以使用此快捷键。而且因为 Roslyn 优秀的 API，有更多扩展可以使用此快捷键生效，详见：基于 Roslyn 同时为 Visual Studio 插件和 NuGet 包开发 .NET/C# 源代码分析器 Analyzer 和修改器 CodeFixProvider。

转到所有

不能每次都去解决方案里面一个个找文件，对吧！所以一个快速搜索文件和符号的快捷键也是非常能够提升效率的。

Ctrl + , 转到所有（go to all）

不过我建议将其改成：

Ctrl + N 这是 ReSharper 默认的转到所有（Goto Everything）的快捷键

这可以帮助你快速找到整个解决方案中的所有文件或符号，看下图：

修改方法可以参见：如何快速自定义 Visual Studio 中部分功能的快捷键，下图是此功能的命令名称 编辑.转到所有（Edit.GoToAll）：

有一些小技巧：

你可以无需拼写完整个单词就找到你想要的符号
- 例如输入 mw 就可以找到 MainWindow
对于两个以上单词拼成的符号，建议将每个单词的首字母输入成大写，这样可以提高目标优先级，更容易找到
- 例如 PrivateTokenManager，如果希望干扰少一些，建议输入 PTM 而不是 ptm；当然想要更少的干扰，可以打更多的字母，例如 priToM 等等

注意到上面的界面里面右上角有一些过滤器吗？这些过滤器有单独的快捷键。这样就直接搜索特定类型的符号，而不是所有了，可以提高查找效率。

Ctrl + O 查找当前文件中的所有成员（只搜一个文件，这可以大大提高命中率） Ctrl + T 转到符号（只搜类型名称、成员名称） Ctrl + G 查找当前文件的行号（比如你在代码审查中看到一行有问题的代码，得知行号，可以迅速跳转到这一行）

重构

重命名

F2

如果你在一个标识符上直接重新输入改了名字，也可以通过 Ctrl + . 或者 Alt + Enter 完成重命名。

其他

这些都可以被最上面的 Ctrl + . 或者 Alt + Enter 替代，因此都可以忘记。

Ctrl + R, Ctrl + E 封装字段
Ctrl + R, Ctrl + I 提取接口
Ctrl + R, Ctrl + V 删除参数
Ctrl + R, Ctrl + O 重新排列参数

IntelliSense 自动完成列表

智能感知

IntelliSense 以前有个漂亮的中文名字，叫做“智能感知”，不过现在大多数的翻译已经与以前的另一个平淡无奇的功能结合到了一起，叫做“自动完成列表”。Visual Studio 默认只会让智能感知列表发挥非常少量的功能，如果你不进行一些配置，使用起来会“要什么没什么”，想显示却不显示。

请通过另一篇博客中的内容把 Visual Studio 的智能感知列表功能好好配置一下，然后我们才可以再次感受到它的强大（记得要翻到最后哦）：

通过设置启用 Visual Studio 默认关闭的大量强大的功能提升开发效率

如果还有一些时机没有打开智能感知列表，可以配置一个快捷键打开它，我这边配置的快捷键是 Alt + 右。

参数信息

Ctrl + Shift + 空格

显示方法的参数信息。

默认在输入参数的时候就已经会显示了；如果错过了，可以在输入 , 的时候继续出现；如果还错过了，可以使用此快捷键出现。

编写

代码格式化

Ctrl + K, Ctrl + E 全文代码清理（包含全文代码格式化以及其他功能） Shift + Alt + F 全文代码格式化 Ctrl + K, Ctrl + F 格式化选定的代码

关于代码清理，你可以配置做哪些事情：

其他

Ctrl + K, Ctrl + / 将当前行注释或取消注释
Ctrl + K, Ctrl + C 将选中的代码注释掉
Ctrl + K, Ctrl + U 或 Ctrl + Shift + / 将选定的内容取消注释

Ctrl + U 将当前选中的所有文字转换为小写（请记得配合 F2 重命名功能使用避免编译不通过）
Ctrl + ] 增加行缩进
Ctrl + [ 减少行缩进

Ctrl + S 保存文档 Ctrl + K, S 保存全部文档（注意按键，是按下 Ctrl + K 之后所有按键松开，然后单按一个 S）

Ctrl + F 打开搜索面板开始强大的搜索功能
Ctrl + H 打开替换面板，或展开搜索面板为替换面板
Ctrl + I 渐进式搜索（就像 Ctrl + F 一样，不过不会抢焦点，搜索完按回车键即完成搜索，适合键盘党操作）
Ctrl + Shift + F 打开搜索窗口（与 Ctrl + F 虽然功能重合，但两者互不影响，意味着你可以充分这两套搜索来执行两套不同的搜索配置）
Ctrl + Shift + H 打开替换窗口（与 Ctrl + H 虽然功能重合，但两者互不影响，意味着你可以充分这两套替换来执行两套不同的替换配置）
Alt + 下 在当前文件中，将光标定位到下一个方法
Alt + 上 在当前文件中，将光标定位到上一个方法

Ctrl + M, Ctrl + M 将光标当前所在的类/方法切换大纲的展开或折叠
Ctrl + M, Ctrl + L 将全文切换大纲的展开或折叠（如果当前有任何大纲折叠了则全部展开，否则全部折叠）
Ctrl + M, Ctrl + P 将全文的大纲全部展开
Ctrl + M, Ctrl + U 将光标当前所在的类/方法大纲展开
Ctrl + M, Ctrl + O 将全文的大纲都折叠到定义那一层

Ctrl + D 查找下一个相同的标识符，然后放一个新的脱字号（或者称作输入光标）（多次点按可以在相同字符串上出很多光标，可以一起编辑，如下图） Ctrl + Insert 查找所有相同的标识符，然后全部放置脱字号（如下图）

脱字号是 Visual Studio 中对于输入光标的称呼，对应英文的 Caret。

书签

Ctrl + K, Ctrl + K 为当前行加入到书签或从书签中删除 Ctrl + K, Ctrl + P 切换到上一个书签 Ctrl + K, Ctrl + N 切换到下一个书签 Ctrl + K, Ctrl + L 删除所有书签（会有对话框提示的，不怕误按）

如果配合书签面板，那么可以在调查问题的时候很方便在找到的各种关键代码处跳转，避免每次都寻找。

另外，还有个任务列表，跟书签列表差不多的功能：

Ctrl + K, Ctrl + H 将当前代码加入到任务列表中或者从列表中删除（效果类似编写 // TODO）

显示

Ctrl + R, Ctrl + W 显示空白字符
Alt + Z 切换自动换行和单行模式

鼠标

最后提及一个，Ctrl + 鼠标点击 可以跳转到定义。

不过这个功能有个 bug：

我报给了微软：

When text is selected, Ctrl+Click will not perform the GoTo Definition. - Developer Community

Unity3D 入门：如何制作天空效果？天空盒的使用

Fri, 22 May 2020 10:48:06 +0000

在 Unity 编辑器的主界面中我们可以很容易制作各种场景物体，但天空如何制作呢？

了解和设置默认的天空盒

在新建一个 Unity3D 项目之后，我们在空空如也的场景下看到的那蓝灰过渡的画面，其实就是 Unity3D 默认提供的“天空”，这个机制叫“天空盒”（Skybox）。

你可以在 Window->Rendering->Lighting Settings（窗口->渲染->照明设置）中打开当前场景的照明设置，里面可以设置天空效果。

如下图就是默认天空盒提供的各种参数：

Unity 新建项目时默认的天空盒是程序天空盒（Procedural Skybox）。一般来说程序天空盒提供了众多可以设置的参数，用来后期调节天空的样式。

默认的天空盒其实一个参数都不能直接设置，但可以通过其他游戏物体来间接设置。例如，你试试把一开始的那个定向光（Directional Light）调一下方向，你会发现默认天空中的太阳位置也变化了，跟着定向光的方向变化。

如果你删过这个定向光，也可以通过新建一个到场景中，然后在上图的界面里面点击选择按钮把刚刚新建的定向光选中来再次创建太阳。

在资源商店中下载天空盒

作为入门的话，可以考虑在资源商店中搜索并使用大神们做好的现成的天空盒（关键词 Skybox）：

找到喜欢的天空盒后，点击 Download->Import 可以导入到当前的项目中。这里提一点，商店中的大部分资源，导入到项目中后都在 Assets 目录下。

等待下载并导入完后，你可以看到最终导入的窗口：

在这个最终的窗口中，点击右下角的“导入”即可最终添加到项目中。

在这里，你可以注意到导入的资源中包含 back front top bottom left right 这些图片。这其实是另一种天空盒——六面天空盒（6 Sided Skybox）。（请原谅上图作者中那奇怪的缩写，因为这名字不重要。）

我把刚刚下载的这款天空盒的六个面分别贴出来，就会像下图这样：

我简单做了个动图，用来直观观看天空盒的贴图：

依然在 Window->Rendering->Lighting Settings（窗口->渲染->照明设置）中打开当前场景的照明设置，然后点击选择“天空盒材质”，选择刚刚我们下载的“sky,startday”。于是，我们的场景就应用了商店下载下来的天空盒了。

像这种六面天空盒，虽然依然可以设置太阳源，不过已经不再关联到天空中的太阳的位置了。

总结

本文没有介绍如何制作一个自己的天空盒，因为我也正在学习中。不过我们了解到：

如何下载并应用一个现成的天空盒
天空盒的种类（六面天空盒、程序天空盒）

专业团队：推荐一个网站，生成巨幅文字注释

Tue, 19 May 2020 11:47:30 +0000

通过学习本文的知识，你将可以在你的项目代码里创造大量的注释。让你的注释闪瞎团队所有人的钛合金X眼，我们是专业团队。

Console.WriteLine(@"
██╗    ██╗ █████╗ ██╗  ████████╗███████╗██████╗ ██╗    ██╗   ██╗
██║    ██║██╔══██╗██║  ╚══██╔══╝██╔════╝██╔══██╗██║    ██║   ██║
██║ █╗ ██║███████║██║     ██║   █████╗  ██████╔╝██║    ██║   ██║
██║███╗██║██╔══██║██║     ██║   ██╔══╝  ██╔══██╗██║    ╚██╗ ██╔╝
╚███╔███╔╝██║  ██║███████╗██║   ███████╗██║  ██║███████╗╚████╔╝ 
 ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚═╝   ╚══════╝╚═╝  ╚═╝╚══════╝ ╚═══╝  
");

网址是：http://patorjk.com/software/taag/

你可以在里面选参数，也可以在 URL 上自己补参数以便唯一确定一个样式。比如上图样式的网址是：http://patorjk.com/software/taag/#p=display&f=ANSI%20Shadow&t=walterlv

还比如：

Console.WriteLine(@"
 ___       __   ________  ___   _________  _______   ________  ___       ___      ___ 
|\  \     |\  \|\   __  \|\  \ |\___   ___\\  ___ \ |\   __  \|\  \     |\  \    /  /|
\ \  \    \ \  \ \  \|\  \ \  \\|___ \  \_\ \   __/|\ \  \|\  \ \  \    \ \  \  /  / /
 \ \  \  __\ \  \ \   __  \ \  \    \ \  \ \ \  \_|/_\ \   _  _\ \  \    \ \  \/  / / 
  \ \  \|\__\_\  \ \  \ \  \ \  \____\ \  \ \ \  \_|\ \ \  \\  \\ \  \____\ \    / /  
   \ \____________\ \__\ \__\ \_______\ \__\ \ \_______\ \__\\ _\\ \_______\ \__/ /   
    \|____________|\|__|\|__|\|_______|\|__|  \|_______|\|__|\|__|\|_______|\|__|/    
");

尽情写到团队项目里面吧！我们是专业团队！

.NET Framework 和 .NET Core 在默认情况下垃圾回收（GC）机制的不同（局部变量部分）

Fri, 15 May 2020 13:50:57 +0000

垃圾回收机制有一些未定义部分，一般来说不要依赖于这些未定义部分编程，否则容易出现一些诡异的 bug 或者不稳定的现象。

本文介绍局部变量这部分的细节，而这点在 .NET Framework 和 .NET Core 默认情况下的表现有差别。

问题代码

看看下面这段代码，你觉得会输出 Foo is collected 吗？

class Program
{
    static void Main(string[] args)
    {
        new WeakReference<Foo>(new Foo());
        GCTest();
    }

    private static void GCTest()
    {
        while (true)
        {
            Thread.Sleep(500);
            GC.Collect();
        }
    }
}

public class Foo
{
    ~Foo()
    {
        Console.WriteLine("Foo is collected");
    }
}

如果你没有修改默认的编译设置，那么答案应该是：

全部 .NET Framework 下都输出 Foo is collected
.NET Core 2.x 及以下输出 Foo is collected
.NET Core 3.x 及以上不会有任何输出

额外的，.NET Core 2.1 - .NET Core 3.x 通过设置可以改变此行为，本文文末会说。

然而所有这些平台编译后的 IL 都差不多。虽然引用的程序集不一样，但代码都是一样的。所以问题不在编译器，而在运行时。

.method private hidebysig static 
    void Main (
        string[] args
    ) cil managed 
{
    // Header Size: 1 byte
    // Code Size: 17 (0x11) bytes
    .maxstack 8
    .entrypoint

    /* (12,13)-(12,45) Program.cs */
    /* 0x00000251 7305000006   */ IL_0000: newobj    instance void Walterlv.Demo.Weak.Foo::.ctor()
    /* 0x00000256 730C00000A   */ IL_0005: newobj    instance void class [System.Runtime]System.WeakReference`1<class Walterlv.Demo.Weak.Foo>::.ctor(!0)
    /* 0x0000025B 26           */ IL_000A: pop
    /* (14,13)-(14,22) Program.cs */
    /* 0x0000025C 2802000006   */ IL_000B: call      void Walterlv.Demo.Weak.Program::GCTest()
    /* (15,9)-(15,10) Program.cs */
    /* 0x00000261 2A           */ IL_0010: ret
} // end of method Program::Main

这个问题我提在了 GitHub 上，大家可以去看看：

GC.Collect: Object without reference will be collected in .NET Framework but will NOT been collected in .NET Core · Issue #36265 · dotnet/runtime

原因

当然，当变量脱离作用域后 GC 本应回收，但在同一个函数中定义的变量是否脱离作用域却是未定义的。你可以经常在 DEBUG 下发现依然可访问的变量，但在 RELEASE 下无法访问变量就体现了这种未定义带来的行为差异。

.NET Core 3.0 开始引入了分层编译（Tiered Compilation）。在开启了分层编译的情况下，JIT 执行方法时先会快速编译，随后如果此方法访问频繁会在后台优化这个编译然后替换掉之前编译的方法，以提升后续的运行性能。

在分层编译被启用的情况下，GC 的行为有改变，局部变量不再及时回收。当然以后有更优化的分层编译后，可能有新的行为改变。

如果要关闭分层编译，可以在项目文件中设置 TieredCompilation 为 false，也可以设置环境变量 COMPlus_TieredCompilation=0。这两个是等价的。

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFrameworks>net48;netcoreapp3.1</TargetFrameworks>
+   <TieredCompilation>false</TieredCompilation>
  </PropertyGroup>

关于分层编译，可以阅读林德熙的博客：

dotnet core 2.1 使用分层编译

本文一开始说的行为改变，指的就是开关分层编译。.NET Core 2.1 开始支持分层编译但默认关闭，而 .NET Core 3.0 开始默认开启。所以在支持的框架上你可以开启或关闭。

参考资料

Compilation config settings - .NET Core - Microsoft Docs

.NET/Windows：删除文件夹后立即判断，有可能依然存在

Fri, 15 May 2020 12:10:18 +0000

如果你不了解本文的内容，可能会在未来某个时候踩坑–你可能在判断文件夹是否存在的时候得到错误的返回值。

删除文件（夹）

使用 .NET 带的删除文件夹的方法：

Directory.Delete("D:\walterlv");

或者使用其他删除文件（夹）的方法，大多数是以下 Windows API 的封装：

BOOL DeleteFile(
  LPCTSTR lpFileName
);
BOOL RemoveDirectoryA(
  LPCSTR lpPathName
);
BOOL RemoveDirectoryW(
  LPCWSTR lpPathName
);

于是，大多数删除文件（夹）的代码都会遇到问题：文件或文件夹可能没有立即删除！

测试程序

using System;
using System.IO;

class Program
{
    static void Main(string[] args)
    {
        var dirPath = @"C:\Users\lvyi\Desktop\Test";
        while (true)
        {
            Console.WriteLine(Directory.Exists(dirPath));
            Directory.CreateDirectory(dirPath);
            Directory.Delete(dirPath);
        }
    }
}

你猜会输出什么？每一行都输出 False 吗？

然而实际上是：

嗯……会混入少量的 True 在里面。这是不是有点“不符合预期”？

原因

删除文件夹的本质方法 RemoveDirectory 在微软的官网中就已经解释了：

The RemoveDirectory function marks a directory for deletion on close. Therefore, the directory is not removed until the last handle to the directory is closed.

RemoveDirectory 函数将标记一个文件夹在关闭后删除。这意味着在最后一个此文件夹的句柄关闭之前，此文件夹将一直不会删除。

所以调用完删除文件夹的方法后，仅仅只是标记这个文件夹要删除而已。那么随后立即获取此文件夹是否存在，将取决于前面调用删除后是否真的删除了文件夹。

删除文件的本质方法 DeleteFile 也有类似的解释：

The DeleteFile function marks a file for deletion on close. Therefore, the file deletion does not occur until the last handle to the file is closed. Subsequent calls to CreateFile to open the file fail with ERROR_ACCESS_DENIED.

DeleteFile 函数将标记一个文件在关闭后删除。这意味着在最后一个文件句柄关闭之前，此文件将一直不会删除。如果随后立即调用 CreateFile 来打开一个文件的话可能会遭遇错误 ERROR_ACCESS_DENIED。

解决方法

因此，不要再依赖于判断文件夹是否存在来决定某个业务。例如，可以考虑创建文件夹之前不判断文件夹是否存在：

--  if (Directory.Exists(path))
--  {
        Directory.CreateDirectory(path);
--  }

注意，以上红色色块标记的代码应该删除！否则你可能会发现这段代码执行完成后，文件夹是不存在的。

如果试图删除文件随后新建空白的文件或者其他文件的话，可以考虑我在另一篇博客中提到的创建或打开文件的方法，用来应对文件不存在的情况：

发现 dotnet 职业技术学院另一小伙伴也遇到这个问题：

不要在Directory删除后立刻调用Directory.Exist - huangtengxiao

参考资料

在制作多框架项目的 NuGet 包时应该注意的问题（buildMultiTargeting/TargetFrameworks）

Fri, 15 May 2020 06:23:19 +0000

制作一个 dll 引用的 NuGet 包简直是一键完成，无论是不是多框架项目；制作 dotnet-tools 也是如此。但如果需要自定义一些编译步骤，那么就需要在制作 NuGet 包时做很多的特殊处理了。

本文介绍制作适用于多框架项目的 NuGet 工具包时应该注意的问题。

背景知识

NuGet 包内的文件夹结构

回顾一下 NuGet 包的文件夹结构：

+ /
+ lib/
+ ref/
+ runtimes/
+ content/
+ build/
+ buildMultiTargeting/
+ buildTransitive
+ tools/

由于涉及到自定义 NuGet 包的代码都写在 build buildMultiTargeting 和 buildTransitive 中，其他都不涉及到 NuGet 包在编译期间会做的事情，另外，buildTransitive 是用来处理包传递过程中的编译过程的，所以我们本文只说也只需要说 build 和 buildMultiTargeting。

这里面的代码都是用 Target 写出来的，如果你对此不了解，建议阅读这些博客：

制作有自定义功能的 NuGet 包

我之前写过一些关于如何制作各种高级功能的 NuGet 包的博客：

按照上面的博客制作出来的 NuGet 包其实是适用于单框架项目和多框架项目的，甚至也适用于传统的非 SDK 风格的项目。

关于单框架和多框架项目，就是项目文件中这里的差别：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <!-- 单框架项目 -->
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

</Project>

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <!-- 多框架项目 -->
    <TargetFrameworks>netcoreapp3.1;net48</TargetFrameworks>
  </PropertyGroup>

</Project>

但是，有的小伙伴希望探索一些更高级的用法，所以可能会遇到在多框架项目中，NuGet 包自定义的功能不执行的问题。

接下来，我们了解一下在单框架和多框架下 NuGet 包执行上的不同。

执行时机

我们打出这样的两种 NuGet 包，一种是仅包含 build 文件夹而不包含 buildMultiTargeting 文件夹；一种是包含 build 文件夹和 buildMultiTargeting 文件夹。

我们的目标项目一种是单框架项目；一种是多框架项目。

于是我们可以得到这样的四种不同的组合情况：

仅含 build 文件夹的 NuGet 包装到单框架项目中
仅含 build 文件夹的 NuGet 包装到多框架项目中
包含 build 和 buildMultiTargeting 文件夹的 NuGet 包装到单框架项目中
包含 build 和 buildMultiTargeting 文件夹的 NuGet 包装到多框架项目中

1. 仅含 `build` 文件夹的 NuGet 包装到单框架项目中

在这种情况下，build 文件夹中的 .props 和 .targets 文件在目标项目编译时正常执行。

2. 仅含 `build` 文件夹的 NuGet 包装到多框架项目中

在这种情况下，build 文件夹中的 .props 和 .targets 文件，会分别在目标项目编译每个框架的时候执行一次。

例如这种项目：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <!-- 多框架项目 -->
    <TargetFrameworks>netcoreapp3.1;net48</TargetFrameworks>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Walterlv.NullableAttributes.Source" Version="0.15.0" />
  </ItemGroup>

</Project>

那么，在编译 netcoreapp3.1 框架的时候会执行一次 Walterlv.NullableAttributes.Source 包中 build 文件夹中的编译任务；在编译 net48 框架的时候又会执行一次 Walterlv.NullableAttributes.Source 包中 build 文件夹中的编译任务。

3. 包含 `build` 和 `buildMultiTargeting` 文件夹的 NuGet 包装到单框架项目中

在这种情况下，buildMultiTargeting 中的任何编译任务相当于不存在。编译过程与情况 1 是完全一样的。

4. 包含 `build` 和 `buildMultiTargeting` 文件夹的 NuGet 包装到多框架项目中

从 NuGet 5.x 版本开始在这种情况下，build 中的内容和 buildMultiTargeting 中的编译任务会同时参与编译。

依然举例这样的目标项目（不过使用了含 buildMultiTargeting 的 NuGet 包）：

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <!-- 多框架项目 -->
    <TargetFrameworks>netcoreapp3.1;net48</TargetFrameworks>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Walterlv.NullableAttributes.Source" Version="2.1.1" />
  </ItemGroup>

</Project>

编译一开始，会将 buildMultiTargeting 中的编译任务加入执行。在编译 netcoreapp3.1 框架的时候会执行一次 Walterlv.NullableAttributes.Source 包中 build 文件夹中的编译任务；在编译 net48 框架的时候又会执行一次 Walterlv.NullableAttributes.Source 包中 build 文件夹中的编译任务。而这两个单独框架的编译结束后，buildMultiTargeting 中的任务才会结束。

也就是说，这两个编译任务文件夹中的编译任务是都会执行的。但是：

两者参与编译的 Targets 不一样。

下表中列出了在你没有编写任何扩展的任务或者干预已有 Target 执行的情况下，默认可以依赖的 Target（指的是可以通过 BeforeTargets="xx" 或 AfterTargets="xx" 的方式扩展编译任务：

可依赖的 Target	build	buildMultiTargeting
BeforeCompile	✔	❌
Compile	✔	❌
CoreCompile	✔	❌
AfterCompile	✔	❌
BeforeBuild	✔	❌
Build	✔	✔
AfterBuild	✔	❌
BeforeRebuild	❌	❌
Rebuild	❌	✔（如果强行执行）
AfterRebuild	❌	❌
BeforeClean	✔（如果强行执行）	❌
Clean	✔（如果强行执行）	✔（如果强行执行）
AfterClean	✔（如果强行执行）	❌

注：强制执行说的是一般编译时不会执行，你需要在命令中指定执行这个 Target。也对应到 Visual Studio 里的“重新编译”和“清理”的功能。

为了更好理解上表，这里给出一个例子。下面的代码如果在 build 文件夹中则会在编译过程输出一堆星号，而如果在 buildMultiTargeting 文件夹中则不会执行。而无论目标项目是否是多框架的。但换成 AfterBuild 则会两个文件夹中都输出。

<Target Name="WalterlvDemoTarget" AfterTargets="Build">
    <Message Text="****************************************************************" />
</Target>

当然，不要被这个第 4 种情况带歪了！如果你的 NuGet 包依然只有一个 build 文件夹，那么上面的所有 Targets 都是会执行的。

参考资料

为 .NET 各种开发工具设置网络代理，提升在大陆的网络性能

Wed, 13 May 2020 02:09:47 +0000

git、nuget、scoop 如何设置网络代理提升网络访问速度呢？

在下面的博客正文中，都假设我的本机搭设了代理服务，其中 SOCKS5 代理服务的端口号是 7777，HTTP 代理服务的端口号是 7778。

git

使用命令行设置

git 支持设置 http 代理和 socks5 代理，http 的代理和 https 的代理是分开设置的。

设置方法：

打开任意一个命令行工具；
在命令行中输入以下两个命令并回车。

git config --global http.proxy http://127.0.0.1:7778
git config --global https.proxy http://127.0.0.1:7778

或者：

git config --global http.proxy socks5://127.0.0.1:7777
git config --global https.proxy socks5://127.0.0.1:7777

在设置完成之后，你无需担心内网访问的问题，因为 Git 会自动在代理的时候过滤掉内网代理。

直接修改配置文件

git 全局配置文件的路径在：

%USERPROFILE%\.gitconfig

在这个文件中，你需要添加以下几行：

    [user]
        name = walterlv
        email = walter.lv@qq.com
+   [http]
+       proxy = http://127.0.0.1:7778
+   [https]
+       proxy = http://127.0.0.1:7778

或者：

    [user]
        name = walterlv
        email = walter.lv@qq.com
+   [http]
+       proxy = socks5://127.0.0.1:7777
+   [https]
+       proxy = socks5://127.0.0.1:7777

添加完成之后，你的 git 访问就会走代理，对于 GitHub 的访问，快速克隆大型仓库是非常有帮助的。

使用 TortoiseGit 设置

以上命令行的方法是最简单的，然而你也可以使用其他的工具设置，比如 TortoiseGit。

设置方法：

在任意的文件夹中打开 TortoiseGit 的设置页面，然后定位到网络一栏中，勾选“使用代理服务器”。
输入服务器地址和端口号，确定即可。

NuGet

使用 NuGet 直接拉取的内容也是很慢的，如果有一个代理服务器的设置那么也能大大提速。

在命令行中设置

> nuget config -set http_proxy=http://127.0.0.1:7778

直接修改配置文件

git 全局配置文件的路径在：

%APPDATA%\NuGet\NuGet.Config

在这个文件中，你需要添加以下几行：

    <?xml version="1.0" encoding="utf-8"?>
    <configuration>
      <packageSources>
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
      </packageSources>
      <config>
+       <add key="http_proxy" value="http://127.0.0.1:7778" />
      </config>
    </configuration>

如果这么设置了，那么 NuGet 会为所有的包源设置代理。然而内部部署的包源并不需要代理，于是还需要设置 no_proxy：

    <configuration>
      <config>
        <add key="http_proxy" value="http://127.0.0.1:7778" />
+       <add key="no_proxy" value="localhost,127.0.0.1,*.walterlv.com" />
      </config>
    </configuration>

Scoop

Scoop 是一款优秀的包管理工具，可以以绿色的方式安装各种工具。

scoop config proxy 127.0.0.1:7778

Chocolatey / ChocolateyGUI

Chocolatey 是 Windows 上非常著名的包管理工具。它支持的代理设置方法非常多，你可以去它的官网了解所有的设置代理的方法：Chocolatey Software - Proxy Settings for Chocolatey。

这里简单搬运一下直接的设置方法。

choco config set proxy 127.0.0.1:7778

同时，它也支持 http_proxy https_proxy 和 no_proxy 这样全局的环境变量设置。

另外，不喜欢命令行版的 choco 和命令行版代理设置的同学，可以考虑用 ChocolateyGUI：

chocolatey/ChocolateyGUI: A delicious GUI for Chocolatey

参考资料

Unity3D 入门：如何在脚本中找到游戏对象的父子级/祖孙级对象和它们的组件

Sun, 10 May 2020 07:34:05 +0000

在真正能玩的游戏场景中，很多脚本的执行是在不确定的游戏对象上进项的，于是会考虑在父对象或者子对象上去写脚本。这时，可能需要查找游戏对象。那么如何在脚本中找到父子游戏对象（gameObject）呢？

场景

如下图所示，Windows 游戏对象下面可能有很多不确定数量和位置的游戏对象，需要操作它们。

在为游戏对象创建脚本的时候，这个脚本中的类会继承自 MonoBehavior：

using UnityEngine;

public class WindowUpdater : MonoBehaviour
{
    void Start()
    {
    }

    void Update()
    {
    }
}

找父组件/子组件

MonoBehavior 直接提供了查找父子组件的方法 GetComponent(s) / GetComponent(s)InParent 和 GetComponent(s)InChildren，因此直接调用即可。对于泛型方法，每个子对象只会找到一个组件，所以通常适用于子组件非常简单的场景。

var renderers = GetComponentsInChildren<Renderer>();
for (var i = 0; i < renderers.Length; i++)
{
    var texture = textures[i];
    renderers[i].material.mainTexture = texture;
}

找父对象/子对象

MonoBehavior 并没有提供直接查找父子对象的方法。

但是 Transform 有！

所以，通过 Transform 可以间接获取到子对象。GetChild() GetChildCount。

var transform = GetComponent<Transform>();
for (int i = 0; 0 < renderers.Length; i++)
{
    transform.GetChild(i).gameObject.SetActive(true);
}

WPF 中使用附加属性，将任意 UI 元素或控件裁剪成圆形（椭圆）

Wed, 06 May 2020 00:15:56 +0000

不知从什么时候开始，头像流行使用圆形了，于是各个平台开始追逐显示圆形裁剪图像的技术。WPF 作为一个优秀的 UI 框架，当然有其内建的机制支持这种圆形裁剪。

不过，内建的机制仅支持画刷，而如果被裁剪的元素支持交互，或者拥有普通画刷无法达到的显示效果，那么就需要本文介绍的更加通用的解决方法了。

UWP 的圆形裁剪请左转参考：UWP 将图片裁剪成圆形（椭圆）。

WPF 的 UIElement 提供了 Clip 依赖项属性，可以使用一个 Geometry 来裁剪任意的 UIElement。由于 Geometry 几乎可以表示任意形状，这意味着我们可以才建成任意想要的样子。

于是，我们可以利用这一点，使用 EllipseGeometry 将任意 UIElement 裁剪成圆形或者椭圆形。比如，写成下面这样：

<Grid>
    <Grid.Clip>
        <EllipseGeometry Center="120 180" RadiusX="120" RadiusY="180" />
    </Grid.Clip>
    <Image Source="demo.jpg" Stretch="Fill" />
    <TextBlock Text="https://walterlv.github.io" Foreground="White" Margin="171,172,51,21"/>
</Grid>

最终可以出现如下的效果。

不过，稍微改变下窗口的大小，就会发现裁剪的范围不对了。因为我们写死了圆形裁剪的中心点和两个不同方向的半径（这里可不好说是长半轴还是短半轴啊）。

我们需要一个可以自动修改裁剪圆形的一种机制，于是，我们想到了 Binding。为了使 XAML 的代码好看一点，我将 Binding 封装到了一个单独的类中处理，使用附加属性提供 API。

我封装好的类如下：

/// <summary>
/// 提供将任意控件裁剪为圆形或椭圆的附加属性。
/// </summary>
public static class EllipseClipper
{
    /// <summary>
    /// 标识 IsClipping 的附加属性。
    /// </summary>
    public static readonly DependencyProperty IsClippingProperty = DependencyProperty.RegisterAttached(
        "IsClipping", typeof(bool), typeof(EllipseClipper), new PropertyMetadata(false, OnIsClippingChanged));

    public static void SetIsClipping(DependencyObject element, bool value)
        => element.SetValue(IsClippingProperty, value);

    public static bool GetIsClipping(DependencyObject element)
        => (bool) element.GetValue(IsClippingProperty);

    private static void OnIsClippingChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
    {
        var source = (UIElement) d;
        if (e.NewValue is false)
        {
            // 如果 IsClipping 附加属性被设置为 false，则清除 UIElement.Clip 属性。
            source.ClearValue(UIElement.ClipProperty);
            return;
        }

        // 如果 UIElement.Clip 属性被用作其他用途，则抛出异常说明问题所在。
        var ellipse = source.Clip as EllipseGeometry;
        if (source.Clip != null && ellipse == null)
        {
            throw new InvalidOperationException(
                $"{typeof(EllipseClipper).FullName}.{IsClippingProperty.Name} " +
                $"is using {source.GetType().FullName}.{UIElement.ClipProperty.Name} " +
                "for clipping, dont use this property manually.");
        }

        // 使用 UIElement.Clip 属性。
        ellipse = ellipse ?? new EllipseGeometry();
        source.Clip = ellipse;

        // 使用绑定来根据控件的宽高更新椭圆裁剪范围。
        var xBinding = new Binding(FrameworkElement.ActualWidthProperty.Name)
        {
            Source = source,
            Mode = BindingMode.OneWay,
            Converter = new HalfConverter(),
        };
        var yBinding = new Binding(FrameworkElement.ActualHeightProperty.Name)
        {
            Source = source,
            Mode = BindingMode.OneWay,
            Converter = new HalfConverter(),
        };
        var xyBinding = new MultiBinding
        {
            Converter = new SizeToClipCenterConverter(),
        };
        xyBinding.Bindings.Add(xBinding);
        xyBinding.Bindings.Add(yBinding);
        BindingOperations.SetBinding(ellipse, EllipseGeometry.RadiusXProperty, xBinding);
        BindingOperations.SetBinding(ellipse, EllipseGeometry.RadiusYProperty, yBinding);
        BindingOperations.SetBinding(ellipse, EllipseGeometry.CenterProperty, xyBinding);
    }

    private sealed class SizeToClipCenterConverter : IMultiValueConverter
    {
        public object Convert(object[] values, Type targetType, object parameter, CultureInfo culture)
            => new Point((double) values[0], (double) values[1]);

        public object[] ConvertBack(object value, Type[] targetTypes, object parameter, CultureInfo culture)
            => throw new NotSupportedException();
    }

    private sealed class HalfConverter : IValueConverter
    {
        public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
            => (double) value / 2;

        public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
            => throw new NotSupportedException();
    }
}

在 XAML 中只需要很简单的一个属性赋值即可达到圆形或椭圆形裁剪。

<Grid local:EllipseClipper.IsClipping="True">
    <Image Source="fluentdesign-app-header.jpg" Stretch="Fill" />
    <TextBlock Text="https://walterlv.github.io" Foreground="White" Margin="171,172,51,21"/>
</Grid>

而且在控件的大小改变的时候也能够正常更新裁剪范围。

这篇博客的核心代码我也贴在了 StackOverflow 上：c# - WPF displaying a gif in an ellipse - Stack Overflow

快速在 Windows 上搭建 Jekyll 开发环境

Wed, 06 May 2020 00:13:27 +0000

Jekyll 是一个不错的静态博客工具，本文将提供快速在 Windows 系统上搭建 Jekyll 开发环境的方法。

For 老手

其实所需的命令只有少数几个而已：

# 全局命令：安装 Ruby 所需的依赖
ridk install
# 全局命令：安装 Jekyll
gem install jekyll bundler
# 工作目录命令：安装博客仓库中所需的依赖
bundle install
# 工作目录命令：将本地博客仓库跑起来
jekyll serve

For 新手

下载必要的软件

考虑到我们的网络环境，为了提升本文的阅读效率，建议一边下载一边阅读。

如果无法下载，可以考虑 Docker 或者 Windows 上的其他包管理器（如 scoop）。

安装 Ruby 和 Jekyll

分别安装下载好的 Ruby 和 MSYS2 安装包，一路下一步，直到两者都安装结束；
一般安装完 Ruby 后会自动弹出一个新的命令行安装界面，我们需要在里面选择 3，然后回车。
- 如果上一步没有提前下载安装 MSYS2，那么这里会因为众所周知的网络原因速度奇慢无比，或者以失败告终。
- 如果没有弹出命令行安装界面或者把它关掉了，那么也可以在任意的命令行中输入 ridk install 来再次进入命令行安装界面。
- 如果网络状况良好，能够一次装成功。（如果不幸失败。则一直再次选 3 继续安装直到全部成功为止。）
```
 Install MSYS2 and MINGW development toolchain succeeded
```
再打开一个新的命令行窗口（cmd/powershell/bash/msys2 都行），输入以下命令安装 jekyll：
```
gem install jekyll bundler
```

自此，Jekyll 开发环境就搭建完成了。

让自己的博客跑起来

如果你已经有了自己的 Jekyll 博客，希望在本地能够编译运行，那么就继续阅读本节。

可能你的博客来源于这些地方：

从 Jekyll Themes 挑选并下载了一款主题；
克隆了自己或别人的博客站点，准备改改自己用；

那么我们开始。首先在博客的根目录打开命令行，接下来的操作都在命令行中。

安装依赖包
```
bundle install
```
将 Jekyll 服务跑起来
```
jekyll serve
```

这就完成了！

不过，如果上述第 2 个步骤发生了错误，通常是依赖包的版本不匹配所致，运行命令更新依赖包：

bundle update

随后再次 jekyll serve 即可。

Ruby 跨版本升级的坑

如果你之前安装过 Ruby 的旧版本，现在需要跨大版本号升级，那么你会遇到很多问题：

ruby 命令对应新旧哪个版本是不明确的
如果你覆盖安装了 ruby，那么之前安装自动设置的那些环境变量（例如 gem）就会丢失

这会导致你试图编译你的博客时遇到各种各样奇怪的错误。

所以，你需要做的是：

卸载掉之前的 ruby
再次安装 ruby

Unity3D 入门：Unity Editor 编辑器常用快捷键

Tue, 05 May 2020 11:35:25 +0000

本文为 Unity3D 入门小伙伴整理 Unity 编辑器中的常用快捷键。

调节工具

Unity 编辑器左上角的一组按钮，正好也对应着键盘左上角的字母：

图标
快捷键	Q	W	E	R	T	Y
英文	Hand Tool	Move Tool	Rotate Tool	Scale Tool	Rect Tool	Move, Rotate or Scale selected objects
中文	手形工具	移动工具	旋转工具	缩放工具	矩形工具	移动、旋转或缩放选定对象
功能	在整个场景中移动漫游	按坐标轴移动选定对象	按三个维度旋转对象	在三个维度上缩放对象	以矩形的方式调节对象的尺寸	综合前面所有对选定对象的调节工具

除了使用 Q 打开手形工具随后用鼠标左键漫游场景外，使用鼠标中键也可以在任意工具下漫游场景（按住鼠标中键然后移动鼠标）。

按住鼠标右键移动可以以当前镜头处为轴心旋转视角，按住鼠标右键的同时按下 W A S D Q E 也可以前后左右下上移动镜头。

按住 Alt 键的同时，也可以在任意工具下使用鼠标左键移动镜头，不过与前面不同的是，这是以目标物体为轴心来移动和旋转的。

按住 Alt 键的同时，按住鼠标右键上下左右移动也可以移远和移近物体。

按住 Ctrl 键的同时，使用以上所有工具移动、旋转或缩放对象的话，可以对齐网格。（Edit->Grid and Snap Settings... 可以打开网格设置。）

按住 V 键的同时，鼠标放到对象中心的移动格子上移动对象，可以让此对象对齐场景中的其他对象。（下图指示了鼠标拖哪里。）

视图调节

F（置于中心）：当在层级（Hierarchy）窗口或场景（Scene）窗口选中某个对象后，可按 F 将对象置于场景中心，并放大/缩小到合适的尺寸。

窗口调整

Shift + 空格（最大化/还原）：当你的焦点在 Unity 编辑器的任何子窗口中的时候，按下 Shift + Space 可以将此子窗口最大化或者还原。

如下图是最大化后的场景窗口：

进入退出播放模式

Ctrl + P（进入退出播放模式）：相当于按下界面中的“播放”按钮。

所有快捷键

在 Edit->Shortcuts... 中可以找到并编辑所有的快捷键。

参考资料

Unity - Manual: Unity shortcuts

Unity3D 入门：让 C# 脚本公开可在 Unity 编辑器中设置的属性

Tue, 05 May 2020 08:22:24 +0000

将一部分参数从 C# 脚本中抽离出来，可以让 C# 脚本在 Unity 项目中更通用，适用于更多游戏对象（gameObject）。

本文介绍如何创建可在 Unity 编辑器中设置属性的 C# 脚本，并介绍如何在 Unity 编辑器中设置它们。

简单的 C# 脚本

本文的例子取自于我的另一篇博客：

Unity3D 入门：最简单的控制视角，以及控制角色前进、转向的脚本 - walterlv

using UnityEngine;

public class PlayerController : MonoBehaviour
{
    private Transform transform;
    public float moveSpeed = 5f;
    public float rotateSpeed = 50f;

    void Start()
    {
        transform = GetComponent<Transform>();
    }

    void Update()
    {
        float adValue = Input.GetAxis("Horizontal");
        float wsValue = Input.GetAxis("Vertical");
        float mValue = Input.GetAxis("Mouse X");

        var moveDirection = (Vector3.forward * wsValue) + (Vector3.right * adValue);
        transform.Translate(moveDirection.normalized * moveSpeed * Time.deltaTime, Space.Self);
        transform.Rotate(Vector3.up * rotateSpeed * Time.deltaTime * mValue);
    }
}

公开字段

只需要将脚本的字段设为 public，Unity 编辑器便能识别出这些字段以及它们的类型，然后允许你在 Inspector 中编辑它们。

注意，Inspector 中不会识别属性，更不会识别方法。所以要公开，必须使用“字段”。

在哪里修改值

Unity 编辑器会在每次重新激活编辑器窗口的时候重新加载 Unity 项目。因此，当你在 Visual Studio 或其他编辑器中新编写了公开字段后，回到 Unity 编辑器中便会识别到这些字段，然后显示出来。

值得注意的是，这个时候就已经记录了此脚本在此游戏对象中的值。也就是说，此后无论你如何在脚本中修改公开字段的值，运行游戏都不会有变化，因为游戏开始后，就会用你在编辑器中设置的值（虽然不是手工设的）覆盖脚本中编写的默认值。

要修改，还是需要在 Inspector 中去修改值。

有趣的名称

按照 Unity C# 脚本的编写规范，公开的字段也是按 camelCase 命名的。当然，你也可以用 PascalCase 命名也不会有什么识别上的问题。

不过，无论你用什么命名，Inspector 中都会将你的名称拆开成多个单词，并首字母大写。

更有趣的是，如果你使用了一些预设的字段名称，那么 Inspector 中会显示成预设的名称。典型的是命名成 Name 的时候，Inspector 中会显示“名称”（如果你装了中文语言包的话）。

Unity3D 入门：最简单的控制视角，以及控制角色前进、转向的脚本

Tue, 05 May 2020 07:58:46 +0000

本文依然是 Unity3D 的入门篇。作为 Unity3D 的入门读者，你可能希望迅速让你能在游戏中操作你的视角，或者让角色移动。

创建脚本

作为入门篇，可能需要讲一下如何创建脚本。按下图，在 Unity 编辑器中：

在 Hierarchy（层级）中选中主摄像机；
在 Inspector（检查器）中选择最后那个 Add Component（添加组件）；
选择 New Script（新建脚本）输入脚本名称，然后点击 Create and Add（创建并添加）。

接下来，我们需要去 Visual Studio 中编辑这个脚本。

点击菜单中的 Assets -> Open C# Project（资源 -> 打开 C# 项目）。于是可以转到 Visual Studio 中编辑你的脚本文件。

最简代码

在 Visual Studio 中找到我们刚刚创建的 PlayerController 脚本。

其实就是脚本名加上 .cs 后缀。Unity 中 C# 脚本要求文件名必须匹配脚本的类名，因此，不要随便尝试改文件名或类名；就算改了，也要同步更新文件名和类名重新匹配，并重新在 Inspector 中添加新名称的脚本。

在脚本中添加如下代码：

using UnityEngine;

public class PlayerController : MonoBehaviour
{
    private Transform transform;
    public float moveSpeed = 5f;
    public float rotateSpeed = 50f;

    void Start()
    {
        transform = GetComponent<Transform>();
    }

    void Update()
    {
        float adValue = Input.GetAxis("Horizontal");
        float wsValue = Input.GetAxis("Vertical");
        float mValue = Input.GetAxis("Mouse X");

        var moveDirection = (Vector3.forward * wsValue) + (Vector3.right * adValue);
        transform.Translate(moveDirection.normalized * moveSpeed * Time.deltaTime, Space.Self);
        transform.Rotate(Vector3.up * rotateSpeed * Time.deltaTime * mValue);
    }
}

Start 消息会在游戏对象（也就是前面我们添加了脚本的那个主摄像机）创建后，第一个 Update 消息执行前调用，可以用来做一些初始化。这里，我们拿到我们需要做变换的 Transform 组件（这里的组件也就是 Unity 编辑器的“检查器”中看到的一个个组件）。

而 Update 会尽量在每一帧执行一次，我们在这里执行一些需要每帧更新的逻辑。

我们做了这些事情：

定义了公共的两个字段 moveSpeed 和 rotateSpeed 表示移动速度和转向速度。
通过 Input.GetAxis 获取不同种类的玩家输入。
通过玩家的输入计算 Transform 组件的更新差量，然后更新 Transform 组件。

关于在脚本当中公开属性以在编辑器中设置的更多细节，可阅读我的另一篇 Unity3D 入门博客：

Unity3D 入门：让 C# 脚本公开可在 Unity 编辑器中设置的属性 - walterlv

可以看以下效果（gif 文件有点大，多等等）：

Unity3D 入门：安装 Unity3D 并配置与 Visual Studio 的协作开发环境

Tue, 05 May 2020 07:22:45 +0000

实际上本文不看也罢，因为整个过程除了网速之外基本没啥坑。不过装完可能有一些配置，所以如果不知道的话可以参考本文。

安装

我们共需要安装两款应用：

Visual Studio 2019 及 Unity 编辑器组件
Unity Hub

这两款应用安装不分先后，不过建议全部都安装完后再启动，避免单独启动无法运行使用的问题。

安装 Visual Studio 2019 的 Unity 编辑器组件。

Visual Studio 2019 的安装包自带 Unity 编辑器的安装入口。在你的开始菜单中搜索并打开“Visual Studio Installer”。如果你没有安装 Visual Studio 的话，那么还是建议去下载安装一下的。

启动完 Visual Studio Installer 之后，选择“修改”：

在“单个组件”里面勾选两个：

Unity 64 位编辑器
Visual Studio Tools for Unity

点击右下角的“修改”后就等待。（可能部分运营商的速度会过慢，这时你可能需要考虑梯子。）

安装 Unity Hub

下载安装地址：

Download - Unity

获得授权

如果没有 Unity 的授权，那么你将无法使用 Unity 编辑器，而 Unity 的授权在 Unity Hub 的应用中才能进行（这也是为什么一定要下一个 Unity Hub 的原因）。

启动 Unity Hub。如果你没有许可证的话，那么打开 Unity Hub 的第一个界面就是 Unity Hub 的许可证的授权界面。如果没有打开这个界面，那么点击右上角的设置->许可证管理可以进来。

点击“激活新许可证”，然后按照你自己的需要选择许可证即可。我出于个人学习 Unity 的需要安装的 Unity，所以选择了个人授权。个人授权免费，不过有效期只有一天，过期需要手工再操作一次。

配置 Visual Studio 集成

使用 Visual Studio 解决方案

在 Unity Hub 中新建一个项目，输入名称选择路径，你就可以开始使用 Unity 来制作你的程序了。

新建或打开 Unity 的项目后，会启动 Visual Studio 2019 安装过程中安装的那个 Unity 编辑器。

选择“Edit->Preference…”打开 Unity 的设置。

在设置中，打开 External Tools，然后在 External ScriptEditor 中选择“Browse…”，找到 Visual Studio 2019 的主程序确定，这时，这里就会变成“Visual Studio 2019”。下面是否勾选 Generate all .csproj files 的区别是生成的 Visual Studio 解决方案中是否包含其他所有的项目（后面会介绍）。

Visual Studio 一般在这种地方：

C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE
C:\Program Files (x86)\Microsoft Visual Studio\2019\Professional\Common7\IDE
C:\Program Files (x86)\Microsoft Visual Studio\2019\Enterprise\Common7\IDE

设置完成之后，点击“打开 C# 项目”可以在 Visual Studio 中打开此项目的解决方案，你就可以在里面编写 C# 脚本了。

后话，其实你什么都不配也依然能使用 Visual Studio 完成开发，不过配完后你将获得这些好处：

获得完整的 Visual Studio 项目，可以用 C#/.NET 的语法分析，可以管理项目（否则你只能以单纯的 C# 单个文件编辑代码）；
可以直接在 Visual Studio 中调试 Unity 程序，获得比较完整的 Visual Studio 的调试体验。

如果你在前面勾选了“生成所有的 .csproj 文件”，那么在 Visual Studio 的解决方案中将可以看到所有的 Unity 辅助项目可供编辑。否则只有 Assembly-CSharp 一个项目。

在 Visual Studio 中调试 Unity 程序

正常你可以直接在项目原本的“启动”或“调试”按钮处看到“附加到 Unity”按钮，点击即可调试 Unity 程序。

当然，Unity 编辑器这边也要运行起来才可以在 Visual Studio 里面进入断点：

如果你没有找到“附加到 Unity”按钮，那么可以在 Visual Studio 的“调试”菜单中找到“附加 Unity 调试程序”。点击后可以自动查找当前正在运行的 Unity 编辑器，选择你希望调试的那一个即可开始调试。

安装其他模块（语言/编译平台）

实际上，按照以上步骤全部完成的话，编译和调试 Unity 项目已经没有问题了。如果你是出于学习目的安装的话，本文的操作到此结束。

至此我们的 Unity 项目并不能发布，因为我们没有安装过任何目标平台的编译环境。

请前往 Unity 的更新页面：https://unity3d.com/get-unity/update

因为我们已经安装了 Unity Hub，所以可以选择：

I already have Unity Hub
Install version from Unity Hub

这时会启动 Unity Hub 然后进入更新页面。如果打开了 Unity Hub 但没有进入更新页面，请去任务栏通知区域右键退出 Unity Hub，重新点击上面的那个 Install version from Unity Hub 按钮。于是可以选择安装哪些组件。

随后点击右下角的“安装”以安装新版本并包含需要的编译组件。

当然，如果你已经安装过新版本，那么也可以通过“添加组件”的方式来安装目标平台的编译环境。

完成

至此，Unity 的安装和基本配置已全部完成。

.NET 程序如何获取图片的宽高（框架自带多种方法的不同性能）

Thu, 30 Apr 2020 10:35:49 +0000

获取图片宽高的方法有很多种，本文介绍 .NET 中获取图片宽高的几种方法并评估其性能。如果你打算对大量图片进行一些处理，本文可能有用。

本文即将评估的方法

本文即将采用以下四种方法获取图片：

System.Drawing.Imaging.Metafile
System.Drawing.Bitmap
System.Windows.Media.Imaging.BitmapImage
System.Windows.Media.Imaging.BitmapDecoder

`System.Drawing.Imaging.Metafile`

实际上不要被这个名字误解了，Metafile 并不是“某个图片的元数据”，与之对应的 MetafileHeader 也不是“某个图片的元数据头”。Metafile 是微软 Windows 系统一种图片格式，也就是大家熟悉的 wmf 和 emf，分别是 Windows Metafile 和 Enhanced Metafile。

所以指望直接读取图片元数据头来提升性能的的小伙伴们注意啦，这不是你们要找的方法。

不过为什么这个也能拿出来说，是因为此类也可以读取其他格式的图片。

var header = Metafile.FromFile(@"D:\blog.walterlv.com\large-background-image.jpg");
var witdh = header.Width;
var height = header.Height;

能拿到。

`System.Drawing.Bitmap`

这个实际上是封装的 GDI+ 位图，所以其性能最好也是 GDI+ 的性能，然而都知道 GDI+ 的静态图片性能不错，但比起现代的其他框架来说确实差得多。

var bitmap = new Bitmap(@"D:\blog.walterlv.com\large-background-image.jpg");
var witdh = bitmap.Width;
var height = bitmap.Height;

`System.Windows.Media.Imaging.BitmapImage`

这是 WPF 框架中提供的显示位图的方法，生成的图片可以直接被 WPF 框架显示。

var bitmap = new BitmapImage(new Uri(@"D:\blog.walterlv.com\large-background-image.jpg", UriKind.Absolute));
var witdh = bitmap.Width;
var height = bitmap.Height;

`System.Windows.Media.Imaging.BitmapDecoder`

这也是 WPF 框架中提供的方法，但相比完全加载图片到可以显示的 System.Windows.Media.Imaging.BitmapImage，此方法的性能会好得多。

var decoder = new JpegBitmapDecoder(new Uri(@"D:\blog.walterlv.com\large-background-image.jpg", UriKind.Absolute), BitmapCreateOptions.DelayCreation, BitmapCacheOption.OnDemand);
var frame = decoder.Frames[0];
var witdh = frame.PixelWidth;
var height = frame.PixelHeight;

性能对比

为了测试性能，我使用下面这张非常大的图，同一张图运行多次：

分别运行以上四个方法各 1 次：

分别运行以上四个方法各 10 次：

分别运行以上四个方法各 100 次（可以发现大量的 GC）：

现在，使用不同的图片运行多次。

分别运行以上四个方法各 10 张图片：

分别运行以上四个方法各 100 张图片（可以发现大量的 GC）：

做成图表，对于同一张图片运行不同次数：

消耗时间(ms)	Metafile	Bitmap	BitmapImage	BitmapDecoder
1次	175	107	71	2
10次	1041	1046	63	17
100次	10335	10360	56	122

对于不同图片运行不同次数：

消耗时间(ms)	Metafile	Bitmap	BitmapImage	BitmapDecoder
1次	175	107	71	2
10次	998	980	83	20
100次	10582	10617	255	204
1000次	127023	128627	3456	4015

可以发现，对于 .NET 框架中原生自带的获取图片尺寸的方法来说：

System.Windows.Media.Imaging.BitmapDecoder 的整体性能是最好的
对于同一张图，System.Windows.Media.Imaging.BitmapImage 的运行时间不随次数的增加而增加，其内部有缓存

参考资料

WMF - 维基百科，自由的百科全书

在 CMD 里根据进程名杀掉进程

Thu, 30 Apr 2020 03:31:27 +0000

任务管理器杀进程大家都会，不过如果你的系统被卡到任务管理器都无法操作了，怎么办？拿控制台 CMD 吧！

系列博客：

taskkill 命令

taskkill /f /t /im chrome.exe

/f 表示强制终止进程。如果不指定，那么 taskkill 会给进程发送终止信号，但进程可以阻止退出（例如提示文档需要保存）。指定了，就会强杀进程。

/t 表示结束此进程和其子进程。

/im 用来指定进程的影映像名称（有 .exe 后缀）。

更多使用方法可以直接输入 taskkill /?。

❯ taskkill /?

TASKKILL [/S system [/U username [/P [password]]]]
         { [/FI filter] [/PID processid | /IM imagename] } [/T] [/F]

描述:
    使用该工具按照进程 ID (PID) 或映像名称终止任务。

参数列表:
    /S    system           指定要连接的远程系统。

    /U    [domain\]user    指定应该在哪个用户上下文执行这个命令。

    /P    [password]       为提供的用户上下文指定密码。如果忽略，提示
                           输入。

    /FI   filter           应用筛选器以选择一组任务。
                           允许使用 "*"。例如，映像名称 eq acme*

    /PID  processid        指定要终止的进程的 PID。
                           使用 TaskList 取得 PID。

    /IM   imagename        指定要终止的进程的映像名称。通配符 '*'可用来
                           指定所有任务或映像名称。

    /T                     终止指定的进程和由它启用的子进程。

    /F                     指定强制终止进程。

    /?                     显示帮助消息。

筛选器:
    筛选器名      有效运算符                有效值
    -----------   ---------------           -------------------------
    STATUS        eq, ne                    RUNNING |
                                            NOT RESPONDING | UNKNOWN
    IMAGENAME     eq, ne                    映像名称
    PID           eq, ne, gt, lt, ge, le    PID 值
    SESSION       eq, ne, gt, lt, ge, le    会话编号。
    CPUTIME       eq, ne, gt, lt, ge, le    CPU 时间，格式为
                                            hh:mm:ss。
                                            hh - 时，
                                            mm - 分，ss - 秒
    MEMUSAGE      eq, ne, gt, lt, ge, le    内存使用量，单位为 KB
    USERNAME      eq, ne                    用户名，格式为 [domain\]user
    MODULES       eq, ne                    DLL 名称
    SERVICES      eq, ne                    服务名称
    WINDOWTITLE   eq, ne                    窗口标题

    说明
    ----
    1) 只有在应用筛选器的情况下，/IM 切换才能使用通配符 '*'。
    2) 远程进程总是要强行 (/F) 终止。
    3) 当指定远程机器时，不支持 "WINDOWTITLE" 和 "STATUS" 筛选器。

例如:
    TASKKILL /IM notepad.exe
    TASKKILL /PID 1230 /PID 1241 /PID 1253 /T
    TASKKILL /F /IM cmd.exe /T
    TASKKILL /F /FI "PID ge 1000" /FI "WINDOWTITLE ne untitle*"
    TASKKILL /F /FI "USERNAME eq NT AUTHORITY\SYSTEM" /IM notepad.exe
    TASKKILL /S system /U 域\用户名 /FI "用户名 ne NT*" /IM *
    TASKKILL /S system /U username /P password /FI "IMAGENAME eq note*"

参考资料

how to kill a program by process name using cmd in windows 8? - Stack Overflow

在 PowerShell 里根据进程名杀掉进程

Thu, 30 Apr 2020 03:31:24 +0000

任务管理器杀进程大家都会，不过如果你的系统被卡到任务管理器都无法操作了，怎么办？直接在 PowerShell 中干掉！另外，这也非常容易集成到各种工具链中。

系列博客：

Stop-Process / kill

PowerShell 脚本 Stop-Process 可以用来结束进程。

结束进程名为 chrome 的进程：

Stop-Process -Name chrome

# kill 是 Stop-Process 的简写，ProcessName 是 Name 的别名。
kill -ProcessName chrome

如果除了关闭你正在看的博客，还顺便要把自己正在编写的代码关闭掉，可以传多个进程名：

Stop-Process -Name chrome,code

taskkill 命令

PowerShell 依然能使用 CMD 命令，于是以下命令依旧可以工作：

taskkill /f /t /im chrome.exe

详见：

在 CMD 里根据进程名杀掉进程 - walterlv

其他间接玩法

Process.Kill

Get-Process 能拿到进程对象，于是可以利用管道拿到对象将其关闭：

Get-Process -Name chrome | Stop-Process

更间接一点，遍历所有拿到的 Process 对象，然后杀掉：

Get-Process -Name chrome | Foreach-Object { $_.Kill() }

Linux Shell 中需要转义的字符

Thu, 30 Apr 2020 03:12:46 +0000

本文整理 Linux Shell 中的转义字符。

在 Linux Shell 中，有很多字符是有特殊含义的，如果期望把这个字符当作普通字符来处理，需要经过 \ 的转义。

在双引号中即可变普通字符的特殊字符

` ` *

空格 ‘\ `

这是转义空格。如果路径中包含空格，那么使用 \ 转义可以避免路径被分割成 Shell 的两个参数。

我有另一篇描述 Linux Shell 中路径空格转义相关的博客：

了解 Windows/Linux 下命令行/Shell 启动程序传参的区别，这下不用再担心 Windows 下启动程序传参到 Linux 下挂掉了 - walterlv

星号 ‘*`

如果单独使用 * 将会表示当前路径下枚举的所有文件或文件夹。如果希望保持 * 的原意，那么将其包裹在引号内，或者使用转义 \*。

井号 `#`

表示注释。

换行符

在引号中，也可以直接换行。这样换行符就是字符串的一部分。

即便在引号中也依然被 Shell 解释的特殊字符

" $ ` \

双引号 ‘"’

双引号的作用是避免空格将本来属于同一段参数的字符串分割成两部分。那么如果真的需要双引号的话就需要使用 \ 来转义。

echo "Hello \"Walterlv\""

这样才可以输出：Hello "Walterlv"。

反引号 `

跟引号一样的作用。

在引号中也需要转义。

美元符 `\$`

在 Linux Shell 中，这是变量的引用。例如 ${x} 就是引用 x 变量。

$ echo "上一个程序的返回值为：\$? = $?"
上一个程序的返回值为：$? = 127

在引号中也需要转义。

反斜杠 `\`

因为 \ 是转义字符，所以其本身的使用也必然需要转义。

在引号中也需要转义。

任意字符

任意字符也可以使用 \ 转义，虽然没用，但也是一个特性。

$ echo \H\e\l\l\o\ \"\W\a\l\t\e\r\l\v\"
Hello "Walterlv"

参考资料

了解 Windows/Linux 下命令行/Shell 启动程序传参的区别，这下不用再担心 Windows 下启动程序传参到 Linux 下挂掉了

Thu, 30 Apr 2020 01:54:25 +0000

启动某个程序，再带上一堆参数，这几乎是程序员们每天必做到事情。另外再算上各种辅助程序员们的自动化脚本，辅助构建的 CI（持续集成）等等，程序员们在创造大量的应用程序然后调用它们。

但是，不经常跨系统玩这些的小伙伴们注意了，Windows 下的 Shell 和 Linux 下的 Shell 是有区别的！如果你不了解这些区别，很容易造成在 Windows 下编写的代码/脚本在 Linux 下无法使用的问题。

本文列举 Windows/Linux 下 Shell 的区别。

分号（;）

分号（;）在 Linux 的 Shell 中是不同命令的分割，而在 Windows 中只是一个普通的字符。

例如：

dotnet build;dotnet pack

这在 Linux 中是执行两句不同的命令，dotnet build 和 dotnet pack。而换到 Windows 中，这变成了执行 dotnet 程序，然后传入 build;dotnet pack 这个参数。

相反的：

foo --tags NET48;NETCOREAPP3_1;RELEASE

这在 Windows 下是启动 foo 程序，然后传入 NET48;NETCOREAPP3_1;RELEASE，而在 Linux 下则变成了执行三个不同的命令。后面两个显然不是命令，于是执行时会报 127 错误：Command not found。（程序执行完成退出，返回值为 127。）

如果你希望你的执行脚本跨平台，那么：

不要使用分号 ; 来尝试将两个或多个不同的命令合并成 1 行，直接执行多个命令即可。
如果命令名称或参数中存在分号，则必须使用引号 " 将它包裹起来。

路径空格

Windows 下针对路径中包含空格的情况，用引号包裹路径：

"C:\Program Files\Walterlv\Foo.exe"

Linux 下，如果路径中包含空格，则有三种不同的解决策略：

# 加 \ 转义
/mnt/c/Program\ Files/Walterlv/Foo

# 加双引号
"/mnt/c/Program Files/Walterlv/Foo"

# 加单引号
'/mnt/c/Program Files/Walterlv/Foo'

可以发现，两者都有的方案是加双引号。所以，如果希望你的命令脚本跨平台使用，则应该使用双引号包裹路径。

路径分隔符

Windows 下，\ 和 / 都是路径分隔符。Linux 下，只有 / 是路径分隔符，\ 是合理的文件名，在 Shell 中，\ 是转义字符。

虽然理论上所有路径都使用 / 可以让你的跨平台脚本在以上所有系统中正常工作，但考虑到 Windows 可能有一些逗比程序对 / 支持不好，更建议：

在所有场景下生成路径字符串时使用当前平台的路径分隔符
不要将某平台生成的路径分隔符直接拿到另一平台使用

关于跨平台路径分隔符的问题，我专门写了一篇博客，在那里可以了解更多：

.NET 将混合了多个不同平台（Windows / Mac / Linux）的文件/目录的路径格式化成同一个平台下的路径 - walterlv

其他特殊字符（ `(` `$` `{` `*` `#` ）

在 Linux 的 Shell 中，有很多字符有特殊用途，而在 Windows Shell 中，这些字符的作用完全由被调用的应用程序来决定。

所以对于跨平台的脚本，最好尽量避免使用这些字符。

关于 Linux 下这些转义字符的用途，可以阅读我的另一篇博客：

Linux Shell 中的所有需要转义的字符 - walterlv

git 乱改你的换行符？一句话设置让 git 不再碰你某个文件的换行符

Thu, 30 Apr 2020 01:26:38 +0000

前些天有位小伙伴告诉我说 git 改了某个重要文件的换行符，导致文件的哈希变了，于是文件校验出现错误。之前一直没问题而最近才有问题是因为最近换了部署服务器，git 的换行符配置不一样。

其实，我们不应该让代码仓库如此容易受到外界环境的影响。所以本文会解释 git 的全局配置如何影响了 git 对换行符的处理，然后说说如何彻底解决这个问题。

关于换行符

\r = CR = Carriage-Return = 回车
\n = LF = Line-Feed = 换行
\r\n = CRLF = Carriage-Return Line-Feed = 回车换行

Windows 下默认的文本换行符是 \r\n，Linux 下默认的换行符是 \n，Mac 下默认的换行符是 \r。因为这些差异，如果某部分文本文件会跨操作系统处理，那么换行符的处理就必须考虑了。git 允许开发者设置如何处理换行符在跨平台上的处理方式，不过不合适的设置可能带来文件发生不期望的修改。

问题

问题本身在本文一开始已经说得比较清楚了，现在疏理一下：

有个文本文件，被 git 改了换行符，导致哈希变化，文件校验出现了错误；
部署服务器以前 git 全局配置和现在不同，所以以前没问题，现在出了问题。

解决

当时，林德熙小伙伴是负责部署服务器配置的，看到出事了立刻想到去服务器把配置改“正确”。

然而我阻止了。因为现在因为换服务器出问题，将来也会因为换服务器出问题，更普遍的，换任何环境都可能出问题。所以这问题应该从仓库着手，避免此文件被修改换行符。

于是我和小伙伴结对打开了 .gitattribute 文件，在末尾加了一行：

    *.bmp       binary
    *.jpg       binary
++  *.inf       binary

这样，*.inf 文件会被 git 视为二进制文件，也就不会处理换行符了。

当然，因为项目很小，所以直接改了位于项目根目录的 .gitattribute 文件。如果项目比较大，那么建议考虑在那个 .inf 文件所在的文件夹新建一个 .gitignore 文件，避免全局的设置对可能不需要生效的文件也起了作用。

原因

git 有个全局配置，在 %USERPROFILE%\.gitconfig 文件里面，可以指定如何处理文本文件的换行符：

[core]
	autocrlf = true

有三个可选值：

true
false
input

在 Windows 系统上：

true 表示在推送时转成 \n，在拉取时转成 \r\n。这样的设置让 Windows 的开发者能兼容很多的开发工具（比如早期的记事本，新的已经支持 \r\n 了），不至于遇到很多换行符问题。
false 表示在推送时和拉取时都原样保留换行符。这样的设置在所有程序员都在同一个平台开发时很有用，git 完全不处理换行符，全部改由开发者自行解决。
input 表示在推送时转成 \n，在拉取时原样保留换行符。注意到，这样的设置会让仓库里所有的换行符都变成 \n 不再有什么时候有 \r\n 了，所以对 Windows 平台的开发者并不友好。

以前的服务器全局配置没有问题，是因为服务器配置为 true，于是拉下来时一定都是 \r\n 哈希正确。而现在全局配置是 false，于是会原样把 git 仓库里的拉下来，哈希错误。

是的，你没看错！远程 git 仓库里的是错的！这是因为有小伙伴使用了 true 或者 input 的配置，导致推送时统一把换行符改成了 \r\n。

.NET 将混合了多个不同平台（Windows / Mac / Linux）的文件/目录的路径格式化成同一个平台下的路径

Thu, 30 Apr 2020 01:24:04 +0000

Windows 下的路径分隔符是 \ 而 Linux 和 Mac 下的路径分隔符是 \。正常如果你的数据不跨 Windows 和 Linux 平台流通的话，不怎么会遇到多种换行符并存的问题的。但如果真发生了流通，那么如何将它们格式化为统一的当前平台认识的分隔符呢？

现有方案

没有原生方案（.NET）

System.IO.Path 带了一堆方法用来处理路径。各大文档博客和书籍也都推荐大家使用 Path 来处理路径字符串的拼接、拆分和提取等，这可以很大程度避免不同遭遇不同平台下路径分隔字符串不一致导致的各种问题。

不过，本文想告诉大家的是，Path 处理路径字符串也不是万能的，这体现在处理跨操作系统的路径字符串时。

现在，我列举了 6 个不同的路径字符串：

var part0 = @"/mnt/d/walterlv/";
var part1 = @"D:\walterlv\";

var part2 = @"Foo/Bar.cs";
var part3 = @"Foo\Bar.cs";

var part4 = @"/mnt/d/walterlv/Foo/Bar.cs";
var part5 = @"D:\walterlv\Foo\Bar.cs";

分成三组。前两个是路径的前半部分，中间两个是路径的后半部分，最后两个是完整路径。每组里面，前者是 Linux 风格的路径分隔符，后者是 Windows 风格的路径分隔符。

现在，我将试图将以下几种混合情况下的路径拼接使用 Path 可能格式化的方法输出出来：

// 看看 Linux 风格和 Windows 风格直接拼接的换行符使用 Path.Combine 能否格式化成功。
var pathFromCombine0 = Path.Combine(part0, part3);
var pathFromCombine1 = Path.Combine(part1, part2);
Console.WriteLine($"Path.Combine(part0, part3) = {pathFromCombine0}");
Console.WriteLine($"Path.Combine(part1, part2) = {pathFromCombine0}");

// 通过 Path.GetFullPath 转相对路径到完整路径时，看看能否将路径格式化成当前平台。
var pathFromFull0 = Path.GetFullPath(part2);
var pathFromFull1 = Path.GetFullPath(part3);
Console.WriteLine($"Path.GetFullPath(part2) = {pathFromFull0}");
Console.WriteLine($"Path.GetFullPath(part3) = {pathFromFull1}");

// 通过 new FileInfo(file).FullName 的一层转换看看能否将混合路径格式化成当前平台。
var pathFromFileInfo0 = new FileInfo(pathFromCombine0).FullName;
var pathFromFileInfo1 = new FileInfo(pathFromCombine1).FullName;
Console.WriteLine($"FileInfo(part0 + part3).FullName = {pathFromFileInfo0}");
Console.WriteLine($"FileInfo(part1 + part2).FullName = {pathFromFileInfo1}");

// 通过 new FileInfo(file).FullName 的一层转换看看能否将非当前平台的路径格式化成当前平台。
var pathFromFileInfo2 = new FileInfo(part4).FullName;
var pathFromFileInfo3 = new FileInfo(part5).FullName;
Console.WriteLine($"Path.GetFullPath(part4) = {pathFromFileInfo2}");
Console.WriteLine($"Path.GetFullPath(part5) = {pathFromFileInfo3}");

猜猜以上代码在 Windows 和 Linux 平台会输出什么？

看图！

图是拼接的，上面一半是 Windows 平台下的运行结果，下面一半是 Linux Ubuntu 18.04 发行版的运行结果。运行时是 .NET Core 3.1。

可以发现这些点：

Path.Combine 的路径拼接仅决定如何合并两段字符串，不会将已有的路径格式化成当前平台的路径分隔符。
Path.GetFullPath 在生成完整路径的时候，虽然补全的部分是当前平台的，但已有的部分依然是原本字符串。
new FileInfo().FullName 在 Windows 平台下可以完美将路径字符串统一成 Windows 平台的风格；但在 Linux 平台上不会统一，已有的 \ 不会变成 /；无论是拼接的字符串，还是原本别的平台的字符串，都是一样的结论。

为什么 .NET 原生不做统一化？

看前面结论可知，在 Windows 平台下是可以将 / 和 \ 全部格式化成 Windows 平台的 \ 的，但 Linux 下却不行。

这并不是因为 .NET 没去做，而是无法做！

在 Linux 下，\ 是合理的文件名！

另外，路径经常使用在 Shell 中，而在 Shell 中，\ 是个转义字符！

例如，你可以有一个文件，名字是 foo\bar.txt。

所以，.NET 绝对不能擅自给你将 \ 当作路径分隔符进行格式化！

关于 \ 在 Linux Shell 中的转义，你可以阅读我的另外两篇博客了解：

了解 Windows/Linux 下命令行/Shell 启动程序传参的区别，这下不用再担心 Windows 下启动程序传参到 Linux 下挂掉了 - walterlv

自己实现

知道了 Linux 是合理的文件名后，当然不能再指望有某个通用的解决方法了。因为通用代码不可能知道在你的上下文下，\ 是否是合理的文件名。在信息不足的情况下，前面 .NET 的 new FileInfo().FullName 已经是最好的解决方案了。

所以，如果你明确这些不同种类的路径字符串的来源你都清楚（没错，就是你自己挖出来的坑），拼接出来之后的后果你才能知道是否是符合业务的。这时你才应该决定是否真的要做路径的格式化。

简单省事型

var path = path
    .Replace('/', Path.DirectorySeparatorChar)
    .Replace('\\', Path.DirectorySeparatorChar);

高性能型

自己实现去。

如何避免

从前面的分析可以知道，如果每个框架、库还有业务开发者都不去作死把平台特定的路径传递到其他平台，那么根本就不会存在不同平台的路径会拼接的情况。

另外，开发者也不应该随便在代码中写死 / 或者 \\ 作为路径的分隔符。

就这样……

参考资料

How to enable linux support double backslashes “\” as the path delimiter - Stack Overflow

如何在 Windows 10 中安装 WSL2 的 Linux 子系统

Tue, 28 Apr 2020 12:26:41 +0000

本文介绍如何在 Windows 10 中安装 WSL2 的 Linux 子系统

第一步：启用虚拟机平台和 Linux 子系统功能

以管理员权限启动 PowerShell，然后输入以下命令启用虚拟机平台：

Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform

以管理员权限启动 PowerShell，然后输入以下命令启用 Linux 子系统功能：

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

在以上每一步命令执行完之后，PowerShell 中可能会提示你重新启动计算机。按“Y”可以重新启动。

当然，这个命令跟你在控制面板中启用“适用于 Windows 的 Linux 子系统”功能是一样的。

第二步：安装一个 Linux 发行版

打开微软商店应用，在搜索框中输入“Linux”然后搜索，你可以看到搜索结果中有很多的 Linux 发行版可以选择。选择一个你喜欢的 Linux 发行版本然后安装：

选择一个 Linux 发行版本然后安装：

需要注意，在商店中的安装并没有实际上完成 Linux 子系统的安装，你还需要运行一次已安装的 Linux 发行版以执行真正的安装操作。

第三步：启用 WSL2

重要：你的操作系统版本必须至少大于或等于 Windows 10.0.18917 ！

使用 wsl -l 可以列出当前系统上已经安装的 Linux 子系统名称。注意这里的 -l 是列表“list”的缩写，是字母 l 不是其他字符。

wsl -l

如果提示 wsl 不是内部或外部命令，说明你没有启用“适用于 Windows 的 Linux 子系统”，请先完成本文第一步。

如果提示没有发现任何已安装的 Linux，说明你没有安装 Linux 发行版，或者只是去商店下载了，没有运行它执行真正的安装，请先完成本文第二步。

使用 wsl --set-version <Distro> 2 命令可以设置一个 Linux 发行版的 WSL 版本。命令中 <Distro> 替换为你安装的 Linux 发型版本的名称，也就是前面通过 wsl -l 查询到的名称。

本文的示例使用的是小白门喜欢的 Ubuntu 发行版。

wsl --set-version Ubuntu 2

当然，使用以下命令可以在以后安装 Linux 的时候默认启用 WSL2：

wsl --set-default-version 2

参考资料

Install WSL 2 - Microsoft Docs

Unity3D 入门：在 Visual Studio 里使用 Visual Studio Tools for Unity 全套工具

Mon, 27 Apr 2020 13:06:05 +0000

Visual Studio 安装过程中一起勾选的 Visual Studio Tools for Unity 提供了与 Unity 编辑器方便的交互功能，充分使用 Visual Studio Tools for Unity 可以提升一部分开发效率减少一点点坑。

Visual Studio Tools for Unity

我在 Unity3D 入门：安装 Unity3D 并配置与 Visual Studio 的协作开发环境 - walterlv 一文中提及了在安装 Unity 的开发环境时建议勾选了 Visual Studio Tools for Unity。

如果你还没安装，可以阅读此博客安装。如果安装后没有设置 Unity 编辑器的关联，也可以阅读这篇博客了解如何设置关联。

快速实现 Unity 消息

在 MonoBehaviour 的类中输入 onXXX 可以在智能感知列表中看到 Unity 在游戏运行时给每个游戏对象广播的消息，直接回车输入可以插入这个方法。于是，你可以无需记忆所有的这些消息就可以在不同的消息中添加处理函数。

或者，你也可以在类中按下 Ctrl+Shift+M 打开“实现 Unity 消息”对话框，通过勾选插入一堆处理函数。

Unity 项目资源管理器

我们在 Unity 编辑器中查看 Unity 项目的文件结构与 Visual Studio 解决方案资源管理器中看到的是完全不同的。实际上，Visual Studio 中的项目和解决方案对 Unity 资产来说是没有意义的，有用的其实是里面的 C# 脚本。

于是就有了“Unity 项目资源管理器”的需要，它可以以跟 Unity 编辑器相同的视角看 Unity 项目中的资产。

附加到 Unity 调试

在安装了 Visual Studio Tools for Unity 后，打开 Unity 的项目你将看到平常的“调试”按钮变成了“附加到 Unity”按钮。

在 Unity 编辑器也运行起来的情况下，可以在 Visual Studio 里面进入断点调试。

当然，如果觉得每次都要单独去点“Play”比较麻烦的话，可以在调试按钮上下拉选择“附加到 Unity 并播放”。这样每次点击按钮的时候就直接会开始运行游戏了。

参考资料

Getting Started with Visual Studio Tools for Unity - Visual Studio - Microsoft Docs

Unity3D 入门：使用 Visual Studio 开发 Unity C# 脚本，说说根目录的那些 sln 和 csproj 文件

Mon, 27 Apr 2020 13:04:09 +0000

本文介绍 Unity3D 项目根目录的 sln 和 csproj 文件，你将知道如何正确理解和使用它们。

等等！那我们在根目录看到的那些 sln 和 csproj 文件是什么？

那只是 Unity 编辑器为了让你方便写 C# 代码临时生成给你用的。

默认 Unity 不指定外部脚本编辑器时，会单纯打开 .cs 文件而已。而如果指定了 Visual Studio 作为外部脚本编辑器，那么再从 Unity 中打开 C# 项目时，将会生成 sln 和 csproj 文件，然后调用 Visual Studio 打开生成的 sln 和 csproj 文件。

这里就需要特别注意了：每次点击 Open C# Project 打开 C# 项目时，都会重新生成 sln 和 csproj 文件，所以实际上你对 sln 和 csproj 所做的任何改动都是无效的！

这样的设计，有好处也有坏处：

有了 sln 和 csproj，Visual Studio 将能充分运行代码分析器，可以在类与其他符号之间跳转，可以有智能感知提示，可以实时发现编写中的代码错误（甚至是引用错误）。
但让 Visual Studio 的各种功能激活后就会让我们这样的入门开发者产生误会，认为这其实就是 C# 项目，会尝试真的对这些项目进行可能超出 Unity 功能范围的修改。

真正在编译完成放到游戏中运行的，是 Assets 文件夹中的文件。而外面的 sln 和 csproj 文件，应该加入到 .gitignore 文件中，从版本管理中忽略掉。

让你的程序置顶到比系统界面都更上层，就像任务管理器/放大镜一样绝对置顶

Sat, 25 Apr 2020 03:50:18 +0000

启动系统自带的放大镜程序，我们会发现即便进了 Windows 8 的开始屏幕，或打开了 Windows 10 的开始菜单和消息中心，它也依然显示在最顶层。如果你为任务管理器开启置顶效果，你会发现它也能显示到开始屏幕的顶层。这是怎么做到的呢？

顺便解释下“桌面应用程序”，指的是传统 Win32 应用程序。解释下“Windows 应用”，指的是开始屏幕/开始菜单/UAP/UWP 甚至是锁屏界面这些。

方法

做到这些，需要四个步骤，缺一不可：

第一步：修改 Manifest

前往你程序的 App.Manifest 文件，设置 requestedExecutionLevel。

<requestedExecutionLevel level="asInvoker" uiAccess="true" />

第二步：修改窗口属性

这两个属性是必须设置的，否则无法达到目的。

ShowInTaskbar=true
TopMost=true

第三步：为程序签名

参见此处 - 为程序签名

第四步：将程序放到受信任的目录下

C:\program files
C:\program files x86
C:\Windows\system32

可能遇到的问题

从服务器返回了一个参照

A referral was returned from the server.

感谢胡承提供的错误和解决方法！

你可能会在按照以上步骤操作后，在执行程序时遇到这样的错误，解决方法是“以管理员权限启动此程序”。

参考资料

How to make Windows 8 desktop apps shown in Metro UI (like Task Manager)?
https://stackoverflow.com/questions/12873323/how-to-make-windows-8-desktop-apps-shown-in-metro-ui-like-task-manager

Code Signing Notes
http://techsupt.winbatch.com/webcgi/webbatch.exe?techsupt/nftechsupt.web+WinBatch/Manifest+Manifest~Faqs.txt

UIAccess in Manifest Files
https://social.msdn.microsoft.com/Forums/windowsdesktop/en-US/4d2e1358-af95-4f4f-b239-68ec7e2525a9/uiaccess-in-manifest-files

Debug Applications with uiAccess Set to “True”
http://blogs.techsmith.com/inside-techsmith/devcorner-debug-uiaccess/

Debugging with uiAccess=true
https://social.msdn.microsoft.com/forums/windowsdesktop/en-us/7a42efab-5ce8-456f-8a58-dfedbc2cefcb/debugging-with-uiaccesstrue

C# 可空引用类型 Nullable 更强制的约束：将警告改为错误 WarningsAsErrors

Thu, 23 Apr 2020 12:17:50 +0000

程序员不看警告！

于是 C# 8.0 带来的可空引用类型由于默认以警告的形式出现，所以实际上约束力非常弱。

本文将把 C# 8.0 的可空引用类型警告提升为错误，以提高约束力。

启用可空引用类型

你需要先在你的项目中启用可空引用类型的支持，才能修改警告到错误：

C# 8.0 如何在项目中开启可空引用类型的支持 - 吕毅

项目属性

在项目属性中设置是比较快捷直观的方法。

在项目上右键属性，打开“生成”标签。

在这里，可以看到“将警告视为错误”一栏：

无
所有
特定警告

可以看到默认选中的是“特定警告”且值是 NU1605。

NU 是 NuGet 中发生的错误或者警告的前缀，NU1605 是大家可能平时经常见到的一个编译错误“检测到包降级”。关于这个错误的信息可以阅读官网：NuGet Warning NU1605 - Microsoft Docs，本文不需要说明。

于是，我们将我们需要视为错误的错误代码补充到后面就可以，以分号分隔。

NU1605;CS8600;CS8602;CS8603;CS8604;CS8618;CS8625

这些值的含义可以参考我的另一篇博客：

C# 8.0 可空引用类型中的各项警告和错误 - 吕毅

记得在改之前，把前面的配置从“活动”改为“所有配置”，这样你就不用改完之后仅在 Debug 生效，完了还要去 Release 配置再改一遍。

WarningsAsErrors

前面使用属性面板指定时，有一个奇怪的默认值。实际上我们直接修改将固化这个默认值，这不利于将来项目跟随 Sdk 或者 NuGet 包的升级。

所以，最好我们能直接修改到项目文件，以便更精细地控制这个属性的值。

在上一节界面中设置实际上是生成了一个属性 WarningsAsErrors。那么我们现在修改 WarningsAsErrors 属性的值，使其拼接之前的值：

    <Project Sdk="Microsoft.NET.Sdk">

      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>netcoreapp3.0</TargetFramework>
        <LangVersion>latest</LangVersion>
        <Nullable>enable</Nullable>
++      <WarningsAsErrors>$(WarningsAsErrors);CS8600;CS8601;CS8602;CS8603;CS8604;CS8609;CS8610;CS8614;CS8616;CS8618;CS8619;CS8622;CS8625</WarningsAsErrors>
      </PropertyGroup>

    </Project>

这句话的含义是先获取之前的值，将其放到我们要设置的值的前面。这样可以跟随 Sdk 或者 NuGet 包的升级而更新此默认值。

这些值的含义可以参考我的另一篇博客：

C# 8.0 可空引用类型中的各项警告和错误 - 吕毅

参考资料

C# 8.0 如何在项目中开启可空引用类型的支持

Thu, 23 Apr 2020 12:17:25 +0000

C# 8.0 引入了可为空引用类型和不可为空引用类型。由于这是语法级别的支持，所以比传统的契约式编程具有更强的约束力。更容易帮助我们消灭 null 异常。

本文将介绍如何在项目中开启 C# 8.0 的可空引用类型的支持。

使用 Sdk 风格的项目文件

如果你还在使用旧的项目文件，请先升级成 Sdk 风格的项目文件：将 WPF、UWP 以及其他各种类型的旧 csproj 迁移成 Sdk 风格的 csproj - 吕毅。

本文会示例一个项目文件。

由于现在 C# 8.0 还没有正式发布，所以如果要启用 C# 8.0 的语法支持，需要在项目文件中设置 LangVersion 属性为 8.0 而不能指定为 latest 等正式版本才能使用的值。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.0</TargetFramework>
    <LangVersion>8.0</LangVersion>
  </PropertyGroup>

</Project>

在项目文件中开启可空引用类型的支持

在项目属性中添加一个属性 NullableContextOptions：

    <Project Sdk="Microsoft.NET.Sdk">

      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>netcoreapp3.0</TargetFramework>
        <LangVersion>latest</LangVersion>
++      <Nullable>enable</Nullable>
      </PropertyGroup>

    </Project>

此属性可被指定为以下四个值之一：

enable
- 所有引用类型均被视为不可为空，启用所有 null 相关的警告。
warnings
- 不会判定类型是否可空或不可为空，但启用局部范围内的 null 相关的警告。
annotations
- 所有引用类型均被视为不可为空，但关闭 null 相关的警告。
disable
- 与 8.0 之前的 C# 行为相同，即既不认为类型不可为空，也不启用 null 相关的警告。

这五个值其实是两个不同维度的设置排列组合之后的结果：

可为空注释上下文
- 用于告知编译器是否要识别一个类型的引用可为空或者不可为空。
可为空警告上下文
- 用于告知编译器是否要启用 null 相关的警告，以及警告的级别。

当仅仅启用警告上下文而不开启可为空注释上下文，那么编译器将仅仅识别局部变量中明显可以判定出对 null 解引用的代码，而不会对包括变量或者参数定义部分进行分析。

将警告视为错误

以上只是警告，如果你希望更严格地执行可空引用的建议，可以考虑使用编译错误：

    <Project Sdk="Microsoft.NET.Sdk">

      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>netcoreapp3.0</TargetFramework>
++      <LangVersion>latest</LangVersion>
++      <Nullable>enable</Nullable>
++      <WarningsAsErrors>$(WarningsAsErrors);CS8600;CS8601;CS8602;CS8603;CS8604;CS8609;CS8610;CS8614;CS8616;CS8618;CS8619;CS8622;CS8625</WarningsAsErrors>
      </PropertyGroup>

    </Project>

详见：

可为空注释（Annotation）上下文

当启动可为空注释上下文后，C# 编译器会将所有的类型引用变量识别为以下种类：

不可为空
可为空
未知

于是，当你写出 string walterlv 的变量定义，那么 walterlv 就是不可为空的引用类型；当写出 string? walterlv 的变量定义，那么 walterlv 就是可为空的引用类型。

对于类型参数来说，可能不能确定是否是可空引用类型，那么将视为“未知”。

当关闭可为空注释上下文后，C# 编译器会将所有类型引用变量识别为以下种类：

无视

于是，无论你使用什么方式顶一个一个引用类型的变量，C# 编译器都不会判定这到底是不是一个可为空还是不可为空的引用类型。

可为空警告上下文

例如以下代码：

string walterlv = null;
var value = walterlv.ToString();

在将 null 赋值给 walterlv 变量时，是不会引发程序异常的；而在后面调用了 ToString() 方法则会引发程序异常。

安全性区别就在这里。安全性警告仅会将编译期间可识别到可能运行时异常的代码进行警告（即下面的 walterlv.ToString()），而不会对没有异常的代码进行警告。如果是 enable，那么将 null 赋值给 walterlv 变量的那一句也会警告。

在源代码文件中开启可空引用类型的支持

除了在项目文件中全局开启可空引用类型的支持，也可以在 C# 源代码文件中覆盖全局的设定。

#nullable enable: 在源代码中启用可空引用类型并给出警告。
#nullable disable: 在源代码中禁用可空引用类型并关闭警告。
#nullable restore: 还原这段代码中可空引用类型和可空警告。
#nullable disable warnings: 在源代码中禁用可空警告。
#nullable enable warnings: 在源代码中启用可空警告。
#nullable restore warnings: 还原这段代码中可空警告。
#nullable disable annotations: 在源代码中禁用可空引用类型。
#nullable enable annotations: 在源代码中启用用可空引用类型。
#nullable restore annotations: 还原这段代码中可空引用类型。

早期版本的属性

在接近正式版的时候，开关才是 Nullable，而之前是 NullableContextOptions，但在 Visual Studio 2019 Preview 2 之前，则是 NullableReferenceTypes。现在，这些旧的属性已经废弃。

ReSharper 支持

ReSharper 从 2019.1.1 版本开始支持 C# 8.0，如果使用早期版本，就会到处报错。

但是，由于 C# 8.0 可空引用类型的特性总在变，所以建议使用 2019.2.3 或以上版本，这是 C# 8.0 正式版本发布之后的 ReSharper。

参考资料

C# 8.0 可空引用类型中的各项警告/错误的含义和示例代码

Thu, 23 Apr 2020 12:16:44 +0000

C# 8.0 引入了可为空引用类型和不可为空引用类型。当你需要给你或者团队更严格的要求时，可能需要定义这部分的警告和错误级别。

本文将介绍 C# 可空引用类型部分的警告和错误提示，便于进行个人项目或者团队项目的配置。

开启可空引用类型以及配置警告和错误

本文的内容本身没什么意义，但如果你试图进行一些团队配置，那么本文的示例可能能带来一些帮助。

警告和错误

`CS8600`

将 null 文本或可能的 null 值转换为非 null 类型。

string walterlv = null;

`CS8601`

可能的 null 引用赋值。

string Text { get; set; }

void Foo(string? text)
{
    // 将可能为 null 的文本向不可为 null 的类型赋值。
    Text = text;
}

`CS8602`

null 引用可能的取消引用。

// 当编译器判定 walterlv 可能为 null 时才会有此警告。
var value = walterlv.ToString();

`CS8603`

可能的 null 引用返回。

string Foo()
{
    return null;
}

`CS8604`

将可能为 null 的引用作为参数传递到不可为 null 的方法中：

void Foo()
{
    string text = GetText();;
    Bar(text);
}

string? GetText()
{
    return null;
}

`CS8609`

返回类型中引用类型的为 Null 性与重写成员不匹配。

比如你的基类中返回值不允许为 null，但是实现中返回值却允许为 null。

protected virtual async Task<string> FooAsync()
{
}

protected override async Task<string?> FooAsync()
{
}

`CS8610`

参数中引用类型的为 Null 性与重写成员不匹配。

比如你的基类中方法参数值不允许为 null，但是实现中方法参数却允许为 null。

protected virtual void FooAsync(string value)
{
}

protected override void FooAsync(string? value)
{
}

`CS8614`

接口中定义的成员中的 null 性与实现中成员的 null 型不匹配。

具体来说，你的接口中允许为 null，但是实现中却不允许为 null。

`CS8616`

接口中定义的成员中的 null 性与实现中成员的 null 型不匹配。

具体来说，你的接口中不允许为 null，但是实现中却允许为 null。

`CS8618`

未初始化不可以为 null 的字段 “_walterlv”。

如果一个类型中存在不可以为 null 的字段，那么需要在构造函数中初始化，如果没有初始化，则会发出警告或者异常。

`CS8619`

一个类型与构造这个类型的 null 性不匹配。

例如：

Task<object?> foo = new Task<object>(() => new object());

`CS8622`

委托定义的参数中引用类型的为 null 性与目标委托不匹配。

比如你定义了一个委托：

void Foo(object? sender, EventArgs e);

然而在订阅事件的时候，使用的函数 null 性不匹配，则会出现警告：

void OnFoo(object sender, EventArgs e)
{
    // 注意到这里的 object 本应该写作 object?
}

`CS8625`

无法将 null 文本转换为非 null 引用或无约束类型参数。

void Foo(string walterlv = null)
{
}

`CS8653`

对于泛型 T，使用 default 设置其值。如果 T 是引用类型，那么 default 就会将这个泛型类型赋值为 null。然而并没有将泛型 T 的使用写为 T?。

git subtree 的使用

Fri, 17 Apr 2020 07:01:24 +0000

本文收集 git subtree 的使用。

将 B 仓库添加为 A 仓库的一个子目录

在 A 仓库的根目录输入命令：

$ git subtree add --prefix=SubFolder/B https://github.com/walterlv/walterlv.git master

这样，B 仓库的整体，会被作为 A 仓库中一个 SubFolder/B 的子文件夹，同时保留 B 仓库中的整个日志记录。

从 A 仓库中分离出一个子文件夹成为 B 仓库

在 A 仓库的根目录输入命令：

git subtree split --prefix=SubFolder/B -b b-branch

这样，SubFolder/B 文件夹便会被分离到新创建的 b-branch 分支。随后，如果你需要将分离的子文件夹推送到新仓库的话，直接将这个分支推送过去就可以了。

将 A 仓库中的 B 子目录推送回 B 仓库

$ git subtree push --prefix=SubFolder/B https://github.com/walterlv/walterlv.git master

当然，如果你经常需要使用 subtree 命令，还是建议将那个远端设置一个别名，例如设置 walterlv：

$ git remote add walterlv https://github.com/walterlv/walterlv.git

那么，上面的命令可以简单一点：

$ git subtree push --prefix=SubFolder/B walterlv master

后面，我们命令都会使用新的远端名称。

将 B 仓库中的新内容拉回 A 仓库的子目录

$ git subtree pull --prefix=SubFolder/B walterlv master

通过子类化窗口（SubClass）来为现有的某个窗口添加新的窗口处理程序（或者叫钩子，Hook）

Tue, 14 Apr 2020 00:19:29 +0000

创建窗口的时候，可以传一个消息处理函数。然而如果窗口不是自己创建的，还能增加消息处理函数吗？答案是可以的，除了 SetWindowsHookEx 来添加钩子之外，更推荐用子类化的方式来添加。

本文介绍如何通过子类化（SubClass）的方式来为窗口添加额外的消息处理函数。

子类化

子类化的本质是通过 SetWindowLong 传入 GWL_WNDPROC 参数。

SetWindowLong 的 API 如下：

LONG SetWindowLongA(
  HWND hWnd,
  int  nIndex,
  LONG dwNewLong
);

nIndex 指定为 GWL_WNDPROC，在此情况下，后面的 dwNewLong 就可以指定为一个函数指针，返回值就是原始的消息处理函数。

对于 .NET/C# 来说，我们需要拿到窗口句柄，拿到一个消息处理函数的指针。

窗口句柄在不同的 UI 框架拿的方法不同，WPF 是通过 HwndSource 或者 WindowInteropHelper 来拿。而将委托转换成函数指针则可通过 Marshal.GetFunctionPointerForDelegate 来转换。

你可别吐槽 WPF 另有它法来加消息处理函数啊！本文说的是 Win32，方法需要具有普适性。特别是那种你只能拿到一个窗口句柄，其他啥也不知道的窗口。

var hWnd = new WindowInteropHelper(this).EnsureHandle();
var wndProc = Marshal.GetFunctionPointerForDelegate<WndProc>(OnWndProc);
_originalWndProc = SetWindowLongPtr(hWnd, GWL_WNDPROC, wndProc);

IntPtr OnWndProc(IntPtr hWnd, uint msg, IntPtr wParam, IntPtr lParam)
{
    // 在这里处理消息。
}

将完整的代码贴下来，大约是这样：

public partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent();
        SourceInitialized += MainWindow_SourceInitialized;
    }

    private void MainWindow_SourceInitialized(object sender, EventArgs e)
    {
        var hWnd = new WindowInteropHelper(this).EnsureHandle();
        _wndProc = OnWndProc;
        var wndProc = Marshal.GetFunctionPointerForDelegate<WndProc>(_wndProc);
        _originalWndProc = SetWindowLongPtr(hWnd, GWL_WNDPROC, wndProc);
    }

    private WndProc _wndProc;
    private IntPtr _originalWndProc;

    private IntPtr OnWndProc(IntPtr hWnd, uint msg, IntPtr wParam, IntPtr lParam)
    {
        switch (msg)
        {
            case WM_NCHITTEST:
                return CallWindowProc(_originalWndProc, hWnd, msg, wParam, lParam);
            default:
                return CallWindowProc(_originalWndProc, hWnd, msg, wParam, lParam);
        }
    }
}

其中，我将委托存成了一个字段，这样可以避免 GC 回收掉这个委托对象造成崩溃。

在示例的消息处理函数中，我示例处理了一下 WM_NCHITTEST（虽然依然什么都没做）。最后，必须调用 CallWindowProc 以调用此前原来的那个消息处理函数。

最后，如果你又不希望处理这个消息了，那么使用以下方法注销掉这个委托：

// 嗯，没错，就是前面更换消息处理函数时返回的那个指针。
SetWindowLongPtr(hWnd, GWL_WNDPROC, _originalWndProc);

上面需要的所有的 P/Invoke 我都贴到了下面，需要的话放到你的代码当中。

private static IntPtr SetWindowLongPtr(IntPtr hWnd, int nIndex, IntPtr dwNewLong)
{
    if (IntPtr.Size == 8)
    {
        return SetWindowLongPtr64(hWnd, nIndex, dwNewLong);
    }
    else
    {
        return new IntPtr(SetWindowLong32(hWnd, nIndex, dwNewLong.ToInt32()));
    }
}

[DllImport("user32.dll", EntryPoint = "SetWindowLong")]
private static extern int SetWindowLong32(IntPtr hWnd, int nIndex, int dwNewLong);

[DllImport("user32.dll", EntryPoint = "SetWindowLongPtr")]
private static extern IntPtr SetWindowLongPtr64(IntPtr hWnd, int nIndex, IntPtr dwNewLong);

[DllImport("user32.dll")]
static extern IntPtr CallWindowProc(IntPtr lpPrevWndFunc, IntPtr hWnd, uint Msg, IntPtr wParam, IntPtr lParam);

private delegate IntPtr WndProc(IntPtr hWnd, uint msg, IntPtr wParam, IntPtr lParam);

private const int GWL_WNDPROC = -4;
private const int WM_NCHITTEST = 0x0084;
private const int HTTRANSPARENT = -1;

其他方法

本文一开始说到了使用 SetWindowsHookEx 的方式来添加钩子，具体你可以阅读我的另一篇博客来了解如何实现：

.NET/C# 使用 SetWindowsHookEx 监听鼠标或键盘消息以及此方法的坑 - walterlv

参考资料

Using Window Procedures - Win32 apps - Microsoft Docs

当无边框窗口被子窗口遮挡导致难以调节窗口大小时，可通过处理 NCHITTEST 消息重新支持调节窗口大小

Sat, 11 Apr 2020 12:32:30 +0000

做无边框窗口之后，我们有方法可以让窗口的标题栏区域和边缘调大小的区域继续正常工作，直到——这个窗口上面覆盖了其他的子窗口。这个子窗口会吃掉消息导致父窗口的边缘无法再继续处理这些消息。

子窗口遮挡了父窗口

看一下下面的动画，这个窗口的下半部分放了一个子窗口。

然后尝试在边缘调节窗口尺寸，会发现被子窗口覆盖的部分是无法完成窗口大小调节的。

究其原因，是子窗口处理掉了与调窗口大小相关的消息，导致父窗口完全不知道应该如何处理这个时候的操作。

在子窗口处理消息循环

在我的另一篇博客中，我有提到通过处理 WM_NCHITTEST 消息，返回 HT_RIGHT 等来实现支持 Windows 原生窗口功能的效果。然而那种方法是不适用于本文的场景的，如果你试试就会发现，那种方法会使得你只能调子窗口的大小，对父窗口无济于事。

正确的处理方法是当鼠标划过原本应该处在非客户区部分的时候，将消息交给父窗口处理。于是，我们需要在消息循环的处理中返回 HTTRANSPARENT 来告诉操作系统这个区域子窗口不处理消息，请交给父窗口。

这里，我以 WPF 的消息循环来写代码。因为只要是 Windows 平台的 UI 框架都有消息循环的处理，所以可以很容易迁移到其他框架甚至是其他语言。

public partial class ChildWindow : Window
{
    public ChildWindow()
    {
        InitializeComponent();
        SourceInitialized += ChildWindow_SourceInitialized;
    }

    private async void ChildWindow_SourceInitialized(object sender, EventArgs e)
    {
        var helper = new WindowInteropHelper(this);
        var source = HwndSource.FromHwnd(helper.Handle);
        source.AddHook(WndProc);
    }

    private IntPtr WndProc(IntPtr hwnd, int msg, IntPtr wParam, IntPtr lParam, ref bool handled)
    {
        const int WM_NCHITTEST = 0x0084;
        const int HTTRANSPARENT = -1;
        switch (msg)
        {
            case WM_NCHITTEST:
                // 这里，我强行让所有区域返回 HTTRANSPARENT，于是整个子窗口都交给父窗口处理消息。
                // 正常，你应该在这里计算窗口边缘。
                handled = true;
                return new IntPtr(HTTRANSPARENT);
            default:
                break;
        }
        return IntPtr.Zero;
    }
}

上面的代码会比较简化，因为我让子窗口的所有区域都返回 HTTRANSPARENT，这会让整个子窗口区域的消息都不由子窗口处理。如果需要使用这段代码的话，你需要自己判断窗口的边缘。

如果需要得到当前坐标的话，可以把下面的方法加入到你的项目中：

public static (int lowOrder, int highOrder) GetOrderWord(IntPtr value)
{
    int low = unchecked((short) (long) value);
    int high = unchecked((short) ((long) value >> 16));
    return (low, high);
}

于是将消息循环中的 lParam 传入可以获得当前的坐标（屏幕坐标系）：

// 获得当前基于屏幕坐标系的当前鼠标光标位置。
var (x, y) = GetOrderWord(lParam);

需要注意一些坑

当你准备使用返回 HTTRANSPARENT 时，一定要保证你坐标所在的父子窗口在同一个线程！

返回 HTTRANSPARENT 时，操作系统只会查找同线程的其他窗口，如果你的父窗口非同一个线程，那么操作系统处理消息循环时是找不到下一个处理消息的窗口的。

如果你一定要在父窗口非同一个线程时返回 HTTRANSPARENT 那么你的整个窗口（顶层窗口和子窗口）将无法再操作！你可以阅读 HTTRANSPARENT is evil - virtualdub.org 了解相关的坑。

参考资料

Windows 系统的默认字体是什么？应用的默认字体是什么？

Sat, 11 Apr 2020 01:48:31 +0000

作为中文应用的开发者，我们多半会认为系统的默认字体是“微软雅黑”。然而如果真的产生了这种误解，则很容易在开发本地化应用的时候踩坑。

于是本文带你了解 Windows 系统的默认字体。

Windows 10/8.1/8/7/Vista

Windows 操作系统的默认字体是 Segoe UI（发音为 see go 这两个单词），默认的字体大小为 9 点。

Segoe UI 是 Segoe 字体家族中专为显示器显示而设计的一款字体。当然，Windows 系统中的其他字体也遵循这一命名规则，带 UI 后缀的适用于界面显示，而不带 UI 后缀的适用于打印和其他排版设计。

Segoe UI包含拉丁（Latin），希腊（Greek），西里尔字母（Cyrillic）和阿拉伯（Arabic）字符，覆盖了基本的英文俄文字母、数字和一些常用符号。然而其他语言就没有了。

其他语言的默认字体分别是：

语言	字体
日语（Japanese）	Yu Gothic UI
韩语（Korean）	Malgun Gothic
繁体中文（Chinese (Traditional)）	Microsoft JhengHei
简体中文（Chinese (Simplified)）	Microsoft YaHei
希伯来语（Hebrew）	Gisha
泰语（Thai）	Leelawadee

[注] 经神樹桜乃指出，日语系统默认字体是 Yu Gothic UI 而不是 Meiryo。

Windows 操作系统在启动应用程序的时候，会根据当前系统用户的地区决定默认字体应该采用哪一个。

Windows XP 及更早系统

早期版本的 Windows，默认字体是 Tahoma。简体中文下则是宋体。

参考资料

Fonts - Win32 apps - Microsoft Docs

如何给 GitHub Pages 配置多个域名？

Fri, 10 Apr 2020 07:02:52 +0000

因为以前对域名进行了一些调整，所以实际上我的博客在历年来经历了两个域名 blog.walterlv.com（新）和 walterlv.com（旧）。然而 GitHub Pages 只支持一个自定义域名，所以为了兼容旧域名的访问，如何可以让多个域名对应同一个 GitHub Pages 呢？

背景

（新）
walterlv.com （旧）

以前不会碰到这样的问题，是因为我并没有使用 GitHub Pages 服务来构建博客，然而现在是了。

GitHub Pages 识别访问的是哪个站点的方式是识别 xxx.github.io 的 xxx 部分，比如默认我只能通过来访问到我通过 GitHub Pages 搭建的博客。因此如果你使用反向代理服务器将一个其他的域名代理到 xxx.github.io 是会得到 404 的——GitHub Pages 不知道你想访问哪个站点。

这时，在 GitHub Pages 设置里面，你就需要设置一个 Custom domain 来帮助 GitHub Pages 部署的时候知道某个域名实际上是你的，需要用来显示此仓库的 GitHub Pages。

比如我在这里设置了，于是当我将反向代理服务器代理到 walterlv.github.io 时，GitHub Pages 便能正确得知这实际上是 walterlv.github.io 这个仓库的，这才能正确显示 GitHub Pages 页面。

此设置会在你的仓库根目录生成 CNAME 文件，里面仅一行文本，即域名。

然而问题来了，我之前的域名实际上是 walterlv.com，这样，当我设置 DNS 时，如果直接将 walterlv.com 设置到 walterlv.github.io 依然会出现 404。

接下来我们说说解决办法。

通过中转仓库

我们需要在 GitHub 上再新建一个仓库，用来中转旧域名中的访问到新的域名。

第一步：新建随意名字的仓库

我们新建一个仓库。新建的时候实际上可以无所谓命名，因为这个仓库里面不会真的有内容，多数时候访问实际上是 404 的。但我们创建它只是为了前面提到的那个 CNAME 文件，告诉 GitHub Pages 我们有两个域名而已。

这里，我创建了一个名为 oldblog 的仓库，正常情况下，访问这个仓库 GitHub Pages 的域名前缀为 walterlv.github.io/oldblog。

第二步：为此仓库添加 GitHub Pages 服务

接着，按照平时去创建 GitHub Pages 服务的方法往这个仓库提交代码。

例如可以在仓库根目录放一个 _config.yml 文件（这是 Jekyll 的配置文件），然后直接提交：

title: walterlv
author: walterlv

当有了一个分支和 Jekyll 的配置文件后，就可以直接使用 GitHub Pages 服务了。在这里，我们将自定义域名填写成旧的域名 walterlv.com。

这样，当我们在域名服务器中将 walterlv.com 设置到 walterlv.github.io 时，GitHub Pages 至少知道应该使用这个仓库里的 GitHub Pages 来显示。

第三步：创建用于跳转的 404 页面

然而我们并不打算在这个仓库里真的放代码/网页，于是在根目录放一个 404.html 文件：

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>正在重定向…… - walterlv</title>
</head>
    <script language="javascript">
        var domain = "blog.walterlv.com";
        var current = window.location.href;
        var target = current.substring(current.indexOf('/', current.indexOf(':') + 3));
        window.location.href = "//" + domain + target;
        location.href = "//" + domain + target;
    </script>
    <body>
        正在重定向……
    </body>
</html>

现在，仓库里面是这样的（walterlv/oldblog）：

第四步：配置 DNS

最后检查你的 DNS 配置：

旧域名：walterlv.com -> walterlv.github.io
新域名： -> walterlv.github.io

到现在，就全部完成。不信你试试，点击链接 https://walterlv.com/post/multiple-domains-for-github-pages 会短暂进入一个“正在重定向……”的页面，然后随即跳转到新域名下相同的页面 https://blog.walterlv.com/post/multiple-domains-for-github-pages。

原理

一个 GitHub Pages 的仓库只能有一个 CNAME 文件，也即我们只能告知 GitHub 我们的一个合理域名。要让 GitHub Pages 支持两个域名，我们不得不建两个仓库，其中第二个仓库的地址为 xxx.walterlv.com/repo-name。在第二个仓库中，我们故意什么都不放，这样会触发 404，我们在 404 页面里面跳转到新的域名即完成了我们的目的。

参考资料

多个域名映射同一个github pages - 守望的个人博客

一点点从坑里爬出来：如何正确打开 WPF 里的 Popup？

Tue, 07 Apr 2020 13:34:17 +0000

在 WPF 中打开一个 Popup 并没有想象当中容易。虽说提供了一个 IsOpen 属性用于显示 Popup，但实际上造成的 Bug 会让你解得死去活来。Win32 的 WS_POPUP 也坑，不过 WPF 会额外再带来一些，所以本文只说 WPF。

先说结论

本文一开始就贴出打开一个 Popup 的代码

// 在以下代码中，我们假定 popup 是我们要显示出来的 Popup，而 textBox 是 Popup 中的文本框。
private async void WalterlvDemoControl_MouseUp(object sender, MouseButtonEventArgs e)
{
    // 必须延迟打开 Popup，如果在 MouseUp 中打开，会使得 Popup 无法获得焦点。
    await Task.Yield();
    popup.IsOpen = true;

    // 必须显式让 Popup 获得焦点，否则内部的 TextBox 输入时，IME 输入框无法跟随。
    await Task.Yield();
    var source = (HwndSource) PresentationSource.FromVisual(popup.Child);
    SetFocus(source.Handle);

    // 必须显式让文本框获得焦点（如果有的话）。
    await Task.Yield();
    Keyboard.Focus(textBox);
}

[DllImport("user32")]
public static extern IntPtr SetFocus(IntPtr hWnd);

如果你的 Popup 中没有文本框，那么最后的两段可以删除。

接下来一一说明。

Popup 有一个属性 StaysOpen，当设置为 false 时，我们期待的效果是失焦后 Popup 关闭。然而如果你是在任何控件的 MouseUp 事件中打开的，那么 Popup 就不会获得焦点。既然不会获得焦点，那么也就不存在失焦的问题。

具体表现为，你打开了 Popup 后，Popup 不会自己再自动关闭了，除非你手动在 Popup 内部点一下让 Popup 获得焦点，随后才会自动关闭。

无论你在后面如何写让 Popup 以及内部控件获得焦点的代码，实际上这种情况下弹出的 Popup 不会真正获得焦点，除非手动点击。

所以我在以上代码中加上了 await Task.Yield() 这样可以让后续的代码不再在 MouseUp 事件中。

如果你的 Popup 中没有文本框，那么这样做就够了；如果有，那么还需要做后续处理。

注意注意，如果你的 Popup 中包含文本框，那么一定需要加上 SetFocus 的调用。WPF 版本的设置焦点，无论是逻辑焦点（xx.Focus()）还是键盘焦点（Keyboard.Focus(xx)）都无法真正让 Popup 获得焦点。这时打字，IME 框是不会跟随文本框的。

需要单独为 TextBox 再设置焦点

只是为 Popup 设置焦点的话，Popup 中的文本框没有获得焦点，是不能直接打字的。当然你可能需求如此。这里就没有特别说明的点了。

VSCode：当匹配到结果时，如何一次性全部选中操作（复制/删除）？

Tue, 07 Apr 2020 12:48:11 +0000

最近需要处理几十万行的文字，然后提取出数千行（嗯，我在做输入法词库）。在 VSCode 里我用正则匹配到了想要的结果后，如何能够快速把这些行提取出来呢？

其实非常简单，Alt + Enter 即可选中所有已经匹配到的文字。

来，我们看这个具体的例子：

这里有一个几十万行的词库，我需要将其中的英文部分提取出来做成单独的词库。于是我使用正则表达式，匹配到所有英文词。

接着，按下 Alt + Enter 我就可以复制出所有的已匹配的词。将其粘贴出来即形成新的纯英文词库。

最简单的代码，让 WPF 支持响应式布局

Sat, 04 Apr 2020 14:55:07 +0000

响应式布局在各种现代的 UI 框架中不是什么新鲜的概念，基本都是内置支持。然而在古老的 WPF 框架中却并没有原生支持，后来虽然通过 Blend 自带的 Interactions 库实现了响应式布局，但生成的代码量太大了，而且需要引入额外的库。

如果只是希望临时局部地方使用响应式布局，那么其实可以直接使用 WPF 内置的绑定机制来完成响应式布局。本文介绍如何使用。

思路是在控件尺寸发生变更的时候更新控件的样式。而能容易实现这个的只有 Trigger 和 Setter 那一套。直接在控件上使用的 Trigger 只能使用 EventTrigger，因此我们需要编写能写更多种类 Trigger 的 Style。

<Style x:Key="Style.Foo.WalterlvDemo">
    <Setter Property="Grid.Row" Value="0" />
    <Setter Property="Grid.Column" Value="0" />
    <Style.Triggers>
        <DataTrigger Value="True"
                     Binding="{Binding ActualHeight, ElementName=DemoWindow,
                              Converter={StaticResource GreaterOrEqualsConverter},
                              ConverterParameter=640}">
            <Setter Property="Grid.Row" Value="1" />
            <Setter Property="Grid.Column" Value="1" />
        </DataTrigger>
    </Style.Triggers>
</Style>

定义了一个样式，默认情况下，行列是 (0, 0)，当窗口宽度大于或等于 640 之后，行列换到 (1, 1)。

这里我们需要一个大于或等于，以及小于的转换器。

using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Windows.Data;

namespace Cvte.EasiNote.UI.Styles.Converters
{
    public class GreaterOrEqualsConverter : IValueConverter
    {
        public double Than { get; set; }

        public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
        {
            if (value is double d)
            {
                return d >= Than;
            }
            else if (value is float f)
            {
                return f >= Than;
            }
            else if (value is ulong ul)
            {
                return ul >= Than;
            }
            else if (value is long l)
            {
                return l >= Than;
            }
            else if (value is uint ui)
            {
                return ui >= Than;
            }
            else if (value is int i)
            {
                return i >= Than;
            }
            else if (value is ushort us)
            {
                return us >= Than;
            }
            else if (value is short s)
            {
                return s >= Than;
            }
            else
            {
                return false;
            }
        }

        public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
        {
            throw new NotSupportedException();
        }
    }

    public class LessConverter : IValueConverter
    {
        public double Than { get; set; }

        public object Convert(object value, Type targetType, object parameter, CultureInfo culture)
        {
            if (value is double d)
            {
                return d < Than;
            }
            else if (value is float f)
            {
                return f < Than;
            }
            else if (value is ulong ul)
            {
                return ul < Than;
            }
            else if (value is long l)
            {
                return l < Than;
            }
            else if (value is uint ui)
            {
                return ui < Than;
            }
            else if (value is int i)
            {
                return i < Than;
            }
            else if (value is ushort us)
            {
                return us < Than;
            }
            else if (value is short s)
            {
                return s < Than;
            }
            else
            {
                return false;
            }
        }

        public object ConvertBack(object value, Type targetType, object parameter, CultureInfo culture)
        {
            throw new NotSupportedException();
        }
    }
}

如果你本身是写的基础控件的样式，那么绑定当然就跟本文一开始说的写法非常类似了。

如果你需要写的是一般控件，可以考虑直接在控件里写 <Framework.Style /> 把样式内联进去。

如果你写的是 DataTemplate，也一样是使用 DataTrigger 绑定。

你也可以不绑定到窗口上，而绑定到控件本身上，使用 TemplatedParent 作为绑定的源即可。

<DataTemplate>
    <DataTemplate.Resources>
        <local:LessConverter x:Key="LessThan60" Than="60" />
    </DataTemplate.Resources>
    <Grid>
        <Image x:Name="Icon" />
        <Rectangle x:Name="Mask" Fill="Red" />
    </Grid>
    <DataTemplate.Triggers>
        <DataTrigger Binding="{Binding ActualWidth, RelativeSource={RelativeSource TemplatedParent}, Converter={StaticResource LessThan60}}" Value="True">
            <Setter TargetName="Icon" Property="Grid.ColumnSpan" Value="3" />
            <Setter TargetName="Mask" Property="Visibility" Value="Collapsed" />
        </DataTrigger>
</DataTemplate>

WPF：无法对元素“XXX”设置 Name 特性值“YYY”。“XXX”在元素“ZZZ”的范围内，在另一范围内定义它时，已注册了名称。

Fri, 03 Apr 2020 06:44:21 +0000

最近在改一段 XAML 代码时，我发现无论如何给一个控件添加 Name 或者 x:Name 属性时都会出现编译错误：无法对元素“XXX”设置 Name 特性值“YYY”。“XXX”在元素“ZZZ”的范围内，在另一范围内定义它时，已注册了名称。

编译错误

编译时，出现错误：

无法对元素“XXX”设置 Name 特性值“YYY”。“XXX”在元素“ZZZ”的范围内，在另一范围内定义它时，已注册了名称。

MC3093: Cannot set Name attribute value ‘X’ on element ‘Y’. ‘Y’ is under the scope of element ‘Z’, which already had a name registered when it was defined in another scope.

这里的 XXX 是元素的类型，YYY 是指定的名称的值，ZZZ 是父容器的名称。

我把出现错误的 XAML 简化后大约是这样的，XXX 是 TextBox，YYY 是 RenameTextBox，而 ZZZ 是 walterlv:Foo。

<walterlv:Foo Background="White">
    <StackPanel Orientation="Horizontal" Focusable="False">
        <TextBlock Text="名称：" />
        <TextBox x:Name="RenameTextBox" />
    </StackPanel>
</walterlv:Foo>

小心用户控件

出现此问题的最大原因在那个 walterlv:Foo 上。实际上，这是一个用户控件，也就是继承自 UserControl 的大家通常用来写界面的东西。

<UserControl x:Class="Walterlv.Foo"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <UserControl.Style>
        <!-- 省略 -->
    </UserControl.Style>
</UserControl>

别问我为什么会有以上这样诡异的代码。我也不知道，这只是偶然发现的代码，我简化后拿到博客中。

于是需要提醒大家注意：

在 WPF 里，拥有直接的 XAML 文件的始终应该作为最终用户界面，不应该当作控件使用（不要试图在其他地方使用时还设置其 Content 属性）；
如果你确实希望做控件，请继承自 CustomControl 然后在 /Themes/Generic.xaml 里写样式。

至于以上 XAML 代码中我看到用的是 <UserControl.Style> 来写样式，是因为踩到了当控件用的另一个坑：

所有在控件的 XAML 中设置的 Content 属性都将被使用时覆盖。

解决方法

当然是考虑将以上诡异的用户控件定义方式改为正统的 CustomControl 啦！将 <UserControl.Style> 里定义的所有样式全部改到 /Themes/Generic.xaml 文件中。

如果你不清楚如何编写一个自定义控件，那么请直接在 Visual Studio 中基于 WPF 自定义控件创建文件，你会发现 Visual Studio 为你写好了注释。

using System;
using System.Collections.Generic;
using System.Text;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Data;
using System.Windows.Documents;
using System.Windows.Input;
using System.Windows.Media;
using System.Windows.Media.Imaging;
using System.Windows.Navigation;
using System.Windows.Shapes;

namespace Walterlv.Demo
{
    /// <summary>
    /// 按照步骤 1a 或 1b 操作，然后执行步骤 2 以在 XAML 文件中使用此自定义控件。
    ///
    /// 步骤 1a) 在当前项目中存在的 XAML 文件中使用该自定义控件。
    /// 将此 XmlNamespace 特性添加到要使用该特性的标记文件的根
    /// 元素中:
    ///
    ///     xmlns:MyNamespace="clr-namespace:Walterlv.Demo"
    ///
    ///
    /// 步骤 1b) 在其他项目中存在的 XAML 文件中使用该自定义控件。
    /// 将此 XmlNamespace 特性添加到要使用该特性的标记文件的根
    /// 元素中:
    ///
    ///     xmlns:MyNamespace="clr-namespace:Walterlv.Demo;assembly=Walterlv.Demo"
    ///
    /// 您还需要添加一个从 XAML 文件所在的项目到此项目的项目引用，
    /// 并重新生成以避免编译错误:
    ///
    ///     在解决方案资源管理器中右击目标项目，然后依次单击
    ///     “添加引用”->“项目”->[浏览查找并选择此项目]
    ///
    ///
    /// 步骤 2)
    /// 继续操作并在 XAML 文件中使用控件。
    ///
    ///     <MyNamespace:Foo/>
    ///
    /// </summary>
    public class Foo : Control
    {
        static Foo()
        {
            DefaultStyleKeyProperty.OverrideMetadata(typeof(Foo), new FrameworkPropertyMetadata(typeof(Foo)));
        }
    }
}

/Themes/Generic.xaml 文件：

<ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="clr-namespace:Walterlv.Demo">


    <Style TargetType="{x:Type local:Foo}">
        <Setter Property="Template">
            <Setter.Value>
                <ControlTemplate TargetType="{x:Type local:Foo}">
                    <Border Background="{TemplateBinding Background}"
                            BorderBrush="{TemplateBinding BorderBrush}"
                            BorderThickness="{TemplateBinding BorderThickness}">
                    </Border>
                </ControlTemplate>
            </Setter.Value>
        </Setter>
    </Style>
</ResourceDictionary>

在 Visual Studio 2019 (16.5) 中查看托管线程正在等待的锁被哪个线程占用

Thu, 02 Apr 2020 09:44:31 +0000

Visual Studio 2019 (16.5) 版本更新中带来了一项很小很难注意到却非常实用的功能，查看哪一个托管线程正在持有 .NET 对象锁。

如果你不了解这个功能如何使用，那么可以阅读本文。

更新日志

Visual Studio 的官方更新日志中对此功能的描述：

View which managed thread is holding a .NET object lock

即“查看托管线程正在持有 .NET 对象锁”。

功能入口

这个功能没有新的入口，你可以在“调用堆栈” (Call Stack) 窗口，“并行堆栈” (Parallel Stacks) 窗口，以及“线程”窗口的位置列中查看哪个托管线程正在持有 .NET 对象锁。

Call Stack

示例

现在我们就实际看一下这个功能的用法和效果。于是我写了一点下面的代码。

static void Main(string[] args)
{
    var locker = new object();

    Thread thread = new Thread(() =>
    {
        Console.WriteLine("后台线程尝试获得锁");
        lock (locker)
        {
            Console.WriteLine("后台线程成功获得锁");
        }
    })
    {
        Name = "walterlv thread",
    };

    Console.WriteLine("主线程尝试获得锁");
    Monitor.Enter(locker);
    Console.WriteLine("主线程成功获得锁");

    thread.Start();
}

在这段代码中，主线程获得锁之后直接退出，而新线程“walterlv thread”则尝试获得锁。

现在在 Visual Studio 2019 中运行这段代码，可以看到另一个线程是不可能获得锁的，于是不会输出最后那一句，其他都会输出。

随后我们在 Visual Studio 中点击“全部中断”，也就是那个“暂停”图标的按钮。

打开调用堆栈窗口（在“调试 -> 窗口 -> 调用堆栈”），可以看到堆栈最顶端显示了正在等待锁，并且指出了线程对象。

然后在线程窗口（在“调试 -> 窗口 -> 线程“）的位置列，鼠标移上去可以看到与堆栈中相同的信息。

当然，我们的主线程实际上早已直接退出了，所以正在等待的锁将永远不会释放（除非进程退出）。

同样的信息，在并行堆栈（在“调试 -> 窗口 -> 并行堆栈”）中也能看到。

参考资料

WPF 中如何绑定附加属性？XAML 中记得加括号，C# 中记得不能用字符串

Wed, 01 Apr 2020 12:35:51 +0000

在 XAML 中写绑定是 WPF 学习的必修课，进阶一点的，是用 C# 代码来写绑定。然而一旦绑定的属性是附加属性，好多小伙伴就会开始遇到坑了。

本文将介绍如何在 XAML 和 C# 代码中绑定附加属性。

背景代码

开始遇到这个问题的背景是我定义了一个附加属性，然后试图通过绑定的方式完成一些业务。

用附加属性来完成的很大一个好处在于不需要改动原有的代码破坏原来的类。例如我只需要在任何一个类中定义 IsDraggable 附加属性，就可以让我其他地方的 Grid Button 等支持拖拽。

public class DraggableElement : FrameworkElement
{
    static TabViewItem()
    {
        DefaultStyleKeyProperty.OverrideMetadata(typeof(DraggableElement),
            new FrameworkPropertyMetadata(typeof(DraggableElement)));
    }

    public static readonly DependencyProperty IsDraggableProperty =
        DependencyProperty.RegisterAttached(
            "IsDraggable", typeof(bool), typeof(TabViewItem),
            new PropertyMetadata(true));

    public static bool GetIsDraggable(DependencyObject item)
        => (bool) item.GetValue(IsDraggableProperty);

    public static void SetIsDraggable(DependencyObject obj, bool value)
        => obj.SetValue(IsDraggableProperty, value);
}

在 XAML 中绑定附加属性

在 XAML 中绑定附加属性的时候需要加上括号和类型的命名空间前缀：

<ListViewItem Content="{Binding (local:DraggableElement.IsDraggable), RelativeSource={RelativeSource Self}}"
              local:DraggableElement.IsDraggable="True" />

对于 WPF 内置的命名空间（http://schemas.microsoft.com/winfx/2006/xaml/presentation 命名空间下），是不需要加前缀的。

<TextBlock x:Name="DemoTextBlock" Grid.Row="1"
           Text="{Binding (Grid.Row), RelativeSource={RelativeSource Self}}" />

跟其他的绑定一样，这里并不需要在 Binding 后面写 Path=，因为 Binding 的构造函数中传入的参数就是赋值给 Path 的。

在 C# 代码中绑定附加属性

上面在说明附加属性绑定的时候我特地额外写了一个不需要写命名空间的 XAML 绑定附加属性的代码，这是为了说明接下来写 C# 代码时的注意事项。

是这样写吗？

// 给不看全文的小伙伴：这段代码是无法工作的！正常工作的在后文。
Binding binding = new Binding("(Grid.Row)")
{
    Source = DemoTextBlock,
}
BindingOperations.SetBinding(DemoTextBlock, TextBox.TextProperty, binding);

设想应该不是，因为 C# 代码中是没有命名空间前缀的，于是对于前面 XAML 中 (local:DraggableElement.IsDraggable) 的 local 部分就很不好处理。

实际上，这里的字符串即便是写成 System.Windows.Grid.Row 和 Walterlv.BindingDemo.DraggableElement.IsDraggable 也依然会绑定失败。

在 C# 代码中绑定附加属性，需要 使用依赖项属性，而不能使用字符串！

Binding binding = new Binding
{
    Source = DemoTextBlock,
    Path = new PropertyPath(Grid.RowProperty),
}
BindingOperations.SetBinding(DemoTextBlock, TextBox.TextProperty, binding);

Binding binding = new Binding
{
    Source = DemoDraggableElement,
    Path = new PropertyPath(DraggableElement.IsDraggableProperty),
}
BindingOperations.SetBinding(DemoDraggableElement, TextBox.TextProperty, binding);

因此需要特别注意，附加属性的绑定不再能使用字符串，需要使用依赖项属性。

参考资料

Binding to an Attached Property

将 Windows Terminal 作为外部工具集成到其他工具/程序/代码中

Tue, 24 Mar 2020 01:49:23 +0000

Windows Terminal 在 Windows 上是一款 UWP 应用，然而其依然具有良好的与外部工具的集成特性，你可以在其他各种工具中配置使用 Windows Terminal 打开。

本文介绍如何配置使用 Windows Terminal 打开。

命令行调用

在应用商店可以下载到 Windows Terminal (Preview)，下载安装后，你就可以开始使用 wt 命令了，这可以用来启动 Windows Terminal。（这里要说明一下，虽然你可以找到应用程序在 C:\Program Files\WindowsApps\Microsoft.WindowsTerminal_0.9.433.0_x64__8wekyb3d8bbwe\WindowsTerminal.exe 下，但是你并没有权限直接去运行 UWP 应用的 exe 入口。

因此，你在任意的命令行工具，甚至是 Win+R 运行窗口，或者开始菜单的搜索中输入 wt 回车就可以运行 Windows Terminal 了。

增加的命令实际上来自于 C:\Users\lvyi\AppData\Local\Microsoft\WindowsApps 目录。你可以进入这个目录找到商店应用增加的所有的命令。

默认情况下直接打开会进入用户文件夹下。

如果需要在特定的工作目录下打开，则需要修改配置。请点击设置按钮打开配置文件，然后修改默认终端的 startingDirectory 属性，从 %USERPROFILE% 修改到其他路径：

如果需要使用“当前工作路径”，则将 startingDirectory 修改为 %__CD__%。注意，CD 两边分别是两个下划线。

    {
      ……
      "snapOnInput": true,
--    "startingDirectory": "%USERPROFILE%",
++    "startingDirectory": "%__CD__%",
      "useAcrylic": true
    },

在修改成 %__CD__% 之后，如果通过快捷方式直接启动 Windows Terminal，则会看到路径被切换到了 C:\Windows\System32。不过这不重要，因为即便是选择了用户路径，每次启动也都是要切走的。

工具集成

在了解了以上命令行调用后，工具集成就简单多了，只需要设置好启动 wt 命令，以及设置好工作路径即可。

如下图是我在 Directory Opus 中设置的 Windows Terminal 的一键打开按钮：

关于 Directory Opus 集成工具可以参见我的其他博客：

C# 代码调用

使用 C# 代码启动的方法也非常常规，直接 Process.Start 然后设置工作路径即可。前提是前面设置了 %__CD__% 为启动路径。

var info = new ProcessStartInfo{
	FileName = "wt.exe",
	WorkingDirectory = @"D:\walterlv",
	UseShellExecute = false,
};
Process.Start(info);

参考资料

Programmatically Opening Windows Terminal in a Specific Folder - Rick Strahl’s Web Log

设置用户无需密码自动登录到 Windows 系统

Mon, 23 Mar 2020 03:36:48 +0000

你一定要为你的 Windows 用户账户设置密码，一来会安全一些，而来可以远程登录使用；但有时出于一些特殊的目的，不希望在每次开机后都必须输入密码才能进入系统。于是你可以使用本文提供的方法在每次开机的时候免密码登录到 Windows 操作系统。

步骤

在 Windows 搜索框中输入 netplwiz，然后回车打开命令；
去掉“要使用本计算机，用户必须输入用户名和密码”的勾勾；
点击“确定”或“应用”后，输入自动登录账号的用户名和密码。

注意，输入用户名和密码的时候，如果你使用了微软账号登录，那么需要输入你的微软账号，比如这样“walterlv@outlook.com”；而密码是你微软账号的密码，而不是 PIN 码。

Windows 10 截图

Windows 7 截图

修复 Windows 10 设置界面里面混乱的语言翻译

Mon, 23 Mar 2020 03:35:35 +0000

Windows 10 每次新发布一个版本都会遇到各种各样的新型 Bug。

本文介绍的是 Windows 10 的设置界面里面，各种各样的语言文字都很混乱，就像统一错位了一样。本文也会同时介绍其修复方法。

系统版本

会出现此问题的系统是 Windows 10 英文版系统。

注意，是 Windows 10 英文版系统，而不是中文版系统的英文语言。如果你想要识别这样的系统的话，也很简单，使用你的系统安装程序，安装程序中界面使用的语言就是此系统的原生语言。

如果在安装完此英文版系统后再安装中文语言，就可能会出现中文语言混乱的问题。

混乱的界面

先看看下面的两张图：

可以注意到，界面当中出现了很多本不应该出现在那个地方的文案。

如果我们这个时候让设置界面弹出一个对话框出来，你还会看到对话框中的文字超出范围导致布局错乱呢：

按钮都不知道被裁成什么样了。

修复方法

经过我的多次尝试，发现，英文版系统安装中文语言包，第一次几乎必定失败，然后出现本文所述的问题。

解决方法是这样的：

将语言切换回英文
删除中文语言包
删除下载缓存文件
重新下载中文语言包

下面详细说明。

将语言切换回英文

进入“系统设置 -> 时间和语言 -> 语言”，通过点击上箭头的方式将英语语言置顶，同时将显示语言切换成英语。

删除中文语言包

以管理员权限启动 PowerShell，然后输入 Get-WinUserLanguageList 命令，以获取我们要删除的语言的 LanguageTag。

PS C:\Windows\system32> Get-WinUserLanguageList

LanguageTag     : en-US
Autonym         : English (United States)
EnglishName     : English
LocalizedName   : English (United States)
ScriptName      : Latin
InputMethodTips : {0409:00000409}
Spellchecking   : True
Handwriting     : False

LanguageTag     : zh-Hans-CN
Autonym         : 中文(中华人民共和国)
EnglishName     : Chinese
LocalizedName   : Chinese (Simplified, China)
ScriptName      : Chinese (Simplified)
InputMethodTips : {0804:{81D4E9C9-1D3B-41BC-9E6C-4B40BF79E35E}{FA550B04-5AD7-411F-A5AC-CA038EC515D7}}
Spellchecking   : True
Handwriting     : True

然后，依次输入以下四句命令，获取语言列表，筛选我们要删除的语言，删除筛选出的语言，设置回列表。

PS C:\Windows\system32> $LangList = Get-WinUserLanguageList
PS C:\Windows\system32> $ToDeletedLang = $LangList | where LanguageTag -eq "zh-Hans-CN"
PS C:\Windows\system32> $LangList.Remove($ToDeletedLang)
True
PS C:\Windows\system32> Set-WinUserLanguageList $LangList -Force

删除下载缓存文件

进入文件夹“C:\Windows\SoftwareDistribution\Download”，删除里面的所有文件和文件夹。

随后，重新启动计算机。

重新下载中文语言包

现在，按照正常的安装中文语言包的方式再安装一次语言包。

即“Settings -> Time & Language -> Language -> Add a preferred language”，然后选择中文，下一步 -> 安装。等待安装结束。

等安装进度条全部结束之后，再选择现实语言为“中文”即可。

使用 SoftEther VPN 在 VPS 和个人电脑之间搭建 VPN 网络

Mon, 23 Mar 2020 03:35:30 +0000

VPN 全称是 Virtual Private Network（虚拟专用网络），可以在多台设备之间建立安全的通信网络。VPS 是 Virtual Private Server，虚拟专用服务器，指的是一台虚拟的电脑，用于提供服务。

注意，本文不会谈及科学上网相关的内容。本文建立 VPN 网络单纯是为了对外提供服务。

VPN 虚拟专用网络

为什么我们需要一个 VPS

为了对公众提供服务，我们需要：

一台 24×7 小时不关机的计算机
一个可被互联网访问到的 IP（公网 IP）

对个人家用电脑来说，你可以做到 24 小时不关机，但你拿不到一个稳定的公网 IP。中国电信可以在办网的时候提供公网 IP，但此 IP 会经常改变，因此几乎无法对外提供服务。虽然可以使用 DDNS（动态域名解析服务），但因为域名解析存在缓存，所以当 IP 改变的时候，你会有数分钟到数小时不等的时间无法访问到正确的 IP。

因此，个人电脑是无法稳定对外提供服务的——我们需要一个 VPS——它有固定的公网 IP。

反向代理

实际上，只需要一个 VPS 我们就能直接对外提供服务了——将服务部署到 VPS 上就可以。但我们也可以将服务部署到另一台计算机上，甚至这台计算机可以没有公网 IP。于是 VPS 上只需要部署一个反向代理服务器即可。

如果使用 FRP 这种反向代理服务器，那么不需要固定公网 IP 就能反向代理。然而 FRP 也有一些不能满足的要求，这时部署反向代理服务器，我们需要真实提供服务的计算机也具有固定的 IP。而 VPN 网络可以提供这一点。

虚拟专用网络（VPN）

如果我们将 VPS 和其他散布在内网或者非固定 IP 的公网计算机连接起来，组成一个专用的网络，那么这个就是“虚拟专用网络”（VPN）。这样，无论这些电脑散布在哪些地方，在哪些网络中，对于对方来说都是“内网”中的另一台电脑，这是可以有固定（内网）IP 的，于是可以做很多事情。

我画了一张简单的图来描述一个简单的 VPN 网络。

接下来，本文将介绍如何搭建一个如图所示的 VPN 网络。

VPS 端 - 服务端

以 Debian 系统的 VPS 为例，除了包管理工具和文本编辑工具，其他各种操作都是大同小异。

我们要在 VPS 端安装一个 SoftEther 的服务端和一个客户端。服务端用于连接整个 VPN 网络，而客户端用于将此 VPS 主机组成此 VPN 网络中的第一台计算机。

下载 SoftEther VPN

下载地址

Download - SoftEther VPN Project

下载有很多的种类可选。考虑到我们会部署到多台计算机上，所以建议选择最末尾的一个 ZIP CD-ROM Image Package of SoftEther VPN。这样，我们可以从一个文件夹中取出所有我们想要的运行环境。

安装 SoftEther VPN Server

在安装 SoftEther VPN 的服务端之前，我们需要确保你的 Linux 系统上有这些工具：

make
gcc
net-tools

如果是 Debian 系统，可以运行命令安装：

apt-get install make
apt-get install gcc
apt-get install net-tools

接下来的安装过程有编译步骤，所以需要用到以上工具。

将我们下载下来的 \VPN-CD-v4.30-9696-beta-2019.07.08\Linux\SoftEther_VPN_Server\64bit_-_Intel_x64_or_AMD64\softether-vpnserver-v4.30-9696-beta-2019.07.08-linux-x64-64bit\vpnserver 文件夹上传到 Linux 系统中，建议 /opt/SoftEther 目录，如下：

然后，进入 vpnserver 文件夹，运行 .install.sh：

cd vpnserver
bash .install.sh

配置 SoftEther VPN Server 服务

现在，前往 /etc/init.d 目录，这个目录存放了各种系统服务的启用和停用脚本。我们需要将 VPN Server 服务放到这个目录下。

你可以在官方文档 7.3 Install on Linux and Initial Configurations - SoftEther VPN Project 找到服务脚本。

记得将下面 DAEMON 中的路径改成你自己的路径。改好之后，命名成 vpnserver，放到 /etc/init.d 目录下。

#!/bin/sh
# chkconfig: 2345 99 01
# description: SoftEther VPN Server
DAEMON=/opt/SoftEther/vpnserver/vpnserver
LOCK=/var/lock/subsys/vpnserver
test -x $DAEMON || exit 0
case "$1" in
start)
$DAEMON start
touch $LOCK
;;
stop)
$DAEMON stop
rm $LOCK
;;
restart)
$DAEMON stop
sleep 3
$DAEMON start
;;
*)
echo "Usage: $0 {start|stop|restart}"
exit 1
esac
exit 0

请确保此文件的行尾符是 CL，而不是 Windows 系统中的 CLRF。

将此文件放入 /etc/init.d 后，记得修改文件的属性：

chmod 755 vpnserver

配置 SoftEther VPN Server 开机启动

Ubuntu 或者 Debian 系统的开机启动项脚本位于 /etc/rcN.d/ 目录中，我们可以使用以下命令设置其开机启动。

update-rc.d vpnserver defaults

启动 SoftEther VPN Server

使用以下命令启动服务：

/etc/init.d/vpnserver start

VPS 端 - 客户端

VPS 主机也需要安装运行 SoftEther VPN 客户端，这样这台主机才会成为 VPN 网络的其中一台主机。

安装方法与服务端非常类似，所以下面的介绍会简略一些。

安装 SoftEther VPN Client

将我们下载下来的 \VPN-CD-v4.30-9696-beta-2019.07.08\Linux\SoftEther_VPN_Client\64bit_-_Intel_x64_or_AMD64\softether-vpnclient-v4.30-9696-beta-2019.07.08-linux-x64-64bit\vpnclient 文件夹上传到 Linux 系统中，建议 /opt/SoftEther 目录，如下：

然后，进入 vpnclient 文件夹，运行 .install.sh：

cd vpnclient
bash .install.sh

配置 SoftEther VPN Client 服务

现在，前往 /etc/init.d 目录，这个目录存放了各种系统服务的启用和停用脚本。我们需要将 VPN Client 服务放到这个目录下。

记得将下面 DAEMON 中的路径改成你自己的路径。改好之后，命名成 vpnclient，放到 /etc/init.d 目录下。

#!/bin/sh
# chkconfig: 2345 99 01
# description: SoftEther VPN Client
DAEMON=/opt/SoftEther/vpnclient/vpnclient
LOCK=/var/lock/subsys/vpnclient
test -x $DAEMON || exit 0
case "$1" in
start)
$DAEMON start
touch $LOCK
;;
stop)
$DAEMON stop
rm $LOCK
;;
restart)
$DAEMON stop
sleep 3
$DAEMON start
;;
*)
echo "Usage: $0 {start|stop|restart}"
exit 1
esac
exit 0

将此文件放入 /etc/init.d 后，记得修改文件的属性：

chmod 755 vpnclient

配置 SoftEther VPN Client 开机启动

使用以下命令设置其开机启动。

update-rc.d vpnclient defaults

启动 SoftEther VPN Client

使用以下命令启动服务：

/etc/init.d/vpnclient start

启动后，会出现一些提示：

The SoftEther VPN Server service has been started.

Let's get started by accessing to the following URL from your PC:

https://**.**.**.**:5555/
  or
https://**.**.**.**/

Note: IP address may vary. Specify your server's IP address.
A TLS certificate warning will appear because the server uses self signed certificate by default. That is natural. Continue with ignoring the TLS warning.

这里会提示你 VPN 服务器的 IP 和端口号。我们接下来在配置客户端的时候会用到这个 IP 和端口号。

个人电脑端

这里个人电脑端我们使用 Windows 系统。

安装

将我们下载下来的 \VPN-CD-v4.30-9696-beta-2019.07.08\Windows\SoftEther_VPN_Server_and_VPN_Bridge安装服务端管理工具 文件夹打开，运行里面的 exe 安装：

▲ 我们将用这个工具来管理我们在 VPS 上部署的 VPN Server

将我们下载下来的 \VPN-CD-v4.30-9696-beta-2019.07.08\Windows\SoftEther_VPN_Client 文件夹打开，运行里面的 exe 安装：

▲ 我们将用这个工具来管理我们在 VPS 上部署的 VPN Client 以及在本机上部署的 VPN Client

配置 VPS 上的 VPN Server

启动“SE-VPN Server Manager (Tools)”：

我们将使用此工具配置我们在 VPS 上的 VPN Server。

第一步：设置新连接，输入设置名、主机名和端口（就是我面前面在 VPS 上输出的 IP 和端口）。输入完之后点确定。

第二步：连接这个设置，第一次连接会提示设置管理员密码，请自己设置一个。

第三步：安装和配置 VPN Server

设置过程是一步步来的，你可以考虑按照下图依次设置。

▲ 远程访问 VPN Server

▲ 设置好主机名后，直接点退出

▲ 启用 L2TP 服务器功能，并设置好 IPsec 预共享密钥

▲ 禁用 VPN Azure

▲ 创建新用户

至此，服务端就设置完毕。接下来我们设置客户端。

配置本地的 VPN Client

启动 SoftEther VPN Client 管理工具，我们即将使用此工具管理本机的客户端和刚刚配好的 VPS 主机上的客户端。

点击“添加新的 VPN 连接”。首次点击的时候会提示创建虚拟网络适配器，点击“是”让它创建即可。

随后，添加新的 VPN 连接：

设置连接信息。

连接设置名：随便填写
主机名：前面我们启动 VPN Server 时输出的 IP
端口号：前面我们启动 VPN Server 时输出的端口号
虚拟 HUB 名：前面我们填完之后，这里就会自动出现了，选择即可
用户认证设置：我们前一步设置用户的时候设置的用户名和密码

配置 VPS 上的 VPN Client

启动“管理远程电脑上的 SoftEther VPN Client”程序：

输入我们前面 VPS 上的 IP 地址：

……

用命令行执行 .NET 单元测试时，如何仅执行符合某些条件的单元测试

Wed, 11 Mar 2020 09:59:23 +0000

本文介绍使用 dotnet test 命令进行单元测试的时候，过滤出被测项目中的一部分测试出来，仅测试这一部分。

背景

建一个 .NET Core 的单元测试项目，例如项目名字是 Walterlv.Demo.Tests。举例其中的一个测试类如下：

using Microsoft.VisualStudio.TestTools.UnitTesting;

namespace Walterlv.Demo.Tests
{
    [TestClass]
    public class FooTest
    {
        [TestCategory("CategoryA")]
        [Priority(1)]
        [TestMethod]
        public void TestMethod1()
        {
        }

        [Priority(2)]
        [TestMethod]
        public void TestMethod2()
        {
        }
    }
}

使用 Visual Studio 的话，直接在测试资源管理器中点击运行全部测试，或者选择想要测试的项点运行所选测试即可。

而使用 GUI 工具的话不利于 CI 集成和自动化测试，所以必然需要用到命令：

> dotnet test .\Walterlv.Demo.Tests.dll

有时为了调试方便或输出分类数据等，要求执行一部分单元测试，这就需要过滤了。dotnet test 的过滤使用 --filter 选项。

过滤

方法名

查找方法名包含某字符串的单元测试并执行：

dotnet test --filter TestMethod1

或者：

dotnet test --filter Name~TestMethod1

如果是排除某方法，则是：

dotnet test --filter FullyQualifiedName!=Walterlv.Demo.Tests.FooTest.TestMethod1

类名

查找类名等于某字符串的单元测试并执行：

dotnet test --filter ClassName=Walterlv.Demo.Tests.FooTest

类名必须包含命名空间，否则找不到。

分类与优先级

查找标记了 [TestCategory("CategoryA")] 的方法并执行单元测试：

dotnet test --filter TestCategory=CategoryA

查找标记了 [Priority(2)] 的方法并执行单元测试：

dotnet test --filter Priority=2

条件与或

条件或（|）：

dotnet test --filter Name~TestMethod1|TestCategory=CategoryA

条件与（’&’）：

dotnet test --filter Name~TestMethod1&TestCategory=CategoryA

参考资料

Running selective unit tests - .NET Core - Microsoft Docs

.NET WebClient 类下载部分文件会错误？可能是解压缩的锅

Wed, 11 Mar 2020 09:02:19 +0000

一直在使用 WebClient 下载文件，.NET 已经封装好，所以用起来代码非常简洁；但直到今天发现有一个文件一直不能正确下载下来。

本文介绍这个问题的原因和解决方法，更重要的是给出调查方法。

本文所涉及到的域名已经过敏感信息处理，所以实际上你是无法访问到的；但这不影响本文对调查方法的描述。

问题

我原本是使用如下的代码去下载任意文件的（参数经过简化）。

private static async Task DownloadFileAsync()
{
    var url = "http://localhost:5000/walterlv-icon.svg";
    var fileName = @"C:\Users\lvyi\Desktop\TEST\walterlv-icon.svg";

    using var webClient = new WebClient();
    webClient.DownloadFile(new Uri(url), fileName);
}

现在，下载一个 svg 的时候，原本应该是如下的图片：

然而实际上下载下来之后却是这样的：

原本大小是 992 字节，实际下载下来后是 508 字节，而且固定是 508 字节。你可以通过右键复制图片地址，然后分别把两张图下载下来看。

调查

显然，WebClient 没有抛出任何异常，而且每次下载下来都是固定的 508 字节，说明肯定不是网络不通或程序提前退出导致的，也不是线程安全相关的问题。基本可以认定为问题出在服务器的配置，或者客户端的请求上。

使用其他“正常”下载器尝试

拿 Chrome 跑以上地址，拿专用下载工具跑以上地址，甚至是拿 Postman 跑以上地址，都可以成功显示或者下载到正确的图片。

这几乎可以肯定，问题出在 .NET 的 WebClient 上，可能是请求不对，或者对响应的后续处理不对。

使用 Postman 和 WebClient 对比测试

为了对比请求和响应，我使用的是 Fiddler 抓包。

WebClient 请求：

GET http://localhost:5000/walterlv-icon.svg HTTP/1.1
Host: localhost:5000
Connection: Keep-Alive

WebClient 响应（因为内含乱码，会让网页显示不正常，所以放截图）：

Postman 请求：

GET http://localhost:5000/walterlv-icon.svg HTTP/1.1
Content-Type: application/json
User-Agent: PostmanRuntime/7.22.0
Accept: */*
Cache-Control: no-cache
Postman-Token: 05bb3d80-d7a7-4c0d-bdd1-9cd65d79ecab
Host: localhost:5000
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

Postman 响应（因为内含乱码，会让网页显示不正常，所以放截图）：

请求和响应贴得很长，这可以让比较感兴趣的小伙伴仔细比较。但这里我直接给出我比较后的结论：

Postman 的请求会发送比较多的头
两者的响应几乎相同（包括文件大小和内容）

由于响应几乎相同，所以实际上前面请求头的不同可以忽略了（至少说明返回的内容没有因为请求的不同而有所变化），我们能够拿到完整的整个文件。

那么问题基本确定就是在 WebClient 对这个响应的处理上了。

可以注意到 Postman 的请求中有 Accept-Encoding，两折的响应中都有 Content-Encoding，指定了 gzip。然而这是 Linux 中用来压缩文件的命令。响应中指定了内容编码方式为 gzip 是否意味着我们下载下来的文件实际上是一个 gzip 压缩文件呢？

于是我将下载下来的文件扩展名改为 gzip，用压缩文件打开，于是真的可以解压出来真实的图片。

于是确认问题的原因是 WebClient 在处理响应的时候没有根据 Content-Encoding 的值解压缩下载下来的文件。

解决

解决的思路：

使 WebClient 支持下载文件后解压缩

使 `WebClient` 支持下载文件后解压缩

各种检查后发现，WebClient 竟然没有提供设置解压缩相关的属性。庆幸的是，在网上搜索 WebClient 和 gzip 关键字后，找到了这一篇答案：.net - Automatically decompress gzip response via WebClient.DownloadData - Stack Overflow。

我们需要重写 WebClient.GetWebRequest 方法，然后改写 AutomaticDecompression 属性。此属性可以改成 gzip、deflate 和 br 或者它们的组合，这与 Postman 发请求时声明支持的值是完全一样的。

class AutoDecompressionWebClient : WebClient
{
    protected override WebRequest GetWebRequest(Uri address)
    {
        var baseRequest = base.GetWebRequest(address);
        if (baseRequest is HttpWebRequest httpWebRequest)
        {
            httpWebRequest.AutomaticDecompression = DecompressionMethods.All;
        }
        return baseRequest;
    }
}

另外，也可以在拉取到响应的流后自己去做解压，可以参见：

.net - How do you download and extract a gzipped file with C#? - Stack Overflow

参考资料

如何在终端和 PowerShell 中将一个命令自动重复执行多次

Wed, 11 Mar 2020 08:26:03 +0000

你可能有很多原因要将一个命令重复执行多次，本文介绍在多个平台下如何多次重复执行命令。

背景

最近遇到一个偶然复现的单元测试错误，于是在每次运行时，打算重复运行多次来调查问题是否已经解决。

实际上，重复执行命令有更多用途：

通过重复执行来复现一些偶发的问题
执行一组命令，每次只有参数不同
大大减轻手工输入命令的工作量

Bash

Linux 或者 Mac 系统的终端中，可以使用 for 来完成重复执行命令，使用 ${} 来引用定义的变量。

for i in {1..10}; do echo ${i}; done

这表示从 1 到 10（两端的值都会取到），依次输出这些数。

比如，我们需要运行 100 次单元测试，那么：

walterlv@localhost:~$ for i in {1..100}; do dotnet test ./Walterlv.Tests.dll; done
Microsoft (R) 测试执行命令行工具版本 16.3.0
版权所有 (C) Microsoft Corporation。保留所有权利。
正在启动测试执行，请稍候...

总共 1 个测试文件与指定模式相匹配。

测试运行成功。
测试总数: 238
     通过数: 238
总时间: 1.6384 秒
Microsoft (R) 测试执行命令行工具版本 16.3.0
版权所有 (C) Microsoft Corporation。保留所有权利。
正在启动测试执行，请稍候...

总共 1 个测试文件与指定模式相匹配。

测试运行成功。
测试总数: 238
     通过数: 238
总时间: 1.7138 秒
...

PowerShell

PowerShell Core 是跨平台的配置框架，可以在 Windows/Linux/Mac 系统下使用。在 PowerShell 中，也可以使用 for：

for ($i=1; $i -le 10; $i++) { echo $i }

这表示从 1 到 10（两端的值都会取到），依次输出这些数。

比如，我们需要运行 100 次单元测试，那么：

PS C:\Users\lvyi> for ($i=1; $i -le 100; $i++) { dotnet test .\Walterlv.Tests.dll }
Microsoft (R) 测试执行命令行工具版本 16.3.0
版权所有 (C) Microsoft Corporation。保留所有权利。
正在启动测试执行，请稍候...

总共 1 个测试文件与指定模式相匹配。

测试运行成功。
测试总数: 238
     通过数: 238
总时间: 1.6384 秒
Microsoft (R) 测试执行命令行工具版本 16.3.0
版权所有 (C) Microsoft Corporation。保留所有权利。
正在启动测试执行，请稍候...

总共 1 个测试文件与指定模式相匹配。

测试运行成功。
测试总数: 238
     通过数: 238
总时间: 1.7138 秒
...

参考资料

How To Run a Command Multiple Times in Terminal and PowerShell

Linux 系统根目录下的文件夹

Thu, 30 Jan 2020 08:02:14 +0000

本文介绍 Linux 系统根目录下的各种文件夹及其用途，了解这些目录可以帮助你更好地管理你的 Linux 主机。

Linux 系统根目录

各个不同 Linux 发行版的根目录会有一些区别，但大多数发行版的主要的目录都是有的。

/bin binary 用于存放经常使用的命令
/boot boot 启动时的一些核心文件
/dev device 外部设备
/etc 用于存放各种系统配置和管理配置（名字来源于法语 et cetera，意思就是 etc…，表示还有一些其他的东西等等，其实就是指一堆杂项，不过现在就用来存放一堆配置文件了）
/home 用户目录，里面按用户名命名了子文件夹
/lib library 存放系统最基本的动态链接共享库
/lib64 library 64bit 动态链接库的 64 位版本
/lost+found 一般情况下是空的，但在非法关闭后，这里就会存放一些文件
/media 识别出的 U 盘，光驱等会在这个目录下
/mnt mount 系统提供此文件夹用于给用户挂载其他的文件系统，例如光驱
/opt 用于安装软件的目录
/proc 是一个虚拟目录，是系统的内存映射，可通过访问此目录获取系统信息（这个目录的内容不在硬盘上而在内存里）
/root 超级管理员 root 用户的主目录
/run 用于在系统启动时运行的程序
/sbin super binary 系统超集管理员使用的系统管理程序
/srv service 存放一些服务启动之后需要提取的数据。
/sys 存放 Linux 系统内核文件
/tmp 用于存放一些临时文件
/usr 用户的应用程序和文件都在此目录下，类似于 Windows 系统中的 Program Files 目录
/var 经常被修改的文件可以放到这个目录，比如说日志文件

参考资料

收集的 Linux VPS 在线重装系统脚本

Wed, 29 Jan 2020 13:58:13 +0000

因为 VPS 上预装的操作系统我并不习惯，所以打算重装一个。有的 VPS 服务商提供了较多种类的系统选择，有的却没有。如果你发现你希望重装的系统服务商没有提供，可以考虑自己安装。

重装脚本 - 来自萌咖

以下是来自萌咖的一键重装脚本的发布贴：

CentOS -> Debian

第一步：先确保安装所需的软件。

yum install -y gawk sed grep

[root@walterlv ~]# yum install -y gawk sed grep
Loaded plugins: fastestmirror
Determining fastest mirrors
epel/x86_64/metalink                                      | 9.5 kB  00:00:00
 * base: mirror.xtom.com.hk
 * epel: my.mirrors.thegigabit.com
 * extras: mirror.xtom.com.hk
 * updates: mirror.xtom.com.hk
base                                                                                                                                                                | 3.6 kB  00:00:00     
epel                                                                                                                                                                | 5.3 kB  00:00:00     
extras                                                                                                                                                              | 2.9 kB  00:00:00     
updates                                                                                                                                                             | 2.9 kB  00:00:00     
(1/7): base/7/x86_64/group_gz                             | 165 kB  00:00:01
(2/7): extras/7/x86_64/primary_db                         | 159 kB  00:00:00
(3/7): epel/x86_64/group_gz                               |  90 kB  00:00:01
(4/7): epel/x86_64/updateinfo                             | 1.0 MB  00:00:03
(5/7): base/7/x86_64/primary_db                           | 6.0 MB  00:00:04
(6/7): updates/7/x86_64/primary_db                        | 5.9 MB  00:00:03
(7/7): epel/x86_64/primary_db                             | 6.9 MB  00:06:01
Package gawk-4.0.2-4.el7_3.1.x86_64 already installed and latest version
Package sed-4.2.2-5.el7.x86_64 already installed and latest version
Package grep-2.20-3.el7.x86_64 already installed and latest version
Nothing to do

第二步：下载脚本。

wget --no-check-certificate -qO DebianNET.sh 'https://moeclub.org/attachment/LinuxShell/DebianNET.sh' && chmod a+x DebianNET.sh

第三步：全自动安装 Debian 9

bash DebianNET.sh -d 9 -v 64 -a

这里的 -a 是自动安装。如果不指定或者指定为 -m 则需要去 VNC 手动安装。

可以设置安装时 root 用户的密码：

bash DebianNET.sh -d 9 -v 64 -a -p WalterlvPwd

如果你希望设置更多的安装选项，也可以选择手动安装。第三步我们修改命令。

第三步：手动安装系统 Debian 9

[root@walterlv ~]# bash DebianNET.sh -d 9 -v 64

安装过程和交互如下：

# Install

Do you want to install os manually?[y/n] y
Manual Mode insatll [Debian] [stretch] [amd64] in VNC.

[Debian] [stretch] [amd64] Downloading...

It will reboot!
Please connect VNC!
Select Install OS [stretch amd64] to install system.

在以上命令重启 Linux 后，前往 VNC 界面选择启动的操作系统：

随后会进入安装和设置界面。

为什么实现 .NET 的 ICollection 集合时需要实现 SyncRoot 属性？如何正确实现这个属性？

Tue, 28 Jan 2020 08:53:15 +0000

非泛型版本的 ICollection 中有 IsSynchronized 属性和 SyncRoot 属性，这两个属性被用来设计成以线程安全的方式访问和修改集合。不过这个设计让线程安全的访问由集合的实现方转嫁到了调用方，导致要么很难实现，要么很难调用。

虽然泛型版本的 ICollection<T> 已经改进了设计，不再引入 SyncRoot 这样的属性到接口中，但如果我们在某些场景下需要实现 ICollection 非泛型集合时，如何正确实现 SyncRoot 模式（SyncRoot Pattern）呢？

先上结论：

—— 不可能正确实现 SyncRoot 模式

在多线程程序设计中，为了在保证线程安全的同时避免死锁，不应该公开同步锁。而 ICollection 接口中的 SyncRoot 属性在接口中必然是公开的，于是没有任何途径可以保证调用方不会发生死锁。

于是实现 SyncRoot 的正确方法应该是：

—— 避免公开 SyncRoot 属性

所以 SyncRoot 模式应该这样实现：

使用显式接口实现，避免公开暴露此属性
抛出异常，避免调用者使用此属性

结合 .NET Core 源代码中的一些常用写法，我给出一个推荐的 SyncRoot 模式的写法：

// Is this List synchronized (thread-safe)?
bool ICollection.IsSynchronized => false;

// Synchronization root for this object.
object ICollection.SyncRoot => this;

嗯，没错，返回了 this，这是各种同步时绝对不应该使用的对象。然而这个属性都是 public 了，不管返回什么，与 this 还有什么区别……

关于为什么同步时不应该返回 this 或者返回公开的对象，原因可以看我的另一篇博客：

为什么不应该公开用来同步的加锁对象？为什么不应该 lock(this)/lock(string) 或者 lock 任何非私有对象？ - walterlv

全民 https！使用 FreeSSL 申请免费的 https 证书

Mon, 13 Jan 2020 00:05:30 +0000

到现在还不为你的网站添加 https 的话，浏览器已经会非常显眼地显示“不安全”了。

感谢 Let’s Encrypt，感谢 buypass，个人使用申请 https 证书的话已经可以免费了。

关于域名

我们使用 FreeSSL.org 申请的是域名证书，对一个或多个域名生效。所以，你至少需要拥有一个域名。如果没有，去 https://tld-list.com/ 输入你心仪的域名，然后找到最便宜的一家买一个吧！

第一步：输入域名

打开 https://freessl.org/，在输入框中输入你想要申请证书的域名，然后点击“创建免费的SSL证书”。

下面有提供商的选择，选 Let’s Encrypt V2 的话，我们可以申请泛域名证书，但有效期只有 3 个月。也就是说 3 个月之后你需要重新申请（重新申请的步骤可以简化，后面会说）。选择 buypass 的话，不能申请泛域名证书，但一次申请可以管 6 个月，比较省事儿。

可能需要解释一下泛域名。泛域名是带通配符的域名，例如 *.walterlv.com 就是一个泛域名。值得注意的是，这只能代表所有的二级域名。

com 是一个顶级域名，walterlv.com 是一个一级域名，是一个二级域名。而泛域名 `*.walterlv.com` 范围涵盖了二级域名，但是不包含一级域名 `walterlv.com` 和三级域名 `s.blog.walterlv.com`。

所以你不能指望申请一个泛域名适用你的所有网站。但是！FreeSSL.org 自动为你的泛域名创建两个证书，对我们初学者来说非常友好，不容易出错！如下图所示。

▲ 当输入了一个泛域名之后，点击“创建免费的SSL证书”，会自动把上一级域名也自动生成了。

第二步：填写邮箱

输入你自己的邮箱，然后点击“点击创建”。

第三步：安装并用 KeyManager 打开

推荐下载安装 KeyManager，这可以在接下来的步骤当中省去一堆手工配置，也为将来重新申请证书带来更高的效率。

下载安装完成后，如果打开 KeyManager 的提示已经消失，可以点击“再次尝试启动KeyManager”打开：

打开 KeyManager 后不需要任何操作，直接回到浏览器中刚刚的页面即可。（当然，如果提示登录或设置密码，则需要输入密码）

回到浏览器后点击“继续”：

第四步：验证域名

FreeSSL.org 需要验证这个域名确实是你自己的，按照它的说明，去你的域名管理页面中配置一个或两个记录（取决于你申请几个证书）。

你需要前往你购买域名的域名提供商的网页里去设置。如果你已经改了域名服务器，就需要去改了之后的域名服务商那里设置。

设置方法是添加一个新的设置，类型是 TXT，名称是和值是上面页面中给你提供的值。

第五步：点击验证

回到 FreeSSL.org 页面，点击“点击验证”，如果通过，这时会继续提示进入 KeyManager 软件。如果没有通过，不要紧，等几分钟再试，不同的域名服务器生效的时间有差异。

第六步：导出证书

在 KeyManager 的证书管理页面，点击单个域名最右边的“…”按钮，点击“详情”，拉倒最下面点击“查看证书”，再点击“导出证书”。

选择你希望导出的证书平台，决定是否要为证书设置密码，点击“导出”。

我应该选择哪个平台？

如果你使用 Nginx 或 frp 反向代理服务器，那么导出为 Nginx 平台。参见：

如果你使用 IIS 反向代理服务器，或者直接使用 Kestrel 对外提供 https 粉刷说，那么导出为 IIS 平台。参见：

使用 Kestrel 为你的 ASP.NET Core 服务添加 https 支持

如果你使用 Apache 或者 Tomcat 作为 Web 服务器，则选择对应的平台。

最后

将证书用于你的 Web 服务器，参见：

三种方法为 ASP.NET Core 对外服务添加 https 支持（kestrel / frp / nginx）

如何设置 ASP.NET Core 程序监听的 IP 和端口

Mon, 13 Jan 2020 00:04:22 +0000

Web 服务需要配置监听的 IP 和端口才可以对外提供真正的服务。本文介绍如何设置 ASP.NET Core 程序监听的 IP 和端口。

ASP.NET Core 程序默认集成了 Kestrel 服务器，可以直接对外提供 Web 服务。虽然可以直接提供服务，但通常建议使用反向代理服务器来间接提供服务。因此，本文建议的大多数设置监听 IP 和端口的方法都是“临时方法”，即那种“配置出来”的方法，而不会直接写死在代码中。

如何选择应该监听的 IP 和端口？

一般来说，监听的 IP 可以选择本地回环地址，特定的 IP 以及任意 IP，分别是：

127.0.0.1 127.0.0.2 127.0.0.3…… 本地回环地址
101.199.96.22 特定的 IP
0.0.0.0 任意 IP

监听本地回环地址时，则访问仅限于本机应用程序，不需要管理员权限来添加防火墙配置。如果在本地计算机配置了反向代理服务器，则强烈推荐使用本地回环地址。如果打算直接让服务对外公开提供，则需要设置为 0.0.0.0 任意 IP。

一台计算机上不同的应用不能使用相同的端口，对于端口的选择只要不重复即可。如果希望让 ASP.NET Core 程序自动选择一个不重复的端口，则将其指定为 0。

配置方法

方法一：直接在项目中设置

在项目上右击属性，在调试标签下可以修改应用的启动 URL。虽然这里修改的是项目的设置，最终生成的 ASP.NET Core 程序并不会使用这个设置，但每次通过项目打开时仍然可以使用这个设置。

这种方式仅仅影响调试时候采用的域名 / IP 和端口号。因此，仅在调试期间生效，待发布后，可以直接接入到反向代理服务器中。

方法二：使用 Kestrel 服务器的配置（不推荐）

直接使用 Kestrel 服务器可以在没有反向代理服务器的情况下直接对外提供 ASP.NET Core 的 Web 服务。

如果仅对外提供 http 服务，则设置非常简单：

    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
++              webBuilder.ConfigureKestrel(serverOptions =>
++              {
++                  serverOptions.Listen("0.0.0.0", 5000);
++              })
                .UseStartup<Startup>();
            });

如果希望加上 https 的支持，可以阅读我的另一篇博客：

使用 Kestrel 为你的 ASP.NET Core 服务添加 https 支持

方法三：使用命令行参数指定

使用命令行参数 --urls 可以为 ASP.NET Core 程序指定监听的 URL。

dotnet ./blog.walterlv.com.exe --urls http://0.0.0.0:13800

这个 URL 中的几个信息都会用到：http 协议，监听任意 IP 地址，监听端口 13800。

通常建议为反向代理的服务选用 http，让 https 的支持交给反向代理服务器去做，参见：

三种方法为 ASP.NET Core 对外服务添加 https 支持（kestrel / frp / nginx）

方法四：设置环境变量

设置环境变量 ASPNETCORE_URLS 即可为 ASP.NET Core 程序指定监听的 URL，格式与上面使用命令行参数是一样的。

注意，这里说的环境变量是单独为某一个程序设置的环境变量，而不是为用户账户或者操作系统设置的环境变量（那样显然会让所有 ASP.NET Core 程序冲突）。所以通常都是用来在反向代理服务器中配置的。

使用 Frp 为你的 Web 服务添加 https 支持

Mon, 13 Jan 2020 00:03:28 +0000

frp 是一个可用于内网穿透的高性能的反向代理应用，支持 tcp, udp 协议，为 http 和 https 应用协议提供了额外的能力，且尝试性支持了点对点穿透。

在众多反向代理应用中，frp 的最大特点就在于内网穿透。所以，如果你有将内网对外提供 Web 服务的需求，就可以考虑使用 frp 为你的 Web 服务提供 https 支持。

下载 frp

前往 GitHub 下载 frp：

Releases · fatedier/frp

有适用于各种不同操作系统的 frp，如果你对外提供的公网服务器和实际提供 Web 服务的服务器不是同一台机器的话，需要为各自机器下载对应版本的 frp。

准备好 Web 服务和 SSL 证书

你可以用任何方式开发你的 Web 服务，注意你的 Web 服务需要监听一个本机端口。

对于准备 SSL 证书，你可以参考我的另一篇博客：

使用 freessl.org 为你的域名申请免费的 SSL 证书

对于本文的后续内容，你需要将证书导出成 Nginx 格式，即一个 crt 文件和一个 key 文件。

配置 frp

你需要准备运行一个 frp 服务端和一个 frp 客户端。它们可以运行在不同的机器上，也可以运行在同一台机器上。

鉴于 frp 的内网穿透的优势，如果你将这两个端部署在不同的机器上，就能够实现 https 支持的同时也做到内网穿透——即你可以将 NAT 网络中的一台电脑对全球公开的互联网提供服务。

当然，你也可以部署到同一台机器上，这样的优势就是一个端口可以服务很多的 Web 服务，同时支持 https。

接下来的描述中，我用 A 机器表示 frp 服务端（也就是对公众开放服务的一端），B 机器表示 frp 客户端（提供 Web 服务的一端）。它们可以是同一台机器，也可以是不同的机器。

反向代理服务端

A 机器需要修改 frps.ini 文件：

[common]
bind_port = 7000
vhost_http_port = 80
vhost_https_port = 443

▲ bind_port 是 frp 服务端口，客户端如果要使用 frp 服务则连接这个端口；vhost_http_port 是代理 http 的端口；vhost_https_port 是代理 https 的端口

配置完成之后，运行 frp 程序：

./frps -c ./frps.ini

▲ 对于 Linux 系统

./frps.exe -c ./frps.ini

▲ 对于 Windows 系统

于是，A 机器就配置好了。

反向代理客户端

B 机器的配置将是 https 支持的重点：

[common]
# 这里填写 A 机器的 IP 或者域名
server_addr = 100.13.*.*
# 填写 A 机器开放的 frp 服务端口，也就是 frps.ini 配置文件中 bind_port 的值
server_port = 7000

[walterlv_example_http]
# 依然支持 http 访问
type = http
# 本地 Web 服务的端口
local_port = 10000
# 需要反向代理的域名（当访客通过此域名访问 A 机器时，才会将请求反向代理到此 Web 服务）
custom_domains = example.walterlv.com

[walterlv_example]
# 配置 https 访问
type = https
# 本地 Web 服务的端口（与前面的配置一样，都对应同一个 Web 服务）
local_port = 10000
# 需要反向代理的域名（当访客通过此域名访问 A 机器时，才会将请求反向代理到此 Web 服务）
custom_domains = example.walterlv.com

# 接下来的配置是支持 https 的重点配置
# 配置插件，将 https 请求转换成 http 请求后再发送给本地 Web 服务程序
plugin = https2http
# 转换成 http 后，发送到本机的 10000 端口
plugin_local_addr = 127.0.0.1:10000
# 可能是 frp 的 Bug？这里必须写成 127.0.0.1，稍后解释
plugin_host_header_rewrite = 127.0.0.1
# 指定代理方式为 frp
plugin_header_X-From-Where = frp
# 指定成你在前面部分导出的证书的路径
plugin_crt_path = C:/Samples/_.walterlv.com_chain.crt
plugin_key_path = C:/Samples/_.walterlv.com_key.key

这就是 frp 的特色，重点配置都放到了反向代理的客户端中。这样的配置方式安全性自然成了问题，但也正因为如此，才可以真正实现带有内网穿透的反向代理。

接下来介绍以下这个文件里面为什么是这样配置的。

[Common] 节点是为了与 frp 服务端取得联系的。所以 server_addr 和 server_port 自然成了必要，毕竟连接一个 Web 服务这是两个必要的参数。如果你的两个端部署在同一台电脑上，那么这里可以填写 127.0.0.1。

[walterlv_example_http] 节点和 [walterlv_example] 两个节点的名称是随便取的，不需要满足什么规律。唯一的要求是，连接到此 frp 服务端的所有客户端之间，这个名称都不能重复。frp 的服务端通过此名称来区分不同的客户端配置。因此，通常将这个名称命名成域名或者功能名。

[walterlv_example_http] 节点配置来兼容 http 访问。如果不配置这一个节点，那么使用 http 访问的访客将得到 frp 服务器返回的 403 状态码。这里的三项配置表示，如果使用 http 协议访问此 frp 服务端，且访问域名是 example.walterlv.com（http 头里写的），那么将此请求转发到 frp 客户端本机的 10000 端口。

[walterlv_example] 节点的前三项与 [walterlv_example_http] 一样，含义也是一样的。接下来就是启用 https2http 插件，将访问 frp 服务端的 https 流量全部转换成 http 流量，然后转发给本机的 http 服务。plugin_local_addr 就是指定转发到本机的 10000 端口。当然你也可以写成非本机的 http 服务，例如 walterlv.github.io:80，这样，https 流量转换成 http 流量后会发给对应的机器。plugin_host_header_rewrite 在目前（frp 0.31.1 版本），这个值必须写成 127.0.0.1，否则会出现错误的重定向（例如，如果指定成 example.walterlv.com 会导致流量回流到 frp 服务端，这绝对是反向代理的一个 Bug！）这个值的含义是修改 http 的请求头，将请求头中的域名部分改写成 127.0.0.1（在改写之前，头是 example.walterlv.com）。plugin_crt_path 和 plugin_key_path 指定为 SSL 证书的路径。plugin_header_X-From-Where 则不是必须的。

工作原理

使用 frp 让 Web 服务支持 https 的流程是一个典型的反向代理服务器的工作流程。

访客在浏览器中输入网址 https://blog.walterlv.com 后，浏览器会查询的 IP，查询到之后，向此 IP 的 443 端口发送 https 请求。frp 服务端收到此请求后检查访问的域名，发现曾经连接此 frp 服务端的一个客户端配置了此域名的反向代理。于是将请求转发给此客户端。frp 客户端在收到转发的 https 请求后，使用 SSL 证书将 https 解密成 http 请求，然后修改 http 头添加或修改额外的信息。最后，frp 客户端将修改后的 http 请求转发给本机的真正的 Web 服务程序。当 Web 服务程序处理完 Web 请求后，响应沿着原路返回。

这里值得注意的是，由于 frp 反向代理系统中，使用 SSL 证书的一端在 frp 客户端，这意味着 frp 服务端完全无法得知此 https 请求的内容。于是在转发后也无法得知此请求的真实来源（访客 IP），这样，真实的 Web 服务将无法得知真实的访客信息。这也是 frp 在此设计下必然出现的缺陷。

如果你希望你的 Web 服务在 https 下破除这些限制，那么建议使用其他的反向代理服务器。关于其他配置 https 的方法，你可以阅读：

除了 frp 以外的方法都可以获得真实的访客信息。

参考资料

frp/README_zh.md at master · fatedier/frp

为 ASP.NET Core 程序制作 URL 的 301/302 跳转

Sun, 12 Jan 2020 14:08:32 +0000

如果你有一些需要重定向网页 URL 的情况，可以返回 HTTP 状态码 301/302 告诉浏览器或者搜索引擎访问新的 URL。本文描述如何在 ASP.NET Core 中进行重定向。

HTTP 状态码 301/302

301 表示“Moved Permanently”，即永久移动。通过返回此状态码可以告知浏览器或者搜索引擎此 URL 已经永久移动到了新的 URL 地址。搜索引擎会使用新的 URL 来更新自己的搜索结果，而浏览器会将此 URL 重定向缓存起来，下次访问的时候直接使用新的 URL 来访问。

302 表示“Found”，发现；原始描述为“Moved Temporarily”，即临时移动。通过返回此状态码可以告知浏览器或者搜索引擎此 URL 临时移动到了新的 URL 地址。搜索引擎会使用此新的 URL 来抓取页面的内容但不会更新此 URL，而浏览器会访问新的 URL 但不会缓存此 URL 重定向。

还有其他的重定向的 HTTP 状态码：

303 See Other
307 Temporary Redirect
308 Permanent Redirect

301/302 本来设计为移动资源的时候保持方法不变，但各大浏览器在实现的时候对于 POST 方法，有的实现成了 GET 方法，有的实现成了 POST 方法。于是在后来的 HTTP 标准中将浏览器的错误实现变成了标准，301 和 302 方法要求使用 GET 方法重定向。不过由于历史原因无法保证一定是改用 GET 方法，所以增加了 303 状态码要求一定使用 GET 方法重定向。随后将原来本应该正确实现的 301 和 302 重新定义成 307 和 308 状态码，要求重定向时不允许修改方法。

ASP.NET Core

ASP.NET Core 的 Blazor 框架生成的页面在路由的时候是不识别 .html 后缀的，而带有 .html 后缀的 URL 会被识别为静态文件。于是，如果创建了一个空的 Blazor 应用，当访问 https://blog.walterlv.com/post/redirect-middleware-for-asp-dotnet.html 网址的时候，会返回 404 Not Found，而不是路由到我的博客页面。

如果我们将此 URL 重定向到不带后缀的 URL，则可以被 Blazor 框架识别并正确显示对应的博客页面。

我们有两个不同的方式来实现这种 URL 的重定向：

做一个重定向的控制器 Controller，然后在控制器中重定向所有的博客页面
做一个重定向的中间件，对所有包含 .html 后缀的博客页面重定向到没有 .html 后缀的博客页面

不过，写一个 Controller 会要求这个 Controller 路由到几乎所有的 URL 上，对其他功能很不利，所以中间件是最合适的方式。

重定向中间件

    public class Startup
    {
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
++          app.UseAutoRemoveHtmlExtension();
            app.UseEndpoints(endpoints =>
            {
                endpoints.MapBlazorHub();
                endpoints.MapFallbackToPage("/_Host");
            });
            app.UseStaticFiles();
        }
    }

在 Startup 类的 Configure 方法中可以添加中间件。为了实现去掉 .html 后缀的中间件，我添加了一个自己的扩展方法 UseAutoRemoveHtmlExtension。

/// <summary>
/// 自动移除所有的 .html 后缀，并永久重定向到没有 .html 后缀的网页。
/// </summary>
/// <param name="app"><see cref="IApplicationBuilder"/>。</param>
/// <returns><see cref="IApplicationBuilder"/>。</returns>
public static IApplicationBuilder UseAutoRemoveHtmlExtension(this IApplicationBuilder app) => app.Use(async (context, next) =>
{
    var urlPath = context.Request.Path.HasValue
        ? context.Request.Path.Value
        : "";
    if (urlPath.EndsWith(".html", StringComparison.OrdinalIgnoreCase))
    {
        // 去掉 .html 后缀
        var url = urlPath[0..^5];
        context.Response.Redirect(url);
        context.Response.StatusCode = 301;
        return;
    }
    await next().ConfigureAwait(false);
});

实现自己的中间件实际上直接调用 IApplicationBuilder 中的 Use 方法即可，传入一个委托用来在 URL 处理过程中添加一个步骤。

两个参数，context 中包含了本次请求的一些上下文，包括域名、URL 路径，返回的 HTTP 状态码。调用 context.Response.Redirect 方法可以进行 302 跳转。如果需要改成 301 跳转，则直接设置 context.Response.StatusCode 方法即可。

接下来，对于不需要重定向的网址，我们直接交给后面的中间件处理，调用 await next()。

重定向

如果你希望做其他种类的跳转，你也可以添加新的中间件，比如：

将 HTTP 重定向到 HTTPS（谷歌建议使用 301 跳转）
你可以在打开某个网页之前要求登录，于是做一个 302 跳转到登录页面；
你可以将一些已经过时的网页进行 301 跳转到新的网页；
- 比如我将一些之前不太规范的博客 URL 重定向到统一的格式；
你可以在迁移服务的时候临时做一个 302 跳转。

小心缓存

请注意，301 重定向会被浏览器缓存。也就是说如果你重定向到了一个错误的网址，那么再次访问的话浏览器将直接访问这个错误的网址。如果希望浏览器停止重定向到这个错误的网址，需要清除浏览器的缓存。所以使用 301 的时候需要谨慎一些。

参考资料

HTTP 302 - 维基百科，自由的百科全书

使用 Kestrel 为你的 ASP.NET Core 服务添加 https 支持

Sat, 11 Jan 2020 12:10:40 +0000

Kestrel 是一个跨平台的适用于 ASP.NET Core 的 Web 服务器。它内置集成在了 ASP.NET Core 项目模板中，所以编写和对外开放一个 Web 服务会非常简单。

虽然不推荐直接使用 Kestrel 对外提供 Web 服务，但为了简单的话，临时使用也是非常不错的选择。

Kestrel 是一个跨平台的适用于 ASP.NET Core 的 Web 服务器。

Kestrel 只是一个 Web 服务器，能够提供对外的 Web 服务；但它没有反向代理功能。也就是说当你使用 Kestrel 指定了一个端口后，这个端口的所有流量将被 Kestrel 处理，不能再与其他 Web 服务程序共用端口了。当然还有一些其他的原因（比如 Web 安全防护），所以通常并不推荐直接使用 Kestrel 对外提供 Web 服务。

但有一点——Kestrel 内置集成在了 ASP.NET Core 项目模板中，所以编写和对外开放一个 Web 服务会非常简单，这也使得 Kestrel 值得被临时使用一下。

配置 Kestrel

当你使用 dotnet 命令或者 Visual Studio 创建 ASP.NET Core 项目后，在 ConfigureWebHostDefaults 扩展方法的委托参数中，使用 webBuilder 对象可以用来配置 Kestrel 服务器。

    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
++              webBuilder.ConfigureKestrel(serverOptions =>
++              {
++                  // 在这里设置 Kestrel 的一些配置属性。
++              })
                .UseStartup<Startup>();
            });

配置 https

配置 Kestrel 时，只需要调用 serverOptions 的 Listen 方法设置监听的 IP 和端口。并且，可以额外写一个委托用来设置监听参数。

使用 listenOptions.UseHttps 即可使用 SSL 证书来支持 https 协议。

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.ConfigureKestrel(serverOptions =>
                {
++                  serverOptions.Listen(IPAddress.Any, 5000, listenOptions =>
++                  {
++                      listenOptions.UseHttps(
++                          @"D:\blog.walterlv.com\ssl\blog-walterlv-com.pfx",
++                          "Hqh#Q*QqV%@aCnx41UB%M31H");
++                  });
                })
                .UseStartup<Startup>();
            });

这种把密码写在代码中的做法一定要拖出去打！

不过我需要做博客中介绍以下这里是传入密码的，你可以采用其他的方式将密码存起来。比如放入 Windows 凭据管理器中，或者以其他加密的方式存在服务器/个人电脑上。

如果不指定证书，也可以使用 https，不过这使用的是默认的配置，只能用在 localhost 中。

另外，如果你还没有 SSL 证书，可以先阅读我的另一篇博客了解如何申请免费的 SSL 证书：

使用 freessl.org 为你的域名申请免费的 SSL 证书

至此，你的 ASP.NET Core 服务已经可以通过 https 对外提供服务了。

使用更强大的方法配置 https

其实我本不应该在博客后面贴上“更多配置”一章的，因为如果需要实现更强大的功能，配置带有反向代理功能的 Web 服务器会强大得多。

可以阅读：

参考资料

ASP.NET Core 中的 Kestrel Web 服务器实现 - Microsoft Docs

三种方法为 ASP.NET Core 对外服务添加 https 支持（kestrel / frp / nginx）

Sat, 11 Jan 2020 12:10:25 +0000

虽然使用 Visual Studio 创建 ASP.NET Core 程序的时候可以选择是否添加 https 支持，不过这种方式只添加了 localhost 的证书，只有本地访问时浏览器才会承认。真正对外公开服务的时候这样是绝对没法儿提供 https 服务的。

本文介绍使用三种不同的方式添加 https 的支持，三种方法各有优劣，本文会进行比较并给出不同的适用场景。你自己选择就好。

你需要有一个证书

如果你还没有证书，可以考虑去 https://freessl.org/ 免费申请一个。可以为泛域名申请 3 个月有效期的证书（Let’s Encrypt），或者为单域名申请 6 个月有效期的证书（buypass）。

如果不知道如何操作，可以参考我的另一篇博客：

使用 freessl.org 为你的域名申请免费的 SSL 证书

你可以在以上博客中得到四种不同格式的证书（Nginx/Apache/IIS/Tomcat），下面的方法中每一种方法会使用到其中的一种证书。

方法

实际上，只要是一个 Web 服务器就可以为 ASP.NET Core 服务程序提供 https 的支持，不过本文只会介绍下面这三种方法：

Kestrel
- 这是 ASP.NET Core 自带提供的 Web 服务器
Frp
- 这是一个开源即将收费的反向代理服务
Nginx
- 这是非常强大的 Web 服务器，同时也是强大的反向代理服务器

Kestrel 最简单，几句代码即可配完。Frp 相对来说也很简单。而 Nginx 非常强大，几乎适用于各种 Web 服务场景。

Nginx 支持 http2，Kestrel 的 Windows 和 Linux 版本支持 http2。

发现写成一篇博客会模糊这些方法之间的步骤，所以我将它们分别写成了几篇博客：

.NET 将多个程序集合并成单一程序集的 4+3 种方法

Fri, 10 Jan 2020 13:52:41 +0000

编写 .NET 程序的时候，我们经常会在项目的输出目录下发现一大堆的文件。除了我们项目自己生成的程序集之外，还能找到这个项目所依赖的一大堆依赖程序集。有没有什么方法可以把这些依赖和我们的程序集合并到一起呢？

本文介绍四种将程序集和依赖打包合并到一起的方法，每一种方法都有其不同的原理和优缺点。我将介绍这些方法的原理并帮助你决定哪种方法最适合你想要使用的场景。

四种方法

目前我已知的将 .NET 程序集与依赖合并到一起的方法有下面四种：

使用 .NET Core 3.0 自带的 PublishSingleFile 属性合并依赖
使用 Fody
使用 SourceYard 源代码包
使用 ILMerge（微软所写）或者 ILRepack（基于 Mono.Ceil）
其他方法

如果你还知道有其他的方法，欢迎评论指出，非常感谢！

上面的第五种方法我也会做一些介绍，要么是因为无法真正完成任务或者适用场景非常有限，要么是其原理我还不理解，因此只进行简单介绍。

使用 .NET Core 3.0 自带的 PublishSingleFile 属性合并依赖

.NET Core 3.0 自 Preview 5 开始，增加了发布成单一 exe 文件的功能。

在你的项目文件中增加下面的两行可以开启此功能：

    <Project Sdk="Microsoft.NET.Sdk">
    
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>netcoreapp3.0</TargetFramework>
++      <RuntimeIdentifier>win10-x64</RuntimeIdentifier>
++      <PublishSingleFile>true</PublishSingleFile>
      </PropertyGroup>
    
    </Project>

第一行 RuntimeIdentifier 一定需要指定，因为发布的单一文件是特定于架构的。这里，我们指定了 win10-x64，你也可以指定为其他的值。可以使用的值你可以在这篇文章中查询到：

.NET Core Runtime IDentifier (RID) catalog - Microsoft Docs

第二行 PublishSingleFile 即开启发布时单一文件的功能。这样，你在发布你的程序的时候可以得到一个单一的可执行程序。发布一个 .NET Core 项目的方法是在命令行中输入：

dotnet publish

当然，如果你没有更改任何你的项目文件（没有增加上面的那两行），那么你在使用发布命令的时候就需要把这两个属性再增加上。因此完整的发布命令是下面这样的：

dotnet publish -r win10-x64 /p:PublishSingleFile=true

这里的 -r 就等同于在项目中指定 RuntimeIdentifier 持续。这里的 /p 是在项目中增加一个属性，而增加的属性名是 PublishSingleFile，增加的属性值是 true。

使用 .NET Core 3.0 这种自带的发布单一 exe 的方法会将你的程序的全部文件（包括所有依赖文件，包括非托管程序集，包括各种资源文件）全部打包到一个 exe 中。当运行这个 exe 的时候，会首先将所有这些文件生成到本地计算机中一个临时目录下。只有第一次运行这个 exe 的时候才会生成这个目录和其中的文件，之后的运行是不会再次生成的。

下面说一些 .NET Core 3.0 发布程序集的一点扩展——.NET Core 3.0 中对于发布程序集的三种处理方式可以放在一起使用：

裁剪程序集（Assembly Trimmer）
提前编译（Ahead-of-Time compilation，通过 crossgen）后面马上会说到 Microsoft.DotNet.ILCompiler
单一文件打包（Single File Bundling）本小节

关于 .NET Core 3.0 中发布仅一个 exe 的方法、原理和实践，可以参见林德熙的博客：

dotnet core 发布只有一个 exe 的方法

.NET Core 在 GitHub 上开源：

.NET Foundation

使用 Fody

在你的项目中安装一个 NuGet 包 Costura.Fody。一般来说，安装完之后，你编译的时候就会生成仅有一个 exe 的程序集了。

如果你继续留意，可以发现项目中多了一个 Fody 的专属配置文件 FodyWeavers.xml，内容如下：

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

仅仅到此为止你已经足够利用 Fody 完成程序集的合并了。

但是，如果希望对 Fody 进行更精细化的配置，可以阅读叶洪的博客：

.NET 合并程序集（将 dll 合并到 exe 中） - Iron 的博客 - CSDN博客

Fody 在 GitHub 上开源：

Fody/Fody: Extensible tool for weaving .net assemblies

使用 SourceYard 源代码包

SourceYard 源代码包在程序集合并上是另辟蹊径的一种合并方式。它不能帮助你将所有的依赖全部合并，但足以让你在发布一些简单应用的时候不至于引入大量的依赖。

例如，你可以考虑新建一个项目，然后安装下面的 NuGet 包：

lindexi.src.MacAddress.Source

安装完成之后，你就可以在你的项目中使用到此 NuGet 包为你带来的获取 MAC 地址的工具类了。

using System;
using lindexi.src;

namespace Walterlv.Demo
{
    internal static class Program
    {
        static void Main()
        {
            var macList = MacAddress.GetActiveMacAddress();
            foreach (var mac in macList)
            {
                Console.WriteLine(mac);
            }
        }
    }
}

编译完你的项目，你会发现你的项目没有携带任何依赖。你安装的 NuGet 包并没有成为你的依赖，反而成为你正在编译的程序集的一部分。

如果你要制作一个像上面那样的源代码包，只需要在你要制作 NuGet 包的项目安装上 dotnetCampus.SourceYard，在你打包成 NuGet 包的时候，就会生成一个普通的 NuGet 包以及一个 *.Source.nupkg 的源代码包。将源代码包上传到 nuget.org 上，其他人便可以安装你制作的源代码包了。

关于如何使用 SourceYard 制作一个源代码包的方法可以阅读林德熙的博客：

SourceYard 制作源代码包

关于能够做出源代码包的原理，可以阅读我的博客：

SourceYard 在 GitHub 上开源：

dotnet-campus/SourceYard: Add a NuGet package only for dll reference? By using dotnetCampus.SourceYard, you can pack a NuGet package with source code. By installing the new source code package, all source codes behaviors just like it is in your project.

使用 ILMerge 或者 ILRepack 等工具

ILMerge 和 ILRepack 的合并就更加富有技术含量——当然坑也更多。

这两个都是工具，因此，你需要将工具下载下来使用。你有很多种方法下载到工具使用，因此我会推荐不同的人群使用不同的工具。

ILMerge

ILMerge 命令行工具是微软官方出品，下载地址：

Download ILMerge from Official Microsoft Download Center

其使用方法请参见我的博客：

.NET 使用 ILMerge 合并多个程序集，避免引入额外的依赖 - walterlv

ILRepack

ILRepack 基于 Mono.Ceil 来进行 IL 合并，其使用方法可以参见我的博客：

.NET 使用 ILRepack 合并多个程序集（替代 ILMerge），避免引入额外的依赖 - walterlv

ILMerge-GUI 工具（已过时，但适合新手随便玩玩）

你可以在以下网址中找到 ILMerge-GUI 的下载链接：

wvd-vegt / ilmergegui / Downloads — Bitbucket

ILMerge-GUI 工具在 Bitbucket 上开源：

wvd-vegt / ilmergegui — Bitbucket

其他方法

使用 Microsoft.DotNet.ILCompiler

可以将 .NET Core 编译为单个无依赖的 Native 程序。

你需要先安装一个预览版的 NuGet 包 Microsoft.DotNet.ILCompiler

关于 Microsoft.DotNet.ILCompiler 的使用，你可以阅读林德熙的博客：

dotnet core 使用 CoreRT 将程序编译为 Native 程序

使用 dnSpy

dnSpy 支持添加一个模块到程序集，也可以创建模块，还可以将程序集转换为模块。因此，一个程序集可以包含多个模块的功能就可以被充分利用起来。

使用 Warp

Warp 在 GitHub 上开源：

dgiagio/warp: Create self-contained single binary applications

其使用可以参见林德熙的博客：

dotnet core 发布只有一个 exe 的方法

各种方法的原理和使用场景比较

原理

使用 .NET Core 3.0 自带的 PublishSingleFile 属性合并依赖，其原理是生成一个启动器容器程序。最终没有对程序进行任何修改，只是单纯的打包而已。

使用 Fody，是将程序集依赖放到了资源里面。当要加载程序集的时候，会直接将资源中的程序集流加载到内存中。

使用 SourceYard 源代码包，是直接将源代码合并到了目标项目里面。

使用 ILMerge / ILRepack，是在 IL 级别对程序集进行了合并。

我们可以通过下面一张图来感受一下后三种原理上的不同。

这是一个分别通过 Fody、SourceYard 和 ILMerge / ILRepack 生成的程序集的反编译图。可以看到，对于 ILRepack / ILMerge 和 SourceYard，反编译后看到的源代码都在目标程序集中，而对于 Fody，依赖仅仅出现在资源中。

适用范围

由于其原理不同，所以其适用范围和造成的副作用也不同。

如果你基于 .NET Core 3.0 开发，并且也不在意在目标计算机上生成的临时文件夹，那么可以考虑使用 PublishSingleFile 属性合并依赖。

如果你不在乎启动性能以及内存消耗，那么可以考虑 Fody（这意味着小型程序比较适合采用）。

如果你的程序非常在乎启动性能，那么就需要考虑 SourceYard、ILMerge / ILRepack 了。

对于 ILMerge / ILRepack 和 SourceYard 的比较，可以看下面这张表格：

方案	ILRepack / ILMerge	SourceYard
适用于	任意 .NET 程序集	通过 SourceYard 发布的 NuGet 包
WPF	ILRepack 支持，ILMerge 不支持	支持
调试（支持）	仅支持一般方法的调试	支持一般程序集支持的所有调试方法
调试（不支持）	不支持异步方法调试，不支持显示局部变量	没有不支持的
隐藏 API	internal 的类型和成员可以隐藏	必须是 private 类型和成员才可隐藏

可以发现，如果我们能够充分将我们需要的包通过 SourceYard 发布成 NuGet，那么我们将可以获得比 ILRepack / ILMerge 更好的编写和调试体验。

表格之外还有一些特别需要说明的：

ILRepack 额外支持修改 WPF 编译生成的 Baml 文件，将资源的引用路径修改成新程序集的路径。
SourceYard 的类型需要写成 private 才可以隐藏，但是只有内部类才可以写 private，因此如果特别需要隐藏，请首先写一个内部类。（因此，你可能会发现有一个类型有很多个分部类，每一个分部类中都是一个私有的内部类）

开源社区

最后说一下，以上所说的所有方法全部是开源的，有问题欢迎在社区讨论一起解决：

.NET 中选择合适的文件打开模式（CreateNew, Create, Open, OpenOrCreate, Truncate, Append）

Wed, 08 Jan 2020 07:05:41 +0000

.NET 中文件打开的 API File.Open 提供了多种不同的文件打开方式，这些方式大多数与 Windows 文件 API 中的模式是对应的，但也有一些 .NET 层面的判断以及名称的变化。在 .NET 层你可以选择适合你业务场景需要的文件打开方式。

文件打开方式

文件打开的多个重载方法中，除了封装好的 OpenRead / OpenWrite 之外，其他都是需要指定 FileMode 参数的。

public static FileStream Open(string path, FileMode mode);

`FileMode`

FileMode 枚举有 6 种不同的值：

public enum FileMode
{
    CreateNew = 1,
    Create = 2,
    Open = 3,
    OpenOrCreate = 4,
    Truncate = 5,
    Append = 6,
}

为了方便查阅，我先将大家可能关心的内容做一个表格：

FileMode	如果文件存在	如果文件不存在
CreateNew	IOException	新建
Create	截断	新建
Open	打开	FileNotFoundException
OpenOrCreate	打开	新建
Truncate	截断	FileNotFoundException
Append	追加	新建

所有这些打开模式都不会修改到文件的属性（Attribute），包括创建时间、针对用户的权限设置。所以如果你希望连这些属性都不需要，而是完完全全创建新的文件，那么请先将原来的文件删除。

注意，在 File.Open 方法中传入以下这些参数的含义描述中可能有一些包含过程和判断的语句，但实际上这些真正的判断和过程发生在 Windows 内核（虽然 .NET 也有一些判断，但是一些参数预判断和参数转换），所以实际拿到文件流（对应 Win32 中拿到句柄）是一个原子操作，不会因为中间加了判断导致与其他线程发生竞争。

`CreateNew`

如果文件不存在，则创建一个新的文件并返回新文件的文件流。如果文件已经存在，则抛出 IOException。

`Create`

如果文件不存在，则创建一个新的文件并返回新文件的文件流。如果文件已经存在，则打开文件并返回此文件的文件流。

基于此文件流的修改会完全复写文件。也就是说，如果原文件内容是 walterlv，通过此文件流写入 111，那么最终文件内容是 111。

`Open`

如果文件存在，则打开文件并返回此文件的文件流。如果文件不存在，则抛出 FileNotFoundException。

基于此文件流的修改不会截断文件。也就是说，如果原文件内容是 walterlv，通过此文件流写入 111，那么最终文件内容是 111terlv。

`OpenOrCreate`

如果文件存在，则打开文件并返回此文件的文件流。如果文件不存在，则创建一个文件并返回新文件的文件流。

基于此文件流的修改不会截断文件。也就是说，如果原文件内容是 walterlv，通过此文件流写入 111，那么最终文件内容是 111terlv。

`Truncate`

如果文件存在，则打开后文件的长度直接变为 0，随后返回此文件的文件流。如果文件不存在，则会抛出 FileNotFoundException。

由于在打开文件时就已经将文件设置为 0 字节，所以对应到上面截断的描述是一定会截断的。写入任何新内容到文件候，文件中都不会存在旧文件中的内容。

`Append`

如果文件不存在，则创建一个新的文件并返回新文件的文件流。如果文件已经存在，则创建一个可以往文件的结尾处开始写的文件流。

如果试图从文件流中往前倒推找到此前的文件内容，会抛出 IOException。

配合文件打开权限

在以上这些 FileMode 中，CreateNew、Create、Truncate、Append 都是需要写文件的权限的，OpenOrCreate 是否需要写权限则取决于文件是否存在。

附源码

以下是 FileStream 中的 Open 方法最终调用处。可以发现，此方法将传入的 FileMode 转换成了 Win32 中的值，并且最终调用了 Windows API CreateFile。

你可以阅读我的另一篇博客了解 Win32 API 中的 CreateFile：

Win32 方法 CreateFile 中选择合适的文件打开模式（CREATE_NEW, CREATE_ALWAYS, OPEN_EXISTING, OPEN_ALWAYS, TRUNCATE_EXISTING） - walterlv

private unsafe SafeFileHandle CreateFileOpenHandle(FileMode mode, FileShare share, FileOptions options)
{
    Interop.Kernel32.SECURITY_ATTRIBUTES secAttrs = GetSecAttrs(share);

    int fAccess =
        ((_access & FileAccess.Read) == FileAccess.Read ? Interop.Kernel32.GenericOperations.GENERIC_READ : 0) |
        ((_access & FileAccess.Write) == FileAccess.Write ? Interop.Kernel32.GenericOperations.GENERIC_WRITE : 0);

    // Our Inheritable bit was stolen from Windows, but should be set in
    // the security attributes class.  Don't leave this bit set.
    share &= ~FileShare.Inheritable;

    // Must use a valid Win32 constant here...
    if (mode == FileMode.Append)
        mode = FileMode.OpenOrCreate;

    int flagsAndAttributes = (int)options;

    // For mitigating local elevation of privilege attack through named pipes
    // make sure we always call CreateFile with SECURITY_ANONYMOUS so that the
    // named pipe server can't impersonate a high privileged client security context
    // (note that this is the effective default on CreateFile2)
    flagsAndAttributes |= (Interop.Kernel32.SecurityOptions.SECURITY_SQOS_PRESENT | Interop.Kernel32.SecurityOptions.SECURITY_ANONYMOUS);

    using (DisableMediaInsertionPrompt.Create())
    {
        Debug.Assert(_path != null);
        return ValidateFileHandle(
            Interop.Kernel32.CreateFile(_path, fAccess, share, ref secAttrs, mode, flagsAndAttributes, IntPtr.Zero));
    }
}

// Contains constants for specifying how the OS should open a file.
// These will control whether you overwrite a file, open an existing
// file, or some combination thereof.
//
// To append to a file, use Append (which maps to OpenOrCreate then we seek
// to the end of the file).  To truncate a file or create it if it doesn't
// exist, use Create.
//
public enum FileMode
{
    // Creates a new file. An exception is raised if the file already exists.
    CreateNew = 1,

    // Creates a new file. If the file already exists, it is overwritten.
    Create = 2,

    // Opens an existing file. An exception is raised if the file does not exist.
    Open = 3,

    // Opens the file if it exists. Otherwise, creates a new file.
    OpenOrCreate = 4,

    // Opens an existing file. Once opened, the file is truncated so that its
    // size is zero bytes. The calling process must open the file with at least
    // WRITE access. An exception is raised if the file does not exist.
    Truncate = 5,

    // Opens the file if it exists and seeks to the end.  Otherwise,
    // creates a new file.
    Append = 6,
}

参考资料

FileMode Enum (System.IO) - Microsoft Docs

Win32 方法 CreateFile 中选择合适的文件打开模式（CREATE_NEW, CREATE_ALWAYS, OPEN_EXISTING, OPEN_ALWAYS, TRUNCATE_EXISTING）

Wed, 08 Jan 2020 07:05:12 +0000

Windows 打开文件的 API 中提供了多种不同的文件打开方式。你可以根据你的业务场景选择适合你的文件打开方式。

Windows API

OpenFile 方法只能打开已经存在的文件，而使用 CreateFile 则可以在打开文件的同时应对不存在文件时的创建。

HANDLE CreateFileW(
  LPCWSTR               lpFileName,
  DWORD                 dwDesiredAccess,
  DWORD                 dwShareMode,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  DWORD                 dwCreationDisposition,
  DWORD                 dwFlagsAndAttributes,
  HANDLE                hTemplateFile
);

其中 dwCreationDisposition 参数用来指定文件打开的时候如何处理文件的创建和追加行为。

`dwCreationDisposition`

dwCreationDisposition 可以传入 5 种不同的值。

CREATE_NEW
CREATE_ALWAYS
OPEN_EXISTING
OPEN_ALWAYS
TRUNCATE_EXISTING

为了方便查阅，我先将大家可能关心的内容做一个表格：

`dwCreationDisposition`	如果文件存在	如果文件不存在
`CREATE_NEW`	`ERROR_FILE_EXISTS`	新建
`CREATE_ALWAYS`	截断	新建
`OPEN_EXISTING`	打开	`ERROR_FILE_NOT_FOUND`
`OPEN_ALWAYS`	打开	新建
`TRUNCATE_EXISTING`	截断	`ERROR_FILE_NOT_FOUND`

`CREATE_NEW`

如果文件不存在，则创建一个文件。如果文件不存在，则执行失败，通过 GetLastError 可以得到错误码 ERROR_FILE_EXISTS (80)。

`CREATE_ALWAYS`

如果文件不存在，则创建一个新的文件。如果文件已经存在，则此文件将完全被复写。

基于此文件流的修改会完全复写文件。也就是说，如果原文件内容是 walterlv，通过此文件流写入 111，那么最终文件内容是 111。

`OPEN_EXISTING`

如果文件存在，则打开文件。如果文件不存在，通过 GetLastError 可以得到错误码 ERROR_FILE_NOT_FOUND (2)。

基于此文件流的修改不会截断文件。也就是说，如果原文件内容是 walterlv，通过此文件流写入 111，那么最终文件内容是 111terlv。

`OPEN_ALWAYS`

如果文件存在，那么会成功打开文件；并且也可以通过 GetLastError 可以得到状态 ERROR_ALREADY_EXISTS (183)。如果文件不存在，新建一个文件。

基于此文件流的修改不会截断文件。也就是说，如果原文件内容是 walterlv，通过此文件流写入 111，那么最终文件内容是 111terlv。

`TRUNCATE_EXISTING`

如果文件存在，则打开后文件的长度直接变为 0。如果文件不存在，通过 GetLastError 可以得到错误码 ERROR_FILE_NOT_FOUND (2)。

参考资料

CreateFileW function (fileapi.h) - Win32 apps - Microsoft Docs

WPF 中如何创建忽略 DPI 属性的图片

Wed, 08 Jan 2020 04:57:02 +0000

WPF 框架设计为与 DPI 无关，但你依然可能遇到 DPI 问题。尤其是 Image 控件显示的图片会根据图片 EXIF 中的 DPI 信息和屏幕 DPI 自动缩放图片。对于 UI 用图来说这是好事，但对于软件用户随便插入的图片来说就不是了——用户传入的图片可能是各种各样不统一的 DPI。因此这种 DPI 我们应该忽略。

解决方法

直接设置 Image 控件的大小是一个不错的方案，这在允许设置 Image 控件大小的场合下是可以使用的。如果你能设置，那么直接设置，这是最好的方法了。

除此之外，我们还可能可以尝试这些方法：

创建 BitmapImage 对象，根据当前屏幕的 DPI 值计算 DecodePixelWidth 和 DecodePixelHeight；
创建 DrawingImage 对象，直接按照 WPF 的坐标单位绘制图片原始像素大小的图片；
创建 Bitmap / WriteableBitmap 对象，重新创建一张 96 DPI 的图片。

以下的代码中，都假设当前 DPI 的值为 monitorDpi。

`DrawingImage`

DrawingImage 可以使用 WPF 的方式来绘制，不过如果要绘制位图，也需要一个 BitmapImage 对象，不过这个时候我们可以按照我们需要的尺寸进行绘制而不用关心 DPI 的问题。由于尺寸是在绘制的时候确定的，所以不需要 Image 控件也设置尺寸。

private static ImageSource CreateBitmapImage(Stream sourceStream)
{
    var bitmap = new BitmapImage();
    bitmap.BeginInit();
    bitmap.StreamSource = sourceStream;
    bitmap.EndInit();

    var image = new ImageDrawing(
        bitmap,
        new Rect(0, 0, bitmap.PixelWidth / monitorDpi.FactorX, bitmap.PixelHeight / monitorDpi.FactorY));
    var drawing = new DrawingImage(image);
    return drawing;
}

为什么不应该公开用来同步的加锁对象？为什么不应该 lock(this)/lock(string) 或者 lock 任何非私有对象？

Tue, 07 Jan 2020 01:29:31 +0000

如果你编写线程安全代码时为了省事儿直接 lock(this)，或者早已听说不应该 lock(this)，只是不知道原因，那么阅读本文可以帮助你了解原因。

原因

不应该 lock(this) 是因为你永远不知道别人会如何使用你的对象，永远不知道别人会在哪里加锁。于是稍不注意就可能死锁！

实例

看看下面的两段代码。

第一段是定义好的一个类，其中某个方法为了线程安全加了锁，但加锁的是 this 对象。

public class Foo
{
    public void DoSafety()
    {
        lock (this)
        {
            // 执行一些线程安全的事情。
        }
    }
}

第二段代码使用了这个类的一个实例。为了响应放到了后台线程中，但为了线程安全，加了锁。

public class Bar
{
    private readonly Foo _foo = new Foo();

    public async void DouB_Walterlv()
    {
        lock (_foo)
        {
            await Task.Run(() => _foo.DoSafety());
        }
    }
}

仔细看看这段代码，如果 DouB_Walterlv 方法执行，会发生什么？

—— 死锁

在 DouB_Walterlv 方法中完全看不出来为什么死锁，只能进入到 DoSafety 中才发现试图 lock 的 this 对象刚刚在另一个线程被 lock (_foo) 了。

扩展

从以上的例子可以看出，不止是 lock (this) 会出现“难以捉摸”的死锁问题，lock 任何公开对象都会这样。

lock 公开的属性

public class Foo
{
    public object SyncRoot { get; } = new object();
}

只要在 A 处 lock 这个对象的同时，在另一个线程调用了同样 lock 这个对象的 B 处的代码，必然死锁。

如果你试图实现某些接口中的 SyncRoot 属性，却遇到了上述矛盾（这样的写法不安全），那么可以阅读我的另一篇博客了解如何实现这样的“有问题”的接口：

为什么实现 .NET 的 ICollection 集合时需要实现 SyncRoot 属性？如何正确实现这个属性？

lock 字符串

你可以定义一个私有的字符串，但你永远不知道这个字符串是否与其他字符串是同一个实例。因此这也是不安全的。

lock 其他任何可能被其他对象获取的公开对象

比如 Type 对象，比如其他公共静态对象。

结论

所以，一旦你决定 lock，那么这个对象请做成 private。

如何在旧版本的 .NET Core / Framework 中使用 C# 8 的异步流（IAsyncDisposable / IAsyncEnumerable / IAsyncEnumerator）

Fri, 03 Jan 2020 09:17:34 +0000

C# 8.0 为我们带来了异步流，可以使用 async foreach，不过使用此语法需要 IAsyncEnumerable / IAsyncEnumerator 类型。本文介绍如何在旧版本的 .NET Framework 和旧版本的 .NET Core 中获得此类型。

异步流所需版本

异步流需要 .NET Core 3.0 及以上版本才能直接支持。而如果是 .NET Framework，则是任何版本都不直接支持。

如果需要在早期版本使用异步流，需要安装 Microsoft.Bcl.AsyncInterfaces 这个 NuGet 包。这就像在早期版本中使用 ValueTuple 需要安装 System.ValueTuple 一样。

安装 Microsoft.Bcl.AsyncInterfaces

需要先在你的项目中安装 NuGet 包：

Microsoft.Bcl.AsyncInterfaces

<PackageReference Include="Microsoft.Bcl.AsyncInterfaces" Version="1.1.0" />

安装此包之后，即可在你的项目当中开启异步流的支持。

一点说明：异步流中使用到了 ValueTask，此类型需要 System.Threading.Tasks.Extensions 包的支持。在 .NET Framework 4.8 以下会自动额外引入此包。

使用异步流

定义支持异步流的方法

private async IAsyncEnumerable<string> EnumerateTestsAsync()
{
    for (var i = 0; i < 3; i++)
    {
        await Task.Delay(100).ConfigureAwait(false);
        yield return $"欢迎访问吕毅的博客，第 {i} 页";
    }
}

使用 await foreach

直接使用 await foreach 即可使用 C# 8.0 带来的异步流。

var verify = 0;
await foreach (var i in EnumerateTestsAsync())
{
    Assert.AreEqual(verify, i);
    verify++;
}
Assert.AreEqual(3, verify);

额外说明

记得如果你在 .NET Framework 4.8 或以下版本，.NET Core 3.0 以下版本编写代码时，自动启用的 C# 语言版本是 7.3，所以你需要额外为你的项目启用 C# 8.0 才行。

<LangVersion>latest</LangVersion>

另外，由于 ValueTask 要求的最低 .NET Framework 版本为 4.5.2，所以如果使用更低版本的 .NET Framework，将无法使用异步流。

参考资料

.NET/C# 解压 Zip 文件时出现异常：System.IO.InvalidDataException: 找不到中央目录结尾记录。

Fri, 03 Jan 2020 09:12:52 +0000

在解压 Zip 文件时出现异常：System.IO.InvalidDataException: 找不到中央目录结尾记录。。

其原因是所解压的文件并非 zip 文件。

异常

在解压 Zip 文件时出现异常：

System.IO.InvalidDataException: 找不到中央目录结尾记录。
   在 System.IO.Compression.ZipArchive.ReadEndOfCentralDirectory()
   在 System.IO.Compression.ZipArchive.Init(Stream stream, ZipArchiveMode mode, Boolean leaveOpen)
   在 System.IO.Compression.ZipArchive..ctor(Stream stream, ZipArchiveMode mode, Boolean leaveOpen, Encoding entryNameEncoding)
   在 System.IO.Compression.ZipFile.Open(String archiveFileName, ZipArchiveMode mode, Encoding entryNameEncoding)
   在 System.IO.Compression.ZipFile.ExtractToDirectory(String sourceArchiveFileName, String destinationDirectoryName, Encoding entryNameEncoding)
   在 System.IO.Compression.ZipFile.ExtractToDirectory(String sourceArchiveFileName, String destinationDirectoryName)

原因

如果一个文件并非 zip 文件，那么在解压的时候就会出现此异常。例如，它下载不全，是损坏的；或者，它实际上是一个 rar 文件或者 7z 文件。

验证也非常简单，直接使用其他任何成熟的解压缩工具试着解压以下这个文件就可以。如果其他工具也不能解压，通常说明文件下载不全或者已损坏，或者下载的是一个被重定向了的 html 文件。如果其他工具能够正常解压，说明这可能是其他格式的压缩包，而不是 zip。

Windows 系统文件资源管理器的命令行参数（如何降权打开程序，如何选择文件）

Thu, 02 Jan 2020 03:05:18 +0000

大多数用户还是习惯使用 Windows 自带的文件资源管理器来管理文件，于是我们可以利用它的命令行参数来帮助我们做一些与之相关的交互。

本文会以实际的例子来说明如何使用 explorer.exe 的命令行参数。

打开文件

在命令行中输入 explorer D:\Services\blog.walterlv.com\test.txt 即可打开 test.txt 文件。不过，这个时候是间接使用文件资源管理器打开的文件，效果跟我们直接在文件资源管理器中双击打开这个文件的效果是一样的。

启动程序

实际上利用文件资源管理器启动程序和前面的打开文件是同一种命令，不过我特别拿出来说，是因为使用这种方式来启动程序还有一种特别的功效：

可以降权执行

使用方法：

explorer D:\Services\blog.walterlv.com\Walterlv.Blog.Home.exe

如果你当前进程是管理员权限，那么可以通过 explorer 间接启动将新启动的进程降低到与 explorer 同级别的权限。

不过，有几点需要注意的：

如果用来降权，那么只会降到与文件资源管理器同级别的权限
- 而文件资源管理器是什么权限在 Windows 7 上和 Windows 8/8.1/10 上不同
- Windows 8/8.1/10 无论开关 UAC 都是普通用户权限，除非你特别使用任务管理器（Task Manager）以管理员权限启动文件资源管理器
- Windows 7 在开启 UAC 的情况下，文件资源管理器是以普通用户权限运行的
- Windows 7 在关闭 UAC 的情况下，文件资源管理器是以管理员权限运行的
不允许给间接启动的程序携带命令行参数
- 如果你试图传入额外的参数，那么最终不会执行这个程序，只会打开一个根你的程序毫无关系的文件管理器的新窗口而已
explorer 必须是已经启动的状态（大多数时候都是这样）

关于利用文件资源管理器降权执行程序的内容，可以阅读我的另一篇博客：

在 Windows 系统上降低 UAC 权限运行程序（从管理员权限降权到普通用户权限） - walterlv

关于 UAC 权限相关的内容，可以阅读我的另一篇博客：

如果你使用 .NET 程序来完成启动程序的话，可能需要关注 UseShellExecute。不过利用 explorer 间接启动就无所谓了，无脑设置为 false 就好，因为它自己就相当于 Shell。

C#/.NET 中启动进程时所使用的 UseShellExecute 设置为 true 和 false 分别代表什么意思？ - walterlv

打开某个文件夹

explorer D:\Services\blog.walterlv.com

选择某个文件

在与其他工具集成的时候，如果有需求要打开某个文件夹，并自动滚动到希望看到的文件选中它，那么这个命令非常有用：

explorer /select,"D:\Services\blog.walterlv.com\Walterlv.Blog.Home.exe"

这可以在打开文件资源管理器的同时，选中 Walterlv.Blog.Home.exe 文件，并将它滚动到可视区域。

其他命令行参数

在以上这些命令的基础上，可以添加一些可选参数用来控制如何执行这些命令。

/separate
- 让文件资源管理器在一个新的进程中打开

一些特殊文件夹的命令

打开当前工作路径的根目录：

> explorer \

打开“文档”文件夹：

> explorer \\
# 或者
explorer /

打开“计算机”文件夹：

# 注意，此命令在 CMD 中可以直接执行，在 PowerShell 中需要加上引号，即 ","
explorer ,

参考资料

如何在 MSBuild 中正确使用 % 来引用每一个项（Item）中的元数据

Fri, 27 Dec 2019 09:45:37 +0000

MSBuild 中写在 <ItemGroup /> 中的每一项是一个 Item，Item 除了可以使用 Include/Update/Remove 来增删之外，还可以定义其他的元数据（Metadata）。

使用 % 可以引用 Item 的元数据，本文将介绍如何正确使用 % 来引用每一个项中的元数据。

定义 Item 的元数据

就像下面这样，当引用一个 NuGet 包时，可以额外使用 Version 来指定应该使用哪个特定版本的 NuGet 包。这里的 Version 和 PrivateAssets 就是 PackageReference 的元数据。

<ItemGroup>
    <PackageReference Include="dotnetCampus.Configurations.Source" Version="1.0.0" PrivateAssets="All" />
    <PackageReference Include="dotnetCampus.CommandLine.Source" Version="1.2.1" PrivateAssets="All" />
    <PackageReference Include="Walterlv.Win32.Source" Version="0.12.2-alpha" PrivateAssets="All" />
    <PackageReference Include="Walterlv.IO.PackageManagement.Source" Version="0.13.2-alpha" PrivateAssets="All" />
</ItemGroup>

我们随便创建一个新的 Item，也可以定义自己的元数据。

<ItemGroup>
    <_WalterlvItem Include="欢迎访问" Url="https://" />
    <_WalterlvItem Include="吕毅的博客" Url="blog.walterlv.com" />
</ItemGroup>

引用元数据

引用元数据使用的是 % 符号。

<Target Name="_WalterlvDemo" AfterTargets="AfterBuild">
    <ItemGroup>
        <_WalterlvItem Include="欢迎访问" Url="https://" />
        <_WalterlvItem Include="吕毅的博客" Url="blog.walterlv.com" />
    </ItemGroup>
    <Message Text="@(_WalterlvItem)：%(Url)" />
</Target>

虽然这里我们只写了一个 Message Task，但是最终我们会输出两次，每一个 _WalterlvItem 项都会输出一次。下面是这段代码的输出：

_WalterlvDemo:
  欢迎访问：https://
  吕毅的博客：blog.walterlv.com

当你使用 % 的时候，会为每一个项执行一次这行代码。当然，如果某个 Task 支持传入集合，那么则可以直接收到集合。

如果你不是用的 Message，而是定义一个其他的属性，使用 @(_WalterlvItem)：%(Url) 作为属性的值，那么这个属性也会为每一个项都计算一次值。当然最终这个属性的值就是最后一项计算所得的值。

也许可以帮你回忆一下，如果我们不写 %(Url) 会输出什么。当只输出 @(WalterlvItem) 的时候，会以普通的分号分隔的文字。

<Target Name="_WalterlvDemo" AfterTargets="AfterBuild">
    <ItemGroup>
        <_WalterlvItem Include="欢迎访问" Url="https://" />
        <_WalterlvItem Include="吕毅的博客" Url="blog.walterlv.com" />
    </ItemGroup>
    <Message Text="@(_WalterlvItem)" />
</Target>

会输出：

_WalterlvDemo:
  欢迎访问;吕毅的博客

使用元数据

如果你希望自己处理编译过程，那么可能会对元数据做更多的处理。

为了简单说明 % 的用法，我将已收集到的所有的元数据和它的本体一起输出到一个文件中。这样，后续的编译过程可以直接使用这个文件来获得所有的项和你希望关心它的所有元数据。

<PropertyGroup>
    <_WalterlvContentArgsFilePath>$(IntermediateOutputPath)Args\Content.txt</_WalterlvContentArgsFilePath>
    <_WalterlvToolFile>$(MSBuildThisFileDirectory)..\bin\compile.exe</_WalterlvContentArgsFilePath>
</PropertyGroup>

<Target Name="_WalterlvDemo" AfterTargets="AfterBuild">
    <ItemGroup>
        <_WalterlvContentFileLine Include="@(Content)" Line="@(Content)|%(Content.PublishState)|%(Content.CopyToOutputDirectory)" />
    </ItemGroup>
    <WriteLinesToFile File="$(_WalterlvContentArgsFilePath)" Lines="%(_WalterlvContentFileLine.Line)" Overwrite="True" />
    <Exec ConsoleToMSBuild="True"
          Command="&quot;$(_WalterlvToolFile)&quot; PackContent --content-file &quot; $(_WalterlvContentArgsFilePath) &quot;" />
</Target>

这段代码的含义是：

定义一个文件路径，这个路径即将用来存放所有 Content 项和它的元数据；
定义一个工具路径，我们即将运行这个路径下的命令行程序来执行自定义的编译；
收集所有的 Content 项，然后把所有项中的 PublishState 和 CopyToOutputDirectory 一起拼接成这个样子：
- Content|PublishState|CopyToOutputDirectory
写文件，将以上拼接出来的每一项写入到文件中的每一行；
执行工具程序，这个程序将使用这个文件来执行自定义的编译。

关于使用 exe 进行自定义编译的部分可以参考我的另一篇博客：

如何创建一个基于命令行工具的跨平台的 NuGet 工具包 - walterlv

关于写文件的部分可以参考我的另一篇博客：

在 MSBuild 编译过程中操作文件和文件夹（检查存在/创建文件夹/读写文件/移动文件/复制文件/删除文件夹） - walterlv

关于项元数据的其他信息

一些已知的元数据：

MSBuild Well-known Item Metadata - Visual Studio - Microsoft Docs

参考资料

MSBuild Items - Visual Studio - Microsoft Docs

在 MSBuild 编译过程中操作文件和文件夹（检查存在/创建文件夹/读写文件/移动文件/复制文件/删除文件夹）

Fri, 27 Dec 2019 09:34:18 +0000

本文整理 MSBuild 在编译过程中对文件和文件夹处理的各种自带的编译任务（Task）。

`Exists` 检查文件存在

使用 Exists 可以判断一个文件或者文件夹是否存在。注意无论是文件还是文件夹，只要给定的路径存在就返回 true。可以作为 MSBuild 属性、项和编译任务的执行条件。

<PropertyGroup Condition=" Exists( '$(MSBuildThisFileDirectory)..\build\build.xml' ) ">
    <_WalterlvPackingDirectory>$(MSBuildThisFileDirectory)..\bin\$(Configuration)\</_WalterlvPackingDirectory>
</PropertyGroup>

`MakeDir` 创建文件夹

下面的例子演示创建一个文件夹：

<Target Name="_WalterlvCreateDirectoryForPacking">
    <MakeDir Directories="$(MSBuildThisFileDirectory)..\bin\$(Configuration)\" />
</Target>

下面是使用到 MakeDir 全部属性的例子，将已经成功创建的文件夹提取出来。

<Target Name="_WalterlvCreateDirectoryForPacking">
    <MakeDir Directories="$(MSBuildThisFileDirectory)..\bin\$(Configuration)\">
        <Output TaskParameter="DirectoriesCreated" PropertyName="CreatedPackingDirectory" />
    </MakeDir>
</Target>

`Move` 移动文件

下面的例子是将输出文件移动到一个专门的目录中，移动后，所有的文件将平级地在输出文件夹中（即所有的子文件夹中的文件也都被移动到同一层目录中了）。

<PropertyGroup>
    <_WalterlvPackingDirectory>$(MSBuildThisFileDirectory)..\bin\$(Configuration)\</_WalterlvPackingDirectory>
</PropertyGroup>

<Target Name="_WalterlvMoveFilesForPacking">
    <ItemGroup>
        <_WalterlvToMoveFile Include="$(OutputPath)**" />
    </ItemGroup>
    <Move SourceFiles="@(_WalterlvToMoveFile)"
          DestinationFolder="$(_WalterlvPackingDirectory)"
          SkipUnchangedFiles="True" />
</Target>

你可以通过下面的例子了解到 Move 的其他大多数属性及其用法：

<PropertyGroup>
    <_WalterlvPackingDirectory>$(MSBuildThisFileDirectory)..\bin\$(Configuration)\</_WalterlvPackingDirectory>
</PropertyGroup>

<Target Name="_WalterlvMoveFilesForPacking">
    <ItemGroup>
        <_WalterlvToMoveFile Include="$(OutputPath)**" />
        <_WalterlvTargetFile Include="$(_WalterlvPackingDirectory)\%(_WalterlvToMoveFile.RecursiveDir)" />
    </ItemGroup>
    <Move SourceFiles="@(_WalterlvToMoveFile)"
          DestinationFiles="$(_WalterlvTargetFile)"
          OverwriteReadOnlyFiles="True">
        <Output TaskParameter="MovedFiles" PropertyName="MovedOutputFiles" />
    </Copy>
</Target>

这段代码除了没有使用 DestinationFolder 之外，使用到了所有 Move 能用的属性：

将所有的 _WalterlvToCopyFile 一对一地复制到 _WalterlvTargetFile 指定的路径上。
即便目标文件是只读的，也会覆盖。

`Copy` 复制文件

下面的例子是将输出文件拷贝到一个专门的目录中，保留原来所有文件之间的目录结构，并且如果文件没有改变则跳过。

<PropertyGroup>
    <_WalterlvPackingDirectory>$(MSBuildThisFileDirectory)..\bin\$(Configuration)\</_WalterlvPackingDirectory>
</PropertyGroup>

<Target Name="_WalterlvCopyFilesForPacking">
    <ItemGroup>
        <_WalterlvToCopyFile Include="$(OutputPath)**" />
    </ItemGroup>
    <Copy SourceFiles="@(_WalterlvToCopyFile)"
          DestinationFolder="$(_WalterlvPackingDirectory)\%(RecursiveDir)"
          SkipUnchangedFiles="True" />
</Target>

如果你希望复制后所有的文件都在同一级文件夹中，不再有子文件夹，那么去掉 \%(RecursiveDir)。

你可以通过下面的例子了解到 Copy 的其他大多数属性及其用法：

<PropertyGroup>
    <_WalterlvPackingDirectory>$(MSBuildThisFileDirectory)..\bin\$(Configuration)\</_WalterlvPackingDirectory>
</PropertyGroup>

<Target Name="_WalterlvCopyFilesForPacking">
    <ItemGroup>
        <_WalterlvToCopyFile Include="$(OutputPath)**" />
        <_WalterlvTargetFile Include="$(_WalterlvPackingDirectory)\%(_WalterlvToCopyFile.RecursiveDir)" />
    </ItemGroup>
    <Copy SourceFiles="@(_WalterlvToCopyFile)"
          DestinationFiles="@(_WalterlvTargetFile)"
          OverwriteReadOnlyFiles="True"
          Retries="10"
          RetryDelayMilliseconds="10"
          SkipUnchangedFiles="True"
          UseHardlinksIfPossible="True">
        <Output TaskParameter="CopiedFiles" PropertyName="CopiedOutputFiles" />
    </Copy>
</Target>

这段代码除了没有使用 DestinationFolder 之外，使用到了所有 Copy 能用的属性：

将所有的 _WalterlvToCopyFile 一对一地复制到 _WalterlvTargetFile 指定的路径上。
即便目标文件是只读的，也会覆盖。
如果复制失败，则重试 10 次，每次等待 10 毫秒
如果文件没有改变，则跳过复制
如果目标文件系统支持硬连接，则使用硬连接来提升性能

`Delete` 删除文件

下面这个例子是删除输出目录下的所有的 pdb 文件（适合 release 下发布软件）。

<Target Name="_WalterlvDeleteFiles">
    <Delete Files="$(OutputPath)*.pdb" />
</Target>

也可以把此操作已经删除的文件列表拿出来。使用全部属性的 Delete 的例子：

<Target Name="_WalterlvDeleteFiles">
    <Delete Files="$(OutputPath)*.pdb" TreatErrorsAsWarnings="True">
        <Output TaskParameter="DeletedFiles" PropertyName="DeletedPdbFiles" />
    </Delete>
</Target>

`ReadLinesFromFile` 读取文件

在编译期间，可以从文件中读出文件的每一行：

<PropertyGroup>
    <_WalterlvToWriteFile>$(OutputPath)walterlv.md</_WalterlvToWriteFile>
</PropertyGroup>

<Target Name="_WalterlvReadFilesToLines">
    <ReadLinesFromFile File="$(_WalterlvToWriteFile)">
        <Output TaskParameter="Lines" PropertyName="TheLinesThatRead" />
    </ReadLinesFromFile>
</Target>

`WriteLinesToFile` 写入文件

可以在编译期间，将一些信息写到文件中以便后续编译的时候使用，甚至将代码写到文件中以便动态生成代码。

<PropertyGroup>
    <_WalterlvBlogSite>https://blog.walterlv.com</_WalterlvBlogSite>
    <_WalterlvToWriteFile>$(OutputPath)walterlv.md</_WalterlvToWriteFile>
</PropertyGroup>

<ItemGroup>
    <_WalterlvToWriteLine Include="This is the first line" />
    <_WalterlvToWriteLine Include="This is the second line" />
    <_WalterlvToWriteLine Include="My blog site is: $(_WalterlvBlogSite)" />
</ItemGroup>

<Target Name="_WalterlvWriteFilesForPacking">
    <WriteLinesToFile File="$(_WalterlvToWriteFile)"
                      Lines="@(_WalterlvToWriteLine)" />
</Target>

▲ 注意，默认写入文件是不会覆盖的，会将内容补充到原来文件的后面。

<Target Name="_WalterlvWriteFilesForPacking">
    <WriteLinesToFile File="$(_WalterlvToWriteFile)"
                      Lines="@(_WalterlvToWriteLine)"
                      Overwrite="True"
                      Encoding="Unicode"
                      WriteOnlyWhenDifferent="True" />
</Target>

`RemoveDir` 删除文件夹

在编写编译命令的时候，可能会涉及到清理资源。或者为了避免无关文件的影响，在编译之前删除我们的工作目录。

<Target Name="_WalterlvRemoveDirectoryForPacking">
    <RemoveDir Directories="$(MSBuildThisFileDirectory)..\bin\$(Configuration)\" />
</Target>

下面是使用到 MakeDir 全部属性的例子，将已经成功创建的文件夹提取出来。

<Target Name="_WalterlvRemoveDirectoryForPacking">
    <RemoveDir Directories="$(MSBuildThisFileDirectory)..\bin\$(Configuration)\">
        <Output TaskParameter="RemovedDirectories" PropertyName="RemovedPackingDirectory" />
    </RemoveDir>
</Target>

如何在 .NET/C# 代码中安全地结束掉一个控制台应用程序？通过发送 Ctrl+C 信号来结束

Thu, 26 Dec 2019 06:16:11 +0000

我的电脑上每天会跑一大堆控制台程序，于是管理这些程序的运行就成了一个问题。或者说你可能也在考虑启动一个控制台程序来完成某些特定的任务。

如果我们需要结束掉这个控制台程序怎么做呢？直接杀进程吗？这样很容易出问题。我正在使用的一个控制台程序会写文件，如果直接杀进程可能导致数据没能写入到文件。所以本文介绍如何使用 .NET/C# 代码向控制台程序发送 Ctrl+C 来安全地结束掉程序。

用 Ctrl+C 结束控制台程序

如果直接用 Process.Kill 杀掉进程，进程可能来不及保存数据。所以无论是窗口程序还是控制台程序，最好都让控制台程序自己去关闭。

▲ 使用 Process.Kill 结束程序，程序退出代码是 -1

▲ 使用 Ctrl+C 结束程序，程序退出代码是 0

Ctrl+C 信号

Windows API 提供了方法可以将当前进程与目标控制台进程关联起来，这样我们便可以向自己发送 Ctrl+C 信号来结束掉关联的另一个控制台进程。

关联和取消关联的方法是下面这两个，AttachConsole 和 FreeConsole：

[DllImport("kernel32.dll")]
private static extern bool AttachConsole(uint dwProcessId);

[DllImport("kernel32.dll")]
private static extern bool FreeConsole();

不过，当发送 Ctrl+C 信号的时候，不止我们希望关闭的控制台程序退出了，我们自己程序也是会退出的（即便我们自己是一个 GUI 程序）。所以我们必须先组织自己响应 Ctrl+C 信号。

需要用到另外一个 API：

[DllImport("kernel32.dll")]
private static extern bool SetConsoleCtrlHandler(ConsoleCtrlDelegate? HandlerRoutine, bool Add);

enum CtrlTypes : uint
{
    CTRL_C_EVENT = 0,
    CTRL_BREAK_EVENT,
    CTRL_CLOSE_EVENT,
    CTRL_LOGOFF_EVENT = 5,
    CTRL_SHUTDOWN_EVENT
}

private delegate bool ConsoleCtrlDelegate(CtrlTypes CtrlType);

不过，因为我们实际上并不需要真的对 Ctrl+C 进行响应，只是单纯临时禁用以下，所以我们归这个委托传入 null 就好了。

最后，也是最关键的，就是发送 Ctrl+C 信号了：

[DllImport("kernel32.dll")]
[return: MarshalAs(UnmanagedType.Bool)]
private static extern bool GenerateConsoleCtrlEvent(CtrlTypes dwCtrlEvent, uint dwProcessGroupId);

下面，我将完整的代码贴出来。

全部源代码

using System;
using System.Diagnostics;
using System.Runtime.InteropServices;

namespace Walterlv.Fracture.Utils
{
    /// <summary>
    /// 提供与控制台程序的交互。
    /// </summary>
    public class ConsoleInterop
    {
        /// <summary>
        /// 关闭控制台程序。
        /// </summary>
        /// <param name="process">要关闭的控制台程序的进程实例。</param>
        /// <param name="timeoutInMilliseconds">如果不希望一直等待进程自己退出，则可以在此参数中设置超时。你可以在超时未推出候采取强制杀掉进程的策略。</param>
        /// <returns>如果进程成功退出，则返回 true；否则返回 false。</returns>
        public static bool StopConsoleProgram(Process process, int? timeoutInMilliseconds = null)
        {
            if (process is null)
            {
                throw new ArgumentNullException(nameof(process));
            }

            if (process.HasExited)
            {
                return true;
            }

            // 尝试将我们自己的进程附加到指定进程的控制台（如果有的话）。
            if (AttachConsole((uint)process.Id))
            {
                // 我们自己的进程需要忽略掉 Ctrl+C 信号，否则自己也会退出。
                SetConsoleCtrlHandler(null, true);

                // 将 Ctrl+C 信号发送到前面已关联（附加）的控制台进程中。
                GenerateConsoleCtrlEvent(CtrlTypes.CTRL_C_EVENT, 0);

                // 拾前面已经附加的控制台。
                FreeConsole();

                bool hasExited;
                // 由于 Ctrl+C 信号只是通知程序关闭，并不一定真的关闭。所以我们等待一定时间，如果仍未关闭，则超时不处理。
                // 业务可以通过判断返回值来角是否进行后续处理（例如强制杀掉）。
                if (timeoutInMilliseconds == null)
                {
                    // 如果没有超时处理，则一直等待，直到最终进程停止。
                    process.WaitForExit();
                    hasExited = true;
                }
                else
                {
                    // 如果有超时处理，则超时候返回。
                    hasExited = process.WaitForExit(timeoutInMilliseconds.Value);
                }

                // 重新恢复我们自己的进程对 Ctrl+C 信号的响应。
                SetConsoleCtrlHandler(null, false);

                return hasExited;
            }
            else
            {
                return false;
            }
        }

        [DllImport("kernel32.dll")]
        private static extern bool AttachConsole(uint dwProcessId);

        [DllImport("kernel32.dll")]
        private static extern bool FreeConsole();

        [DllImport("kernel32.dll")]
        private static extern bool SetConsoleCtrlHandler(ConsoleCtrlDelegate? HandlerRoutine, bool Add);

        [DllImport("kernel32.dll")]
        [return: MarshalAs(UnmanagedType.Bool)]
        private static extern bool GenerateConsoleCtrlEvent(CtrlTypes dwCtrlEvent, uint dwProcessGroupId);

        enum CtrlTypes : uint
        {
            CTRL_C_EVENT = 0,
            CTRL_BREAK_EVENT,
            CTRL_CLOSE_EVENT,
            CTRL_LOGOFF_EVENT = 5,
            CTRL_SHUTDOWN_EVENT
        }

        private delegate bool ConsoleCtrlDelegate(CtrlTypes CtrlType);
    }
}

如何使用

现在，我们可以通过调用 ConsoleInterop.StopConsoleProgram(process) 来安全地结束掉一个控制台程序。

当然，为了处理一些意外的情况，我把超时也加上了。下面的用法演示超时 2 秒候程序还没有退出，则强杀。

if (!ConsoleInterop.StopConsoleProgram(process, 2000))
{
    try
    {
        process.Kill();
    }
    catch (InvalidOperationException e)
    {
    }
}

参考资料

如何将一个 .NET 对象序列化为 HTTP GET 的请求字符串

Mon, 23 Dec 2019 10:45:19 +0000

HTTP GET 请求时携带的参数直接在 URL 中，形式如 ?key1=value&key2=value&key3=value。如果是 POST 请求时，我们可以使用一些库序列化为 json 格式作为 BODY 发送，那么 GET 请求呢？有可以直接将其序列化为 HTTP GET 请求的 query 字符串的吗？

HTTP GET 请求

一个典型的 HTTP GET 请求带参数的话大概是这样的：

https://s.blog.walterlv.com/api/example?key1=value&key2=value&key3=value

于是我们将一个类型序列化为后面的参数：

[DataContract]
public class Foo
{
    [DataMember(Name = "key1")]
    public string? Key1 { get; set; }

    [DataMember(Name = "key2")]
    public string? Key2 { get; set; }

    [DataMember(Name = "key3")]
    public string? Key3 { get; set; }
}

库？

可能是这个需求太简单了，所以并没有找到单独的库。所以我就写了一个源代码包放到了 nuget.org 上。

在这里下载源代码包：

Walterlv.Web.Source

你不需要担心引入额外的依赖，因为这是一个源代码包。关于源代码包不引入额外依赖 dll 的原理，可以参见：

.NET 将多个程序集合并成单一程序集的 4+3 种方法 - walterlv

方法

我们需要做的是，将一个对象序列化为 query 字符串。假设这个对象的局部变量名称是 query，于是我们需要：

取得此对象所有可获取值的属性
- query.GetType().GetProperties()
获取此属性值的方法
- property.GetValue(query, null)
将属性和值拼接起来
- string.Join("&", properties)

然而真实场景可能比这个稍微复杂一点：

我们需要像 Newtonsoft.Json 一样，对于标记了 DataContract 的类，按照 DataMember 来序列化
URL 中的值需要进行转义

所以，我写出了下面的方法：

var isContractedType = query.GetType().IsDefined(typeof(DataContractAttribute));
var properties = from property in query.GetType().GetProperties()
                    where property.CanRead && (isContractedType ? property.IsDefined(typeof(DataMemberAttribute)) : true)
                    let memberName = isContractedType ? property.GetCustomAttribute<DataMemberAttribute>().Name : property.Name
                    let value = property.GetValue(query, null)
                    where value != null && !string.IsNullOrWhiteSpace(value.ToString())
                    select memberName + "=" + HttpUtility.UrlEncode(value.ToString());
var queryString = string.Join("&", properties);
return string.IsNullOrWhiteSpace(queryString) ? "" : prefix + queryString;

完整的代码如下：

using System.Diagnostics.CodeAnalysis;
using System.Linq;
using System.Reflection;
using System.Runtime.Serialization;
using System.Web;

namespace Walterlv.Web.Core
{
    internal class QueryString
    {
        [return: NotNullIfNotNull("query")]
        public static string? Serialize(object? query, string? prefix = "?")
        {
            if (query is null)
            {
                return null;
            }

            var isContractedType = query.GetType().IsDefined(typeof(DataContractAttribute));
            var properties = from property in query.GetType().GetProperties()
                             where property.CanRead && (isContractedType ? property.IsDefined(typeof(DataMemberAttribute)) : true)
                             let memberName = isContractedType ? property.GetCustomAttribute<DataMemberAttribute>().Name : property.Name
                             let value = property.GetValue(query, null)
                             where value != null && !string.IsNullOrWhiteSpace(value.ToString())
                             select memberName + "=" + HttpUtility.UrlEncode(value.ToString());
            var queryString = string.Join("&", properties);
            return string.IsNullOrWhiteSpace(queryString) ? "" : prefix + queryString;
        }
    }
}

你可能会遇到 [return: NotNullIfNotNull("query")] 这一行编译不通过的情况，这个是 C# 8.0 带的可空引用类型所需要的契约类。

你可以将它删除，或者安装我的另一个 NuGet 包来获得更多可空引用类型契约的支持，详见：

C# 8.0 的可空引用类型，不止是加个问号哦！你还有很多种不同的可空玩法 - walterlv

屏幕边缘上有趣的 1 个像素，看不见、摸不到

Mon, 23 Dec 2019 08:00:30 +0000

如果你的屏幕分辨率是 1920×1080，那么一个全屏的窗口程序尺寸是多少呢？想都不用想，是 1920×1080。

那么输入设备输入的坐标是多少呢？是 X∈[0, 1919] ？还是 X∈[1, 1920] ？还是 X∈[0, 1920] ？

鼠标输入与触摸输入

一个有趣的问题，因为 1920×1080 分辨率的屏幕，其横向只有 1920 个像素，也就是说如果需要区分一个像素，那么只需要 1920 个数值就够了。这意味着 X∈[0, 1919] 或者 X∈[1, 1920] 的取值范围就能表示横向的所有像素了。

那么实际上最左侧的点的输入数值是多少呢？最右侧的点的输入数值是多少呢？

我写了一个最大化全屏的程序专门用来测试鼠标和触摸输入的数值是多少。

▲ 在鼠标输入的情况下，最右侧其实是 1919（我的屏幕是 2560×1080，所以最右侧是 2559）

测量的时候，鼠标是直接往右移动到底，移到不能动为止。

那么在触摸输入的时候又如何？

▲ 在触摸输入的情况下，最右侧是 1920（我的屏幕是 2560×1080，所以最右侧是 2560）

测量的时候，是让手指近乎在屏幕外触摸，不断触摸到能够在屏幕上看到的最小或最大值为止。

有趣的 1 像素

发现上面实验中有趣的现象了吗？明明只有 1920×1080 的屏幕分辨率，窗口明明只有 1920×1080 那么大，鼠标下收到正常范围内的输入坐标，而触摸下我们能收到超出我们窗口大小 1 像素的触摸事件！

问题并没有完——

如果说，触摸给了你超出窗口大小的坐标，那么你能如何使用这个坐标呢？虽然程序里收到什么坐标都无所谓（至少不崩），但如果你真拿它来渲染，就会在屏幕之外。

更有趣的是，虽然你能收到这个“在屏幕边缘之外”的坐标，但这个消息并不总会发送到你的程序里。更多的时候，你的程序根本就不会收到这个触摸事件，于是我们也就不能在程序里面更新窗口上显示的坐标到 1920 了，就像鼠标一样。

于是，你可能遇到的问题是：

如果你在屏幕的左侧边缘触摸，你的程序可以一直收到触摸事件，你能够得到正确的响应；
如果你在屏幕的右侧边缘触摸，你将仅能偶尔收到零星的刚好超出窗口大小的触摸坐标，大多数时候收不到触摸事件，于是你可能无法获知用户在屏幕右侧边缘进行触摸。

防踩坑秘籍

林德熙小伙伴告诉我说可以特意把窗口的尺寸做大一个像素。我试过了，确实能够让触摸在整个屏幕上生效，但对于双屏用户来说，就能在另外一个屏幕上看到“露馅儿”了的窗口，对于我这种强迫症患者来说，显然是不能接受的。

我的建议是，并不需要对这种情况进行什么特殊的处理。

使用 MSBuild Target 复制文件的时候如何保持文件夹结构不变

Tue, 17 Dec 2019 08:36:39 +0000

使用 MSBuild 中的 Copy 这个编译目标可以在 .NET 项目编译期间复制一些文件。不过使用默认的参数复制的时候文件夹结构会丢失，所有的文件会保留在同一级文件夹下。

那么如何在复制文件的时候保持文件夹结构与原文件夹结构一样呢？

Copy

下面是一个典型的使用 MSBuild 在编译期间复制文件的一个编译目标。

<Target Name="_WalterlvCopyDemo" AfterTargets="AfterBuild">
  <ItemGroup>
    <_WalterlvToCopyFile Include="$(OutputPath)**" />
  </ItemGroup>
  <Copy SourceFiles="@(_WalterlvToCopyFile)" DestinationFolder="bin\Debug\Test" SkipUnchangedFiles="True" />
</Target>

这样复制的文件是不会保留文件夹结构的。

复制之后，所有的文件夹将不存在，所有文件覆盖地到同一层级。

RecursiveDir

如果希望保留文件夹层级，可以在 DestinationFolder 中使用文件路径来替代文件夹路径。

  <Target Name="_WalterlvCopyDemo" AfterTargets="AfterBuild">
    <ItemGroup>
      <_WalterlvToCopyFile Include="$(OutputPath)**" />
    </ItemGroup>
-   <Copy SourceFiles="@(_WalterlvToCopyFile)" DestinationFolder="bin\Debug\Test" SkipUnchangedFiles="True" />
+   <Copy SourceFiles="@(_WalterlvToCopyFile)" DestinationFolder="bin\Debug\Test\%(RecursiveDir)" SkipUnchangedFiles="True" />
  </Target>

使用正则表达式尽可能准确匹配域名/网址

Mon, 09 Dec 2019 08:58:13 +0000

你可能需要准确地知道一段字符串是否是域名/网址/URL。虽然可以使用 .、/ 这些来模糊匹配，但会造成误判。

实际上单纯使用正则表达式来精确匹配也是非常复杂的，通过代码来判断会简单很多。不过本文依然从域名的定义出发来尽可能匹配一段字符串是否是域名或者网址，在要求不怎么高的场合，使用本文的正则表达式写的代码会比较简单。

网址

网址实际上是 URL（统一资源定位符），它是由协议、主机名和路径组成。不过我们通常所说的网址中的主机名通常是域名，因此我们在匹配的时候主要考虑域名。

域名

维基百科中关于域名的描述：

域名由一或多个部分组成，这些部分通常连接在一起，并由点分隔。最右边的一个标签是顶级域名，例如zh.wikipedia.org的顶级域名是org。一个域名的层次结构，从右侧到左侧隔一个点依次下降一层。每个标签可以包含1到63个八字节。域名的结尾有时候还有一点，这是保留给根节点的，书写时通常省略，在查询时由软件内部补上。

域名里的英文字母不区分大小写。

完整域名的所有字符加起来不得超过253个ASCII字符的总长度。因此，当每一级都使用单个字符时，限制为127个级别：127个字符加上126个点的总长度为253。但实际上，某些域名可能具有其他限制；也没有只有一个字符的域名后缀。

后面关于非 ASCII 字符的描述我没有贴出来。这种域名例如“.中国”。

在中国电信网站备案自助管理系统中，我们可以找到关于域名的描述：

域名中的标号都由英文字母和数字组成，每一个标号不超过63个字符，也不区分大小写字母。标号中除连字符（-）外不能使用其他的标点符号。级别最低的域名写在最左边，而级别最高的域名写在最右边。由多个标号组成的完整域名总共不超过255个字符。

路径

路径是使用 / 分隔的一段一段字符串。

正则表达式匹配

在确认了完整的网址 URL 的规范之后，使用正则表达式来匹配就会比较精确了。

域名

现在，我们来尝试匹配一下域名。

每个标签可组成的字符是 - a-z A-Z 0-9，但是 - 不可作为开头，标签总长度 1-63 个字符，于是
- [a-zA-Z0-9][-a-zA-Z0-9]{0,62}
- 即首字不含 -，后面的字可以包含 -
允许多个标签，于是
- (\.[a-zA-Z0-9][-a-zA-Z0-9]{0,62})+
- 除了标签内容和前面一样，但我们加了个 .

别忘了，我们还有总长度限制，于是考虑加上零宽断言 ^.{3,255}$，匹配开头和结尾，中间任意字符但长度在 3-255 之间。通过零宽断言，我们可以在不捕获匹配字符串的情况下对后面的字符串增加限制条件。

现在，把整个正则表达式拼出来：

^(?=^.{3,255}$)[a-zA-Z0-9][-a-zA-Z0-9]{0,62}(\.[a-zA-Z0-9][-a-zA-Z0-9]{0,62})+$

URL

对于不同的业务需求，可能有严格匹配或者宽松的匹配方式。

比如你要做一些比较精准的检查时需要进行严格的检查，那么选择严格匹配；这时，稍微出现一些不符合要求的字符都将认定为不是 URL。

如果你只是打算做一些简单的检查（例如只是语法高亮），那么简单匹配即可；因为当你使用 Chrome 浏览器访问这些 URL 的时候，依然可以正常访问，Chrome 会帮你格式化一下这个 URL。

https://blog.walterlv.com/post/read-32bit-registry-from-x64-process.html
- 严格匹配和宽松匹配都会成功匹配
https://blog.lindexi.com/post/dotnet-配置-github-自动打包上传-nuget-文件.html
- 里面有 Unicode 字符，宽松匹配才可以匹配此 URL
- 你把这个 URL 复制到 Chrome 中可以正常打开，但从 Chrome 里把这个复制出来的话，就会被转义成 https://blog.lindexi.com/post/dotnet-%E9%85%8D%E7%BD%AE-github-%E8%87%AA%E5%8A%A8%E6%89%93%E5%8C%85%E4%B8%8A%E4%BC%A0-nuget-%E6%96%87%E4%BB%B6.html。
https://[2001:4860:4860::8888]:53/favicon.svg
- 因为我偷懒了，所以只有宽松匹配才可以匹配此 IPv6 地址下的 URL
https://域名.中国
- 因为我偷懒了，所以只有宽松匹配才可以匹配此 IPv6 地址下的 URL

URL（严格）

匹配 URL 跟匹配域名不一样，URL 复杂得多。严格匹配的要求是准确反应出 URL 的标准，但实际上如实反应标准编写的正则表达式会非常复杂，因此相比于 100% 准确匹配，我们还是从简了。

所以如果不是有特别要求，建议还是跳到后面的“宽松”部分来阅读吧！

我们以下面这个网址为例说明。

https://blog.walterlv.com/post/read-32bit-registry-from-x64-process.html

前面是可选的协议名，于是
- (http(s)?:\/\/)
- 然而既然可选，而且是行首，那么加一个 ? 和什么都不加的效果是一样的
随后是域名，于是
- [a-zA-Z0-9][-a-zA-Z0-9]{0,62}(\.[a-zA-Z0-9][-a-zA-Z0-9]{0,62})+
- 这里我们没有把总长度限制算上去
别忘了有个可选的端口号
- (:[0-9]{1,5})?
- 端口号的范围是 0-65535，但 0 是保留端口，49152 到 65535 也是保留端口，因此可以作为网址访问的范围也就是 1-49151，因此我们限制 1-5 位长度。
接下来是资源路径
- 资源路径可以使用的字符也是有限制的，我们接下来详细说明。

组合整个正则表达式：

^[a-zA-Z0-9][-a-zA-Z0-9]{0,62}(\.[a-zA-Z0-9][-a-zA-Z0-9]{0,62})+(:[0-9]{1,5})?[-a-zA-Z0-9()@:%_\\\+\.~#?&//=]*$

顺便一提，不同于域名，我们这里去掉了长度限制，因为 URL 真的可以“很长”。另外，这里的

现在，我们补充说明一下资源路径可以使用的字符问题。

; / ? : @ & = + $ , 这些字符应该被转义。转义使用的字符是 &xxx;，因此在转义之后，依然还可能在网址中看到 & 和 ;，不过没有其他字符了。

- _ . ! ~ * ' ( ) 这些字符可以不进行转义，但也不建议在 URL 中使用。对于这部分，我们考虑将其匹配。

{ } | \ ^ [ ] ` 这部分字符可能被网关当作分隔符使用，因此不建议出现在 URL 中。对于这部分，我们考虑将其匹配。

< > # % " 控制字符。使用 % 可以组成其他 Unicode 字符，使用 # 用来指代网址中的某个部分。

因此，我们最终总结应该匹配的特殊字符有 @ : % _ \ + . ~ # ? & / =。

URL（宽松）

宽松一点的话，正则表达式就好写多了。

这个正则表达式可以不写 https 协议前缀：

^\w+[^\s]+(\.[^\s]+){1,}$

如果上下文中要求必须匹配 https，则可以写：

^(http(s)?:\/\/)\w+[^\s]+(\.[^\s]+){1,}$

https://blog.walterlv.com/post/read-32bit-registry-from-x64-process.html#content)
- 期望不匹配（主要是不能匹配末尾的括号），实际匹配
- 在 URL 中，如果括号是成对的，则此 URL 允许以 ) 结尾，如果 URL 中括号不成对，则此 URL 不能以 ) 结尾；> 同理
https://blog.walterlv.com/post/read-32bit -registry-from-x64-process.html
- 期望不匹配，实际不匹配
https://blog.lindexi.com/post/dotnet-配置-github-自动打包上传-nuget-文件.html
- 期望匹配，实际匹配
https://域名.中国
- 期望匹配，实际匹配
blog.walterlv.com/post/read-32bit-registry-from-x64-process.html
- 期望匹配，实际匹配
x<blog.walterlv.com/post/read-32bit-registry-from-x64-process.html
- 期望不匹配，实际匹配

这里的宽松正则表达式请小心！此正则表达式会将一段话中 URL 后面非空格的部分都算作 URL 的一部分。

C# 8.0 的可空引用类型，不止是加个问号哦！你还有很多种不同的可空玩法

Sun, 08 Dec 2019 07:29:27 +0000

C# 8.0 引入了可空引用类型，你可以通过 ? 为字段、属性、方法参数、返回值等添加是否可为 null 的特性。

但是如果你真的在把你原有的旧项目迁移到可空类型的时候，你就会发现情况远比你想象当中复杂，因为你写的代码可能只在部分情况下可空，部分情况下不可空；或者传入空时才可为空，传入非空时则不可为空。

C# 8.0 可空特性

在开始迁移你的项目之前，你可能需要了解如何开启项目的可空类型支持：

C# 8.0 如何在项目中开启可空引用类型的支持 - walterlv

可空引用类型是 C# 8.0 带来的新特性。

你可能会好奇，C# 语言的可空特性为什么在编译成类库之后，依然可以被引用它的程序集识别。也许你可以理解为有什么特性 Attribute 标记了字段、属性、方法参数、返回值的可空特性，于是可空特性就被编译到程序集中了。

确实，可空特性是通过 NullableAttribute 和 NullableContextAttribute 这两个特性标记的。

但你是否好奇，即使在古老的 .NET Framework 4.5 或者 .NET Standard 2.0 中开发的时候，你也可以编译出支持可空信息的程序集出来。这些古老的框架中没有这些新出来的类型，为什么也可以携带类型的可空特性呢？

实际上反编译一下编译出来的程序集就能立刻看到结果了。

看下图，在早期版本的 .NET 框架中，可空特性实际上是被编译到程序集里面，作为 internal 的 Attribute 类型了。

所以，放心使用可空类型吧！旧版本的框架也是可以用的。

更灵活控制的可空特性

阻碍你将老项目迁移到可空类型的原因，可能还有你原来代码逻辑的问题。因为有些情况下你无法完完全全将类型迁移到可空。

例如：

有些时候你不得不为非空的类型赋值为 null 或者获取可空类型时你能确保此时一定不为 null（待会儿我会解释到底是什么情况）；
一个方法，可能这种情况下返回的是 null 那种情况下返回的是非 null；
可能调用者传入 null 的时候才返回 null，传入非 null 的时候返回非 null。

为了解决这些情况，C# 8.0 还同时引入了下面这些 Attribute：

AllowNull: 标记一个不可空的输入实际上是可以传入 null 的。
DisallowNull: 标记一个可空的输入实际上不应该传入 null。
MaybeNull: 标记一个非空的返回值实际上可能会返回 null，返回值包括输出参数。
NotNull: 标记一个可空的返回值实际上是不可能为 null 的。
MaybeNullWhen: 当返回指定的 true/false 时某个输出参数才可能为 null，而返回相反的值时那个输出参数则不可为 null。
NotNullWhen: 当返回指定的 true/false 时，某个输出参数不可为 null，而返回相反的值时那个输出参数则可能为 null。
NotNullIfNotNull: 指定的参数传入 null 时才可能返回 null，指定的参数传入非 null 时就不可能返回 null。
DoesNotReturn: 指定一个方法是不可能返回的。
DoesNotReturnIf: 在方法的输入参数上指定一个条件，当这个参数传入了指定的 true/false 时方法不可能返回。

想必有了这些描述后，你在具体遇到问题的时候应该能知道选用那个特性。但单单看到这些特性的时候你可能不一定知道什么情况下会用得着，于是我可以为你举一些典型的例子。

输入：`AllowNull`

设想一下你需要写一个属性：

public string Text
{
    get => GetValue() ?? "";
    set => SetValue(value ?? "");
}

当你获取这个属性的值的时候，你一定不会获取到 null，因为我们在 get 里面指定了非 null 的默认值。然而我是允许你设置 null 到这个属性的，因为我处理好了 null 的情况。

于是，请为这个属性加上 AllowNull。这样，获取此属性的时候会得到非 null 的值，而设置的时候却可以设置成 null。

++  [AllowNull]
    public string Text
    {
        get => GetValue() ?? "";
        set => SetValue(value ?? "");
    }

输入：`DisallowNull`

与以上场景相反的一个场景：

private string? _text;

public string? Text
{
    get => _text;
    set => _text = value ?? throw new ArgumentNullException(nameof(value), "不允许将这个值设置为 null");
}

当你获取这个属性的时候，这个属性可能还没有初始化，于是我们获取到 null。然而我却并不允许你将这个属性赋值为 null，因为这是个不合理的值。

于是，请为这个属性加上 DisallowNull。这样，获取此属性的时候会得到可能为 null 的值，而设置的时候却不允许为 null。

输出：`MaybeNull`

如果你有尝试过迁移代码到可空类型，基本上一定会遇到泛型方法的迁移问题：

public T Find<T>(int index)
{
}

比如以上这个方法，找到了就返回找到的值，找不到就返回 T 的默认值。那么问题来了，T 没有指定这是值类型还是引用类型。

如果 T 是引用类型，那么默认值 default(T) 就会引入 null。但是泛型 T 并没有写成 T?，因此它是不可为 null 的。然而值类型和引用类型的 T? 代表的是不同的含义。这种矛盾应该怎么办？

这个时候，请给返回值标记 MaybeNull：

++  [return: MaybeNull]
    public T Find<T>(int index)
    {
    }

这表示此方法应该返回一个不可为 null 的类型，但在某些情况下可能会返回 null。

实际上这样的写法并没有从本质上解决掉泛型 T 的问题，不过可以用来给旧项目迁移时用来兼容 API 使用。

如果你可以不用考虑 API 的兼容性，那么可以使用新的泛型契约 where T : notnull。

public T Find<T>(int index) where T : notnull
{
}

输出：`NotNull`

设想你有一个方法，方法参数是可以传入 null 的：

public void EnsureInitialized(ref string? text)
{
}

然而这个方法的语义是确保此字段初始化。于是可以传入 null 但不会返回 null 的。这个时候请标记 NotNull：

--  public void EnsureInitialized(ref string? text)
++  public void EnsureInitialized([NotNull] ref string? text)
    {
    }

`NotNullWhen`, `MaybeNullWhen`

string.IsNullOrEmpty 的实现就使用到了 NotNullWhen：

bool IsNullOrEmpty([NotNullWhen(false)] string? value);

它表示当返回 false 的时候，value 参数是不可为 null 的。

这样，你在这个方法返回的 false 判断分支里面，是不需要对变量进行判空的。

当然，更典型的还有 TryDo 模式。比如下面是 Version 类的 TryParse：

bool TryParse(string? input, [NotNullWhen(true)] out Version? result)

当返回 true 的时候，result 一定不为 null。

`NotNullIfNotNull`

典型的情况比如指定默认值：

[return: NotNullIfNotNull("defaultValue")]
public string? GetValue(string key, string? defaultValue)
{
}

这段代码里面，如果指定的默认值（defaultValue）是 null 那么返回值也就是 null；而如果指定的默认值是非 null，那么返回值也就不可为 null 了。

在早期 .NET Framework 或者早期版本的 .NET Core 中使用

在本文第一小节里面，我们说 Nullable 是编译到目标程序集中的，所以不需要引用什么特别的程序集就能够使用到可空引用的特性。

那么上面这些特性呢？它们并没有编译到目标程序集中怎么办？

实际上，你只需要有一个命名空间、名字和实现都相同的类型就够了。你可以写一个放到你自己的程序集中，也可以把这些类型写到一个自己公共的库中，然后引用它。当然，你也可以用我已经写好的 NuGet 包 Walterlv.NullableAttributes。

Walterlv.NullableAttributes

微软 .NET 官方的可空特性在这里：

NullableAttributes.cs

我将其注释翻译成中文之后，也写了一份在这里：

Walterlv.Packages/CodeAnalysis.cs at master · walterlv/Walterlv.Packages

如果你想简单一点，可以直接引用我的 NuGet 包：

作为 dll 引用：NuGet Gallery - Walterlv.NullableAttributes
作为源代码包引用：NuGet Gallery - Walterlv.NullableAttributes.Source

源代码包可以在不用引入其他 dll 依赖的情况下完成引用。最终你输出的程序集是不带对此包的依赖的，详见：

.NET 将多个程序集合并成单一程序集的 4+3 种方法 - walterlv

参考资料

Upgrade APIs for nullable reference types with attributes that define expectations for null values - Microsoft Docs

一个简单的方法：截取子类名称中不包含基类后缀的部分

Sun, 08 Dec 2019 07:29:19 +0000

基类是 MenuItem，子类是 WalterlvMenuItem、FooMenuItem。基类是 Configuration，子类是 WalterlvConfiguration、ExtensionConfiguration。在代码中，我们可能会为了能够一眼看清类之间的继承（从属）关系而在子类名称后缀中带上基类的名称。但是由于这种情况下的基类不参与实际的业务，所以对外（文件/网络）的名称通常不需要带上这个后缀。

本文提供一个简单的方法，让子类中基类的后缀删掉，只取得前面的那部分。

在这段代码中，我们至少需要获得两个传入的参数，一个是基类的名称，一个是子类的名称。但是考虑到让开发者就这样传入两者名称的话会比较容易出问题，因为开发者可能根本就不会按照要求去获取类型的名称。所以我们需要自己通过类型对象来获取名称。

另外，我们还需要有一些约束，必须有一个类型是另外一个类型的子类。于是我们可能必须来使用泛型做这样的约束。

于是，我们可以写出下面的方法：

using System;

namespace Walterlv.Utils
{
    /// <summary>
    /// 包含类名相关的处理方法。
    /// </summary>
    internal static class ClassNameUtils
    {
        /// <summary>
        /// 当某个类型的派生类都以基类（<typeparamref name="T"/>）名称作为后缀时，去掉后缀取派生类名称的前面部分。
        /// </summary>
        /// <typeparam name="T">名称统一的基类名称。</typeparam>
        /// <param name="this">派生类的实例。</param>
        /// <returns>去掉后缀的派生类名称。</returns>
        internal static string GetClassNameWithoutSuffix<T>(this T @this)
        {
            if (@this is null)
            {
                throw new ArgumentNullException(nameof(@this));
            }

            var derivedTypeName = @this.GetType().Name;
            var baseTypeName = typeof(T).Name;
            // 截取子类名称中去掉基类后缀的部分。
            var name = derivedTypeName.EndsWith(baseTypeName, StringComparison.Ordinal)
                ? derivedTypeName.Substring(0, derivedTypeName.Length - baseTypeName.Length)
                : derivedTypeName;
            // 如果子类名称和基类完全一样，则直接返回子类名称。
            return string.IsNullOrWhiteSpace(name) ? derivedTypeName : name;
        }
    }
}

我们通过判断子类是否以基类名称作为后缀来决定是否截取子字符串。

在截取完子串之后，我们还需要验证截取的字符串是否已经是空串了，因为父子类的名称可能是完全一样的（虽然这样的做法真的很逗比）。

于是使用起来只需要简单调用一下：

class Program
{
    static void Main(string[] args)
    {
        var name = ClassNameUtils.GetClassNameWithoutSuffix<Foo>(new XFoo());
    }
}

internal class Foo
{

}

internal class XFoo : Foo
{

}

于是我们可以得到 name 局部变量的值为 X。如果这个时候我们对 XFoo 类型改名，例如改成 XFoo1，那么就不会截取，而是直接得到名称 XFoo1。

可集成到文件管理器，一句 PowerShell 脚本发布某个版本的所有 NuGet 包

Sun, 08 Dec 2019 07:29:05 +0000

要发布 NuGet 包，只需要执行命令 nuget push xxx.nupkg 即可，或者去 nuget.org 点鼠标上传。

不过，如果你有很多的 NuGet 包并且经常需要推送的话，也可以集成到 Directory Opus 或者 Total Commander 中。

NuGet 推送命令

NuGet 推送命令可直接在微软官方文档中阅读到：

NuGet CLI push command - Microsoft Docs

在你已经设置了 ApiKey 的情况下：

nuget setapikey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -source https://api.nuget.org/v3/index.json

之后你只需要执行一句命令即可：

nuget.exe push Walterlv.Themes.FluentDesign.Source.0.8.0-alpha.nupkg -source https://api.nuget.org/v3/index.json

或者推送此文件夹下 0.8.0-alpha 版本的所有 NuGet 包：

nuget.exe push *.0.8.0-alpha.nupkg -source https://api.nuget.org/v3/index.json

用 PowerShell 包装一下

要执行 NuGet 的推送命令，我们需要一个可以执行命令的终端，比如 PowerShell。命令的执行结果我们也可以直接在终端看到。

不过，如果命令是集成到其他工具里面，那么就不一定能够看得到命令的执行结果了。

这个时候，可以考虑用 PowerShell 间接执行这个命令：

# PowerShell 版本
powershell -NoExit -c "nuget push *.0.8.0-alpha.nupkg -Source https://api.nuget.org/v3/index.json"

# PowerShell Core 版本
pwsh -NoExit -c "nuget push *.0.8.0-alpha.nupkg -Source https://api.nuget.org/v3/index.json"

关于使用 PowerShell 间接执行命令的更多细节，可以参考我的另一篇博客：

PowerShell 的命令行启动参数（可用于执行命令、传参或进行环境配置） - walterlv

集成到 Directory Opus

我将这个命令集成到了 Directory Opus 中，这样，一次点击或者一个快捷键就能发布某个特定版本的所有的 NuGet 包了。

关于使用 Directory Opus 继承工具栏按钮的细节，可以阅读我的另一篇博客：

在 Directory Opus 中添加自定义的工具栏按钮提升效率 - walterlv

具体来说，就是安装上文中所述的方法添加一个按钮，在按钮当中需要执行的脚本如下：

cd "{sourcepath} "
pwsh -NoExit -c "$file=[Regex]::Match('{file}', '\.\d+\.\d+\.\d+.+.nupkg').Value; nuget push *$file -Source https://api.nuget.org/v3/index.json"

含义为：

转到 Directory Opus 当前目录
执行一段 PowerShell 脚本，但执行完之后不退出（这样，我可以观察到我实际上推送的是哪一些包，并且可以知道推送是否出现了错误）
要执行的命令为 nuget push *.xxx.nupkg -Source https://api.nuget.org/v3/index.json
- 其中，中间的 xxx 是使用正则表达式匹配的 {file} 文件名
- {file} 是 Directory Opus 当前选中的文件，我用正则表达式匹配出其版本号和后面的 .nupkg 后缀
- 将正则表达式匹配出来的文本作为 nuget push 的包，最终生成的命令会非常类似于本文一开始提到的命令 nuget push *.0.8.0-alpha.nupkg -Source https://api.nuget.org/v3/index.json

于是，当我选中了一个包，按下这个工具栏按钮之后，就可以推送与这个包相同版本的所有的 NuGet 包了。

毕竟我一次编译产生的 NuGet 包太多了，还是需要使用这样的方式来提高一点效率。至于为什么不用持续集成，是因为目前 SourceYard 还不支持在 GitHub 上集成。

参考资料

NuGet CLI push command - Microsoft Docs

配置 legacyUnhandledExceptionPolicy 防止后台线程抛出的异常让程序崩溃退出

Thu, 28 Nov 2019 08:08:14 +0000

如果你的程序抛了异常，你是怎么处理的呢？等待程序崩溃退出？还是进行补救？

如果是做 UI 开发，很容易就找到 Dispatcher.UnhandledException 事件，然后在事件中进行补救。如果补救成功，可以设置 e.Handled = true 来阻止异常继续让程序崩溃退出。但是，如果是后台线程抛出了异常呢？并没有 Dispatcher 可以用。所以我们就束手就擒让程序自己退出吗？

WPF 和 Windows Forms 都是微软的框架，为了照顾初学者，微软会默认每一个开发者都不会正确地处理异常。于是在异常发生之后，微软 Windows 会假设开发者并不知道如何应对以便让应用程序正常工作，就擅自将应用程序进程结束掉，以便防止应用程序自己内部产生奇怪的状态和错误，避免对系统环境造成不可逆的严重后果。

能够写出异常处理代码的开发者，微软会默认他们懂了异常处理。

写出了监听 Dispatcher.UnhandledException 事件的开发者，微软会认为他们已经学会了如何在 UI 线程中处理异常。于是允许开发者设置 e.Handled = true 来标记异常已被正确处理，程序可以不用退出了。

还有一个事件 AppDomain.CurrentDomain.UnhandledException，然而这个事件却并不允许开发者标记 e.Handled = true。因为微软认为，应用程序域中所有的线程发生异常都会进入这个事件中，大多数开发者都不明白这些线程这些异常是怎么回事，所以不认为这些开发者具备正确处理这些异常的能力。比如 WPF 的触摸模块发生了异常，开发者知道如何恢复吗？并不知道，还不如结束掉程序然后重启呢！

在这个事件中，有一个属性 IsTerminating 指示是否应用程序正因为这次异常准备退出，不过开发者并不能拿这个属性做些什么。

但还是要照顾更高级的开发者的，于是祭出新的配置——legacyUnhandledExceptionPolicy！

在 app.config 文件的 <runtime> 节点中添加如下代码：

<legacyUnhandledExceptionPolicy enabled="1"/>  

如果你找不到在 App.config 的哪个地方，我再用一段代码标注一下，大概在这里：

    <?xml version="1.0" encoding="utf-8"?>
    <configuration>
        <startup useLegacyV2RuntimeActivationPolicy="true">
            <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.8" />
        </startup>
        <runtime>
++          <legacyUnhandledExceptionPolicy enabled="1" />
        </runtime>
    </configuration>

加上了这个配置之后，AppDomain.CurrentDomain.UnhandledException 事件的 IsTerminating 就变成了 false 啦！也就是说，程序并不会因为这次的异常而崩溃退出。

既然你通过这个配置节点于微软达成了契约，你就需要好好地在 AppDomain.CurrentDomain.UnhandledException 事件中写好异常的恢复逻辑。如果不好好恢复，小心有些致命的异常会导致你的程序出现雪崩式的错误，最终 Windows 还是会通过 CorruptedStateException 把你干掉的！

参考资料

WPF 程序如何跨窗口/跨进程设置控件焦点

Wed, 27 Nov 2019 00:53:01 +0000

WPF 程序提供了 Focus 方法和 TraversalRequest 来在 WPF 焦点范围内转移焦点。但如果 WPF 窗口中嵌入了其他框架的 UI（比如另一个子窗口），那么就需要使用其他的方法来设置焦点了。

一个粗略的设置方法是，使用 Win32 API：

SetFocus(hwnd);

传入的是要设置焦点的窗口的句柄。

参考资料

winapi - Win32: C++: How do I re-focus on Parent Window after clicking in a child window? - Stack Overflow

PowerShell 的命令行启动参数（可用于执行命令、传参或进行环境配置）

Wed, 20 Nov 2019 06:39:56 +0000

有一些程序不支持被直接启动，而要求通过命令行启动。这个时候，你就需要使用 PowerShell 或者 PowerShell Core 来启动这样的程序。我们都知道如何在命令行或各种终端中启动一个程序，但是当你需要自动启动这个程序的时候，你就需要知道如何通过 PowerShell 或其他命令行终端来启动一个程序，而不是手工输入然后回车运行了。

本文就介绍 PowerShell 的命令行启动参数。利用这些参数，你可以自动化地通过 PowerShell 程序来完成一些原本需要通过手工执行的操作或者突破一些限制。

一些必须通过命令行启动的程序

一般来说，编译生成的 exe 程序都可以直接启动，即便是命令行程序也是如此。但是有一些程序就是要做一些限制。比如下面的 FRP 反向代理程序：

借助 cmd.exe 来启动的方法可以参见我的另一篇博客：

cmd.exe 的命令行启动参数（可用于执行命令、传参或进行环境配置） - 吕毅

那么我们如何能够借助于 PowerShell 或者 PowerShell 来启动它呢？

PowerShell 的帮助文档

先打开一个 PowerShell。

对于 Windows 自带的基于 .NET Framework 的 PowerShell，使用 powershell 命令可以直接启动 PowerShell。对于基于 .NET Core 版本的 PowerShell Core，使用 pwsh 命令可以直接启动。

关于 .NET Core 版本的 PowerShell Core 可以参见我的另一篇博客：

安装和运行 .NET Core 版本的 PowerShell - 吕毅

接下来输入下面三个命令中的任何一个：

PowerShell -Help
PowerShell -?
PowerShell /?

或者对于 PowerShell Core 来说，是下面三个命令中的任何一个：

pwsh -Help
pwsh -?
pwsh /?

你就可以看到 PowerShell 的使用说明：

PowerShell 的启动参数示例

使用 PowerShell 间接启动一个程序并传入参数

下面的命令，使用 PowerShell 间接启动 frpc.exe 反向代理程序，并给 frpc.exe 程序传入 -c ./frpc.ini 的启动参数：

> pwsh -Command "D:\walterlv\frpc.exe -c ./frpc.ini"

或者简写为：

> pwsh -c "D:\walterlv\frpc.exe -c ./frpc.ini"

实际上使用 PowerShell 来做这些事情简直是用牛刀杀鸡，因为本身 PowerShell 非常强大。我们只是因为一些程序的限制不得不使用这样的方案来启动程序而已。

比如其中之一，执行脚本。

使用 PowerShell 执行命令/脚本后保留窗口不退出

需要加上 -NoExit 参数。

> pwsh -NoExit -c "D:\walterlv\frpc.exe -c ./frpc.ini"

一定要注意，-c 和后面的命令必须放到最末尾，因为 -c 后面的所有字符串都会被解析为需要执行的命令。

使用 PowerShell 执行多条命令/脚本

多条脚本之间使用 ; 作为分隔：

> pwsh -c "D:\walterlv\frpc.exe -c ./frpc.ini"; "D:\walterlv\frps.exe -c ./frps.ini"

如果引号里面还需要写引号，则可以把里面的引号改成单引号 ' 或者把外面的引号改为单引号 '。

使用 PowerShell 间接执行一个脚本

# Execute a PowerShell Command in a session
PowerShell -Command "Get-EventLog -LogName security"

# Run a script block in a session
PowerShell -Command {Get-EventLog -LogName security}

# An alternate way to run a command in a new session
PowerShell -Command "& {Get-EventLog -LogName security}"

附 PowerShell 的全部启动参数说明

PowerShell[.exe] [-PSConsoleFile <文件> | -Version <版本>]
    [-NoLogo] [-NoExit] [-Sta] [-Mta] [-NoProfile] [-NonInteractive]
    [-InputFormat {Text | XML}] [-OutputFormat {Text | XML}]
    [-WindowStyle <样式>] [-EncodedCommand <Base64 编码命令>]
    [-ConfigurationName <字符串>]
    [-File <文件路径> <参数>] [-ExecutionPolicy <执行策略>]
    [-Command { - | <脚本块> [-args <参数数组>]
                  | <字符串> [<命令参数>] } ]

PowerShell[.exe] -Help | -? | /?

-PSConsoleFile
    加载指定的 Windows PowerShell 控制台文件。若要创建控制台
    文件，请在 Windows PowerShell 中使用 Export-Console。

-Version
    启动指定版本的 Windows PowerShell。
    使用参数输入版本号，如 "-version 2.0"。

-NoLogo
    启动时隐藏版权标志。

-NoExit
    运行启动命令后不退出。

-Sta
    使用单线程单元启动 shell。
    单线程单元(STA)是默认值。

-Mta
    使用多线程单元启动 shell。

-NoProfile
    不加载 Windows PowerShell 配置文件。

-NonInteractive
    不向用户显示交互式提示。

-InputFormat
    描述发送到 Windows PowerShell 的数据的格式。有效值为
    "Text" (文本字符串)或 "XML" (序列化的 CLIXML 格式)。

-OutputFormat
    确定如何设置 Windows PowerShell 输出内容的格式。有效值
    为 "Text" (文本字符串)或 "XML" (序列化的 CLIXML 格式)。

-WindowStyle
    将窗口样式设置为 Normal、Minimized、Maximized 或 Hidden。

-EncodedCommand
    接受 base-64 编码字符串版本的命令。使用此参数
    向 Windows PowerShell 提交需要复杂引号
    或大括号的命令。

-ConfigurationName
    指定运行 Windows PowerShell 的配置终结点。
    该终结点可以是在本地计算机上注册的任何终结点，包括
    默认的 Windows PowerShell 远程处理终结点或具有特定用户角色功能
    的自定义终结点。

-File
    在本地作用域("dot-sourced")中运行指定的脚本，以便
    脚本创建的函数和变量可以在当前
    会话中使用。输入脚本文件路径和任何参数。
    File 必须是命令中的最后一个参数，因为在 File 参数
    名称后面键入的所有字符都将解释
    为后跟脚本参数的脚本文件路径。

-ExecutionPolicy
    设置当前会话的默认执行策略，并将其保存
    在 $env:PSExecutionPolicyPreference 环境变量中。
    该参数不会更改在注册表中
    设置的 Windows PowerShell 执行策略。

-Command
    执行指定的命令(和任何参数)，就好像它们是
    在 Windows PowerShell 命令提示符下键入的一样，然后退出，除非
    指定了 NoExit。Command 的值可以为 "-"、字符串或
    脚本块。

    如果 Command 的值为 "-"，则从标准输入中读取
    命令文本。

    如果 Command 的值为脚本块，则脚本块必须
    用大括号({})括起来。只有在 Windows PowerShell 中运行 PowerShell.exe 时，
    才能指定脚本块。脚本块的结果将作为反序列化的 XML 对象
    (而非活动对象)返回到父 Shell。

    如果 Command 的值为字符串，则 Command 必须是命令中的
    最后一个参数，因为在命令后面键入的所有字符
    都将解释为命令参数。

    若要编写运行 Windows PowerShell 命令的字符串，请使用以下格式:
        "& {<命令>}"
    其中，引号表示一个字符串，调用运算符(&)
    导致执行命令。

-Help, -?, /?
    显示此消息。如果在 Windows PowerShell 中键入 PowerShell.exe
    命令，请在命令参数前面添加连字符(-)，而不是添加正
    斜杠(/)。你可以在 Cmd.exe 中使用连字符或正斜杠。

示例
    PowerShell -PSConsoleFile SqlSnapIn.Psc1
    PowerShell -version 2.0 -NoLogo -InputFormat text -OutputFormat XML
    PowerShell -ConfigurationName AdminRoles
    PowerShell -Command {Get-EventLog -LogName security}
    PowerShell -Command "& {Get-EventLog -LogName security}"

    # To use the -EncodedCommand parameter:
    $command = 'dir "c:\program files" '
    $bytes = [System.Text.Encoding]::Unicode.GetBytes($command)
    $encodedCommand = [Convert]::ToBase64String($bytes)
    powershell.exe -encodedCommand $encodedCommand

参考资料

清理 git 仓库太繁琐？试试 bfg！删除敏感信息删除大文件一句命令搞定（比官方文档还详细的使用说明）

Tue, 05 Nov 2019 03:22:22 +0000

你可能接触过 git-filter-branch 来清理 git 仓库，不过同时也能体会到这个命令使用的繁琐，以及其超长的执行时间。

现在，你可以考虑使用 bfg 来解决问题了！

安装 bfg

传统方式安装（不推荐）

下载安装 Java 运行时
下载安装 bfg.jar

这里并不推荐使用传统方式安装，因为传统方式安装后，bfg 不会成为你计算机的命令。在实际使用工具的时候，你必须为你的每一句命令加上 java -jar bfg.jar 前缀来使用 Java 运行时间接运行。

使用包管理器 scoop 安装

如果你使用包管理器 scoop，那么安装将会非常简单，只需要以下几个命令。

scoop install bfg
scoop bucket add java
scoop install java/openjdk

安装 bfg：

PS C:\Users\lvyi> scoop install bfg
Installing 'bfg' (1.13.0) [64bit]
bfg-1.13.0.jar (12.8 MB) [============================================================================================================================] 100%
Checking hash of bfg-1.13.0.jar ... ok.
Linking ~\scoop\apps\bfg\current => ~\scoop\apps\bfg\1.13.0
Creating shim for 'bfg'.
'bfg' (1.13.0) was installed successfully!
'bfg' suggests installing 'java/oraclejdk' or 'java/openjdk'.

安装 Java 源：

PS C:\Users\lvyi> scoop bucket add java
Checking repo... ok
The java bucket was added successfully.

安装 Jdk：

PS C:\Users\lvyi> scoop install java/openjdk
Installing 'openjdk' (13.0.1-9) [64bit]
openjdk-13.0.1_windows-x64_bin.zip (186.9 MB) [=======================================================================================================] 100%
Checking hash of openjdk-13.0.1_windows-x64_bin.zip ... ok.
Extracting openjdk-13.0.1_windows-x64_bin.zip ... done.
Linking ~\scoop\apps\openjdk\current => ~\scoop\apps\openjdk\13.0.1-9
'openjdk' (13.0.1-9) was installed successfully!

准备工作

当你准备好清理你的仓库的时候，需要进行一些准备。

克隆一个镜像仓库（git clone 命令加上 --mirror 参数）
- 这样，当你 git push 的时候，会更新远端仓库的所有引用
cd 到你要清理的仓库路径的根目录
- 如果你没有前往根目录，那么本文后面的所有命令的最后面你都应该加上路径
可能需要解除保护
- 如果本文后面的命令你遇到了受保护的提交，那么需要在所有命令的后面加上 --no-blob-protection 参数

常见用法

使用 bfg 来清理仓库比 git 原生的 git-filter-branch 快得多。官方说法是，10-720 倍：

turning an overnight job into one that takes less than ten minutes.

将一整夜的工作缩减到不到十分钟。

删除误上传的大文件

使用下面的命令，可以将仓库历史中大于 500M 的文件都删除掉。

> bfg --strip-blobs-bigger-than 500M

删除特定的一个或多个文件

删除 walterlv.snk 文件：

> bfg --delete-files walterlv.snk

删除 walterlv.snk 或 lindexi.snk 文件：

> bfg --delete-files {walterlv,lindexi}.snk

比如原来仓库结构是这样的：

- README.md
- Security.md
- walterlv.snk
+ test
    - lindexi.snk

那么删除完后，根目录的 walterlv.snk 和 test 子目录下的 lindexi.snk 就都删除了。

删除文件夹

删除名字为 walterlv 的文件夹：

> bfg --delete-folders walterlv

此命令可以与上面的 --delete-files 放在一起执行：

> bfg --delete-folders walterlv --delete-files walterlv.snk

删除敏感的密码信息

> bfg --replace-text expression-file.txt

注意，这里的 expression-file.txt 名称是随便取的，你可以取其他任何名称，只要在命令里输入正确的名称（可能需要包含路径）就行。

但是 expression-file.txt 里面的内容却是我们需要关注的重点。

此文件中的每一行是一个匹配表达式。默认情况下，每一个表达式被视为一段文本常量，但你可以通过指定 regex: 前缀来说明此表达式是一个正则表达式，或者指定 glob: 前缀。每一个表达式的后面可以加上 ‘==>’ 来指定匹配的文件应该被替换成什么（如果没有指定，就会被替换成默认值 ***REMOVED***。

下面这个例子示例将 git 仓库中所有文件中的 密码：123456 字符串替换成 ***REMOVED***：

密码：123456

更复杂一点的，下面的例子示例将 git 仓库中所有文件中的 密码：123456 字符串替换成 密码：******：

密码：123456 ==> 密码：******

还可以使用正则表达式：

regex:密码：\d+ ==> 密码：******

推回远端仓库

当你在本地操作完镜像仓库之后，可以将其推回原来的远端仓库了。

> git push

最后，有一个不必要的操作。就是回收已经没有引用的旧提交，这可以减小本地仓库的大小：

> git reflog expire --expire=now --all && git gc --prune=now --aggressive

附命令行用法输出

直接在命令行输入 bfg 可以看 bfg 命令行的用法。我贴在下面可以让还没安装的小伙伴感受一下它的功能：

PS C:\Users\lvyi\Desktop\BfgDemoRepo> bfg
bfg 1.13.0
Usage: bfg [options] [<repo>]

  -b, --strip-blobs-bigger-than <size>
                           strip blobs bigger than X (eg '128K', '1M', etc)
  -B, --strip-biggest-blobs NUM
                           strip the top NUM biggest blobs
  -bi, --strip-blobs-with-ids <blob-ids-file>
                           strip blobs with the specified Git object ids
  -D, --delete-files <glob>
                           delete files with the specified names (eg '*.class', '*.{txt,log}' - matches on file name, not path within repo)
  --delete-folders <glob>  delete folders with the specified names (eg '.svn', '*-tmp' - matches on folder name, not path within repo)
  --convert-to-git-lfs <value>
                           extract files with the specified names (eg '*.zip' or '*.mp4') into Git LFS
  -rt, --replace-text <expressions-file>
                           filter content of files, replacing matched text. Match expressions should be listed in the file, one expression per line - by default, each expression is treated as a literal, but 'regex:' & 'glob:' prefixes are supported, with '==>' to specify a replacement string other than the default of '***REMOVED***'.
  -fi, --filter-content-including <glob>
                           do file-content filtering on files that match the specified expression (eg '*.{txt,properties}')
  -fe, --filter-content-excluding <glob>
                           don't do file-content filtering on files that match the specified expression (eg '*.{xml,pdf}')
  -fs, --filter-content-size-threshold <size>
                           only do file-content filtering on files smaller than <size> (default is 1048576 bytes)
  -p, --protect-blobs-from <refs>
                           protect blobs that appear in the most recent versions of the specified refs (default is 'HEAD')
  --no-blob-protection     allow the BFG to modify even your *latest* commit. Not recommended: you should have already ensured your latest commit is clean.
  --private                treat this repo-rewrite as removing private data (for example: omit old commit ids from commit messages)
  --massive-non-file-objects-sized-up-to <size>
                           increase memory usage to handle over-size Commits, Tags, and Trees that are up to X in size (eg '10M')
  <repo>                   file path for Git repository to clean

我觉得你可能需要中文版，于是自己翻译了一下：

PS C:\Users\lvyi\Desktop\BfgDemoRepo> bfg
bfg 1.13.0
用法: bfg [options] [<repo>]

  -b, --strip-blobs-bigger-than <size>
                           移除大于 <size> 大小的文件（<size> 可填写诸如 '128K'、'1M'）
  -B, --strip-biggest-blobs NUM
                           从大到小移除 NUM 数量的文件
  -bi, --strip-blobs-with-ids <blob-ids-file>
                           移除具有指定 git 对象 id 的文件
  -D, --delete-files <glob>
                           移除具有指定名称的文件（例如 '*.class'、'*.{txt,log}'，仅匹配文件名而不能匹配路径）
  --delete-folders <glob>  移除具有指定名称的文件夹（例如 '.svn'、'*-tmp'，仅匹配文件夹名而不能匹配路径）
  --convert-to-git-lfs <value>
                           将指定名称的文件（例如 '*.zip' 或 '*.mp4'）解压到 Git LFS
  -rt, --replace-text <expressions-file>
                           查找文件内容，并替换其中匹配的文本。<expressions-file> 是一个包含一个或多个匹配表达式的文件，文件中每一行是一个匹配表达式。
                           默认情况下，每一个表达式被视为一段文本常量，但你可以通过指定 'regex:' 前缀来说明此表达式是一个正则表达式，或者指定 'glob:' 前缀。
                           每一个表达式的后面可以加上 '==>' 来指定匹配的文件应该被替换成什么（如果没有指定，就会被替换成默认值 '***REMOVED***'。
  -fi, --filter-content-including <glob>
                           指定文件名（例如 '*.{txt,properties}'），在进行内容替换的时候只对这些文件进行处理。
  -fe, --filter-content-excluding <glob>
                           指定文件名（例如 '*.{xml,pdf}'），在进行内容替换的时候不对这些文件进行处理。
  -fs, --filter-content-size-threshold <size>
                           仅对小于 <size> 指定的大小的文件替换内容。（默认值为 1048576 字节）
  -p, --protect-blobs-from <refs>
                           protect blobs that appear in the most recent versions of the specified refs (default is 'HEAD')
  --no-blob-protection     allow the BFG to modify even your *latest* commit. Not recommended: you should have already ensured your latest commit is clean.
  --private                仅将本次操作视为个人数据的修改（这样生成的新提交会使用旧提交的 Id，其他人拉取仓库的时候因为这些 Id 已经存在于是不会更新，以至于此更改实际上只影响自己）。
  --massive-non-file-objects-sized-up-to <size>
                           increase memory usage to handle over-size Commits, Tags, and Trees that are up to X in size (eg '10M')
  <repo>                   file path for Git repository to clean

参考资料

BFG Repo-Cleaner by rtyley

解决关闭模态窗口后，父窗口居然失去焦点跑到了其他窗口的后面的问题

Tue, 05 Nov 2019 01:58:20 +0000

显示一个模态窗口，正常而普遍的操作。然而却一直有一个难缠的 BUG：当关闭模态窗口时，父窗口有时会跑到其他程序窗口的后面！

而最近读到了微软工程师写过的话之后，明白了这个 BUG 的产生缘由以及解决方法。

这是什么 BUG？

弹出一个模态窗口，然后将模态窗口的父窗口设置为自身窗口；
切换到其他程序窗口中（比如 Windows 资源管理器窗口）；
切换回此模态窗口，然后关闭这个模态窗口上。

你会发现，模态窗口关闭后，父窗口并没有回到当前的顶层显示中。取而代之的，是其他程序的窗口（比如 Windows 资源管理器窗口）。用一张图来描述这个 BUG，将是这样的：

有这两个窗口，其中右边那个是我们开发的：

我们的窗口在资源管理器上面。然后，我们弹出模态子窗口：

现在，我们操作一下资源管理器：

然后，回到模态子窗口中，把它关掉：

我们期待模态子窗口关掉后，它的父窗口会在顶层继续供我们操作，但实际上，Windows 资源管理器却成为了顶层，我们的程序“掉下去了”：

解释和解决方法

在《Windows 进化启示录》书中，微软有说到：

当销毁模态对话框时，这个对话框刚好是拥有前台焦点的窗口。现在，窗口管理器需要找到其他的窗口并把前台焦点交给这个窗口。窗口管理器会首先试着把前台焦点交给对话框的所有者窗口，但此时这个窗口却仍然是禁止的，因此窗口管理器将跳过所有者窗口，并继续查找没有被禁止的窗口。

这很明显是 Windows 的 BUG，然而让微软感到无奈的是，经常有程序喜欢依赖于微软的 BUG 进行开发，一旦微软修复了 BUG，那些依赖于 BUG 开发的程序将变得不正常！

为解决兼容性问题的微软工程师默哀一分钟……

我曾经尝试在模态子窗口关闭后激活一下父窗口，但这样会导致窗口的层级闪烁一下（Windows 资源管理器会短暂地显示到我们的窗口之上）。

而这本书作者推荐的方法是：

重新激活所有者窗口

销毁模态对话框

于是，我试着监听模态子窗口的 Closing 事件，在其中写下主窗口的激活调用，自此 BUG 才算解决。

public ChildModalWindow()
{
    Closing += (sender, e) => Owner?.Activate();
}

将这样的解决办法封装成附加属性给所有的模态子窗口，这样设置附加属性即可解决问题。或者统一模态子窗口的窗口样式，在样式中解决这个 BUG，这样，所有使用了此窗口样式的模态子窗口也将解决问题。

参考资料

《伟大的产品：Windows 进化启示录》by 微软软件工程师 Raymond Chen (2016 年 3 月第 1 版，第 112 页)

C#/.NET 当我们在写事件 += 和 -= 的时候，方法是如何转换成事件处理器的

Tue, 29 Oct 2019 03:53:34 +0000

当我们在写 += 和 -= 事件的时候，我们会在 += 或 -= 的右边写上事件处理函数。我们可以写很多种不同的事件处理函数的形式，那么这些形式都是一样的吗？如果你不注意，可能出现内存泄漏问题。

本文将讲解事件处理函数的不同形式，理解了这些可以避免编写代码的时候出现内存相关的问题。

典型的事件处理函数

事件处理函数本质上是一个委托，比如 FileSystemWatcher 的 Changed 事件是这样定义的：

// 这是简化的代码。
public event FileSystemEventHandler Changed;

这里的 FileSystemEventHandler 是一个委托类型：

public delegate void FileSystemEventHandler(object sender, FileSystemEventArgs e);

一个典型的事件的 += 会像下面这样：

void Subscribe(FileSystemWatcher watcher)
{
    watcher.Changed += new FileSystemEventHandler(OnChanged);
}

void OnChanged(object sender, FileSystemEventArgs e)
{
}

+= 的右边传入的是一个 new 出来的委托实例。

变种事件处理函数

除了上面直接创建的目标类型的委托之外，还有其他类型可以放到 += 的右边：

// 方法组。
watcher.Changed += OnChanged;

// Lambda 表达式。
watcher.Changed += (sender, e) => Console.WriteLine(e.ChangeType);

// Lambda 表达式。
watcher.Changed += (sender, e) =>
{
    // 事件引发时，代码会在这里执行。
};

// 匿名方法。
watcher.Changed += delegate (object sender, FileSystemEventArgs e)
{
    // 事件引发时，代码会在这里执行。
};

// 委托类型的局部变量（或者字段）。
FileSystemEventHandler onChanged = (sender, e) => Console.WriteLine(e.ChangeType);
watcher.Changed += onChanged;

// 局部方法（或者局部静态方法）。
watcher.Changed += OnChanged;
void OnChanged(object sender, FileSystemEventArgs e)
{
}

因为我们可以通过编写事件的 add 和 remove 方法来观察事件 += -= 传入的 value 是什么类型的什么实例，所以可以很容易验证以上每一种实例最终被加入到事件中的真实实例。

实际上我们发现，无论哪一个，最终传入的都是 FileSystemEventHandler 类型的实例。

然而我们知道，只有直接 new 出来的那个和局部变量那个真正是 FileSystemEventHandler 类型的实例，其他都不是。

那么中间发生了什么样的转换使得我们所有种类的写法最终都可以 += 呢？

编译器类型转换

具有相同签名的不同委托类型，彼此之前并没有继承关系，因此在运行时是不可以进行类型转换的。

比如：

FileSystemEventHandler onChanged1 = (sender, e) => Console.WriteLine(e.ChangeType);
Action<object, FileSystemEventArgs> onChanged2 = (sender, e) => Console.WriteLine(e.ChangeType);

这里，onChanged1 的实例不可以赋值给 onChanged2，反过来 onChanged2 的实例也不可以赋值给 onChanged1。于是这里只有 onChanged1 才可以作为 Changed 事件 += 的右边，而 onChanged2 放到 += 右边是会出现编译错误的。

然而，我们可以放 Lambda 表达式，可以放匿名函数，可以放方法组，也可以放局部函数。因为这些类型可以在编译期间，由编译器帮助进行类型转换。而转换的效果就类似于我们自己编写 new FileSystemEventHandler(xxx) 一样。

不是同一个委托实例

看下面这一段代码，你认为可以 -= 成功吗？

void Subscribe(FileSystemWatcher watcher)
{
    watcher.Changed += new FileSystemEventHandler(OnChanged);
    watcher.Changed -= new FileSystemEventHandler(OnChanged);
}

void OnChanged(object sender, FileSystemEventArgs e)
{
}

实际上这是可以 -= 成功的。

我们平时编写代码的时候，下面的情况可能会多一些，于是自然而然以为 += 和 -= 可以成功，因为他们“看起来”是同一个实例：

watcher.Changed += OnChanged;
watcher.Changed -= OnChanged;

在读完刚刚那一段之后，我们就可以知道，实际上这一段和上面 new 出来委托的写法在运行时是一模一样的。

如果你想测试，那么在 += 的时候为对象加上一个 Id，在 -= 的时候你就会发现这是一个新对象（因为没有 Id）。

然而，你平时众多的编码经验会告诉你，这里的 -= 是一定可以成功的。也就是说，+= 和 -= 时传入的委托实例即便不是同一个，也是可以成功 += 和 -= 的。

`+=` `-=` 是怎么做的

+= 和 -= 到底是怎么做的，可以在不同实例时也能 += 和 -= 成功呢？

+= 和 -= 实际上是调用了 Delegate 的 Combine 和 Remove 方法，并生成一个新的委托实例赋值给 += -= 的左边。

public event FileSystemEventHandler Changed
{
    add
    {
        onChangedHandler = (FileSystemEventHandler)Delegate.Combine(onChangedHandler, value);
    }
    remove
    {
        onChangedHandler = (FileSystemEventHandler)Delegate.Remove(onChangedHandler, value);
    }
}

而最终的判断也是通过 Delegate 的 Equals 方法来比较委托的实例是否相等的（== 和 != 也是调用的 Equals）：

public override bool Equals(object? obj)
{
    if (obj == null || !InternalEqualTypes(this, obj))
        return false;

    Delegate d = (Delegate)obj;

    // do an optimistic check first. This is hopefully cheap enough to be worth
    if (_target == d._target && _methodPtr == d._methodPtr && _methodPtrAux == d._methodPtrAux)
        return true;

    // even though the fields were not all equals the delegates may still match
    // When target carries the delegate itself the 2 targets (delegates) may be different instances
    // but the delegates are logically the same
    // It may also happen that the method pointer was not jitted when creating one delegate and jitted in the other
    // if that's the case the delegates may still be equals but we need to make a more complicated check

    if (_methodPtrAux == IntPtr.Zero)
    {
        if (d._methodPtrAux != IntPtr.Zero)
            return false; // different delegate kind
        // they are both closed over the first arg
        if (_target != d._target)
            return false;
        // fall through method handle check
    }
    else
    {
        if (d._methodPtrAux == IntPtr.Zero)
            return false; // different delegate kind

        // Ignore the target as it will be the delegate instance, though it may be a different one
        /*
        if (_methodPtr != d._methodPtr)
            return false;
            */

        if (_methodPtrAux == d._methodPtrAux)
            return true;
        // fall through method handle check
    }

    // method ptrs don't match, go down long path
    //
    if (_methodBase == null || d._methodBase == null || !(_methodBase is MethodInfo) || !(d._methodBase is MethodInfo))
        return Delegate.InternalEqualMethodHandles(this, d);
    else
        return _methodBase.Equals(d._methodBase);
}

于是可以看出来，判断相等就是两个关键对象的判断相等：

方法所在的对象
方法信息（对应到反射里的 MethodInfo)

继续回到这段代码：

void Subscribe(FileSystemWatcher watcher)
{
    watcher.Changed += new FileSystemEventHandler(OnChanged);
    watcher.Changed -= new FileSystemEventHandler(OnChanged);
}

void OnChanged(object sender, FileSystemEventArgs e)
{
}

这里的对象就是 this，方法信息就是 OnChanged 的信息，也就是：

// this 就是对象，OnChanged 就是方法信息。
this.OnChanged

`-=`

于是什么样的 -= 才可以把 += 加进去的事件处理函数减掉呢？

必须是同一个对象的同一个方法

所以：

使用方法组、静态局部函数、委托字段的方式创建的委托实例，在 += 和 -= 的时候无视哪个委托实例，都是可以减掉的；
使用局部函数、委托变量，在同一个上下文中，是可以减掉的，如果调用是再次进入此函数，则不能减掉（因为委托方法所在的对象实例不同）
使用 Lambda 表达式、匿名函数是不能减掉的，因为每次编写的 Lambda 表达式和匿名函数都会创建新的包含此对象的实例。

如何在 .NET 项目中开启不安全代码（以便启用 unsafe fixed 等关键字）

Tue, 29 Oct 2019 03:53:34 +0000

有小伙伴希望在 .NET 代码中使用指针，操作非托管资源，于是可能使用到 unsafe fixed 关键字。但使用此关键字的前提是需要在项目中开启不安全代码。

本文介绍如何在项目中开启不安全代码。

入门方法

第一步：在你需要启用不安全代码的项目上点击右键，然后选择属性：

第二步：在“生成”标签下，勾选上“允许不安全代码”：

第三步：切换到 Release 配置，再勾上一次“允许不安全代码”（确保 Debug 和 Release 都打开）

方法结束。

如果你一开始选择了“所有配置”，那么就不需要分别在 Debug 和 Release 下打开了，一次打开即可。

高级方法

临时方法

不推荐

如果你只是临时希望加上不安全代码开关，则可以在编译的时候加入 -unsafe 命令行参数：

csc -unsafe walterlv.cs

注意，不能给 msbuild 或者 dotnet build 加上 -unsafe 参数来编译项目，只能使用 csc 加上 -unsafe 来编译文件。因此使用场景非常受限，不推荐使用。

其他说明

第一种方法（入门方法）和第二种方法（高级方法）最终的修改是有一些区别的。入门方法会使得项目文件中有针对于 Debug 和 Release 的不同配置，代码会显得冗余；而高级方法中只增加了一行，对任何配置均生效。

因此如果可能，尽量使用高级方法呗。

    <Project Sdk="Microsoft.NET.Sdk">

      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFramework>netcoreapp3.0</TargetFramework>
++      <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
      </PropertyGroup>

--    <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
--      <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
--    </PropertyGroup>

--    <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
--      <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
--    </PropertyGroup>

    </Project>

即使是 .NET Framework 也是可以使用 SDK 风格的项目文件的，详情请阅读：

将 WPF、UWP 以及其他各种类型的旧 csproj 迁移成 Sdk 风格的 csproj - walterlv

不要在 C# 代码中写部分命名空间（要么不写，要么写全），否则会有源码兼容性问题

Tue, 29 Oct 2019 00:51:56 +0000

我只是增加库的一个 API，比如增加几个类而已，应该不会造成兼容性问题吧。对于编译好的二进制文件来说，不会造成兼容性问题；但——可能造成源码不兼容。

本文介绍可能的源码不兼容问题。

This post is written in multiple languages. Please select yours:

比如我有一个项目 P 引用 A 和 B 两个库。其中使用到了 A 库中的 Walterlv.A.Diagnostics.Foo 类型。

using Walterlv.A;
using Walterlv.B;

namespace Walterlv.Demo
{
    class Hello
    {
        Run(Diagnostics.Foo foo)
        {
        }
    }
}

现在，我们在 B 库中新增一个类型 Walterlv.B.Diagnostics.Bar 类型。

那么上面的代码将无法完成编译，因为 Diagnosis 命名空间将具有不确定的含义，其中的 Foo 类型也将无法在不确定的命名空间中找到。

因此：

强烈建议遵守 使用类型的时候，要么不写命名空间（完全留给 using），要么写全命名空间（从第一段开始写，不要省略任何部分），否则就容易与其他命名空间冲突；
可选遵守 在库中新增 API 的时候，可能需要考虑避免将部分命名空间写成过于通用的名称。

是的，即使是单纯的新增 API 也可能会导致使用库的一方在源码级不兼容。当然二进制还是兼容的。

另外，OpportunityLiu 提醒，如果命名空间是 Walterlv.B.Walterlv.A.Diagnostics.Bar，一样可以让写全了的命名空间炸掉。呃……还是不要在库里面折腾这样的命名空间好……不然代码当中到处充斥着 global:: 可是非常难受的。

.NET/C# 在 64 位进程中读取 32 位进程重定向后的注册表

Tue, 22 Oct 2019 08:59:03 +0000

我们知道，32 位程序在读取注册表的时候，会自动将注册表的路径映射到 32 位路径下，即在 Wow6432Node 子节点下。但是 64 位程序不会映射到 32 位路径下。那么 64 位程序如何读取到 32 位程序写入的注册表路径呢？

Wow6432Node

对于 32 位程序，读取注册表路径的时候，会读到 Wow6432Node 节点下的项：

这张图读取的就是前面截图中的节点。

那么怎样编译的程序是 32-bit 的程序呢？

对于 64 位程序，读取的时候就不会有 Wow6432Node 路径部分。由于我没有在那个路径放注册表项，所以会得到 null。

那么怎样编译的程序是 64-bit 的程序呢？

如何在 64 位程序中读取 32 位注册表路径

前面我们的例子代码是这样的：

var value = RegistryHive.LocalMachine.Read(@"SOFTWARE\Walterlv");

可以看到，相同的代码，在 32 位和 64 位进程下得到的结果是不同的：

32 位进程在 32 位系统上，64 位进程在 64 位系统上，读取的路径会是传入的路径；
32 位进程在 64 位系统上，读取的路径会包含 Wow6432Node。

那么如何在 64 位进程中读取 32 位注册表路径呢？

方法是在打开注册表项的时候，传入 RegistryView.Registry32。

RegistryKey.OpenBaseKey(root, RegistryView.Registry32);

Walterlv.Win32

可以在我的 GitHub 仓库中查看完整的实现。当然，除了上面那句话，其他都不是关键代码，在哪里都可以找得到的。

参考资料

c# - Reading the registry and Wow6432Node key - Stack Overflow

解决 WPF 嵌套的子窗口在改变窗口大小的时候闪烁的问题

Tue, 22 Oct 2019 06:14:08 +0000

因为 Win32 的窗口句柄是可以跨进程传递的，所以可以用来实现跨进程 UI。不过，本文不会谈论跨进程 UI 的具体实现，只会提及其实现中的一个重要缓解，使用子窗口的方式。

你有可能在使用子窗口之后，发现拖拽改变窗口大小的时候，子窗口中的内容不断闪烁。如果你也遇到了这样的问题，那么正好可以阅读本文来解决。

问题

你可以看一下下面的这张动图，感受一下窗口的闪烁：

实际上在拖动窗口的时候，是一直都在闪的，只是每次闪烁都非常快，截取 gif 的时候截不到。

如果你希望实际跑一跑项目看看，可以使用下面的代码：

walterlv.demo/Walterlv.Demo.HwndWrapping/Walterlv.Demo.HwndWrapping at a88f81477756af2913349970ba2f0bbab01aaf88 · walterlv/walterlv.demo

我特地提取了一个提交下的代码，如果你要尝试，不能使用 master 分支，因为 master 分支修复了闪烁的问题。

后来使用 CreateWindowEx 创建了一个纯 Win32 窗口，这种闪烁现象更容易被截图：

解决

    public class HwndWrapper : HwndHost
    {
        protected override HandleRef BuildWindowCore(HandleRef hwndParent)
        {
            const int WS_CHILD = 0x40000000;
++          const int WS_CLIPCHILDREN = 0x02000000;
            var owner = ((HwndSource)PresentationSource.FromVisual(this)).Handle;

            var parameters = new HwndSourceParameters("demo")
            {
                ParentWindow = owner,
--              WindowStyle = (int)(WS_CHILD),
++              WindowStyle = (int)(WS_CHILD | WS_CLIPCHILDREN),
            };
            var source = new HwndSource(parameters);
            source.RootVisual = new ChildPage();
            return new HandleRef(this, source.Handle);
        }

        protected override void DestroyWindowCore(HandleRef hwnd)
        {
        }
    }

原因

正在探索……

参考资料

System.ComponentModel.Win32Exception (0x80004005): 无效的窗口句柄。

Tue, 22 Oct 2019 06:13:45 +0000

在 WPF 获取鼠标当前坐标的时候，可能会得到一个异常：System.ComponentModel.Win32Exception:“无效的窗口句柄。”。

本文解释此异常的原因和解决方法。

异常

获取鼠标当前相对于元素 element 的坐标的代码：

var point = Mouse.GetPosition(element);

或者，还有其他的代码：

var point1 = e.PointFromScreen(new Point());
var point2 = e.PointToScreen(new Point());

如果在按下窗口关闭按钮的时候调用以上代码，则会引发异常：

System.ComponentModel.Win32Exception (0x80004005): 无效的窗口句柄。
   at Point MS.Internal.PointUtil.ClientToScreen(Point pointClient, PresentationSource presentationSource)
   at Point System.Windows.Input.MouseDevice.GetScreenPositionFromSystem()

原因

将窗口上的点转换到控件上的点的方法是这样的：

/// <summary>
///     Convert a point from "client" coordinate space of a window into
///     the coordinate space of the screen.
/// </summary>
/// <SecurityNote>
///     SecurityCritical: This code causes eleveation to unmanaged code via call to GetWindowLong
///     SecurityTreatAsSafe: This data is ok to give out
///     validate all code paths that lead to this.
/// </SecurityNote>
[SecurityCritical, SecurityTreatAsSafe]
public static Point ClientToScreen(Point pointClient, PresentationSource presentationSource)
{
    // For now we only know how to use HwndSource.
    HwndSource inputSource = presentationSource as HwndSource;
    if(inputSource == null)
    {
        return pointClient;
    }
    HandleRef handleRef = new HandleRef(inputSource, inputSource.CriticalHandle);

    NativeMethods.POINT ptClient            = FromPoint(pointClient);
    NativeMethods.POINT ptClientRTLAdjusted = AdjustForRightToLeft(ptClient, handleRef);

    UnsafeNativeMethods.ClientToScreen(handleRef, ptClientRTLAdjusted);

    return ToPoint(ptClientRTLAdjusted);
}

最关键的是 UnsafeNativeMethods.ClientToScreen，此方法要求窗口句柄依然有效，然而此时窗口已经关闭，句柄已经销毁。

解决

使用 Direct3D11 的 OpenSharedResource 方法渲染来自其他进程/设备的共享资源（SharedHandle）

Tue, 22 Oct 2019 06:07:30 +0000

如果你得到了一个来自于其他进程或者其他模块的 Direct3D11 的共享资源，即 SharedHandle 句柄，那么可以使用本文提到的方法将其转换成 Direct3D11 的设备和纹理，这样你可以进行后续的其他处理。

SharpDX

本文的代码会使用到 SharpDX 库，因此，你需要在你的项目当中安装这些 NuGet 包：

<!-- 基础，必装 -->
<PackageReference Include="SharpDX" Version="4.2.0" />
<PackageReference Include="SharpDX.D3DCompiler" Version="4.2.0" />
<PackageReference Include="SharpDX.DXGI" Version="4.2.0" />
<PackageReference Include="SharpDX.Mathematics" Version="4.2.0" />
<PackageReference Include="SharpDX.Direct3D11" Version="4.2.0" />

<!-- 其他，可选 -->
<PackageReference Include="SharpDX.Direct2D1" Version="4.2.0" />
<PackageReference Include="SharpDX.Direct3D9" Version="4.2.0" />

SharedHandle

Direct3D 支持在不同的 Direct3D 设备之间共享资源。需要设置 ResourceOptionFlags 为 Shared 的纹理才可以支持共享，当然这不是本文要说的重点。

本文要说的是，如果你拿到了一个来自于其他模块的共享资源句柄的时候，你可以如何使用它。

你的使用可能类似于这样：

public void OnAcceleratedPaint(IntPtr sharedHandle, Int32Rect dirtyRect)
{
    // 通过 sharedHandle 进行后续的处理。
}

OpenSharedResource

DirectX 中用来表示 Direct3D11 的设备类型是 ID3D11Device，它有一个 OpenSharedResource 方法可以用来打开来自于其他设备的共享资源。

对应到 SharpDX 中，用来表示 Direct3D11 的设备的类型是 SharpDX.Direct3D11.Device，其有一个 OpenSharedResource<T> 方法来打开来自于其他设备的共享资源。

我们必须要创建一个自己的 Direct3D11 设备，因为设备是不共享的，代码如下：

var device = new SharpDX.Direct3D11.Device(DriverType.Hardware, DeviceCreationFlags.BgraSupport);
var resource = device.OpenSharedResource<SharpDX.Direct3D11.Resource>(sharedHandle);

后续操作

在得到此共享资源之后，我们可以获得更多关于此资源的描述，以及有限地使用此资源的方法。

获取 Texture2D

可以通过 QueryInterface 获取某个资源相关的 COM 对象的引用。我们拿到的共享资源是 2D 纹理的话，我们可以使用 QueryInterface 获取 SharpDX.Direct3D11.Texture2D COM 对象的引用。

var texture = resource.QueryInterface<SharpDX.Direct3D11.Texture2D>();

获取 Texture2DDescription

可以从 Texture2D 的实例中获取到 Texture2DDescription，这是用来描述此 2D 纹理创建时的各种信息。

// 在 DirectX 的传统代码中，通常使用 desc 来作为 Texture2DDescription 实例命名的后缀。
// 不过 C# 代码通常不这么干，这是 C++ 代码的习惯。在这里这么写是为了在得到 C++ 搜索结果的时候可以与本文所述的 C# 代码对应起来。
var desc = texture.Description;

获取 Surface

或者，我们可以获取到 2D 图面，用于做渲染、绘制等操作。当然，是否能真正进行这些操作取决于 Texture2DDescription 中是否允许相关的操作。

var surface = texture2D.QueryInterface<SharpDX.DXGI.Surface>();

在获取到 SharpDX.DXGI.Surface 的 COM 组件引用之后，可以在内存中映射位图用于调试，可以参见：

将 Direct3D11 在 GPU 中的纹理（Texture2D）导出到内存或导出成图片文件

参考资料

将 Direct3D11 在 GPU 中的纹理（Texture2D）导出到内存（Map）或导出成图片文件

Tue, 22 Oct 2019 06:07:29 +0000

Direct3D11 的使用通常不是应用程序唯一的部分，于是使用 Direct3D11 的代码如何与其他模块正确地组合在一起就是一个需要解决的问题。

本文介绍将 Direct3D11 在 GPU 中绘制的纹理映射到内存中，这样我们可以直接观察到此纹理是否是正确的，而不用担心是否有其他模块影响了最终的渲染过程。

SharpDX

本文的代码会使用到 SharpDX 库，因此，你需要在你的项目当中安装这些 NuGet 包：

<!-- 基础，必装 -->
<PackageReference Include="SharpDX" Version="4.2.0" />
<PackageReference Include="SharpDX.D3DCompiler" Version="4.2.0" />
<PackageReference Include="SharpDX.DXGI" Version="4.2.0" />
<PackageReference Include="SharpDX.Mathematics" Version="4.2.0" />
<PackageReference Include="SharpDX.Direct3D11" Version="4.2.0" />

<!-- 其他，可选 -->
<PackageReference Include="SharpDX.Direct2D1" Version="4.2.0" />
<PackageReference Include="SharpDX.Direct3D9" Version="4.2.0" />

来自于 Direct3D11 的渲染纹理

本文不会说如何创建或者获取来自 Direct3D11 的渲染纹理，不过如果你希望了解，可以：

自己创建：WPF 使用封装的 SharpDx 控件
或者从其他进程/模块获取：使用 Direct3D11 的 OpenSharedResource 方法渲染来自其他进程/设备的共享资源（SharedHandle）

本文接下来的内容，是在你已经获得了 SharpDX.Direct3D11.Resource 的引用，或者 SharpDX.Direct3D11.Texture2D 的前提之下。当然，如果你获得了其中任何一个实例，可以通过 COM 组件的 QueryInterface 方法获得其他实例。

var texture = resource.QueryInterface<SharpDX.Direct3D11.Texture2D>();

var resource = texture.QueryInterface<SharpDX.Direct3D11.Resource>();

关键代码（SharpDX.DXGI.Surface.Map）

要获得 GPU 中渲染的图片，我们必须要将其映射到内存中才行。而映射到内存中的核心代码是 SharpDX.DXGI.Surface 对象的 Map 方法。

using (var surface = texture2D.QueryInterface<SharpDX.DXGI.Surface>())
{
    var map = surface.Map(SharpDX.DXGI.MapFlags.Read, out DataStream dataStream);
    for (var y = 0; y < surface.Description.Height; y++)
    {
        for (var x = 0; x < surface.Description.Width; x++)
        {
            // 在这里使用位图的像素数据，坐标为 (x, y)。
            // 得到此坐标下的像素指针：
            //     var ptr = ((byte*)map.DataPointer) + y * map.Pitch;
            // 得到此像素的颜色值：
            //     var b = *(ptr + 4 * x);
            //     var g = *(ptr + 4 * x + 1);
            //     var r = *(ptr + 4 * x + 2);
            //     var a = *(ptr + 4 * x + 3);
        }
    }
    dataStream.Dispose();
    surface.Unmap();
}

注意以上代码使用了不安全代码（指针），你需要为你的项目开启不安全代码开关，详见：

如何在 .NET 项目中开启不安全代码（以便启用 unsafe fixed 等关键字）

你可能需要拷贝资源

实际上，在使用上面的代码时，你可能会遇到错误，错误出现在 Map 方法的调用上，描述为“参数错误”。实际上真正检查这里的两个参数时并不能发现究竟是哪个参数出了问题。

实际上出问题的参数是 surface 的实例。

一段 GPU 中的纹理要能够被映射到内存，必须要具有 CPU 的访问权。而是否具有 CPU 访问权在创建纹理的时候就已经确定下来了。

如果前面你得到的纹理是自己创建的，那么恭喜你，你只需要改一下创建纹理的参数就好了。给 Texture2DDescription 的 CpuAccessFlags 属性加上 CpuAccessFlags.Read 标识。

desc.CpuAccessFlags = CpuAccessFlags.Read；

但是，如果此纹理不是由你自己创建的，那么就需要拷贝一份新的纹理了。当然，拷贝过程发生在 GPU 中，占用的也是 GPU 专用内存（即显存，如果有的话）。

拷贝需要做到两点：

创建一个新的 Texture2DDescription（一定要是新的实例，你不能影响原来的实例），然后修改其 CPU 访问权限为 Read；
使用 ImmediateContext 实例的 CopyResource 方法来拷贝资源（此实例可以通过 SharpDX.Direct3D11.Device 来找到）。

var originalDesc = originalTexture.Description;
var desc = new Texture2DDescription
{
    CpuAccessFlags = CpuAccessFlags.Read,
    BindFlags = BindFlags.None,
    Usage = ResourceUsage.Staging,
    Width = originalDesc.Width,
    Height = originalDesc.Height,
    Format = originalDesc.Format,
    MipLevels = 1,
    ArraySize = 1,
    SampleDescription =
    {
        Count = 1,
        Quality = 0
    },
};

var texture2D = new Texture2D(device, desc);
device.ImmediateContext.CopyResource(originalTexture, texture2D);

需要注意，拷贝纹理会额外占用显存，一般不建议这么做，除非你真的有需求一定要 CPU 能够访问到这段纹理。

导出成图片文件

实际上，当你组合起来以上以上方法，你应该能够将纹理导出成图片了。

不过，为了理解更方便一些，我还是将导出成图片的全部代码贴出来：

public static unsafe void MapTexture2DToFile(SharpDX.Direct3D11.Texture2D texture, string fileName)
{
    // 获取 Texture2D 的相关实例。
    var device = texture.Device;
    var originDesc = texture.Description;

    // 创建新的 Texture2D 对象。
    var desc = new Texture2DDescription
    {
        CpuAccessFlags = CpuAccessFlags.Read,
        BindFlags = BindFlags.None,
        Usage = ResourceUsage.Staging,
        Width = originDesc.Width,
        Height = originDesc.Height,
        Format = originDesc.Format,
        MipLevels = 1,
        ArraySize = 1,
        SampleDescription =
        {
            Count = 1,
            Quality = 0
        },
        OptionFlags = ResourceOptionFlags.Shared
    };
    var texture2D = new Texture2D(device, desc);

    // 拷贝资源。
    device.ImmediateContext.CopyResource(texture, texture2D);

    var bitmap = new System.Drawing.Bitmap(desc.Width, desc.Height);
    using (var surface = texture2D.QueryInterface<SharpDX.DXGI.Surface>())
    {
        var map = surface.Map(SharpDX.DXGI.MapFlags.Read, out DataStream dataStream);
        var lines = (int)(dataStream.Length / map.Pitch);
        var actualWidth = surface.Description.Width * 4;
        for (var y = 0; y < desc.Height; y++)
        {
            var h = desc.Height - y;
            var ptr = ((byte*)map.DataPointer) + y * map.Pitch;

            for (var x = 0; x < desc.Width; x++)
            {
                var b = *(ptr + 4 * x);
                var g = *(ptr + 4 * x + 1);
                var r = *(ptr + 4 * x + 2);
                var a = *(ptr + 4 * x + 3);
                bitmap.SetPixel(x, y, System.Drawing.Color.FromArgb(a, r, g, b));
            }
        }
        dataStream.Dispose();
        surface.Unmap();
        bitmap.Save(fileName);
    }
}

如果你是希望以纯软件的方式渲染到 WPF 中（WriteableBitmap），可以参考：

WPF 高性能位图渲染 WriteableBitmap 及其高性能用法示例

记得打开不安全代码开关哦！详见：

如何在 .NET 项目中开启不安全代码（以便启用 unsafe fixed 等关键字）

参考资料

.NET 实现 NTFS 文件系统的硬链接 mklink /J（Junction）

Tue, 22 Oct 2019 06:04:24 +0000

我们知道 Windows 系统 NTFS 文件系统提供了硬连接功能，可以通过 mklink 命令开启。如果能够通过代码实现，那么我们能够做更多有趣的事情。

本文提供使用 .NET/C# 代码创建 NTFS 文件系统的硬连接功能（目录联接）。

目录联接

以管理员权限启动 CMD（命令提示符），输入 mklink 命令可以得知 mklink 的用法。

C:\WINDOWS\system32>mklink
创建符号链接。

MKLINK [[/D] | [/H] | [/J]] Link Target

        /D      创建目录符号链接。默认为文件
                符号链接。
        /H      创建硬链接而非符号链接。
        /J      创建目录联接。
        Link    指定新的符号链接名称。
        Target  指定新链接引用的路径
                (相对或绝对)。

我们本次要用 .NET/C# 代码实现的是 /J 目录联接。实现的效果像这样：

这些文件夹带有一个“快捷方式”的角标，似乎是另一些文件夹的快捷方式一样。但这些与快捷方式的区别在于，应用程序读取路径的时候，目录联接会成为路径的一部分。

比如在 D:\Walterlv\NuGet\ 中创建 debug 目录联接，目标设为 D:\Walterlv\DemoRepo\bin\Debug，那么，你在各种应用程序中使用以下两个路径将被视为同一个：

D:\Walterlv\NuGet\debug\DemoRepo-1.0.0.nupkg
D:\Walterlv\DemoRepo\bin\Debug\DemoRepo-1.0.0.nupkg

或者这种：

D:\Walterlv\NuGet\debug\publish\
D:\Walterlv\DemoRepo\bin\Debug\publish\

使用 .NET/C# 实现

本文的代码主要参考自 jeff.brown 在 Manipulating NTFS Junction Points in .NET - CodeProject 一文中所附带的源代码。

由于随时可能更新，所以你可以前往 GitHub 仓库打开此代码：

walterlv.demo/JunctionPoint.cs at master · walterlv/walterlv.demo

使用 JunctionPoint

如果希望在代码中创建目录联接，则直接使用：

JunctionPoint.Create("walterlv.demo", @"D:\Developments", true);

后面的 true 指定如果目录联接存在，则会覆盖掉原来的目录联接。

参考资料

WPF 高性能位图渲染 WriteableBitmap 及其高性能用法示例

Tue, 22 Oct 2019 04:43:29 +0000

WPF 渲染框架并没有对外提供多少可以完全控制渲染的部分，目前可以做的有：

D3DImage，用来承载使用 DirectX 各个版本渲染内容的控件
WriteableBitmap，通过一段内存空间来指定如何渲染一个位图的图片
HwndHost，通过承载一个子窗口以便能叠加任何种类渲染的控件

本文将解释如何最大程度压榨 WriteableBitmap 在 WPF 下的性能。

如何使用 WriteableBitmap

创建一个新的 WPF 项目，然后我们在 MainWindow.xaml 中编写一点可以用来显示 WriteableBitmap 的代码：

<Window x:Class="Walterlv.Demo.HighPerformanceBitmap.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:local="clr-namespace:Walterlv.Demo.HighPerformanceBitmap"
        Title="WriteableBitmap - walterlv" SizeToContent="WidthAndHeight">
    <Grid>
        <Image x:Name="Image" Width="1280" Height="720" />
    </Grid>
</Window>

为了评估其性能，我决定绘制和渲染 4K 品质的位图，并通过以下步骤来评估：

使用 CompositionTarget.Rendering 逐帧渲染以评估其渲染帧率
使用 Benchmark 基准测试来测试内部各种不同方法的性能差异

于是，在 MainWindow.xaml.cs 中添加一些测试用的修改 WriteableBitmap 的代码：

using System;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Input;
using System.Windows.Media;
using System.Windows.Media.Imaging;

namespace Walterlv.Demo.HighPerformanceBitmap
{
    public partial class MainWindow : Window
    {
        private readonly WriteableBitmap _bitmap;

        public MainWindow()
        {
            InitializeComponent();

            _bitmap = new WriteableBitmap(3840, 2160, 96.0, 96.0, PixelFormats.Pbgra32, null);
            Image.Source = _bitmap;
            CompositionTarget.Rendering += CompositionTarget_Rendering;
        }

        private void CompositionTarget_Rendering(object sender, EventArgs e)
        {
            var width = _bitmap.PixelWidth;
            var height = _bitmap.PixelHeight;

            _bitmap.Lock();

            // 在这里添加绘制位图的逻辑。

            _bitmap.AddDirtyRect(new Int32Rect(0, 0, width, height));
            _bitmap.Unlock();
        }
    }
}

注意，我留了一行注释说即将添加绘制位图的逻辑，接下来我们的主要内容将从此展开。

启用不安全代码

为了获取最佳性能，我们需要开启不安全代码。为此，你需要修改一下你的项目属性。

你可以阅读我的另一篇博客了解如何启用不安全代码：

如何在 .NET 项目中开启不安全代码（以便启用 unsafe fixed 等关键字） - walterlv

简单点说就是在你的项目文件中添加下面这一行：

    <Project Sdk="Microsoft.NET.Sdk">
      <PropertyGroup>
        <TargetFramework>netcoreapp3.0</TargetFramework>
++      <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
      </PropertyGroup>
    </Project>

启用帧率测试

接下来，我们需要添加一点点代码来评估 WriteableBitmap 的性能：

++  private readonly byte[] _empty4KBitmapArray = new byte[3840 * 2160 * 4];

--  private void CompositionTarget_Rendering(object sender, EventArgs e)
++  private unsafe void CompositionTarget_Rendering(object sender, EventArgs e)
    {
        var width = _bitmap.PixelWidth;
        var height = _bitmap.PixelHeight;

        _bitmap.Lock();

++      fixed (byte* ptr = _empty4KBitmapArray)
++      {
++          var p = new IntPtr(ptr);
++          Buffer.MemoryCopy(ptr, _bitmap.BackBuffer.ToPointer(), _empty4KBitmapArray.Length, _empty4KBitmapArray.Length);
++      }

        _bitmap.AddDirtyRect(new Int32Rect(0, 0, width, height));
        _bitmap.Unlock();
    }

嗯，就是将一个空的 4K 大小的数组中的内容复制到 WriteableBitmap 的位图缓存中。

4K 脏区

虽然我们看不到任何可变的修改，不过 WriteableBitmap 可不这么认为。因为我们调用了 AddDirtyRect 将整个位图空间都加入到了脏区中，这样 WPF 会重新渲染整幅位图。

Visual Studio 中看到的 CPU 占用率大约维持在 16% 左右（跟具体机器相关）；并且除了一开始启动的时候之外，完全没有 GC（这点很重要），内存稳定在一个值上不再变化。

也只有本文一开始提及的三种方法才可能做到渲染任何可能的图形的时候没有 GC

查看界面渲染帧率可以发现跑满 60 帧没有什么问题（跟具体机器相关）。

小脏区

现在，我们把脏区的区域缩小为 100*100，同样看性能数据。

--  _bitmap.AddDirtyRect(new Int32Rect(0, 0, width, height));
++  _bitmap.AddDirtyRect(new Int32Rect(0, 0, 100, 100));

可以发现 CPU 占用降低到一半（确实是大幅降低，但是跟像素数量并不成比例）；内存没有变化（废话，4K 图像是确定的）；帧率没有变化（废话，只要性能够，帧率就是满的）。

无脏区

现在，我们将脏区清零。

--  _bitmap.AddDirtyRect(new Int32Rect(0, 0, width, height));
++  _bitmap.AddDirtyRect(new Int32Rect(0, 0, 0, 0));

在完全没有脏区的时候，CPU 占用直接降为 0，这个性能提升还是非常恐怖的。

不渲染

如果我们不把 WriteableBitmap 设置为 Image 的 Source 属性，那么无论脏区多大，CPU 占用都是 0。

脏区大小与 CPU 占用率之间的关系

从前面的测试中我们可以发现，脏区的大小在 WriteableBitmap 的渲染里占了绝对的耗时。因此，我把脏区大小与 CPU 占用率之间的关系用图表的形式贴出来，这样可以直观地理解其性能差异。

需要注意，CPU 占用率与机器性能强相关，因此其绝对占用没有意义，但相对大小则有参考价值。

脏区大小	CPU 占用率	帧率
0*0	0.0%	60
1*1	5.1%	60
16*9	5.7%	60
160*90	6.0%	60
320*180	6.5%	60
640*360	6.9%	60
1280*720	7.5%	60
1920*1080	10.5%	60
2560*1440	12.3%	60
3840*2160	16.1%	60

根据这张表我么可以得出：

脏区渲染是 CPU 占用的最大瓶颈（因为没有脏区仅剩内存拷贝的时候 CPU 占用为 0%）

但是有一个需要注意的信息是——虽然 CPU 占用率受脏区影响非常大，但主线程却几乎没有消耗 CPU 占用。此占用基本上全是渲染线程的事。

如果我们分析主线程的性能分布，可以发现内存拷贝现在是性能瓶颈：

后面我们会提到 WriteableBitmap 的渲染原理，也会说到这一点。

启用基准测试（Benchmark）

不过，由于内存数据的拷贝和脏区渲染实际上可以分开到两个不同的线程，如果这两者不同步执行（可能执行次数还有差异）的情况下，内存拷贝也可能成为性能瓶颈的一部分。

于是我将不同的内存拷贝方法进行一个基准测试，便于大家评估使用哪种方法来为 WriteableBitmap 提供渲染数据。

使用 `CopyMemory` 拷贝内存

++  [Benchmark(Description = "CopyMemory")]
++  [Arguments(3840, 2160)]
++  [Arguments(100, 100)]
    public unsafe void CopyMemory(int width, int height)
    {
        _bitmap.Lock();

++      fixed (byte* ptr = _empty4KBitmapArray)
++      {
++          var p = new IntPtr(ptr);
++          CopyMemory(_bitmap.BackBuffer, new IntPtr(ptr), (uint)_empty4KBitmapArray.Length);
++      }

        _bitmap.AddDirtyRect(new Int32Rect(0, 0, width, height));
        _bitmap.Unlock();
    }

[DllImport("kernel32.dll")]
private static extern void CopyMemory(IntPtr destination, IntPtr source, uint length);

使用 `MoveMemory` 移动内存

++  [Benchmark(Description = "RtlMoveMemory")]
++  [Arguments(3840, 2160)]
++  [Arguments(100, 100)]
    public unsafe void RtlMoveMemory(int width, int height)
    {
        _bitmap.Lock();

++      fixed (byte* ptr = _empty4KBitmapArray)
++      {
++          var p = new IntPtr(ptr);
++          MoveMemory(_bitmap.BackBuffer, new IntPtr(ptr), (uint)_empty4KBitmapArray.Length);
++      }

        _bitmap.AddDirtyRect(new Int32Rect(0, 0, width, height));
        _bitmap.Unlock();
    }

    [DllImport("kernel32.dll", EntryPoint = "RtlMoveMemory")]
    private static extern void MoveMemory(IntPtr dest, IntPtr src, uint count);

使用 `Buffer.MemoryCopy` 拷贝内存

需要注意，Buffer.MemoryCopy 是 .NET Framework 4.6 才引入的 API，在 .NET Framework 后续版本以及 .NET Core 的所有版本才可以使用，更旧版本的 .NET Framework 没有这个 API。

++  [Benchmark(Baseline = true, Description = "Buffer.MemoryCopy")]
++  [Arguments(3840, 2160)]
++  [Arguments(100, 100)]
    public unsafe void BufferMemoryCopy(int width, int height)
    {
        _bitmap.Lock();

++      fixed (byte* ptr = _empty4KBitmapArray)
++      {
++          var p = new IntPtr(ptr);
++          Buffer.MemoryCopy(ptr, _bitmap.BackBuffer.ToPointer(), _empty4KBitmapArray.Length, _empty4KBitmapArray.Length);
++      }

        _bitmap.AddDirtyRect(new Int32Rect(0, 0, width, height));
        _bitmap.Unlock();
    }

自己写 for 循环

++  [Benchmark(Description = "for for")]
++  [Arguments(3840, 2160)]
++  [Arguments(100, 100)]
    public unsafe void ForForCopy(int width, int height)
    {
        _bitmap.Lock();

++      var buffer = (byte*)_bitmap.BackBuffer.ToPointer();
++      for (var j = 0; j < height; j++)
++      {
++          for (var i = 0; i < width; i++)
++          {
++              var pixel = buffer + j * width * 4 + i * 4;
++              *pixel = 0xff;
++              *(pixel + 1) = 0x7f;
++              *(pixel + 2) = 0x00;
++              *(pixel + 3) = 0xff;
++          }
++      }

        _bitmap.AddDirtyRect(new Int32Rect(0, 0, width, height));
        _bitmap.Unlock();
    }

基准测试数据

我们跑一次基准测试：

Method	Mean	Error	StdDev	Median	Ratio	RatioSD
CopyMemory	2.723 ms	0.0642 ms	0.1881 ms	2.677 ms	0.84	0.08
RtlMoveMemory	2.659 ms	0.0740 ms	0.2158 ms	2.633 ms	0.82	0.08
Buffer.MemoryCopy	3.246 ms	0.0776 ms	0.2250 ms	3.200 ms	1.00	0.00
‘for for’	10.401 ms	0.1979 ms	0.4964 ms	10.396 ms	3.21	0.25
‘CopyMemory with 100*100 dirty region’	2.446 ms	0.0757 ms	0.2207 ms	2.368 ms	0.76	0.09
‘RtlMoveMemory with 100*100 dirty region’	2.415 ms	0.0733 ms	0.2161 ms	2.369 ms	0.75	0.08
‘Buffer.MemoryCopy with 100*100 dirty region’	3.076 ms	0.0612 ms	0.1523 ms	3.072 ms	0.95	0.08
‘for for with 100*100 dirty region’	10.014 ms	0.2398 ms	0.6995 ms	9.887 ms	3.10	0.29

可以发现：

CopyMemory 和 RtMoveMemory 性能是最好的，其性能差不多；
自己写循环拷贝内存的性能是最差的；
如果 WriteableBitmap 不渲染，那么无论设置多大的脏区都不会对性能有任何影响。

结论和使用建议

综合前面两者的结论，我们可以发现：

WriteableBitmap 的性能瓶颈源于对脏区的重新渲染
- 脏区为 0 或者不在可视化树渲染，则不消耗性能
- 只要有脏区，渲染过程就会开始成为性能瓶颈
  - CPU 占用基础值就很高了
  - 脏区越大，CPU 占用越高，但增幅不大
内存拷贝不是 WriteableBitmap 的性能瓶颈
- 建议使用 Windows API 或者 .NET API 来拷贝内存（而不是自己写）

另外，如果你有一些特殊的应用场景，可以适当调整下自己写代码的策略：

如果你希望有较大脏区的情况下降低 CPU 占用，可以考虑降低 WriteableBitmap 脏区的刷新率
如果你希望 WriteableBitmap 有较低的渲染延迟，则考虑减小脏区

WriteableBitmap 渲染原理

在调用 WriteableBitmap 的 AddDirtyRect 方法的时候，实际上是调用 MILSwDoubleBufferedBitmap.AddDirtyRect，这是 WPF 专门为 WriteableBitmap 而提供的非托管代码的双缓冲位图的实现。

在 WriteableBitmap 内部数组修改完毕之后，需要调用 Unlock 来解锁内部缓冲区的访问，这时会提交所有的修改。接下来的渲染都交给了 MediaContext，用来完成双缓冲位图的渲染。

private void SubscribeToCommittingBatch()
{
    // Only subscribe the the CommittingBatch event if we are on-channel.
    if (!_isWaitingForCommit)
    {
        MediaContext mediaContext = MediaContext.From(Dispatcher);
        if (_duceResource.IsOnChannel(mediaContext.Channel))
        {
            mediaContext.CommittingBatch += CommittingBatchHandler;
            _isWaitingForCommit = true;
        }
    }
}

在上面的 CommittingBatchHandler 中，将渲染指令发送到了渲染线程。

channel.SendCommand((byte*)&command, sizeof(DUCE.MILCMD_DOUBLEBUFFEREDBITMAP_COPYFORWARD));

前面我们通过脏区大小可以得出内存拷贝不是 CPU 占用率的瓶颈，脏区大小才是，不过是渲染线程在占用这 CPU 而不是主线程。但是内存拷贝却成为了主线程的瓶颈（当然前面我们给出了数据，实际上非常小）。所以如果试图分析这么高 CPU 的占用，会发现并不能从主线程上调查得出符合预期的结论（因为即便你完全干掉了内存拷贝，CPU 占用依然是这么高）。

.NET Framework 4.x 程序到底运行在哪个 CLR 版本之上

Wed, 16 Oct 2019 01:42:52 +0000

当我们编译程序目标框架选为 .NET Framework 4.5/4.6/4.7/4.8 时，CLR 运行时是如何判断我们究竟应该用哪一个 .NET Framework 呢？.NET Framework 的版本到底由哪些部分组成？我们编译 .NET Framework 时选择的版本决定了什么？

让我对这个问题产生兴趣的原因是：

我将程序编译的目标框架选为 .NET Framework 4.8；在一台安装了 .NET Framework 4.6 的电脑上提示缺少 .NET Framework 4.8；删除了随编译一起生成的 app.config 文件后程序能够正常运行。
另一个程序，我明明将程序编译的目标框架选为 .NET Framework 4.5，但在一台没有安装任何额外 .NET Framework 的 Windows 7 的电脑上提示缺少的是 .NET Framework 4.0。

这里的疑点在于为什么以上两种看似类似的情况，提示的框架版本却不同。其中的 app.config 文件成为了调查此问题的突破口。

配置支持的运行时

观察程序附带的 app.config 文件，我们发现支持的运行时版本是 v4.0，sku 版本是 4.8。

<configuration>  
   <startup>  
      <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.8" />  
   </startup>  
</configuration>  

疑点：

为什么我们基于 .NET Framework 4.8 开发的程序运行时版本是 4.0？
sku 是什么？

微软的官方文档给了我们解答：supportedRuntime Element。

version：用于指定此应用程序支持的公共语言运行时（CLR）的版本。
sku：stock-keeping unit（官方中文为“库存单位”，然而依然不懂这个词的意思），用于指定此应用程序支持的 .NET Framework 发行版本。

version 的值可取：

.NET Framework 版本	`version` 值
忽略早期版本	忽略早期版本
2.0	“v2.0.50727”
3.0	“v2.0.50727”
3.5	“v2.0.50727”
3.5	“v2.0.50727”
4.0-4.8	“v4.0”

sku 的值可取：

.NET Framework version	`sku` 值
4.0	“.NETFramework,Version=v4.0”
忽略中间版本	忽略中间版本
4.5	“.NETFramework,Version=v4.5”
4.5.1	“.NETFramework,Version=v4.5.1”
4.5.2	“.NETFramework,Version=v4.5.2”
4.6	“.NETFramework,Version=v4.6”
4.6.1	“.NETFramework,Version=v4.6.1”
4.6.2	“.NETFramework,Version=v4.6.2”
4.7	“.NETFramework,Version=v4.7”
4.7.1	“.NETFramework,Version=v4.7.1”
4.7.2	“.NETFramework,Version=v4.7.2”
4.8	“.NETFramework,Version=v4.8”

于是我们发现，其实无论我们将程序的目标框架选为 .NET Framework 的哪一个 4.x 版本，CLR 运行时都是用 v4.0 表示的。微软的描述是：

对于支持 .NET Framework 4.0 或更高版本的应用程序，version 属性指示 CLR 版本，这是 .NET Framework 4 及更高版本的通用版本，而 sku 属性指示应用程序所针对的单个 .NET Framework 版本。

其实看到这里我们就能有一个看似不错的解释：

无论我们选择的目标框架是 .NET Framework 4.x 的哪一个版本，用于指定 CLR 运行时版本的 version 值都是 v4.0；
CLR 运行时会根据配置文件的 sku 值决定应该采用那一组运行库来为程序运行提供支持。

.NET Framework 的组成以及各部分的版本

我们需要寻找到 .NET Framework 的本质，不然如此错综复杂的版本号系统真把我搞懵了。

微软在 .NET Framework Versions and Dependencies 中说到：

每个版本的 .NET Framework 都包含公共语言运行时 (CLR)、基础库和其他托管库。

于是我们谈论 .NET Framework 的版本其实应该分三个不同的部分来谈：

每个新版本的 .NET Framework 都会保留早期版本中的功能并会添加新功能。 CLR 有其自己的版本号标识。虽然 CLR 版本并不总是递增的，但 .NET Framework 版本号在每次发布时都会递增。例如，.NET Framework 4、4.5 和更高版本包含 CLR 4，而 .NET Framework 2.0、3.0 和 3.5 包含 CLR 2.0。（没有版本 3 的 CLR。）

从官方文档给出的表格当中我们可以确信：.NET Framework 4.0/4.5/4.6/4.7 包含的 CLR 版本都是 4.0。

CLR 的更新

然而，不相信微软的 CLR 可以完全没有 BUG，既然 CLR 版本都是 4.0，那么微软对 CLR 运行时的更新怎么处理？安装了 .NET Framework 4.5/4.6/4.7 会如何提升 CLR 的稳定性和安全性？

在 Targeting and Running .NET Framework apps for version 4.5 and later 中，解释了 CLR 的更新机制——就地更新（in-place update）。这篇文章 .NET 4.5 is an in-place replacement for .NET 4.0 对这种就地更新方式有比官方文档更详细的解释，并且还附带自己的一些试验（含代码）。不过文章是 2012 年写的，部分结论现在看来已经过时（因为在我的 Windows 10 配 .NET Framework 4.7 上结论已经不一样），不过对我理解就地更新本身非常有帮助，也为后续调查提供了更清晰的思路。

微软对 .NET Framework 4.x 框架就地更新的说明是：

.NET Framework 4.5 是替代计算机上的 .NET Framework 4 的就地更新，同样，.NET Framework 4.5.1 4.5.2、4.6、4.6.1、4.6.2、4.7、4.7.1、4.7.2、4.8 是对 .NET Framework 4.5 的就地更新，这意味着它们将使用相同的运行时版本，但是程序集版本会更新并包括新类型和成员。在安装其中某个更新后，你的 .NET Framework 4.NET Framework 4.5 或 .NET Framework 4.6 应用应继续运行，而无需重新编译。但是，反过来则不行。

也就是说，无论我们在开发时指定目标框架的版本是 4.x 的哪一个，在运行时，CLR 环境都是 4.0。但是新的 .NET Framework 会带来更新版本的 CLR，这个 CLR 会直接替换掉旧的 CLR。.NET 4.5 is an in-place replacement for .NET 4.0 文章中 .NET Framework 基础库也是就地更新的；但我实际实验的情况是每一个不同的 .NET Framework 基础库有自己单独的文件夹，目前尚不清楚这个改变是从 .NET Framework 的哪一个版本开始的，但一定是 4.5.1、4.5.2、4.6 这三个版本中的一个。

解决一开始的疑问

于是，本文一开始的疑问就全部明晰了：

不管是 .NET Framework 4.5 的还是 4.8 的那两个程序，都是靠 4.0 版本的公共语言运行时（CLR）运行起来的；
如果没有安装 4.0 版本的 CLR，则会弹出提示需要安装 .NET Framework 4.0 版本才能运行，而不管我们的程序目标框架是 .NET Framework 4.x 的哪一个版本；
- 虽然说文案说的是 .NET Framework，但其实需要的是 CLR
如果已经安装有 4.0 版本的 CLR（可能随 .NET Framework 4.5/4.6 安装），我们程序的目标框架是 .NET Framework 4.8，但 .NET Framework 基础库并没有安装 4.8 版本，则运行时会提示需要安装 .NET Framework 4.7；
- 这个提示是 4.0 版的 CLR 弹出的，是根据 supportedRuntime 中指定的 sku 值来决定的

参考资料

使用 .editorconfig 配置 .NET/C# 项目的代码分析规则的严重程度

Sat, 12 Oct 2019 03:35:04 +0000

随着 Visual Studio 2019 更新，在 Visual Studio 中编写代码的时候也带来了基于 Roslyn 的代码质量分析。有一些代码分析严重程度可能与团队约定的不一致，这时就需要配置规则的严重程度。另外如果是个人使用插件安装了分析器，也可以配置一些严重程度满足个人的喜好。

本文介绍使用 .editorconfig 文件来配置 .NET/C# 项目中，代码分析规则的严重性。可以是全局的，也可以每个项目有自己的配置。

生效范围与继承

.editorconfig 文件可以在你的项目中的任何地方，甚至是代码仓库之外。是按照文件夹结构来继承生效的。

比如我的项目结构是这样：

+ Walterlv.Demo
    + Core
        - .editorconfig
        - Foo.cs
    - .editorconfig
    - Program.cs

那么 Foo.cs 文件的规则严重性将受 Core 文件夹中的 .editorconfig 文件管理，如果有些规则不在此文件夹的 .editorconfig 里面，就会受外层 .editorconfig 管理。

另外，你甚至可以在整个代码仓库的外部文件夹放一个 .editorconfig 文件，这样，如果项目中没有对应的规则，那么外面文件夹中的 .editorconfig 规则就会生效，这相当于间接做了一个全局生效的规则集。

.editorconfig 中的内容

.editorconfig 中的分析器严重性内容就像下面这样：

[*.cs]

# CC0097: You have missing/unexistent parameters in Xml Docs
dotnet_diagnostic.CC0097.severity = error

# CA1031: Do not catch general exception types
dotnet_diagnostic.CA1031.severity = suggestion

# IDE0051: 删除未使用的私有成员
dotnet_diagnostic.IDE0051.severity = none

对于 C# 语言的规则，在 [*.cs] 区，每个规则格式是 dotnet_diagnostic.{DiagnosticId}.severity = {Severity}。

当然，我们不需要手工书写这个文件，了解它的格式只是为了出问题的时候不至于一脸懵逼。

配置严重程度

使用 Visual Studio 2019，配置规则严重性非常简单。当然，16.3 以上版本才这么简单，之前的版本步骤多一点。

在提示有问题的代码上按下重构快捷键（默认是 Ctrl + .），可以出现重构菜单，其中就有配置规则严重性的选项，直接选择即可自动添加到 .editorconfig 文件中。如果项目中没有 .editorconfig 文件，则会自动在解决方案同目录下创建一个新的。

对这部分快捷键不了解的话可以阅读：提高使用 Visual Studio 开发效率的键盘快捷键 - walterlv。

什么是模态窗口？本文带你了解模态窗口的本质

Thu, 10 Oct 2019 11:28:26 +0000

做 Windows 桌面应用开发的小伙伴们对“模态窗口”（Modal Dialog）一定不陌生。如果你希望在模态窗口之上做更多的事情，或者自己实现一套模态窗口类似的机制，那么你可能需要了解模态窗口的本质。

本文不会太深，只是从模态窗口一词出发，抵达大家都熟知的一些知识为止。

开发中的模态窗口

在各种系统、语言和框架中，只要有用户可以看见的界面，都存在模态窗口的概念。从交互层面来说，它的形式是在保留主界面作为环境来显示的情况下，打开一个新的界面，用户只能在新的界面上操作，完成或取消后才能返回主界面。从作用上来说，通常是要求用户必须提供某些信息后才能继续操作，或者单纯只是为了广告。

模态窗口的三个特点

如果你希望自己搞一套模态窗口出来，那么只需要满足这三点即可。你可以随便加戏但那都无关紧要。

保留主界面显示的同时，禁用主界面的用户交互；
显示子界面，主界面在子界面操作完成后返回；
当用户试图跳过子界面的交互的时候进行强提醒。

拿 Windows 系统中的模态对话框为例子，大概就像下面这两张图片这样：

有一个小的子界面盖住了主界面，要求用户必须进行选择。Windows 系统设置因为让背景变暗了，所以用户肯定会看得到需要进行的交互；而任务管理器没有让主界面变暗，所以用户在操作子界面的时候，模态窗口的边框和标题栏闪烁以提醒用户注意。

实现模态窗口

对于 Windows 操作系统来说，模态窗口并不是一个单一的概念，你并不能仅通过一个 API 调用就完成显示模态窗口，你需要在不同的时机调用不同的 API 来完成一个模态窗口。如果要完整实现一个自己的模态窗口，则需要编写实现以上三个特点的代码。

当然，你可能会发现实际上你显示一个模态窗口仅仅一句话调用就够了，那是因为你所用的应用程序框架帮你完成了模态窗口的一系列机制。

关于 WPF 框架是如何实现模态窗口的，可以阅读：直击本质：WPF 框架是如何实现模态窗口的

关于如何自己实现一个跨越线程/进程边界的模态窗口，可以阅读：实现 Windows 系统上跨进程/跨线程的模态窗口

如果你希望定制以上第三个特点中强提醒的动画效果，可以阅读：WPF window 子窗口反馈效果（抖动/阴影渐变) - 唐宋元明清2188 - 博客园。

API 调用

为了在 Windows 上实现模态窗口，需要一些 Win32 API 调用（当然，框架够用的话直接用框架就好）。

禁用主窗口

我们需要使用到 BOOL EnableWindow(HWND hWnd, BOOL bEnable); 来启用与禁用某个窗口。

EnableWindow(hWnd, false);
try
{
    // 模态显示一个窗口。
}
finally
{
    EnableWindow(hWnd, true);
}

[DllImport("user32")]
private static extern bool EnableWindow(IntPtr hwnd, bool bEnable);

阻塞代码等待操作完成

因为 async/await 的出现，阻塞其实可以使用 await 来实现。虽然这不是真正的阻塞，但可以真实反应出“异步”这个过程，也就是虽然这里在等待，但实际上依然能够继续在同一个线程响应用户的操作。

UWP 中的新 API 当然已经都是使用 async/await 来实现模态等待了，不过 WPF/Windows Forms 比较早，只能使用 Dispatcher 线程模型来实现模态等待。

于是我们可以考虑直接使用现成的 Dispatcher 线程模型来完成等待，方法是调用下面两个当中的任何一个：

Window.ShowDialog 也就是直接使用窗口原生的模态
Dispatcher.PushFrame 新开一个消息循环以阻塞当前代码的同时继续响应 UI 交互

上面 Window.ShowDialog 的本质也是在调用 Dispatcher.PushFrame，详见：

直击本质：WPF 框架是如何实现模态窗口的

关于 PushFrame 新开消息循环阻塞的原理可以参考：

深入了解 WPF Dispatcher 的工作原理（PushFrame 部分） - walterlv

当然，还有其他可以新开消息循环的方法。

进行 UI 强提醒

由于我们一开始禁用了主窗口，所以如果用户试图操作主窗口是不会有效果的。然而如果用户不知道当前显示了一个模态窗口需要操作，那么给出提醒也是必要的。

简单的在 UI 上的提醒是最简单的了，比如：

将主界面变暗（UWP 应用，Web 应用喜欢这么做）
将主界面变模糊（iOS 应用喜欢这么做）
在模态窗口上增加一个很厚重的阴影（Android 应用喜欢这么做）

然而 Windows 和 Mac OS 这些古老的系统由于兼容性负担不能随便那么改，于是需要有其他的提醒方式。

Windows 采用的方式是让标题栏闪烁，让阴影闪烁。

而这些特效的处理，来自于子窗口需要处理一些特定的消息 WM_SETCURSOR。

详见：WPF window 子窗口反馈效果（抖动/阴影渐变) - 唐宋元明清2188 - 博客园

通常你不需要手工处理这些消息，但是如果你完全定制了窗口样式，则可能需要自行做一个这样的模态窗口提醒效果。

直击本质：WPF 框架是如何实现模态窗口的

Thu, 10 Oct 2019 10:57:27 +0000

想知道你在 WPF 编写 Window.ShowDialog() 之后，WPF 框架是如何帮你实现模态窗口的吗？

本文就带你来了解这一些。

`Window.ShowDialog`

WPF 显示模态窗口的方法就是 Window.ShowDialog，因此我们直接进入这个方法查看。由于 .NET Core 版本的 WPF 已经开源，我们会使用 .NET Core 版本的 WPF 源代码。

Window.ShowDialog 的源代码可以在这里查看：

Window.cs

这个方法非常长，所以我只把其中与模态窗口最关键的代码和相关注释留下，其他都删除（这当然是不可编译的）：

public Nullable<bool> ShowDialog()
{
    // NOTE:
    // _threadWindowHandles is created here.  This reference is nulled out in EnableThreadWindows
    // when it is called with a true parameter.  Please do not null it out anywhere else.
    // EnableThreadWindow(true) is called when dialog is going away.  Once dialog is closed and
    // thread windows have been enabled, then there no need to keep the array list around.
    // Please see BUG 929740 before making any changes to how _threadWindowHandles works.
    _threadWindowHandles = new ArrayList();
    //Get visible and enabled windows in the thread
    // If the callback function returns true for all windows in the thread, the return value is true.
    // If the callback function returns false on any enumerated window, or if there are no windows
    // found in the thread, the return value is false.
    // No need for use to actually check the return value.
    UnsafeNativeMethods.EnumThreadWindows(SafeNativeMethods.GetCurrentThreadId(),
                                            new NativeMethods.EnumThreadWindowsCallback(ThreadWindowsCallback),
                                            NativeMethods.NullHandleRef);
    //disable those windows
    EnableThreadWindows(false);

    try
    {
        _showingAsDialog = true;
        Show();
    }
    catch
    {
        // NOTE:
        // See BUG 929740.
        // _threadWindowHandles is created before calling ShowDialog and is deleted in
        // EnableThreadWindows (when it's called with true).
        //
        // Window dlg = new Window();
        // Button b = new button();
        // b.OnClick += new ClickHandler(OnClick);
        // dlg.ShowDialog();
        //
        //
        // void OnClick(...)
        // {
        //      dlg.Close();
        //      throw new Exception();
        // }
        //
        //
        // If above code is written, then we get inside this exception handler only after the dialog
        // is closed.  In that case all the windows that we disabled before showing the dialog have already
        // been enabled and _threadWindowHandles set to null in EnableThreadWindows.  Thus, we don't
        // need to do it again.
        //
        // In any other exception cases, we get in this handler before Dialog is closed and thus we do
        // need to enable all the disable windows.
        if (_threadWindowHandles != null)
        {
            // Some exception case. Re-enable the windows that were disabled
            EnableThreadWindows(true);
        }
    }
}

觉得代码还是太长？不要紧，我再简化一下：

EnumThreadWindows 获取当前线程的所有窗口
把当前线程中的所有窗口都禁用掉（用的是 Win32 API 的禁用哦，这不会导致窗口内控件的样式变为禁用状态）
将窗口显示出来（如果出现异常，则还原之前禁用的窗口）

可以注意到禁用掉的窗口是“当前线程”的哦。

`ShowHelper`

接下来的重点方法是 Window.ShowDialog 中的那句 Show()。在 Show() 之前设置了 _showingAsDialog 为 true，于是这里会调用 ShowHelper 方法并传入 true。

下面的代码也是精简后的 ShowHelper 方法：

private object ShowHelper(object booleanBox)
{
    try
    {
        // tell users we're going modal
        ComponentDispatcher.PushModal();

        _dispatcherFrame = new DispatcherFrame();
        Dispatcher.PushFrame(_dispatcherFrame);
    }
    finally
    {
        // tell users we're going non-modal
        ComponentDispatcher.PopModal();
    }
}

可以看到，重点是 PushModal、PopModal 以及 PushFrame。

PushFrame 的效果就是让调用 ShowDialog 的代码看起来就像阻塞了一样（实际上就是阻塞了，只不过开了新的消息循环看起来 UI 不卡）。

关于 PushFrame 为什么能够“阻塞”你的代码的同时还能继续响应 UI 操作的原理，可以阅读：

深入了解 WPF Dispatcher 的工作原理（PushFrame 部分） - walterlv

那么 ComponentDispatcher.PushModal 和 ComponentDispatcher.PopModal 呢？可以在这里（ComponentDispatcherThread.cs）看它的代码，实际上是为了模态计数以及引发事件的，对模态的效果没有本质上的影响。

.NET/C# 检测电脑上安装的 .NET Framework 的版本

Thu, 10 Oct 2019 08:51:58 +0000

如果你希望知道某台计算机上安装了哪些版本的 .NET Framework，那么正好本文可以帮助你解决问题。

如何找到已安装的 .NET Framework

有的电脑的 .NET Framework 是自带的，有的是操作系统自带的。这样，你就不能通过控制面板的“卸载程序”去找到到底安装了哪个版本的 .NET Framework 了。

关于各个版本 Windows 10 上自带的 .NET Framework 版本，可以阅读各个版本 Windows 10 系统中自带的 .NET Framework 版本 - walterlv。

而如果通过代码 Environment.Version 来获取 .NET 版本，实际上获取的是 CLR 的版本，详见使用 PowerShell 获取 CLR 版本号 - walterlv。

这些版本号是不同的，详见 .NET Framework 4.x 程序到底运行在哪个 CLR 版本之上 - walterlv。

那么如何获取已安装的 .NET Framework 的版本呢？最靠谱的方法竟然是通过读取注册表。

注册表位置和含义

读取位置在这里：

计算机\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full\2052

而唯一准确能够判定 .NET Framework 版本的，只有里面的 Release 值。但可惜的是，这个值并不能直接看出来到底是 4.5 还是 4.8。我们需要有一张对应表。

我把它整理成了字典和注释，这样会比较容易理解每个编号对应的 .NET Framework 版本代号。

/// <summary>
/// 获取 .NET Framework 4.5 及以上版本的发行号与版本名称的对应关系。
/// 4.5 及以下版本没有这样的对应关系。
/// </summary>
private static readonly Dictionary<int, string> ReleaseToNameDictionary = new Dictionary<int, string>
{
    // .NET Framework 4.5
    { 378389, "4.5" },
    // .NET Framework 4.5.1（Windows 8.1 或 Windows Server 2012 R2 自带）
    { 378675, "4.5.1" },
    // .NET Framework 4.5.1（其他系统安装）
    { 378758, "4.5.1" },
    // .NET Framework 4.5.2
    { 379893, "4.5.2" },
    // .NET Framework 4.6（Windows 10 第一个版本 1507 自带）
    { 393295, "4.6" },
    // .NET Framework 4.6（其他系统安装）
    { 393297, "4.6" },
    // .NET Framework 4.6.1（Windows 10 十一月更新 1511 自带）
    { 394254, "4.6.1" },
    // .NET Framework 4.6.1（其他系统安装）
    { 394271, "4.6.1" },
    // .NET Framework 4.6.2（Windows 10 一周年更新 1607 和 Windows Server 2016 自带）
    { 394802, "4.6.2" },
    // .NET Framework 4.6.2（其他系统安装）
    { 394806, "4.6.2" },
    // .NET Framework 4.7（Windows 10 创造者更新 1703 自带）
    { 460798, "4.7" },
    // .NET Framework 4.7（其他系统安装）
    { 460805, "4.7" },
    // .NET Framework 4.7.1（Windows 10 秋季创造者更新 1709 和 Windows Server 1709 自带）
    { 461308, "4.7.1" },
    // .NET Framework 4.7.1（其他系统安装）
    { 461310, "4.7.1" },
    // .NET Framework 4.7.2（Windows 10 2018年四月更新 1803 和 Windows Server 1803 自带）
    { 461808, "4.7.2" },
    // .NET Framework 4.7.2（其他系统安装）
    { 461814, "4.7.2" },
    // .NET Framework 4.8（Windows 10 2019年五月更新 1903 自带）
    { 528040, "4.8" },
    // .NET Framework 4.8（其他系统安装）
    { 528049, "4.8" },
};

另外，还有一些值也是有意义的（只是不那么精确）：

主版本
- 也就是可以共存的版本，比如 v3.5 系列和 v4 系列就是可以共存的，它们分别是就地更新的保持兼容的版本
发行版本名称
- 完整版 Full 和精简版 Client
版本号
- 比如 3.5.30729.4926 或者 4.7.02556
服务包版本
- 古时候的微软喜欢用 SP1 SP2 来命名同一个版本的多次更新，这也就是那个年代的产物

它们分别在注册表的这些位置：

主版本
- 计算机\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NET Framework Setup\NDP 里项的名称
发行版本名称
- 以上项里子项的名称
版本号
- 以上项里的 Version 值
服务包版本
- 以上项里的 SP 值

读取注册表

在上面已经梳理了读取注册表的位置之后，相信你可以很容易写出读取已安装 .NET Framework 版本的代码出来。

我已经将其做成了 NuGet 源代码包（使用 SourceYard 打包），你可以安装 NuGet 包来获得读取已安装 .NET Framework 版本的功能：

NuGet Gallery - Walterlv.Environment.Source

或者在 GitHub 查看源代码：

Walterlv.Packages/NdpInfo.cs at master · walterlv/Walterlv.Packages

只有一个类型——NdpInfo。

使用方法有两种。

第一种，获取当前计算机上所有已经安装的 .NET Framework 版本：

var allVersions = await NdpInfo.ReadFromRegistryAsync();

执行完成之后看看得到的字典 allVersions 如下：

字典里 Key 是不能共存的主版本，Value 是这个主版本里当前已经安装的具体版本信息。

如果直接使用 ToString()，是可以生成我们平时经常在各大文档或者社区使用的 .NET Framework 的名称。

第二种，获取当前已安装的最新的 .NET Framework 版本名称：

var currentVersion = NdpInfo.GetCurrentVersionName();

这可以直接获取到一个字符串，比如 .NET Framework 4.8。对于只是简单获取一下已安装名称而不用做更多处理的程序来说会比较方便。

Windows 系统上用 .NET/C# 查找所有窗口，并获得窗口的标题、位置、尺寸、最小化、可见性等各种状态

Thu, 10 Oct 2019 04:11:37 +0000

在 Windows 应用开发中，如果需要操作其他的窗口，那么可以使用 EnumWindows 这个 API 来枚举这些窗口。

你可以使用本文编写的一个类型，查找到所有窗口中你关心的信息。

需要使用的 API

枚举所有窗口仅需要使用到 EnumWindows，其中需要定义一个委托 WndEnumProc 作为传入参数的类型。

剩下的我们需要其他各种方法用于获取窗口的其他属性。

GetParent 获取窗口的父窗口，这可以确认找到的窗口是否是顶层窗口。（关于顶层窗口，可以延伸使用 SetParent 跨进程设置父子窗口时的一些问题（小心卡死） - walterlv。）
IsWindowVisible 判断窗口是否可见
GetWindowText 获取窗口标题
GetClassName 获取窗口类名
GetWindowRect 获取窗口位置和尺寸，为此我们还需要定义一个结构体 LPRECT

private delegate bool WndEnumProc(IntPtr hWnd, int lParam);

[DllImport("user32")]
private static extern bool EnumWindows(WndEnumProc lpEnumFunc, int lParam);

[DllImport("user32")]
private static extern IntPtr GetParent(IntPtr hWnd);

[DllImport("user32")]
private static extern bool IsWindowVisible(IntPtr hWnd);

[DllImport("user32")]
private static extern int GetWindowText(IntPtr hWnd, StringBuilder lptrString, int nMaxCount);

[DllImport("user32")]
private static extern int GetClassName(IntPtr hWnd, StringBuilder lpString, int nMaxCount);

[DllImport("user32")]
private static extern bool GetWindowRect(IntPtr hWnd, ref LPRECT rect);

[StructLayout(LayoutKind.Sequential)]
private readonly struct LPRECT
{
    public readonly int Left;
    public readonly int Top;
    public readonly int Right;
    public readonly int Bottom;
}

枚举所有窗口

我将以上 API 封装成 FindAll 函数，并提供过滤器可以给大家过滤众多的窗口使用。

比如，我写了下面一个简单的示例，可以输出当前可见的所有窗口以及其位置和尺寸：

using System;

namespace Walterlv.WindowDetector
{
    class Program
    {
        static void Main(string[] args)
        {
            var windows = WindowEnumerator.FindAll();
            for (int i = 0; i < windows.Count; i++)
            {
                var window = windows[i];
                Console.WriteLine($@"{i.ToString().PadLeft(3, ' ')}. {window.Title}
     {window.Bounds.X}, {window.Bounds.Y}, {window.Bounds.Width}, {window.Bounds.Height}");
            }
            Console.ReadLine();
        }
    }
}

这里的 FindAll 方法，我提供了一个默认参数，可以指定如何过滤所有枚举到的窗口。如果不指定，则会找可见的，包含标题的，没有最小化的窗口。如果你希望找一些看不见的窗口，可以自己写过滤条件。

什么都不要过滤的话，就传入 _ => true，意味着所有的窗口都会被枚举出来。

附源码

因为源代码会经常更新，所以建议在这里查看：

walterlv.demo/Walterlv.WindowDetector/Walterlv.WindowDetector at master · walterlv/walterlv.demo

无法访问的话，可以看下面：

using System;
using System.Collections.Generic;
using System.Drawing;
using System.Runtime.InteropServices;
using System.Text;

namespace Walterlv.WindowDetector
{
    /// <summary>
    /// 包含枚举当前用户空间下所有窗口的方法。
    /// </summary>
    public class WindowEnumerator
    {
        /// <summary>
        /// 查找当前用户空间下所有符合条件的窗口。如果不指定条件，将仅查找可见窗口。
        /// </summary>
        /// <param name="match">过滤窗口的条件。如果设置为 null，将仅查找可见窗口。</param>
        /// <returns>找到的所有窗口信息。</returns>
        public static IReadOnlyList<WindowInfo> FindAll(Predicate<WindowInfo> match = null)
        {
            var windowList = new List<WindowInfo>();
            EnumWindows(OnWindowEnum, 0);
            return windowList.FindAll(match ?? DefaultPredicate);

            bool OnWindowEnum(IntPtr hWnd, int lparam)
            {
                // 仅查找顶层窗口。
                if (GetParent(hWnd) == IntPtr.Zero)
                {
                    // 获取窗口类名。
                    var lpString = new StringBuilder(512);
                    GetClassName(hWnd, lpString, lpString.Capacity);
                    var className = lpString.ToString();

                    // 获取窗口标题。
                    var lptrString = new StringBuilder(512);
                    GetWindowText(hWnd, lptrString, lptrString.Capacity);
                    var title = lptrString.ToString().Trim();

                    // 获取窗口可见性。
                    var isVisible = IsWindowVisible(hWnd);

                    // 获取窗口位置和尺寸。
                    LPRECT rect = default;
                    GetWindowRect(hWnd, ref rect);
                    var bounds = new Rectangle(rect.Left, rect.Top, rect.Right - rect.Left, rect.Bottom - rect.Top);

                    // 添加到已找到的窗口列表。
                    windowList.Add(new WindowInfo(hWnd, className, title, isVisible, bounds));
                }

                return true;
            }
        }

        /// <summary>
        /// 默认的查找窗口的过滤条件。可见 + 非最小化 + 包含窗口标题。
        /// </summary>
        private static readonly Predicate<WindowInfo> DefaultPredicate = x => x.IsVisible && !x.IsMinimized && x.Title.Length > 0;

        private delegate bool WndEnumProc(IntPtr hWnd, int lParam);

        [DllImport("user32")]
        private static extern bool EnumWindows(WndEnumProc lpEnumFunc, int lParam);

        [DllImport("user32")]
        private static extern IntPtr GetParent(IntPtr hWnd);

        [DllImport("user32")]
        private static extern bool IsWindowVisible(IntPtr hWnd);

        [DllImport("user32")]
        private static extern int GetWindowText(IntPtr hWnd, StringBuilder lptrString, int nMaxCount);

        [DllImport("user32")]
        private static extern int GetClassName(IntPtr hWnd, StringBuilder lpString, int nMaxCount);

        [DllImport("user32")]
        private static extern void SwitchToThisWindow(IntPtr hWnd, bool fAltTab);

        [DllImport("user32")]
        private static extern bool GetWindowRect(IntPtr hWnd, ref LPRECT rect);

        [StructLayout(LayoutKind.Sequential)]
        private readonly struct LPRECT
        {
            public readonly int Left;
            public readonly int Top;
            public readonly int Right;
            public readonly int Bottom;
        }
    }

    /// <summary>
    /// 获取 Win32 窗口的一些基本信息。
    /// </summary>
    public readonly struct WindowInfo
    {
        public WindowInfo(IntPtr hWnd, string className, string title, bool isVisible, Rectangle bounds) : this()
        {
            Hwnd = hWnd;
            ClassName = className;
            Title = title;
            IsVisible = isVisible;
            Bounds = bounds;
        }

        /// <summary>
        /// 获取窗口句柄。
        /// </summary>
        public IntPtr Hwnd { get; }

        /// <summary>
        /// 获取窗口类名。
        /// </summary>
        public string ClassName { get; }

        /// <summary>
        /// 获取窗口标题。
        /// </summary>
        public string Title { get; }

        /// <summary>
        /// 获取当前窗口是否可见。
        /// </summary>
        public bool IsVisible { get; }

        /// <summary>
        /// 获取窗口当前的位置和尺寸。
        /// </summary>
        public Rectangle Bounds { get; }

        /// <summary>
        /// 获取窗口当前是否是最小化的。
        /// </summary>
        public bool IsMinimized => Bounds.Left == -32000 && Bounds.Top == -32000;
    }
}

在 WPF 程序中应用 Windows 10 真•亚克力效果

Thu, 10 Oct 2019 02:25:11 +0000

从 Windows 10 (1803) 开始，Win32 应用也可以有 API 来实现原生的亚克力效果了。不过相比于 UWP 来说，可定制性会差很多。

本文介绍如何在 WPF 程序中应用 Windows 10 真•亚克力效果。（而不是一些流行的项目里面自己绘制的亚克力效果。）

API

需要使用的 API 是微软的文档中并未公开的 SetWindowCompositionAttribute。

我在另一篇博客中有介绍此 API 各种用法的效果，详见：

使用 SetWindowCompositionAttribute 来控制程序的窗口边框和背景（可以做 Acrylic 亚克力效果、模糊效果、主题色效果等） - walterlv

当然，使用此 API 也可以做 Windows 10 早期的模糊效果，比如：

在 Windows 10 上为 WPF 窗口添加模糊特效（就像开始菜单和操作中心那样） - walterlv

如何使用

为了方便地让你的窗口获得亚克力效果，我做了两层不同的 API：

AcrylicBrush 当然，受到 Win32 启用亚克力效果的限制，只能在窗口上设置此属性
WindowAccentCompositor 用于更多地控制窗口与系统的叠加组合效果

代码请参见：

Walterlv.Packages/WindowAccentCompositor.cs at master · walterlv/Walterlv.Packages

注意事项

要使得亚克力效果可以生效，需要：

设置一个混合色 GradientColor
混合色不能是全透明（如果全透明，窗口的亚克力部分就全透明穿透了），当然也不能全不透明，这样就看不到亚克力效果了。

参考资料

winapi - How do you set the glass blend colour on Windows 10? - Stack Overflow

使用 SetWindowCompositionAttribute 来控制程序的窗口边框和背景（可以做 Acrylic 亚克力效果、模糊效果、主题色效果等）

Thu, 10 Oct 2019 00:09:12 +0000

Windows 系统中有一个没什么文档的 API，SetWindowCompositionAttribute，可以允许应用的开发者将自己窗口中的内容渲染与窗口进行组合。这可以实现很多系统中预设的窗口特效，比如 Windows 7 的毛玻璃特效，Windows 8/10 的前景色特效，Windows 10 的模糊特效，以及 Windows 10 1709 的亚克力（Acrylic）特效。而且这些组合都发生在 dwm 进程中，不会额外占用应用程序的渲染性能。

本文介绍 SetWindowCompositionAttribute 可以实现的所有效果。你可以通过阅读本文了解到与系统窗口可以组合渲染到哪些程度。

试验用的源代码

本文将创建一个简单的 WPF 程序来验证 SetWindowCompositionAttribute 能达到的各种效果。你也可以不使用 WPF，得到类似的效果。

简单的项目文件结构是这样的：

[项目] Walterlv.WindowComposition
- App.xaml
- App.xaml.cs
- MainWindow.xaml
- MainWindow.xaml.cs
- WindowAccentCompositor

其中，App.xaml 和 App.xaml.cs 保持默认生成的不动。

为了验证此 API 的效果，我需要将 WPF 主窗口的背景色设置为纯透明或者 null，而设置 ControlTemplate 才能彻彻底底确保所有的样式一定是受我们自己控制的，我们在 ControlTemplate 中没有指定任何可以显示的内容。MainWindow.xaml 的全部代码如下：

<Window x:Class="Walterlv.WindowComposition.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="欢迎访问吕毅的博客：blog.walterlv.com" Height="450" Width="800">
    <Window.Template>
        <ControlTemplate TargetType="Window">
            <AdornerDecorator>
                <ContentPresenter />
            </AdornerDecorator>
        </ControlTemplate>
    </Window.Template>
    <!-- 我们注释掉 WindowChrome，是因为即将验证 WindowChrome 带来的影响。 -->
    <!--<WindowChrome.WindowChrome>
        <WindowChrome GlassFrameThickness="-1" />
    </WindowChrome.WindowChrome>-->
    <Grid>
    </Grid>
</Window>

而 MainWindow.xaml.cs 中，我们简单调用一下我们即将写的调用 SetWindowCompositionAttribute 的类型。

using System.Windows;
using System.Windows.Media;
using Walterlv.Windows.Effects;

namespace Walterlv.WindowComposition
{
    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();
            var compositor = new WindowAccentCompositor(this);
            compositor.Composite(Color.FromRgb(0x18, 0xa0, 0x5e));
        }
    }
}

还剩下一个 WindowAccentCompositor.cs 文件，因为比较长放到博客里影响阅读，所以建议前往这里查看：

Walterlv.Packages/WindowAccentCompositor.cs at master · walterlv/Walterlv.Packages

而其中对我们最终渲染效果有影响的就是 AccentPolicy 类型的几个属性。其中 AccentState 属性是下面这个枚举，而 GradientColor 将决定窗口渲染时叠加的颜色。

private enum AccentState
{
    ACCENT_DISABLED = 0,
    ACCENT_ENABLE_GRADIENT = 1,
    ACCENT_ENABLE_TRANSPARENTGRADIENT = 2,
    ACCENT_ENABLE_BLURBEHIND = 3,
    ACCENT_ENABLE_ACRYLICBLURBEHIND = 4,
    ACCENT_INVALID_STATE = 5,
}

影响因素

经过试验，对最终显示效果有影响的有这些：

选择的 AccentState 枚举值
使用的 GradientColor 叠加色
是否使用 WindowChrome 让客户区覆盖非客户区
目标操作系统（Windows 7/8/8.1/10）

使用 WindowChrome，你可以用你自己的 UI 覆盖掉系统的 UI 窗口样式。关于 WindowChrome 让客户区覆盖非客户区的知识，可以阅读：

[WPF 自定义控件] Window（窗体）的 UI 元素及行为 - dino.c - 博客园

需要注意的是，WindowChrome 的 GlassFrameThickness 属性可以设置窗口边框的粗细，设置为 0 将导致窗口没有阴影，设置为负数将使得整个窗口都是边框。

排列组合

我们依次来看看效果。

AccentState=ACCENT_DISABLED

使用 ACCENT_DISABLED 时，GradientColor 叠加色没有任何影响，唯一影响渲染的是 WindowChrome 和操作系统。

不使用 WindowChrome，在 Windows 10 上：

不使用 WindowChrome 在 Windows 7 上：

在 Windows 10 上，使用 WindowChrome：

<WindowChrome.WindowChrome>
    <WindowChrome />
</WindowChrome.WindowChrome>

在 Windows 7 上，使用 WindowChrome：

当然，以上边框比较细，跟系统不搭，可以设置成其他值：

在 Windows 10 上，使用 WindowChrome 并且 GlassFrameThickness 设置为 -1：

<WindowChrome.WindowChrome>
    <WindowChrome GlassFrameThickness="-1" />
</WindowChrome.WindowChrome>

而在 Windows 7 上，这就是非常绚丽的全窗口的 Aero 毛玻璃特效：

AccentState=ACCENT_ENABLE_GRADIENT

使用 ACCENT_DISABLED 时，GradientColor 叠加色会影响到最终的渲染效果。

还记得我们前面叠加的颜色是什么吗？

接下来别忘了然后把它误以为是我系统的主题色哦！

不使用 WindowChrome，在 Windows 10 上：

另外，你会注意到左、下、右三个方向上边框会深一些。那是 Windows 10 的窗口阴影效果，因为实际上 Windows 10 叠加的阴影也是窗口区域的一部分，只是一般人看不出来而已。我们叠加了颜色之后，这里就露馅儿了。

另外，这个颜色并不是我们自己的进程绘制的哦，是 dwm 绘制的颜色。

如果不指定 GradientColor 也就是保持为 0，你将看到上面绿色的部分全是黑色的；嗯，包括阴影的部分……

不使用 WindowChrome 在 Windows 7 上：

可以看出，在 Windows 7 上，GradientColor 被无视了。

而使用 WindowChrome 在 Windows 10 上，则可以得到整个窗口的叠加色：

<WindowChrome.WindowChrome>
    <WindowChrome GlassFrameThickness="16 48 16 16" />
</WindowChrome.WindowChrome>

可以注意到，窗口获得焦点的时候，整个窗口都是叠加色；而窗口失去焦点的时候，指定了边框的部分颜色会更深（换其他颜色叠加可以看出来是叠加了半透明黑色）。

如果你希望失去焦点的时候，边框部分不要变深，请将边框设置为 -1：

<WindowChrome.WindowChrome>
    <WindowChrome GlassFrameThickness="-1" />
</WindowChrome.WindowChrome>

使用 WindowChrome 在 Windows 7 上，依然没有任何叠加色的效果：

AccentState=ACCENT_ENABLE_TRANSPARENTGRADIENT

使用 ACCENT_ENABLE_TRANSPARENTGRADIENT 时，GradientColor 叠加色没有任何影响，唯一影响渲染的是 WindowChrome 和操作系统。

不使用 WindowChrome，在 Windows 10 上：

依然左、下、右三个方向上边框会深一些，那是 Windows 10 的窗口阴影效果。

不使用 WindowChrome 在 Windows 7 上：

GradientColor 也是被无视的，而且效果跟之前一样。

使用 WindowChrome 在 Windows 10 上，在获得焦点的时候整个背景是系统主题色；而失去焦点的时候是灰色，但边框部分是深色。

依然可以将边框设置为 -1 使得边框不会变深：

使用 WindowChrome 在 Windows 7 上，依然是老样子：

AccentState=ACCENT_ENABLE_BLURBEHIND

ACCENT_ENABLE_BLURBEHIND 可以在 Windows 10 上做出模糊效果，就跟 Windows 10 早期版本的模糊效果是一样的。你可以看我之前的一篇博客，那时亚克力效果还没出来：

在 Windows 10 上为 WPF 窗口添加模糊特效（就像开始菜单和操作中心那样） - walterlv

使用 ACCENT_ENABLE_BLURBEHIND 时，GradientColor 叠加色没有任何影响，唯一影响渲染的是 WindowChrome 和操作系统。

在 Windows 10 上，没有使用 WindowChrome：

你可能需要留意一下那个“诡异”的模糊范围，你会发现窗口的阴影外侧也是有模糊的！！！你能忍吗？肯定不能忍，所以还是乖乖使用 WindowChrome 吧！

在 Windows 7 上，没有使用 WindowChrome，效果跟其他值一样，依然没有变化：

在 Windows 10 上，使用 WindowChrome：

使用 WindowChrome 在 Windows 7 上，依然是老样子：

AccentState=ACCENT_ENABLE_ACRYLICBLURBEHIND

从 Windows 10 (1803) 开始，Win32 程序也能添加亚克力效果了，因为 SetWindowCompositionAttribute 的参数枚举新增了 ACCENT_ENABLE_ACRYLICBLURBEHIND。

亚克力效果相信大家不陌生，那么在 Win32 应用程序里面使用的效果是什么呢？

不使用 WindowChrome，在 Windows 10 上：

咦！等等！这不是跟之前一样吗？

嗯，下面就是不同了，亚克力效果支持与半透明的 GradientColor 叠加，所以我们需要将传入的颜色修改为半透明：

    var compositor = new WindowAccentCompositor(this);
--  compositor.Composite(Color.FromRgb(0x18, 0xa0, 0x5e));
++  compositor.Composite(Color.FromArgb(0x3f, 0x18, 0xa0, 0x5e));

那么如果改为全透明会怎么样呢？

不幸的是，完全没有效果！！！

    var compositor = new WindowAccentCompositor(this);
--  compositor.Composite(Color.FromRgb(0x18, 0xa0, 0x5e));
++  compositor.Composite(Color.FromArgb(0x00, 0x18, 0xa0, 0x5e));

接下来是使用 WindowChrome 时：

<WindowChrome.WindowChrome>
    <WindowChrome GlassFrameThickness="16 48 16 16" />
</WindowChrome.WindowChrome>

然而周围有一圈偏白色的渐变是什么呢？那个其实是 WindowChrome 设置的边框白，被亚克力效果模糊后得到的混合效果。

所以，如果要获得全窗口的亚克力效果，请将边框设置成比较小的值：

<WindowChrome.WindowChrome>
    <WindowChrome GlassFrameThickness="0 1 0 0" />
</WindowChrome.WindowChrome>

记得不要像前面的那些效果一样，如果设置成 -1，你将获得纯白色与设置的 Gradient 叠加色的亚克力特效，是个纯色：

你可以将叠加色的透明度设置得小一些，这样可以看出叠加的颜色：

    var compositor = new WindowAccentCompositor(this);
--  compositor.Composite(Color.FromRgb(0x18, 0xa0, 0x5e));
++  compositor.Composite(Color.FromArgb(0xa0, 0x18, 0xa0, 0x5e));

那么可以设置为全透明吗？

    var compositor = new WindowAccentCompositor(this);
--  compositor.Composite(Color.FromRgb(0x18, 0xa0, 0x5e));
++  compositor.Composite(Color.FromArgb(0x00, 0x18, 0xa0, 0x5e));

很不幸，最终你会完全看不到亚克力效果，而变成了毫无特效的透明窗口：

最上面那根白线，是我面前面设置边框为 0 1 0 0 导致的。

如果在这种情况下，将边框设置为 0 会怎样呢？记得前面我们说过的吗，会导致阴影消失哦！

呃……你将看到……这个……

什么都没有……

是不是找到了一条新的背景透明异形窗口的方法？

还是省点心吧，亚克力效果在 Win32 应用上的性能还是比较堪忧的……

想要背景透明，请参见：

WPF 制作高性能的透明背景异形窗口（使用 WindowChrome 而不要使用 AllowsTransparency=True） - walterlv

不用考虑 Windows 7，因为大家都知道不支持。实际效果会跟前面的一模一样。

AccentState=ACCENT_INVALID_STATE

这个值其实不用说了，因为 AccentState 在不同系统中可用的值不同，为了保证向后兼容性，对于新系统中设置的值，旧系统其实就视之为 ACCENT_INVALID_STATE。

那么如果系统认为设置的是 ACCENT_INVALID_STATE 会显示成什么样子呢？

答案是，与 ACCENT_DISABLED 完全相同。

总结

由于 Windows 7 上所有的值都是同样的效果，所以下表仅适用于 Windows 10。

	效果
ACCENT_DISABLED	黑色（边框为纯白色）
ACCENT_ENABLE_GRADIENT	GradientColor 颜色（失焦后边框为深色）
ACCENT_ENABLE_TRANSPARENTGRADIENT	主题色（失焦后边框为深色）
ACCENT_ENABLE_BLURBEHIND	模糊特效（失焦后边框为灰色）
ACCENT_ENABLE_ACRYLICBLURBEHIND	与 GradientColor 叠加颜色的亚克力特效
ACCENT_INVALID_STATE	黑色（边框为纯白色）

在以上的特效之下，WindowChrome 可以让客户区覆盖非客户区，或者让整个窗口都获得特效，而不只是标题栏。

附源代码

请参见 GitHub 地址以获得最新代码。如果不方便访问，那么就看下面的吧。

Walterlv.Packages/WindowAccentCompositor.cs at master · walterlv/Walterlv.Packages

using System;
using System.Runtime.InteropServices;
using System.Windows;
using System.Windows.Interop;
using System.Windows.Media;

namespace Walterlv.Windows.Effects
{
    /// <summary>
    /// 为窗口提供模糊特效。
    /// </summary>
    public class WindowAccentCompositor
    {
        private readonly Window _window;

        /// <summary>
        /// 创建 <see cref="WindowAccentCompositor"/> 的一个新实例。
        /// </summary>
        /// <param name="window">要创建模糊特效的窗口实例。</param>
        public WindowAccentCompositor(Window window) => _window = window ?? throw new ArgumentNullException(nameof(window));

        public void Composite(Color color)
        {
            Window window = _window;
            var handle = new WindowInteropHelper(window).EnsureHandle();

            var gradientColor =
                // 组装红色分量。
                color.R << 0 |
                // 组装绿色分量。
                color.G << 8 |
                // 组装蓝色分量。
                color.B << 16 |
                // 组装透明分量。
                color.A << 24;

            Composite(handle, gradientColor);
        }

        private void Composite(IntPtr handle, int color)
        {
            // 创建 AccentPolicy 对象。
            var accent = new AccentPolicy
            {
                AccentState = AccentState.ACCENT_ENABLE_ACRYLICBLURBEHIND,
                GradientColor = 0,
            };

            // 将托管结构转换为非托管对象。
            var accentPolicySize = Marshal.SizeOf(accent);
            var accentPtr = Marshal.AllocHGlobal(accentPolicySize);
            Marshal.StructureToPtr(accent, accentPtr, false);

            // 设置窗口组合特性。
            try
            {
                // 设置模糊特效。
                var data = new WindowCompositionAttributeData
                {
                    Attribute = WindowCompositionAttribute.WCA_ACCENT_POLICY,
                    SizeOfData = accentPolicySize,
                    Data = accentPtr,
                };
                SetWindowCompositionAttribute(handle, ref data);
            }
            finally
            {
                // 释放非托管对象。
                Marshal.FreeHGlobal(accentPtr);
            }
        }

        [DllImport("user32.dll")]
        private static extern int SetWindowCompositionAttribute(IntPtr hwnd, ref WindowCompositionAttributeData data);

        private enum AccentState
        {
            ACCENT_DISABLED = 0,
            ACCENT_ENABLE_GRADIENT = 1,
            ACCENT_ENABLE_TRANSPARENTGRADIENT = 2,
            ACCENT_ENABLE_BLURBEHIND = 3,
            ACCENT_ENABLE_ACRYLICBLURBEHIND = 4,
            ACCENT_INVALID_STATE = 5,
        }

        [StructLayout(LayoutKind.Sequential)]
        private struct AccentPolicy
        {
            public AccentState AccentState;
            public int AccentFlags;
            public int GradientColor;
            public int AnimationId;
        }

        [StructLayout(LayoutKind.Sequential)]
        private struct WindowCompositionAttributeData
        {
            public WindowCompositionAttribute Attribute;
            public IntPtr Data;
            public int SizeOfData;
        }

        private enum WindowCompositionAttribute
        {
            // 省略其他未使用的字段
            WCA_ACCENT_POLICY = 19,
            // 省略其他未使用的字段
        }
    }
}

使用傲梅分区助手无损合并分区，无损调整分区大小

Mon, 07 Oct 2019 12:14:24 +0000

Windows 本身就提供了强大的磁盘和分区管理工具，一个是操作简单的“磁盘管理”，一个是功能强大的命令行版的“diskpart”。不过这两个都有一些限制，一是不能影响到系统文件，二是其修改的分区不能被应用程序占用（diskpart 可在下次重启时做到）。另外，系统为了管理工具操作的效率和正确性，也有一些功能没有开放。

DiskGenius 是个强大的工具，不过傲梅也很良心。本文介绍使用傲梅分区助手来管理磁盘。

下载

傲梅分区助手有绿色版、专业版和 PE 版。一般我们选择绿色版就好，如果你要改到系统分区，就需要使用集成了傲梅分区助手的 PE 系统。

下载傲梅分区助手

下面是专业版的截图：

下面是 PE 版的截图，也是我实际操作分区时截下来的图：

不要吐槽为何我用的是古老的 1709 系统，实际上我的系统盘是下面那个 I 盘。不然为什么我会把系统的版本号放到卷标中呢？

调整分区大小

在 PE 系统中找到傲梅分区助手，然后启动。在需要调整位置和大小的分区上右键点击选择“调整/移动分区”：

然后在弹出的详细设置对话框中调整分区的位置和大小。如果是 SSD，建议点击“高级”然后勾选“允许分区对齐以优化SSD或HDD硬盘”，这可以开启 4K 对齐以大幅优化 SSD 的读写性能。

最后点击确定。

注意这个时候还没有开始执行真正的操作！

合并分区

合并分区功能可以将你一个磁盘中的多个分区无损合并成一个。

选择好将哪个分区合并到哪一个，这时另一个分区中的所有文件会放到目标分区中的一个文件夹里。合并完之后你自己移动好这些文件即可。

因为我的分区在合并过程中的操作没有截图，所以只能看到下面这个提前在磁盘管理中的截图：

开始执行真正的操作

在你设置好你的所有操作之后，点击左上角的“提交”按钮，这可以开始依次执行之前所有设置的磁盘最终状态。

在提交界面，你可以看到即将进行的所有操作的简介，以及预计完成这些操作所花的时间。

虽然上图只是示例，但我实际将我在下面这篇博客中删除出来的空余空间全部合并在一起，并且还额外合并了两个都需要保留数据的分区。这个过程傲梅的预计时间是 9小时18分，实际上也刚好在 9 个小时左右！

EFI 分区/恢复分区不可删除？你需要使用命令行了（全命令行操作）

所以，如果你打算开始进行大量的磁盘调整、对拷或者其他无损分区操作：

请提前准备好大量你不用电脑的时间。
请提前准备好大量你不用电脑的时间。
请提前准备好大量你不用电脑的时间。

这是我实际上在 PE 中操作的截图：

EFI 分区/恢复分区不可删除？你需要使用命令行了（配合鼠标操作）

Mon, 07 Oct 2019 03:05:02 +0000

Windows 系统在安装的时候，会自动为我们的磁盘划分一个恢复分区和一个 EFI 分区。如果后面不打算再用这些分区的时候，却发现无法删除。

本文将提供解决方法。

因为误操作会导致数据丢失，所以我将两种不同的解决方法分开成两篇文章以避免干扰：

无法删除

看下图，有两种不同类型的无法删除：

有完整菜单只是删除按钮不可用的 EFI 分区；
仅有一个“帮助”菜单的恢复分区。

删除方法会略有不同，我会在合适的地方提示你使用正确的方法的。

我的磁盘 2 原本包含两个可见分区，一个是图中黑色色块，原来放的是旧操作系统，一个是图中的 D 盘，放大量文件。因为我新买了一个大容量 SSD 专门用来放操作系统，所以原来操作系统所在的磁盘就可以回收与 D 盘合并。

然而悲剧的是，中间隔着一个 820MB 的恢复分区，导致我没有办法为 D 分区扩容。

更麻烦的是，在磁盘管理中，这三个我不会再使用的恢复分区都不可删除。

PS. 吐槽一下，大版本升级一次 Windows 10 竟然会在后面给我多创建一个恢复分区……

解决办法

在实操之前，你必须清除地知道你每一步在做什么，否则你需要承担丢失数据的后果：

如果你在网上找到一些操作 disk 的命令，请不要相信——因为此命令清除的是整个磁盘而不只是单个分区

第一步：打开命令提示符

打开开始菜单，输入 cmd 然后回车确定，我们可以打开命令提示符

第二步：打开 diskpart

在 cmd 中输入 diskpart 然后回车，你会看到一个 UAC 提示弹窗，点击“是”之后会启动一个新的管理员权限启动的命令提示符，这里运行着 Diskpart 程序。

第三步：找到要操作的磁盘

输入 list disk 回车，我们可以看到自己计算机中所有已经插入的磁盘。

DISKPART> list disk

  磁盘 ###  状态           大小     可用     Dyn  Gpt
  --------  -------------  -------  -------  ---  ---
  磁盘 0    联机              238 GB      0 B
  磁盘 1    联机              931 GB  2048 KB
  磁盘 2    联机              489 GB   199 GB        *
  磁盘 3    联机              476 GB  1024 KB        *

请注意，这里看到的是磁盘，而不是平时在“计算机”中看到的分区——每一个磁盘都可以包含一个到多个分区哦！

你有两种方法来确认我们即将操作的是哪个磁盘：

前面我们在磁盘管理中看到的那个界面，也就是本文一开始的那张图，可以直接看出我们要删除的分区在“磁盘 2”上。
根据分区的大小去猜，相信分区少的时候你可以猜对。

好的，我们知道要操作的是“磁盘 2”，于是我们输入命令 select disk 2（如果你是其他磁盘请换成自己的数字）：

DISKPART> select disk 2

磁盘 2 现在是所选磁盘。

紧接着，我们输入 list partition 列出此磁盘上的所有分区：

DISKPART> list partition

  分区 ###       类型              大小     偏移量
  -------------  ----------------  -------  -------
  分区      1    恢复                 499 MB  1024 KB
  分区      2    系统                 100 MB   500 MB
  分区      3    保留                  16 MB   600 MB
  分区      5    恢复                 820 MB   199 GB
  分区      6    主要                 288 GB   200 GB

通过分区，我们也能再次确认我们找到了正确的要操作的磁盘。

截至目前，我们还没有对系统进行任何更改，所以你操作错了也不用担心。但接下来你就需要谨慎一些。

第 4.1 步：删除分区（仅适用于 EFI 分区）

因为我不再将此磁盘用作系统盘，所以里面除了那个 288GB 的数据部分不能动之外，其他系统生成的部分都是需要删除的，所以接下来我需要对分区 1 2 5 都进行一遍以下操作（你的目的不同可能需要删除的分区也不一样）。

先选中要操作的分区：

DISKPART> select partition 1

分区 1 现在是所选分区。

然后更改其 ID：

DISKPART> SET ID=ebd0a0a2-b9e5-4433-87c0-68b6b72699c7

DiskPart 成功设置了分区 ID。

然后操作其他的分区。

完整的截图如下：

这个时候，回到磁盘管理中，F5 刷新，你可以看到原本不可删除的 EFI 分区，现在可以直接使用鼠标删除了。点击一下“删除卷”即可。

第 4.2 步：删除分区（适用于所有类型的分区）

恢复分区不能使用上面 4.1 中的方法删除，如果你在 4.1 的操作之后还发现存在不可删除的恢复分区，请尝试使用我的另一篇博客：

EFI 分区/恢复分区不可删除？你需要使用命令行了（全命令行操作）

参考资料

EFI 分区/恢复分区不可删除？你需要使用命令行了（全命令行操作）

Mon, 07 Oct 2019 03:04:58 +0000

Windows 系统在安装的时候，会自动为我们的磁盘划分一个恢复分区和一个 EFI 分区。如果后面不打算再用这些分区的时候，却发现无法删除。

本文将提供解决方法。

因为误操作会导致数据丢失，所以我将两种不同的解决方法分开成两篇文章以避免干扰：

无法删除

看下图，有两种不同类型的无法删除：

有完整菜单只是删除按钮不可用的 EFI 分区；
仅有一个“帮助”菜单的恢复分区。

使用本文提供的方法，你可以删除以上两种不同类型的分区。

然而悲剧的是，中间隔着一个 820MB 的恢复分区，导致我没有办法为 D 分区扩容。

更麻烦的是，在磁盘管理中，这三个我不会再使用的恢复分区都不可删除。

PS. 吐槽一下，大版本升级一次 Windows 10 竟然会在后面给我多创建一个恢复分区……

解决办法

在实操之前，你必须清除地知道你每一步在做什么，否则你需要承担丢失数据的后果：

如果你在网上找到一些操作 disk 的命令，请不要相信——因为此命令清除的是整个磁盘而不只是单个分区

第一步：打开命令提示符

打开开始菜单，输入 cmd 然后回车确定，我们可以打开命令提示符

第二步：打开 diskpart

第三步：找到要操作的磁盘

输入 list disk 回车，我们可以看到自己计算机中所有已经插入的磁盘。

DISKPART> list disk

  磁盘 ###  状态           大小     可用     Dyn  Gpt
  --------  -------------  -------  -------  ---  ---
  磁盘 0    联机              238 GB      0 B
  磁盘 1    联机              931 GB  2048 KB
  磁盘 2    联机              489 GB   199 GB        *
  磁盘 3    联机              476 GB  1024 KB        *

请注意，这里看到的是磁盘，而不是平时在“计算机”中看到的分区——每一个磁盘都可以包含一个到多个分区哦！

你有两种方法来确认我们即将操作的是哪个磁盘：

前面我们在磁盘管理中看到的那个界面，也就是本文一开始的那张图，可以直接看出我们要删除的分区在“磁盘 2”上。
根据分区的大小去猜，相信分区少的时候你可以猜对。

好的，我们知道要操作的是“磁盘 2”，于是我们输入命令 select disk 2（如果你是其他磁盘请换成自己的数字）：

DISKPART> select disk 2

磁盘 2 现在是所选磁盘。

紧接着，我们输入 list partition 列出此磁盘上的所有分区：

DISKPART> list partition

  分区 ###       类型              大小     偏移量
  -------------  ----------------  -------  -------
  分区      1    恢复                 499 MB  1024 KB
  分区      2    系统                 100 MB   500 MB
  分区      3    保留                  16 MB   600 MB
  分区      5    恢复                 820 MB   199 GB
  分区      6    主要                 288 GB   200 GB

通过分区，我们也能再次确认我们找到了正确的要操作的磁盘。

截至目前，我们还没有对系统进行任何更改，所以你操作错了也不用担心。但接下来你就需要谨慎一些。

第四步：删除分区

先选中要操作的分区：

DISKPART> select partition 1

分区 1 现在是所选分区。

然后输入 delete part override 删除这个分区：

DISKPART> delete part override

DiskPart 成功地删除了所选分区。

接着，依次删除其他分区。下面是删除其中前两个分区后的截图：

所有分区删除完毕之后，可以看到我的整个磁盘现在只剩下我要留下的重要数据分区了。

DISKPART> list partition

  分区 ###       类型              大小     偏移量
  -------------  ----------------  -------  -------
  分区      6    主要                 288 GB   200 GB

这时回到磁盘管理中，可以看到大量已被删除的未分配的空间连在了一起。

可以将我的 D 盘扩展更多空间啦！

参考资料

磁盘中出现多个的恢复分区，能否删除？ - 知乎

如何在 Visual Studio 2019 中设置使用 .NET Core SDK 的预览版（全局生效）

Tue, 24 Sep 2019 00:37:39 +0000

.NET Core 3 相比于 .NET Core 2 是一个大更新。也正因为如此，即便它长时间处于预览版尚未发布的状态，大家也一直在使用。

Visual Studio 2019 中提供了使用 .NET Core SDK 预览版的开关。但几个更新的版本其开关的位置不同，本文将介绍在各个版本中的位置，方便你找到然后设置。

Visual Studio 2019 (16.3 及以上)

.NET Core 3.0 已经发布，下载地址：

Download .NET (Linux, macOS, and Windows)

Visual Studio 16.3 与 .NET Core 3.0 正式版同步发布，因此不再需要 .NET Core 3.0 的预览版设置界面。你只需要安装正式版 .NET Core SDK 即可。

Visual Studio 2019 (16.2)

从 Visual Studio 2019 的 16.2 版本，.NET Core 预览版的设置项的位置在：

工具 -> 选项
环境 -> 预览功能 -> Use previews of the .NET Core SDK (需要 restart)

如果你是英文版的 Visual Studio，也可以参考英文版：

Tools -> Options
Environment -> Preview Features -> Use previews of the .NET Core SDK (requires restart)

Visual Studio 2019 (16.1)

从 Visual Studio 2019 的 16.1 版本，.NET Core 预览版的设置项的位置在：

工具 -> 选项
环境 -> 预览功能 -> 使用 .NET Core SDK 的预览

如果你是英文版的 Visual Studio，也可以参考英文版：

Tools -> Options
Environment -> Preview Features -> Use previews of the .NET Core SDK

Visual Studio 2019 (16.0 和早期预览版)

在 Visual Studio 2019 的早期，.NET Core 在设置中是有一个专用的选项的，在这里：

工具 -> 选项
项目和解决方案 -> .NET Core -> 使用 .NET Core SDK 预览版

如果你是英文版的 Visual Studio，也可以参考英文版：

Tools -> Options
Projects and solutions -> .NET Core -> Use previews of the .NET Core SDK

关于全局配置

Visual Studio 2019 中此对于 .NET Core SDK 的预览版的设置是全局生效的。

也就是说，你在 Visual Studio 2019 中进行了此设置，在命令行中使用 MSBuild 或者 dotnet build 命令进行编译也会使用这样的设置项。

那么这个全局的设置项在哪个地方呢？是如何全局生效的呢？可以阅读我的其他博客：

WPF 程序如何移动焦点到其他控件

Thu, 19 Sep 2019 03:41:12 +0000

WPF 中可以使用 UIElement.Focus() 将焦点设置到某个特定的控件，也可以使用 TraversalRequest 仅仅移动焦点。本文介绍如何在 WPF 程序中控制控件的焦点。

`UIElement.Focus`

仅仅需要在任何一个控件上调用 Focus() 方法即可将焦点设置到这个控件上。

但是需要注意，要使 Focus() 能够工作，这个元素必须满足两个条件：

Focusable 设置为 true
IsVisible 是 true

`TraversalRequest`

如果你并不是将焦点设置到某个特定的控件，而是希望将焦点转移，可以考虑使用 TraversalRequest 类。

比如，以下代码是将焦点转移到下一个控件，也就是按下 Tab 键时焦点会去的控件。

var traversalRequest = new TraversalRequest(FocusNavigationDirection.Next);
// view 是可视化树中的一个控件。
view.MoveFocus(traversalRequest);

关于逻辑焦点和键盘焦点

键盘焦点就是你实际上按键输入和快捷键会生效的焦点，也就是当前正在工作的控件的焦点。

而 WPF 有多个焦点范围（Focus Scope），按下 Tab 键切换焦点的时候只会在当前焦点范围切焦点，不会跨范围。那么一旦跨范围切焦点的时候，焦点会去哪里呢？答案是逻辑焦点。

每个焦点范围内都有一个逻辑焦点，记录如果这个焦点范围一旦获得焦点后应该在哪个控件获得键盘焦点。

比如默认情况下 WPF 每个 Window 就是一个焦点范围，那么每个 Window 中的当前焦点就是逻辑焦点。而一旦这个 Window 激活，那么这个窗口中的逻辑焦点就会成为键盘焦点，另一个窗口当中的逻辑焦点保留，而键盘焦点则丢失。

跨窗口/跨进程切换焦点

参见我的另一篇博客：

WPF 程序如何跨窗口/跨进程设置控件焦点

参考资料

winapi - Win32: C++: How do I re-focus on Parent Window after clicking in a child window? - Stack Overflow

使用 SetParent 制作父子窗口的时候，如何设置子窗口的窗口样式以避免抢走父窗口的焦点

Thu, 19 Sep 2019 02:24:12 +0000

制作传统 Win32 程序以及 Windows Forms 程序的时候，一个用户看起来独立的窗口本就是通过各种父子窗口嵌套完成的，有大量窗口句柄，窗口之间形成父子关系。不过，对于 WPF 程序来说，一个独立的窗口实际上只有一个窗口句柄，窗口内的所有内容都是 WPF 绘制的。

如果你不熟悉 Win32 窗口中的父子窗口关系和窗口样式，那么很有可能遇到父子窗口之间“抢夺焦点”的问题，本文介绍如何解决这样的问题。

“抢夺焦点”

下图中的上下两个部分是两个不同的窗口，他们之间通过 SetParent 建立了父子关系。

注意看下面的窗口标题栏，当我在这些不同区域间点击的时候，窗口标题栏在黑色和灰色之间切换：

这说明当子窗口获得焦点的时候，父窗口会失去焦点并显示失去焦点的样式。

你可以在这篇博客中找到一个简单的例子：

解决办法

而原因和解决方法仅有一个，就是子窗口需要有一个子窗口的样式。

具体来说，子窗口必须要有 WS_CHILD 样式。

你可以看看 Spyxx.exe 抓出来的默认普通窗口和子窗口的样式差别：

![默认普通窗口]](/static/posts/2019-09-19-10-21-31.png)

▲ 默认普通窗口

▲ 子窗口

参考资料

关于WS_CLIPCHILDREN和WS_CLIPSIBLINGS的理解（个人认为还是相当全面的） - helloj2ee - 博客园

.NET/C# 利用 Walterlv.WeakEvents 高性能地定义和使用弱事件

Wed, 18 Sep 2019 14:05:55 +0000

弱引用是 .NET 引入的概念，可以用来协助解决内存泄漏问题。然而事件也可能带来内存泄漏问题，是否有弱事件机制可以使用呢？.NET 没有自带的弱事件机制，但其中的一个子集 WPF 带了。然而我们不是什么项目都能引用 WPF 框架类库的。

本文介绍 Walterlv.WeakEvents 库来定义和使用弱事件。

系列博客：

下载安装 Walterlv.WeakEvents

在你需要做弱事件的项目中安装 NuGet 包：

Walterlv.WeakEvents

定义弱事件

现在，定义弱事件就不能直接写 event EventHandler Bar 了，要像下面这样写：

using System;
using Walterlv.WeakEvents;

namespace Walterlv.Demo
{
    public class Foo
    {
        private readonly WeakEvent<EventArgs> _bar = new WeakEvent<EventArgs>();

        public event EventHandler Bar
        {
            add => _bar.Add(value, value.Invoke);
            remove => _bar.Remove(value);
        }

        private void OnBar() => _bar.Invoke(this, EventArgs.Empty);
    }
}

使用弱事件

对于弱事件的使用，就跟以前任何其他正常事件一样了，直接 += 和 -=。

这样，如果我有一个 A 类的实例 a，订阅了以上 Foo 的 Bar 事件，那么当 a 脱离作用范围后，将可以被垃圾回收机制回收。而如果不这么做，Foo 将始终保留对 a 实例的引用，这将阻止垃圾回收。

.NET 设计一套高性能的弱事件机制

Wed, 18 Sep 2019 13:59:58 +0000

弱引用是 .NET 引入的概念，可以用来协助解决内存泄漏问题。然而事件也可能带来内存泄漏问题，是否有弱事件机制可以使用呢？.NET 没有自带的弱事件机制，但其中的一个子集 WPF 带了。然而我们不是什么项目都能引用 WPF 框架类库的。网上有很多弱事件的 NuGet 包，不过仅仅支持定义事件的时候写成弱事件而不支持让任意事件变成弱事件，并且存在性能问题。

本文将设计一套弱事件机制，不止可以让任意一个 CLR 事件成为弱事件，还具有近乎原生事件的性能。

系列博客：

场景与问题

本文主要为了设计一套弱事件机制而编写，因此如果你感兴趣，应该已经理解了我试图做什么事情。

当然，如果并不理解，可以阅读这个机制的应用篇，里面有具体的应用场景：

.NET/C# 利用 Walterlv.WeakEvents 高性能地中转一个自定义的弱事件（可让任意 CLR 事件成为弱事件）

现有设计

在我进行此设计之前，已有如下种类的弱事件机制：

WPF 框架自带的 WeakEventManager
- 功能非常有限，自己继承实现一个的难度非常高，但具有很高的性能；WPF 绑定等机制的底层实现用到了这个类型。
WPF 框架自带的泛型类 WeakEventManager<TEventSource, TEventArgs>
- 可以让你更容易地实现一个自己的弱事件，但是性能非常差
使用网上很多的 NuGet 包
- 下载量较高的几个 NuGet 包我都有研究过其中的源代码，要么有限制必须是定义事件的时候就必须使用弱事件，要么使用反射或其他动态调用方法性能较差
StackOverflow 上关于 Weak Event 的高赞回答
- 目前还没有找到可以支持将任意事件添加弱事件支持的回答

由于我希望编写的弱事件机制尽可能减少对非预期框架的依赖，而且具有很高的性能，所以我打算自己实现一套。

设计原则

支持为任意类型的事件添加弱事件支持，而不只是自己定义新事件的时候可以使用（对标主流 NuGet 包和 StackOverflow 上的回答）
具有很高的性能（对标主流的 NuGet 包和 WPF 泛型版本的 WeakEventManager）
类的使用者只需要编写极少量的代码就能完成（对标 WPF 非泛型版本的 WeakEventManager）

这三个原则，从上到下优先级依次降低。

要支持所有类型的 CLR 事件，意味着我的设计中必须要能够直接监听到任意事件，而不能所有代码都从我自己编写的代码开始。

要有很高的性能，就意味着我几乎不能使用“反射”，也不能使用委托的 DynamicInvoke 方法，还不能生成 IL 代码（首次生成很慢），也不能使用表达式树（首次编译很慢）。那么可以使用的也就只剩下两个了，一个是纯 C#/.NET 带的编译期就能确定执行的代码，另一个是使用 Roslyn 编译期在编译期间进行特殊处理。

类的使用者要编写极少量的代码，意味着能够抽取到框架中的代码就尽量抽取到框架中。

取名

俗话说，一个好的名字是成功的一半。

因为我希望为任意 CLR 事件添加弱事件支持，所以其职责有点像“代理、中间人、中继、中转”，对应英文的 Proxy Agent Relay Transfer。最终我选择名称 Relay（中继），因为好听。

API 设计

对于 API 的设计，我有一个小原则：

如果技术实现很难，那么 API 迁就技术实现；如果技术实现很容易，那么技术迁就 API

我总结了好的 API 设计的一些原则：

好的框架需要好的 API 设计 —— API 设计的六个原则 - walterlv

不得不说，此类型设计的技术难度还是挺大的。虽然我们知道有 WeakReference<T> 可用，但依然存在很多的技术难点。于是 API 的设计可能要退而求其次优先满足前两个优先级更高的目标。

我们期望 API 足够简单，因此在几个备选方案中选择：

WeakEventRelay.Subscribe("Changed", OnChanged)
- 使用字符串来表示事件，肯定会用到反射，不可取
WeakEventRelay.Subscribe(o => o.Changed, OnChanged)
- 如果使用 Action 来做，会遇到 o.Changed 必须出现在 += 左边的编译错误
- 如果使用表达式树，也一样会遇到 o.Changed 必须出现在 += 左边的编译错误，同时还会出现少量性能问题

因此，直接一个方法就能完成事件注册是不可能的了，我们改用其他方法——继承自某个基类：

internal sealed class FileSystemWatcherWeakEventRelay : WeakEventRelay<FileSystemWatcher>
{
    public event FileSystemEventHandler Changed
    {
        add => /*实现弱事件订阅*/;
        remove => /*实现弱事件注销*/;
    }
}

那么实现的难点就都在 add 和 remove 方法里面了。

技术实现

我们究竟需要哪些信息才可以完成弱事件机制呢？

事件源（也就是在使用弱事件机制之前最原始的事件引发者，经常以 object sender 的形式出现在你的代码中）
要订阅的事件（比如 FileSystemWatcher.Changed 事件）
新注册的事件处理函数（也就是 add 和 remove 方法中的 value）

然而事情并没有那么简单：

一

在框架通用代码中，我不可能获取到要订阅的事件。因为事件要求只能出现在 += 的左边，不能以任何其他形式使用（包括但不限于通过参数传递，伪装成 Lambda 表达式，伪装成表达式树）。这意味着 o.Changed += OnChanged 这样的事件订阅完全写不出来通用代码（除非牺牲性能）。

那么还能怎么做呢？只能将这段写不出来的代码留给业务编写者来编写了。

也就是说，类似于 o.Changed += OnChanged 这样的代码只能交给业务开发者来实现。与此同时也注定了 OnChanged 必须由业务开发者编写（因为无法写出通用的高性能的事件处理函数，并且还能在 += 和 -= 的时候保持同一个实例。

二

我没有办法通过抽象的办法引发一个事件。具体来说，无法在抽象的通用代码中写出 Changed.Invoke(sender, e) 这样代码。因为委托的基类 Delegate MultiCastDelegate 没有 Invoke 方法可以使用，只有耗性能的 DynamicInvoke 方法。各种不同的委托定义虽然可以有相同的参数和返回值类型，但是却不能相互转换，因此我也不能将传入的委托转换成 Action<TSender, TArgs> 这样的通用委托。

庆幸的是，C# 提供了将方法组隐式转换委托的方法，可以让两个参数和返回值类型相同的委托隐式转换。但注意，这是隐式转换，没有运行时代码可以高性能地完成这件事情。

在 add 和 remove 方法中，value 参数就是使用方传入的事件处理函数，value.Invoke 就是方法组，可以隐式转换为通用的 Action<TSender, TArgs>。

这意味着，我们可以将 value.Invoke 传入来以通用的方式调用事件处理函数。但是请特别注意，这会导致新创建委托实例，导致 -= 的时候实例与 += 的时候不一致，无法注销事件。因此，我们除了传入 value.Invoke 之外，还必须传入 value 本身。

API 半残品预览

internal sealed class FileSystemWatcherWeakEventRelay : WeakEventRelay<FileSystemWatcher>
{
    public event FileSystemEventHandler Changed
    {
        add => Subscribe(o => o.Changed += OnChanged, value, value.Invoke);
        remove => Unsubscribe(o => o.Changed -= OnChanged, value);
    }

    private void OnChanged(object sender, FileSystemEventArgs e) => /* 引发弱事件 */;
}

这已经开始让业务方的代码变得复杂起来了。

方案完善

我们还需要能够注册、注销和引发弱事件，而这部分就没那么坑了。因为：

我们已经把最坑的 o.Changed += OnChanged，value，value.Invoke 都传进来了；
在类型中定义一个弱事件，目前网上各种主流弱事件 NuGet 包都有实现。

我写了一个 WeakEvent<TSender, TArgs> 泛型类专门用来定义弱事件。

不过，这让业务方的代码压力更大了：

internal sealed class FileSystemWatcherWeakEventRelay : WeakEventRelay<FileSystemWatcher>
{
    private readonly WeakEvent<FileSystemEventArgs> _changed = new WeakEvent<FileSystemEventArgs>();

    public event FileSystemEventHandler Changed
    {
        add => Subscribe(o => o.Changed += OnChanged, () => _changed.Add(value, value.Invoke));
        remove => _changed.Remove(value);
    }

    private void OnChanged(object sender, FileSystemEventArgs e) => TryInvoke(_changed, sender, e);
}

最后，订阅事件所需的实例，我认为最好不要能够让业务方直接能访问。因为弱事件的实现并不简单（看上面如此复杂的公开 API 就知道了），如果能够直接访问，势必带来更复杂的使用问题。所以我仅在部分方法和 Lambda 表达式参数中开放实例。

所以，构造函数需要传入事件源。

最后的问题

最后还留下了一个问题

订阅者现在确实“弱事件”了，但这个“中继”怎么办？可是被强引用了啊？

虽然中继的类实例小得多，但这确实依然也是泄漏，因此需要回收。

于是我在任何可能执行代码的时机加上了回收检查：如果发现所有订阅者都已经被回收，那么“中继”也就可以被回收了，将注销所有事件源的订阅。（当然要允许重新开始订阅。）

所以最后业务方编写的中继代码又多了一些：

using System.IO;
using Walterlv.WeakEvents;

namespace Walterlv.Demo
{
    internal sealed class FileSystemWatcherWeakEventRelay : WeakEventRelay<FileSystemWatcher>
    {
        public FileSystemWatcherWeakEventRelay(FileSystemWatcher eventSource) : base(eventSource) { }

        private readonly WeakEvent<FileSystemEventArgs> _changed = new WeakEvent<FileSystemEventArgs>();

        public event FileSystemEventHandler Changed
        {
            add => Subscribe(o => o.Changed += OnChanged, () => _changed.Add(value, value.Invoke));
            remove => _changed.Remove(value);
        }

        private void OnChanged(object sender, FileSystemEventArgs e) => TryInvoke(_changed, sender, e);

        protected override void OnReferenceLost(FileSystemWatcher source)
        {
            source.Changed -= OnChanged;
        }
    }
}

实际使用

虽然弱事件中继的代码复杂了点，但是：

1 最终用户的使用可是非常简单的：

public class WalterlvDemo
{
    public WalterlvDemo()
    {
        _watcher = new FileSystemWatcher(@"D:\Desktop\walterlv.demo.md")
        {
            EnableRaisingEvents = true,
        };
        _watcher.Created += OnCreated;
        _watcher.Changed += OnChanged;
        _watcher.Renamed += OnRenamed;
        _watcher.Deleted += OnDeleted;
    }

    private readonly FileSystemWatcher _watcher;
    private void OnCreated(object sender, FileSystemEventArgs e) { }
    private void OnChanged(object sender, FileSystemEventArgs e) { }
    private void OnRenamed(object sender, RenamedEventArgs e) { }
    private void OnDeleted(object sender, FileSystemEventArgs e) { }
}

2 是在懒得写，我可以加上 Roslyn 编译器生成中继代码的方式，这个我将在不久的将来加入到 Walterlv.WeakEvents 库中。

.NET/C# 利用 Walterlv.WeakEvents 高性能地中转一个自定义的弱事件（可让任意 CLR 事件成为弱事件）

Wed, 18 Sep 2019 13:59:52 +0000

本文介绍 Walterlv.WeakEvents 库来做弱事件。你可以借此将任何一个 CLR 事件当作弱事件来使用。

系列博客：

场景与问题

了解一下场景，你就能知道这是否是适合你的方案。

比如我正在使用 FileSystemWatcher 来监听一个文件的改变，我可能会使用到这些事件：

Created 在文件被创建时引发
Changed 在文件内容或属性发生改变时引发
Renamed 在文件被重命名时引发
Deleted 在文件被删除时引发

更具体一点的代码是这样的：

public class WalterlvDemo
{
    public WalterlvDemo()
    {
        _watcher = new FileSystemWatcher(@"D:\Desktop\walterlv.demo.md")
        {
            EnableRaisingEvents = true,
        };
        _watcher.Created += OnCreated;
        _watcher.Changed += OnChanged;
        _watcher.Renamed += OnRenamed;
        _watcher.Deleted += OnDeleted;
    }

    private readonly FileSystemWatcher _watcher;
    private void OnCreated(object sender, FileSystemEventArgs e) { }
    private void OnChanged(object sender, FileSystemEventArgs e) { }
    private void OnRenamed(object sender, RenamedEventArgs e) { }
    private void OnDeleted(object sender, FileSystemEventArgs e) { }
}

private void Foo()
{
    var demo = new WalterlvDemo();
    // 使用 demo
    // 此方法结束后，demo 将脱离作用域，本应该可以被回收的。
}

但是，一旦我们这么写，那么我们这个类型 WalterlvDemo 的实例 demo 将无法被回收，因为 FileSystemWatcher 将始终通过事件引用着这个实例。即使你已经不再引用这个类型的任何一个实例，此实例也会被 _watcher 的事件引用着，而 FileSystemWatcher 的实例也因为 EnableRaisingEvents 而一直存在。

一个可行的解决办法是调用 FileSystemWatcher 的 Dispose 方法。不过有些时候很难决定到底在什么时机调用 Dispose 合适。

现在，我们希望有一种方法，能够在 WalterlvDemo 的实例失去作用域后被回收，最好 FileSystemWatcher 也能够自动被 Dispose 释放掉。

如果你试图解决的是类似这样的问题，那么本文就可以帮到你。

总结一下：

用到了一个现有的类型（你无法修改它的源代码，本例中是 FileSystemWatcher）；
你无法决定什么时候释放此类型的实例（本例中是不知道什么时候调用 Dispose）；
一旦你监听此类型的事件，将产生内存泄漏，导致你自己类型的实例无法释放（本例中是 demo 变量脱离作用域。）。

目前有 WPF 自带的 WeakEventManager 机制，网上也有很多可用的 NuGet 包，但是都有限制：

只能给自己定义的类型引入弱事件机制，不能给现有类型引入弱事件；
要么用反射，要么用 IL 生成代码，性能都不高。

而 Walterlv.WeakEvents 除了解决了给任一类型引入弱事件的问题，还具有非常高的性能，几乎跟定义原生事件无异。

下载安装 Walterlv.WeakEvents

在你需要做弱事件的项目中安装 NuGet 包：

Walterlv.WeakEvents

编写自定义的弱事件中继

现在，我们需要编写一个自定义的弱事件中继类 FileSystemWatcherWeakEventRelay，即专门为 FileSystemWatcher 做的弱事件中继。

下面是一个简单点的例子，为其中的 Changed 事件做了一个中继：

using System.IO;
using Walterlv.WeakEvents;

namespace Walterlv.Demo
{
    internal sealed class FileSystemWatcherWeakEventRelay : WeakEventRelay<FileSystemWatcher>
    {
        public FileSystemWatcherWeakEventRelay(FileSystemWatcher eventSource) : base(eventSource) { }

        private readonly WeakEvent<FileSystemEventArgs> _changed = new WeakEvent<FileSystemEventArgs>();

        public event FileSystemEventHandler Changed
        {
            add => Subscribe(o => o.Changed += OnChanged, () => _changed.Add(value, value.Invoke));
            remove => _changed.Remove(value);
        }

        private void OnChanged(object sender, FileSystemEventArgs e) => TryInvoke(_changed, sender, e);

        protected override void OnReferenceLost(FileSystemWatcher source)
        {
            source.Changed -= OnChanged;
        }
    }
}

你可能会看到代码有点儿多，但是我向你保证，这是除了采用 Roslyn 编译器技术以外最高性能的方案了。如果你对弱事件的性能有要求，那么还是接受这些代码会比较好。

不要紧张，我来一一解释这些代码。另外，如果你不想懂这些代码，就按照模板一个个敲就好了，都是模板化的代码（特别适合使用 Roslyn 编译器生成，我可能接下来就会做这件事情避免你写出这些代码）。

首先，我们定义了一个自定义的弱事件中继 FileSystemWatcherWeakEventRelay，继承自库 Walterlv.WeakEvents 中的 WeakEventRelay<FileSystemWatcher> 类型。带上的泛型参数表明是针对 FileSystemWatcher 类型做弱事件中继。
一个构造函数，将参数传递给基类：public FileSystemWatcherWeakEventRelay(FileSystemWatcher eventSource) : base(eventSource) { }。这个构造函数是可以用 Visual Studio 生成的，快捷键是 Ctrl + . 或者 Alt + Enter（快捷键功效详见：提高使用 Visual Studio 开发效率的键盘快捷键）
定义了一个私有的 WeakEvent<FileSystemEventArgs>，名为 _changed，这个就是弱事件的核心。泛型参数是事件参数的类型（注意，为了极致的性能，这里的泛型参数是事件参数的名称，而不是大多数弱事件框架中提供的事件处理委托类型）。
定义了一个对外公开的事件 public event FileSystemEventHandler Changed。
- add 方法固定调用 Subscribe(o => o.Changed += OnChanged, () => _changed.Add(value, value.Invoke));。其中 Changed 是 FileSystemWatcher 中的事件，OnChanged 是我们即将定义的事件处理函数，_changed 是前面定义好的弱事件字段，而后面的 value 和 value.Invoke 是固定写法。
- remove 方法固定调用弱事件的 Remove 方法，即 _changed.Remove(value);。
编写针对公开事件的事件处理函数 OnChanged，并在里面固定调用 TryInvoke(_changed, sender, e)。
重写 OnReferenceLost 方法，用于在对象已被回收后反注册 FileSystemWatcher 中的事件。

希望看了上面这 6 点之后你还能理解这些代码都是在做啥。如果依然不能理解，可以考虑：

参考下面 FileSystemWatcherWeakEventRelay 的完整代码来理解哪些是可变部分哪些是不可变部分，自己替换就好；
等待 Walterlv.WeakEvents 库的作者更新自动生成这段代码的功能。

using System.IO;
using Walterlv.WeakEvents;

namespace Walterlv.Demo
{
    internal sealed class FileSystemWatcherWeakEventRelay : WeakEventRelay<FileSystemWatcher>
    {
        public FileSystemWatcherWeakEventRelay(FileSystemWatcher eventSource) : base(eventSource) { }

        private readonly WeakEvent<FileSystemEventArgs> _created = new WeakEvent<FileSystemEventArgs>();
        private readonly WeakEvent<FileSystemEventArgs> _changed = new WeakEvent<FileSystemEventArgs>();
        private readonly WeakEvent<RenamedEventArgs> _renamed = new WeakEvent<RenamedEventArgs>();
        private readonly WeakEvent<FileSystemEventArgs> _deleted = new WeakEvent<FileSystemEventArgs>();

        public event FileSystemEventHandler Created
        {
            add => Subscribe(o => o.Created += OnCreated, () => _created.Add(value, value.Invoke));
            remove => _created.Remove(value);
        }

        public event FileSystemEventHandler Changed
        {
            add => Subscribe(o => o.Changed += OnChanged, () => _changed.Add(value, value.Invoke));
            remove => _changed.Remove(value);
        }

        public event RenamedEventHandler Renamed
        {
            add => Subscribe(o => o.Renamed += OnRenamed, () => _renamed.Add(value, value.Invoke));
            remove => _renamed.Remove(value);
        }

        public event FileSystemEventHandler Deleted
        {
            add => Subscribe(o => o.Deleted += OnDeleted, () => _deleted.Add(value, value.Invoke));
            remove => _deleted.Remove(value);
        }

        private void OnCreated(object sender, FileSystemEventArgs e) => TryInvoke(_created, sender, e);
        private void OnChanged(object sender, FileSystemEventArgs e) => TryInvoke(_changed, sender, e);
        private void OnRenamed(object sender, RenamedEventArgs e) => TryInvoke(_renamed, sender, e);
        private void OnDeleted(object sender, FileSystemEventArgs e) => TryInvoke(_deleted, sender, e);

        protected override void OnReferenceLost(FileSystemWatcher source)
        {
            source.Created -= OnCreated;
            source.Changed -= OnChanged;
            source.Renamed -= OnRenamed;
            source.Deleted -= OnDeleted;
            source.Dispose();
        }
    }
}

使用自定义的弱事件中继

当你把上面这个自定义的弱事件中继类型写好了之后，使用它就非常简单了，对我们原有的代码改动非常小。

    public class WalterlvDemo
    {
        public WalterlvDemo()
        {
            _watcher = new FileSystemWatcher(@"D:\Desktop\walterlv.demo.md")
            {
                EnableRaisingEvents = true,
            };
++          var weakEvent = new FileSystemWatcherWeakEventRelay(_watcher);
--          _watcher.Created += OnCreated;
--          _watcher.Changed += OnChanged;
--          _watcher.Renamed += OnRenamed;
--          _watcher.Deleted += OnDeleted;
++          weakEvent.Created += OnCreated;
++          weakEvent.Changed += OnChanged;
++          weakEvent.Renamed += OnRenamed;
++          weakEvent.Deleted += OnDeleted;
        }

        private readonly FileSystemWatcher _watcher;
        private void OnCreated(object sender, FileSystemEventArgs e) { }
        private void OnChanged(object sender, FileSystemEventArgs e) { }
        private void OnRenamed(object sender, RenamedEventArgs e) { }
        private void OnDeleted(object sender, FileSystemEventArgs e) { }
    }

最终效果预览

我写了一个程序，每 1 秒修改一次文件；每 5 秒回收一次内存。然后使用 FileSystemWatcher 来监视这个文件的改变。

可以看到，在回收内存之后，将不会再监视文件的改变。当然，如果你期望一直可以监视改变，当然也不希望用到本文的弱事件。

为什么弱事件中继的 API 如此设计？

一句话解答：为了高性能！

请参见我的另一篇博客：

.NET 设计一套高性能的弱事件机制

参考资料

Weak Event Patterns - Microsoft Docs

C#/.NET 中启动进程时所使用的 UseShellExecute 设置为 true 和 false 分别代表什么意思？

Tue, 17 Sep 2019 04:37:17 +0000

在 .NET 中创建进程时，可以传入 ProcessStartInfo 类的一个新实例。在此类型中，有一个 UseShellExecute 属性。

本文介绍 UseShellExecute 属性的作用，设为 true 和 false 时，分别有哪些进程启动行为上的差异。

本质差异

Process.Start 本质上是启动一个新的子进程，不过这个属性的不同，使得启动进程的时候会调用不同的 Windows 的函数。

UseShellExecute = true
- 调用的是 ShellExecute
UseShellExecute = false
- 调用的是 CreateProcess

当然，如果你知道这两个函数的区别，那你自然也就了解此属性设置为 true 和 false 的区别了。

效果差异

ShellExecute 的用途是打开程序或者文件或者其他任何能够打开的东西（如网址）。

也就是说，你可以在 Process.Start 的时候传入这些：

一个可执行程序（exe）
一个网址
一个 html / mp4 / jpg / docx / enbx 等各种文件
在 PATH 环境变量中的各种程序

不过，此方法有一些值得注意的地方：

不支持重定向输入和输出
最终启动了哪个进程可能是不确定的，你可能需要注意潜在的安全风险

而 CreateProcess 则会精确查找路径来执行，不支持各种非可执行程序的打开。但是：

支持重定向输入和输出

如何选择

UseShellExecute 在 .NET Framework 中的的默认值是 true，在 .NET Core 中的默认值是 false。

如果有以下需求，那么建议设置此值为 false：

需要明确执行一个已知的程序
需要重定向输入和输出

如果你有以下需求，那么建议设置此值为 true 或者保持默认：

需要打开文档、媒体、网页文件等
需要打开 Url
需要打开脚本执行
需要打开计算机上环境变量中路径中的程序

参考资料

c# - When do we need to set UseShellExecute to True? - Stack Overflow

.NET Framework 的 bug？try-catch-when 中如果 when 语句抛出异常，程序将彻底崩溃

Thu, 12 Sep 2019 06:58:50 +0000

在 .NET Framework 4.8 中，try-catch-when 中如果 when 语句抛出异常，程序将彻底崩溃。而 .NET Core 3.0 中不会出现这样的问题。

本文涉及的 Bug 已经报告给了微软，并且得到了微软的回复。是 .NET Framework 4.8 为了解决一个安全性问题而强行结束了进程。

This post is written in multiple languages. Please select yours:

官方文档中 when 的行为

你可以前往官方文档：

使用用户筛选的异常处理程序 - Microsoft Docs

在其中，你可以找到这样一段话：

用户筛选的子句的表达式不受任何限制。如果在执行用户筛选的表达式期间发生异常，则将放弃该异常，并视筛选表达式的值为 false。在这种情况下，公共语言运行时继续搜索当前异常的处理程序。

即当 when 块中出现异常时，when 表达式将视为值为 false，并且此异常将被忽略。

示例程序

鉴于官方文档中的描述，我们可以编写一些示例程序来验证这样的行为。

using System;
using System.IO;

namespace Walterlv.Demo.CatchWhenCrash
{
    internal class Program
    {
        private static void Main(string[] args)
        {
            try
            {
                try
                {
                    Console.WriteLine("Try");
                    throw new FileNotFoundException();
                }
                catch (FileNotFoundException ex) when (ex.FileName.EndsWith(".png"))
                {
                    Console.WriteLine("Catch 1");
                }
                catch (FileNotFoundException)
                {
                    Console.WriteLine("Catch 2");
                }
            }
            catch (Exception)
            {
                Console.WriteLine("Catch 3");
            }
            Console.WriteLine("End");
        }
    }
}

很显然，我们直接 new 出来的 FileNotFoundException 的 FileName 属性会保持为 null。对其解引用会产生 NullReferenceException。很显然代码不应该这么写，但可以用来验证 catch-when 语句的行为。

按照官网描述，输出应该为 Try-Catch 2-End。因为 when 中的异常被忽略，因此不会进入到外层的 catch 块中；因为 when 中出现异常导致表达式值视为 false，因此进入了更合适的异常处理块 Catch 2 中。

在 .NET Core 3.0 中的行为和 .NET Framework 4.8 中的行为

下面两张图分别是这段代码在 .NET Core 3.0 和 .NET Framework 4.8 中的输出：

可以注意到，只有 .NET Core 3.0 中的行为符合官方文档的描述，而 .NET Framework 4.8 中甚至连 End 都没有输出！几乎可以确定，程序在 .NET Framework 4.8 中出现了致命的崩溃！

如果我们以 Visual Studio 调试启动此程序，可以看到抛出了 CLR 异常：

以下是在 Visual Studio 中单步跟踪的步骤：

Issue 和行为

由于本人金鱼般的记忆力，我竟然给微软报了三次这个 Bug：

给文档的（2019.09.10）：When use the when keyword in a catch expression the app crashes instead of do what the document says · Issue #14338 · dotnet/docs
给框架和 SDK 的（2019.09.12）： When use the when keyword in a catch expression the app crashes instead of do what the document says · Issue #41047 · dotnet/corefx
给运行时的（2019.07.02）：App will crash when using the when keyword in a catch expression · Issue #25534 · dotnet/coreclr

此问题是 .NET Framework 4.8 为了修复一个安全性问题才强行结束了进程：

Process corrupting exceptions in exception filter (like access violation) now result in aborting the current process. [110375, clr.dll, Bug, Build:3694]

请参见：

dotnet/dotnet48-changes.md at master · microsoft/dotnet

如何在 WPF 中获取所有已经显式赋过值的依赖项属性

Thu, 12 Sep 2019 03:39:49 +0000

获取 WPF 的依赖项属性的值时，会依照优先级去各个级别获取。这样，无论你什么时候去获取依赖项属性，都至少是有一个有效值的。有什么方法可以获取哪些属性被显式赋值过呢？如果是 CLR 属性，我们可以自己写判断条件，然而依赖项属性没有自己写判断条件的地方。

本文介绍如何获取以及显式赋值过的依赖项属性。

需要用到 DependencyObject.GetLocalValueEnumerator() 方法来获得一个可以遍历所有依赖项属性本地值。

public static void DoWhatYouLikeByWalterlv(DependencyObject dependencyObject)
{
    var enumerator = dependencyObject.GetLocalValueEnumerator();
    while (enumerator.MoveNext())
    {
        var entry = enumerator.Current;
        var property = entry.Property;
        var value = entry.Value;
        // 在这里使用 property 和 value。
    }
}

这里的 value 可能是 MarkupExtension 可能是 BindingExpression 还可能是其他一些可能延迟计算值的提供者。因此，你不能在这里获取到常规方法获取到的依赖项属性的真实类型的值。

但是，此枚举拿到的所有依赖项属性的值都是此依赖对象已经赋值过的依赖项属性的本地值。如果没有赋值过，将不会在这里的遍历中出现。

参考资料

Dependency properties overview - Microsoft Docs

在 WPF 中获取一个依赖对象的所有依赖项属性

Thu, 12 Sep 2019 03:24:33 +0000

本文介绍如何在 WPF 中获取一个依赖对象的所有依赖项属性。

通过 WPF 标记获取

public static IEnumerable<DependencyProperty> EnumerateDependencyProperties(object element)
{
    if (element is null)
    {
        throw new ArgumentNullException(nameof(element));
    }

    MarkupObject markupObject = MarkupWriter.GetMarkupObjectFor(element);
    if (markupObject != null)
    {
        foreach (MarkupProperty mp in markupObject.Properties)
        {
            if (mp.DependencyProperty != null)
            {
                yield return mp.DependencyProperty;
            }
        }
    }
}

public static IEnumerable<DependencyProperty> EnumerateAttachedProperties(object element)
{
    if (element is null)
    {
        throw new ArgumentNullException(nameof(element));
    }

    MarkupObject markupObject = MarkupWriter.GetMarkupObjectFor(element);
    if (markupObject != null)
    {
        foreach (MarkupProperty mp in markupObject.Properties)
        {
            if (mp.IsAttached)
            {
                yield return mp.DependencyProperty;
            }
        }
    }
}

通过设计器专用方法获取

本来 .NET 中提供了一些专供设计器使用的类型 TypeDescriptor 可以帮助设计器找到一个类型或者组件的所有可以设置的属性，不过我们也可以通过此方法来获取所有可供使用的属性。

下面是带有重载的两个方法，一个传入类型一个传入实例。

/// <summary>
/// 获取一个对象中所有的依赖项属性。
/// </summary>
public static IEnumerable<DependencyProperty> GetDependencyProperties(object instance)
    => TypeDescriptor.GetProperties(instance, new Attribute[] { new PropertyFilterAttribute(PropertyFilterOptions.All) })
        .OfType<PropertyDescriptor>()
        .Select(x => DependencyPropertyDescriptor.FromProperty(x)?.DependencyProperty)
        .Where(x => x != null);

/// <summary>
/// 获取一个类型中所有的依赖项属性。
/// </summary>
public static IEnumerable<DependencyProperty> GetDependencyProperties(Type type)
    => TypeDescriptor.GetProperties(type, new Attribute[] { new PropertyFilterAttribute(PropertyFilterOptions.All) })
        .OfType<PropertyDescriptor>()
        .Select(x => DependencyPropertyDescriptor.FromProperty(x)?.DependencyProperty)
        .Where(x => x != null);

参考资料

临时编写和调试 C++ 代码？用 VSCode 就够了！一分钟搭好 C++ 调试环境

Sat, 07 Sep 2019 02:07:36 +0000

突然间要编写或者调试几个 C++ 的小程序，动用 Visual Studio 创建一个解决方案显得大了些。如果能够利用随时随地就方便打开的 Visual Studio Code 来开发，则清爽很多。

本文教你一分钟在 Visual Studio Code 中搭建好 C++ 开发环境。

本文大纲

本文总共分为三个步骤，每个步骤都非常简单。

第一步：安装扩展

你需要在 Visual Studio Code 中安装 C/C++ 扩展。

第二步：启动 VSCode

注意，安装完成后，要通过 Visual Studio 自带的 Developer Command Prompt for VS 2019 来启动 Visual Studio Code。这样才可以获得 Visual Studio 2019 自带的各种编译工具路径的环境变量。Visual Studio Code 就可以无缝使用 Visual Studio 2019 附带的那些工具。

然后，在新启动的命令行工具中启动 Visual Studio Code。

输入 code 即可启动：

> code

如果已有线程的路径，可以带上路径的命令行参数：

> code C:\Users\lvyi\Desktop\Walterlv.CppDemo

第三步：F5 运行

随便在目录中新建一个文件，写上 C++ 代码。比如在 example.cpp 文件中写上如下代码：

#include<iostream>
using namespace std;

int main()
{
    cout<<"welcome to blog.walterlv.com";
    return 0;
}

按下 F5，选择对应的 C++ 编译平台（我这里选择 C++ (Windows)），然后选择 cl.exe build and debug active file。

cl.exe build and debug active file 的目的是调试当前激活的文件，这样的调试方式在 python/java 等语言中大家屡见不鲜，好处是对于小型代码调试起来非常简单直接。

接下来 Visual Studio Code 就会生成一些调试所需的配置文件。

再次按下 F5，Visual Studio Code 会提示没有编译任务，点击 Configure Task，随后选择 C/C++: cl.exe build active file。

接下来 Visual Studio Code 就会生成一些编译所需的配置文件。

再次按下 F5 就可以直接编译 example.cpp 文件然后运行调试了。

输出在 Debug Console 里面：

其他注意事项

如果你给 Visual Studio 设置了非默认的终端，那么需要注意：

应该使用 PowerShell 系列的终端（例如 pwsh）不能使用 bash 系列的终端。因为 Windows 下工具使用的路径格式是反斜杠 \，而 bash 系列终端使用的路径是斜杠 /。如果使用 bash 终端，编译工具会因为路径问题导致编译失败。

另外，不要怪我说我是这么编写教程的：

首先，我们已知 1+1=2

于是可以推导出……

在使用 .NET Remoting 技术开发跨进程通信时可能遇到的各种异常

Thu, 05 Sep 2019 13:26:31 +0000

在使用 .NET Remoting 开发跨进程应用的时候，你可能会遇到一些异常。因为这些异常在后验的时候非常简单但在一开始有各种异常烦扰的时候却并不清晰，所以我将这些异常整理到此文中，方便小伙伴们通过搜索引擎查阅。

连接到 IPC 端口失败: 系统找不到指定的文件

System.Runtime.Remoting.RemotingException:“连接到 IPC 端口失败: 系统找不到指定的文件。”

或者英文版：

System.Runtime.Remoting.RemotingException: Failed to connect to an IPC Port: The system cannot find the file specified.

出现此异常时，说明你获取到了一个远端对象，但是在使用此对象的时候，甚至还没有注册 IPC 端口。

比如，下面的代码是注册一个 IPC 端口的一种比较粗暴的写法，传入的 portName 是 IPC 的 Uri 路径前缀。例如我可以传入 walterlv，这样一个 IPC 对象的格式大约类似 ipc://walterlv/xxx。

private static void RegisterChannel(string portName)
{
    var serverProvider = new BinaryServerFormatterSinkProvider
    {
        TypeFilterLevel = TypeFilterLevel.Full,
    };
    var clientProvider = new BinaryClientFormatterSinkProvider();
    var properties = new Hashtable
    {
        ["portName"] = portName
    };
    var channel = new IpcChannel(properties, clientProvider, serverProvider);
    ChannelServices.RegisterChannel(channel, false);
}

当试图访问 ipc://walterlv/foo 对象并调用其中的方法的时候，如果连 walterlv 端口都没有注册，就会出现 连接到 IPC 端口失败: 系统找不到指定的文件。 异常。

如果你已经注册了 walterlv 端口，但是没有 foo 对象，则会出现另一个错误 找不到请求的服务，请看下一节。

找不到请求的服务

System.Runtime.Remoting.RemotingException:“找不到请求的服务”

或者英文版：

System.Runtime.Remoting.RemotingException: Requested Service not found

当出现此异常时，可能的原因有三个：

要查找的远端对象尚未创建；
要查找的远端对象已被回收；
没有使用匹配的方法创建和访问对象。

更具体来说，对于第一种情况，就是当你试图跨进程访问某对象的时候，此对象还没有创建。你需要做的，是控制好对象创建的时机，创建对象的进程需要比访问它的进程更早完成对象的创建和封送。也就是下面的代码需要先调用。

RemotingServices.Marshal(@object, typeof(TObject).Name, typeof(TObject));

而对于第二种情况，你可能需要手动处理好封送对象的生命周期。重写 InitializeLifetimeService 方法并返回 null 是一个很偷懒却有效的方法。

namespace Walterlv.Remoting.Framework
{
    public abstract class RemoteObject : MarshalByRefObject
    {
        public sealed override object InitializeLifetimeService() => null;
    }
}

而对于第三种情况，你需要检查你是如何注册 .NET Remoting 通道的，创建和访问方式必须匹配。

信道“ipc”已注册

System.Runtime.Remoting.RemotingException:“信道“ipc”已注册。”

在同一个进程中，IpcChannel 类的默认信道名称 IpcChannel.ChannelName 值是字符串 "ipc"。如果你不通过它的参数 properties 来指定 ["name"] = "另一个名称"，那么你就不能重复调用 ChannelServices.RegisterChannel 来调用这个信道。

说简单点，就是上面的方法 RegisterChannel 你不能在一个进程中调用两次，即便 "portName" 不同也不行。通常你也不需要去调用两次，如果一定要，请通过 HashTable 修改 name 属性。

参考资料

c# - .Net remoting error “Requested Service not found” - Stack Overflow

.NET/C# 阻止屏幕关闭，阻止系统进入睡眠状态

Thu, 05 Sep 2019 06:49:41 +0000

在 Windows 系统中，一段时间不操作键盘和鼠标，屏幕便会关闭，系统会进入睡眠状态。但有些程序（比如游戏、视频和演示文稿）在运行过程中应该阻止屏幕关闭，否则屏幕总是关闭，会导致体验会非常糟糕。

本文介绍如何编写 .NET/C# 代码临时阻止屏幕关闭以及系统进入睡眠状态。

Windows API

我们需要使用到一个 Windows API：

/// <summary>
/// Enables an application to inform the system that it is in use, thereby preventing the system from entering sleep or turning off the display while the application is running.
/// </summary>
[DllImport("kernel32")]
private static extern ExecutionState SetThreadExecutionState(ExecutionState esFlags);

使用到的枚举用 C# 类型定义是：

[Flags]
private enum ExecutionState : uint
{
    /// <summary>
    /// Forces the system to be in the working state by resetting the system idle timer.
    /// </summary>
    SystemRequired = 0x01,

    /// <summary>
    /// Forces the display to be on by resetting the display idle timer.
    /// </summary>
    DisplayRequired = 0x02,

    /// <summary>
    /// This value is not supported. If <see cref="UserPresent"/> is combined with other esFlags values, the call will fail and none of the specified states will be set.
    /// </summary>
    [Obsolete("This value is not supported.")]
    UserPresent = 0x04,

    /// <summary>
    /// Enables away mode. This value must be specified with <see cref="Continuous"/>.
    /// <para />
    /// Away mode should be used only by media-recording and media-distribution applications that must perform critical background processing on desktop computers while the computer appears to be sleeping.
    /// </summary>
    AwaymodeRequired = 0x40,

    /// <summary>
    /// Informs the system that the state being set should remain in effect until the next call that uses <see cref="Continuous"/> and one of the other state flags is cleared.
    /// </summary>
    Continuous = 0x80000000,
}

以上所有的注释均照抄自微软的官方 API 文档：

SetThreadExecutionState function (winbase.h) - Microsoft Docs

API 封装

如果你擅长阅读英文，那么以上的 API 函数、枚举和注释足够你完成你的任务了。

不过，我这里提供一些封装，以应对一些常用的场景。

using System;
using System.Runtime.InteropServices;

namespace Walterlv.Windows
{
    /// <summary>
    /// 包含控制屏幕关闭以及系统休眠相关的方法。
    /// </summary>
    public static class SystemSleep
    {
        /// <summary>
        /// 设置此线程此时开始一直将处于运行状态，此时计算机不应该进入睡眠状态。
        /// 此线程退出后，设置将失效。
        /// 如果需要恢复，请调用 <see cref="RestoreForCurrentThread"/> 方法。
        /// </summary>
        /// <param name="keepDisplayOn">
        /// 表示是否应该同时保持屏幕不关闭。
        /// 对于游戏、视频和演示相关的任务需要保持屏幕不关闭；而对于后台服务、下载和监控等任务则不需要。
        /// </param>
        public static void PreventForCurrentThread(bool keepDisplayOn = true)
        {
            SetThreadExecutionState(keepDisplayOn
                ? ExecutionState.Continuous | ExecutionState.SystemRequired | ExecutionState.DisplayRequired
                : ExecutionState.Continuous | ExecutionState.SystemRequired);
        }

        /// <summary>
        /// 恢复此线程的运行状态，操作系统现在可以正常进入睡眠状态和关闭屏幕。
        /// </summary>
        public static void RestoreForCurrentThread()
        {
            SetThreadExecutionState(ExecutionState.Continuous);
        }

        /// <summary>
        /// 重置系统睡眠或者关闭屏幕的计时器，这样系统睡眠或者屏幕能够继续持续工作设定的超时时间。
        /// </summary>
        /// <param name="keepDisplayOn">
        /// 表示是否应该同时保持屏幕不关闭。
        /// 对于游戏、视频和演示相关的任务需要保持屏幕不关闭；而对于后台服务、下载和监控等任务则不需要。
        /// </param>
        public static void ResetIdle(bool keepDisplayOn = true)
        {
            SetThreadExecutionState(keepDisplayOn
                ? ExecutionState.SystemRequired | ExecutionState.DisplayRequired
                : ExecutionState.SystemRequired);
        }
    }
}

如果你对这段封装中的 keepDisplayOn 参数，也就是 ExecutionState.DisplayRequired 枚举不了解，看看下图直接就懂了。一个指的是屏幕关闭，一个指的是系统进入睡眠。

此封装后，使用则相当简单：

// 阻止系统睡眠，阻止屏幕关闭。
SystemSleep.PreventForCurrentThread();

// 恢复此线程曾经阻止的系统休眠和屏幕关闭。
SystemSleep.RestoreForCurrentThread();

或者：

// 重置系统计时器，临时性阻止系统睡眠和屏幕关闭。
// 此效果类似于手动使用鼠标或键盘控制了一下电脑。
SystemSleep.ResetIdle();

在使用 PreventForCurrentThread 这个 API 的时候，你需要避免程序对空闲时机的控制不好，导致屏幕始终不关闭。

如果你发现无论你设置了多么短的睡眠时间和屏幕关闭时间，屏幕都不会关闭，那就是有某个程序阻止了屏幕关闭，你可以：

参考资料

SetThreadExecutionState function (winbase.h) - Microsoft Docs

git fetch 失败，因为 unable to resolve reference 'refs/remotes/origin/xxx': reference broken

Thu, 05 Sep 2019 06:37:15 +0000

我在使用 git fetch 命令的时候，发现竟然会失败，提示错误 error: cannot lock ref 'refs/remotes/origin/xxx': unable to resolve reference 'refs/remotes/origin/xxx': reference broken。

本文介绍如何修复这样的错误，并探索此错误产生的原因。

错误

在使用 git fetch 命令之后，发现竟然出现了错误，错误输出如下：

$ git fetch --all --prune
Fetching origin
error: cannot lock ref 'refs/remotes/origin/next/release': unable to resolve reference 'refs/remotes/origin/next/release': reference broken
From git***.***.com:walterlv/demo-project
 ! [new branch]            next/release        -> origin/next/release  (unable to update local ref)
error: cannot lock ref 'refs/remotes/origin/feature/ai': unable to resolve reference 'refs/remotes/origin/feature/ai': reference broken
 ! [new branch]            feature/ai          -> origin/feature/ai  (unable to update local ref)
error: cannot lock ref 'refs/remotes/origin/release': unable to resolve reference 'refs/remotes/origin/release': reference broken
 ! [new branch]            release             -> origin/release  (unable to update local ref)
error: Could not fetch origin

修复

前往仓库路径，然后删除这些分支对应的文件。

前往仓库所在的本地文件夹；
进入子目录 .git\refs\remotes；
一个个对着上面失败的分支，将其删除。

比如在我的错误例子中，要删除的文件分别是：

.git\refs\remotes\origin\next\release
.git\refs\remotes\origin\feature\ai
.git\refs\remotes\origin\release

随后，重新尝试 git fetch，git 会重新生成这些分支文件，因此不用担心会删出问题：

$ git fetch --all --prune
Fetching origin
From gitlab.gz.cvte.cn:t/tech-app/dev/win/app/easinote
   a1fd2551f7..cfb662e870  next/release  -> origin/next/release
 * [new branch]            feature/ai    -> origin/feature/ai
   97d72dfc8f..ceb346c8e2  release       -> origin/release

WPF 不要给 Window 类设置变换矩阵（分析篇）：System.InvalidOperationException: 转换不可逆。

Mon, 02 Sep 2019 06:13:35 +0000

最近总是收到一个异常 “System.InvalidOperationException: 转换不可逆。”，然而看其堆栈，一点点自己写的代码都没有。到底哪里除了问题呢？

虽然异常堆栈信息里面没有自己编写的代码，但是我们还是找到了问题的原因和解决方法。

异常堆栈

这就是抓到的此问题的异常堆栈：

System.InvalidOperationException: 转换不可逆。
   在 System.Windows.Media.Matrix.Invert()
   在 MS.Internal.PointUtil.TryApplyVisualTransform(Point point, Visual v, Boolean inverse, Boolean throwOnError, Boolean& success)
   在 MS.Internal.PointUtil.TryClientToRoot(Point point, PresentationSource presentationSource, Boolean throwOnError, Boolean& success)
   在 System.Windows.Input.MouseDevice.LocalHitTest(Boolean clientUnits, Point pt, PresentationSource inputSource, IInputElement& enabledHit, IInputElement& originalHit)
   在 System.Windows.Input.MouseDevice.GlobalHitTest(Boolean clientUnits, Point pt, PresentationSource inputSource, IInputElement& enabledHit, IInputElement& originalHit)
   在 System.Windows.Input.StylusWisp.WispStylusDevice.FindTarget(PresentationSource inputSource, Point position)
   在 System.Windows.Input.StylusWisp.WispLogic.PreNotifyInput(Object sender, NotifyInputEventArgs e)
   在 System.Windows.Input.InputManager.ProcessStagingArea()
   在 System.Windows.Input.InputManager.ProcessInput(InputEventArgs input)
   在 System.Windows.Input.StylusWisp.WispLogic.InputManagerProcessInput(Object oInput)
   在 System.Windows.Threading.ExceptionWrapper.InternalRealCall(Delegate callback, Object args, Int32 numArgs)
   在 System.Windows.Threading.ExceptionWrapper.TryCatchWhen(Object source, Delegate callback, Object args, Int32 numArgs, Delegate catchHandler)

可以看到，我们的堆栈结束点是 ExceptionWrapper.TryCatchWhen 可以得知此异常是通过 Dispatcher.UnhandledException 来捕获的。也就是说，此异常直接通过 Windows 消息被我们间接触发，而不是直接通过我们编写的代码触发。而最顶端是对矩阵求逆，而此异常是试图对一个不可逆的矩阵求逆。

分析过程

如果你不想看分析过程，可以直接移步至本文的最后一节看原因和解决方案。

源代码

因为 .NET Framework 版本的 WPF 是开源的，.NET Core 版本的 WPF 目前还处于按揭开源的状态，所以我们看 .NET Framework 版本的代码来分析原因。

我按照调用堆栈从顶到底的顺序，将前面三帧的代码贴到下面。

`PointUtil.TryApplyVisualTransform`

public static Point TryApplyVisualTransform(Point point, Visual v, bool inverse, bool throwOnError, out bool success)
{
    success = true;

    if(v != null)
    {
        Matrix m = GetVisualTransform(v);

        if (inverse)
        {
            if(throwOnError || m.HasInverse)
            {
                m.Invert();
            }
            else
            {
                success = false;
                return new Point(0,0);
            }
        }

        point = m.Transform(point);
    }

    return point;
}

`PointUtil.TryClientToRoot`

[SecurityCritical,SecurityTreatAsSafe]
public static Point TryClientToRoot(Point point, PresentationSource presentationSource, bool throwOnError, out bool success)
{
    if (throwOnError || (presentationSource != null && presentationSource.CompositionTarget != null && !presentationSource.CompositionTarget.IsDisposed))
    {
        point = presentationSource.CompositionTarget.TransformFromDevice.Transform(point);
        point = TryApplyVisualTransform(point, presentationSource.RootVisual, true, throwOnError, out success);
    }
    else
    {
        success = false;
        return new Point(0,0);
    }

    return point;
}

你可能会说，在调用堆栈上面看不到 PointUtil.ClientToRoot 方法。但其实如果我们看一看 MouseDevice.LocalHitTest 的代码，会发现其实调用的是 PointUtil.ClientToRoot 方法。在调用堆栈上面看不到它是因为方法足够简单，被内联了。

[SecurityCritical,SecurityTreatAsSafe]
public static Point ClientToRoot(Point point, PresentationSource presentationSource)
{
    bool success = true;
    return TryClientToRoot(point, presentationSource, true, out success);
}

求逆的矩阵

下面我们一步一步分析异常的原因。

我们先看看是什么代码在做矩阵求逆。下面截图中的方法是反编译的，就是上面我们在源代码中列出的 TryApplyVisualTransform 方法。

先获取了传入 Visual 对象的变换矩阵，然后根据参数 inverse 来对其求逆。如果矩阵可以求逆，即 HasInverse 属性返回 true，那么代码可以继续执行下去而不会出现异常。但如果 HasInverse 返回 false，则根据 throwOnError 来决定是否抛出异常，在需要抛出异常的情况下会真实求逆，也就是上面截图中我们看到的异常发生处的代码。

那么接下来我们需要验证三点：

这个 Visual 是哪里来的；
这个 Visual 的变换矩阵什么情况下不可求逆；
throwOnError 确定传入的是 true 吗。

于是我们继续往上层调用代码中查看。

可以很快验证上面需要验证的两个点：

throwOnError 传入的是 true；
Visual 是 PresentationSource 的 RootVisual。

而 PresentationSource 的 RootVisual 是什么呢？PresentationSource 是承载 WPF 可视化树的一个对象，对于窗口 Window，是通过 HwndSource（PresentationSource 的子类）承载的；对于跨线程 WPF UI，可以通过自定义的 PresentationSource 子类来完成。这部分可以参考我之前的一些博客：

不管怎么说，这个指的就是 WPF 可视化树的根：

如果你使用 Window 来显示 WPF 窗口，那么根就是 Window 类；
如果你是用 Popup 来承载一个弹出框，那么根就是 PopupRoot 类；
如果你使用了一些跨线程/跨进程 UI 的技术，那么根就是自己写的可视化树根元素。

对于绝大多数 WPF 开发者来说，只会碰到前面第一种情况，也就是仅仅有 Window 作为可视化树的根的情况。一般人很难直接给 PopupRoot 设置变换矩阵，一般 WPF 程序的代码也很少做跨线程或跨进程 UI。

于是我们几乎可以肯定，是有某处的代码让 Window 的变换矩阵不可逆了。

矩阵求逆

什么样的矩阵是不可逆的？

异常代码

发生异常的代码是 WPF 中 Matrix.Invert 方法，其发生异常的代码如下：

首先判断矩阵的行列式 Determinant 是否为 0，如果为 0 则抛出矩阵不可逆的异常。

行列式

WPF 的 2D 变换矩阵 $M$ 是一个 $3\times{3}$ 的矩阵：

\[\begin{bmatrix} M11 & M12 & 0 \\ M21 & M22 & 0 \\ OffsetX & OffsetY & 1 \end{bmatrix}\]

其行列式 $det(M)$ 是一个标量：

\[\left | A \right | = \begin{vmatrix} M11 & M12 & 0 \\ M21 & M22 & 0 \\ OffsetX & OffsetY & 1 \end{vmatrix} = M11 \times M22 - M12 \times M21\]

因为矩阵求逆的时候，行列式的值会作为分母，于是会无法计算，所以行列式的值为 0 时，矩阵不可逆。

前面我们计算 WPF 的 2D 变换矩阵的行列式的值为 $M11 \times M22 - M12 \times M21$，因此，只要使这个式子的值为 0 即可。

那么 WPF 的 2D 变换的时候，如何使此值为 0 呢？

平移？平移只会修改 $OffsetX$ 和 $OffsetY$，因此对结果没有影响
缩放？缩放会将原矩阵点乘缩放矩阵
旋转？旋转会将旋转矩阵点乘原矩阵

其中，原矩阵在我们的场景下就是恒等的矩阵，即 Matrix.Identity：

\[\begin{bmatrix} 1 & 0 & 0 \\ 0 & 1 & 0 \\ 0 & 0 & 1 \end{bmatrix}\]

接下来缩放和旋转我们都不考虑变换中心的问题，因为变换中心的问题都可以等价为先进行缩放和旋转后，再单纯进行平移。由于平移对行列式的值没有影响，于是我们忽略。

缩放矩阵

缩放矩阵。如果水平和垂直分量分别缩放 $ScaleX$ 和 $ScaleY$ 倍，则缩放矩阵为：

\[\begin{bmatrix} ScaleX & 0 & 0 \\ 0 & ScaleY & 0 \\ 0 & 0 & 1 \end{bmatrix}\]

原矩阵点乘缩放矩阵结果为：

\[\begin{bmatrix} 1 & 0 & 0 \\ 0 & 1 & 0 \\ 0 & 0 & 1 \end{bmatrix} \cdot \begin{bmatrix} ScaleX & 0 & 0 \\ 0 & ScaleY & 0 \\ 0 & 0 & 1 \end{bmatrix} = \begin{bmatrix} ScaleX & 0 & 0 \\ 0 & ScaleY & 0 \\ 0 & 0 & 1 \end{bmatrix}\]

于是，只要 $ScaleX$ 和 $ScaleY$ 任何一个为 0 就可以导致新矩阵的行列式必定为 0。

旋转矩阵

旋转矩阵。假设用户设置的旋转角度为 angle，那么换算成弧度为 angle * (Math.PI/180.0)，我们将弧度记为 $\alpha$，那么旋转矩阵为：

\[\begin{bmatrix} \cos{\alpha} & \sin{\alpha} & 0 \\ -\sin{\alpha} & \cos{\alpha} & 0 \\ 0 & 0 & 1 \end{bmatrix}\]

旋转矩阵点乘原矩阵的结果为：

\[\begin{bmatrix} \cos{\alpha} & \sin{\alpha} & 0 \\ -\sin{\alpha} & \cos{\alpha} & 0 \\ 0 & 0 & 1 \end{bmatrix} \cdot \begin{bmatrix} 1 & 0 & 0 \\ 0 & 1 & 0 \\ 0 & 0 & 1 \end{bmatrix} = \begin{bmatrix} \cos{\alpha} & \sin{\alpha} & 0 \\ -\sin{\alpha} & \cos{\alpha} & 0 \\ 0 & 0 & 1 \end{bmatrix}\]

对此矩阵的行列式求值：

\[\cos^{2}{\alpha} + \sin^{2}{\alpha} = 1\]

也就是说其行列式的值恒等于 1，因此其矩阵必然可求逆。

WPF 2D 变换矩阵求逆小结

对于 WPF 的 2D 变换矩阵：

平移和旋转不可能导致矩阵不可逆；
缩放，只要水平和垂直方向的任何一个分量缩放量为 0，矩阵就会不可逆。

寻找问题代码

现在，我们寻找问题的方向已经非常明确了：

找到设置了 ScaleTransform 的 Window，检查其是否给 ScaleX 或者 ScaleY 属性赋值为了 0。

然而，真正写一个 demo 程序来验证这个问题的时候，就发现没有这么简单。因为：

我们发现，不止是 ScaleX 和 ScaleY 属性不能设为 0，实际上设成 0.5 或者其他值也是不行的。

唯一合理值是 1。

那么为什么依然有异常呢？难道是 ScaleTransform 的值一开始正常，然后被修改？

编写 demo 验证，果然如此。而只有变换到 0 才会真的引发本文一开始我们提到的异常。一般会开始设为 1 而后设为 0 的代码通常是在做动画。

一定是有代码正在为窗口的 ScaleTransform 做动画。

结果全代码仓库搜索 ScaleTransform 真的找到了问题代码。

<Window x:Name="WalterlvDoubiWindow"
        x:Class="Walterlv.Exceptions.Unknown.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        mc:Ignorable="d"
        Title="MainWindow" Height="450" Width="800">
    <Window.RenderTransform>
        <ScaleTransform ScaleX="1" ScaleY="1" />
    </Window.RenderTransform>
    <Window.Resources>
        <Storyboard x:Key="Storyboard.Load">
            <DoubleAnimation Storyboard.TargetName="WalterlvDoubiWindow"
                             Storyboard.TargetProperty="(UIElement.RenderTransform).(ScaleTransform.ScaleX)"
                             From="0" To="1" />
            <DoubleAnimation Storyboard.TargetName="WalterlvDoubiWindow"
                             Storyboard.TargetProperty="(UIElement.RenderTransform).(ScaleTransform.ScaleY)"
                             From="0" To="1" />
        </Storyboard>
    </Window.Resources>
    <Grid>
        <!-- 省略的代码 -->
    </Grid>
</Window>

不过，这段代码并不会导致每次都出现异常，而是在非常多次尝试中偶尔能出现一次异常。

原因和解决方案

原因

Window 类是不可以设置 RenderTransform 属性的，但允许设置恒等（Matrix.Identity）的变换；
如果让 Window 类缩放分量设置为 0，就会出现矩阵不可逆异常。

解决方案

不要给 Window 类设置变换，如果要做，请给 Window 内部的子元素设置。比如上面的例子中，我们给 Grid 设置就没有问题（而且可以做到类似的效果。

WPF 不要给 Window 类设置变换矩阵（应用篇）

Mon, 02 Sep 2019 04:34:25 +0000

WPF 的 Window 类是不允许设置变换矩阵的。不过，总会有小伙伴为了能够设置一下试图绕过一些验证机制。

不要试图绕过，因为你会遇到更多问题。

试图设置变换矩阵

当你试图给 Window 类设置变换矩阵的时候，会出现异常：

System.InvalidOperationException:“转换对于 Window 无效。”

无论是缩放还是旋转，都一样会出现异常。

我们在 WPF 不要给 Window 类设置变换矩阵（分析篇）一文中已经证明在 WPF 的 2D 变换中，旋转一定不会造成矩阵不可逆，因此此验证是针对此属性的强验证。

只有做设置的变换是恒等变换的时候，才可以完成设置。

this.RenderTransform = new TranslateTransform(0, 0);
this.RenderTransform = new ScaleTransform(1, 1);
this.RenderTransform = new RotateTransform(0);
this.RenderTransform = new MatrixTransform(Matrix.Identity);

绕过验证

然而你可以通过先设置变换，再修改变换值的方式绕过验证：

var scaleTransform = new ScaleTransform(1, 1);
this.RenderTransform = scaleTransform;
scaleTransform.ScaleX = 0.5;
scaleTransform.ScaleY = 0.5;

实际上，你绕过也没有关系，可是这样的设置实际上是没有任何效果的。

不过为什么还是会有小伙伴这么设置呢？

是因为小伙伴同时还设置了窗口透明 AllowsTransparency="True"、WindowStyle="None" 和 Background="Transparent"，导致看起来好像这个变换生效了一样。

小心异常

此设置不仅没有效果，还会引发异常，请阅读我的另一篇博客了解：

WPF 不要给 Window 类设置变换矩阵（分析篇）：System.InvalidOperationException: 转换不可逆。

通过设置启用 Visual Studio 默认关闭的大量强大的功能提升开发效率

Thu, 29 Aug 2019 13:54:47 +0000

使用 Visual Studio 开发 C#/.NET 应用程序，以前有 ReSharper 来不足其各项功能短板，后来不断将 ReSharper 的功能一点点搬过来稍微好了一些。不过直到 Visual Studio 2019，才开始渐渐可以和 ReSharper 拼一下了。

如果你使用 Visual Studio 2019，那么像本文这样配置一下，可以大大提升你的开发效率。

工具选项

打开菜单 “工具” -> “选项”，然后你就打开了 Visual Studio 的选项窗口。接下来本文的所有内容都会在这里进行。

文本编辑器

在 “文本编辑器” -> “常规” 分类中，我们关心这些设置：

使鼠标单击可执行转到定义 这样按住 Ctrl 键点击标识符的时候可以转到定义（开启此选项之后，后面有其他选项可以转到反编译后的源码）

当然也有其他可以打开玩的：

查看空白 专治强迫症，可以把空白字符都显示出来，这样你可以轻易看到对齐问题以及多于的空格了

C#

在 “文本编辑器” -> “C#” -> “IntelliSense” 分类中，我们关心这些设置：

键入字符后显示完成列表 删除字符后显示完成列表 突出显示完成列表项的匹配部分 显示完成项筛选器 打开这些选项可以让智能感知列表更容易显示出来，而我们也知道智能感知列表的强大
推荐 显示 unimported 命名空间中的项(实验) 这一项默认不会勾选，但强烈建议勾选上；它可以帮助我们直接输入没有 using 的命名空间中的类型，这可以避免记住大量记不住的类名

C# 高级

在 “文本编辑器” -> “C#” -> “高级” 分类中，我们关心大量设置：

支持导航到反编译源(实验) 前面我们说可以 Ctrl + 鼠标导航到定义，如果打开了这个就可以看反编译后的源码了
启用可为 null 的引用分析 IDE 功能 这个功能可能还没有完成，暂时还是无法开启的

当然也有其他可以打开玩的：

启用完成解决方案分析 这是基于 Roslyn 的分析，Visual Studio 的大量重构功能都依赖于它；默认关闭也可以用，只是仅分析当前正在编辑的文件；如果打开则分析整个解决方案，你会在错误列表中看到大量的编译警告

代码样式

在 “文本编辑器” -> “C#” -> “代码样式” 分类，如果你关心代码的书写风格，那么这个分类底下的每一个子类别都可以考虑一个个检查一下。

人工智能 IntelliCode

Visual Studio 2019 默认安装了 IntelliCode 可以充分利用微软使用 GitHub 上开源项目训练出来的模型来帮助编写代码。这些强烈建议开启。

C# 基础模型 微软利用 GitHub 开源项目训练的基础模型
XAML 基础模型 微软利用 GitHub 开源项目训练的基础模型
C# 参数完成
C# 自定义模型 如果针对单个项目训练出来了模型，那么可以使用专门针对此项目训练的模型
EditorConfig 推理 可以根据项目推断生成 EditorConfig 文件 可以参见在 Visual Studio 中使用 EditorConfig 统一代码风格
自定义模型训练提示 如果开启，那么每个项目的规模如果达到一定程度就会提示训练一个自定义模型出来

训练模型会上传一部分数据到 IntelliCode 服务器，你可以去 %TEMP%\Visual Studio IntelliCode 目录来查看到底上传了哪些数据。

快捷键

当然，设置好快捷键也是高效编码的重要一步，可以参考：

自动完成

在你点击 “确定” 关闭了以上窗口之后，我们还需要设置一项。

确保下图中的这个按钮处于 “非选中” 状态：

这样，当出现智能感知列表的时候，我们直接就可以按下回车键输入这个选项了；否则你还需要按上下选中再回车。

C#/.NET 中 Thread.Sleep(0), Task.Delay(0), Thread.Yield(), Task.Yield() 不同的执行效果和用法建议

Thu, 29 Aug 2019 08:34:41 +0000

在 C#/.NET 中，有 Thread.Sleep(0), Task.Delay(0), Thread.Yield(), Task.Yield() 中，有几种不同的让当前线程释放执行权的方法。他们的作用都是放弃当前线程当前的执行权，让其他线程得以调度。但是他们又不太一样。

本文说说他们的原理区别和用法区别。

原理区别

Thread.Sleep(0)

Thread.Sleep(int millisecondsTimeout) 的代码贴在下面，其内部实际上是在调用 SleepInternal，而 SleepInternal 由 CLR 内部实现。其目的是将当前线程挂起一个指定的时间间隔。

如果将超时时间设置为 0，即 Thread.Sleep(0)，那么这将强制当前线程放弃剩余的 CPU 时间片。

放弃当前线程剩余的 CPU 时间片就意味着其他比此线程优先级高且可以被调度的线程将会在此时被调度。然而此方法只是放弃当前 CPU 执行的时间片，如果当前系统环境下其他可以被调度的其他线程的优先级都比这个线程的优先级低，实际上此线程依然还是会优先执行。

如果你的方法不会被其他线程影响，那么不会有执行上的区别，但如果你的方法涉及到多个线程的调用，那么 Thread.Sleep(0) 的调用可能导致其他线程也进入此方法（而不是等此线程的当前时间片执行完后再进入）。当然，CPU 对单个线程的执行时间片是纳秒级别的，所以实际上你因为此方法调用获得的多线程重入效果是“纯属巧合”的。

/*=========================================================================
** Suspends the current thread for timeout milliseconds. If timeout == 0,
** forces the thread to give up the remainer of its timeslice.  If timeout
** == Timeout.Infinite, no timeout will occur.
**
** Exceptions: ArgumentException if timeout < 0.
**             ThreadInterruptedException if the thread is interrupted while sleeping.
=========================================================================*/
[System.Security.SecurityCritical]  // auto-generated
[ResourceExposure(ResourceScope.None)]
[MethodImplAttribute(MethodImplOptions.InternalCall)]
private static extern void SleepInternal(int millisecondsTimeout);

[System.Security.SecuritySafeCritical]  // auto-generated
public static void Sleep(int millisecondsTimeout)
{
    SleepInternal(millisecondsTimeout);
    // Ensure we don't return to app code when the pause is underway
    if(AppDomainPauseManager.IsPaused)
        AppDomainPauseManager.ResumeEvent.WaitOneWithoutFAS();
}

Thread.Yield()

Thread.Yield() 的代码贴在下面，其内部调用 YieldInternal，实际上也是由 CLR 内部实现。

此方法也是放弃当前线程的剩余时间片，所以其效果与 Thread.Sleep(0) 是相同的。

[System.Security.SecurityCritical]  // auto-generated
[ResourceExposure(ResourceScope.None)]
[DllImport(JitHelpers.QCall, CharSet = CharSet.Unicode)]
[SuppressUnmanagedCodeSecurity]
[HostProtection(Synchronization = true, ExternalThreading = true),
    ReliabilityContract(Consistency.WillNotCorruptState, Cer.Success)]
private static extern bool YieldInternal();

[System.Security.SecuritySafeCritical]  // auto-generated
[HostProtection(Synchronization = true, ExternalThreading = true),
    ReliabilityContract(Consistency.WillNotCorruptState, Cer.Success)]
public static bool Yield()
{
    return YieldInternal();
}

Thread.Sleep(1)

Thread.Sleep(1) 与 Thread.Sleep(0) 虽然只有参数上的微小差别，但实际上做了不同的事情。

Thread.Sleep(1) 会使得当前线程挂起一个指定的超时时间，这里设置为 1ms。于是，在这个等待的超时时间段内，你的当前线程处于不可被调度的状态。那么即便当前剩余的可以被调度的线程其优先级比这个更低，也可以得到调度。

下面是针对这三个方法执行时间的一个实验结果：

▲ Thread 不同方法的耗时实验结果

其中，Nothing 表示没有写任何代码。

测量使用的是 Stopwatch，你可以通过阅读 .NET/C# 在代码中测量代码执行耗时的建议（比较系统性能计数器和系统时间）了解 Stopwatch 测量的原理和精度。

var stopwatch = Stopwatch.StartNew();
Thread.Sleep(0);
var elapsed = stopwatch.Elapsed;
Console.WriteLine($"Thread.Sleep(0) : {elapsed}");

Task.Delay(0)

Task.Delay 是 Task 系列的线程模型（TAP）中的方法。关于 TAP 可参见 Task-based Asynchronous Pattern (TAP) Microsoft Docs。

这是一套基于异步状态机（AsyncStateMachine）实现的线程模型，这也是与 Thread 系列方法最大的不同。

当传入参数 0 的时候，会直接返回 Task.CompletedTask。这意味着你在 Task.Delay(0) 后面写的代码会被立刻调用（如果还有剩余 CPU 时间片的话）。

/// <summary>
/// Creates a Task that will complete after a time delay.
/// </summary>
/// <param name="millisecondsDelay">The number of milliseconds to wait before completing the returned Task</param>
/// <param name="cancellationToken">The cancellation token that will be checked prior to completing the returned Task</param>
/// <returns>A Task that represents the time delay</returns>
/// <exception cref="T:System.ArgumentOutOfRangeException">
/// The <paramref name="millisecondsDelay"/> is less than -1.
/// </exception>
/// <exception cref="T:System.ObjectDisposedException">
/// The provided <paramref name="cancellationToken"/> has already been disposed.
/// </exception>        
/// <remarks>
/// If the cancellation token is signaled before the specified time delay, then the Task is completed in
/// Canceled state.  Otherwise, the Task is completed in RanToCompletion state once the specified time
/// delay has expired.
/// </remarks>        
public static Task Delay(int millisecondsDelay, CancellationToken cancellationToken)
{
    // Throw on non-sensical time
    if (millisecondsDelay < -1)
    {
        throw new ArgumentOutOfRangeException("millisecondsDelay", Environment.GetResourceString("Task_Delay_InvalidMillisecondsDelay"));
    }
    Contract.EndContractBlock();

    // some short-cuts in case quick completion is in order
    if (cancellationToken.IsCancellationRequested)
    {
        // return a Task created as already-Canceled
        return Task.FromCancellation(cancellationToken);
    }
    else if (millisecondsDelay == 0)
    {
        // return a Task created as already-RanToCompletion
        return Task.CompletedTask;
    }

    // Construct a promise-style Task to encapsulate our return value
    var promise = new DelayPromise(cancellationToken);

    // Register our cancellation token, if necessary.
    if (cancellationToken.CanBeCanceled)
    {
        promise.Registration = cancellationToken.InternalRegisterWithoutEC(state => ((DelayPromise)state).Complete(), promise);
    }

    // ... and create our timer and make sure that it stays rooted.
    if (millisecondsDelay != Timeout.Infinite) // no need to create the timer if it's an infinite timeout
    {
        promise.Timer = new Timer(state => ((DelayPromise)state).Complete(), promise, millisecondsDelay, Timeout.Infinite);
        promise.Timer.KeepRootedWhileScheduled();
    }

    // Return the timer proxy task
    return promise;
}

Task.Yield()

Task.Yield() 的最大作用实际上是让一个异步方法立刻返回，让后面其他代码的调用进入下一个异步上下文。

public async Task Foo()
{
    // 执行某些操作。
    await Task.Yield();
    // 执行另一些操作。
}

如果外面的代码使用 await 来等待 Foo，那么 Task.Yield 的作用可能不太明显，但是如果外面并没有 await 或者任何一层更外层的调用没有 await，那么就有区别了。对于没有异步等待的调用，那个方法就会在此 Task.Yield() 这一句执行后返回。而此后的代码将在那些没有异步等待的方法之后执行。

Task.Yield() 实际上只是返回一个 YieldAwaitable 的新实例，而 YieldAwaitable.GetAwaiter 方法返回一个 YieldAwaiter 的新实例。也就是说，后续的执行效果完全取决于 YieldAwaiter 是如何实现这个异步过程的（异步状态机会执行这个过程）。我有另一篇博客说明 Awaiter 是如何实现的：如何实现一个可以用 await 异步等待的 Awaiter。

YieldAwaiter 靠 QueueContinuation 来决定后续代码的执行时机。此方法的核心代码贴在了下面。

有两个分支，如果指定了 SynchronizationContext，那么就会使用 SynchronizationContext 自带的 Post 方法来执行异步任务的下一个步骤。调用 continuation 就是执行异步状态机中的下一个步骤以进入下一个异步状态；不过，为了简化理解，你可以认为这就是调用 await 后面的那段代码。

WPF UI 线程的 SynchronizationContext 被设置为了 DispatcherSynchronizationContext，它的 Post 方法本质上是用消息循环来实现的。其他线程如果没有特殊设置，则是 null。这一部分知识可以看参见：出让执行权：Task.Yield, Dispatcher.Yield。

如果没有指定 SynchronizationContext 或者当前的 SynchronizationContext 就是 SynchronizationContext 类型基类，那么就会执行后面 else 中的逻辑。主要就是在线程池中寻找一个线程然后执行代码，或者再次启动一个 Task 任务并加入队列；这取决于 TaskScheduler.Current 的设置。

// Get the current SynchronizationContext, and if there is one,
// post the continuation to it.  However, treat the base type
// as if there wasn't a SynchronizationContext, since that's what it
// logically represents.
var syncCtx = SynchronizationContext.CurrentNoFlow;
if (syncCtx != null && syncCtx.GetType() != typeof(SynchronizationContext))
{
    syncCtx.Post(s_sendOrPostCallbackRunAction, continuation);
}
else
{
    // If we're targeting the default scheduler, queue to the thread pool, so that we go into the global
    // queue.  As we're going into the global queue, we might as well use QUWI, which for the global queue is
    // just a tad faster than task, due to a smaller object getting allocated and less work on the execution path.
    TaskScheduler scheduler = TaskScheduler.Current;
    if (scheduler == TaskScheduler.Default)
    {
        if (flowContext)
        {
            ThreadPool.QueueUserWorkItem(s_waitCallbackRunAction, continuation);
        }
        else
        {
            ThreadPool.UnsafeQueueUserWorkItem(s_waitCallbackRunAction, continuation);
        }
    }
    // We're targeting a custom scheduler, so queue a task.
    else
    {
        Task.Factory.StartNew(continuation, default(CancellationToken), TaskCreationOptions.PreferFairness, scheduler);
    }
}

Task.Delay(1)

与 Thread 一样，Task.Delay(1) 与 Task.Delay(0) 虽然只有参数上的微小差别，但实际上也做了不同的事情。

Task.Delay(1) 实际上是启动了一个 System.Threading.Timer，然后订阅时间抵达之后的回调函数。

会从 Timer.TimerSetup 设置，到使用 TimerHolder 并在内部使用 TimerQueueTimer 来设置回调；内部实际使用 TimerQueue.UpdateTimer 来完成时间等待之后的回调通知，最终通过 EnsureAppDomainTimerFiresBy 调用到 ChangeAppDomainTimer 来完成时间抵达之后的回调。

而 await 之后的那段代码会被异步状态机封装，传入上面的回调中。

[System.Security.SecurityCritical]
[ResourceExposure(ResourceScope.None)]
[DllImport(JitHelpers.QCall, CharSet = CharSet.Unicode)]
[SuppressUnmanagedCodeSecurity]
static extern bool ChangeAppDomainTimer(AppDomainTimerSafeHandle handle, uint dueTime);

相比于 Thread 相关方法仅涉及到当前线程的调度，Task 相关的方法会涉及到线程池的调度，并且使用 System.Threading.Timer 来进行计时，耗时更加不可控：

▲ Task 不同方法的耗时实验结果（三次不同的实验结果）

其中，Nothing 表示没有写任何代码。

测量使用的是 Stopwatch，你依然可以通过阅读 .NET/C# 在代码中测量代码执行耗时的建议（比较系统性能计数器和系统时间）了解 Stopwatch 测量的原理和精度。

var stopwatch = Stopwatch.StartNew();
await Task.Delay(0);
var elapsed = stopwatch.Elapsed;
Console.WriteLine($"Thread.Sleep(0) : {elapsed}");

在 [c# - Task.Delay().Wait(); sometimes causing a 15ms delay in messaging system - Stack Overflow](https://stackoverflow.com/q/41830216/6233938) 上有个说法，说操作系统的时钟中断有时间间隔，而 Windows 操作系统上这个时间间隔的默认值大约在 15ms，所以实际上你写等待 1ms，实际等待时间也会接近 15ms。

You’re seeing an artifact of the Windows interrupt rate, which is (by default) approx every 15ms. Thus if you ask for 1-15ms, you’ll get an approx 15ms delay. ~16-30 will yield 30ms… so on.

用法区别

Thread.Sleep(0) 和 Thread.Yield 在线程调度的效果上是相同的，Thread.Sleep(int) 是带有超时的等待，本质上也是线程调度。如果你希望通过放弃当前线程时间片以便给其他线程一些执行实际，那么考虑 Thread.Sleep(0) 或者 Thread.Yield；如果希望进行线程调度级别的等待（效果类似于阻塞线程），那么使用 Thread.Sleep(int)。

如果你允许有一个异步上下文，可以使用 async/await，那么可以使用 Task.Delay(0) 或者 Task.Yield()。另外，如果等待时使用 Task.Delay 而不是 Thread.Sleep，那么你可以节省一个线程的资源，尤其是在一个线程池的线程中 Sleep 的话，会使得线程池中更多的线程被进行无意义的占用，对其他任务在线程池中的调度不利。

参考资料

Thread.Sleep(0) vs Sleep(1) vs Yeild - stg609 - 博客园
[c# - Task.Delay().Wait(); sometimes causing a 15ms delay in messaging system - Stack Overflow](https://stackoverflow.com/q/41830216/6233938)
c# - When to use Task.Delay, when to use Thread.Sleep? - Stack Overflow
c# - Should I always use Task.Delay instead of Thread.Sleep? - Stack Overflow
What’s the difference between Thread.Sleep(0) and Thread,Yield()?

WPF 的 Application.Current.Dispatcher 中，为什么 Current 可能为 null

Tue, 27 Aug 2019 05:05:49 +0000

在 WPF 程序中，可能会存在 Application.Current.Dispatcher.Xxx 这样的代码让一部分逻辑回到主 UI 线程。因为发现在调用这句代码的时候出现了 NullReferenceException，于是就有三位小伙伴告诉我说 Current 和 Dispatcher 属性都可能为 null。

然而实际上这里只可能 Current 为 null 而此上下文的 Dispatcher 是绝对不会为 null 的。（当然我们这里讨论的是常规编程手段，如果非常规手段，你甚至可以让实例的 this 为 null 呢……）

当你的应用程序退出时，所有 UI 线程的代码都不再会执行，因此这是安全的；但所有非 UI 线程的代码依然在继续执行，此时随时可能遇到 Application.Current 属性为 null。

由于本文所述的两个部分都略长，所以拆分成两篇博客，这样更容易理解。

`Application.Current` 静态属性

源代码

Application 类型的源代码会非常长，所以这里就不贴了，可以前往这里查看：

DispatcherObject.cs

其中，Current 返回的是 _appInstance 的静态字段。因此 _appInstance 字段为 null 的时机就是 Application.Current 为 null 的时机。

/// <summary>
///     The Current property enables the developer to always get to the application in
///     AppDomain in which they are running.
/// </summary>
static public Application Current
{
    get
    {
        // There is no need to take the _globalLock because reading a
        // reference is an atomic operation. Moreover taking a lock
        // also causes risk of re-entrancy because it pumps messages.

        return _appInstance;
    }
}

由于 _appInstance 字段是私有字段，所以仅需调查这个类本身即可找到所有的赋值时机。（反射等非常规手段需要排除在外，因为这意味着开发者是逗比——自己闯的祸不能怪 WPF 框架。）

赋值时机

_appInstance 的赋值时机有两处：

Application 的实例构造函数（注意哦，是实例构造函数而不是静态构造函数）；
Application.DoShutdown 方法。

在 Application 的实例构造函数中：

_appInstance 的赋值是线程安全的，这意味着多个 Application 实例的构造不会因为线程安全问题导致 _appInstance 字段的状态不正确。
如果 _appCreatedInThisAppDomain 为 true 那么，将抛出异常，组织此应用程序域中创建第二个 Application 类型的实例。

/// <summary>
///     Application constructor
/// </summary>
/// <SecurityNote>
///    Critical: This code posts a work item to start dispatcher if in the browser
///    PublicOk: It is ok because the call itself is not exposed and the application object does this internally.
/// </SecurityNote>
[SecurityCritical]
public Application()
{
    // 省略了一部分代码。
    lock(_globalLock)
    {
        // set the default statics
        // DO NOT move this from the begining of this constructor
        if (_appCreatedInThisAppDomain == false)
        {
            Debug.Assert(_appInstance == null, "_appInstance must be null here.");
            _appInstance = this;
            IsShuttingDown    = false;
            _appCreatedInThisAppDomain = true;
        }
        else
        {
            //lock will be released, so no worries about throwing an exception inside the lock
            throw new InvalidOperationException(SR.Get(SRID.MultiSingleton));
        }
    }
    // 省略了一部分代码。
}

也就是说，此类型实际上是设计为单例的。在第一个实例构造出来之后，单例的实例即可开始使用。

后续赋值

此单例实例的唯一结束时机就是 Application.DoShutdown 方法。这是唯一将 _appInstance 赋值为 null 的代码。

/// <summary>
/// DO NOT USE - internal method
/// </summary>
///<SecurityNote>
///     Critical: Calls critical code: Window.InternalClose
///     Critical: Calls critical code: HwndSource.Dispose
///     Critical: Calls critical code: PreloadedPackages.Clear()
///</SecurityNote>
[SecurityCritical]
internal virtual void DoShutdown()
{
    // 省略了一部分代码。

    // Event handler exception continuality: if exception occurs in ShuttingDown event handler,
    // our cleanup action is to finish Shuttingdown.  Since Shuttingdown cannot be cancelled.
    // We don't want user to use throw exception and catch it to cancel Shuttingdown.
    try
    {
        // fire Applicaiton Exit event
        OnExit(e);
    }
    finally
    {
        SetExitCode(e._exitCode);

        // By default statics are shared across appdomains, so need to clear
        lock (_globalLock)
        {
            _appInstance = null;
        }

        _mainWindow = null;
        _htProps = null;
        NonAppWindowsInternal = null;

        // 省略了一部分代码。
    }
}

可以调用到此代码的公共 API 有：

Application.Shutdown 实例方法
导致 Window 关闭的若干方法（InternalDispose）
IBrowserHostServices.PostShutdown 接口方法

因此，所有直接或间接调用到以上方法的地方都会导致 Application.Current 属性被赋值为 null。

对所写代码的影响

从以上的分析可以得知，只要你还能在 Application.DoShutdown 执行之后继续执行代码，那么这部分的代码都将面临着 Application.Current 为 null 风险。

那么，到底有哪些时机可能遇到 Application.Current 为 null 呢？这部分就与读者项目中所用的业务代码强相关了。

但是这部分业务代码会有一些公共特征帮助你判定你是否可能写出遭遇 Application.Current 为 null 的代码。

此特征是：此代码与 Application.Current 不在同一线程。

与 `Application.Current` 不在同一线程

对于 WPF 程序，你的多数代码可能是由用户交互产生，即便有后续代码的执行，也依然是从 UI 交互产生。这样的代码不会遇到 Application.Current 为 null 的情况。

但是，如果你的代码由非 UI 线程触发，例如在 Usb 设备改变、与其他端的通信、某些异步代码的回调等等，这些代码不受 Dispatcher 是否调度影响，几乎一定会执行。因此 Application.Current 就算赋值为 null 了，它们也不知道，依然会继续执行，于是就会遭遇 Application.Current 为 null。

这本质上是一个线程安全问题。

使用 `Invoke/BeginInvoke/InvokeAsync` 的代码不会出问题

Application.DoShutdown 方法被 ShutdownImpl 包装，且所有调用均从此包装进入，因此，所有可能导致 Application.Current 为 null 的代码，均会调用此方法，也就是说，会调用 Dispatcher.CriticalInvokeShutdown 实例方法。

/// <summary>
/// This method gets called on dispatch of the Shutdown DispatcherOperationCallback
/// </summary>
///<SecurityNote>
///  Critical: Calls critical code: DoShutdown, Dispatcher.CritcalInvokeShutdown()
///</SecurityNote>
[SecurityCritical]
private void ShutdownImpl()
{
    // Event handler exception continuality: if exception occurs in Exit event handler,
    // our cleanup action is to finish Shutdown since Exit cannot be cancelled. We don't
    // want user to use throw exception and catch it to cancel Shutdown.
    try
    {
        DoShutdown();
    }
    finally
    {
        // Quit the dispatcher if we ran our own.
        if (_ownDispatcherStarted == true)
        {
            Dispatcher.CriticalInvokeShutdown();
        }

        ServiceProvider = null;
    }
}

所有的关闭 Dispatcher 的调用有两类，Application 关闭时调用的是内部方法 CriticalInvokeShutdown。

立即关闭 CriticalInvokeShutdown，即以 Send 优先级 Invoke 关闭方法，而 Send 优先级调用 Invoke 几乎等同于直接调用（为什么是等同而不是直接调用？因为还需要考虑回到 Dispatcher 初始化时所在的线程）。
开始关闭 BeginInvokeShutdown，即以指定的优先级 InvokeAsync 关闭方法。

而关闭 Dispatcher 意味着所有使用 Invoke/BeginInvoke/InvokeAsync 的任务将终止。

//<SecurityNote>
//  Critical - as it accesses security critical data ( window handle)
//</SecurityNote>
[SecurityCritical]
private void ShutdownImplInSecurityContext(Object state)
{
    // 省略了一部分代码。

    // Now that the queue is off-line, abort all pending operations,
    // including inactive ones.
    DispatcherOperation operation = null;
    do
    {
        lock(_instanceLock)
        {
            if(_queue.MaxPriority != DispatcherPriority.Invalid)
            {
                operation = _queue.Peek();
            }
            else
            {
                operation = null;
            }
        }

        if(operation != null)
        {
            operation.Abort();
        }
    } while(operation != null);

    // 省略了一部分代码。
}

由于此终止代码在 Dispatcher 所在的线程执行，而所有 Invoke/BeginInvoke/InvokeAsync 代码也都在此线程执行，因此这些代码均不会并发。已经执行的代码会在此终止代码之前，而在此终止代码之后也不会再执行任何 Invoke/BeginInvoke/InvokeAsync 的任务了。

所有通过 Invoke/BeginInvoke/InvokeAsync 或间接通过此方法（如 WPF 控件相关事件）调用的代码，均不会遭遇 Application.Current 为 null。
所有在 UI 线程使用 async / await 并使用默认上下文执行的代码，均不会遭遇 Application.Current 为 null。（这意味着你没有使用 .ConfigureAwait(false)，详见在编写异步方法时，使用 ConfigureAwait(false) 避免使用者死锁 - walterlv。）

最简示例代码

using System;
using System.Threading;
using System.Threading.Tasks;
using System.Windows;

namespace Walterlv.Demo.ApplicationDispatcher
{
    class Program
    {
        [STAThread]
        static void Main(string[] args)
        {
            var app = new Application();
            Task.Delay(1000).ContinueWith(t =>
            {
                app.Dispatcher.InvokeAsync(() => app.Shutdown());
            });
            Task.Delay(2000).ContinueWith(t =>
            {
                Application.Current.Dispatcher.InvokeAsync(() => { });
            });
            app.Run();
            Thread.Sleep(2000);
        }
    }
}

结论

总结以上所有的分析：

任何与 Application 不在同一个线程的代码，都可能遭遇 Application.Current 为 null。
任何与 Application 在同一个线程的代码，都不可能遇到 Application.Current 为 null。

这其实是一个线程安全问题。用所有业务开发者都可以理解的说法描述就是：

因此，记得所有非 UI 线程的代码，如果需要转移到 UI 线程执行，记得判空：

private void OnUsbDeviceChanged(object sender, EventArgs e)
{
    // 记得这里需要判空，因为此上下文可能在非 UI 线程。
    Application.Current?.InvokeAsync(() => { });
}

`Application.Dispatcher` 实例属性

关于 Application.Dispatcher 是否可能为 null 的分析，由于比较长，请参见我的另一篇博客：

WPF 的 Application.Current.Dispatcher 中，Dispatcher 属性一定不会为 null - walterlv

参考资料

Application.cs

WPF 的 Application.Current.Dispatcher 中，Dispatcher 属性一定不会为 null

Tue, 27 Aug 2019 04:51:43 +0000

由于本文所述的两个部分都略长，所以拆分成两篇博客，这样更容易理解。

`Application.Dispatcher` 实例属性

Application.Dispatcher 实例属性来自于 DispatcherObject。

源代码

为了分析此属性是否可能为 null，我现在将 DispatcherObject 的全部代码贴在下面：

using System;
using System.Windows;
using System.Threading;
using MS.Internal.WindowsBase;               // FriendAccessAllowed
 
namespace System.Windows.Threading
{
    /// <summary>
    ///     A DispatcherObject is an object associated with a
    ///     <see cref="Dispatcher"/>.  A DispatcherObject instance should
    ///     only be access by the dispatcher's thread.
    /// </summary>
    /// <remarks>
    ///     Subclasses of <see cref="DispatcherObject"/> should enforce thread
    ///     safety by calling <see cref="VerifyAccess"/> on all their public
    ///     methods to ensure the calling thread is the appropriate thread.
    ///     <para/>
    ///     DispatcherObject cannot be independently instantiated; that is,
    ///     all constructors are protected.
    /// </remarks>
    public abstract class DispatcherObject
    {
        /// <summary>
        ///     Returns the <see cref="Dispatcher"/> that this
        ///     <see cref="DispatcherObject"/> is associated with.
        /// </summary>
        [System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Advanced)]
        public Dispatcher Dispatcher
        {
            get
            {
                // This property is free-threaded.
 
                return _dispatcher;
            }
        }
 
        // This method allows certain derived classes to break the dispatcher affinity
        // of our objects.
        [FriendAccessAllowed] // Built into Base, also used by Framework.
        internal void DetachFromDispatcher()
        {
            _dispatcher = null;
        }
 
        // Make this object a "sentinel" - it can be used in equality tests, but should
        // not be used in any other way.  To enforce this and catch bugs, use a special
        // sentinel dispatcher, so that calls to CheckAccess and VerifyAccess will
        // fail;  this will catch most accidental uses of the sentinel.
        [FriendAccessAllowed] // Built into Base, also used by Framework.
        internal void MakeSentinel()
        {
            _dispatcher = EnsureSentinelDispatcher();
        }
 
        private static Dispatcher EnsureSentinelDispatcher()
        {
            if (_sentinelDispatcher == null)
            {
                // lazy creation - the first thread reaching here creates the sentinel
                // dispatcher, all other threads use it.
                Dispatcher sentinelDispatcher = new Dispatcher(isSentinel:true);
                Interlocked.CompareExchange<Dispatcher>(ref _sentinelDispatcher, sentinelDispatcher, null);
            }
 
            return _sentinelDispatcher;
        }
 
        /// <summary>
        ///     Checks that the calling thread has access to this object.
        /// </summary>
        /// <remarks>
        ///     Only the dispatcher thread may access DispatcherObjects.
        ///     <p/>
        ///     This method is public so that any thread can probe to
        ///     see if it has access to the DispatcherObject.
        /// </remarks>
        /// <returns>
        ///     True if the calling thread has access to this object.
        /// </returns>
        [System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)]
        public bool CheckAccess()
        {
            // This method is free-threaded.
 
            bool accessAllowed = true;
            Dispatcher dispatcher = _dispatcher;
 
            // Note: a DispatcherObject that is not associated with a
            // dispatcher is considered to be free-threaded.
            if(dispatcher != null)
            {
                accessAllowed = dispatcher.CheckAccess();
            }
 
            return accessAllowed;
        }
 
        /// <summary>
        ///     Verifies that the calling thread has access to this object.
        /// </summary>
        /// <remarks>
        ///     Only the dispatcher thread may access DispatcherObjects.
        ///     <p/>
        ///     This method is public so that derived classes can probe to
        ///     see if the calling thread has access to itself.
        /// </remarks>
        [System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)]
        public void VerifyAccess()
        {
            // This method is free-threaded.
 
            Dispatcher dispatcher = _dispatcher;
 
            // Note: a DispatcherObject that is not associated with a
            // dispatcher is considered to be free-threaded.
            if(dispatcher != null)
            {
                dispatcher.VerifyAccess();
            }
        }
 
        /// <summary>
        ///     Instantiate this object associated with the current Dispatcher.
        /// </summary>
        protected DispatcherObject()
        {
            _dispatcher = Dispatcher.CurrentDispatcher;
        }
 
        private Dispatcher _dispatcher;
        private static Dispatcher _sentinelDispatcher;
    }
}

代码来自：DispatcherObject.cs。

Dispatcher 属性仅仅是在获取 _dispatcher 字段的值，因此我们只需要看 _dispatcher 字段的赋值时机，以及所有给 _dispatcher 赋值的代码。

由于 _dispatcher 字段是私有字段，所以仅需调查这个类本身即可找到所有的赋值时机。（反射等非常规手段需要排除在外，因为这意味着开发者是逗比——自己闯的祸不能怪 WPF 框架。）

赋值时机

先来看看 dispatcher 字段的赋值时机。

DispatcherObject 仅有一个构造函数，而这个构造函数中就已经给 _dispatcher 赋值了，因此其所有的子类的初始化之前，_dispatcher 就会被赋值。

protected DispatcherObject()
{
    _dispatcher = Dispatcher.CurrentDispatcher;
}

那么所赋的值是否可能为 null 呢，这就要看 Dispatcher.CurrentDispatcher 是否可能返回一个 null 了。

以下是 Dispatcher.CurrentDispatcher 的属性获取代码：

public static Dispatcher CurrentDispatcher
{
    get
    {
        // Find the dispatcher for this thread.
        Dispatcher currentDispatcher = FromThread(Thread.CurrentThread);;

        // Auto-create the dispatcher if there is no dispatcher for
        // this thread (if we are allowed to).
        if(currentDispatcher == null)
        {
            currentDispatcher = new Dispatcher();
        }

        return currentDispatcher;
    }
}

可以看到，无论前面的方法得到的值是否是 null，后面都会再给 currentDispatcher 局部变量赋值一个新创建的实例的。因此，此属性是绝对不会返回 null 的。

由此可知，DispatcherObject 自构造起便拥有一个不为 null 的 Dispatcher 属性，其所有子类在初始化之前便会得到不为 null 的 Dispatcher 属性。

后续赋值

现在我们来看看在初始化完成之后，后面是否有可能将 _dispatcher 赋值为 null。

给 _dispatcher 字段的赋值代码仅有两个：

// This method allows certain derived classes to break the dispatcher affinity
// of our objects.
[FriendAccessAllowed] // Built into Base, also used by Framework.
internal void DetachFromDispatcher()
{
    _dispatcher = null;
}

// Make this object a "sentinel" - it can be used in equality tests, but should
// not be used in any other way.  To enforce this and catch bugs, use a special
// sentinel dispatcher, so that calls to CheckAccess and VerifyAccess will
// fail;  this will catch most accidental uses of the sentinel.
[FriendAccessAllowed] // Built into Base, also used by Framework.
internal void MakeSentinel()
{
    _dispatcher = EnsureSentinelDispatcher();
}

第一个 DetachFromDispatcher 很好理解，让 DispatcherObject 跟 Dispatcher 无关。在整个 WPF 的代码中，使用此方法的仅有以下 6 处：

Freezable.Freeze 实例方法
BeginStoryboard.Seal 实例方法
Style.Seal 实例方法
TriggerBase.Seal 实例方法
StyleHelper 在 SealTemplate 静态方法中对 FrameworkTemplate 类型的实例调用此方法
ResourceDictionary 在构造函数中为 DispatcherObject 类型的 DummyInheritanceContext 属性调用此方法

而 Application 类型不是以上任何一个类型的子类（Application 类的直接基类是 DispatcherObject），因此 Application 类中的 Dispatcher 属性不可能因为 DetachFromDispatcher 方法的调用而被赋值为 null。

接下来看看 MakeSentinel 方法，此方法的作用不如上面方法那样直观，实际上它的作用仅仅为了验证某个方法调用时所在的线程是否是符合预期的（给 VerifyAccess 和 CheckAccess 使用）。

使用此方法的仅有 1 处：

ItemsControl 所用的 ItemInfo 类的静态构造函数

internal static readonly DependencyObject SentinelContainer = new DependencyObject();
internal static readonly DependencyObject UnresolvedContainer = new DependencyObject();
internal static readonly DependencyObject KeyContainer = new DependencyObject();
internal static readonly DependencyObject RemovedContainer = new DependencyObject();

static ItemInfo()
{
    // mark the special DOs as sentinels.  This helps catch bugs involving
    // using them accidentally for anything besides equality comparison.
    SentinelContainer.MakeSentinel();
    UnresolvedContainer.MakeSentinel();
    KeyContainer.MakeSentinel();
    RemovedContainer.MakeSentinel();
}

所有这些使用都与 Application 无关。

结论

总结以上所有的分析：

Application 类型的实例在初始化之前，Dispatcher 属性就已经被赋值且不为 null；
所有可能改变 _dispatcher 属性的常规方法均与 Application 类型无关；

因此，所有常规手段均不会让 Application 类的 Dispatcher 属性拿到 null 值。如果你还说拿到了 null，那就检查是否有逗比程序员通过反射或其他手段将 _dispatcher 字段改为了 null 吧……

`Application.Current` 静态属性

关于 Application.Current 是否可能为 null 的分析，由于比较长，请参见我的另一篇博客：

WPF 的 Application.Current.Dispatcher 中，Current 可能为 null

参考资料

DispatcherObject.cs

使用 SetParent 跨进程设置父子窗口时的一些问题（小心卡死）

Tue, 27 Aug 2019 00:49:06 +0000

在微软的官方文档中，说 SetParent 可以在进程内设置，也可以跨进程设置。当使用跨进程设置窗口的父子关系时，你需要注意本文提到的一些问题，避免踩坑。

跨进程设置 `SetParent`

关于 SetParent 函数设置窗口父子关系的文档可以看这个：

SetParent function (winuser.h) - Microsoft Docs

在这篇文章的 DPI 感知一段中明确写明了在进程内以及跨进程设置父子关系时的一些行为。虽然没有明确说明支持跨进程设置父子窗口，不过这段文字就几乎说明 Windows 系统对于跨进程设置窗口父子关系还是支持的。

但 Raymond Chen 在 Is it legal to have a cross-process parent/child or owner/owned window relationship? 一文中有另一段文字：

If I remember correctly, the documentation for SetParent used to contain a stern warning that it is not supported, but that remark does not appear to be present any more. I have a customer who is reparenting windows between processes, and their application is experiencing intermittent instability.
如果我没记错的话，SetParent 的文档曾经包含一个严厉的警告表明它不受支持，但现在这段备注似乎已经不存在了。我就遇到过一个客户跨进程设置窗口之间的父子关系，然后他们的应用程序间歇性不稳定。

这里表明了 Raymond Chen 对于跨进程设置父子窗口的一些担忧，但从文档趋势来看，还是支持的。只是这种担忧几乎说明跨进程设置 SetParent 存在一些坑。

那么本文就说说跨进程设置父子窗口的一些坑。

消息循环强制同步

消息循环

我们会感觉到 Windows 中某个窗口有响应（比如鼠标点击有反应），是因为这个窗口在处理 Windows 消息。窗口进行消息循环不断地处理消息使得各种各样的用户输入可以被处理，并正确地在界面上显示。

一个典型的消息循环大概像这样：

while(GetMessage(ref msg, IntPtr.Zero, 0, 0))
{
    TranslateMessage(ref msg);
    DispatchMessage(ref msg);
}

对于显示了窗口的某个线程调用了 GetMessage 获取了消息，Windows 系统就会认为这个线程有响应。相反，如果长时间不调用 GetMessage，Windows 就会认为这个线程无响应。TranslateMessage 则是翻译一些消息（比如从按键消息翻译成字符消息）。真正处理 GetMessage 中的内容则是后面的调度消息 DispatchMessage，是这个函数的调用使得我们 UI 界面上的内容可以有可见的反映。

一般来说，每个创建了窗口的线程都有自己独立的消息循环，且不会互相影响。然而一旦这些窗口之间建立了父子关系之后就会变得麻烦起来。

强制同步

Windows 会让具有父子关系的所有窗口的消息循环强制同步。具体指的是，所有具有父子关系的窗口消息循环，其消息循环会串联成一个队列（这样才可以避免消息循环的并发）。

也就是说，如果你有 A、B、C、D 四个窗口，分属不同进程，A 是 B、C、D 窗口的父窗口，那么当 A 在处理消息的时候，B、C、D 的消息循环就会卡在 GetMessage 的调用。同样，无论是 B、C 还是 D 在处理消息的时候，其他窗口也会同样卡在 GetMessage 的调用。这样，所有进程的 UI 线程实际上会互相等待，所有通过消息循环执行的代码都不会同时执行。然而实际上 Windows GUI 应用程序的开发中基本上 UI 代码都是通过消息循环来执行的，所以这几乎等同于所有进程的 UI 线程强制同步成类似一个 UI 线程的效果了。

带来的副作用也就相当明显，任何一个进程卡了 UI，其他进程的 UI 将完全无响应。当然，不依赖消息循环的代码不会受此影响，比如 WPF 应用程序的动画和渲染。

如何解决

对于 SetParent 造成的这些问题，实际上没有官方的解决方案，你需要针对你不同的业务采用不同的解决办法。

正如 Raymond Chen 所说：

(It’s one of those “if you don’t already know what the consequences are, then you are not smart enough to do it correctly” things. You must first become the master of the rules before you can start breaking them.)
正如有些人说的“如果你不知道后果，那么你也不足以正确地完成某件事情”。在开始破坏规则之前，您必须先成为规则的主人。

你必须清楚跨进程设置父子窗口带来的各种副作用，然后针对性地给出解决方案：

比如所有窗口会强制串联成一个队列，那么可以考虑将暂时不显示的窗口断开父子关系；
比如设置窗口的位置大小等操作，必须考虑此窗口不是顶层窗口的问题，需要跨越进程到顶层窗口来操作；

参考资料

windows - Good or evil - SetParent() win32 API between different processes - Stack Overflow
Hosting WPF UI cross-thread and cross-process – Diaries of a Software Plumber

[Is it legal to have a cross-process parent/child or owner/owned window relationship?

The Old New Thing](https://devblogs.microsoft.com/oldnewthing/?p=4683)

winapi - Why are “TranslateMessage” and “DispatchMessage” separate calls? - Stack Overflow

程序员可能会使用的各种命名规则

Mon, 19 Aug 2019 00:44:36 +0000

古老的程序员们有时会纠结命名问题，而现在，程序员们的命名已经开创了数个流派。本文整理了程序员们命名会使用到的各种流派，当然一些编程语言会同时使用数个流派。

PascalCase

有很多个名字，除了 PascalCase 还有 UpperCamelCase, BumpyCase。

所有单词直接连接，连接的每个单词的首字母大写。

WelcomeToReadWalterlvBlog

camelCase

所有单词直接连接，连接的每个单词的首字母大写。

walterlvIsADoubi

snake_case

单词的所有字母小写，单词之间通过下划线 _ 连接起来。

welcome_to_read_walterlv_blog

kebab-case

单词的所有字母小写，单词之间通过连字符（hyphen，-）连接起来。

walterlv-is-a-doubi

参考资料

System.InvalidOperationException:“BuildWindowCore 无法返回寄宿的子窗口句柄。”

Wed, 14 Aug 2019 08:32:42 +0000

当试图在 WPF 窗口中嵌套显示 Win32 子窗口的时候，你有可能出现错误：“BuildWindowCore 无法返回寄宿的子窗口句柄。”。

这是很典型的 Win32 错误，本文介绍如何修复此错误。

我们在 MainWindow 中嵌入一个其他的窗口来承载新的 WPF 控件。一般情况下我们当然不会这么去做，但是如果我们要跨越进程边界来完成 WPF 渲染内容的融合的时候，就需要嵌入一个新的窗口了。

WPF 中可以使用 HwndSource 来包装一个 WPF 控件到 Win32 窗口，使用自定义的继承自 HwndHost 的类可以把 Win32 窗口包装成 WPF 控件。由于窗口句柄是可以跨越进程边界传递的，所以这样的方式可以完成跨进程的 WPF 控件显示。

问题

你有可能在调试嵌入窗口代码的时候遇到错误：

System.InvalidOperationException:“BuildWindowCore 无法返回寄宿的子窗口句柄。”

英文是：

BuildWindowCore failed to return the hosted child window handle.

原因和解决办法

此异常的原因非常简单，是 HwndSource 的 BuildWindowCore 的返回值有问题。具体来说，就是子窗口的句柄返回了 0。

也就是下面这段代码中 return new HandleRef(this, IntPtr.Zero) 这句，第二个参数是 0。

protected override HandleRef BuildWindowCore(HandleRef hwndParent)
{
    const int WS_CHILD = 1073741824;
    const int WS_CLIPCHILDREN = 33554432;
    var parameters = new HwndSourceParameters("demo")
    {
        ParentWindow = hwndParent.Handle,
        WindowStyle = (int)(WS_CHILD | WS_CLIPCHILDREN),
        TreatAncestorsAsNonClientArea = true,
    };
    var source = new HwndSource(parameters);
    source.RootVisual = new Button();
    return new HandleRef(this, _handle);
}

要解决，就需要传入正确的句柄值。当然上面的代码为了示例，故意传了一个不知道哪里的 _handle，实际上应该传入 source.Handle 才是正确的。

System.InvalidOperationException:“寄宿 HWND 必须是子窗口。”

Wed, 14 Aug 2019 08:32:35 +0000

当试图在 WPF 窗口中嵌套显示 Win32 子窗口的时候，你有可能出现错误：“System.InvalidOperationException:“寄宿 HWND 必须是子窗口。””。

这是很典型的 Win32 错误，本文介绍如何修复此错误。

一个最简的嵌入其他窗口的例子

下面是最简单的一个例子，为了简单，没有跨进程传递 Win32 窗口句柄，而是直接创建出来。

using System.Runtime.InteropServices;
using System.Windows;
using System.Windows.Interop;

namespace Walterlv.Demo.HwndWrapping
{
    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();
            Loaded += OnLoaded;
        }

        private void OnLoaded(object sender, RoutedEventArgs e)
        {
            Content = new HwndWrapper();
        }
    }

    public class HwndWrapper : HwndHost
    {
        private HwndSource _source;

        protected override HandleRef BuildWindowCore(HandleRef hwndParent)
        {
            var parameters = new HwndSourceParameters("walterlv");
            _source = new HwndSource(parameters);
            // 这里的 ChildPage 是一个继承自 UseControl 的 WPF 控件，你可以自己创建自己的 WPF 控件。
            _source.RootVisual = new ChildPage();
            return new HandleRef(this, _source.Handle);
        }

        protected override void DestroyWindowCore(HandleRef hwnd)
        {
            _source?.Dispose();
        }
    }
}

寄宿 HWND 必须是子窗口

当运行此代码的时候，会提示错误：

System.InvalidOperationException:“寄宿 HWND 必须是子窗口。”

或者英文版：

System.InvalidOperationException:”Hosted HWND must be a child window.”

这是一个 Win32 错误，因为我们试图将一个普通的窗口嵌入到另一个窗口中，而实际上要完成嵌入需要子窗口才行。

那么如何设置一个 Win32 窗口为子窗口呢？使用 SetWindowLong 来设置 Win32 窗口的样式是可以的。不过我们因为使用了 HwndSource，所以可以通过 HwndSourceParameters 来更方便地设置窗口样式。

我们需要将 HwndSourceParameters 那一行改成这样：

++  const int WS_CHILD = 0x40000000;
--  var parameters = new HwndSourceParameters("walterlv");
++  var parameters = new HwndSourceParameters("walterlv")
++  {
++      ParentWindow = hwndParent.Handle,
++      WindowStyle = WS_CHILD,
++  };

最关键的是两点：

需要设置此窗口为子窗口，也就是设置 WindowStyle 为 WS_CHILD；
需要设置此窗口的父窗口，也就是设置 ParentWindow 为 hwndParent.Handle（我们使用参数中传入的 hwndParent 作为父窗口）。

现在再运行，即可正常显示此嵌套窗口：

另外，WindowStyle 属性最好加上 WS_CLIPCHILDREN，详情请阅读：

解决 WPF 嵌套的子窗口在改变窗口大小的时候闪烁的问题

参考资料

WPF嵌入式调用Win32应用程序的问题—提示异常：寄宿的HWND必须是指定父级的子窗口

System.InvalidOperationException:“寄宿的 HWND 必须是指定父级的子窗口。”

Wed, 14 Aug 2019 08:32:16 +0000

当试图在 WPF 窗口中嵌套显示 Win32 子窗口的时候，你有可能出现错误：“寄宿的 HWND 必须是指定父级的子窗口。”。

这是很典型的 Win32 错误，本文介绍如何修复此错误。

问题

你有可能在调试嵌入窗口代码的时候遇到错误：

System.InvalidOperationException:“寄宿的 HWND 必须是指定父级的子窗口。”

英文是：

Hosted HWND must be a child window of the specified parent.

原因和解决办法

出现此错误，是因为同一个子窗口被两次设置为同一个窗口的子窗口。

具体来说，就是 A 窗口使用 HwndHost 设置成了 B 的子窗口，随后 A 又通过一个新的 HwndHost 设置成了新子窗口。

要解决，则必须确保一个窗口只能使用 HwndHost 设置一次子窗口。

如何创建一个基于 MSBuild Task 的跨平台的 NuGet 工具包

Wed, 07 Aug 2019 06:50:59 +0000

MSBuild 的 Task 为我们扩展项目的编译过程提供了强大的扩展性，它使得我们可以用 C# 语言编写扩展；利用这种扩展性，我们可以为我们的项目定制一部分的编译细节。NuGet 为我们提供了一种自动导入 .props 和 .targets 的方法，同时还是一个 .NET 的包平台；我们可以利用 NuGet 发布我们的工具并自动启用这样的工具。

制作这样的一个跨平台 NuGet 工具，我们能够为安装此工具的项目提供自动的但定制化的编译细节——例如自动生成版本号，自动生成某些中间文件等。

本文更偏向于入门，只在帮助你一步一步地制作一个最简单的 NuGet 工具包，以体验和学习这个过程。然后我会在另一篇博客中完善其功能，做一个完整可用的 NuGet 工具。

关于创建跨平台 NuGet 工具包的博客，我写了两篇。一篇介绍写基于 MSBuild Task 的 dll，一篇介绍写任意的命令行工具，可以是用于 .NET Framework 的 exe，也可以是基于 .NET Core 的 dll，甚至可以是使用本机工具链编译的平台相关的各种格式的命令行工具。内容是相似的但关键的坑不同。我分为两篇可以减少完成单个任务的理解难度：

第零步：前置条件

第一步：创建一个项目，用来写工具的核心逻辑

为了方便制作跨平台的 NuGet 工具，新建项目时我们优先选用 .NET Core Library 项目或 .NET Standard Library 项目。

紧接着，我们需要打开编辑此项目的 .csproj 文件，将目标框架改成多框架的，并填写必要的信息。

<!-- Walterlv.NuGetTool.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <!-- 给一个初始的版本号。 -->
    <Version>1.0.0-alpha</Version>
    <!-- 使用 .NET Framework 4.7 和 .NET Core 2.0。
      要点 1：
        - 加入 net47 的支持是为了能让基于 .NET Framework 的 msbuild 能够使用此工具编译；
        - 加入 netcoreapp2.0 的支持是为了能让基于 .NET Core 的 dotnet build (Roslyn) 能够使用此工具编译；
        - 当然 net47 太新了，只适用于 Visual Studio 2017 的较新版本，如果你需要照顾到更多用户，建议使用 net46。
      要点 2：
        注意，我们使用 NuGet 包来依赖 Task 框架，但此 NuGet 包要求的最低 .NET Framework 版本为 4.6。
        如果需要制作 .NET Framework 4.5 及以下版本，就必须改为引用以下程序集：
        - Microsoft.Build
        - Microsoft.Build.Framework
        - Microsoft.Build.Tasks.v4.0
        - Microsoft.Build.Utilities.v4.0 -->
    <TargetFrameworks>net47;netcoreapp2.0</TargetFrameworks>
    <!-- 这个就是创建项目时使用的名称。 -->
    <AssemblyName>Walterlv.NuGetTool</AssemblyName>
    <!-- 此值设为 true，才会在编译之后生成 NuGet 包。 -->
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
    <!-- 作者的 Id，如果要发布到 nuget.org，那么这里就是 NuGet 用户 Id。 -->
    <Authors>walterlv</Authors>
  </PropertyGroup>
</Project>

然后，安装如下 NuGet 包：

Microsoft.Build.Framework: 提供了编写 ITask 的框架，有了这个才能写 ITask
Microsoft.Build.Utilities.Core: 提供了 ITask 框架的基本实现，这样才能用更少的代码写完 Task

要特别注意：由于我们是一个 NuGet 工具，不需要被其他项目直接依赖，所以此项目的依赖包不应该传递到下一个项目中。所以请将所有的 NuGet 包资产都声明成私有的，方法是在 NuGet 包的引用后面加上 PrivateAssets="All"。想了解 PrivateAssets 的含义一起相关属性，可以阅读我的另一篇文章项目文件中的已知 NuGet 属性（使用这些属性，创建 NuGet 包就可以不需要 nuspec 文件啦） - 吕毅。

<ItemGroup>
  <PackageReference Include="Microsoft.Build.Framework" Version="15.6.85" />
  <PackageReference Include="Microsoft.Build.Utilities.Core" Version="15.6.85" />
  <PackageReference Update="@(PackageReference)" PrivateAssets="All" />
</ItemGroup>

接下来就是取名字的时间了！为 Class1 类改一个名字。这个类将成为我们这个 NuGet 工具包的入口类。

比如我们想做一个用 Git 提交信息来生成版本号的类，可以叫做 GitVersion；想做一个生成多语言文件的类，可以叫做 LangGenerator。在这里，为了示范而不是真正的实现功能，我取名为 DemoTool。

取好名字之后，让这个类继承自 Microsoft.Build.Utilities.Task：

// DemoTool.cs
using Microsoft.Build.Utilities;

namespace Walterlv.NuGetTool
{
    public class DemoTool : Task
    {
        public override bool Execute()
        {
            return true;
        }
    }
}

这时进行编译，我们的 NuGet 包就会出现在项目的输出目录 bin\Debug 下了。

第二步：组织 NuGet 目录

刚刚生成的 NuGet 包还不能真正拿来用。事实上你也可以拿去安装，不过最终的效果只是加了一个毫无作用的引用程序集而已（顺便还带来一堆垃圾的间接引用）。

所以，我们需要进行“一番配置”，使得这个项目编译成一个NuGet 工具，而不是一个依赖包。

现在，介绍一下 NuGet 预设的目录（如果你想看，可以去解压 .nupkg 文件）：

// 根目录，用来放 readme.txt 的（已经有人提 issue 要求加入 markdown 支持了）
+ /
// 用来放引用程序集 .dll，文档注释 .xml 和符号文件 .pdb 的
+ lib/
// 用来放那些与平台相关的 .dll/.pdb/.pri 的
+ runtimes/
// 任意种类的文件，在这个文件夹中的文件会在编译时拷贝到输出目录（保持文件夹结构）
+ content/
// 这里放 .props 和 .targets 文件，会自动被 NuGet 导入，成为项目的一部分（要求文件名与包名相同）
+ build/
// 这里也是放 .props 和 .targets 文件，会自动被 NuGet 导入，成为项目的一部分（要求文件名与包名相同）
+ buildMultiTargeting/
// PowerShell 脚本或者程序，在这里的工具可以在“包管理控制台”(Package Manager Console) 中使用
+ tools/

▲ 以上结构可以去官网翻阅原文 How to create a NuGet package - Microsoft Docs，不过我这里额外写了一个预设目录 buildMultiTargeting，官方文档却没有说。

注意到我们的 csproj 文件中的 <TargetFrameworks> 节点吗？如果指定为单个框架，则自动导入的是 build 目录下的；如果指定为多个框架，则自动导入的是 buildMultiTargeting 目录下的。

我们的初衷是做一个 NuGet 工具，所以我们需要选择合适的目录来存放我们的输出文件。

我们要放一个 Walterlv.NuGetTool.targets 文件到 build 和 buildMultiTargeting 文件夹中，以便能够让我们定制编译流程。我们要让我们写的 dll（也就是那个 Task）能够工作，但是以上任何预定义的文件夹都不能满足我们的要求，于是我们建一个自定义的文件夹，取名为 tasks，这样 NuGet 便不会对我们的这个 dll 进行特殊处理，而将处理权全部交给我们。

于是我们自己的目录结构为：

+ build/
    - Walterlv.NuGetTool.targets
+ buildMultiTargeting/
    - Walterlv.NuGetTool.targets
+ tasks/
    + net47/
        - Walterlv.NuGetTool.dll
    + netcoreapp2.0/
        - Walterlv.NuGetTool.dll
- readme.txt

那么，如何改造我们的项目才能够生成这样的 NuGet 目录结构呢？

我们先在 Visual Studio 里建好文件夹：

随后去编辑项目的 .csproj 文件，在最后的 </Project> 前面添加下面这些项：

<!-- Walterlv.NuGetTool.csproj -->
<ItemGroup>
  <None Include="Assets\build\**" Pack="True" PackagePath="build\" />
  <None Include="Assets\buildMultiTargeting\**" Pack="True" PackagePath="buildMultiTargeting\" />
  <None Include="Assets\readme.txt" Pack="True" PackagePath="" />
</ItemGroup>

None 表示这一项要显示到 Visual Studio 解决方案中（其实对于不认识的文件，None 就是默认值）；Include 表示相对于项目文件的路径（支持通配符）；Pack 表示这一项要打包到 NuGet；PackagePath 表示这一项打包到 NuGet 中的路径。(如果你想了解更多 csproj 中的 NuGet 属性，可以阅读我的另一篇文章：项目文件中的已知 NuGet 属性（使用这些属性，创建 NuGet 包就可以不需要 nuspec 文件啦） - 吕毅)

这样的一番设置，我们的 build、buildMultiTargeting 和 readme.txt 准备好了，但是 tasks 文件夹还没有。由于我们是把我们生成的 dll 放到 tasks 里面，第一个想到的当然是修改输出路径——然而这是不靠谱的，因为 NuGet 并不识别输出路径。事实上，我们还可以设置一个属性 <BuildOutputTargetFolder>，将值指定为 tasks，那么我们就能够将我们的输出文件打包到 NuGet 对应的 tasks 文件夹下了。

至此，我们的 .csproj 文件看起来像如下这样（为了减少行数，我已经去掉了注释）：

<!-- Walterlv.NuGetTool.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <Version>1.0.0-alpha</Version>
    <AssemblyName>Walterlv.NuGetTool</AssemblyName>
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
    <!-- ↓ 新增的属性 -->
    <BuildOutputTargetFolder>tasks</BuildOutputTargetFolder>
    <!-- ↓ 新增的属性 -->
    <NoPackageAnalysis>true</NoPackageAnalysis>
    <!-- ↓ 新增的属性 -->
    <DevelopmentDependency>true</DevelopmentDependency>
    <Authors>walterlv</Authors>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.Build.Framework" Version="15.6.85" />
    <PackageReference Include="Microsoft.Build.Utilities.Core" Version="15.6.85" />
    <!-- ↓ 在第一步中不要忘了这一行 -->
    <PackageReference Update="@(PackageReference)" PrivateAssets="All" />
  </ItemGroup>
  <ItemGroup>
    <Folder Include="Assets\tasks\" />
  </ItemGroup>
  <ItemGroup>
    <!-- ↓ 新增的三项 -->
    <None Include="Assets\build\**" Pack="True" PackagePath="build\" />
    <None Include="Assets\buildMultiTargeting\**" Pack="True" PackagePath="buildMultiTargeting\" />
    <None Include="Assets\readme.txt" Pack="True" PackagePath="" />
  </ItemGroup>
</Project>

注意到我同时还在文件中新增了另外两个属性配置 NoPackageAnalysis 和 DevelopmentDependency。由于我们没有 lib 文件夹，所以 NuGet 会给出警告，NoPackageAnalysis 将阻止这个警告。DevelopmentDependency 是为了说明这是一个开发依赖，设置为 true 将阻止包作为依赖传递给下一个项目。（事实上这又是官方的一个骗局！因为新版本的 NuGet 竟然去掉了这个功能！，已经被吐槽了，详见：PackageReference should support DevelopmentDependency metadata · Issue #4125 · NuGet/Home）。关于这些属性更详细的解释，依然可以参见：项目文件中的已知 NuGet 属性（使用这些属性，创建 NuGet 包就可以不需要 nuspec 文件啦） - 吕毅。

现在再尝试编译一下我们的项目，去输出目录下解压查看 nupkg 文件，你就能看到期望的 NuGet 文件夹结构了；建议一个个点进去看，你可以看到我们准备好的空的 Walterlv.NuGetTool.targets 文件，也能看到我们生成的 Walterlv.NuGetTool.dll。

第三步：编写 Target

.targets 文件是对项目功能进行扩展的关键文件，由于安装 NuGet 包会自动导入包中的此文件，所以它几乎相当于我们功能的入口。

现在，我们需要徒手编写这个文件了。

<!-- Assets\build\Walterlv.NuGetTool.targets -->
<Project>

  <PropertyGroup>
    <!-- 我们使用 $(MSBuildRuntimeType) 来判断编译器是 .NET Core 的还是 .NET Framework 的。
         然后选用对应的文件夹。-->
    <NuGetWalterlvTaskFolder Condition=" '$(MSBuildRuntimeType)' == 'Core'">$(MSBuildThisFileDirectory)..\tasks\netcoreapp2.0\</NuGetWalterlvTaskFolder>
    <NuGetWalterlvTaskFolder Condition=" '$(MSBuildRuntimeType)' != 'Core'">$(MSBuildThisFileDirectory)..\tasks\net47\</NuGetWalterlvTaskFolder>
  </PropertyGroup>

  <UsingTask TaskName="Walterlv.NuGetTool.DemoTool" AssemblyFile="$(NuGetWalterlvTaskFolder)\Walterlv.NuGetTool.dll" />
  <Target Name="WalterlvDemo" BeforeTargets="CoreCompile">
    <DemoTool />
  </Target>

</Project>

targets 的文件结构与 csproj 是一样的，你可以阅读我的另一篇文章理解 C# 项目 csproj 文件格式的本质和编译流程 - 吕毅了解其结构。

上面的文件中，我们指定 Target 的执行时机为 CoreCompile 之前，也就是编译那些 .cs 文件之前。在这个时机，我们可以修改要编译的 .cs 文件。如果想了解更多关于 Target 执行时机或顺序相关的资料，可以阅读：Target Build Order。

别忘了我们还有一个 buildMultiTargeting 文件夹，也要放一个几乎一样功能的 targets 文件；不过我们肯定不会傻到复制一个一样的。我们在 buildMultiTargeting 文件夹里的 targets 文件中写以下内容，这样我们的注意力便可以集中在前面的 targets 文件中了。

<!-- Assets\buildMultiTargeting\Walterlv.NuGetTool.targets -->
<Project>
  <!-- 直接 Import 我们在 build 中写的那个 targets 文件。
       NuGet 留下了为多框架项目提供特殊扩展的方案，其实有时候也是很有用的。-->
  <Import Project="..\build\Walterlv.NuGetTool.targets" />
</Project>

第四部：调试

严格来说，写到这里，我们的跨平台 NuGet 工具已经写完了。在以上状态下，你只需要编译一下，就可以获得一个跨平台的基于 MSBuild Task 的 NuGet 工具。只是——你肯定会非常郁闷——心里非常没谱，这工具到底有没有工作起来！有没有按照我预期的进行工作！如果遇到了 Bug 怎么办！

于是现在我们来掌握一些调试技巧，这样才方便我们一步步完善我们的功能嘛！额外插一句：以上第一到第三步几乎都是结构化的步骤，其实非常适合用工具来自动化完成的。

让我们的 Target 能够正确找到我们新生成的 dll

你应该注意到，我们的 targets 文件在 Assets\build 目录下，而我们的 Assets 文件夹下并没有真实的 tasks 文件夹（里面是空的）。于是我们希望在调试状态下，dll 能够指向输出目录下。于是我们修改 targets 文件添加配置：

<!-- Assets\build\Walterlv.NuGetTool.targets -->
<Project>

  <PropertyGroup Condition=" $(IsInDemoToolDebugMode) == 'True' ">
    <NuGetWalterlvTaskFolder Condition=" '$(MSBuildRuntimeType)' == 'Core'">$(MSBuildThisFileDirectory)..\..\bin\$(Configuration)\netcoreapp2.0\</NuGetWalterlvTaskFolder>
    <NuGetWalterlvTaskFolder Condition=" '$(MSBuildRuntimeType)' != 'Core'">$(MSBuildThisFileDirectory)..\..\bin\$(Configuration)\net47\</NuGetWalterlvTaskFolder>
  </PropertyGroup>

  <PropertyGroup Condition=" $(IsInDemoToolDebugMode) != 'True' ">
    <NuGetWalterlvTaskFolder Condition=" '$(MSBuildRuntimeType)' == 'Core'">$(MSBuildThisFileDirectory)..\tasks\netcoreapp2.0\</NuGetWalterlvTaskFolder>
    <NuGetWalterlvTaskFolder Condition=" '$(MSBuildRuntimeType)' != 'Core'">$(MSBuildThisFileDirectory)..\tasks\net47\</NuGetWalterlvTaskFolder>
  </PropertyGroup>
  
  <UsingTask TaskName="Walterlv.NuGetTool.DemoTool" AssemblyFile="$(NuGetWalterlvTaskFolder)\Walterlv.NuGetTool.dll" />
  <Target Name="WalterlvDemo" BeforeTargets="CoreCompile">
    <DemoTool />
  </Target>

</Project>

这样，我们就拥有了一个可以供用户设置的属性 <IsInDemoToolDebugMode> 了。

准备一个用于测试 Task 的测试项目

接着，我们在解决方案中新建一个调试项目 Walterlv.Debug（我选用了 .NET Standard 2.0 框架）。然后在它的 csproj 中 <Import> 我们刚刚的 .targets 文件，并设置 <IsInDemoToolDebugMode> 属性为 True：

<!-- Walterlv.Debug.csproj -->
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <IsInDemoToolDebugMode>True</IsInDemoToolDebugMode>
  </PropertyGroup>

  <Import Project="..\Walterlv.NuGetTool\Assets\build\Walterlv.NuGetTool.targets" />
  
</Project>

当准备好基本的调试环境之后，我们的解决方案看起来是下面这样的样子：

让我们自定义的 Task 开始工作，并能够进入断点

最简单能够让 DemoTool 这个自定义的 Task 进入断点的方式当然是加上 Debugger.Launch(); 了，就像这样：

// DemoTool.cs
using System.Diagnostics;
using Microsoft.Build.Utilities;

namespace Walterlv.NuGetTool
{
    public class DemoTool : Task
    {
        public override bool Execute()
        {
            // 新增了启动调试器的代码。
            Debugger.Launch();
            return true;
        }
    }
}

这样，一旦此函数开始执行，Windows 将显示一个选择调试器的窗口，我们选择当前打开的 Visual Studio 即可。

当然，也有一些比较正统的方法，为了使这篇文章尽可能简单，我只附一张图，如果有需要，可以自己去尝试：

现在，我们去 Walterlv.Debug 目录下输入 msbuild 命令，在输出到如下部分的时候，就会进入我们的断点了：

这下，我们的调试环境就全部搭建好了，你可以发挥你的想象力在 Task 里面随意挥洒你的代码！

当然，只要你记得去掉 Debugger.Launch();，或者加上 #if DEBUG 这样的条件编译，那么随时打包就是一个可以发布的跨平台 NuGet 工具包了。

提示：一旦调试环境搭建好，你可能会遇到编译 Walterlv.NuGetTool 项目时，发现 dll 被占用的情况，这时，打开任务管理器结束掉 msbuild.exe 进行即可。

第五步：发挥你的想象力

想象力是没有限制的，不过如果不知道 Task 能够为我们提供到底什么样的功能，也是无从下手的。这一节我会说一些 Task 在 C# 代码和 .targets 文件中的互相操作。

.targets 向 Task 传参数

.targets 向 Task 传参数只需要写一个属性赋值的句子就可以了：

<!-- Assets\build\Walterlv.NuGetTool.targets -->
<Target Name="WalterlvDemo" BeforeTargets="CoreCompile">
  <DemoTool IntermediateOutputPath="$(IntermediateOutputPath)" />
</Target>

这里，$(IntermediateOutputPath) 是 msbuild 编译期间会自动设置的全局属性，代表此项目编译过程中临时文件的存放路径（也就是我们常见的 obj 文件夹）。当然，使用 dotnet build 或者 dotnet msbuild 也是有这样的全局属性的。我们为 <DemoTool> 节点也加了一个属性，名为 IntermediateOutputPath。

在 DemoTool 的 C# 代码中，只需要写一个字符串属性即可接收这样的传参。

// DemoTool.cs
public class DemoTool : Task
{
    public string IntermediateOutputPath { get; set; }

    public override bool Execute()
    {
        Debugger.Launch();
        var intermediateOutputPath = IntermediateOutputPath;
        return true;
    }
}

▲ 在断点中我们能够看到传进来的参数的值

你可以尽情发挥你的想象力，传入更多让人意想不到的参数，实现不可思议的功能。更多 MSBuild 全局参数，可以参考我的另一篇文章项目文件中的已知属性（知道了这些，就不会随便在 csproj 中写死常量啦） - 吕毅。

Task 向 .targets 返回参数

如果只是传入参数，那么我们顶多只能干一些不痛不痒的事情，或者就是两者互相约定了一些常量。什么？你说直接去改源代码？那万一你的代码不幸崩溃了，项目岂不被你破坏了！（当然，你去改了源码，还会破坏 MSBuild 的差量编译。）

我们新定义一个属性，但在属性上面标记 [Output] 特性。这样，这个属性就会作为输出参数传到 .targets 里了。

// DemoTool.cs
using System.Diagnostics;
using System.IO;
using Microsoft.Build.Framework;
using Microsoft.Build.Utilities;

namespace Walterlv.NuGetTool
{
    public class DemoTool : Task
    {
        public string IntermediateOutputPath { get; set; }

        [Output]
        public string AdditionalCompileFile { get; set; }

        public override bool Execute()
        {
            Debugger.Launch();
            var intermediateOutputPath = IntermediateOutputPath;
            var additional = Path.Combine(intermediateOutputPath, "DoubiClass.cs");
            AdditionalCompileFile = Path.GetFullPath(additional);
            File.WriteAllText(AdditionalCompileFile,
                @"using System;
namespace Walterlv.Debug
{
    public class Doubi
    {
        public string Name { get; }
        private Doubi(string name) => Name = name;
        public static Doubi Get() => new Doubi(""吕毅"");
    }
}");
            return true;
        }
    }
}

然后，我们在 .targets 里接收这个输出参数，生成一个属性：

<!-- Assets\build\Walterlv.NuGetTool.targets -->
<Target Name="WalterlvDemo" BeforeTargets="CoreCompile">
  <DemoTool IntermediateOutputPath="$(IntermediateOutputPath)">
    <Output TaskParameter="AdditionalCompileFile" PropertyName="WalterlvDemo_AdditionalCompileFile" />
  </DemoTool>

  <ItemGroup>
    <Compile Include="$(WalterlvDemo_AdditionalCompileFile)" />
  </ItemGroup>
</Target>

这样，我们生成的 Walterlv.Debug 调试项目在编译完成之后，还会额外多出一个“逗比”类。而且——我们甚至能够直接在 Walterlv.Debug 项目的中使用这个编译中生成的新类。

使用编译生成的新类既不会报错，也不会产生警告下划线，就像原生写的类一样。

如果你要在编译期间替换一个类而不是新增一个类，例如将 Class1.cs 更换成新类，那么需要将其从编译列表中移除：

<!-- Assets\build\Walterlv.NuGetTool.targets -->
<ItemGroup>
  <Compile Remove="Class1.cs" />
  <Compile Include="$(WalterlvDemo_AdditionalCompileFile)" />
</ItemGroup>

需要注意：编译期间才生成的项（<ItemGroup>）或者属性（<PropertyGroup>），需要写在 <Target> 节点的里面。如果写在外面，则不是编译期间生效的，而是始终生效的。当写在外面时，要特别留意可能某些属性没有初始化完全，你应该只使用那些肯定能确认存在的属性或文件。

在 Target 里编写调试代码

虽然说以上的每一个步骤我都是一边实操一边写的，但即便如此，本文都写了 500 多行了，如果你依然能够不出错地完成以上每一步，那也是万幸了！Task 里我能还能用断点调试，那么 Target 里面怎么办呢？

我们可以用 <Message> 节点来输出一些信息：

<!-- Assets\build\Walterlv.NuGetTool.targets -->
<Target Name="WalterlvDemo" BeforeTargets="CoreCompile">
  <DemoTool IntermediateOutputPath="$(IntermediateOutputPath)">
    <Output TaskParameter="AdditionalCompileFile" PropertyName="WalterlvDemo_AdditionalCompileFile" />
  </DemoTool>

  <Message Text="临时文件的路径为：$(WalterlvDemo_AdditionalCompileFile)" />

  <ItemGroup>
    <Compile Include="$(WalterlvDemo_AdditionalCompileFile)" />
  </ItemGroup>
</Target>

在 Task 输出错误或警告

我们继承了 Microsoft.Build.Utilities.Task，此类有一个 Log 属性，可以用来输出信息。使用 LogWarning 方法可以输出警告，使用 LogError 可以输出错误。如果输出了错误，那么就会导致编译不通过。

加入差量编译支持

如果你觉得你自己写的 Task 执行非常耗时，那么建议加入差量编译的支持。关于加入差量编译，可以参考我的另一篇文章每次都要重新编译？太慢！让跨平台的 MSBuild/dotnet build 的 Target 支持差量编译。

本地测试 NuGet 包

在发布 NuGet 包之前，我们可以先在本地安装测试。由于我们在 C:\Users\lvyi\Desktop\Walterlv.NuGetTool\Walterlv.NuGetTool\bin\Debug 输出路径下已经有了打包好的 nupkg 文件，所以可以加一个本地 NuGet 源。

我们找一个其他的项目，然后在 Visual Studio 中设置 NuGet 源为我们那个 NuGet 工具项目的输出路径。

这时安装，编译完之后，我们就会发现我们的项目生成的 dll 中多出了一个“逗比(Doubi)”类，并且可以在那个项目中编写使用 Doubi 的代码了。

总结

不得不说，制作一个跨平台的基于 MSBuild Task 的 NuGet 工具包还是比较麻烦的，我们总结一下：

准备项目的基本配置（设置各种必要的项目属性，安装必要的 NuGet 依赖）
建立好 NuGet 的文件夹结构
编写 Task 和 Target
新增功能、调试和测试

如果你在实践的过程中遇到了各种问题，欢迎在下面留言，一般我会在一天之内给予回复。

如果在阅读这篇文章时存在一些概念理解上的问题，或者不知道如何扩展本文的功能，可能需要阅读下我的另一些文章：

当然，还有一些正在编写，过一段时间可以阅读到。

参考资料

walterlv

将美化进行到底，把 PowerShell 做成 oh-my-zsh 的样子

安装 oh-my-posh

启用模组并设置主题

安装字体/安装第三方 PowerShell

使用 WPF 做一个可以逼真地照亮你桌面的高性能阳光

效果预览

代码实现

第一步：制作一个全透明窗口

第二步：编写一个像素着色器

第三步：画一个简单的阳光形状

效果与性能

路径标记语法（Path Markup Syntax）完全教程

示例

名称

语法（Syntax）

F

起点和终点

M m 移动命令

L l H h V v 直线命令

C c、Q q、S s、T t 贝塞尔曲线命令

A a 椭圆弧命令

Z z 闭合命令

解析

用 WiX 制作安装包：创建一个简单的 exe 安装包

创建 WiX EXE 项目

引用 MSI 项目

编辑 Bundle.wxs 文件

编辑基本的安装包信息

测试效果

附源代码

Bundle.wxs

0x800b0109 - 已处理证书链，但是在不受信任提供程序信任的根证书中终止。

错误

原因

解决

WiX Toolset 安装包制作入门教程（目录篇）

系列教程说明

分类 Hello World

msi 格式安装包的 Hello World

exe 格式安装包的 Hello World

要求 .NET Framework 前置的 Hello World

使用 WPF 制作安装界面的 Hello World

你可能在 Hello World 系列中遇到的问题和解决办法汇总

方法与汇总

具体问题

基本概念和原则

完成主要安装流程

可供查阅的资料汇总

其他 WiX Toolset 教程系列

如何调试 WiX Burn 制作的自定义托管引导程序的 exe 安装包

查看日志

Debugger.Launch()

对比测试

用 WiX Burn 制作托管安装包：出现 0x80131508 错误

现象

调查

解决

用 WiX 制作安装包：设置的 .NET Framework 前置会始终安装，即使目标电脑已经自带或装好

现象

调查

解决

使用 WiX 创建最简单的安装包过程中可能出现的问题和解决方案汇总

无法启动 exe 安装包

.NET Framework 始终会安装

用 WiX Burn 制作托管安装包：出现 0x80070002 错误

现象

调查

解决

如何查看用 WiX 制作的安装包的日志

用 WiX 制作安装包：制作 WPF 安装包界面（入门篇）

本文准备做什么？

创建 WPF 项目

将 WPF UI 项目对接 WiX 捆绑包

1. 添加“BootstrapperCore.dll”引用

2. 实现自己的引导程序（Bootstrapper）

3. 添加 BootstrapperCore.config 文件

在捆绑包项目里接入 WPF UI 项目

测试效果

附源代码

`F`

`M` `m` 移动命令

`L` `l` `H` `h` `V` `v` 直线命令

`C` `c`、`Q` `q`、`S` `s`、`T` `t` 贝塞尔曲线命令

`A` `a` 椭圆弧命令

`Z` `z` 闭合命令

`Debugger.Launch()`