Zony 的博客

Linux 使用 CUDA Docker 镜像加速视频转码

Thu, 27 Jun 2024 13:08:00 +0000

0. 背景

在某些时候我们会使用到显卡对视频转码进行加速，此时可以使用 NVIDA 官方提供的 CUDA 镜像来进行加速，在这个 CUDA 镜像里面提供了完整的 NVIDA 驱动等环境，可以直接被 ffmpeg 调用以进行加速。

1. 配置基础环境

1.1 安装 NVIDIA Container Toolkit

访问网站 https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html 根据你自己系统的发行版选择安装方式，我这里是 Ubuntu Server，默认情况是 APT 包管理器，因此根据 APT 的步骤进行安装即可。安装完成之后，使用以下命令启用。

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

1.2 禁用 Systemd CG Group

在使用过程当中，当某个 CUDA 容器运行一段时间之后就出现错误:

NOTICE: Containers losing access to GPUs with error: "Failed to initialize NVML: Unknown Error"

查询得知是这个 Issue #48 提到的问题，根据里面的描述，最快的解决办法就是修改 /etc/docker/daemon.json 文件，然后在里面加上:

{
  "exec-opts": ["native.cgroupdriver=cgroupfs"]
}

随后重启 Docker 服务。

sudo systemctl restart docker
sudo systemctl daemon-reload

2. 构建新的镜像

默认情况下 nvidia/cuda:12.4.1-runtime-ubuntu22.04 镜像已经包含了 NVIDIA 驱动，但是没有包含编码器和解码器，所以我们要让 ffmpeg 能够正常工作，就需要安装对应的编解码器。

FROM nvidia/cuda:12.4.1-runtime-ubuntu22.04 AS base

# Install dependencies
RUN apt update \
    && apt install -y ffmpeg \
    && apt install -y bash \
    && apt install -y libnvidia-encode-550

3. 启动容器

docker run 命令要运行指定镜像时，需要加上一些参数，如下:

docker run -it --gpus all -e NVIDIA_DRIVER_CAPABILITIES=all --rm nvidia/cuda:12.4.1-runtime-ubuntu22.04 bash

如果使用 docker compose 文件，下面就是示例:

services:
  demo:
    image: demo-image:latest
    container_name: "demo"
    restart: always

    environment:
      NVIDIA_DRIVER_CAPABILITIES: all

    runtime: nvidia

排查 dotNET Core 程序内存暴涨的问题

Fri, 08 Mar 2024 15:30:00 +0000

0. 问题

新版本上线之后，发现内存猛涨，入站流量猛增，不清楚具体原因，部分接口提示 OOM 异常，随后 Pod 直接崩溃无限重启。

1. 准备

Pod 已经接入了 NewRelic 和 Graylog，但是仍然没有办法找到真正的罪魁祸手，此时只能进入 Pod 容器当中抓取内存 Dump 信息。我们容器的基础镜像是基于 Apline-3.18 的，进入容器之后执行了以下命令开始安装相应的工具。

# 我们的镜像是基于 runtime 的，因此需要手动安装一下 SDK，以便后续操作。
# 这里还安装了 bash，后续会使用 bash 进行交互操作，自带的 sh 不好用。
apk add dotnet6-sdk bash
# 安装 Dump 工具
dotnet tool install --global dotnet-dump

因为容器的 ENTRYPOINT 就是直接运行的 dotNET 程序，一般来说其 PID 都是 1，如果你不清楚具体的进程 ID，可以执行

尝试运行 dotnet-dump collect -p 1 收集 Dump 信息，但是得到了以下错误:

/build# dotnet-dump collect -p 1

Writing full to /build/core_20240307_090401
Write dump failed - HRESULT: 0x00000000.

搜索一番之后，得知这是 Pod 没有足够的权限去执行 Dump 操作，因此修改了 Rollouts(或者 Deplotment) 的 YAML 定义，添加对应的 securityContext 应用即可，随后便能够正确地获取 Dump 文件。

securityContext:
  capabilities:
    add:
    - SYS_PTRACE
    - SYS_ADMIN
  seccompProfile:
    type: RuntimeDefault

再次执行 dotnet-dump collect -p 1 获取到了对应的 Dump 文件，将文件拷贝到挂载的 NFS 卷当中，随即下载到本地以便进行调试排查问题。

2. 调查

得到 Dump 文件之后，我们可以使用多种工具来分析 Dump 文件，这里我使用的是 dotnet-dump 命令。因为我是 macOS 的机器，使用 dotnet-dump 我可以直接开始进行分析，你也可以使用 Visual Studio 、dotnetMemory、WinDBG 来打开 Dump 的文件，具体看你的喜好了。

使用 dotnet dump analyze <dump file path> 进入交互式页面:

Loading core dump: D:\dotNET_Dumps\\core_20240307_142201 ...
Ready to process analysis commands. Type 'help' to list available commands or 'help [command]' to get detailed help on a command.
Type 'quit' or 'exit' to exit the session.

首先我们可以看一下目前 GC 堆的信息:

> eeheap -gc

========================================
Number of GC Heaps: 3
----------------------------------------
Heap 0 (00007faa2a73b6b0)
generation 0 starts at 7fa2495932e8
generation 1 starts at 7fa2458279f0
generation 2 starts at 7fa232703000
ephemeral segment allocation context: none
Small object heap
         segment            begin        allocated        committed allocated size         committed size
    7fa232702000     7fa232703000     7fa249be4020     7fa252174000 0x174e1020 (390991904) 0x1fa72000 (531046400)
Large object heap starts at 7fa3b2703000
         segment            begin        allocated        committed allocated size         committed size
    7fa3b2702000     7fa3b2703000     7fa3e3dfc348     7fa3e3dfd000 0x316f9348 (829395784) 0x316fb000 (829403136)
Pinned object heap starts at 7fa6b2703000
         segment            begin        allocated        committed allocated size         committed size
    7fa6b2702000     7fa6b2703000     7fa6b27d4bb8     7fa6b27d5000 0xd1bb8 (859064)       0xd3000 (864256)
------------------------------
Heap 1 (00007faa2a68b6e0)
generation 0 starts at 7fa2c75ae080
generation 1 starts at 7fa2c40eec00
generation 2 starts at 7fa2b2703000
ephemeral segment allocation context: none
Small object heap
         segment            begin        allocated        committed allocated size         committed size
    7fa2b2702000     7fa2b2703000     7fa2c9b1ebb0     7fa2d00b8000 0x1741bbb0 (390183856) 0x1d9b6000 (496721920)
Large object heap starts at 7fa4b2703000
         segment            begin        allocated        committed allocated size         committed size
    7fa4b2702000     7fa4b2703000     7fa4e3f804f0     7fa4e3f81000 0x3187d4f0 (830985456) 0x3187f000 (830992384)
Pinned object heap starts at 7fa7b2703000
         segment            begin        allocated        committed allocated size         committed size
    7fa7b2702000     7fa7b2703000     7fa7b2703018     7fa7b2704000 0x18 (24)              0x2000 (8192)
------------------------------
Heap 2 (00007faa2a5db720)
generation 0 starts at 7fa3466d0298
generation 1 starts at 7fa343173ee0
generation 2 starts at 7fa332703000
ephemeral segment allocation context: none
Small object heap
         segment            begin        allocated        committed allocated size         committed size
    7fa332702000     7fa332703000     7fa348631878     7fa34f736000 0x15f2e878 (368240760) 0x1d034000 (486752256)
Large object heap starts at 7fa5b2703000
         segment            begin        allocated        committed allocated size         committed size
    7fa5b2702000     7fa5b2703000     7fa5e519c3b0     7fa5e519d000 0x32a993b0 (849974192) 0x32a9b000 (849981440)
Pinned object heap starts at 7fa8b2703000
         segment            begin        allocated        committed allocated size         committed size
    7fa8b2702000     7fa8b2703000     7fa8b270c0f0     7fa8b2714000 0x90f0 (37104)         0x12000 (73728)
------------------------------
GC Allocated Heap Size:    Size: 0xda315cf0 (3660668144) bytes.
GC Committed Heap Size:    Size: 0xeff58000 (4025843712) bytes.

可以看到有 3 个 GC 堆，并且大部分内存占用都在 LOH 上，我们使用 dumpheap -stat -min 85000 搜索一下大小大于 85000 字节的对象有多少？

> dumpheap -stat -min 85000
Statistics:
          MT Count     TotalSize Class Name
7fa9b9be29c0     1        85,112 Serilog.Events.LogEventPropertyValue[]
7fa9ba87d710     1       117,464 Microsoft.AspNetCore.Routing.Matching.DfaState[]
7fa9b327b110     2       261,648 System.Object[]
7fa9b3348080     2       849,380 System.Int32[]
7fa9bb1e29f8     5     1,441,912 ***.Core.***.*************[]
7fa9b334d2e0     6     1,939,370 System.String
7fa9bb3589a0     1     2,097,176 ***.Core.***.***.***[]
7fa9b5200528     9     2,228,440 ***.Core.***.***[]
7fa9b5206200    20     3,670,496 ***.Core.***.***[]
7fa9bb3625e8     1     4,506,048 System.Collections.Generic.Dictionary<System.String, ***.***.***.***.***>+Entry[]
7fa9b338edd0    20     9,716,748 System.Char[]
7faa2cb14350    76    13,295,160 Free
7fa9b3d60c98 1,100 2,464,160,840 System.Byte[]
Total 1,244 objects, 2,504,369,794 bytes

可以看到这里面有 1100 个对象的大小都超过了 85000 字节，总共加起来快 2.3GB 了，所以问题出在这里。随后使用 dumpheap -type System.Byte[] 查看这些具体的对象列表，以便得到具体对象的地址:

    7fa5d5175480     7fa9b3d60c98     18,749,311
    7fa5d6356c20     7fa9b3d60c98      6,734,857
    7fa5d69c3050     7fa9b3d60c98        878,704
    7fa5d6a998e0     7fa9b3d60c98        174,565
    7fa5d6ad21c0     7fa9b3d60c98     18,749,311
    7fa5d7cb3960     7fa9b3d60c98      6,734,857
    7fa5d831fd90     7fa9b3d60c98     10,670,254
    7fa5d8d4ce60     7fa9b3d60c98     10,670,254
    7fa5d9779f30     7fa9b3d60c98     18,749,311
    7fa5da95b6d0     7fa9b3d60c98     18,749,311
    7fa5dbb3ce70     7fa9b3d60c98      1,931,776
    7fa5dbd6b8e0     7fa9b3d60c98      6,842,488
    7fa5dc3f2178     7fa9b3d60c98      7,773,830
    7fa5dcb5c020     7fa9b3d60c98      7,773,830
    7fa5dd2c5ec8     7fa9b3d60c98      7,773,830
    7fa5dda2fd70     7fa9b3d60c98     12,585,235
    7fa5de6306a8     7fa9b3d60c98      1,889,260
    7fa5de7fdab8     7fa9b3d60c98      1,172,106
    7fa5de91bd68     7fa9b3d60c98        134,508
    7fa5de94dff8     7fa9b3d60c98      8,857,584
    7fa5df1c0808     7fa9b3d60c98      6,842,488
    7fa5df8470a0     7fa9b3d60c98      6,842,488
    7fa5dfecd938     7fa9b3d60c98      6,842,488
    7fa5e05541d0     7fa9b3d60c98      8,857,584
    7fa5e0dc69e0     7fa9b3d60c98      7,773,449
    7fa5e1530710     7fa9b3d60c98      7,773,449
    7fa5e1c9a440     7fa9b3d60c98        980,321
    7fa5e1d899c8     7fa9b3d60c98      1,052,316
    7fa5e1e8a888     7fa9b3d60c98      1,052,316
    7fa5e1f8b748     7fa9b3d60c98      7,373,509
    7fa5e2693a30     7fa9b3d60c98      7,373,509
    7fa5e2d9bd18     7fa9b3d60c98      2,660,027
    7fa5e30253f8     7fa9b3d60c98      2,660,027
    7fa5e32aead8     7fa9b3d60c98      2,783,326
    7fa5e3556358     7fa9b3d60c98      2,783,326
    7fa5e37fdbd8     7fa9b3d60c98      2,783,326
    7fa5e3aa5458     7fa9b3d60c98      6,840,270
    7fa5e412b448     7fa9b3d60c98     17,239,905
    7fa6b27706c8     7fa9b3d60c98          4,120
    7fa6b27716e0     7fa9b3d60c98          4,120
    7fa6b27726f8     7fa9b3d60c98          4,120
    7fa6b2773710     7fa9b3d60c98          4,120
    7fa6b2774728     7fa9b3d60c98          4,120
    7fa6b2775740     7fa9b3d60c98          4,120
    7fa6b2776758     7fa9b3d60c98          4,120
    7fa6b2777770     7fa9b3d60c98          4,120
    7fa6b2778788     7fa9b3d60c98          4,120
    7fa6b27797a0     7fa9b3d60c98          4,120
    7fa6b277a7b8     7fa9b3d60c98          4,120
    7fa6b277b7d0     7fa9b3d60c98          4,120
    7fa6b277c7e8     7fa9b3d60c98          4,120
    7fa6b277d800     7fa9b3d60c98          4,120
    7fa6b277e818     7fa9b3d60c98          4,120
    7fa6b277f830     7fa9b3d60c98          4,120
    7fa6b2790860     7fa9b3d60c98          4,120
    7fa6b2791878     7fa9b3d60c98          4,120
    7fa6b2792890     7fa9b3d60c98          4,120
    7fa6b27938a8     7fa9b3d60c98          4,120
    7fa6b27948c0     7fa9b3d60c98          4,120
    7fa6b27958d8     7fa9b3d60c98          4,120
    7fa6b27968f0     7fa9b3d60c98          4,120
    7fa6b2797908     7fa9b3d60c98          4,120
    7fa6b2798920     7fa9b3d60c98          4,120
    7fa6b2799938     7fa9b3d60c98          4,120
    7fa6b279a950     7fa9b3d60c98          4,120
    7fa6b279b968     7fa9b3d60c98          4,120
    7fa6b279c980     7fa9b3d60c98          4,120
    7fa6b279d998     7fa9b3d60c98          4,120
    7fa6b279e9b0     7fa9b3d60c98          4,120
    7fa6b279f9c8     7fa9b3d60c98          4,120
    7fa6b27a09e0     7fa9b3d60c98          4,120
    7fa6b27a19f8     7fa9b3d60c98          4,120
    7fa6b27a2a10     7fa9b3d60c98          4,120
    7fa6b27a3a28     7fa9b3d60c98          4,120
    7fa6b27a4a40     7fa9b3d60c98          4,120
    7fa6b27a5a58     7fa9b3d60c98          4,120
    7fa6b27a6a70     7fa9b3d60c98          4,120
    7fa6b27a7a88     7fa9b3d60c98          4,120
    7fa6b27a8aa0     7fa9b3d60c98          4,120
    7fa6b27a9ab8     7fa9b3d60c98          4,120
    7fa6b27aaad0     7fa9b3d60c98          4,120
    7fa6b27abae8     7fa9b3d60c98          4,120
    7fa6b27acb00     7fa9b3d60c98          4,120
    7fa6b27adb18     7fa9b3d60c98          4,120
    7fa6b27aeb30     7fa9b3d60c98          4,120
    7fa6b27afb48     7fa9b3d60c98          4,120
    7fa6b27b0b60     7fa9b3d60c98          4,120
    7fa6b27b1b78     7fa9b3d60c98          4,120
    7fa6b27b2b90     7fa9b3d60c98          4,120
    7fa6b27b3ba8     7fa9b3d60c98          4,120
    7fa8b2703018     7fa9b3d60c98          4,120
    7fa8b2704030     7fa9b3d60c98          4,120
    7fa8b2705048     7fa9b3d60c98          4,120
    7fa8b2706060     7fa9b3d60c98          4,120
    7fa8b2707078     7fa9b3d60c98          4,120
    7fa8b2708090     7fa9b3d60c98          4,120
    7fa8b27090a8     7fa9b3d60c98          4,120
    7fa8b270a0c0     7fa9b3d60c98          4,120
    7fa8b270b0d8     7fa9b3d60c98          4,120

Statistics:
          MT  Count     TotalSize Class Name
7fa9b4c13148      1            24 AutoMapper.Configuration.MemberConfigurationExpression<***.Core.***.***, ***.***.***.***.***, System.Byte[]>+<>c__DisplayClass21_0
7fa9b4c13070      1            32 System.Linq.Expressions.Expression1<System.Func<***.***.***.***, System.Byte[]>>
7fa9bb162720      1            32 System.Collections.Generic.List<System.Byte[]>
7fa9b4c12a38      1            48 AutoMapper.Configuration.MemberConfigurationExpression<***.***.***.***, ***.***.***.***.***, System.Byte[]>
7fa9baa24648      1            64 System.Func<Microsoft.Win32.SafeHandles.SafeX509Handle, System.Byte[]>
7fa9b4199a80      1            64 System.Action<AutoMapper.IMemberConfigurationExpression<***.***.***.***, ***.***.***.***.***, System.Byte[]>>
7fa9ba918cf8      1            64 System.Func<System.String, System.Threading.CancellationToken, System.Byte[]>
7fa9bb7434d0      1            64 System.Buffers.SpanAction<System.Char, System.ValueTuple<System.Byte[], System.Int32, System.Int32>>
7fa9ba21c2f8      1            64 System.Func<System.Byte[], System.Security.Cryptography.HashAlgorithm>
7fa9ba3fb308      1            64 System.Action<System.IntPtr, System.Byte[], System.Int32, System.Net.Sockets.SocketError>
7fa9b98b3e90     67         4,288 System.Action<System.Int32, System.Byte[], System.Int32, System.Net.Sockets.SocketFlags, System.Net.Sockets.SocketError>
7fa9b6ad65e8     55        50,376 System.Byte[][]
7fa9b3d60c98 68,716 3,046,115,321 System.Byte[]
Total 68,848 objects, 3,046,170,505 byte

到这一步，你就需要多看看这些对象是什么东西，你可以使用 dumpobj [address] 查看某个对象的具体信息，这里我优先考虑那些比较大的对象，这里我选择了

7fa5d6ad21c0 看看里面有什么东西。

> dumpobj 7fa5d6ad21c0
Name:        System.Byte[]
MethodTable: 00007fa9b3d60c98
EEClass:     00007fa9b3d60c28
Tracked Type: false
Size:        18749311(0x11e177f) bytes
Array:       Rank 1, Number of elements 18749287, Type Byte
Content:     ... ftypisom....isomiso2avc1mp41....free...}mdat..........E....H..,. .#..x264 - core 155 r2917 0a84d98 - H.264/MPEG-4 AVC codec
Fields:
None

从内容可以看到，这似乎是一个视频文件被加载到了一个字节数组，那么我们需要看看谁在持有它，这里我们可以使用 gcroot [address] 来查看它的引用情况。

> gcroot 7fa5d6ad21c0
Caching GC roots, this may take a while.
Subsequent runs of this command will be faster.

Thread da:
    7fa21caae740 7fa9ba5849b9 Serilog.Capturing.PropertyValueConverter.TryConvertEnumerable(System.Object, System.Type, Serilog.Parsing.Destructuring, Serilog.Events.LogEventPropertyValue ByRef)
        r12:
          -> 7fa236bd11a8     System.Collections.Generic.List<***.***.***.CompanyManager>
          -> 7fa5b420b040     ***.***.***.CompanyManager[]
          -> 7fa236bd1c90     ***.***.***.CompanyManager
          -> 7fa33f3b91e0     ***.***.***.CompanyTypeManager
          -> 7fa33fa34ee8     System.Collections.Generic.List<***.***.***.ManualManager>
          -> 7fa33fa375f0     ***.***.***.ManualManager[]
          -> 7fa33fa37058     ***.***.***.ManualManager
          -> 7fa5d6ad21c0     System.Byte[]

... Other Information

    7fa21caaf680 7fa9b93b3c34 Serilog.Core.Logger.ForContext(System.String, System.Object, Boolean)
        r15:
          -> 7fa2b6278930     ***.***.***.Services.BaseResponse
          -> 7fa2b627dc18     ***.***.***.ServiceLogItemManager
          -> 7fa2b627d998     ***.***.***.ServiceLogManager
          -> 7fa236bcac90     ***.***.***.UserManager
          -> 7fa236bccbb0     ***.***.***.UserGroupManager
          -> 7fa236bcd558     ***.***.***.CompanyManager
          -> 7fa236bcdfb8     ***.***.***.CompanyTypeManager
          -> 7fa236bd11a8     System.Collections.Generic.List<***.***.***.CompanyManager>
          -> 7fa5b420b040     ***.***.***.CompanyManager[]
          -> 7fa236bd1c90     ***.***.***.CompanyManager
          -> 7fa33f3b91e0     ***.***.***.CompanyTypeManager
          -> 7fa33fa34ee8     System.Collections.Generic.List<***.***.***.ManualManager>
          -> 7fa33fa375f0     ***.***.***.ManualManager[]
          -> 7fa33fa37058     ***.***.***.ManualManager
          -> 7fa5d6ad21c0     System.Byte[]

    7fa21caaf710 7fa9bb62a3a2 ***.***.***.***.SendNewOrderIntegrationBeforeCommit(***.***.***.***, System.Collections.Generic.List`1<***.***.***.***Manager>)
        rbp-d0: 00007fa21caaf850
          -> 7fa2b6278930     ***.***.***.***.BaseResponse
          -> 7fa2b627dc18     ***.***.***.ServiceLogItemManager
          -> 7fa2b627d998     ***.***.***.ServiceLogManager
          -> 7fa236bcac90     ***.***.***.UserManager
          -> 7fa236bccbb0     ***.***.***.UserGroupManager
          -> 7fa236bcd558     ***.***.***.CompanyManager
          -> 7fa236bcdfb8     ***.***.***.CompanyTypeManager
          -> 7fa236bd11a8     System.Collections.Generic.List<***.***.***.CompanyManager>
          -> 7fa5b420b040     ***.***.***.CompanyManager[]
          -> 7fa236bd1c90     ***.***.***.CompanyManager
          -> 7fa33f3b91e0     ***.***.***.CompanyTypeManager
          -> 7fa33fa34ee8     System.Collections.Generic.List<***.***.***.ManualManager>
          -> 7fa33fa375f0     ***.***.***.ManualManager[]
          -> 7fa33fa37058     ***.***.***.ManualManager
          -> 7fa5d6ad21c0     System.Byte[]

Found 32 unique roots.

看起来这里的 Byte[] 最后是被某个 BaseResponse 所持有的，并且被 7fa21caaf680 7fa9b93b3c34 Serilog.Core.Logger.ForContext(System.String, System.Object, Boolean) 调用，其实到这一步我也猜到大概是什么原因了，如果想要获取更加详细的信息，可以切换到对应线程执行 clrstack 查看调用堆栈。

这里 Thread Number 是 da，使用 threads 指令查看所有线程:

> threads
*0 0x0001 (1)
 1 0x0007 (7)
 2 0x0008 (8)
 3 0x0009 (9)
 4 0x000A (10)
 5 0x000B (11)
 6 0x000C (12)
 7 0x000D (13)
 8 0x000E (14)
 9 0x000F (15)
 10 0x0010 (16)
 11 0x0011 (17)
 12 0x0013 (19)
 13 0x0017 (23)
 14 0x0018 (24)
 15 0x0019 (25)
 16 0x001B (27)
 17 0x001D (29)
 18 0x001E (30)
 19 0x001F (31)
 20 0x0020 (32)
 21 0x0024 (36)
 22 0x0025 (37)
 23 0x0026 (38)
 24 0x002A (42)
 25 0x004A (74)
 26 0x00BB (187)
 27 0x00BC (188)
 28 0x00BD (189)
 29 0x00CE (206)
 30 0x00D1 (209)
 31 0x00D2 (210)
 32 0x00D4 (212)
 33 0x00D5 (213)
 34 0x00D6 (214)
 35 0x00DA (218)
 36 0x00DB (219)

发现 0x00DA 对应的是 35 号线程，使用命令 setthread 35 切换到对应线程，执行 clrstack 指令查看调用堆栈。

> setthread 35
> clrstack
OS Thread Id: 0xda (35)
        Child SP               IP Call Site
00007FA21CAACE00 00007faa2ce99f63 [InlinedCallFrame: 00007fa21caace00] Interop+Sys.ReceiveMessage(System.Runtime.InteropServices.SafeHandle, MessageHeader*, System.Net.Sockets.SocketFlags, Int64*)
00007FA21CAACE00 00007fa9ba5ddc38 [InlinedCallFrame: 00007fa21caace00] Interop+Sys.ReceiveMessage(System.Runtime.InteropServices.SafeHandle, MessageHeader*, System.Net.Sockets.SocketFlags, Int64*)
00007FA21CAACDF0 00007FA9BA5DDC38 ILStubClass.IL_STUB_PInvoke(System.Runtime.InteropServices.SafeHandle, MessageHeader*, System.Net.Sockets.SocketFlags, Int64*)
00007FA21CAACE90 00007FA9BA5DDAE9 System.Net.Sockets.SocketPal.SysReceive(System.Net.Sockets.SafeSocketHandle, System.Net.Sockets.SocketFlags, System.Span`1<Byte>, Byte[], Int32 ByRef, System.Net.Sockets.SocketFlags ByRef, Error ByRef) [/_/src/libraries/System.Net.Sockets/src/System/Net/Sockets/SocketPal.Unix.cs @ 158]
00007FA21CAACF30 00007FA9BA5DD671 System.Net.Sockets.SocketPal.TryCompleteReceiveFrom(System.Net.Sockets.SafeSocketHandle, System.Span`1<Byte>, System.Collections.Generic.IList`1<System.ArraySegment`1<Byte>>, System.Net.Sockets.SocketFlags, Byte[], Int32 ByRef, Int32 ByRef, System.Net.Sockets.SocketFlags ByRef, System.Net.Sockets.SocketError ByRef) [/_/src/libraries/System.Net.Sockets/src/System/Net/Sockets/SocketPal.Unix.cs @ 834]
00007FA21CAACFA0 00007FA9BAD28C59 System.Net.Sockets.SocketAsyncContext.ReceiveFrom(System.Memory`1<Byte>, System.Net.Sockets.SocketFlags ByRef, Byte[], Int32 ByRef, Int32, Int32 ByRef) [/_/src/libraries/System.Net.Sockets/src/System/Net/Sockets/SocketAsyncContext.Unix.cs @ 1540]
00007FA21CAAD030 00007FA9BAD28ABB System.Net.Sockets.SocketPal.Receive(System.Net.Sockets.SafeSocketHandle, Byte[], Int32, Int32, System.Net.Sockets.SocketFlags, Int32 ByRef)
00007FA21CAAD0B0 00007FA9BAD28857 System.Net.Sockets.Socket.Receive(Byte[], Int32, Int32, System.Net.Sockets.SocketFlags, System.Net.Sockets.SocketError ByRef)
00007FA21CAAD130 00007FA9BAD28549 System.Net.Sockets.NetworkStream.Read(Byte[], Int32, Int32) [/_/src/libraries/System.Net.Sockets/src/System/Net/Sockets/NetworkStream.cs @ 231]
00007FA21CAAD180 00007FA9BAD2DD75 System.IO.Stream.Read(System.Span`1<Byte>) [/_/src/libraries/System.Private.CoreLib/src/System/IO/Stream.cs @ 667]
00007FA21CAAD1D0 00007FA9BA5DC52B System.Net.Sockets.NetworkStream.Read(System.Span`1<Byte>) [/_/src/libraries/System.Net.Sockets/src/System/Net/Sockets/NetworkStream.cs @ 246]
00007FA21CAAD220 00007FA9BAD2DB78 Microsoft.Data.SqlClient.SNI.SslOverTdsStream.Read(System.Span`1<Byte>) [/_/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SNI/SslOverTdsStream.NetCoreApp.cs @ 32]
00007FA21CAAD290 00007FA9BAD39691 System.Net.Security.SslStream+<EnsureFullTlsFrameAsync>d__186`1[[System.Net.Security.SyncReadWriteAdapter, System.Net.Security]].MoveNext()
00007FA21CAAD310 00007FA9BAD39477 System.Runtime.CompilerServices.AsyncMethodBuilderCore.Start[[System.Net.Security.SslStream+<EnsureFullTlsFrameAsync>d__186`1[[System.Net.Security.SyncReadWriteAdapter, System.Net.Security]], System.Net.Security]](<EnsureFullTlsFrameAsync>d__186`1<System.Net.Security.SyncReadWriteAdapter> ByRef) [/_/src/libraries/System.Private.CoreLib/src/System/Runtime/CompilerServices/AsyncMethodBuilderCore.cs @ 38]
00007FA21CAAD350 00007FA9BAD393D7 System.Net.Security.SslStream.EnsureFullTlsFrameAsync[[System.Net.Security.SyncReadWriteAdapter, System.Net.Security]](System.Net.Security.SyncReadWriteAdapter)
00007FA21CAAD3C0 00007FA9BAD38A39 System.Net.Security.SslStream+<ReadAsyncInternal>d__188`1[[System.Net.Security.SyncReadWriteAdapter, System.Net.Security]].MoveNext() [/_/src/libraries/System.Net.Security/src/System/Net/Security/SslStream.Implementation.cs @ 963]
00007FA21CAAD520 00007FA9BAD385D7 System.Runtime.CompilerServices.AsyncMethodBuilderCore.Start[[System.Net.Security.SslStream+<ReadAsyncInternal>d__188`1[[System.Net.Security.SyncReadWriteAdapter, System.Net.Security]], System.Net.Security]](<ReadAsyncInternal>d__188`1<System.Net.Security.SyncReadWriteAdapter> ByRef) [/_/src/libraries/System.Private.CoreLib/src/System/Runtime/CompilerServices/AsyncMethodBuilderCore.cs @ 38]
00007FA21CAAD560 00007FA9BAD3847B System.Net.Security.SslStream.Read(Byte[], Int32, Int32) [/_/src/libraries/System.Net.Security/src/System/Net/Security/SslStream.cs @ 767]
00007FA21CAAD620 00007FA9BAD27C43 Microsoft.Data.SqlClient.SNI.SNITCPHandle.Receive(Microsoft.Data.SqlClient.SNI.SNIPacket ByRef, Int32) [/_/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SNI/SNITcpHandle.cs @ 799]
00007FA21CAAD780 00007FA9BAD279FA Microsoft.Data.SqlClient.SNI.TdsParserStateObjectManaged.ReadSyncOverAsync(Int32, UInt32 ByRef) [/_/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/TdsParserStateObjectManaged.cs @ 219]
00007FA21CAAD7D0 00007FA9BAD276EF Microsoft.Data.SqlClient.TdsParserStateObject.ReadSniSyncOverAsync() [/_/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/TdsParserStateObject.cs @ 1223]
00007FA21CAAD820 00007FA9BAD2760C Microsoft.Data.SqlClient.TdsParserStateObject.TryReadNetworkPacket() [/_/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/TdsParserStateObject.cs @ 1181]
00007FA21CAAD840 00007FA9BAD37E54 Microsoft.Data.SqlClient.TdsParserStateObject.TryPrepareBuffer() [/_/src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/TdsParserStateObject.cs @ 901]
00007FA21CAAD860 00007FA9BAD3C748 Microsoft.Data.SqlClient.TdsParserStateObject.TryReadUInt32(UInt32 ByRef) [/_/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/TdsParserStateObject.cs @ 632]
00007FA21CAAD890 00007FA9BAD7C73C Microsoft.Data.SqlClient.TdsParserStateObject.TryReadPlpLength(Boolean, UInt64 ByRef) [/_/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/TdsParserStateObject.cs @ 908]
00007FA21CAAD8D0 00007FA9BAD7CA11 Microsoft.Data.SqlClient.TdsParserStateObject.TryReadPlpBytes(Byte[] ByRef, Int32, Int32, Int32 ByRef) [/_/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/TdsParserStateObject.cs @ 1054]
00007FA21CAAD930 00007FA9BAD6D9A8 Microsoft.Data.SqlClient.TdsParser.TryReadSqlValue(Microsoft.Data.SqlClient.SqlBuffer, Microsoft.Data.SqlClient.SqlMetaDataPriv, Int32, Microsoft.Data.SqlClient.TdsParserStateObject, Microsoft.Data.SqlClient.SqlCommandColumnEncryptionSetting, System.String, Microsoft.Data.SqlClient.SqlCommand) [/_/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/TdsParser.cs @ 6054]
00007FA21CAAD9B0 00007FA9BAD6CF76 Microsoft.Data.SqlClient.SqlDataReader.TryReadColumnInternal(Int32, Boolean, Boolean) [/_/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SqlDataReader.cs @ 3915]
00007FA21CAADA40 00007FA9BAD6C92A Microsoft.Data.SqlClient.SqlDataReader.GetValueInternal(Int32) [/_/src/Microsoft.Data.SqlClient/netcore/src/Microsoft/Data/SqlClient/SqlDataReader.cs @ 2719]
00007FA21CAADA60 00007FA9BAD6C864 Microsoft.Data.SqlClient.SqlDataReader.GetValue(Int32)
00007FA21CAADAA0 00007FA9BAD6C26A ***.DataAccess.NeoBaseDAL`1[[System.__Canon, System.Private.CoreLib]].LoadObject(System.Data.IDataReader)
00007FA21CAADBE0 00007FA9BAD7E4C9 ***.DataAccess.NeoBaseDAL`1[[System.__Canon, System.Private.CoreLib]].LoadObjects(Microsoft.Data.SqlClient.SqlDataReader)
00007FA21CAADC20 00007FA9BAD7D6BB ***.DataAccess.NeoBaseDAL`1[[System.__Canon, System.Private.CoreLib]].GetData(System.__Canon, ***.Domain.FiltroPaginador)
00007FA21CAADCC0 00007FA9BAD7D12E ***.Domain.NeoBaseManager`1[[System.__Canon, System.Private.CoreLib]].GetData(System.__Canon)
00007FA21CAADD10 00007FA9BB66EAFD ***.***.***.***.get_ListManual()
00007FA21CAADFC0 00007faa2c663c13 [DebuggerU2MCatchHandlerFrame: 00007fa21caadfc0]
00007FA21CAAE0C8 00007faa2c663c13 [HelperMethodFrame_PROTECTOBJ: 00007fa21caae0c8] System.RuntimeMethodHandle.InvokeMethod(System.Object, System.Span`1<System.Object> ByRef, System.Signature, Boolean, Boolean)
00007FA21CAAE240 00007FA9B49E9B3C System.Reflection.RuntimeMethodInfo.Invoke(System.Object, System.Reflection.BindingFlags, System.Reflection.Binder, System.Object[], System.Globalization.CultureInfo) [/_/src/coreclr/System.Private.CoreLib/src/System/Reflection/RuntimeMethodInfo.cs @ 435]
00007FA21CAAE2C0 00007FA9BB644BB8 Serilog.Capturing.PropertyValueConverter+<GetProperties>d__22.MoveNext()
00007FA21CAAE340 00007FA9B49A7C29 System.Collections.Generic.LargeArrayBuilder`1[[System.__Canon, System.Private.CoreLib]].AddRange(System.Collections.Generic.IEnumerable`1<System.__Canon>) [/_/src/libraries/Common/src/System/Collections/Generic/LargeArrayBuilder.SpeedOpt.cs @ 116]
00007FA21CAAE3A0 00007FA9B40C0EA5 System.Collections.Generic.EnumerableHelpers.ToArray[[System.__Canon, System.Private.CoreLib]](System.Collections.Generic.IEnumerable`1<System.__Canon>) [/_/src/libraries/Common/src/System/Collections/Generic/EnumerableHelpers.Linq.cs @ 85]
00007FA21CAAE410 00007FA9BA584DD7 Serilog.Capturing.PropertyValueConverter.TryConvertCompilerGeneratedType(System.Object, System.Type, Serilog.Parsing.Destructuring, Serilog.Events.LogEventPropertyValue ByRef)
00007FA21CAAE460 00007FA9B93B4090 Serilog.Capturing.PropertyValueConverter.CreatePropertyValue(System.Object, Serilog.Parsing.Destructuring, Int32)
00007FA21CAAE4D0 00007FA9BB644CCD Serilog.Capturing.PropertyValueConverter+<GetProperties>d__22.MoveNext()
00007FA21CAAE550 00007FA9B49A7C29 System.Collections.Generic.LargeArrayBuilder`1[[System.__Canon, System.Private.CoreLib]].AddRange(System.Collections.Generic.IEnumerable`1<System.__Canon>) [/_/src/libraries/Common/src/System/Collections/Generic/LargeArrayBuilder.SpeedOpt.cs @ 116]
00007FA21CAAE5B0 00007FA9B40C0EA5 System.Collections.Generic.EnumerableHelpers.ToArray[[System.__Canon, System.Private.CoreLib]](System.Collections.Generic.IEnumerable`1<System.__Canon>) [/_/src/libraries/Common/src/System/Collections/Generic/EnumerableHelpers.Linq.cs @ 85]
00007FA21CAAE620 00007FA9BA584DD7 Serilog.Capturing.PropertyValueConverter.TryConvertCompilerGeneratedType(System.Object, System.Type, Serilog.Parsing.Destructuring, Serilog.Events.LogEventPropertyValue ByRef)
00007FA21CAAE670 00007FA9B93B4090 Serilog.Capturing.PropertyValueConverter.CreatePropertyValue(System.Object, Serilog.Parsing.Destructuring, Int32)
00007FA21CAAE6E0 00007FA9BB66EA50 Serilog.Capturing.PropertyValueConverter+DepthLimiter.CreatePropertyValue(System.Object, Serilog.Parsing.Destructuring)
00007FA21CAAE740 00007FA9BA5849B9 Serilog.Capturing.PropertyValueConverter.TryConvertEnumerable(System.Object, System.Type, Serilog.Parsing.Destructuring, Serilog.Events.LogEventPropertyValue ByRef)
00007FA21CAAE7A0 00007FA9B93B403D Serilog.Capturing.PropertyValueConverter.CreatePropertyValue(System.Object, Serilog.Parsing.Destructuring, Int32)
00007FA21CAAE810 00007FA9BB644CCD Serilog.Capturing.PropertyValueConverter+<GetProperties>d__22.MoveNext()
00007FA21CAAE890 00007FA9B49A7C29 System.Collections.Generic.LargeArrayBuilder`1[[System.__Canon, System.Private.CoreLib]].AddRange(System.Collections.Generic.IEnumerable`1<System.__Canon>) [/_/src/libraries/Common/src/System/Collections/Generic/LargeArrayBuilder.SpeedOpt.cs @ 116]
00007FA21CAAE8F0 00007FA9B40C0EA5 System.Collections.Generic.EnumerableHelpers.ToArray[[System.__Canon, System.Private.CoreLib]](System.Collections.Generic.IEnumerable`1<System.__Canon>) [/_/src/libraries/Common/src/System/Collections/Generic/EnumerableHelpers.Linq.cs @ 85]
00007FA21CAAE960 00007FA9BA584DD7 Serilog.Capturing.PropertyValueConverter.TryConvertCompilerGeneratedType(System.Object, System.Type, Serilog.Parsing.Destructuring, Serilog.Events.LogEventPropertyValue ByRef)
00007FA21CAAE9B0 00007FA9B93B4090 Serilog.Capturing.PropertyValueConverter.CreatePropertyValue(System.Object, Serilog.Parsing.Destructuring, Int32)
00007FA21CAAEA20 00007FA9BB644CCD Serilog.Capturing.PropertyValueConverter+<GetProperties>d__22.MoveNext()
00007FA21CAAEAA0 00007FA9B49A7C29 System.Collections.Generic.LargeArrayBuilder`1[[System.__Canon, System.Private.CoreLib]].AddRange(System.Collections.Generic.IEnumerable`1<System.__Canon>) [/_/src/libraries/Common/src/System/Collections/Generic/LargeArrayBuilder.SpeedOpt.cs @ 116]
00007FA21CAAEB00 00007FA9B40C0EA5 System.Collections.Generic.EnumerableHelpers.ToArray[[System.__Canon, System.Private.CoreLib]](System.Collections.Generic.IEnumerable`1<System.__Canon>) [/_/src/libraries/Common/src/System/Collections/Generic/EnumerableHelpers.Linq.cs @ 85]
00007FA21CAAEB70 00007FA9BA584DD7 Serilog.Capturing.PropertyValueConverter.TryConvertCompilerGeneratedType(System.Object, System.Type, Serilog.Parsing.Destructuring, Serilog.Events.LogEventPropertyValue ByRef)
00007FA21CAAEBC0 00007FA9B93B4090 Serilog.Capturing.PropertyValueConverter.CreatePropertyValue(System.Object, Serilog.Parsing.Destructuring, Int32)
00007FA21CAAEC30 00007FA9BB644CCD Serilog.Capturing.PropertyValueConverter+<GetProperties>d__22.MoveNext()
00007FA21CAAECB0 00007FA9B49A7C29 System.Collections.Generic.LargeArrayBuilder`1[[System.__Canon, System.Private.CoreLib]].AddRange(System.Collections.Generic.IEnumerable`1<System.__Canon>) [/_/src/libraries/Common/src/System/Collections/Generic/LargeArrayBuilder.SpeedOpt.cs @ 116]
00007FA21CAAED10 00007FA9B40C0EA5 System.Collections.Generic.EnumerableHelpers.ToArray[[System.__Canon, System.Private.CoreLib]](System.Collections.Generic.IEnumerable`1<System.__Canon>) [/_/src/libraries/Common/src/System/Collections/Generic/EnumerableHelpers.Linq.cs @ 85]
00007FA21CAAED80 00007FA9BA584DD7 Serilog.Capturing.PropertyValueConverter.TryConvertCompilerGeneratedType(System.Object, System.Type, Serilog.Parsing.Destructuring, Serilog.Events.LogEventPropertyValue ByRef)
00007FA21CAAEDD0 00007FA9B93B4090 Serilog.Capturing.PropertyValueConverter.CreatePropertyValue(System.Object, Serilog.Parsing.Destructuring, Int32)
00007FA21CAAEE40 00007FA9BB644CCD Serilog.Capturing.PropertyValueConverter+<GetProperties>d__22.MoveNext()
00007FA21CAAEEC0 00007FA9B49A7C29 System.Collections.Generic.LargeArrayBuilder`1[[System.__Canon, System.Private.CoreLib]].AddRange(System.Collections.Generic.IEnumerable`1<System.__Canon>) [/_/src/libraries/Common/src/System/Collections/Generic/LargeArrayBuilder.SpeedOpt.cs @ 116]
00007FA21CAAEF20 00007FA9B40C0EA5 System.Collections.Generic.EnumerableHelpers.ToArray[[System.__Canon, System.Private.CoreLib]](System.Collections.Generic.IEnumerable`1<System.__Canon>) [/_/src/libraries/Common/src/System/Collections/Generic/EnumerableHelpers.Linq.cs @ 85]
00007FA21CAAEF90 00007FA9BA584DD7 Serilog.Capturing.PropertyValueConverter.TryConvertCompilerGeneratedType(System.Object, System.Type, Serilog.Parsing.Destructuring, Serilog.Events.LogEventPropertyValue ByRef)
00007FA21CAAEFE0 00007FA9B93B4090 Serilog.Capturing.PropertyValueConverter.CreatePropertyValue(System.Object, Serilog.Parsing.Destructuring, Int32)
00007FA21CAAF050 00007FA9BB644CCD Serilog.Capturing.PropertyValueConverter+<GetProperties>d__22.MoveNext()
00007FA21CAAF0D0 00007FA9B49A7C29 System.Collections.Generic.LargeArrayBuilder`1[[System.__Canon, System.Private.CoreLib]].AddRange(System.Collections.Generic.IEnumerable`1<System.__Canon>) [/_/src/libraries/Common/src/System/Collections/Generic/LargeArrayBuilder.SpeedOpt.cs @ 116]
00007FA21CAAF130 00007FA9B40C0EA5 System.Collections.Generic.EnumerableHelpers.ToArray[[System.__Canon, System.Private.CoreLib]](System.Collections.Generic.IEnumerable`1<System.__Canon>) [/_/src/libraries/Common/src/System/Collections/Generic/EnumerableHelpers.Linq.cs @ 85]
00007FA21CAAF1A0 00007FA9BA584DD7 Serilog.Capturing.PropertyValueConverter.TryConvertCompilerGeneratedType(System.Object, System.Type, Serilog.Parsing.Destructuring, Serilog.Events.LogEventPropertyValue ByRef)
00007FA21CAAF1F0 00007FA9B93B4090 Serilog.Capturing.PropertyValueConverter.CreatePropertyValue(System.Object, Serilog.Parsing.Destructuring, Int32)
00007FA21CAAF260 00007FA9BB644CCD Serilog.Capturing.PropertyValueConverter+<GetProperties>d__22.MoveNext()
00007FA21CAAF2E0 00007FA9B49A7C29 System.Collections.Generic.LargeArrayBuilder`1[[System.__Canon, System.Private.CoreLib]].AddRange(System.Collections.Generic.IEnumerable`1<System.__Canon>) [/_/src/libraries/Common/src/System/Collections/Generic/LargeArrayBuilder.SpeedOpt.cs @ 116]
00007FA21CAAF340 00007FA9B40C0EA5 System.Collections.Generic.EnumerableHelpers.ToArray[[System.__Canon, System.Private.CoreLib]](System.Collections.Generic.IEnumerable`1<System.__Canon>) [/_/src/libraries/Common/src/System/Collections/Generic/EnumerableHelpers.Linq.cs @ 85]
00007FA21CAAF3B0 00007FA9BA584DD7 Serilog.Capturing.PropertyValueConverter.TryConvertCompilerGeneratedType(System.Object, System.Type, Serilog.Parsing.Destructuring, Serilog.Events.LogEventPropertyValue ByRef)
00007FA21CAAF400 00007FA9B93B4090 Serilog.Capturing.PropertyValueConverter.CreatePropertyValue(System.Object, Serilog.Parsing.Destructuring, Int32)
00007FA21CAAF470 00007FA9BB644CCD Serilog.Capturing.PropertyValueConverter+<GetProperties>d__22.MoveNext()
00007FA21CAAF4F0 00007FA9B49A7C29 System.Collections.Generic.LargeArrayBuilder`1[[System.__Canon, System.Private.CoreLib]].AddRange(System.Collections.Generic.IEnumerable`1<System.__Canon>) [/_/src/libraries/Common/src/System/Collections/Generic/LargeArrayBuilder.SpeedOpt.cs @ 116]
00007FA21CAAF550 00007FA9B40C0EA5 System.Collections.Generic.EnumerableHelpers.ToArray[[System.__Canon, System.Private.CoreLib]](System.Collections.Generic.IEnumerable`1<System.__Canon>) [/_/src/libraries/Common/src/System/Collections/Generic/EnumerableHelpers.Linq.cs @ 85]
00007FA21CAAF5C0 00007FA9BA584DD7 Serilog.Capturing.PropertyValueConverter.TryConvertCompilerGeneratedType(System.Object, System.Type, Serilog.Parsing.Destructuring, Serilog.Events.LogEventPropertyValue ByRef)
00007FA21CAAF610 00007FA9B93B4090 Serilog.Capturing.PropertyValueConverter.CreatePropertyValue(System.Object, Serilog.Parsing.Destructuring, Int32)
00007FA21CAAF680 00007FA9B93B3C34 Serilog.Core.Logger.ForContext(System.String, System.Object, Boolean)
00007FA21CAAF710 00007FA9BB62A3A2 ***.***.***.***.SendNewOrderIntegrationBeforeCommit(***.***.***.***, System.Collections.Generic.List`1<***.***.***.***>)
00007FA21CAAF930 00007FA9BB60EDAD ***.***.***.***.GenerateOrder(***.***.***.***, Boolean)
00007FA21CAAFD90 00007FA9BB60910F ***.***.***.***.GenerateOrderManuallyWithSelectedItems(***.***.***.***, ***.***.***.***)
00007FA21CAAFE20 00007FA9BB608F44 ***.***.***.***.GenerateOrder(***.***.***.***, Int64)
00007FA21CAAFE60 00007FA9BB605B29 ***.***.***.Controllers.OrderController.GenerateOrder(***.***.***.***.*********)
... 省略
00007FA21CAB11F0 00007FA9BA585082 NewRelic.Providers.Wrapper.AspNetCore.WrapPipelineMiddleware.Invoke(Microsoft.AspNetCore.Http.HttpContext)
00007FA21CAB1240 00007FA9BA56EDB1 Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http.HttpProtocol+<ProcessRequests>d__226`1[[System.__Canon, System.Private.CoreLib]].MoveNext()
00007FA21CAB13E0 00007FA9B70753AD System.Threading.ExecutionContext.RunFromThreadPoolDispatchLoop(System.Threading.Thread, System.Threading.ExecutionContext, System.Threading.ContextCallback, System.Object) [/_/src/libraries/System.Private.CoreLib/src/System/Threading/ExecutionContext.cs @ 268]
00007FA21CAB1420 00007FA9BADE97EA System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[[System.Threading.Tasks.VoidTaskResult, System.Private.CoreLib],[Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http.HttpProtocol+<ProcessRequests>d__226`1[[System.__Canon, System.Private.CoreLib]], Microsoft.AspNetCore.Server.Kestrel.Core]].MoveNext(System.Threading.Thread) [/_/src/libraries/System.Private.CoreLib/src/System/Runtime/CompilerServices/AsyncTaskMethodBuilderT.cs @ 332]
00007FA21CAB1470 00007FA9B6FD2073 System.Threading.ThreadPoolWorkQueue.Dispatch() [/_/src/libraries/System.Private.CoreLib/src/System/Threading/ThreadPoolWorkQueue.cs @ 724]
00007FA21CAB14E0 00007FA9B6FD0230 System.Threading.PortableThreadPool+WorkerThread.WorkerThreadStart() [/_/src/libraries/System.Private.CoreLib/src/System/Threading/PortableThreadPool.WorkerThread.cs @ 107]
00007FA21CAB16F0 00007faa2c663c13 [DebuggerU2MCatchHandlerFrame: 00007fa21cab16f0]

找到对应方法 SendNewOrderIntegrationBeforeCommit 里面调用 Serilog.Core.Logger.ForContext 的地方，发现了以下代码:

result objBaseResponse = ***.***(***, ***.IdOrder);
Log..ForContext("{@Result}", objBaseResponse, true)
    .Information("SendNewOrderIntegration end");

3. 结论

调查 objBaseResponse 得知，里面手搓了类似于导航属性的玩意儿，而且还有循环依赖，这样一旦走到这个打日志的地方，就会遍历对象的属性，与此同时还会触发从数据库获取数据的操作，也就是会导致入站流量飙升。

Create a logger that enriches log events with the specified property.
Params:
propertyName – The name of the property. Must be non-empty.
value – The property value.
destructureObjects – If true, the value will be serialized as a structured object if possible; if false, the object will be recorded as a scalar or simple array.

本来不指定 true 值可能都不会有问题，一旦指定了 true 值，序列化对象的时候就会完全遍历里面的子对象。

4. 资料

修复 Parallels Desktop 无网络的问题

Thu, 28 Dec 2023 22:29:00 +0000

问题

更新了 Paralles Desktop 之后，发现 Windows 虚拟机和 Ubuntu 虚拟机均无法找到网卡，无法连接网络。

解决

打开 Parallels Desktop 对应虚拟机的设置，找到网络选项，点击高级，重新生成 MAC 地址，然后重启虚拟机即可恢复正常。

在 .NET 5 以后的 HttpClient 超时问题

Mon, 12 Jun 2023 23:43:00 +0000

背景

起因是朋友在使用深信服的 Easy Connect 连接到内网之后，使用 HttpClient 访问对应内网的 API 站点均返回 System.Net.Sockets.SocketException (10060) 异常。但使用其他语言的原生 HTTP 库，比如 Golang / Python / Java 都可以正常访问，因此怀疑是 HttpClient 的问题。

原因

经过搜索得知，这是存在于 .NET 5 及其以上版本的问题，在 .NET 3.1 是不存在这种情况的。底层原因是从 .NET 5 开始，HttpClient 的底层实现使用的是双栈套接字(Dual-Stack Sockets)，在某些情况下，你的网卡获得了 IPv6 地址，但是 VPN 处于某种原因不能正确地处理 IPv6 请求时就会导致上述情况的发生。在 PR #55012 中，说明了这种情况:

Introduces an AppContext switch System.Net.DisableIPv6 and environment variable DOTNET_SYSTEM_NET_DISABLEIPV6 to emulate the lack of OS-level IPv6 support. This is useful to workaround dual-stack socket issues when the OS reports support of IPv6, but some other underlying infrastructure element (typically VPN) doesn’t function well with IPv6 request.

For consistency, this switch also impacts NameResolution and Ping, not only Sockets.

解决

根据 PR 提到的信息，我们只需要在程序启动的时候使用以下代码禁用 IPv6 栈即可解决。

AppContext.SetSwitch("System.Net.DisableIPv6",true);

WCF 服务容器化的一些问题

Sat, 31 Dec 2022 09:43:00 +0000

背景

目前项目当中存有 .NET Framework 和 .NET Core 两种类型的项目，但是都需要进行容器化将其分别部署在 Windows 集群和 Linux 集群当中。在 WCF 进行容器化的时候，遇到了以下几个问题：

某些服务使用到了 WSHttpBinding 保护服务安全，要在容器里面加载 SSL 证书。
WCF 服务的日志，如何重定向到标准输出流?

解决

问题一

关于第一个问题，最开始我觉得只需要将 WCF 服务打包出来，暴露一个 HTTP 端点。然后在这个 WCF 服务的前面再加一层 NGINX，具体的证书由 NGINX 进行管理。大概的流程就是 API Caller --> (HTTPS)F5 --> (HTTPS)NGINX --> (HTTP)WCF，按照这样的方式部署之后，对应的服务端点无法访问，具体的错误提示的是 Schema 不匹配。因为 WSHttpBinding 强制使用 HTTPS，如果我仅暴露一个 HTTP 端点，是无法绕过 WSHttpBinding 的限制的。

随后我又在网上找到了这篇文章，该文章的思路就是实现一个 CustomBinding，然后在里面忽略掉这块验证，经过我的测试无法满足需求。

上述方法行不通就只有创建一个自签 SSL 证书，并导入到 IIS 当中，随后在 NGINX 启用 SSL 转发，目前看来已经解决这个问题。下面是我的 Dockerfile 以及入口点的 PowerShell 脚本，脚本里面包含了证书生成与导入方法。

dockerfile:

FROM mcr.microsoft.com/dotnet/framework/sdk:4.8 AS build
WORKDIR /build

COPY . .
RUN cd ./src; nuget restore
WORKDIR /build/src/ProjectName
RUN msbuild Wcf.csproj /p:Configuration=Release -r:False

FROM mcr.microsoft.com/dotnet/framework/wcf:4.8-windowsservercore-ltsc2019 AS runtime
WORKDIR /WcfService
EXPOSE 443

COPY --from=build /build/wcf-entrypoint.ps1 .
COPY --from=build /build/src/ProjectName .

ENTRYPOINT ["powershell", ".\\wcf-entrypoint.ps1"]

entrypoint.ps1

$hostName = $env:HostName
$port = "443"
$password = "Your password."
$storeLocation = "Cert:\LocalMachine\My"
$certificate = New-SelfSignedCertificate -DnsName $hostName -CertStoreLocation $storeLocation
$thumbPrint = $certificate.Thumbprint
$certificatePath = ("cert:\localmachine\my\" + $certificate.Thumbprint)
$bindingInformation = "*:" + $port + ":" + $hostName
$securedString = ConvertTo-SecureString -String $password -Force -AsPlainText
Export-PfxCertificate -FilePath "C:\WcfService\temp.pfx" -Cert $certificatePath -Password $securedString
Import-PfxCertificate -FilePath "C:\WcfService\temp.pfx" -CertStoreLocation "Cert:\LocalMachine\Root" -Password $securedString
New-IISSite -Name "WcfService" -PhysicalPath C:\WcfService -BindingInformation $bindingInformation -CertificateThumbPrint $thumbPrint -CertStoreLocation $storeLocation -Protocol https

# Entry point for the application.
&C:\\ServiceMonitor.exe w3svc

问题二

由于 WCF 是托管在 IIS 里面的，我们的日志信息是无法输出到标准输出流的。所以我们就采取了一个曲线救国的方案，使用一个旁路程序，我们的日志输出到文件当中，由这个旁路程序监控文件变动，然后将变动的内容输出到标准输出流里面。

这个功能有点像 Logstash，你可能会说我们为什么不直接用 Logstash 收集这些日志呢？因为我们所有项目的日志，都是由基础架构团队统一处理。规范就是我们日志必须输出到标准输出流，并且日志是结构化日志，还需带上一些 ProjectId 之类的标记信息。然后由注入的 Sidecar 容器统一收集、处理、上报到 Garylog 平台。

回到正题，最开始我找到了微软实现的一个开源工具，它的本意就是为一些 Windows 容器解决日志收集问题的。

项目的地址是: https://github.com/microsoft/windows-container-tools。

使用这个工具，指定好路径与需要运行的程序，替换 Dockerfile 的入口点即可解决问题。微软那个工具的核心，就是使用了系统提供的文件监听 API，在 .NET 里面也有提供类似的 API，叫做 FileSystemWatcher，如果有兴趣的话，也可以参考 C++ 的源码和思路自己实现。

基于 Godaddy 与阿里云, 一键申请 SSL 证书

Sat, 01 Oct 2022 14:04:00 +0000

部署

acme.sh 的部署我采用的是 docker 方式进行部署，相应的 docker-compose.yaml 文件内容如下。

version: "3"

services:
  acme.sh:
    image: neilpang/acme.sh:latest
    container_name: acme.sh
    command: daemon
    volumes:
      - "./Volume:/acme.sh"
      - "/var/run/docker.sock:/var/run/docker.sock"
    environment:
      - DEPLOY_DOCKER_CONTAINER_LABEL=__nginx__
      - DEPLOY_DOCKER_CONTAINER_RELOAD_CMD="nginx -s reload -c /etc/nginx/nginx.conf"
    restart: always
    networks:
      - internal-network

networks:
  internal-network:
    external: true

其中 ./Volume 是用于挂载证书文件夹的。

证书申请

无论是使用哪种方式申请证书，都需要注册申请人的信息。使用 docker exec -ti <container-name> sh 命令进入到容器内部，随后执行以下命令注册信息。

acme.sh --register-account -m <你的 Email 邮箱地址>

阿里云一键申请

首先登录阿里云的控制台，鼠标移动到右上角头像位置，弹出的下拉中选择 AccessKey 管理。

在新的页面中，选择 创建 AccessKey 即可创建一个新的密钥，记录好 Key 与 Secret 备用。

还是来到 acme.sh 的容器内部，执行以下命令，将阿里云相关的密钥信息导出到环境变量，以便 acme.sh 使用。最后调用 acme.sh --issue 方法开始自动申请证书。

下面的变量以 example.com 域名为例，只要申请成功就是泛解析域名的证书。

# 导出到环境变量。
export Ali_Key="Key"
export Ali_Secret="Secret"

# 申请证书。
acme.sh --issue --dns dns_ali -d example.com -d *.example.com --debug

Godaddy 申请

前置操作也是一样的，需要注册申请人的信息，然后来到 Godaddy 对应的 API Key Managment 页面，选择 Create New API Key，在随后的 Environment 中选择 Production，生成了对应的密钥之后，保存下来。

这里只会显示一次，请记得复制保存对应的密钥信息。

最后进入到 acme.sh 容器，键入以下命令开始申请 SSL 证书。

# 导出到环境变量。
export GD_Key="Key"
export GD_Secret="Secret"

# 申请证书。
acme.sh --issue --dns dns_gd -d example.com -d *.example.com

Reference: acme.sh 搭配 GoDaddy 自動續期 Let’s Encrypt 免費萬用憑證 - 腳印網頁資訊設計

解决被占用的文件夹无法被删除的问题

Fri, 30 Sep 2022 20:44:00 +0000

问题

删除某些文件夹的时候，如果该文件夹正在被某些程序占用，则无法删除。

解决

方法 1

使用 资源管理器 根据文件句柄找到对应的进程，然后手动结束即可。

方法 2

管理员权限打开 PowerShell/命令行提示符/终端，然后输入 del 命令强制删除文件/文件夹。

del <file/dir path>

Reference:

Windows 10文件/文件夹正在使用无法删除的6个解决方法

限制容器在 Docker 输出的日志大小

Tue, 27 Sep 2022 18:09:00 +0000

默认情况下，Docker 容器如果不被销毁的话，那么它的日志会一直保留。如果我们有一个连续运行一年的 NGINX 服务容器，那么它的日志文件就会非常大。 Docker 容器的日志都会挂在到 /var/lib/docker/containers/ 文件夹下，并且以下面的格式进行命名。

/var/lib/docker/containers/<container id>/<container id>-json.log

有三种方式限制日志大小，默认情况是全局设置，这样设置的话会对所有容器进行应用。

方式一

使用文本编辑器编辑 /etc/docker/daemon.json 文件，并在里面加上限制日志容量的相关参数。

{
  "log-driver": "json-file",
  "log-opts": {"max-size": "10m", "max-file": "3"}
}

修改完成之后，需要重启 Docker 服务。

sudo systemctl restart docker

方式二

如果我们的容器是通过 docker run 命令启动的，我们也可以添加相关参数进行限制。

docker run --log-opt max-size=10m --log-opt max-file=5 my-app:latest

方式三

如果你使用的是 Docker Compose 启动对应的容器，可以在 docker-compose.yaml 文件里面定义相应的参数。

version: '3'
services:
  nginx:
    container_name: nginx
    image: nginx
    restart: always
    logging:
      driver: "json-file"
      options:
       max-file: "5"
       max-size: "10m"

使用 NGINX 转发 Github Pages 站点

Tue, 27 Sep 2022 17:59:00 +0000

背景

新的 Blog 是基于 Hugo 搭建的，原始博客内容和生成的静态资源，都是托管在 Github 仓库里面的。但 Github Pages 有时候会抽风，并且访问速度并不是很稳定，因此萌生了使用 NGINX 反向代理 Github Pages 的想法。

解决

基本原理就是将目标站点(Github Pages) 作为一个 upstream 服务，然后 NGINX 负责将所有流量都转发到 upstream 即可。因此，我们的配置文件编写就比较简单了，只需要注意 Host 等信息需要使用 upstream 站点的信息(Github Pages)。

blog-proxy.conf

server{
    listen 80;
    server_name your.blog.com;
    return 301 https://your.blog.com$request_uri;
}

server{
    listen 443 ssl http2;
    server_name your.blog.com;

    ssl_certificate   /opt/cert/sslfile.pem;
    ssl_certificate_key  /opt/cert/sslfile.key;
    ssl_session_timeout 5m;
    ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;

    location / {
        proxy_redirect off;
        proxy_set_header Host yourblog.github.io;    # 填写 Github Pages 的地址。
        proxy_set_header X-Host yourblog.github.io;  # 填写 Github Pages 的地址。
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        # Cache pages.
        proxy_cache_valid 200 206 304 301 302 1d;    # 配置缓存过期时间。
        proxy_cache_valid any 1d;
        proxy_cache_key $uri;

        proxy_pass https://yourblog.github.io;       # 填写 Github Pages 的地址。
    }
}

使用 ssl on 时，NGINX 提示 Warn

Tue, 27 Sep 2022 17:47:00 +0000

现象

部分站点配置启用了 SSL 证书，启动站点的时候提示 warn。

default.conf

server{
    listen 443 ssl http2;
    server_name something.example.com;

    ssl on;
    
    # ...
}

Shell 输出

2022/09/27 09:39:10 [warn] 1#1: the "ssl" directive is deprecated, use the "listen ... ssl" directive instead in /etc/nginx/conf.d/default.conf:5

原因

SSL 不建议作为一个指令使用，而只是 listen 指令的一个参数。

解决

只需要移除掉 ssl on 即可。

new-default.conf

server{
    listen 443 ssl http2;
    server_name something.example.com;
    
    # ...
}

C# 使用 AltCover 获得代码覆盖率 - E2E Test 和 Unit Test

Fri, 12 Aug 2022 19:00:00 +0000

背景

在 CI/CD 流程当中，测试是 CI 中很重要的部分。跟开发人员关系最大的就是单元测试，单元测试编写完成之后，我们可以使用 IDE 或者 dot cover 等工具获得单元测试对于业务代码的覆盖率。不过我们需要一个独立的 CLI 工具，这样我们才能够在 Jenkins 的 CI 流程集成。

端到端测试(End to End Test) 是在 Preview 版本部署完成之后，需要对 Preview 版本进行自动化测试，测试完成之后输出对应的覆盖率报告。根据代码覆盖率报告，我们可以了解 QA 编写的测试用例，是否完整覆盖了所有分支流程。

实现

工具选型

单元测试框架我选择的是 xUnit，它对于 .NET Core 与 .NET Framework 的支持都不错，并且也提供了独立于 IDE 之外的 Console Runner，可以很方便地同 Jenkins 集成。

覆盖率收集工具我选择的是 AltCover，因为它能够收集到部署在 IIS 的 ASP.NET MVC 程序覆盖率指标，这样我们就能够对一些 .NET Framework 老项目进行测试覆盖率汇总计算。AltCover 可以生成多种格式的覆盖率报告，默认格式是 OpenCover。

AltCover 生成的覆盖率报告并不是直接可读的，我们需要一个工具来生成人类可以阅读理解的报告。这里我选择的是 ReportGenerator ，它支持 OpenCover 格式的覆盖率报告，并生成对应的 HTML 文件方便查看。

.NET Framework 集成

我建立了一个简单的 ASP.NET Web API 项目(.NET Framework 4.8)，提供了一个 ApiTestController 控制器，暴露了一个 HTTP POST 方法 CreateOrder，内部逻辑比较简单，就是创建了一个新的 OrderAggregateRoot 实例，然后返回了一个 Success 文本。

/// <summary>
/// ApiTestController.
/// </summary>
[Route("api/test")]
public class ApiTestController : ApiController
{
    private readonly IOrderRepository _orderRepository;

    /// <summary>
    /// <see cref="ApiTestController"/>.
    /// </summary>
    public ApiTestController()
    {
        _orderRepository = new FakeOrderRepository();
    }

    /// <summary>
    /// CreateOrder.
    /// </summary>
    [HttpPost]
    [Route("api/test/create")]
    public IHttpActionResult CreateOrder(CreateOrderInputDto input)
    {
        var newOrder = new OrderAggregateRoot(null, input.Items.Select(x => new OrderItem(x.Price, x.Number)).ToList());
        _orderRepository.InsertAsync(newOrder);

        return Ok("Success");
    }
}

单元测试覆盖率报告

单元测试项目建立比较简单，我建立了一个 AltCoverTestUnitTest 项目，并且添加了 ASP.NET Web API 项目的引用，在内部添加了 AltCover 与 xUnit 相关包的引用。

AltCover 与 xUnit Console Runner 包安装完成之后，对于 .NET Framework 项目来说，会在对应的解决方案目录下面有一个 packages 文件夹，在里面找到 packages\altcover.8.3.838\tools\net472 目录，在这个目录里面有一个 AltCover.exe 的可执行文件，这个就是 AltCover 的 CLI 工具。

而 xUnit Console Runner 对应的 CLI 工具则在 packages\xunit.runner.console.2.4.2\tools\net472 中，根据自己的平台使用 xunit.console.exe 或者是 xunit.console.x86.exe 均可。

随后我们直接使用 MSBuild 命令/IDE 重新编译一下单元测试项目，转到对应的 bin\Debug 目录。在 .bin\Debug 目录中，执行以下命令，将会生成一个新的文件夹，里面会包含修改后的 DLL 文件。

这里 CLI 工具的路径，取决于你的实际路径，就在你解决方案对应的 pacakges 里面。

D:\CoverageTool\AltCoverTestRESFul\packages\altcover.8.3.838\tools\net472\AltCover.exe /o=./__UnitTestWithAltCover -s=Adapter -s=Shouldly -s=Microsoft -t="Shouldly." -s="AltCover.Monitor" -t="System." -s=xunit -e="EmptyFiles" -e=Tests -r=".\_Reports\UnitTestWithAltCover.xml"

这里我解释以下命令，其中 /o 参数指的是修改后 DLL 的输出目录，这里我指定的当前目录下的 __UnitTestWithAltCover 文件夹。-s 参数指的是需要排除的程序集名称，支持通配符与正则表达式。-e 的作用与 -s 类似，具体可以查看 Usage ，最有一个 -r 参数指定报告的输出路径，也就是 OpenCover 格式的 XML 文件输出路径。

为什么需要排除？因为我们的项目可能会引用很多第三方库，这个时候我们为了减少报告的噪音，你也不想在报告里面看到一堆 Microsoft 的代码吧，所以需要手动排除掉这些程序集。

为什么叫做修改后，因为执行命令后，AltCover 会重新生成一个新的 DLL，这个新的 DLL 反编译后可以看到会在每行代码插入 Instance.Visit() 来记录代码的访问路径。

命令执行完成之后，可以看到对应的覆盖率文件生成了，但是这里面覆盖率是 0，因为我们的单元测试还没开始跑。

随后我们执行下面的命令，使用 xUnit Console Runner 运行我们的单元测试项目。

D:\CoverageTool\AltCoverTestRESFul\packages\xunit.runner.console.2.4.2\tools\net47\xunit.console.exe ./__UnitTestWithAltCover/AltCoverTestUnitTest.dll -xml "./_Reports/UnitTestWithAltCoverReport.xml"

第一个参数是需要执行的单元测试 DLL，第二个参数 -xml 说明我们具体的执行结果输出路径，这里我们也输出到了 _Reports 文件夹，这个时候我们就有两个 XML 文件了。

切换到 _Reports 文件夹，打开终端，我们这个时候需要使用 reportgeneator 工具，根据这两个 XML 文件生成人类可读的 HTML 报告。

reportgenerator "-reports:UnitTestWithAltCover.xml;UnitTestWithAltCoverReport.xml" "-targetdir:coveragereport" -reporttypes:Html

上述命令的意思就是根据这两个 xml ，在当前目录的 coveragereport 文件夹，生成一个新的 HTML 报告。

关于 reportgenerator 的安装，可以参考官方的线上工具，它会根据你选择的情况返回适合的安装命令。我自己直接使用的 dotnet tool install --global dotnet-reportgenerator-globaltool 命令进行的安装。

最后的效果:

IIS Web API 覆盖率报告

我们建立一个新的 IIS 站点，并将对应的 DLL 文件放到对应的目录下面。首先暂停对应 IIS 站点，并且停止对应的应用程序池。

随后执行以下命令，将会修改对应的 DLL 文件，以便后续进行覆盖率跟踪，原理跟上面的一样。

D:\CoverageTool\AltCoverTestRESFul\packages\altcover.8.3.838\tools\net472\AltCover.exe --save --inplace -i "D:\TempFiles\IIS\AltCoverTestWebSite\bin" -s=Adapter -s=Shouldly -s="Antlr3.Runtime" -s=Microsoft -t="Shouldly." -s="AltCover.Monitor" -t="System." -s=xunit -e="EmptyFiles" -e=Tests

执行完上述命令以后，将会在终端执行目录下生成两个文件，一个是 coverage.xml ，一个是 coverage.xml.acv 文件，后者是 AltCover 的控制文件，用于记录程序在运行过程中的执行代码路径。

随后启动对应的 IIS 站点与应用程序池，执行自动化测试，或者调用对应的接口。

如果需要停止测试了，需要将对应的 IIS 站点与应用程序池停止，只有停止了，AltCover 才会将已执行代码路径信息写入到对应的控制文件当中。

可以看到 coverage.xml.0.acv 文件已经有内容了，但是我们还需要将控制文件的信息合并到 coverage.xml 当中，这个时候需要执行第二个命令进行合并。

D:\CoverageTool\AltCoverTestRESFul\packages\altcover.8.3.838\tools\net472\AltCover.exe runner --collect -r "D:\TempFiles\IIS\AltCoverTestWebSite\bin"

output:

... D:\TempFiles\IIS\AltCoverTestWebSite\coverage.xml.0.acv (380b)
308 visits recorded in 00:00:00.0171096 (18,002 visits/sec)
A total of 308 visits recorded
Coverage statistics flushing took 0.04 seconds
Visited Classes 10 of 12 (83.33)
Visited Methods 14 of 22 (63.64)
Visited Points 65 of 93 (69.89)
Visited Branches 4 of 30 (13.33)
Maximum CRAP score 30
==== Alternative Results (includes all methods including those without corresponding source) ====
Alternative Visited Classes 13 of 15 (86.67)
Alternative Visited Methods 20 of 30 (66.67)
Alternative maximum CRAP score 30

可以看到控制台的输出已经有 308 visits recorded，随后我们使用 reportgenerator 工具生成 HTML 报告。

.NET Core 集成

单元测试覆盖率报告

集成方法同 .NET Framework 一样。

ASP .NET Core 覆盖率报告

这里我使用的是 dotnet tool 安装的 altcover 命令，安装命令如下，前提是你得有 .NET Core 运行时。

dotnet tool install --global altcover.global --version

随后编译对应的 ASP.NET Core 项目，并且在对应的 bin\Debug 目录打开终端，执行以下命令进行准备工作。

altcover /o=./__UnitTestWithAltCover -i .

随后使用 altcover runner 命令启动对应的程序。

altcover runner -x .\__UnitTestWithAltCover\AltCoverTestRESTFulCore.exe -r .\__UnitTestWithAltCover\

如果已经完成了测试，请终止掉对应的进程，否则 AltCover 不会将数据写入到 XML 文件，最后也使用 reportgenerator 工具生成 HTML 报告。

总结

如果你的项目是基于 .NET Core ，那么可以直接选择微软主推的 coverlet ，AltCover 对于 .NET Framework、Mono、.NET Core 项目都有不错的支持，并且作者维护得也很勤快。

Bitbucket 使用 SSH 拉取仓库失败的问题

Tue, 28 Jun 2022 20:19:00 +0000

问题

在 Bitbucket 使用 Linux 机器上 ssh-keygen 工具生成的公钥作为 API KEY，然后在 Jenkins 里面存储对应的 SSH 私钥，最后执行 Job 的时候，Windows Agent 提示 SSH 密钥不正确。

 > git fetch --tags --force --progress -- ssh://git@bitbucket.xxxxx.com:7999/xxxx.git +refs/heads/*:refs/remotes/origin/* # timeout=10
ERROR: Error fetching remote repo 'origin'
hudson.plugins.git.GitException: Failed to fetch from git@bitbucket.xxxxx.com:7999/xxxx.git
	at hudson.plugins.git.GitSCM.fetchFrom(GitSCM.java:1001)
	at hudson.plugins.git.GitSCM.retrieveChanges(GitSCM.java:1242)
	at hudson.plugins.git.GitSCM.checkout(GitSCM.java:1302)
	at org.jenkinsci.plugins.workflow.steps.scm.SCMStep.checkout(SCMStep.java:129)
	at org.jenkinsci.plugins.workflow.steps.scm.SCMStep$StepExecutionImpl.run(SCMStep.java:97)
	at org.jenkinsci.plugins.workflow.steps.scm.SCMStep$StepExecutionImpl.run(SCMStep.java:84)
	at org.jenkinsci.plugins.workflow.steps.SynchronousNonBlockingStepExecution.lambda$start$0(SynchronousNonBlockingStepExecution.java:47)
	at java.base/java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:515)
	at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264)
	at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
	at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
	at java.base/java.lang.Thread.run(Thread.java:829)
Caused by: hudson.plugins.git.GitException: Command "git fetch --tags --force --progress -- ssh://git@bitbucket.xxxxx.com:7999/xxxx.git +refs/heads/*:refs/remotes/origin/*" returned status code 128:
stdout: 
stderr: git@bitbucket.xxxxx.com: Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

	at org.jenkinsci.plugins.gitclient.CliGitAPIImpl.launchCommandIn(CliGitAPIImpl.java:2671)
	at org.jenkinsci.plugins.gitclient.CliGitAPIImpl.launchCommandWithCredentials(CliGitAPIImpl.java:2096)
	at org.jenkinsci.plugins.gitclient.CliGitAPIImpl.access$500(CliGitAPIImpl.java:84)
	at org.jenkinsci.plugins.gitclient.CliGitAPIImpl$1.execute(CliGitAPIImpl.java:618)
	at org.jenkinsci.plugins.gitclient.RemoteGitImpl$CommandInvocationHandler$GitCommandMasterToSlaveCallable.call(RemoteGitImpl.java:158)
	at org.jenkinsci.plugins.gitclient.RemoteGitImpl$CommandInvocationHandler$GitCommandMasterToSlaveCallable.call(RemoteGitImpl.java:151)
	at hudson.remoting.UserRequest.perform(UserRequest.java:211)
	at hudson.remoting.UserRequest.perform(UserRequest.java:54)
	at hudson.remoting.Request$2.run(Request.java:376)
	at hudson.remoting.InterceptingExecutorService.lambda$wrap$0(InterceptingExecutorService.java:78)
	at java.util.concurrent.FutureTask.run(Unknown Source)
	at java.util.concurrent.ThreadPoolExecutor.runWorker(Unknown Source)
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(Unknown Source)
	at hudson.remoting.Engine$1.lambda$newThread$0(Engine.java:122)
	at java.lang.Thread.run(Unknown Source)
	Suppressed: hudson.remoting.Channel$CallSiteStackTrace: Remote call to xxx-xxx-xxx.xxx.xxx
		at hudson.remoting.Channel.attachCallSiteStackTrace(Channel.java:1797)
		at hudson.remoting.UserRequest$ExceptionResponse.retrieve(UserRequest.java:356)
		at hudson.remoting.Channel.call(Channel.java:1001)
		at org.jenkinsci.plugins.gitclient.RemoteGitImpl$CommandInvocationHandler.execute(RemoteGitImpl.java:143)
		at jdk.internal.reflect.GeneratedMethodAccessor8221.invoke(Unknown Source)
		at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
		at java.base/java.lang.reflect.Method.invoke(Method.java:566)
		at org.jenkinsci.plugins.gitclient.RemoteGitImpl$CommandInvocationHandler.invoke(RemoteGitImpl.java:129)
		at com.sun.proxy.$Proxy126.execute(Unknown Source)
		at hudson.plugins.git.GitSCM.fetchFrom(GitSCM.java:999)
		at hudson.plugins.git.GitSCM.retrieveChanges(GitSCM.java:1242)
		at hudson.plugins.git.GitSCM.checkout(GitSCM.java:1302)
		at org.jenkinsci.plugins.workflow.steps.scm.SCMStep.checkout(SCMStep.java:129)
		at org.jenkinsci.plugins.workflow.steps.scm.SCMStep$StepExecutionImpl.run(SCMStep.java:97)
		at org.jenkinsci.plugins.workflow.steps.scm.SCMStep$StepExecutionImpl.run(SCMStep.java:84)
		at org.jenkinsci.plugins.workflow.steps.SynchronousNonBlockingStepExecution.lambda$start$0(SynchronousNonBlockingStepExecution.java:47)
		at java.base/java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:515)
		at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264)
		at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
		at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
		at java.base/java.lang.Thread.run(Thread.java:829)

最后登录到对应的 Windows 节点，直接使用 git clone 命令也是这样，说明不是 Jenkins 的权限问题。

查询资料得知，出现这种情况需要将对应公钥(id_rsa)与私钥文件(id_rsa.pub) 复制到 Jenkins Agent 执行用户的 HOME 目录下的 .ssh 文件夹。

普通用户的 HOME 目录就是 echo $HOME，一般也就是 C:\User\UserName 的路径。但是 Jenkins Agent 一旦作为服务执行，那么他的执行用户就是 SYSTEM ACCOUNT，它的 HOME 目录路径是 C:\WINDOWS\system32\config\systemprofile\.ssh 。

根据上述情况试了，还是没有解决，不管是 ssh-add xxx，还是更改 Git 的 SSH CONFIG 文件都无法解决。

原因

我一直以为是自己的问题，结果用 GitHub 试了，是正常的。最后将目光转向了 BitBucket，根据官方的文章，设置了 GIT_SSH_COMMAND 环境变量，并指定 ssh -vvvv 命令，这样能够让我们看到详细的错误信息。

最后得到了以下输出:

查询资料得知，根本原因是 BitBucket 现在不支持 RSA SHA-1 生成的密钥。

解决

官方的解决方案有两种，第一种是使用不安全的 RSA SHA-1 密钥，只需要更改客户端的配置文件，将 ssh-rsa 添加进去即可。不过这种做法并不安全，最好的做法还是使用 ssh-keygen 命令生成更加安全，基于 ED25519 算法的密钥。

ssh-keygen -t ed25519 -C "your_email@example.com"

将这个公钥重新设置在 Bitbucket，然后将私钥替换掉 Jenkins 里面的 Credential，执行 Jenkins Job 成功。

参考资料

Abp vNext 源码分析 - 20. 电子邮件与短信支持

Mon, 28 Jun 2021 01:43:29 +0000

一、简介

ABP vNext 使用 Volo.Abp.Sms 包和 Volo.Abp.Emailing 包将短信和电子邮件作为基础设施进行了抽象，开发人员仅需要在使用的时候注入 ISmsSender 或 IEmailSender 即可实现短信发送和邮件发送。

二、源码分析

2.1 启动模块

短信发送的抽象层比较简单，AbpSmsModule 模块内部并无任何操作，仅作为空模块进行定义。

电子邮件的 AbpEmailingModule 模块内，主要添加了一些本地化资源支持。另一个动作就是添加了一个 BackgroundEmailSendingJob 后台作业，这个后台作业主要是用于后续发送电子邮件使用。因为邮件发送这个动作实时性要求并不高，在实际的业务实践当中，我们基本会将其加入到一个后台队列慢慢发送，所以这里 ABP 为我们实现了 BackgroundEmailSendingJob。

BackgroundEmailSendingJob.cs:

public class BackgroundEmailSendingJob : AsyncBackgroundJob<BackgroundEmailSendingJobArgs>, ITransientDependency
{
    protected IEmailSender EmailSender { get; }

    public BackgroundEmailSendingJob(IEmailSender emailSender)
    {
        EmailSender = emailSender;
    }

    public override async Task ExecuteAsync(BackgroundEmailSendingJobArgs args)
    {
        if (args.From.IsNullOrWhiteSpace())
        {
            await EmailSender.SendAsync(args.To, args.Subject, args.Body, args.IsBodyHtml);
        }
        else
        {
            await EmailSender.SendAsync(args.From, args.To, args.Subject, args.Body, args.IsBodyHtml);
        }
    }
}

这个后台任务的逻辑也不复杂，就使用 IEmailSender 发送邮件，我们在任何地方需要后台发送邮件的时，只需要注入 IBackgroundJobManager，使用 BackgroundEmailSendingJobArgs 作为参数添加入队一个后台作业即可。

使用 IBackgroundJobManager 添加一个新的邮件发送欢迎邮件:

public class DemoClass
{
    private readonly IBackgroundJobManager _backgroundJobManager;
    private readonly IUserInfoRepository _userRep;

    public DemoClass(IBackgroundJobManager backgroundJobManager,
        IUserInfoRepository userRep)
    {
        _backgroundJobManager = backgroundJobManager;
        _userRep = userRep;
    }

    public async Task SendWelcomeEmailAsync(Guid userId)
    {
        var userInfo = await _userRep.GetByIdAsync(userId);

        await _backgroundJobManager.EnqueueAsync(new BackgroundEmailSendingJobArgs
        {
            To = userInfo.EmailAddress,
            Subject = "Welcome",
            Body = "Welcome, Hello World!",
            IsBodyHtml = false;
        });
    }
}

注意

目前 BackgroundEmailSendingJobArgs 参数不支持发送附件，ABP 可能在以后的版本会进行实现。

2.2 Email 的核心组件

ABP 定义了一个 IEmailSender 接口，定义了多个 SendAsync() 方法重载，用于直接发送电子邮件。同时也提供了 QueueAsync() 方法，通过后台任务队列来发送邮件。

public interface IEmailSender
{
    Task SendAsync(
        string to,
        string subject,
        string body,
        bool isBodyHtml = true
    );

    Task SendAsync(
        string from,
        string to,
        string subject,
        string body,
        bool isBodyHtml = true
    );

    Task SendAsync(
        MailMessage mail,
        bool normalize = true
    );

    Task QueueAsync(
        string to,
        string subject,
        string body,
        bool isBodyHtml = true
    );

    Task QueueAsync(
        string from,
        string to,
        string subject,
        string body,
        bool isBodyHtml = true
    );

    //TODO: 准备添加的 QueueAsync 方法。目前存在的问题: MailMessage 不能够被序列化，所以不能加入到后台任务队列当中。
}

ABP 实际拥有两种 Email Sender 实现，分别是 SmtpEmailSender 和 MailkitEmailSender，各个类型的关系如下。

UML 类图:

classDiagram
	class IEmailSender{
		<<Interface>>
		+SendAsync(string,string,string,bool=true) Task
		+SendAsync(string,string,string,string,bool=true) Task
		+SendAsync(MailMessage,bool=true) Task
		+QueueAsync(string,string,string,bool=true) Task
		+QueueAsync(string,string,string,string,bool=true) Task
	}
	class ISmtpEmailSender{
		<<Interface>>
		......
		+BuildClientAsync() Task~SmtpClient~
	}
	class IMailKitSmtpEmailSemder{
		<<Interface>>
		......
		+BuildClientAsync() Task~SmtpClient~
	}
	class EmailSenderBase{
		<<Abstract>>
		......
	}
	class SmtpEmailSender{
		......
	}
	class MailKitSmtpEmailSender{
		......
	}
	class NullEmailSender{
		......
	}
	
	ISmtpEmailSender --|> IEmailSender: 继承
	IMailKitSmtpEmailSemder --|> IEmailSender: 继承
	EmailSenderBase ..|> IEmailSender: 实现
	SmtpEmailSender ..|> ISmtpEmailSender: 实现
	SmtpEmailSender --|> EmailSenderBase: 继承
	NullEmailSender --|> EmailSenderBase: 继承
	MailKitSmtpEmailSender ..|> IMailKitSmtpEmailSemder: 实现
	MailKitSmtpEmailSender --|> EmailSenderBase: 继承

可以从 UML 类图看出，每个 EmailSender 实现都与一个 IXXXConfiguration 对应，这个配置类存储了基于 Smtp 发件的必须配置。因为 MailKit 本身也是基于 Smtp 发送邮件的，所以没有重新定义新的配置类，而是直接复用的 ISmtpEmailSenderConfiguration 接口与实现。

在 EmailSenderBase 基类当中，基本实现了 IEmailSender 接口的所有方法的逻辑，只留下了 SendEmailAsync(MailMessage mail) 作为一个抽象方法等待子类实现。也就是说其他的方法最终都是使用该方法来最终发送邮件。

public abstract class EmailSenderBase : IEmailSender
{
    protected IEmailSenderConfiguration Configuration { get; }

    protected IBackgroundJobManager BackgroundJobManager { get; }

    protected EmailSenderBase(IEmailSenderConfiguration configuration, IBackgroundJobManager backgroundJobManager)
    {
        Configuration = configuration;
        BackgroundJobManager = backgroundJobManager;
    }

    // ... 实现的接口方法

    protected abstract Task SendEmailAsync(MailMessage mail);

    // 使用 Configuration 里面的参数，统一处理邮件数据。
    protected virtual async Task NormalizeMailAsync(MailMessage mail)
    {
        if (mail.From == null || mail.From.Address.IsNullOrEmpty())
        {
            mail.From = new MailAddress(
                await Configuration.GetDefaultFromAddressAsync(),
                await Configuration.GetDefaultFromDisplayNameAsync(),
                Encoding.UTF8
                );
        }

        if (mail.HeadersEncoding == null)
        {
            mail.HeadersEncoding = Encoding.UTF8;
        }

        if (mail.SubjectEncoding == null)
        {
            mail.SubjectEncoding = Encoding.UTF8;
        }

        if (mail.BodyEncoding == null)
        {
            mail.BodyEncoding = Encoding.UTF8;
        }
    }
}

ABP 默认可用的邮件发送组件是 SmtpEmailSender，它使用的是 .NET 自带的邮件发送组件，本质上就是构建了一个 SmtpClient 客户端，然后调用它的发件方法进行邮件发送。

public class SmtpEmailSender : EmailSenderBase, ISmtpEmailSender, ITransientDependency
{
    // ... 省略的代码。
    public async Task<SmtpClient> BuildClientAsync()
    {
        var host = await SmtpConfiguration.GetHostAsync();
        var port = await SmtpConfiguration.GetPortAsync();

        var smtpClient = new SmtpClient(host, port);

        // 从 SettingProvider 中获取各个配置参数，构建 Client 进行发送。
        try
        {
            if (await SmtpConfiguration.GetEnableSslAsync())
            {
                smtpClient.EnableSsl = true;
            }

            if (await SmtpConfiguration.GetUseDefaultCredentialsAsync())
            {
                smtpClient.UseDefaultCredentials = true;
            }
            else
            {
                smtpClient.UseDefaultCredentials = false;

                var userName = await SmtpConfiguration.GetUserNameAsync();
                if (!userName.IsNullOrEmpty())
                {
                    var password = await SmtpConfiguration.GetPasswordAsync();
                    var domain = await SmtpConfiguration.GetDomainAsync();
                    smtpClient.Credentials = !domain.IsNullOrEmpty()
                        ? new NetworkCredential(userName, password, domain)
                        : new NetworkCredential(userName, password);
                }
            }

            return smtpClient;
        }
        catch
        {
            smtpClient.Dispose();
            throw;
        }
    }

    protected override async Task SendEmailAsync(MailMessage mail)
    {
        // 调用构建方法，构建 Client，用于发送 mail 数据。
        using (var smtpClient = await BuildClientAsync())
        {
            await smtpClient.SendMailAsync(mail);
        }
    }
}

针对属性注入失败的情况，ABP 提供了 NullEmailSender 作为默认实现，在发送邮件的时候会使用 Logger 打印具体的信息。

public class NullEmailSender : EmailSenderBase
{
    public ILogger<NullEmailSender> Logger { get; set; }

    public NullEmailSender(IEmailSenderConfiguration configuration, IBackgroundJobManager backgroundJobManager)
        : base(configuration, backgroundJobManager)
    {
        Logger = NullLogger<NullEmailSender>.Instance;
    }

    protected override Task SendEmailAsync(MailMessage mail)
    {
        Logger.LogWarning("USING NullEmailSender!");
        Logger.LogDebug("SendEmailAsync:");
        LogEmail(mail);
        return Task.FromResult(0);
    }

    // ... 其他方法。
}

2.3 Email 的配置存储

从 EmailSenderBase 里面可以看到，它从 IEmailSenderConfiguration 当中获取发件人的邮箱地址和展示名称，它的 UML 类图关系如下。

classDiagram
	class IEmailSenderConfiguration{
		<<Interface>>
		+GetDefaultFromAddressAsync() Task~string~
		+GetDefaultFromDisplayNameAsync() Task~string~
	}
	class ISmtpEmailSenderConfiguration{
		<<Interface>>
		+GetHostAsync() Task~string~
		+GetPortAsync() Task~int~
		+GetUserNameAsync() Task~string~
		+GetPasswordAsync() Task~string~
		+GetDomainAsync() Task~string~
		+GetEnableSslAsync() Task~bool~
		+GetUseDefaultCredentialsAsync() Task~bool~
	}
	class EmailSenderConfiguration{
		#GetNotEmptySettingValueAsync(string name) Task~string~
	}
	class SmtpEmailSenderConfiguration{
	
	}
	class ISettingProvider{
		<<Interface>>
		+GetOrNullAsync(string name) Task~string~
	}
	
	ISmtpEmailSenderConfiguration --|> IEmailSenderConfiguration: 继承
	EmailSenderConfiguration ..|> IEmailSenderConfiguration: 实现
	EmailSenderConfiguration ..> ISettingProvider: 依赖
	SmtpEmailSenderConfiguration --|> EmailSenderConfiguration: 继承
	SmtpEmailSenderConfiguration ..|> ISmtpEmailSenderConfiguration: 实现

可以看到配置文件时通过 ISettingProvider 获取的，这样就可以保证从不同租户甚至是用户来获取发件人的配置信息。这里值得注意的是在 EmailSenderConfiguration 中，实现了一个 GetNotEmptySettingValueAsync(string name) 方法，该方法主要是封装了获取逻辑，当值不存在的时候抛出 AbpException 异常。

protected async Task<string> GetNotEmptySettingValueAsync(string name)
{
    var value = await SettingProvider.GetOrNullAsync(name);

    if (value.IsNullOrEmpty())
    {
        throw new AbpException($"Setting value for '{name}' is null or empty!");
    }

    return value;
}

至于 SmtpEmailSenderConfiguration，只是提供了其他的属性获取(密码、端口等)而已，本质上还是调用的 GetNotEmptySettingValueAsync() 方法从 SettingProvider 中获取具体的配置信息。

sequenceDiagram
	发送邮件 ->> Smtp 配置类: 1.GetHostAsync()
	Smtp 配置类 ->> Email 配置类: 2.GetNotEmptySettingValueAsync("HotsItem")
	Email 配置类 ->> Setting Provider: 3.GetOrNullAsync("HotsItem")
	Setting Provider -->> 发送邮件: 4.获得主机数据。

关于配置名称的常量，都在 EmailSettingNames 里面进行定义，并使用 EmailSettingProvider 将其注册到 ABP 的配置模块当中:

EmailSettingNames.cs

namespace Volo.Abp.Emailing
{
    public static class EmailSettingNames
    {
        public const string DefaultFromAddress = "Abp.Mailing.DefaultFromAddress";

        public const string DefaultFromDisplayName = "Abp.Mailing.DefaultFromDisplayName";

        public static class Smtp
        {
            public const string Host = "Abp.Mailing.Smtp.Host";

            public const string Port = "Abp.Mailing.Smtp.Port";

            // ... 其他常量定义。
        }
    }
}

EmailSettingProvider.cs

internal class EmailSettingProvider : SettingDefinitionProvider
{
    public override void Define(ISettingDefinitionContext context)
    {
        context.Add(
            new SettingDefinition(
                EmailSettingNames.Smtp.Host, 
                "127.0.0.1", 
                L("DisplayName:Abp.Mailing.Smtp.Host"), 
                L("Description:Abp.Mailing.Smtp.Host")),

            new SettingDefinition(EmailSettingNames.Smtp.Port, 
                "25", 
                L("DisplayName:Abp.Mailing.Smtp.Port"), 
                L("Description:Abp.Mailing.Smtp.Port")),
                // ... 其他配置参数。
        );
    }

    private static LocalizableString L(string name)
    {
        return LocalizableString.Create<EmailingResource>(name);
    }
}

2.4 邮件模板

文字模板是 ABP 后续提供的一个新的模块，它可以让开发人员预先定义文本模板，然后使用时根据对象数据替换模板中的内容，并且 ABP 提供的文本模板还支持本地化。关于文本模板的功能，我们后续单独会写一篇文章进行说明，在这里只是大概 Mail 是如何使用的。

在项目当中，ABP 仅定义了两个 *.tpl 的模板文件，分别是控制布局的 Layout.tpl，还有渲染具体消息的 Message.tpl。同权限、Setting 一样，模板也会使用一个 StandardEmailTemplates 类型定义模板的编码常量，并且实现一个 XXXDefinitionProvider 类型将其注入到 ABP 框架当中。

StandardEmailTemplates.cs

public static class StandardEmailTemplates
{
    public const string Layout = "Abp.StandardEmailTemplates.Layout";
    public const string Message = "Abp.StandardEmailTemplates.Message";
}

StandardEmailTemplateDefinitionProvider.cs

public class StandardEmailTemplateDefinitionProvider : TemplateDefinitionProvider
{
    public override void Define(ITemplateDefinitionContext context)
    {
        context.Add(
            new TemplateDefinition(
                StandardEmailTemplates.Layout,
                displayName: LocalizableString.Create<EmailingResource>("TextTemplate:StandardEmailTemplates.Layout"),
                isLayout: true
            ).WithVirtualFilePath("/Volo/Abp/Emailing/Templates/Layout.tpl", true)
        );

        context.Add(
            new TemplateDefinition(
                StandardEmailTemplates.Message,
                displayName: LocalizableString.Create<EmailingResource>("TextTemplate:StandardEmailTemplates.Message"),
                layout: StandardEmailTemplates.Layout
            ).WithVirtualFilePath("/Volo/Abp/Emailing/Templates/Message.tpl", true)
        );
    }
}

2.5 MailKit 集成

MailKit 是一个优秀跨平台的 .NET 邮件操作库，它的官方 GitHub 地址为 https://github.com/jstedfast/MailKit ，支持很多高级特性，这里我就不再详细介绍 MailKit 的其他特性，只是讲解一下 MailKit 同 ABP 自带的邮件模块是如何集成的。

官方的 Volo.Abp.MailKit 包仅包含 4 个文件，它们分别是 AbpMailKitModule.cs (空模块，占位)、AbpMailKitOptions.cs (MailKit 的特殊配置)、IMailKitSmtpEmailSender.cs (实现了 IEmailSender 基类的一个接口)、MailKitSmtpEmailSender.cs (具体的发送逻辑实现)。

需要注意一下，这里针对 MailKit 的特殊配置是使用的 IConfiguration 里面的数据(通常是 appsetting.json)，而不是从 Abp.Settings 里面获取的。

MailKitSmtpEmailSender.cs

[Dependency(ServiceLifetime.Transient, ReplaceServices = true)]
public class MailKitSmtpEmailSender : EmailSenderBase, IMailKitSmtpEmailSender
{
    protected AbpMailKitOptions AbpMailKitOptions { get; }

    protected ISmtpEmailSenderConfiguration SmtpConfiguration { get; }

    // ... 构造函数。

    protected override async Task SendEmailAsync(MailMessage mail)
    {
        using (var client = await BuildClientAsync())
        {
            // 使用了 mail 参数来构造 MailKit 的对象。
            var message = MimeMessage.CreateFromMailMessage(mail);
            await client.SendAsync(message);
            await client.DisconnectAsync(true);
        }
    }

    // 构造 MailKit 所需要的 Client 对象。
    public async Task<SmtpClient> BuildClientAsync()
    {
        var client = new SmtpClient();

        try
        {
            await ConfigureClient(client);
            return client;
        }
        catch
        {
            client.Dispose();
            throw;
        }
    }

    // 进行一些基本配置，比如服务器信息和密码信息等。
    protected virtual async Task ConfigureClient(SmtpClient client)
    {
        await client.ConnectAsync(
            await SmtpConfiguration.GetHostAsync(),
            await SmtpConfiguration.GetPortAsync(),
            await GetSecureSocketOption()
        );

        if (await SmtpConfiguration.GetUseDefaultCredentialsAsync())
        {
            return;
        }

        await client.AuthenticateAsync(
            await SmtpConfiguration.GetUserNameAsync(),
            await SmtpConfiguration.GetPasswordAsync()
        );
    }

    // 根据 Option 的值获取一些安全配置。
    protected virtual async Task<SecureSocketOptions> GetSecureSocketOption()
    {
        if (AbpMailKitOptions.SecureSocketOption.HasValue)
        {
            return AbpMailKitOptions.SecureSocketOption.Value;
        }

        return await SmtpConfiguration.GetEnableSslAsync()
            ? SecureSocketOptions.SslOnConnect
            : SecureSocketOptions.StartTlsWhenAvailable;
    }
}

2.6 短信发送的核心组件

短信发送仅提供了一个 ISmsSender 接口，该接口有提供一个发送方法，ABP 官方提供了 Aliyun 的短信发送功能(Volo.Abp.Sms.Aliyun)。

UML 图:

classDiagram
	class ISmsSender{
		<<Interface>>
		SendAsync(SmsMessage smsMessage) Task
	}
	class NullSmsSender{
	}
	class SmsMessage{
		+string PhoneNumber
		+string Text
		+IDictionary~string, object~ Properties
	}
	NullSmsSender ..|> ISmsSender: 实现
	ISmsSender ..> SmsMessage: 依赖

功能比较简单，重点是 SmsMessage 里面的参数，第一个是发送的号码，第二个是发送的内容。仅凭上述参数肯定不够，所以 ABP 提供了一个属性字典，便于我们传入一些特定的参数。

三、总结

ABP 将 Email 这块功能封装成了单独的模块，便于开发人员进行邮件发送。并且官方也提供了 MailKit 的支持，我们可以根据自己的需求来替换不同的实现。只不过针对于一些异步邮件发送的场景，目前还不能很好的支持(主要是使用了 MailMessage 无法序列化)。

我觉得 ABP 应该自己定义一个 Context 类型，反转依赖，在具体的实现当中确定邮件发送的对象类型。或者是将默认的 Smtp 发送者独立出来一个模块，就跟 MailKit 一样，使用 ABP 的 Context 类型来构造 MailMessage 对象。

四、总目录

欢迎翻阅作者的其他文章，请 点击我 进行跳转，如果你觉得本篇文章对你有帮助，请点击文章末尾的 推荐按钮。

最后更新时间: 2021年6月27日 23点31分

Abp vNext 源码分析 - 19. 单元测试

Tue, 27 Apr 2021 06:11:00 +0000

简介

ABP vNext 框架使用 xUnit 作为单元测试组件，官方的所有模块都编写了大量的 单元/集成测试 确保功能正常。由于 ABP vNext 模块化系统的原因，开发人员在建立单元测试项目的时候需要集成 Volo.Abp.UnitTest 项目，这样在执行单元测试的时候才不会缺少必要组件。

分析

ABP vNext 单元测试相关的类型最核心的是集成测试基类 AbpIntegratedTest 和 MVC 专用测试基类 AbpAspNetCoreIntegratedTestBase，这两个基类核心工作就是初始化 IoC 容器并且初始化整个模块系统，只不过后者对 控制器 相关的组件进行了初始化配置，让开发人员可以针对 控制器 进行单元/集成测试。

从上图可以看到两个基类都继承自 AbpTestBaseWithServiceProvider 基类，在这个基类里面将 IServiceProvider 作为一个抽象成员。这是因为 MVC 和测试基类的 ServiceProvider 来源不一样，一个是 ABP vNext 根据 Application 类已注册 IoC 容器构建的，另一个使用的是 IHost 测试主机内的 ServiceProvider。

单元测试执行本质上就是将测试类进行实例化，然后调用对应的单元测试方法，所以测试基类的初始化动作都是放在对应的无参构造函数。

虽然 Volo.Abp.UnitTest 也是单独的一个项目，它的 AbpTestBaseModule 是没有任何动作，仅仅是为了同其他项目保持一致，内部是没有任何代码。

using Volo.Abp.Modularity;

namespace Volo.Abp
{
    public class AbpTestBaseModule : AbpModule
    {

    }
}

集成测试基类

一般来说，我们会直接从 AbpIntegratedTest 继承并实现我们需要的单元测试基类，包括 ABP vNext 官方的默认模版也是这样。集成测试基类的核心代码很简单，就是在无参构造函数的内部进行初始化动作，且在过程中按顺序执行两个生命周期方法。

简易流程图:

public abstract class AbpIntegratedTest<TStartupModule> : AbpTestBaseWithServiceProvider, IDisposable
    where TStartupModule : IAbpModule
{
    protected IAbpApplication Application { get; }

    protected override IServiceProvider ServiceProvider => Application.ServiceProvider;

    protected IServiceProvider RootServiceProvider { get; }

    protected IServiceScope TestServiceScope { get; }

    protected AbpIntegratedTest()
    {
        var services = CreateServiceCollection();

        BeforeAddApplication(services);

        var application = services.AddApplication<TStartupModule>(SetAbpApplicationCreationOptions);
        Application = application;

        AfterAddApplication(services);

      	// 根据已有 IServiceCollection 创建 IoC 容器。
        RootServiceProvider = CreateServiceProvider(services);
        TestServiceScope = RootServiceProvider.CreateScope();
				
      	// 使用子容器对 ABP 模块系统进行初始化。
        application.Initialize(TestServiceScope.ServiceProvider);
    }

    // ... 其他代码。
}

上述代码可以看到默认的测试基类并没有直接使用 RootServiceProvider，而是创建了一个子容器给 ABP vNext 使用，这主要是为了后续可以对容器进行销毁操作，具体可一看下面的 Dispose() 方法。

public virtual void Dispose()
{
    Application.Shutdown();
    TestServiceScope.Dispose();
    Application.Dispose();
}

总的来说，测试基类就是构建了一个 IAbpApplication 对象，根据传入的 TStartupModule 模块进入拓扑排序过程，依次执行各个模块的生命周期配置。

MVC 测试基类

针对我们的 Http Api 层，如果需要对 Controller 进行测试的话，就需要从 MVC 测试基类继承编写单元/集成测试，各个类型的关系如下。

AbpTestBaseWithServiceProvider#ServiceProvider#GetService() : #GetRequiredService() : AbpIntegratedTest#BeforeAddApplication(IServiceCollection service)#SetAbpApplicationCreationOptions(AbpApplicationCreationOptions options)#AfterAddApplication(IServiceCollection services)#CreateServiceProvider(IServiceCollection service)+Dispose()AbpAspNetCoreIntegratedTestBase#TestServer Server#HttpClient Client-IHost host#CreateHostBuilder() : IHostBuilder#ConfigureServices(HostBuilderContext context, IServiceCollection services)#GetUrl_OfType_TController() : string#GetUrl_OfType_TController(string actionName) : string#GetUrl_OfType_TController(string actionName, object queryStringParamsAsAnonymousObject) : string+Dispose()IDispose<> IDispose

针对 AspNetCore 来说，ABP 创建了一个新的 Host 主机，在每次执行测试的时候会启动一个新的 Web 服务器。(并不会创建真实服务，不存在端口占用问题)

在基类当中，ABP 定义了两个属性 Server 和 Client，它们都是 Mock 了对应的接口，方便后续的单元测试，这里的 ITestServerAccessor 接口是用于 Mock AspNetCoreTestDynamicProxyHttpClientFactory 接口所需要的。

AspNetCoreTestDynamicProxyHttpClientFactory 接口是 ABP 底层进行动态代理所使用的，在请求远程服务的时候会调用这个接口创建 HttpClient 对象。

protected AbpAspNetCoreIntegratedTestBase()
{
    var builder = CreateHostBuilder();

    _host = builder.Build();
    _host.Start();

    Server = _host.GetTestServer();
    Client = _host.GetTestClient();

    ServiceProvider = Server.Services;

    ServiceProvider.GetRequiredService<ITestServerAccessor>().Server = Server;
}

从 UML 类图当中，可以看到基类定义了几个 GetUrl() 方法，这几个方法是根据 Controller 获取对应的请求路径。

这里我以一个 SampleController 控制器为例，它提供了一个 Index 方法，返回了一个页面内容。针对它来说，我们编写集成测试是这样操作的。

public class SimpleController : AbpController
{
    public ActionResult Index()
    {
        return Content("Index-Result");
    }
}

集成测试

public class SimpleController_Tests : AbpAspNetCoreIntegratedTestBase<Startup>
{
    protected virtual async Task<HttpResponseMessage> GetResponseAsync(string url, HttpStatusCode expectedStatusCode = HttpStatusCode.OK)
    {
        using (var requestMessage = new HttpRequestMessage(HttpMethod.Get, url))
        {
            requestMessage.Headers.Add("Accept-Language", CultureInfo.CurrentUICulture.Name);
            var response = await Client.SendAsync(requestMessage);
            response.StatusCode.ShouldBe(expectedStatusCode);
            return response;
        }
    }

    protected virtual async Task<string> GetResponseAsStringAsync(string url, HttpStatusCode expectedStatusCode = HttpStatusCode.OK)
    {
        using (var response = await GetResponseAsync(url, expectedStatusCode))
        {
            return await response.Content.ReadAsStringAsync();
        }
    }

    [Fact]
    public async Task ActionResult_ContentResult()
    {
        var result = await GetResponseAsStringAsync(
            GetUrl<SimpleController>(nameof(SimpleController.Index))
        );

        result.ShouldBe("Index-Result");
    }
}

EF Core 的集成

在执行单元测试过程中，我们难免会对数据库进行操作。这个时候不可能连接真实数据库，就需要我们在测试基类当中进行一些初始化动作，将底层的数据库链接改为 SQLite 的内存模式。

public class SampleEntityFrameworkCoreTestModule : AbpModule
{
    private SqliteConnection _sqliteConnection;

    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        ConfigureInMemorySqlite(context.Services);
    }

    private void ConfigureInMemorySqlite(IServiceCollection services)
    {
        // 建立链接并执行迁移。
        _sqliteConnection = CreateDatabaseAndGetConnection();

        // 使用 SQLite 作为 EF Provider。
        services.Configure<AbpDbContextOptions>(options =>
        {
            options.Configure(context =>
            {
                context.DbContextOptions.UseSqlite(_sqliteConnection);
            });
        });
    }

    public override void OnApplicationShutdown(ApplicationShutdownContext context)
    {
        _sqliteConnection.Dispose();
    }

    private static SqliteConnection CreateDatabaseAndGetConnection()
    {
        // 使用 SQLite 的内存模式链接字符串。
        var connection = new SqliteConnection("Data Source=:memory:");
        connection.Open();

        var options = new DbContextOptionsBuilder<SampleMigrationsDbContext>()
            .UseSqlite(connection)
            .Options;

        // 执行迁移，构建表结构。
        using (var context = new SampleMigrationsDbContext(options))
        {
            context.GetService<IRelationalDatabaseCreator>().CreateTables();
        }

        return connection;
    }
}

总结

ABP 的测试更偏向于集成测试，因为各个功能都依赖于模块，所以在执行单元测试的时候会运行更长的时间。日常开发过程当中，我们更多地还是针对应用层进行测试就可以了，粒度更细的话也可以针对仓储层、领域层、API 层 编写测试即可。

为了保证项目质量，在开发完成之后编写单元/集成测试是每个开发人员应做的工作。编写单元/集成测试，虽然不能 100% 避免 BUG，但可以保证每次进行业务修改之后接口的正确性。

四、总目录

欢迎翻阅作者的其他文章，请 点击我 进行跳转，如果你觉得本篇文章对你有帮助，请点击文章末尾的 推荐按钮。

最后更新时间: 2021年6月27日 23点41分

acme.sh 免费泛解析证书生成

Tue, 16 Mar 2021 07:15:00 +0000

环境准备

本篇文章使用的 ACME 客户端是基于 Docker 容器使用的，所以需要准备 Docker 运行环境。本文使用的是 CentOS 7.x 与 Docker CE - 19.03.13，且已经安装了 Docker Compose 工具。

我已经参考官方的 GitHub 文章编写了 acme.sh 需要的 Docker Compose 文件，标准模版如下:

version: "3"

services:
  acme.sh:
    image: neilpang/acme.sh:latest
    container_name: acme.sh
    command: daemon
    volumes:
      - "<ACME 证书文件的生成目录>:/acme.sh"
      - "/var/run/docker.sock:/var/run/docker.sock"
    environment:
      - Ali_Key=<填写阿里云的 Access Key>
      - Ali_Secret=<填写阿里云的 Access Secret>
      - DEPLOY_DOCKER_CONTAINER_LABEL=__nginx__
      - DEPLOY_DOCKER_CONTAINER_RELOAD_CMD="nginx -s reload -c /etc/nginx/nginx.conf"
    restart: always
    networks:
      - internal-network

networks:
  internal-network:
    external: true

参数配置

针对 ACME 的默认参数，我们只需要提供 DNS 服务商的 API 访问密钥即可，acme.sh 会自动对我们的域名进行配置验证，我这里以阿里云的为例，其他受支持的 DNS 服务商可以前往 Github 文档查看。

除开环境变量的配置参数以外，针对 Acme 的证书文件生成目录也需要单独进行配置，这块可以用于。

具体使用

拉取镜像

执行一下命令拉取 acme.sh 的 Docker 镜像。

docker pull neilpang/acme.sh:latest

运行容器

docker-compose up -d

生成证书

由于已经在环境变量配置了阿里云的参数，所以现在只需要指定域名即可生成对应的证书，域名验证等一系列步骤都交由 acme.sh 自动完成。

进入到 acme.sh 的容器，执行生成命令。

acme.sh --issue --dns dns_ali -d example.com -d www.example.com

等待验证成功以后，就会在 acme.sh 文件夹生成对应的证书文件。

[Tue Mar 16 07:07:44 UTC 2021] Using CA: https://acme-v02.api.letsencrypt.org/directory
[Tue Mar 16 07:07:45 UTC 2021] Create account key ok.
[Tue Mar 16 07:07:45 UTC 2021] Registering account: https://acme-v02.api.letsencrypt.org/directory
[Tue Mar 16 07:07:46 UTC 2021] Registered
[Tue Mar 16 07:07:46 UTC 2021] ACCOUNT_THUMBPRINT='账号信息'
[Tue Mar 16 07:07:46 UTC 2021] Creating domain key
[Tue Mar 16 07:07:47 UTC 2021] The domain key is here: /acme.sh/example.com/example.com.key
[Tue Mar 16 07:07:47 UTC 2021] Multi domain='DNS:example.com,DNS:www.example.com'
[Tue Mar 16 07:07:47 UTC 2021] Getting domain auth token for each domain
[Tue Mar 16 07:07:49 UTC 2021] Getting webroot for domain='example.com'
[Tue Mar 16 07:07:49 UTC 2021] Getting webroot for domain='www.example.com'
[Tue Mar 16 07:07:49 UTC 2021] Adding txt value: eJ2UJrvi_lAMmY0D-BFrM4WNvDXkICUR0BSJ3EXyBtw for domain:  _acme-challenge.example.com
[Tue Mar 16 07:07:51 UTC 2021] The txt record is added: Success.
[Tue Mar 16 07:07:51 UTC 2021] Adding txt value: u_T1kks2iNU1E_1bAtE8zpz-e81uTISws8o_ZL8YE40 for domain:  _acme-challenge.www.example.com
[Tue Mar 16 07:07:53 UTC 2021] The txt record is added: Success.
[Tue Mar 16 07:07:53 UTC 2021] Let's check each DNS record now. Sleep 20 seconds first.
[Tue Mar 16 07:08:14 UTC 2021] You can use '--dnssleep' to disable public dns checks.
[Tue Mar 16 07:08:14 UTC 2021] See: https://github.com/acmesh-official/acme.sh/wiki/dnscheck
[Tue Mar 16 07:08:14 UTC 2021] Checking example.com for _acme-challenge.example.com
[Tue Mar 16 07:08:16 UTC 2021] Domain example.com '_acme-challenge.example.com' success.
[Tue Mar 16 07:08:16 UTC 2021] Checking www.example.com for _acme-challenge.www.example.com
[Tue Mar 16 07:08:17 UTC 2021] Domain www.example.com '_acme-challenge.www.example.com' success.
[Tue Mar 16 07:08:17 UTC 2021] All success, let's return
[Tue Mar 16 07:08:17 UTC 2021] Verifying: example.com
[Tue Mar 16 07:08:21 UTC 2021] Success
[Tue Mar 16 07:08:21 UTC 2021] Verifying: www.example.com
[Tue Mar 16 07:08:25 UTC 2021] Success
[Tue Mar 16 07:08:25 UTC 2021] Removing DNS records.
[Tue Mar 16 07:08:25 UTC 2021] Removing txt: eJ2UJrvi_lAMmY0D-BFrM4WNvDXkICUR0BSJ3EXyBtw for domain: _acme-challenge.example.com
[Tue Mar 16 07:08:27 UTC 2021] Removed: Success
[Tue Mar 16 07:08:27 UTC 2021] Removing txt: u_T1kks2iNU1E_1bAtE8zpz-e81uTISws8o_ZL8YE40 for domain: _acme-challenge.www.example.com
[Tue Mar 16 07:08:30 UTC 2021] Removed: Success
[Tue Mar 16 07:08:30 UTC 2021] Verify finished, start to sign.
[Tue Mar 16 07:08:30 UTC 2021] Lets finalize the order.
[Tue Mar 16 07:08:30 UTC 2021] Le_OrderFinalize='https://acme-v02.api.letsencrypt.org/acme/finalize/123456'
[Tue Mar 16 07:08:31 UTC 2021] Downloading cert.
[Tue Mar 16 07:08:31 UTC 2021] Le_LinkCert='https://acme-v02.api.letsencrypt.org/acme/cert/123456123456'
[Tue Mar 16 07:08:32 UTC 2021] Cert success.
-----BEGIN CERTIFICATE-----
你的证书文件信息。
-----END CERTIFICATE-----
[Tue Mar 16 07:08:32 UTC 2021] Your cert is in  /acme.sh/example.com/example.com.cer
[Tue Mar 16 07:08:32 UTC 2021] Your cert key is in  /acme.sh/example.com/example.com.key
[Tue Mar 16 07:08:32 UTC 2021] The intermediate CA cert is in  /acme.sh/example.com/ca.cer
[Tue Mar 16 07:08:32 UTC 2021] And the full chain certs is there:  /acme.sh/example.com/fullchain.cer

Harbor 2.1.2 安装部署

Mon, 04 Jan 2021 06:22:44 +0000

环境

首先需要准备好 Docker + Docker-Compose 环境，Docker 在 CentOS 7.x 的安装教程请参考 这篇文章，后续文章假设你已经安装好了上述环境。

安装

标准安装

首先从 Harbor 的官方 GitHub Relase 下载最新的安装包，Harbor 本身的运行也是依赖于 Docker Compose ，整个压缩包本质上就是一系列离线镜像，执行安装脚本就是执行 docker load 命令将需要的镜像直接加载。

下载安装包，请访问 https://github.com/goharbor/harbor/releases/tag/v2.1.2 下载 tgz 压缩包。
将文件移动到安装文件夹，这里我建立了一个 /opt/harbor 文件夹。
运行 tar -xvf harbor-offline-installer-v1.10.1.tgz 解压文件包。
移动到解压完成的文件夹，编辑对应的 harbor.yml 文件，设置域名、SSL 证书等信息。

注意⚠️:

这一步的证书文件必须是全链证书(fullchain)，否则后续 docker login 的时候会提示 X509 错误。
执行 ./install.sh --with-clair 开始安装 Harbor。

完成上述步骤以后 Harbor 就安装成功了。

不使用内置 NGINX

在我们的环境当中，NGINX 容器是单独存在的，并且使用的是 docker nework create 创建的外部网络。这个时候就不能够使用 Harbor 安装脚本内提供的 NGINX，需要变更 Harbor 的 Docker Compose 文件。

执行 docker-compose down 命令，停止所有 Harbor 容器。

编辑 Harbor 的 docker-compose.yml 文件，引入外部网络，这里我以 internal-network 为例，下面是变更好的 YAML 文件。

version: '2.3'
services:
  log:
    image: goharbor/harbor-log:v2.1.2
    container_name: harbor-log
    restart: always
    dns_search: .
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - SETGID
      - SETUID
    volumes:
      - /var/log/harbor/:/var/log/docker/:z
      - type: bind
        source: ./common/config/log/logrotate.conf
        target: /etc/logrotate.d/logrotate.conf
      - type: bind
        source: ./common/config/log/rsyslog_docker.conf
        target: /etc/rsyslog.d/rsyslog_docker.conf
    ports:
      - 127.0.0.1:1514:10514
    networks:
      - harbor
      - internal-network
  registry:
    image: goharbor/registry-photon:v2.1.2
    container_name: registry
    restart: always
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETGID
      - SETUID
    volumes:
      - /data/registry:/storage:z
      - ./common/config/registry/:/etc/registry/:z
      - type: bind
        source: /data/secret/registry/root.crt
        target: /etc/registry/root.crt
      - type: bind
        source: ./common/config/shared/trust-certificates
        target: /harbor_cust_cert
    networks:
      - harbor
      - internal-network
    dns_search: .
    depends_on:
      - log
    logging:
      driver: "syslog"
      options:
        syslog-address: "tcp://127.0.0.1:1514"
        tag: "registry"
  registryctl:
    image: goharbor/harbor-registryctl:v2.1.2
    container_name: registryctl
    env_file:
      - ./common/config/registryctl/env
    restart: always
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETGID
      - SETUID
    volumes:
      - /data/registry:/storage:z
      - ./common/config/registry/:/etc/registry/:z
      - type: bind
        source: ./common/config/registryctl/config.yml
        target: /etc/registryctl/config.yml
      - type: bind
        source: ./common/config/shared/trust-certificates
        target: /harbor_cust_cert
    networks:
      - harbor
      - internal-network
    dns_search: .
    depends_on:
      - log
    logging:
      driver: "syslog"
      options:
        syslog-address: "tcp://127.0.0.1:1514"
        tag: "registryctl"
  postgresql:
    image: goharbor/harbor-db:v2.1.2
    container_name: harbor-db
    restart: always
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - SETGID
      - SETUID
    volumes:
      - /data/database:/var/lib/postgresql/data:z
    networks:
      harbor:
    dns_search: .
    env_file:
      - ./common/config/db/env
    depends_on:
      - log
    logging:
      driver: "syslog"
      options:
        syslog-address: "tcp://127.0.0.1:1514"
        tag: "postgresql"
  core:
    image: goharbor/harbor-core:v2.1.2
    container_name: harbor-core
    env_file:
      - ./common/config/core/env
    restart: always
    cap_drop:
      - ALL
    cap_add:
      - SETGID
      - SETUID
    volumes:
      - /data/ca_download/:/etc/core/ca/:z
      - /data/:/data/:z
      - ./common/config/core/certificates/:/etc/core/certificates/:z
      - type: bind
        source: ./common/config/core/app.conf
        target: /etc/core/app.conf
      - type: bind
        source: /data/secret/core/private_key.pem
        target: /etc/core/private_key.pem
      - type: bind
        source: /data/secret/keys/secretkey
        target: /etc/core/key
      - type: bind
        source: ./common/config/shared/trust-certificates
        target: /harbor_cust_cert
    networks:
      - harbor
      - internal-network
    dns_search: .
    depends_on:
      - log
      - registry
      - redis
      - postgresql
    logging:
      driver: "syslog"
      options:
        syslog-address: "tcp://127.0.0.1:1514"
        tag: "core"
  portal:
    image: goharbor/harbor-portal:v2.1.2
    container_name: harbor-portal
    restart: always
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETGID
      - SETUID
      - NET_BIND_SERVICE
    volumes:
      - type: bind
        source: ./common/config/portal/nginx.conf
        target: /etc/nginx/nginx.conf
    networks:
      - harbor
      - internal-network
    dns_search: .
    depends_on:
      - log
    logging:
      driver: "syslog"
      options:
        syslog-address: "tcp://127.0.0.1:1514"
        tag: "portal"

  jobservice:
    image: goharbor/harbor-jobservice:v2.1.2
    container_name: harbor-jobservice
    env_file:
      - ./common/config/jobservice/env
    restart: always
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETGID
      - SETUID
    volumes:
      - /data/job_logs:/var/log/jobs:z
      - type: bind
        source: ./common/config/jobservice/config.yml
        target: /etc/jobservice/config.yml
      - type: bind
        source: ./common/config/shared/trust-certificates
        target: /harbor_cust_cert
    networks:
      - harbor
      - internal-network
    dns_search: .
    depends_on:
      - core
    logging:
      driver: "syslog"
      options:
        syslog-address: "tcp://127.0.0.1:1514"
        tag: "jobservice"
  redis:
    image: goharbor/redis-photon:v2.1.2
    container_name: redis
    restart: always
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETGID
      - SETUID
    volumes:
      - /data/redis:/var/lib/redis
    networks:
      harbor:
    dns_search: .
    depends_on:
      - log
    logging:
      driver: "syslog"
      options:
        syslog-address: "tcp://127.0.0.1:1514"
        tag: "redis"

networks:
  harbor:
    external: false
  internal-network:
    external: true

在独立的 NGINX 中创建对应的配置文件，在上一步的 YAML 文件内部，我为每个容器指定了 container_name，确保容器名字唯一不会因为外部原因而变动。这个配置文件我是从之前 Harbor 内部的 NGINX 拷贝出来的，直接拿去改吧改吧就能用。

server{
    listen 80;
    server_name 你的域名;
    return 301 https://你的域名$request_uri;
}

server{
    listen 443 ssl;
    server_name 你的域名;

    # disable any limits to avoid HTTP 413 for large image uploads
    client_max_body_size 0;

    # required to avoid HTTP 411: see Issue #1486 (https://github.com/docker/docker/issues/1486)
    chunked_transfer_encoding on;

    # Add extra headers
    add_header Strict-Transport-Security "max-age=31536000; includeSubdomains; preload";
    add_header X-Frame-Options DENY;
    add_header Content-Security-Policy "frame-ancestors 'none'";

    ssl_certificate   /etc/nginx/ssl/你的域名/full.pem;      # SSL 证书文件的存放路径
    ssl_certificate_key  /etc/nginx/ssl/你的域名/key.pem;   # SSL 密钥文件的存放路径

    ssl_protocols TLSv1.2;
    ssl_ciphers '!aNULL:kECDH+AESGCM:ECDH+AESGCM:RSA+AESGCM:kECDH+AES:ECDH+AES:RSA+AES:';
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;

    location / {
      proxy_pass http://harbor-portal:8080/;
      proxy_set_header Host $http_host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

      # When setting up Harbor behind other proxy, such as an Nginx instance, remove the below line if the proxy already has similar settings.
      proxy_set_header X-Forwarded-Proto $scheme;

      proxy_cookie_path / "/; HttpOnly; Secure";

      proxy_buffering off;
      proxy_request_buffering off;
    }

    location /c/ {
      proxy_pass http://harbor-core:8080/c/;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

      # When setting up Harbor behind other proxy, such as an Nginx instance, remove the below line if the proxy already has similar settings.
      proxy_set_header X-Forwarded-Proto $scheme;

      proxy_cookie_path / "/; Secure";

      proxy_buffering off;
      proxy_request_buffering off;
    }

    location /api/ {
      proxy_pass http://harbor-core:8080/api/;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

      # When setting up Harbor behind other proxy, such as an Nginx instance, remove the below line if the proxy already has similar settings.
      proxy_set_header X-Forwarded-Proto $scheme;

      proxy_cookie_path / "/; Secure";

      proxy_buffering off;
      proxy_request_buffering off;
    }

    location /chartrepo/ {
      proxy_pass http://harbor-core:8080/chartrepo/;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

      # When setting up Harbor behind other proxy, such as an Nginx instance, remove the below line if the proxy already has similar settings.
      proxy_set_header X-Forwarded-Proto $scheme;

      proxy_cookie_path / "/; Secure";

      proxy_buffering off;
      proxy_request_buffering off;
    }

    location /v1/ {
      return 404;
    }

    location /v2/ {
      proxy_pass http://harbor-core:8080/v2/;
      proxy_set_header Host $http_host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

      # When setting up Harbor behind other proxy, such as an Nginx instance, remove the below line if the proxy already has similar settings.
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_buffering off;
      proxy_request_buffering off;
      proxy_send_timeout 900;
      proxy_read_timeout 900;
    }

    location /service/ {
      proxy_pass http://harbor-core:8080/service/;
      proxy_set_header Host $http_host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

      # When setting up Harbor behind other proxy, such as an Nginx instance, remove the below line if the proxy already has similar settings.
      proxy_set_header X-Forwarded-Proto $scheme;

      proxy_cookie_path / "/; Secure";

      proxy_buffering off;
      proxy_request_buffering off;
    }

    location /service/notifications {
      return 404;
    }
}

这里我使用的是 acme.sh 申请的泛解析 SSL 证书。

效果

ASP.NET Core 移除已注册的过滤器

Sun, 22 Nov 2020 13:23:03 +0000

背景

ABP vNext 默认对异常响应进行了处理，现在某个项目需要自定义异常响应结果。

问题

在 ABP vNext 的 MVC 模块当中，可以看到是通过 AddService(typeof(AbpExceptionFilter)) 添加的过滤器。最初我的想法是在 ConfigureService() 生命周期方法内，使用 Configure<MvcOptions> 移除已经注册的过滤器。找到对应的 Remove() 方法，发现需要提供一个 IFilterMetadata 对象，顿时懵逼。

解决

通过查阅 AddService() 方法的源码，看到底层是通过 ServiceFilterAttribute 将一个过滤器类型包裹起来。最后将其强转为一个 IFilterMetadata 扔进集合，有强转这一步我们翻阅源码可以看到 ServiceFilterAttribute 应该是实现了这个接口的。

public IFilterMetadata AddService(Type filterType, int order)
{
    if (filterType == (Type) null)
    throw new ArgumentNullException(nameof (filterType));
    ServiceFilterAttribute serviceFilterAttribute = typeof (IFilterMetadata).IsAssignableFrom(filterType) ? new ServiceFilterAttribute(filterType)
    {
    Order = order
    } : throw new ArgumentException(Resources.FormatTypeMustDeriveFromType((object) filterType.FullName, (object) typeof (IFilterMetadata).FullName), nameof (filterType));
    this.Add((IFilterMetadata) serviceFilterAttribute);
    return (IFilterMetadata) serviceFilterAttribute;
}

那么我们只需要在 Remove() 方法当中传递一个 ServiceFilterAttribute 特性包装过滤器即可。

context.Services.Configure<MvcOptions>(op =>
{
    var abpExceptionFilter = new ServiceFilterAttribute(typeof(AbpExceptionFilter));
    op.Filters.Remove(abpExceptionFilter);
});

如果需要添加自己的过滤器，只需要调用 AddService(typeof(YourFilter)) 注册。

Abp vNext 源码分析 - 21. 界面与文字的本地化

Fri, 25 Sep 2020 08:28:00 +0000

一、简介

ABP vNext 提供了全套的本地化字符串支持，具体用法可以参考官方使用文档。vNext 本身是对 Microsoft 提供的本地化组件进行了实现，通过 JSON 文件提供本地化源，这一点与老 ABP 不太一样，老 ABP 框架是全套自己手撸。vNext 针对服务端和客户端都提供了文字本地化的工具类，这样开发人员可以很快速地开发支持多语言的网站程序。

二、源码分析

本地化涉及的主要模块有 Volo.Abp.Localization.Abstractions 和 Volo.Abp.Localization，可以看到 Volo 针对包的结构也逐渐向 Microsoft 的构建方式靠拢。有直接依赖的模块是 Volo.Abp.VirtualFileSystem，之所以会引用到这个模块，是因为默认的本地化数据源是通过内嵌 JSON 文件实现的，所以会用到虚拟文件系统读取数据。

2.1 本地化的抽象接口

首先打开 Volo.Abp.Localization.Abstractions 项目，它的基本结构如下图所示，需要注意的核心类型就是 ILocalizableString 接口和它的两个具体实现 FixedLocalizableString 与 LocalizableString。

这里的 IAbpStringLocalizerFactoryWithDefaultResourceSupport 接口是为 AbpStringLocalizerFactoryExtensions 服务的，后面会详细解释，主要作用是根据默认资源类型快速创建一个 IStringLocalizer 实例。

2.1.1 本地化字符串对象的封装

可以看到在该项目内部定义了一个 ILocalizableString 的接口，在 ABP vNext 内部需要用到多语言表示的字符串属性，都是定义的 ILocalizableString 类型。本质上它是针对 Microsoft 提供的 LocalizedString 进行了一层包装，这个接口只提供了一个方法 Localize()，具体的签名见下面的代码。

public interface ILocalizableString
{
  LocalizedString Localize(IStringLocalizerFactory stringLocalizerFactory);
}

在 ABP vNext 框架当中，拥有两个实现，分别是 LocalizableString 和 FixedLocalizableString，后者用于创建固定字串的显示。例如 ABP vNext 自带的权限系统，针对权限名称和描述必须传递 ILocalizableString 类型的值，但是开发人员暂时没有提供对应的本地化翻译，这个时候就可以使用 FixedLocalizableString 传递固定字符串。

实现也是很简单，在调用了 Localize() 方法之后，会根据构造函数的 Value 创建一个新的 LocalizedString 对象。

public class FixedLocalizableString : ILocalizableString
{
    public string Value { get; }

    public FixedLocalizableString(string value)
    {
        Value = value;
    }

    public LocalizedString Localize(IStringLocalizerFactory stringLocalizerFactory)
    {
        return new LocalizedString(Value, Value);
    }
}

用法举例:

public class DataDictionaryDefinitionPermissionProvider : PermissionDefinitionProvider
{
    public override void Define(IPermissionDefinitionContext context)
    {
        var dataDictionaryGroup = context.AddGroup(DataDictionaryPermissions.GroupName, L("Permission:DataDictionary"));

        var dataDictionary = dataDictionaryGroup.AddPermission(DataDictionaryPermissions.DataDictionary.Default, L("Permission:DataDictionary"));
        dataDictionary.AddChild(DataDictionaryPermissions.DataDictionary.Create, L("Permission:Create"));
        dataDictionary.AddChild(DataDictionaryPermissions.DataDictionary.Update, L("Permission:Edit"));
        dataDictionary.AddChild(DataDictionaryPermissions.DataDictionary.Delete, L("Permission:Delete"));
      	// 这里使用了 FixedLocalizableString 提供本地化字符串。
        dataDictionary.AddChild(DataDictionaryPermissions.DataDictionary.Management, new FixedLocalizableString("字典管理"));
    }

    private static LocalizableString L(string name)
    {
        return LocalizableString.Create<DataDictionaryResource>(name);
    }
}

另一个 LocalizableString 就是正常通过 IStringLocalizerFactory 获取的本地化字符串对象。

public class LocalizableString : ILocalizableString
{
    [CanBeNull]
    public Type ResourceType { get; }

    [NotNull]
    public string Name { get; }

    public LocalizableString(Type resourceType, [NotNull] string name)
    {
        Name = Check.NotNullOrEmpty(name, nameof(name));
        ResourceType = resourceType;
    }

    public LocalizedString Localize(IStringLocalizerFactory stringLocalizerFactory)
    {
        return stringLocalizerFactory.Create(ResourceType)[Name];
    }

    public static LocalizableString Create<TResource>([NotNull] string name)
    {
        return new LocalizableString(typeof(TResource), name);
    }
}

在类型里面定义了一个静态方法，用于目标类型与 KEY 的 LocalizableString 对象，常见于权限定义的地方，在上面的示例代码中有用到过。

2.1.2 本地化资源类型的别名

TODO

2.2 本地化的基础设施

下文指代的基础设施是指 ABP vNext 为了优雅地实现 Microsoft 本地化接口所构建的一系列组件，ABP vNext 的大部分组件都是基于 Microsoft 提供的抽象体系，也是为了更好地兼容。

2.2.1 模块的启动

具体的实现模块逻辑也不复杂，首先替换了默认的本地化资源容器工厂。接着往 ABP 的虚拟文件系统添加了当前模块，以便后续访问对应的 JSON 文件，最后往本地化的相关配置项添加了两个本地化资源。

public class AbpLocalizationModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        AbpStringLocalizerFactory.Replace(context.Services);

        Configure<AbpVirtualFileSystemOptions>(options =>
        {
            options.FileSets.AddEmbedded<AbpLocalizationModule>("Volo.Abp", "Volo/Abp");
        });

        Configure<AbpLocalizationOptions>(options =>
        {
            options
                .Resources
                .Add<DefaultResource>("en");

            options
                .Resources
                .Add<AbpLocalizationResource>("en")
                .AddVirtualJson("/Localization/Resources/AbpLocalization");
        });
    }
}

2.2.2 本地化的配置

AbpLocalizationOptions 内部定义了本地化系统的相关参数，主要由资源集合(Resources)、默认资源(DefaultResourceType)、全局的本地化数据源提供者(GlobalContributors)、支持的语言(Languages)。

注意:

当进行本地化操作时，没有指定资源类型的时候会使用默认资源类型。

public class AbpLocalizationOptions
{
    public LocalizationResourceDictionary Resources { get; }

    public Type DefaultResourceType { get; set; }

    public ITypeList<ILocalizationResourceContributor> GlobalContributors { get; }

    public List<LanguageInfo> Languages { get; }

    public Dictionary<string, List<NameValue>> LanguagesMap  { get; }

    public Dictionary<string, List<NameValue>> LanguageFilesMap { get; }

    public AbpLocalizationOptions()
    {
        Resources = new LocalizationResourceDictionary();
        GlobalContributors = new TypeList<ILocalizationResourceContributor>();
        Languages = new List<LanguageInfo>();
        LanguagesMap = new Dictionary<string, List<NameValue>>();
        LanguageFilesMap = new Dictionary<string, List<NameValue>>();
    }
}

从上述代码我们可以知道，要让本地化系统正常工作，我们会接触到下面这几个类型 LocalizationResourceDictionary、LocalizationResource、ILocalizationResourceContributor、LanguageInfo。

2.2.3 本地化资源的定义

在使用本地化系统的时候，ABP vNext 文档首先会让我们定义一个类型，并在模块的 ConfigureService() 周期，通过配置项添加到本地化系统当中，就像这样。

Configure<AbpLocalizationOptions>(options =>
{
    options.Resources
        .Add<DataDictionaryResource>("en")
        .AddVirtualJson("/Localization/Resources");
});

这里可以看到，ABP vNext 实现了一套流畅方法(Fluent Method)，通过这一系列的操作，我们会生成一个 LocalizationResource 实例，添加到配置系统当中，以便后续进行使用。

这里的 Add() 方法是由 LocalizationResourceDictionary 提供的，它本质上就是一个字典，只不过由 ABP vNext 封装了一些自定义的方法，方便添加字典项数据。可以看到它的实现也很简单，首先判断字典是否存在对应的 Key，如果不存在就使用资源类型和区域文化信息构造一个新的 LocalizationResource 对象，并将其添加到字典当中。

public class LocalizationResourceDictionary : Dictionary<Type, LocalizationResource>
{
    public LocalizationResource Add<TResouce>([CanBeNull] string defaultCultureName = null)
    {
        return Add(typeof(TResouce), defaultCultureName);
    }

    public LocalizationResource Add(Type resourceType, [CanBeNull] string defaultCultureName = null)
    {
        if (ContainsKey(resourceType))
        {
            throw new AbpException("This resource is already added before: " + resourceType.AssemblyQualifiedName);
        }

        return this[resourceType] = new LocalizationResource(resourceType, defaultCultureName);
    }

    // ... 其他代码。
}

转到 LocalizationResouce 的定义，内部存储了具体的资源类型、资源名称、当前资源默认的区域文化信息、本地化数据源提供者(与全局的不同，这里仅作用于某个具体本地化资源)、继承的基类资源类型集合。

资源类型和资源名称用于区分不同的本地化资源。默认区域文化信息代表当前资源，当获取指定语言的本地化字符串失败时，会读取默认的区域文化信息对应的本地化字符串。

这里的 BaseResouceTypes 是为了复用其他资源的本地化字符串，例如你定义了一个 AppleResouceType，但是你想要获取 FruitResouceType 对应的字符串，那么就需要往这个集合添加需要服用的资源类型。ABP vNext 为 LocalizationResource 提供了一个扩展方法 AddBaseTypes() 便于在模块配置时添加需要复用的类型。除此之外 ABP vNext 也提供了特性支持，跟模块定义一样，在类定义上面添加 InheritResourceAttribute 特性，传入需要复用的类型定义即可。

[InheritResource(
    typeof(LocalizationTestValidationResource),
    typeof(LocalizationTestCountryNamesResource)
    )]
public sealed class LocalizationTestResource
{
    
}

可以看到在下述代码当中，ABP vNext 会扫描当前 ResouceType 的特性，并将其定义的复用类型添加到基类集合当中。

public class LocalizationResource
{
    [NotNull]
    public Type ResourceType { get; }

    [NotNull]
    public string ResourceName => LocalizationResourceNameAttribute.GetName(ResourceType);

    [CanBeNull]
    public string DefaultCultureName { get; set; }

    [NotNull]
    public LocalizationResourceContributorList Contributors { get; }

    [NotNull]
    public List<Type> BaseResourceTypes { get; }

    public LocalizationResource(
        [NotNull] Type resourceType, 
        [CanBeNull] string defaultCultureName = null,
        [CanBeNull] ILocalizationResourceContributor initialContributor = null)
    {
        ResourceType = Check.NotNull(resourceType, nameof(resourceType));
        DefaultCultureName = defaultCultureName;

        BaseResourceTypes = new List<Type>();
        Contributors = new LocalizationResourceContributorList();

        if (initialContributor != null)
        {
            Contributors.Add(initialContributor);
        }

        AddBaseResourceTypes();
    }

    protected virtual void AddBaseResourceTypes()
    {
        var descriptors = ResourceType
            .GetCustomAttributes(true)
            .OfType<IInheritedResourceTypesProvider>();

        foreach (var descriptor in descriptors)
        {
            foreach (var baseResourceType in descriptor.GetInheritedResourceTypes())
            {
                BaseResourceTypes.AddIfNotContains(baseResourceType);
            }
        }
    }
}

当资源类型(Resource Type) 定义好之后，通过上面的一番操作，就能够得到一个 LocalizationResource 实例，并将其添加到了 AbpLocalizationOptions 内的 LocalizationResourceDictionary 对象。开发人员定义了多少个本地化资源类型，就会往这个字典添加多少个 LocaliztaionResource 实例。

2.2.4 本地化的数据源

不论是配置项还是某个本地化资源定义类，都会存储一组 Contributor 。转到对应的接口定义，这个接口定义了三个公开方法，分别用于初始化(Initialize())、获取某个具体的本地化字符串(LocalizedString())、为指定的字典填充本地化资源数据(Fill())。

public interface ILocalizationResourceContributor
{
    void Initialize(LocalizationResourceInitializationContext context);

    LocalizedString GetOrNull(string cultureName, string name);

    void Fill(string cultureName, Dictionary<string, LocalizedString> dictionary);
}

所有的数据源都是由各个 Contributor 提供的，这里以 VirtualFileLocalizationResourceContributorBase 为例，在内部通过虚拟文件系统获取到了文件数据，通过文件数据构造一系列的字典。这里的 字典有两层，第一层的 Key 是区域文化信息，Value 是对应区域文化信息的本地化字符串字典。第二层的 Key 是本地化字符串的标识，Value 就是具体的 LocalizedString 实例。

public abstract class VirtualFileLocalizationResourceContributorBase : ILocalizationResourceContributor
{
    // ... 其他代码
    public void Initialize(LocalizationResourceInitializationContext context)
    {
        _virtualFileProvider = context.ServiceProvider.GetRequiredService<IVirtualFileProvider>();
    }

    public LocalizedString GetOrNull(string cultureName, string name)
    {
        return GetDictionaries().GetOrDefault(cultureName)?.GetOrNull(name);
    }

    public void Fill(string cultureName, Dictionary<string, LocalizedString> dictionary)
    {
        GetDictionaries().GetOrDefault(cultureName)?.Fill(dictionary);
    }

    private Dictionary<string, ILocalizationDictionary> GetDictionaries()
    {
        // ... 获取本地化资源的字典，这里的字典按区域文化进行分组。
    }

    private Dictionary<string, ILocalizationDictionary> CreateDictionaries()
    {
        var dictionaries = new Dictionary<string, ILocalizationDictionary>();

        foreach (var file in _virtualFileProvider.GetDirectoryContents(_virtualPath))
        {
            // ... 其他代码。
            // 根据文件创建某个区域文化的具体的数据源字典。
            var dictionary = CreateDictionaryFromFile(file);
            if (dictionaries.ContainsKey(dictionary.CultureName))
            {
                throw new AbpException($"{file.GetVirtualOrPhysicalPathOrNull()} dictionary has a culture name '{dictionary.CultureName}' which is already defined!");
            }

            dictionaries[dictionary.CultureName] = dictionary;
        }

        return dictionaries;
    }

    protected abstract bool CanParseFile(IFileInfo file);

    protected virtual ILocalizationDictionary CreateDictionaryFromFile(IFileInfo file)
    {
        using (var stream = file.CreateReadStream())
        {
            return CreateDictionaryFromFileContent(Utf8Helper.ReadStringFromStream(stream));
        }
    }

    protected abstract ILocalizationDictionary CreateDictionaryFromFileContent(string fileContent);
}

2.2.5 本地化资源字典

具体存储本地化字符串标识和展示文本的对象是 ILocalizationDictionary，它的具体实现是 StaticLocalizationDictionary，在其内部有一个 Dictionary<string, LocalizedString> 字典，这个字典就对应的 JSON 文件当中的本地化数据了。

{
  "culture": "zh-Hans",
  "texts": {
    "DisplayName:Abp.Localization.DefaultLanguage": "默认语言",
    "Description:Abp.Localization.DefaultLanguage": "应用程序的默认语言."
  }
}

对应的字典形式就是内部字典的 KEY:Value。

public class StaticLocalizationDictionary : ILocalizationDictionary
{
    public string CultureName { get; }

    protected Dictionary<string, LocalizedString> Dictionary { get; }

    public StaticLocalizationDictionary(string cultureName, Dictionary<string, LocalizedString> dictionary)
    {
        CultureName = cultureName;
        Dictionary = dictionary;
    }

    public virtual LocalizedString GetOrNull(string name)
    {
        return Dictionary.GetOrDefault(name);
    }

    public void Fill(Dictionary<string, LocalizedString> dictionary)
    {
        foreach (var item in Dictionary)
        {
            dictionary[item.Key] = item.Value;
        }
    }
}

当最外层的 Contributor 获取文本的时候，实际是结合区域文化信息(Culture Name) 定义到对应的本地化资源字典，再通过 Name 获取资源字典内部对应的 LocalizedString 对象。

2.3 同 Microsoft 本地化集成

2.2 节讲完了 ABP vNext 实现的基础设施，结合某个资源类型附带的 Contributor 组就能够获取到具体的本地化字符串数据，在本节主要讲解 ABP vNext 同 Microsoft 的集成。

2.3.1 IStringLocalizer 工厂

在 AbpLocalizationModule 模块中，第一句就是替换了默认的 String Localizer 工厂，并注入了 ResourceManagerStringLocalizerFactory 类型，这个类型主要用于后续的默认行为。

internal static void Replace(IServiceCollection services)
{
  services.Replace(ServiceDescriptor.Singleton<IStringLocalizerFactory, AbpStringLocalizerFactory>());
  services.AddSingleton<ResourceManagerStringLocalizerFactory>();
}

在 Microsoft 提供的 IStringLocalizerFactory 接口中，只定义了两个创建 IStringLocalizer 的方法。

public interface IStringLocalizerFactory
{
    IStringLocalizer Create(Type resourceSource);

    IStringLocalizer Create(string baseName, string location);
}

第二个方法 ABP 是直接调用的默认工厂(ResouceManagerStringLocalizerFactory) 提供的方法，而且还加了个 TODO 注明不知道什么时候会被调用。

public virtual IStringLocalizer Create(string baseName, string location)
{
    //TODO: Investigate when this is called?

    return InnerFactory.Create(baseName, location);
}

这里我们着重关注第一个方法，ABP 主要实现的也是第一个方法，它会根据传入的 resourceSource 参数从缓存当中获取(不存在则构造)对应的 IStringLocalizer 。如果在 ABP 提供的资源集合当中，没有查找到对应的 Type，则直接调用默认工厂返回 IStringLocalizer。如果存在则会以 Type 作为 Key，StringLocalizerCacheItem(就是 LocalizationResource 的马甲) 作为 Value，从缓存拿，没拿到就构建一个新的并加入到缓存中。

public virtual IStringLocalizer Create(Type resourceType)
{
    var resource = AbpLocalizationOptions.Resources.GetOrDefault(resourceType);
    if (resource == null)
    {
        return InnerFactory.Create(resourceType);
    }

    if (LocalizerCache.TryGetValue(resourceType, out var cacheItem))
    {
        return cacheItem.Localizer;
    }

    lock (LocalizerCache)
    {
        return LocalizerCache.GetOrAdd(
            resourceType,
            _ => CreateStringLocalizerCacheItem(resource)
        ).Localizer;
    }
}

private StringLocalizerCacheItem CreateStringLocalizerCacheItem(LocalizationResource resource)
{
    // 构造时会将全局配置的 Contributor 添加到对应的组。
    foreach (var globalContributor in AbpLocalizationOptions.GlobalContributors)
    {
        resource.Contributors.Add((ILocalizationResourceContributor) Activator.CreateInstance(globalContributor));
    }

    using (var scope = ServiceProvider.CreateScope())
    {
        var context = new LocalizationResourceInitializationContext(resource, scope.ServiceProvider);

        // 调用各个 Contributor 的初始化方法，进行初始化操作。
        foreach (var contributor in resource.Contributors)
        {
            contributor.Initialize(context);
        }
    }

    return new StringLocalizerCacheItem(
        new AbpDictionaryBasedStringLocalizer(
            resource,
            resource.BaseResourceTypes.Select(Create).ToList()
        )
    );
}

2.3.2 IStringLocalizer

ABP 针对 IStringLocalizer 的默认实现是 AbpDictionaryBasedStringLocalizer，IStringLocalizer 主要包含两个索引器和一个 GetAllStrings() 方法。

索引器本身直接就调用的 GetLocalizedString() 与 GetLocalizedStringFormatted() 方法。后者用于处理格式化的参数，内部就是利用的 string.Format() 方法替换占位符的内容。

public class AbpDictionaryBasedStringLocalizer : IStringLocalizer, IStringLocalizerSupportsInheritance
{
    // ... 其他代码

    public virtual LocalizedString this[string name] => GetLocalizedString(name);

    public virtual LocalizedString this[string name, params object[] arguments] => GetLocalizedStringFormatted(name, arguments);

    // ... 其他代码

    protected virtual LocalizedString GetLocalizedString(string name)
    {
        return GetLocalizedString(name, CultureInfo.CurrentUICulture.Name);
    }

    protected virtual LocalizedString GetLocalizedString(string name, string cultureName)
    {
        var value = GetLocalizedStringOrNull(name, cultureName);

        // 如果没有从当前容器取得对应的本地化字符串，就从复用的基类中获取。
        if (value == null)
        {
            foreach (var baseLocalizer in BaseLocalizers)
            {
                using (CultureHelper.Use(CultureInfo.GetCultureInfo(cultureName)))
                {
                    var baseLocalizedString = baseLocalizer[name];
                    if (baseLocalizedString != null && !baseLocalizedString.ResourceNotFound)
                    {
                        return baseLocalizedString;
                    }
                }
            }

            return new LocalizedString(name, name, resourceNotFound: true);
        }

        return value;
    }
}

转到 GetLocalizedStringOrNull() 方法内部，可以看到获取本地化字符串的具体逻辑。

首先会从本地化资源定义的 Contributors 中获取本地化字符串。
如果没有找到则尝试从类似的区域文化信息字典中获取，例如 zh-Hans(简体中文) 源没有拿到则考虑从 zh-Hant(繁体中文)获取。
还是没有取得，最后会使用默认的区域文化信息匹配对应的本地化字符串，一般来说该值建议设置为 en。

protected virtual LocalizedString GetLocalizedStringOrNull(string name, string cultureName, bool tryDefaults = true)
{
    //Try to get from original dictionary (with country code)
    var strOriginal = Resource.Contributors.GetOrNull(cultureName, name);
    if (strOriginal != null)
    {
        return strOriginal;
    }

    if (!tryDefaults)
    {
        return null;
    }

    //Try to get from same language dictionary (without country code)
    if (cultureName.Contains("-")) //Example: "tr-TR" (length=5)
    {
        var strLang = Resource.Contributors.GetOrNull(CultureHelper.GetBaseCultureName(cultureName), name);
        if (strLang != null)
        {
            return strLang;
        }
    }

    //Try to get from default language
    if (!Resource.DefaultCultureName.IsNullOrEmpty())
    {
        var strDefault = Resource.Contributors.GetOrNull(Resource.DefaultCultureName, name);
        if (strDefault != null)
        {
            return strDefault;
        }
    }

    //Not found
    return null;
}

三、总结

CefSharp 开发触屏终端遇到的问题记录

Mon, 24 Aug 2020 03:34:00 +0000

一、背景

最开始准备使用的 Chromely 做一个终端机项目，本来以为挺顺利的一个事情折腾了两天半。由于无法直接控制窗体的属性，最后还是切换到 .NET Framework 4.8 + CefSharp，记录一下遇到的坑和问题。

二、问题

2.1 输入法无法弹出

终端机系统最开始是 Windows 7，系统自带的输入法无法输入中文，后面使用的多文输入法有时候能够输入有时候不能够输入。最后折腾了半天，咨询厂家可以安装 Windows 10，安装后系统自带输入法可以输入中文。

新的问题又出现了，如果窗口没有全屏的情况下，输入法是可以将内容输入到网页的文本框。但是窗口置顶且全屏，触摸输入的内容就像无法获取焦点一样，无法输入。

爬了很多网站，都没有给出个明确的答案，最后在 某篇 Issue 里面说将 browser.FocusHandler 属性设置为 null，解决该问题。

2.2 重写右键菜单

这个问题比较简单，只需要重新实现 IMenuHandler 接口，替换掉 Cef Browser 的对应组件即可。

示例:

public class CustomMenuHandler : IContextMenuHandler
{
    public void OnBeforeContextMenu(IWebBrowser chromiumWebBrowser, IBrowser browser, IFrame frame, IContextMenuParams parameters, IMenuModel model)
    {
        model.Clear();

        model.AddItem((CefMenuCommand) 21000, "菜单项1");
    }

    public bool OnContextMenuCommand(IWebBrowser chromiumWebBrowser, IBrowser browser, IFrame frame, IContextMenuParams parameters, CefMenuCommand commandId,
        CefEventFlags eventFlags)
    {
        if (commandId == (CefMenuCommand) 21000)
        {
            MessageBox.Show("我是菜单项1");
        }
        return false;
    }

    public void OnContextMenuDismissed(IWebBrowser chromiumWebBrowser, IBrowser browser, IFrame frame)
    {
    }

    public bool RunContextMenu(IWebBrowser chromiumWebBrowser, IBrowser browser, IFrame frame, IContextMenuParams parameters, IMenuModel model,
        IRunContextMenuCallback callback)
    {
        return false;
    }
}

2.3 身份证读卡器对接

身份证读卡器终端机上面是集成新中新的，跟着 SDK 的 Demo 来，一跑程序就炸。没有跑出任何异常，最后发现是 Chromely 吞掉了异常。实际的错误问题是 DLL 的版本不对，新中新只提供了 x86 的 DLL，但程序编译的是 x64。最后将程序的目标平台改为 x86 解决问题。

2.4 前端同后端通讯

其实就是 JS 调用后端的接口，之前搜索的文章都是 CefSharp 的老版本代码，最新的是使用 browser.JavascriptObjectRepository.Register() 注入处理器，然后前端再进行调用。具体代码可以参考 CefSharp 的 官方 Demo。

2.5 打开调试窗口

CefSharp Browser 提供了一个 ShowDevTools() 方法用于打开调试窗口，需要注意的是，必须在浏览器完全初始化之后才能够调用。所以你需要判断一下 CefSharp Browser 的状态。

browser.IsBrowserInitializedChanged += (sender, args) =>
{
    if (browser.IsBrowserInitialized)
    {
        browser.ShowDevTools();
    }
};

2.6 关于触屏的其他配置

在 Cef 初始化的时候，需要对 Cef 进行一些其他的配置，例如开启触屏事件、禁用 USB 键盘等。

private static void InitializeCef()
{
    CefSharpSettings.LegacyJavascriptBindingEnabled = true;
    CefSharpSettings.SubprocessExitIfParentProcessClosed = true;

    Cef.EnableHighDPISupport();

    var settings = new CefSettings();
    settings.CefCommandLineArgs.Add("disable-usb-keyboard-detect", "1");
    settings.CefCommandLineArgs.Add("enable-media-stream", "1");
    settings.CefCommandLineArgs.Add("touch-events", "1");

    Cef.Initialize(settings);
}

2.7 允许前端跨域和调用摄像头

在 [2.6](#2.6 关于触屏的其他配置) 一节中，我通过添加 enable-media-stream 参数让前端可以直接调用摄像头。如果想要让前端发起跨域请求，就得在 Browser 里面将 WebSecurity 属性设置为 Disabled。

browser.BrowserSettings.WebSecurity = CefState.Disabled;

2.8 下载文件

CefSharp 针对于前端的下载文件动作进行了处理，如果你对于这个动作有自己的处理逻辑，可以实现 IDownloadHandler 接口。然后在 Browser 的对应属性替换成你自己的实现即可。

dotNET Core 的 Docker 容器目录乱码问题

Thu, 30 Jul 2020 07:37:00 +0000

现象

使用 docker exec -ti <容器名> bash 进入容器，使用 ls 命令列出的数据里面，中文没有正常显示。

原因

就是对应的 Shell 字符集不正确的问题，调整对应的字符集为 UTF-8 即可。

解决

首先执行 locale -a，查看输出的内容里面是否有 C.UTF-8 字符集。
执行 locale 查看当前的字符集，如果均为 POSIX 说明有问题，需要进行变更。
变更的方法很简单，创建/更改一下环境变量即可。

export LC_ALL="C.UTF-8"

上面这种方法仅对当前会话有效，如果想永久生效，将上面这句话放到对应的 Shell 的 Profile 里面即可。

Abp vNext 源码分析 - 23. 二进制大对象系统(BLOB)

Mon, 27 Jul 2020 12:09:00 +0000

一、简介

ABP vNext 在 v 2.9.x 版本当中添加了 BLOB 系统，主要用于存储大型二进制文件。ABP 抽象了一套通用的 BLOB 体系，开发人员在存储或读取二进制文件时，可以忽略具体实现，直接使用 IBlobContainer 或 IBlobContainer<T> 进行操作。官方的 BLOB Provider 实现有 Azure、AWS、FileSystem(文件系统存储)、Database(数据库存储)、阿里云 OSS，你也可以自己继承 BlobProviderBase 来实现其他的 Provider。

BLOB 常用于各类二进制文件存储和管理，基本就是对云服务的 OSS 进行了抽象，在使用当中也会有 Bucket 和 Object Key 的概念，在 BLOB 里面对应的就是 ContainerName 和 BlobName。

关于 BLOB 的官方使用指南，可以参考 https://docs.abp.io/en/abp/latest/Blob-Storing，本文的阅读前提是建立在你已经阅读过该指南，并有一定的使用经验。

二、源码分析

2.1 模块分析

看一个 ABP 的库项目，首先从他的 Module 入手，对应的 BLOB 核心库的 Module 就是 AbpBlobStoringModule 类，在其内部，只进行了两个操作，注入了 IBlobContainer 与 IBlobContainer<> 的实现。

public override void ConfigureServices(ServiceConfigurationContext context)
{
    context.Services.AddTransient(
        typeof(IBlobContainer<>),
        typeof(BlobContainer<>)
    );

    context.Services.AddTransient(
        typeof(IBlobContainer),
        serviceProvider => serviceProvider
            .GetRequiredService<IBlobContainer<DefaultContainer>>()
    );
}

从上述代码可以看出来，IBlobContainer 的默认实现还是基于 BlobContainer<T> 的。那么为啥会有个泛型的 Container，从简介中可以看到 OSS 里面对应的 Bucket 其实就是一个 IBlobContainer。假如你会针对某云的多个 Bucket 进行操作，那么就需要类型化的 BlobContainer 了。

在这里可以看到，IBlobContainer 的实现是一个工厂方法，这一点在后面会进行解释。

2.2 BLOB 容器

2.2.1 容器的定义

每个容器就是一个 OSS 的 Bucket，开发人员在对 BLOB 进行操作时，会注入 IBlobContainer/IBlobContainer<T>，通过接口提供的 5 种方法进行操作，这五个方法分别是 保存对象、删除对象、判断对象是否存在、获取对象、获取对象(不存在返回 NULL)。

public interface IBlobContainer
{
    // 保存对象
    Task SaveAsync(
        string name,
        Stream stream,
        bool overrideExisting = false,
        CancellationToken cancellationToken = default
    );
    
    // 删除对象
    Task<bool> DeleteAsync(
        string name,
        CancellationToken cancellationToken = default
    );
    
    // 判断对象是否存在
    Task<bool> ExistsAsync(
        string name,
        CancellationToken cancellationToken = default
    );
    
    // 获取对象
    Task<Stream> GetAsync(
        string name,
        CancellationToken cancellationToken = default
    );

    // 获取对象(不存在返回 NULL)
    Task<Stream> GetOrNullAsync(
        string name,
        CancellationToken cancellationToken = default
    );
    
    //TODO: Create shortcut extension methods: GetAsArraryAsync, GetAsStringAsync(encoding) (and null versions)
}

泛型的 BLOB 容器也是集成自该接口，内部没有任何特殊的方法。

public interface IBlobContainer<TContainer> : IBlobContainer
    where TContainer: class
{
    
}

2.2.2 容器的实现

容器的两种实现都存放在 BlobContainer.cs 文件当中，标注容器实现内部都会有一个 ContainerName，用于标识不同的容器，并且和其他的组件作为 关联键 进行绑定。每个容器都会关联 BlobContainerConfiguration、IBlobProvider 两个组件，它们分别提供了容器的配置信息和容器的具体实现 Provider，在容器构造的时候根据 ContainerName 分别进行初始化。

public class BlobContainer : IBlobContainer
{
    protected string ContainerName { get; }

    protected BlobContainerConfiguration Configuration { get; }

    protected IBlobProvider Provider { get; }

    protected ICurrentTenant CurrentTenant { get; }

    protected ICancellationTokenProvider CancellationTokenProvider { get; }

    protected IServiceProvider ServiceProvider { get; }

    // ... 其他代码。
}

可以看到这里还注入了 ICurrentTenant，注入该对象的主要作用是用来处理多租户的情况，如果当前容器启用了多租户，那么会手动 Change()。下面以 SaveAsync() 方法为例。

public virtual async Task SaveAsync(
    string name,
    Stream stream,
    bool overrideExisting = false,
    CancellationToken cancellationToken = default)
{
    // 变更当前租户信息，当启用了多租户时，会使用当前租户进行变更。
    using (CurrentTenant.Change(GetTenantIdOrNull()))
    {
        // 根据 ContainerName 取得对应的标准化容器名称和对象名称。
        var (normalizedContainerName, normalizedBlobName) = NormalizeNaming(ContainerName, name);

        // 使用 ContainerName 匹配的 Provider 存储对象数据。
        await Provider.SaveAsync(
            new BlobProviderSaveArgs(
                normalizedContainerName,
                Configuration,
                normalizedBlobName,
                stream,
                overrideExisting,
                CancellationTokenProvider.FallbackToProvider(cancellationToken)
            )
        );
    }
}

这里有两个地方需要单独分析，第一个是 NormalizeNaming() 的作用，第二个是 BlobProviderSaveArgs 对象。

2.2.3.1 名称标准化对象

IBlobNamingNormalizer(BLOB 名称标准化对象)，主要用于将一个字符串进行标准化处理，防止 Provider 无法处理这种名称。各大 OSS 都对容器的名称或对象的名称有命名要求，比如必须全部小写，不能有哪些特殊符号等等。

protected virtual (string, string) NormalizeNaming(string containerName,  string blobName)
{
    // 从当前的配置信息中获取对应的标准化器，如果不存在任何标准化工具对象，则直接返回原始名称。
    if (!Configuration.NamingNormalizers.Any())
    {
        return (containerName, blobName);
    }

    using (var scope = ServiceProvider.CreateScope())
    {
        // 获取所有的标准化器，并依次进行名称的标准化处理。
        foreach (var normalizerType in Configuration.NamingNormalizers)
        {
            var normalizer = scope.ServiceProvider
                .GetRequiredService(normalizerType)
                .As<IBlobNamingNormalizer>();

            containerName = normalizer.NormalizeContainerName(containerName);
            blobName = normalizer.NormalizeBlobName(blobName);
        }

        return (containerName, blobName);
    }
}

2.2.3.2 BLOB 上下文

在 BLOB 里面，ABP 分别为每个操作都定义了一个 ***Args 对象，它就是一个上下文对象，用于在整个调用周期中传递参数。

2.2.3.3 BLOB 配置信息

每个 BLOB 容器都会有一个 BlobContainerConfiguration 用于存储配置信息，它主要有以下几个重要的属性。

public class BlobContainerConfiguration
{
    // 当前 BLOB 容器对应的 Provider 类型。
    public Type ProviderType { get; set; }

    // 当前 BLOB 容器是否启用了多租户。
    public bool IsMultiTenant { get; set; } = true;

    // 当前 BLOB 容器的名称标准化对象。
    public ITypeList<IBlobNamingNormalizer> NamingNormalizers { get; }

    // 当前 BLOB 容器的属性。
    [NotNull] private readonly Dictionary<string, object> _properties;

    // 当尝试获取某些配置属性，但是不存在时，会从这个 Configuration 拿取数据。
    [CanBeNull] private readonly BlobContainerConfiguration _fallbackConfiguration;

    public BlobContainerConfiguration(BlobContainerConfiguration fallbackConfiguration = null)
    {
        NamingNormalizers = new TypeList<IBlobNamingNormalizer>();
        _fallbackConfiguration = fallbackConfiguration;
        _properties = new Dictionary<string, object>();
    }

    [CanBeNull]
    public T GetConfigurationOrDefault<T>(string name, T defaultValue = default)
    {
        return (T) GetConfigurationOrNull(name, defaultValue);
    }

    [CanBeNull]
    public object GetConfigurationOrNull(string name, object defaultValue = null)
    {
        return _properties.GetOrDefault(name) ??
                _fallbackConfiguration?.GetConfigurationOrNull(name, defaultValue) ??
                defaultValue;
    }

    // ... 其他代码。
}

在后续各种 Provider 里面定义的配置项，本质上就是对 _properties 字典进行操作。

2.2.3 容器的构造与初始化

BLOB 容器并不是通过 IoC 容器直接解析构造的，而是通过 IBlobContainerFactory 工厂进行创建，与容器相关的配置对象和 BLOB Provider 也是在这个时候进行构造赋值。

public class BlobContainerFactory : IBlobContainerFactory, ITransientDependency
{
    protected IBlobProviderSelector ProviderSelector { get; }

    protected IBlobContainerConfigurationProvider ConfigurationProvider { get; }

    protected ICurrentTenant CurrentTenant { get; }

    protected ICancellationTokenProvider CancellationTokenProvider { get; }

    protected IServiceProvider ServiceProvider { get; }

    public BlobContainerFactory(
        IBlobContainerConfigurationProvider configurationProvider,
        ICurrentTenant currentTenant,
        ICancellationTokenProvider cancellationTokenProvider,
        IBlobProviderSelector providerSelector,
        IServiceProvider serviceProvider)
    {
        ConfigurationProvider = configurationProvider;
        CurrentTenant = currentTenant;
        CancellationTokenProvider = cancellationTokenProvider;
        ProviderSelector = providerSelector;
        ServiceProvider = serviceProvider;
    }

    public virtual IBlobContainer Create(string name)
    {
        // 根据容器的名称，获取对应的配置。
        var configuration = ConfigurationProvider.Get(name);

        // 构造一个新的容器对象。
        return new BlobContainer(
            name,
            configuration,
            // 一样的是根据容器名称，获得匹配的 Provider 类型。
            ProviderSelector.Get(name),
            CurrentTenant,
            CancellationTokenProvider,
            ServiceProvider
        );
    }
}

那么这个工厂方法是在什么时候调用的呢？跳转到工厂方法的实现，发现会被一个静态扩展方法所调用，重要的是这个方法是一个泛型方法，这样就与开头的类型化 BLOB 容器相对应了。

public static class BlobContainerFactoryExtensions
{
    public static IBlobContainer Create<TContainer>(
        this IBlobContainerFactory blobContainerFactory
    )
    {
        // 通过 GetContainerName 方法获取容器的名字。
        return blobContainerFactory.Create(
            BlobContainerNameAttribute.GetContainerName<TContainer>()
        );
    }
}

GetContainerName() 方法也很简单，如果容器类型没有指定 BlobContainerNameAttribute 特性，那么就会默认使用类型的 FullName 作为名称。

public static string GetContainerName(Type type)
{
    var nameAttribute = type.GetCustomAttribute<BlobContainerNameAttribute>();

    if (nameAttribute == null)
    {
        return type.FullName;
    }

    return nameAttribute.GetName(type);
}

最后的最后，看一下这个类型化的 BLOB 容器。

public class BlobContainer<TContainer> : IBlobContainer<TContainer>
    where TContainer : class
{
    private readonly IBlobContainer _container;

    public BlobContainer(IBlobContainerFactory blobContainerFactory)
    {
        _container = blobContainerFactory.Create<TContainer>();
    }

    // ... 其他代码。
}

对应的是模块初始化的工厂方法：

context.Services.AddTransient(
    typeof(IBlobContainer),
    serviceProvider => serviceProvider
        .GetRequiredService<IBlobContainer<DefaultContainer>>()

这里的 DefaultContainer 就指定了该特性，所以本质上一个 IBlobContainer 就是一个类型化的容器，它的泛型参数是 DefaultContainer。

[BlobContainerName(Name)]
public class DefaultContainer
{
    public const string Name = "default";
}

2.2.3.1 BLOB 的配置提供者

BLOB 容器工厂使用 IBlobContainerConfigurationProvider 来匹配对应容器的配置信息，实现比较简单，直接注入了 AbpBlobStoringOptions 并尝试从它的 BlobContainerConfigurations 中获取配置对象。

public class DefaultBlobContainerConfigurationProvider : IBlobContainerConfigurationProvider, ITransientDependency
{
    protected AbpBlobStoringOptions Options { get; }

    public DefaultBlobContainerConfigurationProvider(IOptions<AbpBlobStoringOptions> options)
    {
        Options = options.Value;
    }
    
    public virtual BlobContainerConfiguration Get(string name)
    {
        return Options.Containers.GetConfiguration(name);
    }
}

这里的 BlobContainerConfigurations 对象，核心就是一个键值对，键就是 BLOB 容器的名称，值就是容器对应的配置对象。

public class BlobContainerConfigurations
{
    private BlobContainerConfiguration Default => GetConfiguration<DefaultContainer>();

    private readonly Dictionary<string, BlobContainerConfiguration> _containers;

    public BlobContainerConfigurations()
    {
        _containers = new Dictionary<string, BlobContainerConfiguration>
        {
            // 添加默认的 BLOB 容器。
            [BlobContainerNameAttribute.GetContainerName<DefaultContainer>()] = new BlobContainerConfiguration()
        };
    }

    // ... 其他代码

    public BlobContainerConfigurations Configure(
        [NotNull] string name,
        [NotNull] Action<BlobContainerConfiguration> configureAction)
    {
        Check.NotNullOrWhiteSpace(name, nameof(name));
        Check.NotNull(configureAction, nameof(configureAction));

        configureAction(
            _containers.GetOrAdd(
                name,
                () => new BlobContainerConfiguration(Default)
            )
        );

        return this;
    }

    public BlobContainerConfigurations ConfigureAll(Action<string, BlobContainerConfiguration> configureAction)
    {
        foreach (var container in _containers)
        {
            configureAction(container.Key, container.Value);
        }
        
        return this;
    }

    // ... 其他代码
}

在使用过程中，我们在模块里面调用的 Configure() 方法，就会在字典添加一个新的 Item，并为其赋值。而 ConfigureAll() 就是遍历这个字典，为每个 BLOB 容器调用委托，以便进行配置。

2.2.3.2 BLOB 的 Provider 选择器

在构造 BLOB 容器的时候，BLOB 容器工厂通过 IBlobProviderSelector 来选择对应的 BLOB Provider，具体选择哪一个是根据 BlobContainerConfiguration 里面的 ProviderType 决定的。

public virtual IBlobProvider Get([NotNull] string containerName)
{
    Check.NotNull(containerName, nameof(containerName));
    
    // 获得当前 BLOB 容器对应的配置信息。
    var configuration = ConfigurationProvider.Get(containerName);
    
    if (!BlobProviders.Any())
    {
        throw new AbpException("No BLOB Storage provider was registered! At least one provider must be registered to be able to use the Blog Storing System.");
    }
    
    foreach (var provider in BlobProviders)
    {
        // 通过配置信息匹配对应的 Provider。
        if (ProxyHelper.GetUnProxiedType(provider).IsAssignableTo(configuration.ProviderType))
        {
            return provider;
        }
    }

    throw new AbpException(
        $"Could not find the BLOB Storage provider with the type ({configuration.ProviderType.AssemblyQualifiedName}) configured for the container {containerName} and no default provider was set."
    );
}

上面的 BlobProviders 其实就是直接从 IoC 解析的 IEnumerable<IBlobProvider> 对象，我还找了半天是哪个地方进行赋值的。当 ABP 框架自动之后，会自动将已经实现的 BLOB Provider 注入到 IoC 容器中，如果某个容器在使用时指定了对应的配置参数，则会匹配对应的 BLOB Provider。

2.3 Provider 的实现

2.3.1 File System

文件系统作为 BLOB 的最简化实现，本质就是通过文件夹进行租户隔离动作，所有操作都会将数据持久化到硬盘上。核心代码就一个文件 FileSystemBlobProvider，在这个文件内部定义了具体的执行逻辑，我们这里大概看一下 SaveAsyn() 的实现。

public override async Task SaveAsync(BlobProviderSaveArgs args)
{
    var filePath = FilePathCalculator.Calculate(args);

    if (!args.OverrideExisting && await ExistsAsync(filePath))
    {
        throw new BlobAlreadyExistsException($"Saving BLOB '{args.BlobName}' does already exists in the container '{args.ContainerName}'! Set {nameof(args.OverrideExisting)} if it should be overwritten.");
    }

    DirectoryHelper.CreateIfNotExists(Path.GetDirectoryName(filePath));

    var fileMode = args.OverrideExisting
        ? FileMode.Create
        : FileMode.CreateNew;

    await Policy.Handle<IOException>()
        .WaitAndRetryAsync(2, retryCount => TimeSpan.FromSeconds(retryCount))
        .ExecuteAsync(async () =>
        {
            using (var fileStream = File.Open(filePath, fileMode, FileAccess.Write))
            {
                await args.BlobStream.CopyToAsync(
                    fileStream,
                    args.CancellationToken
                );

                await fileStream.FlushAsync();
            }
        });
}

很简单，通过 FilePathCalculator 计算出来文件的具体路径，然后结合配置参数来判断文件是否存在，以及是否进入后续操作。通过 Polly 提供的重试机制来创建文件。

2.3.2 DataBase

数据库 Provider 是利用数据库的 BLOB 类型，将这些大型对象存储到数据库当中，不太建议这样操作。这里不再进行详细介绍，基本大同小异。

2.3.3 各类 OSS (腾讯云为例)

OSS 作为云厂商的标配，基本概念和操作都与 ABP 的 BLOB 相匹配，集成起来也还是比较简单，就是将各个 OSS 的 SDK 塞进来就行。这里注意点的是，每个 BLOB Provider 都会编写一个基于 BlobContainerConfiguration 类型的静态方法，取名都叫做 UseXXX()，并在里面对具体的配置进行赋值。

public static class TencentCloudBlobContainerConfigurationExtensions
{
    public static TencentCloudBlobProviderConfiguration GetTencentCloudConfiguration(
        this BlobContainerConfiguration containerConfiguration)
    {
        return new TencentCloudBlobProviderConfiguration(containerConfiguration);
    }

    public static BlobContainerConfiguration UseTencentCloud(
        this BlobContainerConfiguration containerConfiguration,
        Action<TencentCloudBlobProviderConfiguration> tencentCloudConfigureAction)
    {
        containerConfiguration.ProviderType = typeof(TencentCloudBlobProvider);
        containerConfiguration.NamingNormalizers.TryAdd<TencentCloudBlobNamingNormalizer>();
        
        tencentCloudConfigureAction(new TencentCloudBlobProviderConfiguration(containerConfiguration));

        return containerConfiguration;
    }
}

可能会对这个 TencentCloudBlobProviderConfiguration 有一些好奇，其实就是个套娃，因为直接传入了 BlobContainerConfiguration 对象，里面的各种属性本质上就是对配置项的那个 Dictionary<string,object> 进行操作。

public class TencentCloudBlobProviderConfiguration
{
    public string AppId
    {
        get => _containerConfiguration.GetConfigurationOrDefault<string>(TencentCloudBlobProviderConfigurationNames.AppId);
        set => _containerConfiguration.SetConfiguration(TencentCloudBlobProviderConfigurationNames.AppId, value);
    }

    public string SecretId
    {
        get => _containerConfiguration.GetConfigurationOrDefault<string>(TencentCloudBlobProviderConfigurationNames.SecretId);
        set => _containerConfiguration.SetConfiguration(TencentCloudBlobProviderConfigurationNames.SecretId, value);
    }

    // ... 其他代码

    public TencentCloudBlobProviderConfiguration(BlobContainerConfiguration containerConfiguration)
    {
        _containerConfiguration = containerConfiguration;
    }
}

腾讯云的 BLOB Provider 仓库：https://github.com/EasyAbp/Abp.BlobStoring.TencentCloud

2.4 回顾

开发人员可以在模块的 ConfigureService() 阶段为所有容器或者特定容器指定参数。
ABP vNext 框架会注入所有的 BLOB Provider，并注入默认的 IBlobContainer<DefaultContainer> 容器和其他的类型化容器实现。
当需要使用 BLOB 时，开发人员注入了 IBlobContainer 或 IBlobContainer<T>。
BLOB 容器的工厂会根据容器的名称匹配对应的 BLOB Provider 和配置对象。
BLOB Provider 根据 **Args 参数内部附带的配置对象，读取对应的配置信息进行自定义的操作。

三、总结

小型项目直接集成 FileSystem 即可，中大型项目可以使用各种 OSS Provider，BLOB 系统可以简化开发人员对于大量二进制文件的管理操作。最近工作相当杂乱繁忙，下半年希望有时间继续学习更新吧。

其他相关文章，请参阅 文章目录 。

Abp vNext 源码分析 - 19. 多租户

Tue, 03 Mar 2020 04:03:15 +0000

一、简介

ABP vNext 原生支持多租户体系，可以让开发人员快速地基于框架开发 SaaS 系统。ABP vNext 实现多租户的思路也非常简单，通过一个 TenantId 来分割各个租户的数据，并且在查询的时候使用统一的全局过滤器(类似于软删除)来筛选数据。

关于多租户体系的东西，基本定义与核心逻辑存放在 Volo.ABP.MultiTenancy 内部。针对 ASP.NET Core MVC 的集成则是由 Volo.ABP.AspNetCore.MultiTenancy 项目实现的，针对多租户的解析都在这个项目内部。租户数据的存储和管理都由 Volo.ABP.TenantManagement 模块提供，开发人员也可以直接使用该项目快速实现多租户功能。

二、源码分析

2.1 启动模块

AbpMultiTenancyModule 模块是启用整个多租户功能的核心模块，内部只进行了一个动作，就是从配置类当中读取多租户的基本信息，以 JSON Provider 为例，就需要在 appsettings.json 里面有 Tenants 节。

"Tenants": [
    {
      "Id": "446a5211-3d72-4339-9adc-845151f8ada0",
      "Name": "tenant1"
    },
    {
      "Id": "25388015-ef1c-4355-9c18-f6b6ddbaf89d",
      "Name": "tenant2",
      "ConnectionStrings": {
        "Default": "...write tenant2's db connection string here..."
      }
    }
  ]

2.1.1 默认租户来源

这里的数据将会作为默认租户来源，也就是说在确认当前租户的时候，会从这里面的数据与要登录的租户进行比较，如果不存在则不允许进行操作。

public interface ITenantStore
{
    Task<TenantConfiguration> FindAsync(string name);

    Task<TenantConfiguration> FindAsync(Guid id);

    TenantConfiguration Find(string name);

    TenantConfiguration Find(Guid id);
}

默认的存储实现：

[Dependency(TryRegister = true)]
public class DefaultTenantStore : ITenantStore, ITransientDependency
{
    // 直接从 Options 当中获取租户数据。
    private readonly AbpDefaultTenantStoreOptions _options;

    public DefaultTenantStore(IOptionsSnapshot<AbpDefaultTenantStoreOptions> options)
    {
        _options = options.Value;
    }

    public Task<TenantConfiguration> FindAsync(string name)
    {
        return Task.FromResult(Find(name));
    }

    public Task<TenantConfiguration> FindAsync(Guid id)
    {
        return Task.FromResult(Find(id));
    }

    public TenantConfiguration Find(string name)
    {
        return _options.Tenants?.FirstOrDefault(t => t.Name == name);
    }

    public TenantConfiguration Find(Guid id)
    {
        return _options.Tenants?.FirstOrDefault(t => t.Id == id);
    }
}

除了从配置文件当中读取租户信息以外，开发人员也可以自己实现 ITenantStore 接口，比如说像 TenantManagement 一样，将租户信息存储到数据库当中。

2.1.2 基于数据库的租户存储

话接上文，我们说过在 Volo.ABP.TenantManagement 模块内部有提供另一种 ITenantStore 接口的实现，这个类型叫做 TenantStore，内部逻辑也很简单，就是从仓储当中查找租户数据。

public class TenantStore : ITenantStore, ITransientDependency
{
    private readonly ITenantRepository _tenantRepository;
    private readonly IObjectMapper<AbpTenantManagementDomainModule> _objectMapper;
    private readonly ICurrentTenant _currentTenant;

    public TenantStore(
        ITenantRepository tenantRepository, 
        IObjectMapper<AbpTenantManagementDomainModule> objectMapper,
        ICurrentTenant currentTenant)
    {
        _tenantRepository = tenantRepository;
        _objectMapper = objectMapper;
        _currentTenant = currentTenant;
    }

    public async Task<TenantConfiguration> FindAsync(string name)
    {
        // 变更当前租户为租主。
        using (_currentTenant.Change(null)) //TODO: No need this if we can implement to define host side (or tenant-independent) entities!
        {
            // 通过仓储查询租户是否存在。
            var tenant = await _tenantRepository.FindByNameAsync(name);
            if (tenant == null)
            {
                return null;
            }

            // 将查询到的信息转换为核心库定义的租户信息。
            return _objectMapper.Map<Tenant, TenantConfiguration>(tenant);
        }
    }

    // ... 其他的代码已经省略。
}

可以看到，最后也是返回的一个 TenantConfiguration 类型。关于这个类型，是 ABP 在多租户核心库定义的一个基本类型之一，主要是用于规定持久化一个租户信息需要包含的属性。

[Serializable]
public class TenantConfiguration
{
    // 租户的 Guid。
    public Guid Id { get; set; }

    // 租户的名称。
    public string Name { get; set; }

    // 租户对应的数据库连接字符串。
    public ConnectionStrings ConnectionStrings { get; set; }

    public TenantConfiguration()
    {
        
    }

    public TenantConfiguration(Guid id, [NotNull] string name)
    {
        Check.NotNull(name, nameof(name));

        Id = id;
        Name = name;

        ConnectionStrings = new ConnectionStrings();
    }
}

2.2 租户的解析

ABP vNext 如果要判断当前的租户是谁，则是通过 AbpTenantResolveOptions 提供的一组 ITenantResolveContributor 进行处理的。

public class AbpTenantResolveOptions
{
    // 会使用到的这组解析对象。
    [NotNull]
    public List<ITenantResolveContributor> TenantResolvers { get; }

    public AbpTenantResolveOptions()
    {
        TenantResolvers = new List<ITenantResolveContributor>
        {
            // 默认的解析对象，会通过 Token 内字段解析当前租户。
            new CurrentUserTenantResolveContributor()
        };
    }
}

这里的设计与权限一样，都是由一组 解析对象(解析器) 进行处理，在上层开放的入口只有一个 ITenantResolver ，内部通过 foreach 执行这组解析对象的 Resolve() 方法。

下面就是我们 ITenantResolver 的默认实现 TenantResolver，你可以在任何时候调用它。比如说你在想要获得当前租户 Id 的时候。不过一般不推荐这样做，因为 ABP 已经给我们提供了 MultiTenancyMiddleware 中间件。

也就是说，在每次请求的时候，都会将这个 Id 通过 ICurrentTenant.Change() 进行变更，那么在这个请求执行完成之前，通过 ICurrentTenant 取得的 Id 都会是解析器解析出来的 Id。

public class TenantResolver : ITenantResolver, ITransientDependency
{
    private readonly IServiceProvider _serviceProvider;
    private readonly AbpTenantResolveOptions _options;

    public TenantResolver(IOptions<AbpTenantResolveOptions> options, IServiceProvider serviceProvider)
    {
        _serviceProvider = serviceProvider;
        _options = options.Value;
    }

    public TenantResolveResult ResolveTenantIdOrName()
    {
        var result = new TenantResolveResult();

        using (var serviceScope = _serviceProvider.CreateScope())
        {
            // 创建一个解析上下文，用于存储解析器的租户 Id 解析结果。
            var context = new TenantResolveContext(serviceScope.ServiceProvider);

            // 遍历执行解析器。
            foreach (var tenantResolver in _options.TenantResolvers)
            {
                tenantResolver.Resolve(context);

                result.AppliedResolvers.Add(tenantResolver.Name);

                // 如果有某个解析器为上下文设置了值，则跳出。
                if (context.HasResolvedTenantOrHost())
                {
                    result.TenantIdOrName = context.TenantIdOrName;
                    break;
                }
            }
        }

        return result;
    }
}

2.2.1 默认的解析对象

如果不使用 Volo.Abp.AspNetCore.MultiTenancy 模块，ABP vNext 会调用 CurrentUserTenantResolveContributor 解析当前操作的租户。

public class CurrentUserTenantResolveContributor : TenantResolveContributorBase
{
    public const string ContributorName = "CurrentUser";

    public override string Name => ContributorName;

    public override void Resolve(ITenantResolveContext context)
    {
        // 从 Token 当中获取当前登录用户的信息。
        var currentUser = context.ServiceProvider.GetRequiredService<ICurrentUser>();
        if (currentUser.IsAuthenticated != true)
        {
            return;
        }

        // 设置解析上下文，确认当前的租户 Id。
        context.Handled = true;
        context.TenantIdOrName = currentUser.TenantId?.ToString();
    }
}

在这里可以看到，如果从 Token 当中解析到了租户 Id，会将这个 Id 传递给 解析上下文。这个上下文在最开始已经遇到过了，如果 ABP vNext 在解析的时候发现租户 Id 被确认了，就不会执行剩下的解析器。

2.2.2 ABP 提供的其他解析器

ABP 在 Volo.Abp.AspNetCore.MultiTenancy 模块当中还提供了其他几种解析器，他们的作用分别如下。

解析器类型	作用	优先级
`QueryStringTenantResolveContributor`	通过 Query String 的 `__tenant` 参数确认租户。	2
`RouteTenantResolveContributor`	通过路由判断当前租户。	3
`HeaderTenantResolveContributor`	通过 Header 里面的 `__tenant` 确认租户。	4
`CookieTenantResolveContributor`	通过携带的 Cookie 确认租户。	5
`DomainTenantResolveContributor`	二级域名解析器，通过二级域名确定租户。	第二

2.2.3 域名解析器

这里比较有意思的是 DomainTenantResolveContributor，开发人员可以通过 AbpTenantResolveOptions.AddDomainTenantResolver() 方法添加这个解析器。域名解析器会通过解析二级域名来匹配对应的租户，例如我针对租户 A 分配了一个二级域名 http://a.system.com，那么这个 a 就会被作为租户名称解析出来，最后传递给 ITenantResolver 解析器作为结果。

注意：

在使用 Header 作为租户信息提供者的时候，开发人员使用的是 NGINX 作为反向代理服务器 时，需要在对应的 config 文件内部配置 underscores_in_headers on; 选项。否则 ABP 所需要的 __tenantId 将会被过滤掉，或者你可以指定一个没有下划线的 Key。

域名解析器的详细代码解释：

public class DomainTenantResolveContributor : HttpTenantResolveContributorBase
{
    public const string ContributorName = "Domain";

    public override string Name => ContributorName;

    private static readonly string[] ProtocolPrefixes = { "http://", "https://" };

    private readonly string _domainFormat;

    // 使用指定的格式来确定租户前缀，例如 “{0}.abp.io”。
    public DomainTenantResolveContributor(string domainFormat)
    {
        _domainFormat = domainFormat.RemovePreFix(ProtocolPrefixes);
    }

    protected override string GetTenantIdOrNameFromHttpContextOrNull(
        ITenantResolveContext context, 
        HttpContext httpContext)
    {
        // 如果 Host 值为空，则不进行任何操作。
        if (httpContext.Request?.Host == null)
        {
            return null;
        }

        // 解析具体的域名信息，并进行匹配。
        var hostName = httpContext.Request.Host.Host.RemovePreFix(ProtocolPrefixes);
        // 这里的 FormattedStringValueExtracter 类型是 ABP 自己实现的一个格式化解析器。
        var extractResult = FormattedStringValueExtracter.Extract(hostName, _domainFormat, ignoreCase: true);

        context.Handled = true;

        if (!extractResult.IsMatch)
        {
            return null;
        }

        return extractResult.Matches[0].Value;
    }
}

从上述代码可以知道，域名解析器是基于 HttpTenantResolveContributorBase 基类进行处理的，这个抽象基类会取得当前请求的一个 HttpContext，将这个传递与解析上下文一起传递给子类实现，由子类实现负责具体的解析逻辑。

public abstract class HttpTenantResolveContributorBase : TenantResolveContributorBase
{
    public override void Resolve(ITenantResolveContext context)
    {
        // 获取当前请求的上下文。
        var httpContext = context.GetHttpContext();
        if (httpContext == null)
        {
            return;
        }

        try
        {
            ResolveFromHttpContext(context, httpContext);
        }
        catch (Exception e)
        {
            context.ServiceProvider
                .GetRequiredService<ILogger<HttpTenantResolveContributorBase>>()
                .LogWarning(e.ToString());
        }
    }

    protected virtual void ResolveFromHttpContext(ITenantResolveContext context, HttpContext httpContext)
    {
        // 调用抽象方法，获取具体的租户 Id 或名称。
        var tenantIdOrName = GetTenantIdOrNameFromHttpContextOrNull(context, httpContext);
        if (!tenantIdOrName.IsNullOrEmpty())
        {
            // 获得到租户标识之后，填充到解析上下文。
            context.TenantIdOrName = tenantIdOrName;
        }
    }

    protected abstract string GetTenantIdOrNameFromHttpContextOrNull([NotNull] ITenantResolveContext context, [NotNull] HttpContext httpContext);
}

2.3 租户信息的传递

租户解析器通过一系列的解析对象，获取到了租户或租户 Id 之后，会将这些数据给哪些对象呢？或者说，ABP 在什么地方调用了 租户解析器，答案就是 中间件。

在 Volo.ABP.AspNetCore.MultiTenancy 模块的内部，提供了一个 MultiTenancyMiddleware 中间件。

开发人员如果需要使用 ASP.NET Core 的多租户相关功能，也可以引入该模块。并且在模块的 OnApplicationInitialization() 方法当中，使用 IApplicationBuilder.UseMultiTenancy() 进行启用。

这里在启用的时候，需要注意中间件的顺序和位置，不要放到最末尾进行处理。

public class MultiTenancyMiddleware : IMiddleware, ITransientDependency
{
    private readonly ITenantResolver _tenantResolver;
    private readonly ITenantStore _tenantStore;
    private readonly ICurrentTenant _currentTenant;
    private readonly ITenantResolveResultAccessor _tenantResolveResultAccessor;

    public MultiTenancyMiddleware(
        ITenantResolver tenantResolver, 
        ITenantStore tenantStore, 
        ICurrentTenant currentTenant, 
        ITenantResolveResultAccessor tenantResolveResultAccessor)
    {
        _tenantResolver = tenantResolver;
        _tenantStore = tenantStore;
        _currentTenant = currentTenant;
        _tenantResolveResultAccessor = tenantResolveResultAccessor;
    }

    public async Task InvokeAsync(HttpContext context, RequestDelegate next)
    {
        // 通过租户解析器，获取当前请求的租户信息。
        var resolveResult = _tenantResolver.ResolveTenantIdOrName();
        _tenantResolveResultAccessor.Result = resolveResult;

        TenantConfiguration tenant = null;
        // 如果当前请求是属于租户请求。
        if (resolveResult.TenantIdOrName != null)
        {
            // 查询指定的租户 Id 或名称是否存在，不存在则抛出异常。
            tenant = await FindTenantAsync(resolveResult.TenantIdOrName);
            if (tenant == null)
            {
                //TODO: A better exception?
                throw new AbpException(
                    "There is no tenant with given tenant id or name: " + resolveResult.TenantIdOrName
                );
            }
        }

        // 在接下来的请求当中，将会通过 ICurrentTenant.Change() 方法变更当前租户，直到
        // 请求结束。
        using (_currentTenant.Change(tenant?.Id, tenant?.Name))
        {
            await next(context);
        }
    }

    private async Task<TenantConfiguration> FindTenantAsync(string tenantIdOrName)
    {
        // 如果可以格式化为 Guid ，则说明是租户 Id。
        if (Guid.TryParse(tenantIdOrName, out var parsedTenantId))
        {
            return await _tenantStore.FindAsync(parsedTenantId);
        }
        else
        {
            return await _tenantStore.FindAsync(tenantIdOrName);
        }
    }
}

在取得了租户的标识(Id 或名称)之后，将会通过 ICurrentTenant.Change() 方法变更当前租户的信息，变更了当租户信息以后，在程序的其他任何地方使用 ICurrentTenant.Id 取得的数据都是租户解析器解析出来的数据。

下面就是这个当前租户的具体实现，可以看到这里采用了一个 经典手法-嵌套。这个手法在工作单元和数据过滤器有见到过，结合 DisposeAction() 在 using 语句块结束的时候把当前的租户 Id 值设置为父级 Id。即在同一个语句当中，可以通过嵌套 using 语句块来处理不同的租户。

using(_currentTenant.Change("A"))
{
    Logger.LogInformation(_currentTenant.Id);
    using(_currentTenant.Change("B"))
    {
        Logger.LogInformation(_currentTenant.Id);
    }
}

具体的实现代码，这里的 ICurrentTenantAccessor 内部实现就是一个 AsyncLocal<BasicTenantInfo> ，用于在一个异步请求内部进行数据传递。

public class CurrentTenant : ICurrentTenant, ITransientDependency
{
    public virtual bool IsAvailable => Id.HasValue;

    public virtual Guid? Id => _currentTenantAccessor.Current?.TenantId;

    public string Name => _currentTenantAccessor.Current?.Name;

    private readonly ICurrentTenantAccessor _currentTenantAccessor;

    public CurrentTenant(ICurrentTenantAccessor currentTenantAccessor)
    {
        _currentTenantAccessor = currentTenantAccessor;
    }

    public IDisposable Change(Guid? id, string name = null)
    {
        return SetCurrent(id, name);
    }

    private IDisposable SetCurrent(Guid? tenantId, string name = null)
    {
        var parentScope = _currentTenantAccessor.Current;
        _currentTenantAccessor.Current = new BasicTenantInfo(tenantId, name);
        return new DisposeAction(() =>
        {
            _currentTenantAccessor.Current = parentScope;
        });
    }
}

这里的 BasicTenantInfo 与 TenantConfiguraton 不同，前者仅用于在程序当中传递用户的基本信息，而后者是用于定于持久化的标准模型。

2.4 租户的使用

2.4.1 数据库过滤

租户的核心作用就是隔离不同客户的数据，关于过滤的基本逻辑则是存放在 AbpDbContext<TDbContext> 的。从下面的代码可以看到，在使用的时候会从注入一个 ICurrentTenant 接口，这个接口可以获得从租户解析器里面取得的租户 Id 信息。并且还有一个 IsMultiTenantFilterEnabled() 方法来判定当前 是否应用租户过滤器。

public abstract class AbpDbContext<TDbContext> : DbContext, IEfCoreDbContext, ITransientDependency
    where TDbContext : DbContext
{
    protected virtual Guid? CurrentTenantId => CurrentTenant?.Id;

    protected virtual bool IsMultiTenantFilterEnabled => DataFilter?.IsEnabled<IMultiTenant>() ?? false;
        
    // ... 其他的代码。
        
    public ICurrentTenant CurrentTenant { get; set; }

    // ... 其他的代码。

    protected virtual Expression<Func<TEntity, bool>> CreateFilterExpression<TEntity>() where TEntity : class
    {
        // 定义一个 Lambda 表达式。
        Expression<Func<TEntity, bool>> expression = null;

        // 如果聚合根/实体实现了软删除接口，则构建一个软删除过滤器。
        if (typeof(ISoftDelete).IsAssignableFrom(typeof(TEntity)))
        {
            expression = e => !IsSoftDeleteFilterEnabled || !EF.Property<bool>(e, "IsDeleted");
        }

        // 如果聚合根/实体实现了多租户接口，则构建一个多租户过滤器。
        if (typeof(IMultiTenant).IsAssignableFrom(typeof(TEntity)))
        {
            // 筛选 TenantId 为 CurrentTenantId 的数据。
            Expression<Func<TEntity, bool>> multiTenantFilter = e => !IsMultiTenantFilterEnabled || EF.Property<Guid>(e, "TenantId") == CurrentTenantId;
            expression = expression == null ? multiTenantFilter : CombineExpressions(expression, multiTenantFilter);
        }

        return expression;
    }

    // ... 其他的代码。
}

2.4.2 种子数据构建

在 Volo.ABP.TenantManagement 模块当中，如果用户创建了一个租户，ABP 不只是在租户表插入一条新数据而已。它还会设置种子数据的 构造上下文，并且执行所有的 种子数据构建者(IDataSeedContributor)。

[Authorize(TenantManagementPermissions.Tenants.Create)]
public virtual async Task<TenantDto> CreateAsync(TenantCreateDto input)
{
    var tenant = await TenantManager.CreateAsync(input.Name);
    await TenantRepository.InsertAsync(tenant);

    using (CurrentTenant.Change(tenant.Id, tenant.Name))
    {
        //TODO: Handle database creation?

        //TODO: Set admin email & password..?
        await DataSeeder.SeedAsync(tenant.Id);
    }
    
    return ObjectMapper.Map<Tenant, TenantDto>(tenant);
}

这些构建者当中，就包括租户的超级管理员(admin)和角色构建，以及针对超级管理员角色进行权限赋值操作。

这里需要注意第二点，如果开发人员没有指定超级管理员用户和密码，那么还是会使用默认密码为租户生成超级管理员，具体原因看如下代码。

public class IdentityDataSeedContributor : IDataSeedContributor, ITransientDependency
{
    private readonly IIdentityDataSeeder _identityDataSeeder;

    public IdentityDataSeedContributor(IIdentityDataSeeder identityDataSeeder)
    {
        _identityDataSeeder = identityDataSeeder;
    }

    public Task SeedAsync(DataSeedContext context)
    {
        return _identityDataSeeder.SeedAsync(
            context["AdminEmail"] as string ?? "admin@abp.io",
            context["AdminPassword"] as string ?? "1q2w3E*",
            context.TenantId
        );
    }
}

所以开发人员要实现为不同租户 生成随机密码，那么就不能够使用 TenantManagement 提供的创建方法，而是需要自己编写一个应用服务进行处理。

2.4.3 权限的控制

如果开发人员使用了 ABP 提供的 Volo.Abp.PermissionManagement 模块，就会看到在它的种子数据构造者当中会对权限进行判定。因为有一些 超级权限 是租主才能够授予的，例如租户的增加、删除、修改等，这些超级权限在定义的时候就需要说明是否是数据租主独有的。

关于这点，可以参考租户管理模块在权限定义时，传递的 MultiTenancySides.Host 参数。

public class AbpTenantManagementPermissionDefinitionProvider : PermissionDefinitionProvider
{
    public override void Define(IPermissionDefinitionContext context)
    {
        var tenantManagementGroup = context.AddGroup(TenantManagementPermissions.GroupName, L("Permission:TenantManagement"));

        var tenantsPermission = tenantManagementGroup.AddPermission(TenantManagementPermissions.Tenants.Default, L("Permission:TenantManagement"), multiTenancySide: MultiTenancySides.Host);
        tenantsPermission.AddChild(TenantManagementPermissions.Tenants.Create, L("Permission:Create"), multiTenancySide: MultiTenancySides.Host);
        tenantsPermission.AddChild(TenantManagementPermissions.Tenants.Update, L("Permission:Edit"), multiTenancySide: MultiTenancySides.Host);
        tenantsPermission.AddChild(TenantManagementPermissions.Tenants.Delete, L("Permission:Delete"), multiTenancySide: MultiTenancySides.Host);
        tenantsPermission.AddChild(TenantManagementPermissions.Tenants.ManageFeatures, L("Permission:ManageFeatures"), multiTenancySide: MultiTenancySides.Host);
        tenantsPermission.AddChild(TenantManagementPermissions.Tenants.ManageConnectionStrings, L("Permission:ManageConnectionStrings"), multiTenancySide: MultiTenancySides.Host);
    }

    private static LocalizableString L(string name)
    {
        return LocalizableString.Create<AbpTenantManagementResource>(name);
    }
}

下面是权限种子数据构造者的代码：

public class PermissionDataSeedContributor : IDataSeedContributor, ITransientDependency
{
    protected ICurrentTenant CurrentTenant { get; }

    protected IPermissionDefinitionManager PermissionDefinitionManager { get; }
    protected IPermissionDataSeeder PermissionDataSeeder { get; }

    public PermissionDataSeedContributor(
        IPermissionDefinitionManager permissionDefinitionManager,
        IPermissionDataSeeder permissionDataSeeder,
        ICurrentTenant currentTenant)
    {
        PermissionDefinitionManager = permissionDefinitionManager;
        PermissionDataSeeder = permissionDataSeeder;
        CurrentTenant = currentTenant;
    }

    public virtual Task SeedAsync(DataSeedContext context)
    {
        // 通过 GetMultiTenancySide() 方法判断当前执行
        // 种子构造者的租户情况，是租主还是租户。
        var multiTenancySide = CurrentTenant.GetMultiTenancySide();
        // 根据条件筛选权限。
        var permissionNames = PermissionDefinitionManager
            .GetPermissions()
            .Where(p => p.MultiTenancySide.HasFlag(multiTenancySide))
            .Select(p => p.Name)
            .ToArray();

        // 将权限授予具体租户的角色。
        return PermissionDataSeeder.SeedAsync(
            RolePermissionValueProvider.ProviderName,
            "admin",
            permissionNames,
            context.TenantId
        );
    }
}

而 ABP 在判断当前是租主还是租户的方法也很简单，如果当前租户 Id 为 NULL 则说明是租主，如果不为空则说明是具体租户。

public static MultiTenancySides GetMultiTenancySide(this ICurrentTenant currentTenant)
{
    return currentTenant.Id.HasValue
        ? MultiTenancySides.Tenant
        : MultiTenancySides.Host;
}

2.4.4 租户的独立设置

关于这块的内容，可以参考之前的 这篇文章 ，ABP 也为我们提供了各个租户独立的自定义参数在，这块功能是由 TenantSettingManagementProvider 实现的，只需要在设置参数值的时候提供租户的 ProviderName 即可。

例如：

settingManager.SetAsync("WeChatIsOpen", "true", TenantSettingValueProvider.ProviderName, tenantId.ToString(), false);

三、总结

其他相关文章，请参阅 文章目录 。

Docker 安装 ELK

Fri, 17 Jan 2020 07:37:13 +0000

安装

首先安装 Docker 与 Docker-Compose 相关的组件，我们这里直接使用准备好的 ELK 镜像，执行以下命令从 Dockerhub 上拉取指定版本的镜像，在本例当中我使用的是 7.40 版本。

docker pull sebp/elk:740

配置

为其编写 docker-compose.yaml 文件，内容如下：

version: '3.7'
services:
  nginx:
    image: nginx
    container_name: nginx
    ports: 
      - 80:80
      - 443:443
    networks:
      - internal-network
    volumes: 
      - /root/Volumes/Nginx/nginx.conf:/etc/nginx/nginx.conf
      - /root/Volumes/Nginx/Configs:/etc/nginx/conf.d
    restart: always
  elk:
    image: sebp/elk:740
    container_name: elk
    ports:
      - 9200:9200
      - 5044:5044
    expose:
      - 5601
    networks:
      - internal-network
    volumes:
      - /opt/elk-data:/var/lib/elasticsearch
      - /etc/localtime:/etc/localtime
    depends_on: 
      - nginx
    ulimits: 
      nproc: 262144
      nofile:
        soft: 262144
        hard: 262144
      memlock: 9223372036854775807
    restart: always

networks:
  internal-network:
    external: true

上面的 Yaml 文件内容大概意思就是开放 ELK 的 9200 与 5400 端口，然后使用 Nginx 代理 Kibana Dashboard，并且将相关的数据卷挂载了出来。

这里需要注意的是，我配置了 ulimits 节，这是因为 ELK 在启动的时候会检测相关内核参数，除了在 Yaml 编写还不够，还得变更宿主机的相关参数。关于这些参数的内容变更，请参考以下内容：

变更 /etc/security/limits.conf 文件，为其追加以下内容：

* soft nofile 204800
* hard nofile 204800
* soft nproc 204800
* hard nproc 204800

* soft memlock unlimited
* hard memlock unlimited

跳转到 /etc/security/limits.d 目录下，修改相应的 conf 文件，为其追加以下内容：

* soft nproc unlimited
* hard nproc unlimited

最后重启服务器，以上内容都是基于 CentOS 7.x 进行编写。

运行

安装好 docker-compose 工具以后，直接在 Yaml 文件的根目录运行 docker-compose up -d 即可。如果正常的话，访问对应的机器即可。

Abp vNext 源码分析 - 14. EntityFramework Core 的集成

Wed, 08 Jan 2020 03:09:08 +0000

一、简要介绍

在以前的文章里面，我们介绍了 ABP vNext 在 DDD 模块定义了仓储的接口定义和基本实现。本章将会介绍，ABP vNext 是如何将 EntityFramework Core 框架跟仓储进行深度集成。

ABP vNext 在集成 EF Core 的时候，不只是简单地实现了仓储模式，除开仓储以外，还提供了一系列的基础设施，如领域事件的发布，数据过滤器的实现。

二、源码分析

EntityFrameworkCore 相关的模块基本就下面几个，除了第一个是核心 EntityFrameworkCore 模块以外，其他几个都是封装的 EntityFrameworkCore Provider，方便各种数据库进行集成。

2.1 EF Core 模块集成与初始化

首先从 Volo.Abp.EntityFrameworkCore 的 AbpEntityFrameworkCoreModule 开始分析，该模块只重写了 ConfigureServices() 方法，在内部也只有两句代码。

public override void ConfigureServices(ServiceConfigurationContext context)
{
    // 调用 AbpDbContextOptions 的预配置方法，为了解决下面的问题。
    // https://stackoverflow.com/questions/55369146/eager-loading-include-with-using-uselazyloadingproxies
    Configure<AbpDbContextOptions>(options =>
    {
        options.PreConfigure(abpDbContextConfigurationContext =>
        {
            abpDbContextConfigurationContext.DbContextOptions
                .ConfigureWarnings(warnings =>
                {
                    warnings.Ignore(CoreEventId.LazyLoadOnDisposedContextWarning);
                });
        });
    });

    // 注册 IDbContextProvider 组件。
    context.Services.TryAddTransient(typeof(IDbContextProvider<>), typeof(UnitOfWorkDbContextProvider<>));
}

首先看第一句代码，它在内部会调用 AbpDbContextOptions 提供的 PreConfigure() 方法。这个方法逻辑很简单，会将传入的 Action<AbpDbContextConfigurationContext> 委托添加到一个 List<Action<AbpDbContextConfigurationContext>> 集合，并且在 DbContextOptionsFactory 工厂中使用。

第二局代码则比较简单，为 IDbContextProvider<> 类型注入默认实现 UnitOfWorkDbContextProvider<>。

public class AbpDbContextOptions
{
    internal List<Action<AbpDbContextConfigurationContext>> DefaultPreConfigureActions { get; set; }

    // ...

    public void PreConfigure([NotNull] Action<AbpDbContextConfigurationContext> action)
    {
        Check.NotNull(action, nameof(action));

        DefaultPreConfigureActions.Add(action);
    }

    // ...
}

从上面的代码可以看出来，这个 AbpDbContextConfigurationContext 就是一个配置上下文，用于 ABP vNext 框架在初始化的时候进行各种配置。

2.1.1 EF Core Provider 的集成

在翻阅 AbpDbContextOptions 代码的时候，我发现除了预配置方法，它还提供了一个 Configure([NotNull] Action<AbpDbContextConfigurationContext> action) 方法，以及它的泛型重载 Configure<TDbContext>([NotNull] Action<AbpDbContextConfigurationContext<TDbContext>> action)，它们的内部实现与预配置类似。

这两个方法在 ABP vNext 框架内部的应用，主要在各个 EF Provider 模块当中有体现。

这里我以 Volo.Abp.EntityFrameworkCore.PostgreSql 模块作为例子，在项目内部只有两个扩展方法的定义类。在 AbpDbContextOptionsPostgreSqlExtensions 当中，就使用到了 Configure() 方法。

public static void UsePostgreSql(
    [NotNull] this AbpDbContextOptions options,
    [CanBeNull] Action<NpgsqlDbContextOptionsBuilder> postgreSqlOptionsAction = null)
{
    options.Configure(context =>
    {
        // 这里的 context 类型是 AbpDbContextConfigurationContext。
        context.UsePostgreSql(postgreSqlOptionsAction);
    });
}

上面代码中的 UsePostgreSql() 方法很明显不是 EF Core Provider 所定义的扩展方法，跳转到具体实现，发现就是一层简单的封装。由于 AbpDbContextConfigurationContext 内部提供了 DbContextOptionsBuilder ，所以直接使用这个 DbContextOptionsBuilder 调用提供的扩展方法即可。

public static class AbpDbContextConfigurationContextPostgreSqlExtensions
{
    public static DbContextOptionsBuilder UsePostgreSql(
        [NotNull] this AbpDbContextConfigurationContext context,
        [CanBeNull] Action<NpgsqlDbContextOptionsBuilder> postgreSqlOptionsAction = null)
    {
        if (context.ExistingConnection != null)
        {
            return context.DbContextOptions.UseNpgsql(context.ExistingConnection, postgreSqlOptionsAction);
        }
        else
        {
            return context.DbContextOptions.UseNpgsql(context.ConnectionString, postgreSqlOptionsAction);
        }
    }
}

2.1.2 数据库上下文的配置工厂

无论是 PreConfigure() 的委托集合，还是 Configure() 配置的委托，都会在 DbContextOptionsFactory 提供的 Create<TDbContext>(IServiceProvider serviceProvider) 方法中被使用。该方法的作用只有一个，执行框架的配置方法，然后生成数据库上下文的配置对象。

internal static class DbContextOptionsFactory
{
    public static DbContextOptions<TDbContext> Create<TDbContext>(IServiceProvider serviceProvider)
        where TDbContext : AbpDbContext<TDbContext>
    {
        // 获取一个 DbContextCreationContext 对象。
        var creationContext = GetCreationContext<TDbContext>(serviceProvider);

        // 依据 creationContext 信息构造一个配置上下文。
        var context = new AbpDbContextConfigurationContext<TDbContext>(
            creationContext.ConnectionString,
            serviceProvider,
            creationContext.ConnectionStringName,
            creationContext.ExistingConnection
        );

        // 获取 AbpDbOptions 配置。
        var options = GetDbContextOptions<TDbContext>(serviceProvider);

        // 从 Options 当中获取添加的 PreConfigure 与 Configure 委托，并执行。
        PreConfigure(options, context);
        Configure(options, context);

        // 
        return context.DbContextOptions.Options;
    }

    // ...
}

首先我们来看看 GetCreationContext<TDbContext>() 方法是如何构造一个 DbContextCreationContext 对象的，它会优先从 Current 取得一个上下文对象，如果存在则直接返回，不存在则使用连接字符串等信息构建一个新的上下文对象。

private static DbContextCreationContext GetCreationContext<TDbContext>(IServiceProvider serviceProvider)
    where TDbContext : AbpDbContext<TDbContext>
{
    // 优先从一个 AsyncLocal 当中获取。
    var context = DbContextCreationContext.Current;
    if (context != null)
    {
        return context;
    }

    // 从 TDbContext 的 ConnectionStringName 特性获取连接字符串名称。
    var connectionStringName = ConnectionStringNameAttribute.GetConnStringName<TDbContext>();
    // 使用 IConnectionStringResolver 根据指定的名称获得连接字符串。
    var connectionString = serviceProvider.GetRequiredService<IConnectionStringResolver>().Resolve(connectionStringName);

    // 构造一个新的 DbContextCreationContext 对象。
    return new DbContextCreationContext(
        connectionStringName,
        connectionString
    );
}

2.1.3 连接字符串解析器

与老版本的 ABP 一样，ABP vNext 将连接字符串解析的工作，抽象了一个解析器。连接字符串解析器默认有两种实现，适用于普通系统和多租户系统。

普通的解析器，名字叫做 DefaultConnectionStringResolver，它的连接字符串都是从 AbpDbConnectionOptions 当中获取的，而这个 Option 最终是从 IConfiguration 映射过来的，一般来说就是你 appsetting.json 文件当中的连接字符串配置。

多租户解析器 的实现叫做 MultiTenantConnectionStringResolver，它的内部核心逻辑就是获得到当前的租户，并查询租户所对应的连接字符串，这样就可以实现每个租户都拥有不同的数据库实例。

2.1.4 数据库上下文配置工厂的使用

回到最开始的地方，方法 Create<TDbContext>(IServiceProvider serviceProvider) 在什么地方会被使用呢？跳转到唯一的调用点是在 AbpEfCoreServiceCollectionExtensions 静态类的内部，它提供的 AddAbpDbContext<TDbContext>() 方法内部，就使用了 Create<TDbContext>() 作为 DbContextOptions<TDbContext> 的工厂方法。

public static class AbpEfCoreServiceCollectionExtensions
{
    public static IServiceCollection AddAbpDbContext<TDbContext>(
        this IServiceCollection services, 
        Action<IAbpDbContextRegistrationOptionsBuilder> optionsBuilder = null)
        where TDbContext : AbpDbContext<TDbContext>
    {
        services.AddMemoryCache();

        // 构造一个数据库注册配置对象。
        var options = new AbpDbContextRegistrationOptions(typeof(TDbContext), services);
        // 回调传入的委托。
        optionsBuilder?.Invoke(options);

        // 注入指定 TDbContext 的 DbOptions<TDbContext> ，将会使用 Create<TDbContext> 方法进行瞬时对象构造。
        services.TryAddTransient(DbContextOptionsFactory.Create<TDbContext>);

        // 替换指定类型的 DbContext 为当前 TDbContext。
        foreach (var dbContextType in options.ReplacedDbContextTypes)
        {
            services.Replace(ServiceDescriptor.Transient(dbContextType, typeof(TDbContext)));
        }

        // 构造 EF Core 仓储注册器，并添加仓储。
        new EfCoreRepositoryRegistrar(options).AddRepositories();

        return services;
    }
}

2.2 仓储的注入与实现

关于仓储的注入，其实在之前的文章就有讲过，这里我就大概说一下情况。

在上述代码当中，调用了 AddAbpDbContext<TDbContext>() 方法之后，就会通过 Repository Registrar 进行仓储注入。

public virtual void AddRepositories()
{
    // 遍历用户添加的自定义仓储。
    foreach (var customRepository in Options.CustomRepositories)
    {
        // 调用 AddDefaultRepository() 方法注入仓储。
        Options.Services.AddDefaultRepository(customRepository.Key, customRepository.Value);
    }

    // 判断是否需要注册实体的默认仓储。
    if (Options.RegisterDefaultRepositories)
    {
        RegisterDefaultRepositories();
    }
}

可以看到，在注入仓储的时候，分为两种情况。第一种是用户的自定义仓储，这种仓储是通过 AddRepository() 方法添加的，添加之后将会把它的 实体类型 与 仓储类型 放在一个字典内部。在仓储注册器进行初始化的时候，就会遍历这个字典，进行注入动作。

第二种情况则是用户在设置了 RegisterDefaultRepositories=true 的情况下，ABP vNext 就会从数据库上下文的类型定义上遍历所有实体类型，然后进行默认仓储注册。

具体的仓储注册实现：

public static IServiceCollection AddDefaultRepository(this IServiceCollection services, Type entityType, Type repositoryImplementationType)
{
    // 注册 IReadOnlyBasicRepository<TEntity>。
    var readOnlyBasicRepositoryInterface = typeof(IReadOnlyBasicRepository<>).MakeGenericType(entityType);
    // 如果具体实现类型继承了该接口，则进行注入。
    if (readOnlyBasicRepositoryInterface.IsAssignableFrom(repositoryImplementationType))
    {
        services.TryAddTransient(readOnlyBasicRepositoryInterface, repositoryImplementationType);

        // 注册 IReadOnlyRepository<TEntity>。
        var readOnlyRepositoryInterface = typeof(IReadOnlyRepository<>).MakeGenericType(entityType);
        if (readOnlyRepositoryInterface.IsAssignableFrom(repositoryImplementationType))
        {
            services.TryAddTransient(readOnlyRepositoryInterface, repositoryImplementationType);
        }

        // 注册 IBasicRepository<TEntity>。
        var basicRepositoryInterface = typeof(IBasicRepository<>).MakeGenericType(entityType);
        if (basicRepositoryInterface.IsAssignableFrom(repositoryImplementationType))
        {
            services.TryAddTransient(basicRepositoryInterface, repositoryImplementationType);

            // 注册 IRepository<TEntity>。
            var repositoryInterface = typeof(IRepository<>).MakeGenericType(entityType);
            if (repositoryInterface.IsAssignableFrom(repositoryImplementationType))
            {
                services.TryAddTransient(repositoryInterface, repositoryImplementationType);
            }
        }
    }

    // 获得实体的主键类型，如果不存在则忽略。
    var primaryKeyType = EntityHelper.FindPrimaryKeyType(entityType);
    if (primaryKeyType != null)
    {
        // 注册 IReadOnlyBasicRepository<TEntity, TKey>。
        var readOnlyBasicRepositoryInterfaceWithPk = typeof(IReadOnlyBasicRepository<,>).MakeGenericType(entityType, primaryKeyType);
        if (readOnlyBasicRepositoryInterfaceWithPk.IsAssignableFrom(repositoryImplementationType))
        {
            services.TryAddTransient(readOnlyBasicRepositoryInterfaceWithPk, repositoryImplementationType);

            // 注册 IReadOnlyRepository<TEntity, TKey>。
            var readOnlyRepositoryInterfaceWithPk = typeof(IReadOnlyRepository<,>).MakeGenericType(entityType, primaryKeyType);
            if (readOnlyRepositoryInterfaceWithPk.IsAssignableFrom(repositoryImplementationType))
            {
                services.TryAddTransient(readOnlyRepositoryInterfaceWithPk, repositoryImplementationType);
            }

            // 注册 IBasicRepository<TEntity, TKey>。
            var basicRepositoryInterfaceWithPk = typeof(IBasicRepository<,>).MakeGenericType(entityType, primaryKeyType);
            if (basicRepositoryInterfaceWithPk.IsAssignableFrom(repositoryImplementationType))
            {
                services.TryAddTransient(basicRepositoryInterfaceWithPk, repositoryImplementationType);

                // 注册 IRepository<TEntity, TKey>。
                var repositoryInterfaceWithPk = typeof(IRepository<,>).MakeGenericType(entityType, primaryKeyType);
                if (repositoryInterfaceWithPk.IsAssignableFrom(repositoryImplementationType))
                {
                    services.TryAddTransient(repositoryInterfaceWithPk, repositoryImplementationType);
                }
            }
        }
    }

    return services;
}

回到仓储自动注册的地方，可以看到实现类型是由 GetDefaultRepositoryImplementationType() 方法提供的。

protected virtual void RegisterDefaultRepository(Type entityType)
{
    Options.Services.AddDefaultRepository(
        entityType,
        GetDefaultRepositoryImplementationType(entityType)
    );
}

protected virtual Type GetDefaultRepositoryImplementationType(Type entityType)
{
    var primaryKeyType = EntityHelper.FindPrimaryKeyType(entityType);

    if (primaryKeyType == null)
    {
        return Options.SpecifiedDefaultRepositoryTypes
            ? Options.DefaultRepositoryImplementationTypeWithoutKey.MakeGenericType(entityType)
            : GetRepositoryType(Options.DefaultRepositoryDbContextType, entityType);
    }

    return Options.SpecifiedDefaultRepositoryTypes
        ? Options.DefaultRepositoryImplementationType.MakeGenericType(entityType, primaryKeyType)
        : GetRepositoryType(Options.DefaultRepositoryDbContextType, entityType, primaryKeyType);
}

protected abstract Type GetRepositoryType(Type dbContextType, Type entityType);

protected abstract Type GetRepositoryType(Type dbContextType, Type entityType, Type primaryKeyType);

这里的两个 GetRepositoryType() 都是抽象方法，具体的实现分别在 EfCoreRepositoryRegistrar、MemoryDbRepositoryRegistrar、MongoDbRepositoryRegistrar 的内部，这里我们只讲 EF Core 相关的。

protected override Type GetRepositoryType(Type dbContextType, Type entityType)
{
    return typeof(EfCoreRepository<,>).MakeGenericType(dbContextType, entityType);
}

可以看到，在方法内部是构造了一个 EfCoreRepository 类型作为默认仓储的实现。

2.3 数据库上下文提供者

在 Ef Core 仓储的内部，需要操作数据库时，必须要获得一个数据库上下文。在仓储内部的数据库上下文都是由 IDbContextProvider<TDbContext> 提供了，这个东西在 EF Core 模块初始化的时候就已经被注册，它的默认实现是 UnitOfWorkDbContextProvider<TDbContext>。

public class EfCoreRepository<TDbContext, TEntity> : RepositoryBase<TEntity>, IEfCoreRepository<TEntity>
    where TDbContext : IEfCoreDbContext
    where TEntity : class, IEntity
{
    public virtual DbSet<TEntity> DbSet => DbContext.Set<TEntity>();

    DbContext IEfCoreRepository<TEntity>.DbContext => DbContext.As<DbContext>();

    protected virtual TDbContext DbContext => _dbContextProvider.GetDbContext();

    // ...
    
    private readonly IDbContextProvider<TDbContext> _dbContextProvider;

    // ...

    public EfCoreRepository(IDbContextProvider<TDbContext> dbContextProvider)
    {
        _dbContextProvider = dbContextProvider;
        
        // ...
    }

    // ...
}

首先来看一下这个实现类的基本定义，比较简单，注入了两个接口，分别用于获取工作单元和构造 DbContext。需要注意的是，这里通过 where 约束来指定 TDbContext 必须实现 IEfCoreDbContext 接口。

public class UnitOfWorkDbContextProvider<TDbContext> : IDbContextProvider<TDbContext>
    where TDbContext : IEfCoreDbContext
{
    private readonly IUnitOfWorkManager _unitOfWorkManager;
    private readonly IConnectionStringResolver _connectionStringResolver;

    public UnitOfWorkDbContextProvider(
        IUnitOfWorkManager unitOfWorkManager,
        IConnectionStringResolver connectionStringResolver)
    {
        _unitOfWorkManager = unitOfWorkManager;
        _connectionStringResolver = connectionStringResolver;
    }

    // ...
}

接着想下看，接口只定义了一个方法，就是 GetDbContext()，在这个默认实现里面，首先会从缓存里面获取数据库上下文，如果没有获取到，则创建一个新的数据库上下文。

public TDbContext GetDbContext()
{
    // 获得当前的可用工作单元。
    var unitOfWork = _unitOfWorkManager.Current;
    if (unitOfWork == null)
    {
        throw new AbpException("A DbContext can only be created inside a unit of work!");
    }

    // 获得数据库连接上下文的连接字符串名称。
    var connectionStringName = ConnectionStringNameAttribute.GetConnStringName<TDbContext>();
    // 根据名称解析具体的连接字符串。
    var connectionString = _connectionStringResolver.Resolve(connectionStringName);

    // 构造数据库上下文缓存 Key。
    var dbContextKey = $"{typeof(TDbContext).FullName}_{connectionString}";

    // 从工作单元的缓存当中获取数据库上下文，不存在则调用 CreateDbContext() 创建。
    var databaseApi = unitOfWork.GetOrAddDatabaseApi(
        dbContextKey,
        () => new EfCoreDatabaseApi<TDbContext>(
            CreateDbContext(unitOfWork, connectionStringName, connectionString)
        ));

    return ((EfCoreDatabaseApi<TDbContext>)databaseApi).DbContext;
}

回到最开始的数据库上下文配置工厂，在它的内部会优先从一个 Current 获取一个 DbContextCreationContext 实例。而在这里，就是 Current 被赋值的地方，只要调用了 Use() 方法，在释放之前都会获取到同一个实例。

private TDbContext CreateDbContext(IUnitOfWork unitOfWork, string connectionStringName, string connectionString)
{
    var creationContext = new DbContextCreationContext(connectionStringName, connectionString);
    using (DbContextCreationContext.Use(creationContext))
    {
        // 这里是重点，真正创建数据库上下文的地方。
        var dbContext = CreateDbContext(unitOfWork);

        if (unitOfWork.Options.Timeout.HasValue &&
            dbContext.Database.IsRelational() &&
            !dbContext.Database.GetCommandTimeout().HasValue)
        {
            dbContext.Database.SetCommandTimeout(unitOfWork.Options.Timeout.Value.TotalSeconds.To<int>());
        }

        return dbContext;
    }
}

// 如果是事务型的工作单元，则调用 CreateDbContextWithTransaction() 进行创建，但不论如何都是通过工作单元提供的 IServiceProvider 解析出来 DbContext 的。
private TDbContext CreateDbContext(IUnitOfWork unitOfWork)
{
    return unitOfWork.Options.IsTransactional
        ? CreateDbContextWithTransaction(unitOfWork)
        : unitOfWork.ServiceProvider.GetRequiredService<TDbContext>();
}

以下代码才是在真正地创建 DbContext 实例。

public TDbContext CreateDbContextWithTransaction(IUnitOfWork unitOfWork) 
{
    var transactionApiKey = $"EntityFrameworkCore_{DbContextCreationContext.Current.ConnectionString}";
    var activeTransaction = unitOfWork.FindTransactionApi(transactionApiKey) as EfCoreTransactionApi;

    // 没有取得缓存。
    if (activeTransaction == null)
    {
        var dbContext = unitOfWork.ServiceProvider.GetRequiredService<TDbContext>();

        // 判断是否指定了事务隔离级别，并开始事务。
        var dbtransaction = unitOfWork.Options.IsolationLevel.HasValue
            ? dbContext.Database.BeginTransaction(unitOfWork.Options.IsolationLevel.Value)
            : dbContext.Database.BeginTransaction();

        // 跟工作单元绑定添加一个已经激活的事务。
        unitOfWork.AddTransactionApi(
            transactionApiKey,
            new EfCoreTransactionApi(
                dbtransaction,
                dbContext
            )
        );

        // 返回构造好的数据库上下文。
        return dbContext;
    }
    else
    {
        DbContextCreationContext.Current.ExistingConnection = activeTransaction.DbContextTransaction.GetDbTransaction().Connection;

        var dbContext = unitOfWork.ServiceProvider.GetRequiredService<TDbContext>();

        if (dbContext.As<DbContext>().HasRelationalTransactionManager())
        {
            dbContext.Database.UseTransaction(activeTransaction.DbContextTransaction.GetDbTransaction());
        }
        else
        {
            dbContext.Database.BeginTransaction(); //TODO: Why not using the new created transaction?
        }

        activeTransaction.AttendedDbContexts.Add(dbContext);

        return dbContext;
    }
}

2.4 数据过滤器

ABP vNext 还提供了数据过滤器机制，可以让你根据指定的标识过滤数据，例如租户 Id 和软删除标记。它的基本接口定义在 Volo.Abp.Data 项目的 IDataFilter.cs 文件中，提供了启用、禁用、检测方法。

public interface IDataFilter<TFilter>
    where TFilter : class
{
    IDisposable Enable();

    IDisposable Disable();

    bool IsEnabled { get; }
}

public interface IDataFilter
{
    IDisposable Enable<TFilter>()
        where TFilter : class;
    
    IDisposable Disable<TFilter>()
        where TFilter : class;

    bool IsEnabled<TFilter>()
        where TFilter : class;
}

默认实现也在该项目下面的 DataFilter.cs 文件，首先看以下 IDataFilter 的默认实现 DataFilter，内部有一个解析器和并发字典。这个并发字典存储了所有的过滤器，其键是真实过滤器的类型(ISoftDelete 或 IMultiTenant)，值是 DataFilter<TFilter>，具体对象根据 TFilter 的不同而不同。

public class DataFilter : IDataFilter, ISingletonDependency
{
    private readonly ConcurrentDictionary<Type, object> _filters;

    private readonly IServiceProvider _serviceProvider;

    public DataFilter(IServiceProvider serviceProvider)
    {
        _serviceProvider = serviceProvider;
        _filters = new ConcurrentDictionary<Type, object>();
    }

    // ...
}

看一下其他的方法，都是对 IDataFilter<Filter> 的包装。

public class DataFilter : IDataFilter, ISingletonDependency
{
    // ...

    public IDisposable Enable<TFilter>()
        where TFilter : class
    {
        return GetFilter<TFilter>().Enable();
    }

    public IDisposable Disable<TFilter>()
        where TFilter : class
    {
        return GetFilter<TFilter>().Disable();
    }

    public bool IsEnabled<TFilter>()
        where TFilter : class
    {
        return GetFilter<TFilter>().IsEnabled;
    }

    private IDataFilter<TFilter> GetFilter<TFilter>()
        where TFilter : class
    {
        // 并发字典当中获取指定类型的过滤器，如果不存在则从 IoC 中解析。
        return _filters.GetOrAdd(
            typeof(TFilter),
            () => _serviceProvider.GetRequiredService<IDataFilter<TFilter>>()
        ) as IDataFilter<TFilter>;
    }
}

这么看来，IDataFilter 叫做 IDataFilterManager 更加合适一点，最开始我还没搞明白两个接口和实现的区别，真正搞事情的是 DataFilter<Filter>。

public class DataFilter<TFilter> : IDataFilter<TFilter>
    where TFilter : class
{
    public bool IsEnabled
    {
        get
        {
            EnsureInitialized();
            return _filter.Value.IsEnabled;
        }
    }

    // 注入数据过滤器配置类。
    private readonly AbpDataFilterOptions _options;

    // 用于存储过滤器的启用状态。
    private readonly AsyncLocal<DataFilterState> _filter;

    public DataFilter(IOptions<AbpDataFilterOptions> options)
    {
        _options = options.Value;
        _filter = new AsyncLocal<DataFilterState>();
    }

    // ...

    // 确保初始化成功。
    private void EnsureInitialized()
    {
        if (_filter.Value != null)
        {
            return;
        }

        // 如果过滤器的默认状态为 NULL，优先从配置类中取得指定过滤器的默认启用状态，如果不存在则默认为启用。
        _filter.Value = _options.DefaultStates.GetOrDefault(typeof(TFilter))?.Clone() ?? new DataFilterState(true);
    }
}

数据过滤器在设计的时候，也是按照工作单元的形式进行设计的。不论是启用还是停用都是范围性的，会返回一个用 DisposeAction 包装的可释放对象，这样在离开 using 语句块的时候，就会还原为来的状态。比如调用 Enable() 方法，在离开 using 语句块之后，会调用 Disable() 禁用掉数据过滤器。

public IDisposable Enable()
{
    if (IsEnabled)
    {
        return NullDisposable.Instance;
    }

    _filter.Value.IsEnabled = true;

    return new DisposeAction(() => Disable());
}

public IDisposable Disable()
{
    if (!IsEnabled)
    {
        return NullDisposable.Instance;
    }

    _filter.Value.IsEnabled = false;

    return new DisposeAction(() => Enable());
}

2.4.1 MongoDb 与 Memory 的集成

可以看到有两处使用，分别是 Volo.Abp.Domain 项目与 Volo.Abp.EntityFrameworkCore 项目。

首先看第一个项目的用法：

public abstract class RepositoryBase<TEntity> : BasicRepositoryBase<TEntity>, IRepository<TEntity>
    where TEntity : class, IEntity
{
    public IDataFilter DataFilter { get; set; }

    // ...

    // 分别在查询的时候判断实体是否实现了两个接口。
    protected virtual TQueryable ApplyDataFilters<TQueryable>(TQueryable query)
        where TQueryable : IQueryable<TEntity>
    {
        // 如果实现了软删除接口，则从 DataFilter 中获取过滤器的开启状态。
        // 如果已经开启，则过滤掉被删除的数据。
        if (typeof(ISoftDelete).IsAssignableFrom(typeof(TEntity)))
        {
            query = (TQueryable)query.WhereIf(DataFilter.IsEnabled<ISoftDelete>(), e => ((ISoftDelete)e).IsDeleted == false);
        }

        // 如果实现了多租户接口，则从 DataFilter 中获取过滤器的开启状态。
        // 如果已经开启，则按照租户 Id 过滤数据。
        if (typeof(IMultiTenant).IsAssignableFrom(typeof(TEntity)))
        {
            var tenantId = CurrentTenant.Id;
            query = (TQueryable)query.WhereIf(DataFilter.IsEnabled<IMultiTenant>(), e => ((IMultiTenant)e).TenantId == tenantId);
        }

        return query;
    }

    // ...
}

逻辑比较简单，都是判断实体是否实现某个接口，并且结合启用状态来进行过滤，在原有 IQuerable 拼接 WhereIf() 即可。但是 EF Core 使用这种方式不行，所以上述方法只会在 Memory 和 MongoDb 有使用。

2.4.2 EF Core 的集成

EF Core 集成数据过滤器则是放在数据库上下文基类 AbpDbContext<TDbContext> 中，在数据库上下文的 OnModelCreating() 方法内通过 ConfigureBasePropertiesMethodInfo 进行反射调用。

public abstract class AbpDbContext<TDbContext> : DbContext, IEfCoreDbContext, ITransientDependency
    where TDbContext : DbContext
{
    // ...
    protected virtual bool IsMultiTenantFilterEnabled => DataFilter?.IsEnabled<IMultiTenant>() ?? false;

    protected virtual bool IsSoftDeleteFilterEnabled => DataFilter?.IsEnabled<ISoftDelete>() ?? false;

    // ...

    public IDataFilter DataFilter { get; set; }

    // ...

    private static readonly MethodInfo ConfigureBasePropertiesMethodInfo = typeof(AbpDbContext<TDbContext>)
        .GetMethod(
            nameof(ConfigureBaseProperties),
            BindingFlags.Instance | BindingFlags.NonPublic
        );

    // ...

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        base.OnModelCreating(modelBuilder);

        foreach (var entityType in modelBuilder.Model.GetEntityTypes())
        {
            ConfigureBasePropertiesMethodInfo
                .MakeGenericMethod(entityType.ClrType)
                .Invoke(this, new object[] { modelBuilder, entityType });

            // ...
        }
    }

    // ...

    protected virtual void ConfigureBaseProperties<TEntity>(ModelBuilder modelBuilder, IMutableEntityType mutableEntityType)
        where TEntity : class
    {
        if (mutableEntityType.IsOwned())
        {
            return;
        }

        ConfigureConcurrencyStampProperty<TEntity>(modelBuilder, mutableEntityType);
        ConfigureExtraProperties<TEntity>(modelBuilder, mutableEntityType);
        ConfigureAuditProperties<TEntity>(modelBuilder, mutableEntityType);
        ConfigureTenantIdProperty<TEntity>(modelBuilder, mutableEntityType);
        // 在这里，配置全局过滤器。
        ConfigureGlobalFilters<TEntity>(modelBuilder, mutableEntityType);
    }

    // ...

    protected virtual void ConfigureGlobalFilters<TEntity>(ModelBuilder modelBuilder, IMutableEntityType mutableEntityType)
        where TEntity : class
    {
        // 符合条件则为其创建过滤表达式。
        if (mutableEntityType.BaseType == null && ShouldFilterEntity<TEntity>(mutableEntityType))
        {
            // 创建过滤表达式。
            var filterExpression = CreateFilterExpression<TEntity>();
            if (filterExpression != null)
            {
                // 为指定的实体配置查询过滤器。
                modelBuilder.Entity<TEntity>().HasQueryFilter(filterExpression);
            }
        }
    }

    // ...

    // 判断实体是否拥有过滤器。
    protected virtual bool ShouldFilterEntity<TEntity>(IMutableEntityType entityType) where TEntity : class
    {
        if (typeof(IMultiTenant).IsAssignableFrom(typeof(TEntity)))
        {
            return true;
        }

        if (typeof(ISoftDelete).IsAssignableFrom(typeof(TEntity)))
        {
            return true;
        }

        return false;
    }

    // 构建表达式。
    protected virtual Expression<Func<TEntity, bool>> CreateFilterExpression<TEntity>()
        where TEntity : class
    {
        Expression<Func<TEntity, bool>> expression = null;

        if (typeof(ISoftDelete).IsAssignableFrom(typeof(TEntity)))
        {
            expression = e => !IsSoftDeleteFilterEnabled || !EF.Property<bool>(e, "IsDeleted");
        }

        if (typeof(IMultiTenant).IsAssignableFrom(typeof(TEntity)))
        {
            Expression<Func<TEntity, bool>> multiTenantFilter = e => !IsMultiTenantFilterEnabled || EF.Property<Guid>(e, "TenantId") == CurrentTenantId;
            expression = expression == null ? multiTenantFilter : CombineExpressions(expression, multiTenantFilter);
        }

        return expression;
    }
        
    // ...
}

2.5 领域事件集成

在讲解事件总线与 DDD 这块的时候，我有提到过 ABP vNext 有实现领域事件功能，用户可以在聚合根内部使用 AddLocalEvent(object eventData) 或 AddDistributedEvent(object eventData) 添加了领域事件。

public abstract class AggregateRoot : Entity, 
    IAggregateRoot,
    IGeneratesDomainEvents, 
    IHasExtraProperties,
    IHasConcurrencyStamp
{
    // ...

    private readonly ICollection<object> _localEvents = new Collection<object>();
    private readonly ICollection<object> _distributedEvents = new Collection<object>();

    // ...

    // 添加本地事件。
    protected virtual void AddLocalEvent(object eventData)
    {
        _localEvents.Add(eventData);
    }

    // 添加分布式事件。
    protected virtual void AddDistributedEvent(object eventData)
    {
        _distributedEvents.Add(eventData);
    }

    // 获得所有本地事件。
    public virtual IEnumerable<object> GetLocalEvents()
    {
        return _localEvents;
    }

    // 获得所有分布式事件。
    public virtual IEnumerable<object> GetDistributedEvents()
    {
        return _distributedEvents;
    }

    // 清空聚合需要触发的所有本地事件。
    public virtual void ClearLocalEvents()
    {
        _localEvents.Clear();
    }

    // 清空聚合需要触发的所有分布式事件。
    public virtual void ClearDistributedEvents()
    {
        _distributedEvents.Clear();
    }
}

可以看到，我们在聚合内部执行任何业务行为的时候，可以通过上述的方法发送领域事件。那这些事件是在什么时候被发布的呢？

发现这几个 Get 方法有被 AbpDbContext 所调用，其实在它的内部，会在每次 SaveChangesAsync() 的时候，遍历所有实体，并获取它们的本地事件与分布式事件集合，最后由 EntityChangeEventHelper 进行触发。

public abstract class AbpDbContext<TDbContext> : DbContext, IEfCoreDbContext, ITransientDependency
    where TDbContext : DbContext
{
    // ...
    public override async Task<int> SaveChangesAsync(bool acceptAllChangesOnSuccess, CancellationToken cancellationToken = default)
    {
        try
        {
            var auditLog = AuditingManager?.Current?.Log;

            List<EntityChangeInfo> entityChangeList = null;
            if (auditLog != null)
            {
                entityChangeList = EntityHistoryHelper.CreateChangeList(ChangeTracker.Entries().ToList());
            }

            var changeReport = ApplyAbpConcepts();

            var result = await base.SaveChangesAsync(acceptAllChangesOnSuccess, cancellationToken).ConfigureAwait(false);

            // 触发领域事件。
            await EntityChangeEventHelper.TriggerEventsAsync(changeReport).ConfigureAwait(false);

            if (auditLog != null)
            {
                EntityHistoryHelper.UpdateChangeList(entityChangeList);
                auditLog.EntityChanges.AddRange(entityChangeList);
                Logger.LogDebug($"Added {entityChangeList.Count} entity changes to the current audit log");
            }

            return result;
        }
        catch (DbUpdateConcurrencyException ex)
        {
            throw new AbpDbConcurrencyException(ex.Message, ex);
        }
        finally
        {
            ChangeTracker.AutoDetectChangesEnabled = true;
        }
    }

    // ...

    protected virtual EntityChangeReport ApplyAbpConcepts()
    {
        var changeReport = new EntityChangeReport();

        // 遍历所有的实体变更事件。
        foreach (var entry in ChangeTracker.Entries().ToList())
        {
            ApplyAbpConcepts(entry, changeReport);
        }

        return changeReport;
    }

    protected virtual void ApplyAbpConcepts(EntityEntry entry, EntityChangeReport changeReport)
    {
        // 根据不同的实体操作状态，执行不同的操作。
        switch (entry.State)
        {
            case EntityState.Added:
                ApplyAbpConceptsForAddedEntity(entry, changeReport);
                break;
            case EntityState.Modified:
                ApplyAbpConceptsForModifiedEntity(entry, changeReport);
                break;
            case EntityState.Deleted:
                ApplyAbpConceptsForDeletedEntity(entry, changeReport);
                break;
        }

        // 添加领域事件。
        AddDomainEvents(changeReport, entry.Entity);
    }

    // ...

    protected virtual void AddDomainEvents(EntityChangeReport changeReport, object entityAsObj)
    {
        var generatesDomainEventsEntity = entityAsObj as IGeneratesDomainEvents;
        if (generatesDomainEventsEntity == null)
        {
            return;
        }

        // 获取到所有的本地事件和分布式事件，将其加入到 EntityChangeReport 对象当中。
        var localEvents = generatesDomainEventsEntity.GetLocalEvents()?.ToArray();
        if (localEvents != null && localEvents.Any())
        {
            changeReport.DomainEvents.AddRange(localEvents.Select(eventData => new DomainEventEntry(entityAsObj, eventData)));
            generatesDomainEventsEntity.ClearLocalEvents();
        }

        var distributedEvents = generatesDomainEventsEntity.GetDistributedEvents()?.ToArray();
        if (distributedEvents != null && distributedEvents.Any())
        {
            changeReport.DistributedEvents.AddRange(distributedEvents.Select(eventData => new DomainEventEntry(entityAsObj, eventData)));
            generatesDomainEventsEntity.ClearDistributedEvents();
        }
    }
}

转到 `` 的内部，发现有如下代码：

// ...
public async Task TriggerEventsAsync(EntityChangeReport changeReport)
{
    // 触发领域事件。
    await TriggerEventsInternalAsync(changeReport).ConfigureAwait(false);

    if (changeReport.IsEmpty() || UnitOfWorkManager.Current == null)
    {
        return;
    }

    await UnitOfWorkManager.Current.SaveChangesAsync().ConfigureAwait(false);
}

protected virtual async Task TriggerEventsInternalAsync(EntityChangeReport changeReport)
{
    // 触发默认的实体变更事件，例如某个实体被创建、修改、删除。
    await TriggerEntityChangeEvents(changeReport.ChangedEntities).ConfigureAwait(false);

    // 触发用户自己发送的领域事件。
    await TriggerLocalEvents(changeReport.DomainEvents).ConfigureAwait(false);
    await TriggerDistributedEvents(changeReport.DistributedEvents).ConfigureAwait(false);
}

// ...

protected virtual async Task TriggerLocalEvents(List<DomainEventEntry> localEvents)
{
    foreach (var localEvent in localEvents)
    {
        await LocalEventBus.PublishAsync(localEvent.EventData.GetType(), localEvent.EventData).ConfigureAwait(false);
    }
}

protected virtual async Task TriggerDistributedEvents(List<DomainEventEntry> distributedEvents)
{
    foreach (var distributedEvent in distributedEvents)
    {
        await DistributedEventBus.PublishAsync(distributedEvent.EventData.GetType(), distributedEvent.EventData).ConfigureAwait(false);
    }
}

三、系列文章目录

点击我 跳转到文章总目录。

使用 HttpClient 进行表单提交时，遇到的问题

Sun, 29 Dec 2019 03:37:33 +0000

问题

在开发微信支付的小微商户进件接口时，需要通过表单来上传身份证图片等数据。在微信支付接口文档也说明了，需要使用 multipart/form-data 的方式发送请求。.NET 提供了 MultipartFormDataContent 类型，帮助我们构建表单请求，故有以下代码：

var form = new MultipartFormDataContent()
{
    {new StringContent("Value"),"Name},
    {new ByteArrayContent(new byte[]{}/*模拟文件数据*/),"File,"FileName}
}

按照微信支付官方文档提交之后，一直提示参数错误，百思不得其解。

原因

通过 Postman 模拟表单提交，捕获数据包，将其与 C# 的提交代码进行对比，发现了两处问题。

Postman 的原始提交：

POST http://api.mch.weixin.qq.com/secapi/mch/uploadmedia HTTP/1.1
User-Agent: PostmanRuntime/7.21.0
Accept: */*
Cache-Control: no-cache
Postman-Token: b6800c0f-3f16-4981-b661-e6d16fc1bb1e
Host: api.mch.weixin.qq.com
Content-Type: multipart/form-data; boundary=--------------------------639275760242036520206377
Accept-Encoding: gzip, deflate
Content-Length: 566
Connection: keep-alive

----------------------------639275760242036520206377
Content-Disposition: form-data; name="mch_id"

1565111111
----------------------------639275760242036520206377
Content-Disposition: form-data; name="media_hash"

7215E92A8F3F3D0256484EFFF53A25F6
----------------------------639275760242036520206377
Content-Disposition: form-data; name="sign_type"

HMAC-SHA256
----------------------------639275760242036520206377
Content-Disposition: form-data; name="sign"

A1D8B094FA24BE5531D1AC198DE25550
----------------------------639275760242036520206377--

C# 代码的提交：

POST http://api.mch.weixin.qq.com/secapi/mch/uploadmedia HTTP/1.1
Host: api.mch.weixin.qq.com
Content-Type: multipart/form-data; boundary="e9d5712f-7923-4ec5-8bf3-c8d5d3cd3217"
Content-Length: 502

--e9d5712f-7923-4ec5-8bf3-c8d5d3cd3217
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name=mch_id


--e9d5712f-7923-4ec5-8bf3-c8d5d3cd3217
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name=media_hash

33F15BC2D17D6FFBC18FA566EF65722E
--e9d5712f-7923-4ec5-8bf3-c8d5d3cd3217
Content-Type: text/plain; charset=utf-8
Content-Disposition: form-data; name=sign

1E377684F9BD583D2ED26FB367916C0C
--e9d5712f-7923-4ec5-8bf3-c8d5d3cd3217--

1. Boundary 的双引号

使用 MultipartFormDataContent 提交的表单请求，外部 Content-Type 的 boundary 值带有 " 号。而 Postman 提交的表单请求，它的 boudary 值是没有双引号的。

那为什么会造成这样的差异呢？参考这篇博客的讲解，是由于各个系统/语言针对 RFC 2046 的实现不一致导致的。针对于 MultipartFormDataContent 的行为，如果 Boundary 后面的值带有双引号是符合标准的。

RFC 2612 原文：

Although RFC 2046 [40] permits the boundary string to be quoted, some existing implementations handle a quoted boundary string incorrectly.

Boundary 的作用，是一个随机生成的字符串，在 HTTP 协议当中用于分割内部多个 Content。为什么是随机生成的呢？就是防止这个分割符跟你内部的 Content 产生重复造成意外。(C# 默认使用的是 Guid 作为随机串，你也可以在构造 MultipartFormDataContent 的时候，通过其构造函数手动指定)

2. 表单内键值对，值的双引号

第二个问题则是表单内的内容，他们的 name 键值对，其值又没有双引号，所以你得在添加 Content 的时候，得手动指定双引号。

解决

两个问题都是由于双引号导致的，所以只需要在真正发起调用之前将内部的双引号替换为空，或者将缺失的双引号添加上即可。

针对问题一，其内部的 ContentType.Parameters ，通过 LINQ 找到 boundary 的键值对，替换内部的双引号即可。

var boundaryValue = form.Headers.ContentType.Parameters.Single(p => p.Name == "boundary");
boundaryValue.Value = boundaryValue.Value.Replace("\"", String.Empty);

针对问题二，在构造内部 Content 的时候，其 Name 手动赋予双引号。

var form = new MultipartFormDataContent
{
    {new StringContent(mchId), "\"mch_id\""},
    {new ByteArrayContent(bytes), "media", $"\"{HttpUtility.UrlEncode(Path.GetFileName(imagePath))}\""},
    {new StringContent(mediaHash), "\"media_hash\""},
    {new StringContent(sign), "sign"}
};

Abp vNext 源码分析 - 13. 本地事件总线与分布式事件总线 (Rabbit MQ)

Tue, 10 Dec 2019 09:54:06 +0000

一、简要介绍

ABP vNext 封装了两种事件总线结构，第一种是 ABP vNext 自己实现的本地事件总线，这种事件总线无法跨项目发布和订阅。第二种则是分布式事件总线，ABP vNext 自己封装了一个抽象层进行定义，并使用 RabbitMQ 编写了一个基本实现。

在使用方式上，两种事件总线的作用基本相同。

事件总线分布在两个模块，在 Volo.Abp.EventBus 模块内部，定义了事件总线的抽象接口，以及本地事件总线 (ILocalEventBus) 的实现。分布式事件总线的具体实现，是在 Volo.Abp.EventBus.RabbitMQ 模块内部进行定义，从项目名称可以看出来，这个模块是基于 RabbitMQ 消息队列实现的。

但是该项目并不是直接引用 RabbitMQ.Client 包，而是在 Volo.Abp.RabbitMQ 项目内部引用。这是因为除了分布式事件总线以外，ABP 还基于 RabbitMQ 实现了一个后台作业管理器。

ABP vNext 框架便将一些对象抽象出来，放在 Volo.Abp.RabbitMQ 项目内部进行定义和实现。

二、源码分析

2.1 事件处理器的注册

分析源码，首先从一个项目的模块开始，Volo.Abp.EventBus 库的模块 AbpEventBusModule 只干了一件事情。在组件注册的时候，根据组件的实现接口 (ILocalEventHandler 或 IDistributedEventHandler) 不同，将其赋值给 AbpLocalEventBusOptions 与 AbpDistributedEventBusOptions 的 Handlers 属性。

也就是说，开发人员定义的事件处理程序 (Handler) 都会在依赖注入的时候，都会将其类型 (Type) 添加到事件总线的配置类当中，方便后续进行使用。

2.2 事件总线的接口

通过事件总线模块的单元测试我们可以知道，事件的发布与订阅都是通过 IEventBus 的两个子接口 (ILocalEventBus/IDistributedEventBus) 进行的。在 IEventBus 接口的定义中，有三种行为，分别是发布、订阅、取消订阅。

对于 ILocalEventBus 接口和 IDistributedEventBus 接口来说，它们都提供了一个，针对本地事件处理器和分布式处理器的特殊订阅方法。

ILocalEventBus：

/// <summary>
/// Defines interface of the event bus.
/// </summary>
public interface ILocalEventBus : IEventBus
{
    /// <summary>
    /// Registers to an event. 
    /// Same (given) instance of the handler is used for all event occurrences.
    /// </summary>
    /// <typeparam name="TEvent">Event type</typeparam>
    /// <param name="handler">Object to handle the event</param>
    IDisposable Subscribe<TEvent>(ILocalEventHandler<TEvent> handler)
        where TEvent : class;
}

IDistributedEventBus：

public interface IDistributedEventBus : IEventBus
{
    /// <summary>
    /// Registers to an event. 
    /// Same (given) instance of the handler is used for all event occurrences.
    /// </summary>
    /// <typeparam name="TEvent">Event type</typeparam>
    /// <param name="handler">Object to handle the event</param>
    IDisposable Subscribe<TEvent>(IDistributedEventHandler<TEvent> handler)
        where TEvent : class;
}

2.3 事件总线基本流程和实现

同其他模块一样，因为有分布式事件总线和本地事件总线，ABP vNext 同样抽象了一个 EventBusBase 类型，作为它们的基类实现。

一般的流程，我们是先定义某个事件，然后订阅该事件并指定事件处理器，最后在某个时刻发布事件。例如下面的代码：

首先定义了一个事件处理器，专门用于处理 EntityChangedEventData<MyEntity> 事件。

public class MyEventHandler : ILocalEventHandler<EntityChangedEventData<MyEntity>>
{
    public int EntityChangedEventCount { get; set; }

    public Task HandleEventAsync(EntityChangedEventData<MyEntity> eventData)
    {
        EntityChangedEventCount++;
        return Task.CompletedTask;
    }
}
var handler = new MyEventHandler();

LocalEventBus.Subscribe<EntityChangedEventData<MyEntity>>(handler);

await LocalEventBus.PublishAsync(new EntityCreatedEventData<MyEntity>(new MyEntity()));

2.3.1 事件的订阅

可以看到，这里使用的是 ILocalEventBus 定义的订阅方法，跳转到内部实现，它还是调用的 EventBus 的方法。

public virtual IDisposable Subscribe<TEvent>(ILocalEventHandler<TEvent> handler) where TEvent : class
{
    // 调用基类的 Subscribe 方法，并传递 TEvent 的类型，和事件处理器。
    return Subscribe(typeof(TEvent), handler);
}
public virtual IDisposable Subscribe(Type eventType, IEventHandler handler)
{
    return Subscribe(eventType, new SingleInstanceHandlerFactory(handler));
}

可以看到，这里传递了一个 SingleInstanceHandlerFactory 对象，这玩意儿是干嘛用的呢？从名字可以看出来，这是一个工厂，是用来创建 Handler (事件处理器) 的工厂，并且是一个单实例的事件处理器工厂。

下面就是 IEventHandlerFactory 接口的定义，以及 SingleInstanceHandlerFactory 实现。

public interface IEventHandlerFactory
{
    // 获得一个事件处理器包装对象，即事件处理器执行完毕之后，可以调用
    // IEventHandlerDisposeWrapper.Dispose() 进行释放。
    IEventHandlerDisposeWrapper GetHandler();

    // 判断在已有的事件处理器工厂集合中，是否已经存在了相同的事件处理器。
    bool IsInFactories(List<IEventHandlerFactory> handlerFactories);
}

public class SingleInstanceHandlerFactory : IEventHandlerFactory
{
    // 构造工厂时，传递的事件处理器实例。
    public IEventHandler HandlerInstance { get; }


    public SingleInstanceHandlerFactory(IEventHandler handler)
    {
        HandlerInstance = handler;
    }

    // 通过 EventHandlerDisposeWrapper 包装事件处理器实例。
    public IEventHandlerDisposeWrapper GetHandler()
    {
        return new EventHandlerDisposeWrapper(HandlerInstance);
    }

    // 判断针对 HandlerInstance 的事件处理器是否已经存在。
    public bool IsInFactories(List<IEventHandlerFactory> handlerFactories)
    {
        return handlerFactories
            .OfType<SingleInstanceHandlerFactory>()
            .Any(f => f.HandlerInstance == HandlerInstance);
    }
}

针对 IEventHandlerFactory 工厂，还拥有 3 个不同的实现，下表分别说明它们的应用场景。

实现类型	作用
`IocEventHandlerFactory`	每个工厂对应一个事件处理器的的类型，并通过 `ScopeFactory` 解析具体的事件处理器。生命周期由 `scope` 控制，当 `scope` 释放时，对应的事件处理器实例也会被销毁。
`SingleInstanceHandlerFactory`	每个工厂对应单独的一个事件处理器实例，事件处理器实例是由创建者控制的。
`TransientEventHandlerFactory`	每个工厂对应一个事件处理器的类型，区别是它不由 IoC 解析实例，而是使用的 `Activator.CreateInstance()` 方法构造实例，是一个瞬时对象，调用包装器的 `Dispose` 即会进行释放。
`TransientEventHandlerFactory<THandler>`	每个工厂对应指定的 `THandler` 事件处理器，生命周期同上面的工厂一样。

这几种工厂都是在订阅操作时，不同的订阅重载使用不同的工厂，或者是自己指定事件处理器的工厂均可。

public virtual IDisposable Subscribe<TEvent, THandler>()
    where TEvent : class
    where THandler : IEventHandler, new()
{
    return Subscribe(typeof(TEvent), new TransientEventHandlerFactory<THandler>());
}

public virtual IDisposable Subscribe(Type eventType, IEventHandler handler)
{
    return Subscribe(eventType, new SingleInstanceHandlerFactory(handler));
}

不过有一种特殊的行为，开发人员可以 不用显式订阅。在 EventBus 类型中，定义了一个 SubscribeHandlers(ITypeList<IEventHandler> handlers) 方法。该方法接收一个类型集合，通过遍历集合，从事件处理器的定义当中，取得事件处理器监听的事件类型 TEvent。

在取得了事件类型，并知晓了事件处理器类型以后，事件总线就可以订阅 TEvent 类型的事件，并使用 IocEventHandlerFactory 工厂来构造事件处理器。

protected virtual void SubscribeHandlers(ITypeList<IEventHandler> handlers)
{
    // 遍历事件处理器的类型，其实这里的就是模块启动时，传递给 XXXOptions 的集合。
    foreach (var handler in handlers)
    {
        // 获得事件处理器的所有接口定义，并遍历接口进行检查。
        var interfaces = handler.GetInterfaces();
        foreach (var @interface in interfaces)
        {
            // 如果接口没有实现 IEventHandler 类型，则忽略。
            if (!typeof(IEventHandler).GetTypeInfo().IsAssignableFrom(@interface))
            {
                continue;
            }

            // 从泛型参数当中，获得定义的事件类型。
            var genericArgs = @interface.GetGenericArguments();
            // 泛型参数完全匹配 1 时，才进行订阅操作。
            if (genericArgs.Length == 1)
            {
                Subscribe(genericArgs[0], new IocEventHandlerFactory(ServiceScopeFactory, handler));
            }
        }
    }
}

这个订阅方法在 EventBus 当中是一个抽象方法，分别在本地事件总线和分布式事件总线有实现，这里我们首先讲解本地事件的逻辑。

public class LocalEventBus : EventBusBase, ILocalEventBus, ISingletonDependency
{
    protected ConcurrentDictionary<Type, List<IEventHandlerFactory>> HandlerFactories { get; }

    public LocalEventBus(
        IOptions<AbpLocalEventBusOptions> options,
        IServiceScopeFactory serviceScopeFactory)
        : base(serviceScopeFactory)
    {
        Options = options.Value;
        Logger = NullLogger<LocalEventBus>.Instance;

        HandlerFactories = new ConcurrentDictionary<Type, List<IEventHandlerFactory>>();

        // 调用父类的方法，将模块初始化时扫描到的事件处理器，都尝试进行订阅。
        SubscribeHandlers(Options.Handlers);
    }

    public override IDisposable Subscribe(Type eventType, IEventHandlerFactory factory)
    {
        GetOrCreateHandlerFactories(eventType)
            // 锁住集合，以确保线程安全。
            .Locking(factories =>
                {
                    // 如果在集合内部，已经有了对应的工厂，则不进行添加。
                    if (!factory.IsInFactories(factories))
                    {
                        factories.Add(factory);
                    }
                }
            );

        // 返回一个事件处理器工厂注销器，当调用 Dispose() 方法时，会取消之前订阅的事件。
        return new EventHandlerFactoryUnregistrar(this, eventType, factory);
    }

    private List<IEventHandlerFactory> GetOrCreateHandlerFactories(Type eventType)
    {
        // 根据事件的类型，从字典中获得该类型的所有事件处理器工厂。
        return HandlerFactories.GetOrAdd(eventType, (type) => new List<IEventHandlerFactory>());
    }
}

上述流程结合 EventBus 和 LocalEventBus 讲解了事件的订阅流程，事件的订阅操作都是对 HandlerFactories 的操作，往里面添加指定事件的事件处理器工厂，而每个工厂都是跟具体的事件处理器实例/类型进行关联的。

2.3.2 事件的发布

当开发人员需要发布事件的时候，一般都是通过对应的 EventBus，调用响应的 PublishAsync 方法，传递要触发的事件类型与事件数据。接口和基类当中，定义了两种发布方法的签名与实现：

public virtual Task PublishAsync<TEvent>(TEvent eventData) where TEvent : class
{
    return PublishAsync(typeof(TEvent), eventData);
}

public abstract Task PublishAsync(Type eventType, object eventData);

第二种方法一共也分为本地事件总线的实现，和分布式事件总线的实现，本地事件比较简单，我们先分析本地事件总线的实现。

public override async Task PublishAsync(Type eventType, object eventData)
{
    // 定义了一个异常集合，用于接收多个事件处理器执行时，产生的所有异常。
    var exceptions = new List<Exception>();

    // 触发事件处理器。
    await TriggerHandlersAsync(eventType, eventData, exceptions);

    // 如果有任何异常产生，则抛出到之前的调用栈。
    if (exceptions.Any())
    {
        if (exceptions.Count == 1)
        {
            exceptions[0].ReThrow();
        }

        throw new AggregateException("More than one error has occurred while triggering the event: " + eventType, exceptions);
    }
}

可以看到真正的触发行为是在 TriggerHandlersAsync(Type eventType, object eventData, List<Exception> exceptions) 内部进行实现的。

protected virtual async Task TriggerHandlersAsync(Type eventType, object eventData, List<Exception> exceptions)
{
    // 针对于这个的作用，等同于 ConfigureAwait(false) 。
    // 具体可以参考 https://blogs.msdn.microsoft.com/benwilli/2017/02/09/an-alternative-to-configureawaitfalse-everywhere/。
    await new SynchronizationContextRemover();

    // 根据事件的类型，得到它的所有事件处理器工厂。
    foreach (var handlerFactories in GetHandlerFactories(eventType))
    {
        // 遍历所有的事件处理器工厂，通过 Factory 获得事件处理器，调用 Handler 的 HandleEventAsync 方法。
        foreach (var handlerFactory in handlerFactories.EventHandlerFactories)
        {
            await TriggerHandlerAsync(handlerFactory, handlerFactories.EventType, eventData, exceptions);
        }
    }

    // 如果类型继承了 IEventDataWithInheritableGenericArgument 接口，那么会检测泛型参数是否有父类。
    // 如果有父类，则会使用当前的事件数据，为其父类发布一个事件。
    if (eventType.GetTypeInfo().IsGenericType &&
        eventType.GetGenericArguments().Length == 1 &&
        typeof(IEventDataWithInheritableGenericArgument).IsAssignableFrom(eventType))
    {
        var genericArg = eventType.GetGenericArguments()[0];
        var baseArg = genericArg.GetTypeInfo().BaseType;
        if (baseArg != null)
        {
            // 构造基类的事件类型，使用当前一样的泛型定义，只是泛型参数使用基类。
            var baseEventType = eventType.GetGenericTypeDefinition().MakeGenericType(baseArg);
            // 构建类型的构造参数。
            var constructorArgs = ((IEventDataWithInheritableGenericArgument)eventData).GetConstructorArgs();
            // 通过事件类型和构造参数，构造一个新的事件数据实例。
            var baseEventData = Activator.CreateInstance(baseEventType, constructorArgs);
            // 发布父类的同类事件。
            await PublishAsync(baseEventType, baseEventData);
        }
    }
}

在上述代码内部，都还没有真正执行事件处理器，真正的事件处理器执行程序是在下面的方法进行执行的。ABP vNext 通过引入 IEventDataWithInheritableGenericArgument 接口，实现了 类型继承事件 的触发，该接口提供了一个 GetConstructorArgs() 方法定义，方便后面生成构造参数。

例如有一个基础事件叫做 EntityEventData<Student>，如果 Student 继承自 Person，那么在触发该事件的时候，也会发布一个 EntityEventData<Person> 事件。

2.3.3 事件处理器的执行

真正事件处理器的执行，是通过下面的方法实现的，大概思路就是通过事件总线工厂，构建了事件处理器的实例。通过反射，调用事件处理器的 HandleEventAsync() 方法。如果在处理过程当中，出现了异常，则将异常数据放置在 List<Exception> 集合当中。

protected virtual async Task TriggerHandlerAsync(IEventHandlerFactory asyncHandlerFactory, Type eventType, object eventData, List<Exception> exceptions)
{
    using (var eventHandlerWrapper = asyncHandlerFactory.GetHandler())
    {
        try
        {
            // 获得事件处理器的类型。
            var handlerType = eventHandlerWrapper.EventHandler.GetType();

            // 判断事件处理器是本地事件还是分布式事件。
            if (ReflectionHelper.IsAssignableToGenericType(handlerType, typeof(ILocalEventHandler<>)))
            {
                // 获得方法定义。
                var method = typeof(ILocalEventHandler<>)
                    .MakeGenericType(eventType)
                    .GetMethod(
                        nameof(ILocalEventHandler<object>.HandleEventAsync),
                        new[] { eventType }
                    );

                // 使用工厂创建的实例调用方法。
                await (Task)method.Invoke(eventHandlerWrapper.EventHandler, new[] { eventData });
            }
            else if (ReflectionHelper.IsAssignableToGenericType(handlerType, typeof(IDistributedEventHandler<>)))
            {
                var method = typeof(IDistributedEventHandler<>)
                    .MakeGenericType(eventType)
                    .GetMethod(
                        nameof(IDistributedEventHandler<object>.HandleEventAsync),
                        new[] { eventType }
                    );

                await (Task)method.Invoke(eventHandlerWrapper.EventHandler, new[] { eventData });
            }
            else
            {
                // 如果都不是，则说明类型不正确，抛出异常。
                throw new AbpException("The object instance is not an event handler. Object type: " + handlerType.AssemblyQualifiedName);
            }
        }
        // 捕获到异常都统一添加到异常集合当中。
        catch (TargetInvocationException ex)
        {
            exceptions.Add(ex.InnerException);
        }
        catch (Exception ex)
        {
            exceptions.Add(ex);
        }
    }
}

2.4 分布式事件总线

分布式事件总线的实现都存放在 Volo.Abp.EventBus.RabbitMQ，该项目的代码比较少，由三个文件构成。

在 RabbitMQ 模块的内部，只干了两件事情。首先从 JSON 配置文件当中，获取 AbpRabbitMqEventBusOptions 配置的三个参数，然后解析 RabbitMqDistributedEventBus 实例，并调用初始化方法 (Initialize())。

[DependsOn(
    typeof(AbpEventBusModule),
    typeof(AbpRabbitMqModule))]
public class AbpEventBusRabbitMqModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        var configuration = context.Services.GetConfiguration();

        // 从配置文件读取配置。
        Configure<AbpRabbitMqEventBusOptions>(configuration.GetSection("RabbitMQ:EventBus"));
    }

    public override void OnApplicationInitialization(ApplicationInitializationContext context)
    {
        // 调用初始化方法。
        context
            .ServiceProvider
            .GetRequiredService<RabbitMqDistributedEventBus>()
            .Initialize();
    }
}

2.4.1 分布式事件总线的初始化

public void Initialize()
{
    // 创建一个消费者，并配置交换器和队列。
    Consumer = MessageConsumerFactory.Create(
        new ExchangeDeclareConfiguration(
            AbpRabbitMqEventBusOptions.ExchangeName,
            type: "direct",
            durable: true
        ),
        new QueueDeclareConfiguration(
            AbpRabbitMqEventBusOptions.ClientName,
            durable: true,
            exclusive: false,
            autoDelete: false
        ),
        AbpRabbitMqEventBusOptions.ConnectionName
    );

    // 消费者在消费消息的时候，具体的执行逻辑。
    Consumer.OnMessageReceived(ProcessEventAsync);

    // 调用基类的方法，自动订阅对应的事件。
    SubscribeHandlers(AbpDistributedEventBusOptions.Handlers);
}

2.4.2 分布式事件的订阅

在定义分布式事件的时候，我们必须使用 EventNameAttribute 为事件声明路由键。

public override IDisposable Subscribe(Type eventType, IEventHandlerFactory factory)
{
    var handlerFactories = GetOrCreateHandlerFactories(eventType);

    if (factory.IsInFactories(handlerFactories))
    {
        return NullDisposable.Instance;
    }

    handlerFactories.Add(factory);

    if (handlerFactories.Count == 1) //TODO: Multi-threading!
    {
        // 为消费者绑定一个路由键，在收到对应的事件时，就会触发之前绑定的方法。
        Consumer.BindAsync(EventNameAttribute.GetNameOrDefault(eventType));
    }

    return new EventHandlerFactoryUnregistrar(this, eventType, factory);
}

订阅的时候，除了 Consumer.BindAsync() 以外，基本流程和本地事件总线基本一致。

2.4.3 分布式事件的发布

分布式事件总线一样重写了发布方法，内部首先使用 IRabbitMqSerializer 序列化器 (基于 JSON.NET) 将事件数据进行序列化，然后将消息投递出去。

public override Task PublishAsync(Type eventType, object eventData)
{
    var eventName = EventNameAttribute.GetNameOrDefault(eventType);
    // 序列化事件数据。
    var body = Serializer.Serialize(eventData);

    // 创建一个信道用于通讯。
    using (var channel = ConnectionPool.Get(AbpRabbitMqEventBusOptions.ConnectionName).CreateModel())
    {
        channel.ExchangeDeclare(
            AbpRabbitMqEventBusOptions.ExchangeName,
            "direct",
            durable: true
        );
        
        // 更改投递模式为持久化模式。
        var properties = channel.CreateBasicProperties();
        properties.DeliveryMode = RabbitMqConsts.DeliveryModes.Persistent;

        // 发布一个新的事件。
        channel.BasicPublish(
            exchange: AbpRabbitMqEventBusOptions.ExchangeName,
            routingKey: eventName,
            mandatory: true,
            basicProperties: properties,
            body: body
        );
    }

    return Task.CompletedTask;
}

2.4.4 分布式事件的执行

执行逻辑都存放在 ProcessEventAsync(IModel channel, BasicDeliverEventArgs ea) 方法内部，基本就是监听到指定的消息，首先反序列化消息，调用父类的 TriggerHandlersAsync 去执行具体的事件处理器。

private async Task ProcessEventAsync(IModel channel, BasicDeliverEventArgs ea)
{
    var eventName = ea.RoutingKey;
    var eventType = EventTypes.GetOrDefault(eventName);
    if (eventType == null)
    {
        return;
    }

    var eventData = Serializer.Deserialize(ea.Body, eventType);

    await TriggerHandlersAsync(eventType, eventData);
}

三、总结

ABP vNext 为我们实现了比较完善的本地事件总线，和基于 RabbitMQ 的分布式事件总线。在平时开发过程中，我们本地事件总线的使用频率应该还是比较高，而分布式事件总线目前仍处于一个半成品，很多高级特性还没实现，例如重试策略等。所以分布式事件总线要使用的话，建议使用较为成熟的 CAP 库替代 ABP vNext 的分布式事件总线。

C# 结合 PInvoke 对接 IP 摄像头的笔记

Wed, 27 Nov 2019 11:27:00 +0000

最近做项目的时候，需要对接厂商提供的 IP 摄像头。但是他们只提供了 C++ 的 SDK，没办法，只能开始撸 C# 的 SDK Helper 类。本篇文章主要记录了对接 C++ DLL 需要注意的几个地方，以及常见类型的转换。

要对接 C++ 的 DLL，首先得知道如何引用 DLL 内的方法。在 C# 当中，只需要编写符合 C++ 的函数签名，再使用 [DllImport] 特性指定 DLL 文件路径和入口点等参数即可。

假如你需要使用 Win32 API 提供的方法，这里我以 SetProcessDPIAware 函数为例：

public static class Win32Helper
{
    [DllImport("user32.dll")]
	public static extern bool SetProcessDPIAware();
}

接下来你只需要像使用静态方法一样，调用 Win32Helper.SetProcessDPIAware() 方法即可。

对接 DLL 时的问题记录

一般来说，提供 SDK 的厂商都会给你一份 DEMO 项目，或者是包含有函数定义的头文件 (*.h)。你只需要按照转换规则，将头文件里面的函数签名翻译成 C# 版本的即可。

函数签名不正确

有的时候，你名字直接和头文件一样还不行，得手动指定 EntryPoint 参数。你可以使用 DLL Export Viewer 工具来查看 DLL 的所有开放函数签名，将其复制下来，填写到 EntryPoint 参数即可。

[DllImport(@"ThirdFiles\AlprSDK.dll", EntryPoint = "AlprSDK_Startup@12", CharSet = CharSet.Ansi, CallingConvention = CallingConvention.Winapi)]
public static extern int AlprSDK_Startup(IntPtr hNotifyWnd, uint nCommandId, string pLocalAddress);

传递回调函数

有时第三方 SDK 需要你传递回调函数，一般都只提供了一个 void* 定义，也就是一个函数指针。那我们在 C# 如何将委托传递给该参数作为回调函数呢？

ALPRSDK_API OS_Error WINAPI AlprSDK_SearchAllCameras(unsigned int nTimeout,void* callback, char *pLocalAddr = NULL);

这个时候就需要使用到 [UnmanagedFunctionPointer] 特性来指定函数指针了，只需要将其标注到委托定义上，指定函数的调用方式即可。

最后我在 C# 里面编写的方法签名如下：

[UnmanagedFunctionPointer(CallingConvention.Winapi, CharSet = CharSet.Ansi)]
public delegate void SearchAllCamerasCallback(uint deviceType, string deviceName, string deviceIp,
    byte[] macAddress, ushort wPortWeb, ushort wPortListen, string pSubMask, string pGateway,
    string pMultiAddress, string pDnsAddress, ushort wMultiPort, int nChannelNum, int nFindCount,
    uint dwDeviceId);

[DllImport(@"ThirdFiles\AlprSDK.dll", EntryPoint = "_AlprSDK_SearchAllCameras@12", CharSet = CharSet.Ansi, CallingConvention = CallingConvention.Winapi)]
public static extern int AlprSDK_SearchAllCameras(uint nTimeout, SearchAllCamerasCallback callback, string pLocalAddress);

获取摄像头传递的位图

原始 C++ 的函数签名如下：

////////////////////////////////////////////////////////////////////////////////////////////
//捕获一张bmp图片.
//pBmpBuf:存放数据的缓冲区，传入参数时应该为NULL，内存由SDK自行管理.外面的应用程序不用去释放内存
//len:    数据的长度
ALPRSDK_API OS_Error WINAPI AlprSDK_CaptureBmp(int nHandleID, void **pBmpBuf, int *len);

主要的难点在于参数 void** pbmp 的翻译，这里参数 xx 就是指针的指针。因为这个位图是 SDK 来生成的，所以它会在内存空间开辟一段区域用于位图的存储。所以 void* 指向的是这个位图的起始地址，而我传递 void** 就是让 SDK 将这个起始地址传递给我。

所以 void* 可以翻译为 IntPtr，而这个地址不是我赋值的，而是 SDK 给我的地址，所以我们需要加上按引用传递关键字 ref 。

如此，我们便获得了位图在内存空间的起始地址，而且方法也将这个位图的大小给了我们。我们只需要从起始地址读取 N 个字节的数据，将其转储到 byte[] 即可。有了 byte[] 对象，你就可以进行其他的操作了，例如加载，保存等。

在 C# 内部，我是这样定义方法签名，并进行使用的：

[DllImport(@"ThirdFiles\AlprSDK.dll", EntryPoint = "_AlprSDK_CaptureBmp@12", CharSet = CharSet.Ansi, CallingConvention = CallingConvention.Winapi)]
public static extern uint AlprSDK_CaptureBmp(int nHandleId, ref IntPtr pBmpBuf, ref int len);

读取位图数据，并将其存储到磁盘当中。

var bitmapPtr = IntPtr.Zero;
var length = 0;

var result = AlprSdk.AlprSDK_CaptureBmp(0, ref bitmapPtr, ref length);
ThrowIfResultNotZero("无法从摄像头获取位图",result);

var bytes = new byte[length];
Marshal.Copy(bitmapPtr, bytes, 0, length);
using (var ms = File.Create(@"D:\bitmap.bmp"))
{
    using (var writer = new StreamWriter(ms))
    {
        writer.Write(bytes);
    }
}

附录 1：常用数据类型对照表

C/C++	C#	备注
`WORD`	`ushort`
`DWORD`	`uint`
`UCHAR`	`int` 或 `byte`
`UCHAR*`	`string` 或 `IntPtr`
`unsigned char*`	`[MarshalAs(UnmanagedType.LPArray)]byte[]`
`char*`	`string`
`LPCTSTR`	`string`
`LPTSTR`	`[MarshalAs(UnmanagedType.LPTStr)] string`
`long`	`int`
`ulong`	`uint`
`HANDLE`	`IntPtr`
`HWND`	`IntPtr`
`void*`	`IntPtr`
`int`	`int`
`int*`	`ref int`
`*int`	`IntPtr`
`unsigned int`	`uint`
`COLORREF`	`uint`
`CHAR`	`char`
`HDC`	`int`
`HGDIOBJ`	`int`
`BOOL`	`bool`
`LPSTR`	`string`
`LPCSTR`	`string`
`BYTE`	`byte`

参考文章：C# 与 C++ 数据类型对照

附录 2：相关工具软件下载

DLL Export Viewer v1.66：https://www.cnblogs.com

Abp vNext 自定义 Ef Core 仓储引发异常

Thu, 14 Nov 2019 15:14:00 +0000

问题

在使用自定义 Ef Core 仓储和 ABP vNext 注入的默认仓储时，通过两个 Repository 进行 Join 操作，提示 Cannot use multiple DbContext instances within a single query execution. Ensure the query uses a single context instance. 。这个异常信息翻译成中文的大概意思就是，你不能使用两个 DbContext 里面的 DbSet 进行 Join 查询。

如果将自定义仓储改为 IRepository<TEntity,TKey> 进行注入，是可以与 _courseRepostory 进行关联查询的。

我在 XXXEntityFrameworkCoreModule 的配置，以及自定义仓储 EfCoreStudentRepository 代码如下。

XXXEntityFrameworkCoreModule 代码：

public class XXXEntityFrameworkCoreModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        context.Services.AddAbpDbContext<XXXDbContext>(op =>
        {
            op.AddDefaultRepositories();
        });
        
        Configure<AbpDbContextOptions>(op => op.UsePostgreSql());
    }
}

EfCoreStudentRepository 代码：

public class EfCoreStudentRepository : EfCoreRepository<IXXXDbContext, Student, long>, IStudentRepository
{
    public EfCoreStudentRepository(IDbContextProvider<IXXXDbContext> dbContextProvider) : base(dbContextProvider)
    {
    }

    public Task<int> GetCountWithStudentlIdAsync(long studentId)
    {
        return DbSet.CountAsync(x=>x.studentId == studentId);
    }
}

原因

原因在异常信息已经说得十分清楚了，这里我们需要了解两个问题。

什么原因导致两个仓储内部的 DbContext 不一致？
为什么 ABP vNext 自己实现的仓储能够进行关联查询呢？

首先我们得知道，仓储内部的 DbContext 是怎么获取的。我们的自定义仓储都会继承 EfCoreRepository ，而这个仓储是实现了 IQuerable<T> 接口的，最终它会通过一个 IDbContextProvider<TDbContext> 获得一个可用的 DbContext 。

public class EfCoreRepository<TDbContext, TEntity> : RepositoryBase<TEntity>, IEfCoreRepository<TEntity>
    where TDbContext : IEfCoreDbContext
    where TEntity : class, IEntity
{
    public virtual DbSet<TEntity> DbSet => DbContext.Set<TEntity>();

    DbContext IEfCoreRepository<TEntity>.DbContext => DbContext.As<DbContext>();

    // 这里可以看到，是通过 IDbContextProvider 来获得 DbContext 的。
    protected virtual TDbContext DbContext => _dbContextProvider.GetDbContext();

    protected virtual AbpEntityOptions<TEntity> AbpEntityOptions => _entityOptionsLazy.Value;

    private readonly IDbContextProvider<TDbContext> _dbContextProvider;
    private readonly Lazy<AbpEntityOptions<TEntity>> _entityOptionsLazy;

    // ... 其他代码。
}

下面就是 IDbContextProvider<TDbContext> 内部的核心代码：

public class UnitOfWorkDbContextProvider<TDbContext> : IDbContextProvider<TDbContext> where TDbContext : IEfCoreDbContext
{
    private readonly IUnitOfWorkManager _unitOfWorkManager;
    private readonly IConnectionStringResolver _connectionStringResolver;

    // ... 其他代码。

    public TDbContext GetDbContext()
    {
        var unitOfWork = _unitOfWorkManager.Current;
        if (unitOfWork == null)
        {
            throw new AbpException("A DbContext can only be created inside a unit of work!");
        }

        var connectionStringName = ConnectionStringNameAttribute.GetConnStringName<TDbContext>();
        var connectionString = _connectionStringResolver.Resolve(connectionStringName);

        // 会构造一个 Key，而这个 Key 刚好是泛型类型的 FullName。
        var dbContextKey = $"{typeof(TDbContext).FullName}_{connectionString}";

        // 内部是从一个字典当中，根据 dbContextKey 获取 DbContext。如果不存在的话则调用工厂方法创建一个新的 DbContext。
        var databaseApi = unitOfWork.GetOrAddDatabaseApi(
            dbContextKey,
            () => new EfCoreDatabaseApi<TDbContext>(
                CreateDbContext(unitOfWork, connectionStringName, connectionString)
            ));

        return ((EfCoreDatabaseApi<TDbContext>)databaseApi).DbContext;
    }

    // ... 其他代码。
}

通过以上代码我们就可以知道，ABP vNext 在仓储的内部是通过 IDbContextProvider<TDbContext> 中的 TDbContext 泛型，来确定是否构建一个新的 DbContext 对象。

不论是 ABP vNext 针对 IRepository<TEntity,TKey> ，还是我们自己实现的自定义仓储，它们最终的实现都是基于 EfCoreRepository<TDbContext,TEntity,TKey> 的。而我们 IDbContextProvider<TDbContext> 的泛型，也是这个仓储基类提供的，后者的 TDbContext 就是前者的泛型参数。

所以当我们在模块添加 DbContext 的过城中，只要调用了 AddDefaultRepositories() 方法，ABP vNext 就会遍历你提供的 TDbContext 所定义的实体，然后为这些实体建立默认的仓储。

在注入仓储的时候，找到了获得默认仓储实现类型的方法，可以看到这里它使用的是 DefaultRepositoryDbContextType 作为默认的 TDbContext 类型。

protected virtual Type GetDefaultRepositoryImplementationType(Type entityType)
{
    var primaryKeyType = EntityHelper.FindPrimaryKeyType(entityType);

    // 重点在于构造仓储类型时，传递的 Options.DefaultRepositoryDbContextType 参数，这个参数就是后面 EfCoreRepository 的 TDbContext 泛型。
    if (primaryKeyType == null)
    {
        return Options.SpecifiedDefaultRepositoryTypes
            ? Options.DefaultRepositoryImplementationTypeWithoutKey.MakeGenericType(entityType)
            : GetRepositoryType(Options.DefaultRepositoryDbContextType, entityType);
    }

    return Options.SpecifiedDefaultRepositoryTypes
        ? Options.DefaultRepositoryImplementationType.MakeGenericType(entityType, primaryKeyType)
        : GetRepositoryType(Options.DefaultRepositoryDbContextType, entityType, primaryKeyType);
}

最后我发现这个就是在模块调用 AddAbpContext<TDbContext> 所提供的泛型参数。

public abstract class AbpCommonDbContextRegistrationOptions : IAbpCommonDbContextRegistrationOptionsBuilder
{
    // ... 其他代码

    protected AbpCommonDbContextRegistrationOptions(Type originalDbContextType, IServiceCollection services)
    {
        OriginalDbContextType = originalDbContextType;
        Services = services;
        DefaultRepositoryDbContextType = originalDbContextType;
        CustomRepositories = new Dictionary<Type, Type>();
        ReplacedDbContextTypes = new List<Type>();
    }

    // ... 其他代码
}

public class AbpDbContextRegistrationOptions : AbpCommonDbContextRegistrationOptions, IAbpDbContextRegistrationOptionsBuilder
{
    public Dictionary<Type, object> AbpEntityOptions { get; }

    public AbpDbContextRegistrationOptions(Type originalDbContextType, IServiceCollection services)
        : base(originalDbContextType, services) // 之类调用的就是上面的构造方法。
    {
        AbpEntityOptions = new Dictionary<Type, object>();
    }
}

public static class AbpEfCoreServiceCollectionExtensions
{
    public static IServiceCollection AddAbpDbContext<TDbContext>(
        this IServiceCollection services, 
        Action<IAbpDbContextRegistrationOptionsBuilder> optionsBuilder = null)
        where TDbContext : AbpDbContext<TDbContext>
    {
        // ... 其他代码。
        
        var options = new AbpDbContextRegistrationOptions(typeof(TDbContext), services);

        // ... 其他代码。

        return services;
    }
}

所以，我们的默认仓储的 dbContextKey 是 XXXDbContext，我们的自定义仓储继承 EfCoreRepository<IXXXDbContext,TEntity,TKey> ，所以它的 dbContextKey 就是 IXXXDbContext 。所以自定义仓储获取到的 DbContext 就与自定义仓储的不一致了，从而提示上述异常。

解决

找到自定自定义仓储的定义，修改它 EfCoreReposiotry<TDbContext,TEntity,TKey> 的 TDbContext 泛型参数，变更为 XXXDbContext 即可。

public class EfCoreStudentRepository : EfCoreRepository<XXXDbContext, Student, long>, IStudentRepository
{
    public EfCoreStudentRepository(IDbContextProvider<XXXDbContext> dbContextProvider) : base(dbContextProvider)
    {
    }

    public Task<int> GetCountWithStudentlIdAsync(long studentId)
    {
        return DbSet.CountAsync(x=>x.studentId == studentId);
    }
}

Abp vNext 源码分析 - 12. 后台作业与后台工作者

Fri, 25 Oct 2019 08:27:00 +0000

一、简要说明

文章信息：

基于的 ABP vNext 版本：1.0.0

创作日期：2019 年 10 月 24 日晚

更新日期：暂无

ABP vNext 提供了后台工作者和后台作业的支持，基本实现与原来的 ABP 框架类似，并且 ABP vNext 还提供了对 HangFire 和 RabbitMQ 的后台作业集成。开发人员在使用这些第三方库的时候，基本就是开箱即用，不需要做其他复杂的配置。

后台作业在系统开发的过程当中，是比较常用的功能。因为总是有一些长耗时的任务，而这些任务我们不是立即响应的，例如 Excel 文档导入、批量发送短信通知等。

后台工作者 的话，ABP vNext 的实现就是在 CLR 的 Timer 之上封装了一层，周期性地执行用户逻辑。ABP vNext 默认提供的 后台任务管理器，就是在后台工作者基础之上进行的封装。

涉及到后台任务、后台工作者的模块一共有 6 个，它们分别是：

Volo.Abp.Threading ：提供了一些常用的线程组件，其中 AbpTimer 就是在里面实现的。
Volo.Abp.BackgroundWorkers ：后台工作者的定义和实现。
Volo.Abp.BackgroundJobs.Abstractions ：后台任务的一些共有定义。
Volo.Abp.BackgroundJobs ：默认的后台任务管理器实现。
Volo.Abp.BackgroundJobs.HangFire ：基于 Hangfire 库实现的后台任务管理器。
Volo.Abp.BackgroundJobs.RabbitMQ ：基于 RabbitMQ 实现的后台任务管理器。

二、源码分析

2.1 线程组件

2.1.1 健壮的计时器

CLR 为我们提供了多种计时器，我们一般使用的是 System.Threading.Timer ，它是基于 CLR 线程池的一个周期计时器，会根据我们配置的 Period (周期) 定时执行。在 CLR 线程池中，所有的 Timer 只有 1 个线程为其服务。这个线程直到下一个计时器的触发时间，当下一个 Timer 对象到期时，这个线程就会将 Timer 的回调方法通过 ThreadPool.QueueUserWorkItem() 扔到线程池去执行。

不过这带来了一个问题，即你的回调方法执行时间超过了计时器的周期，那么就会造成上一个任务还没执行完成又开始执行新的任务。

解决这个方法其实很简单，即启动之后，将周期设置为 Timeout.Infinite ，这样只会执行一次。当回调方法执行完成之后，就设置 dueTime 参数说明下次执行要等待多久，并且周期还是 Timeout.Infinite。

ABP vNext 已经为我们提供了健壮的计时器，该类型的定义是 AbpTimer ，在内部用到了 volatile 关键字和 Monitor 实现 条件变量模式 解决多线程环境下的问题。

public class AbpTimer : ITransientDependency
{
    // 回调事件。
    public event EventHandler Elapsed;

    // 执行周期。
    public int Period { get; set; }

    // 定时器启动之后就开始运行，默认为 Fasle。
    public bool RunOnStart { get; set; }

    // 日志记录器。
    public ILogger<AbpTimer> Logger { get; set; }

    private readonly Timer _taskTimer;
    // 定时器是否在执行任务，默认为 false。
    private volatile bool _performingTasks;
    // 定时器的运行状态，默认为 false。
    private volatile bool _isRunning;

    public AbpTimer()
    {
        Logger = NullLogger<AbpTimer>.Instance;

        // 回调函数是 TimerCallBack，执行周期为永不执行。
        _taskTimer = new Timer(TimerCallBack, null, Timeout.Infinite, Timeout.Infinite);
    }

    public void Start(CancellationToken cancellationToken = default)
    {
        // 如果传递的周期小于等于 0 ，则抛出异常。
        if (Period <= 0)
        {
            throw new AbpException("Period should be set before starting the timer!");
        }

        // 使用互斥锁，保证线程安全。
        lock (_taskTimer)
        {
            // 如果启动之后就需要马上执行，则设置为 0，马上执行任务，否则会等待 Period 毫秒之后再执行（1 个周期）。
            _taskTimer.Change(RunOnStart ? 0 : Period, Timeout.Infinite);
            // 定时器成功运行了。
            _isRunning = true;
        }
        // 释放 _taskTimer 的互斥锁。
    }

    public void Stop(CancellationToken cancellationToken = default)
    {
        // 使用互斥锁。
        lock (_taskTimer)
        {
            // 将内部定时器设置为永不执行的状态。
            _taskTimer.Change(Timeout.Infinite, Timeout.Infinite);

            // 检测当前是否还有正在执行的任务，如果有则等待任务执行完成。
            while (_performingTasks)
            {
                // 临时释放锁，阻塞当前线程。但是其他线程可以获取 _timer 的互斥锁。
                Monitor.Wait(_taskTimer);
            }

            // 需要表示停止状态，所以标记状态为 false。
            _isRunning = false;
        }
    }

    private void TimerCallBack(object state)
    {
        lock (_taskTimer)
        {
            // 如果有任务正在运行，或者内部定时器已经停止了，则不做任何事情。
            if (!_isRunning || _performingTasks)
            {
                return;
            }

            // 临时停止内部定时器。
            _taskTimer.Change(Timeout.Infinite, Timeout.Infinite);
            // 表明马上需要执行任务了。
            _performingTasks = true;
        }

        try
        {
            // 调用绑定的事件。
            Elapsed.InvokeSafely(this, new EventArgs());
        }
        catch
        {
            // 注意，这里将会吞噬异常。
        }
        finally
        {
            lock (_taskTimer)
            {
                // 任务执行完成，更改状态。
                _performingTasks = false;

                // 如果定时器还在运行，没有被停止，则启动下一个 Period 周期。
                if (_isRunning)
                {
                    _taskTimer.Change(Period, Timeout.Infinite);
                }

                // 解除因为释放锁而阻塞的线程。
                // 如果已经调用了 Stop，则会唤醒那个因为 Wait 阻塞的线程，就会使 _isRunning 置为 false。
                Monitor.Pulse(_taskTimer);
            }
        }
    }
}

这里对 _performingTasks 和 _isRunning 字段设置为 volatile 防止指令重排和寄存器缓存。这是因为在 Stop 方法内部使用到的 _performingTasks 可能会被优化，所以将该字段设置为了易失的。

2.2.1 `IRunnable` 接口

ABP vNext 为任务的启动和停止，抽象了一个 IRunnable 接口。虽然描述说的是对线程的行为进行抽象，但千万千万不要手动调用 Thread.Abort() 。关于 Thread.Abort() 的坏处，这里不再多加赘述，可以参考 这篇文章 的描述，或者搜索其他的相关文章。

public interface IRunnable
{
    // 启动这个服务。
    Task StartAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// 停止这个服务。
    /// </summary>
    Task StopAsync(CancellationToken cancellationToken = default);
}

2.2 后台工作者

2.2.1 模块的构造

后台工作者的模块行为比较简单，它定义了在应用程序初始化和销毁时的行为。在初始化时，后台工作者管理器 获得所有 后台工作者，并开始启动它们。在销毁时，后台工作者管理器获得所有后台工作者，并开始停止他们，这样才能够做到优雅退出。

[DependsOn(
    typeof(AbpThreadingModule)
    )]
public class AbpBackgroundWorkersModule : AbpModule
{
    public override void OnApplicationInitialization(ApplicationInitializationContext context)
    {
        var options = context.ServiceProvider.GetRequiredService<IOptions<AbpBackgroundWorkerOptions>>().Value;
        // 如果启用了后台工作者，那么获得后台工作者管理器的实例，并调用 StartAsync 启动所有后台工作者。
        if (options.IsEnabled)
        {
            AsyncHelper.RunSync(
                () => context.ServiceProvider
                    .GetRequiredService<IBackgroundWorkerManager>()
                    .StartAsync()
            );
        }
    }

    public override void OnApplicationShutdown(ApplicationShutdownContext context)
    {
        var options = context.ServiceProvider.GetRequiredService<IOptions<AbpBackgroundWorkerOptions>>().Value;
        // 如果启用了后台工作者，那么获得后台工作者管理器的实例，并调用 StopAsync 停止所有后台工作者。
        if (options.IsEnabled)
        {
            AsyncHelper.RunSync(
                () => context.ServiceProvider
                    .GetRequiredService<IBackgroundWorkerManager>()
                    .StopAsync()
            );
        }
    }
}

2.2.1 后台工作者的定义

首先看看 IBackgroundWorker 接口的定义，是空的。不过继承了 ISingletonDependency 接口，说明我们的每个后台工作者都是单例的。

/// <summary>
/// 在后台运行，执行某些任务的工作程序（线程）的接口定义。
/// </summary>
public interface IBackgroundWorker : IRunnable, ISingletonDependency
{

}

ABP vNext 为我们定义了一个抽象的后台工作者类型 BackgroundWorkerBase，这个基类的设计目的是提供一些常用组件（和 ApplicationService 一样）。

public abstract class BackgroundWorkerBase : IBackgroundWorker
{
    //TODO: Add UOW, Localization and other useful properties..?
    //TODO: 是否应该提供工作单元、本地化以及其他常用的属性？

    public ILogger<BackgroundWorkerBase> Logger { protected get; set; }

    protected BackgroundWorkerBase()
    {
        Logger = NullLogger<BackgroundWorkerBase>.Instance;
    }
    
    public virtual Task StartAsync(CancellationToken cancellationToken = default)
    {
        Logger.LogDebug("Started background worker: " + ToString());
        return Task.CompletedTask;
    }

    public virtual Task StopAsync(CancellationToken cancellationToken = default)
    {
        Logger.LogDebug("Stopped background worker: " + ToString());
        return Task.CompletedTask;
    }

    public override string ToString()
    {
        return GetType().FullName;
    }
}

ABP vNext 内部只有一个默认的后台工作者实现 PeriodicBackgroundWorkerBase。从名字上来看，意思是就是周期执行的后台工作者，内部就是用的 AbpTimer 来实现，ABP vNext 将其包装起来是为了实现统一的模式(后台工作者)。

public abstract class PeriodicBackgroundWorkerBase : BackgroundWorkerBase
{
    protected readonly AbpTimer Timer;

    // 也就意味着子类必须在其构造函数，指定 timer 的执行周期。
    protected PeriodicBackgroundWorkerBase(AbpTimer timer)
    {
        Timer = timer;
        Timer.Elapsed += Timer_Elapsed;
    }

    // 启动后台工作者。
    public override async Task StartAsync(CancellationToken cancellationToken = default)
    {
        await base.StartAsync(cancellationToken);
        Timer.Start(cancellationToken);
    }

    // 停止后台工作者。
    public override async Task StopAsync(CancellationToken cancellationToken = default)
    {
        Timer.Stop(cancellationToken);
        await base.StopAsync(cancellationToken);
    }
    
    // Timer 关联的周期事件，之所以不直接挂载 DoWork，是为了捕获异常。
    private void Timer_Elapsed(object sender, System.EventArgs e)
    {
        try
        {
            DoWork();
        }
        catch (Exception ex)
        {
            Logger.LogException(ex);
        }
    }

    // 你要周期执行的任务。
    protected abstract void DoWork();
}

我们如果要实现自己的后台工作者，只需要继承该类，实现 DoWork() 方法即可。

public class TestWorker : PeriodicBackgroundWorkerBase
{
    public TestWorker(AbpTimer timer) : base(timer)
    {
        // 每五分钟执行一次。
        timer.Period = (int)TimeSpan.FromMinutes(5).TotalMilliseconds;
    }

    protected override void DoWork()
    {
        Console.WriteLine("后台工作者被执行了。");
    }
}

然后在我们自己模块的 OnPreApplicationInitialization() 方法内解析出后台作业管理器(IBackgroundWorkerManager)，调用它的 Add() 方法，将我们定义的 TestWorker 添加到管理器当中即可。

2.2.2 后台工作者管理器

所有的后台工作者都是通过 IBackgroundWorkerManager 进行管理的，它提供了 StartAsync()、StopAsync()、Add() 方法。前面两个方法就是 IRunnable 接口定义的，后台工作者管理器直接集成了该接口，后面的 Add() 方法就是用来动态添加我们的后台工作者。

后台工作者管理器的默认实现是 BackgroundWorkerManager 类型，它内部做的事情很简单，就是维护一个后台工作者集合。每当调用 StartAsync() 或 StopAsync() 方法的时候，都从这个集合遍历后台工作者，执行他们的启动和停止方法。

这里值得注意的一点是，当我们调用 Add() 方法添加了一个后台工作者之后，后台工作者管理器就会启动这个后台工作者。

public class BackgroundWorkerManager : IBackgroundWorkerManager, ISingletonDependency, IDisposable
{
    protected bool IsRunning { get; private set; }

    private bool _isDisposed;

    private readonly List<IBackgroundWorker> _backgroundWorkers;

    public BackgroundWorkerManager()
    {
        _backgroundWorkers = new List<IBackgroundWorker>();
    }

    public virtual void Add(IBackgroundWorker worker)
    {
        _backgroundWorkers.Add(worker);

        // 如果当前后台工作者管理器还处于运行状态，则调用工作者的 StartAsync() 方法启动。
        if (IsRunning)
        {
            AsyncHelper.RunSync(
                () => worker.StartAsync()
            );
        }
    }

    public virtual void Dispose()
    {
        if (_isDisposed)
        {
            return;
        }

        _isDisposed = true;

        //TODO: ???
    }

    // 启动，则遍历集合启动。
    public virtual async Task StartAsync(CancellationToken cancellationToken = default)
    {
        IsRunning = true;

        foreach (var worker in _backgroundWorkers)
        {
            await worker.StartAsync(cancellationToken);
        }
    }

    // 停止， 则遍历集合停止。
    public virtual async Task StopAsync(CancellationToken cancellationToken = default)
    {
        IsRunning = false;

        foreach (var worker in _backgroundWorkers)
        {
            await worker.StopAsync(cancellationToken);
        }
    }
}

上述代码其实存在一个问题，即后台工作者被释放以后，是否还能执行 Add() 操作。参考我 之前的文章 ，其实当对象被释放之后，就应该抛出 ObjectDisposedException 异常。

2.3 后台作业

比起后台工作者，我们执行一次性任务的时候，一般会使用后台作业进行处理。比起只能设置固定周期的 PeriodicBackgroundWorkerBase ，集成了 Hangfire 的后台作业管理器，能够让我们使用 Cron 表达式，更加灵活地设置任务的执行周期。

2.3.1 模块的构造

关于后台作业的模块，我们需要说道两处。第一处是位于 Volo.Abp.BackgroundJobs.Abstractions 项目的 AbpBackgroundJobsAbstractionsModule ，第二出则是位于 Volo.Abp.BackgroundJobs 项目的 AbpBackgroundJobsModule 。

AbpBackgroundJobsAbstractionsModule 的主要行为是将符合条件的后台作业，添加到 AbpBackgroundJobOptions 配置当中，以便后续进行使用。

public override void PreConfigureServices(ServiceConfigurationContext context)
{
    RegisterJobs(context.Services);
}

private static void RegisterJobs(IServiceCollection services)
{
    var jobTypes = new List<Type>();

    // 如果注册的类型符合 IBackgroundJob<> 泛型，则添加到集合当中。
    services.OnRegistred(context =>
    {
        if (ReflectionHelper.IsAssignableToGenericType(context.ImplementationType, typeof(IBackgroundJob<>)))
        {
            jobTypes.Add(context.ImplementationType);
        }
    });

    services.Configure<AbpBackgroundJobOptions>(options =>
    {
        // 将数据赋值给配置类。
        foreach (var jobType in jobTypes)
        {
            options.AddJob(jobType);
        }
    });
}

Volo.Abp.BackgroundJobs 内部是 ABP vNext 为我们提供的 默认后台作业管理器，这个后台作业管理器 本质上是一个后台工作者。

这个后台工作者会周期性(取决于 AbpBackgroundJobWorkerOptions.JobPollPeriod 值，默认为 5 秒种)地从 IBackgroundJobStore 捞出一堆后台任务，并且在后台执行。至于每次执行多少个后台任务，这也取决于 AbpBackgroundJobWorkerOptions.MaxJobFetchCount 的值，默认值是 1000 个。

注意：

这里的 Options 类是 AbpBackgroundJobWorkerOptions，别和 AbpBackgroundWorkerOptions 混淆了。

所以在 AbpBackgroundJobsModule 模块里面，只做了一件事情，就是将负责后台作业的后台工作者，添加到后台工作者管理器种，并开始周期性地执行。

public override void OnApplicationInitialization(ApplicationInitializationContext context)
{
    var options = context.ServiceProvider.GetRequiredService<IOptions<AbpBackgroundJobOptions>>().Value;
    if (options.IsJobExecutionEnabled)
    {
        // 获得后台工作者管理器，并将负责后台作业的工作者添加进去。
        context.ServiceProvider
            .GetRequiredService<IBackgroundWorkerManager>()
            .Add(context.ServiceProvider.GetRequiredService<IBackgroundJobWorker>()
            );
    }
}

2.3.2 后台作业的定义

在上一节里面看到，只要是实现 IBackgroundJob<TArgs> 类型的都视为一个后台作业。这个后台作业接口，只定义了一个行为，那就是执行(Execute(TArgs))。这里的 TArgs 泛型作为执行后台作业时，需要传递的参数类型。

// 因为是传入的参数，所以泛型参数是逆变的。
public interface IBackgroundJob<in TArgs>
{
    void Execute(TArgs args);
}

检查源码，发现 ABP vNext 的邮箱模块定义了一个邮件发送任务 BackgroundEmailSendingJob，它的实现大概如下。

public class BackgroundEmailSendingJob : BackgroundJob<BackgroundEmailSendingJobArgs>, ITransientDependency
{
    // ...
    
    public override void Execute(BackgroundEmailSendingJobArgs args)
    {
        AsyncHelper.RunSync(() => EmailSender.SendAsync(args.To, args.Subject, args.Body, args.IsBodyHtml));
    }
}

2.3.3 后台作业管理器

后台作业都是通过一个后台作业管理器(IBackgroundJobManager)进行管理的，这个接口定义了一个入队方法(EnqueueAsync())，注意，我们的后台作业在入队后，不是马上执行的。

说一下这个入队处理逻辑：

首先我们会通过参数的类型，获取到任务的名称。(假设任务上面没有标注 BackgroundJobNameAttribute 特性，那么任务的名称就是参数类型的 FullName 。)
构造一个 BackgroundJobInfo 对象。
通过 IBackgroundJobStore 持久化任务信息。

public virtual async Task<string> EnqueueAsync<TArgs>(TArgs args, BackgroundJobPriority priority = BackgroundJobPriority.Normal, TimeSpan? delay = null)
{
    // 获取任务名称。
    var jobName = BackgroundJobNameAttribute.GetName<TArgs>();
    var jobId = await EnqueueAsync(jobName, args, priority, delay);
    return jobId.ToString();
}

protected virtual async Task<Guid> EnqueueAsync(string jobName, object args, BackgroundJobPriority priority = BackgroundJobPriority.Normal, TimeSpan? delay = null)
{
    var jobInfo = new BackgroundJobInfo
    {
        Id = GuidGenerator.Create(),
        JobName = jobName,
        // 通过序列化器，序列化参数值，方便存储。这里内部其实使用的是 JSON.NET 进行序列化。
        JobArgs = Serializer.Serialize(args),
        Priority = priority,
        CreationTime = Clock.Now,
        NextTryTime = Clock.Now
    };

    // 如果任务有执行延迟，则任务的初始执行时间要加上这个延迟。
    if (delay.HasValue)
    {
        jobInfo.NextTryTime = Clock.Now.Add(delay.Value);
    }

    // 持久化任务信息，方便后面执行后台作业的工作者能够取到。
    await Store.InsertAsync(jobInfo);

    return jobInfo.Id;
}

BackgroundJobNameAttribute 相关的方法：

public static string GetName<TJobArgs>()
{
    return GetName(typeof(TJobArgs));
}

public static string GetName([NotNull] Type jobArgsType)
{
    Check.NotNull(jobArgsType, nameof(jobArgsType));

    // 判断参数类型上面是否标注了特性，并且特性实现了 IBackgroundJobNameProvider 接口。
    return jobArgsType
                .GetCustomAttributes(true)
                .OfType<IBackgroundJobNameProvider>()
                .FirstOrDefault()
                ?.Name
        // 拿不到名字，则使用类型的 FullName。
            ?? jobArgsType.FullName;
}

2.3.4 后台作业的存储

后台作业的存储默认是放在内存的，这点可以从 InMemoryBackgroundJobStore 类型实现看出来。在它的内部使用了一个并行字典，通过作业的 Guid 与作业进行关联绑定。

除了内存实现，在 Volo.Abp.BackgroundJobs.Domain 模块还有一个 BackgroundJobStore 实现，基本套路与 SettingStore 一样，都是存储到数据库里面。

public class BackgroundJobStore : IBackgroundJobStore, ITransientDependency
{
    protected IBackgroundJobRepository BackgroundJobRepository { get; }

    // ... 
    
    public BackgroundJobInfo Find(Guid jobId)
    {
        return ObjectMapper.Map<BackgroundJobRecord, BackgroundJobInfo>(
            BackgroundJobRepository.Find(jobId)
        );
    }
    
    // ...

    public void Insert(BackgroundJobInfo jobInfo)
    {
        BackgroundJobRepository.Insert(
            ObjectMapper.Map<BackgroundJobInfo, BackgroundJobRecord>(jobInfo)
        );
    }

    // ...
}

2.3.5 后台作业的执行

默认的后台作业管理器是通过一个后台工作者来执行后台任务的，这个实现叫做 BackgroundJobWorker，这个后台工作者的生命周期也是单例的。后台作业的具体执行逻辑里面，涉及到了以下几个类型的交互。

类型	作用
`AbpBackgroundJobOptions`	提供每个后台任务的配置信息，包括任务的类型、参数类型、任务名称数据。
`AbpBackgroundJobWorkerOptions`	提供后台作业工作者的配置信息，例如每个周期最大执行的作业数量、后台工作者的执行周期、作业执行超时时间等。
`BackgroundJobConfiguration`	后台任务的配置信息，作用是将持久化存储的作业信息与运行时类型进行绑定和实例化，以便 ABP vNext 来执行具体的任务。
`IBackgroundJobExecuter`	后台作业的执行器，当我们从持久化存储获取到后台作业信息时，将会通过这个执行器来执行具体的后台作业。
`IBackgroundJobSerializer`	后台作业序列化器，用于后台作业持久化时进行序列化的工具，默认采用的是 JSON.NET 进行实现。
`JobExecutionContext`	执行器在执行后台作业时，是通过这个上下文参数进行执行的，在这个上下文内部，包含了后台作业的具体类型、后台作业的参数值。
`IBackgroundJobStore`	前面已经讲过了，这个是用于后台作业的持久化存储，默认实现是存储在内存。
`BackgroundJobPriority`	后台作业的执行优先级定义，ABP vNext 在执行后台任务时，会根据任务的优先级进行排序，以便在后面执行的时候优先级高的任务先执行。

我们来按照逻辑顺序走一遍它的实现，首先后台作业的执行工作者会从持久化存储内，获取 MaxJobFetchCount 个任务用于执行。从持久化存储获取后台作业信息(BackgroundJobInfo)，是由 IBackgroundJobStore 提供的。

var store = scope.ServiceProvider.GetRequiredService<IBackgroundJobStore>();

var waitingJobs = store.GetWaitingJobs(WorkerOptions.MaxJobFetchCount);

// 不存在任何后台作业，则直接结束本次调用。
if (!waitingJobs.Any())
{
    return;
}

InMemoryBackgroundJobStore 的相关实现：

public List<BackgroundJobInfo> GetWaitingJobs(int maxResultCount)
{
    return _jobs.Values
        .Where(t => !t.IsAbandoned && t.NextTryTime <= Clock.Now)
        .OrderByDescending(t => t.Priority)
        .ThenBy(t => t.TryCount)
        .ThenBy(t => t.NextTryTime)
        .Take(maxResultCount)
        .ToList();
}

上面的代码可以看出来，首先排除 被放弃的任务 ，包含达到执行时间的任务，，然后根据任务的优先级从高到低进行排序。重试次数少的优先执行，预计执行时间越早的越先执行。最后从这些数据中，筛选出 maxResultCount 结果并返回。

说到这里，我们来看一下这个 NextTryTime 是如何被计算出来的？回想起最开始的后台作业管理器，我们在添加一个后台任务的时候，就会设置这个后台任务的 预计执行时间。第一个任务被添加到执行队列中时，它的值一般是 Clock.Now ，也就是它被添加到队列的时间。

不过 ABP vNext 为了让那些经常执行失败的任务，有比较低的优先级再执行，就在每次任务执行失败之后，会将 NextTryTime 的值指数级进行增加。这块代码可以在 CalculateNextTryTime 里面看到，也就是说某个任务的执行 失败次数越高，那么它下一次的预期执行时间就会越远。

protected virtual DateTime? CalculateNextTryTime(BackgroundJobInfo jobInfo, IClock clock)
{
    // 一般来说，这个 DefaultWaitFactor 因子的值是 2.0 。
    var nextWaitDuration = WorkerOptions.DefaultFirstWaitDuration * (Math.Pow(WorkerOptions.DefaultWaitFactor, jobInfo.TryCount - 1)); // 同执行失败的次数进行挂钩。
    var nextTryDate = jobInfo.LastTryTime?.AddSeconds(nextWaitDuration) ??
                        clock.Now.AddSeconds(nextWaitDuration);

    if (nextTryDate.Subtract(jobInfo.CreationTime).TotalSeconds > WorkerOptions.DefaultTimeout)
    {
        return null;
    }

    return nextTryDate;
}

当预期的执行时间都超过 DefaultTimeout 的超时时间时(默认为 2 天)，说明这个任务确实没救了，就不要再执行了。

我们之前说到，从 IBackgroundJobStore 拿到了需要执行的后台任务信息集合，接下来我们就要开始执行后台任务了。

foreach (var jobInfo in waitingJobs)
{
    jobInfo.TryCount++;
    jobInfo.LastTryTime = clock.Now;

    try
    {
        // 根据任务名称获取任务的配置参数。
        var jobConfiguration = JobOptions.GetJob(jobInfo.JobName);
        // 根据配置里面存储的任务类型，将参数值进行反序列化。
        var jobArgs = serializer.Deserialize(jobInfo.JobArgs, jobConfiguration.ArgsType);
        // 构造一个新的执行上下文，让执行器执行任务。
        var context = new JobExecutionContext(scope.ServiceProvider, jobConfiguration.JobType, jobArgs);

        try
        {
            jobExecuter.Execute(context);

            // 如果任务执行成功则删除该任务。            
            store.Delete(jobInfo.Id);
        }
        catch (BackgroundJobExecutionException)
        {
            // 发生任务执行失败异常时，根据指定的公式计算下一次的执行时间。
            var nextTryTime = CalculateNextTryTime(jobInfo, clock);

            if (nextTryTime.HasValue)
            {
                jobInfo.NextTryTime = nextTryTime.Value;
            }
            else
            {
                // 超过超时时间的时候，公式计算函数返回 null，该任务置为废弃任务。
                jobInfo.IsAbandoned = true;
            }

            TryUpdate(store, jobInfo);
        }
    }
    catch (Exception ex)
    {
        // 执行过程中，产生了未知异常，设置为废弃任务，并打印日志。
        Logger.LogException(ex);
        jobInfo.IsAbandoned = true;
        TryUpdate(store, jobInfo);
    }
}

执行后台任务的时候基本分为 5 步，它们分别是：

获得任务关联的配置参数，默认不用提供，因为在之前模块初始化的时候就已经配置了（你也可以显式指定）。
通过之前存储的配置参数，将参数值反序列化出来，构造具体实例。
构造一个执行上下文。
后台任务执行器执行具体的后台任务。
成功则删除任务，失败则更新任务下次的执行状态。

至于执行器里面的真正执行操作，你都拿到了参数值和任务类型了。就可以通过类型用 IoC 获取后台任务对象的实例，然后通过反射匹配方法签名，在实例上调用这个方法传入参数即可。

public virtual void Execute(JobExecutionContext context)
{
    // 构造具体的后台作业实例对象。
    var job = context.ServiceProvider.GetService(context.JobType);
    if (job == null)
    {
        throw new AbpException("The job type is not registered to DI: " + context.JobType);
    }

    // 获得需要执行的方法签名。
    var jobExecuteMethod = context.JobType.GetMethod(nameof(IBackgroundJob<object>.Execute));
    if (jobExecuteMethod == null)
    {
        throw new AbpException($"Given job type does not implement {typeof(IBackgroundJob<>).Name}. The job type was: " + context.JobType);
    }

    try
    {
        // 直接通过 MethodInfo 的 Invoke 方法调用，传入具体的实例对象和参数值即可。
        jobExecuteMethod.Invoke(job, new[] { context.JobArgs });
    }
    catch (Exception ex)
    {
        Logger.LogException(ex);

        // 如果是执行方法内的异常，则包装进行处理，然后抛出。
        throw new BackgroundJobExecutionException("A background job execution is failed. See inner exception for details.", ex)
        {
            JobType = context.JobType.AssemblyQualifiedName,
            JobArgs = context.JobArgs
        };
    }
}

2.3.5 集成 Hangfire

ABP vNext 对于 Hangfire 的集成代码分布在 Volo.Abp.HangFire 和 Volo.Abp.BackgroundJobs.HangFire 模块内部，前者是在模块配置里面，调用 Hangfire 库的相关方法，注入组件到 IoC 容器当中。后者则是对后台作业进行了适配处理，替换了默认的 IBackgroundJobManager 实现。

在 AbpHangfireModule 模块内部，通过工厂创建出来一个 BackgroudJobServer 实例，并将它的生命周期与应用程序的生命周期进行绑定，以便进行销毁处理。

public class AbpHangfireModule : AbpModule
{
    private BackgroundJobServer _backgroundJobServer;

    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        context.Services.AddHangfire(configuration =>
        {
            context.Services.ExecutePreConfiguredActions(configuration);
        });
    }

    public override void OnApplicationInitialization(ApplicationInitializationContext context)
    {
        var options = context.ServiceProvider.GetRequiredService<IOptions<AbpHangfireOptions>>().Value;
        _backgroundJobServer = options.BackgroundJobServerFactory.Invoke(context.ServiceProvider);
    }

    public override void OnApplicationShutdown(ApplicationShutdownContext context)
    {
        //TODO: ABP may provide two methods for application shutdown: OnPreApplicationShutdown & OnApplicationShutdown
        _backgroundJobServer.SendStop();
        _backgroundJobServer.Dispose();
    }
}

我们直奔主题，看一下基于 Hangfire 的后台作业管理器是怎么实现的。

public class HangfireBackgroundJobManager : IBackgroundJobManager, ITransientDependency
{
    public Task<string> EnqueueAsync<TArgs>(TArgs args, BackgroundJobPriority priority = BackgroundJobPriority.Normal,
        TimeSpan? delay = null)
    {
        // 如果没有延迟参数，则直接通过 Enqueue() 方法扔进执行对了。
        if (!delay.HasValue)
        {
            return Task.FromResult(
                BackgroundJob.Enqueue<HangfireJobExecutionAdapter<TArgs>>(
                    adapter => adapter.Execute(args)
                )
            );
        }
        else
        {
            return Task.FromResult(
                BackgroundJob.Schedule<HangfireJobExecutionAdapter<TArgs>>(
                    adapter => adapter.Execute(args),
                    delay.Value
                )
            );
        }
    }

上述代码中使用 HangfireJobExecutionAdapter 进行了一个适配操作，因为 Hangfire 要将一个后台任务扔进队列执行，不是用 TArgs 就能解决的。

转到这个适配器定义，提供了一个 Execute(TArgs) 方法，当被添加到 Hangfire 队列执行的时候。实际 Hangfire 会调用适配器的 Excetue(TArgs) 方法，然后内部还是使用的 IBackgroundJobExecuter 来执行具体定义的任务。

public class HangfireJobExecutionAdapter<TArgs>
{
    protected AbpBackgroundJobOptions Options { get; }
    protected IServiceScopeFactory ServiceScopeFactory { get; }
    protected IBackgroundJobExecuter JobExecuter { get; }

    public HangfireJobExecutionAdapter(
        IOptions<AbpBackgroundJobOptions> options, 
        IBackgroundJobExecuter jobExecuter, 
        IServiceScopeFactory serviceScopeFactory)
    {
        JobExecuter = jobExecuter;
        ServiceScopeFactory = serviceScopeFactory;
        Options = options.Value;
    }

    public void Execute(TArgs args)
    {
        using (var scope = ServiceScopeFactory.CreateScope())
        {
            var jobType = Options.GetJob(typeof(TArgs)).JobType;
            var context = new JobExecutionContext(scope.ServiceProvider, jobType, args);
            JobExecuter.Execute(context);
        }
    }
}

2.3.6 集成 RabbitMQ

基于 RabbitMQ 的后台作业实现，我想放在分布式事件总线里面，对其一起进行讲解。

三、总结

ABP vNext 为我们提供了多种后台作业管理器的实现，你可以根据自己的需求选用不同的后台作业管理器，又或者是自己动手造轮子。

需要看其他的 ABP vNext 相关文章？点击我 即可跳转到总目录。

Abp vNext 源码分析 - 11. 用户的自定义参数与配置

Thu, 24 Oct 2019 04:26:50 +0000

一、简要说明

文章信息：

基于的 ABP vNext 版本：1.0.0

创作日期：2019 年 10 月 23 日晚

更新日期：暂无

ABP vNext 针对用户可编辑的配置，提供了单独的 Volo.Abp.Settings 模块，本篇文章的后面都将这种用户可变更的配置，叫做参数。所谓可编辑的配置，就是我们在系统页面上，用户可以动态更改的参数值。

例如你做的系统是一个门户网站，那么前端页面上展示的 Title ，你可以在后台进行配置。这个时候你就可以将网站这种全局配置作为一个参数，在程序代码中进行定义。通过 GlobalSettingValueProvider(后面会讲) 作为这个参数的值提供者，用户就可以随时对 Title 进行更改。又或者是某些通知的开关，你也可以定义一堆参数，让用户可以动态的进行变更。

二、源码分析

2.1 模块启动流程

AbpSettingsModule 模块干的事情只有两件，第一是扫描所有 ISettingDefinitionProvider (参数定义提供者)，第二则是往配置参数添加一堆参数值提供者(ISettingValueProvider)。

public class AbpSettingsModule : AbpModule
{
    public override void PreConfigureServices(ServiceConfigurationContext context)
    {
        // 自动扫描所有实现了 ISettingDefinitionProvider 的类型。
        AutoAddDefinitionProviders(context.Services);
    }

    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        // 配置默认的一堆参数值提供者。
        Configure<AbpSettingOptions>(options =>
        {
            options.ValueProviders.Add<DefaultValueSettingValueProvider>();
            options.ValueProviders.Add<GlobalSettingValueProvider>();
            options.ValueProviders.Add<TenantSettingValueProvider>();
            options.ValueProviders.Add<UserSettingValueProvider>();
        });
    }

    private static void AutoAddDefinitionProviders(IServiceCollection services)
    {
        var definitionProviders = new List<Type>();

        services.OnRegistred(context =>
        {
            if (typeof(ISettingDefinitionProvider).IsAssignableFrom(context.ImplementationType))
            {
                definitionProviders.Add(context.ImplementationType);
            }
        });

        // 将扫描到的数据添加到 Options 中。
        services.Configure<AbpSettingOptions>(options =>
        {
            options.DefinitionProviders.AddIfNotContains(definitionProviders);
        });
    }
}

2.2 参数的定义

2.2.1 参数的基本定义

ABP vNext 关于参数的定义在类型 SettingDefinition 可以找到，内部的结构与 PermissionDefine 类似。。开发人员需要先定义有哪些可配置的参数，然后 ABP vNext 会自动进行管理，在网站运行期间，用户、租户可以根据自己的需要随时变更参数值。

public class SettingDefinition
{
    /// <summary>
    /// 参数的唯一标识。
    /// </summary>
    [NotNull]
    public string Name { get; }

    // 参数的显示名称，是一个多语言字符串。
    [NotNull]
    public ILocalizableString DisplayName
    {
        get => _displayName;
        set => _displayName = Check.NotNull(value, nameof(value));
    }
    private ILocalizableString _displayName;

    // 参数的描述信息，也是一个多语言字符串。
    [CanBeNull]
    public ILocalizableString Description { get; set; }

    /// <summary>
    /// 参数的默认值。
    /// </summary>
    [CanBeNull]
    public string DefaultValue { get; set; }

    /// <summary>
    /// 指定参数与其参数的值，是否能够在客户端进行显示。对于某些密钥设置来说是很危险的，默认值为 Fasle。
    /// </summary>
    public bool IsVisibleToClients { get; set; }

    /// <summary>
    /// 允许更改本参数的值提供者，为空则允许所有提供者提供参数值。
    /// </summary>
    public List<string> Providers { get; } //TODO: 考虑重命名为 AllowedProviders。

    /// <summary>
    /// 当前参数是否能够继承父类的 Scope 信息，默认值为 True。
    /// </summary>
    public bool IsInherited { get; set; }

    /// <summary>
    /// 参数相关连的一些扩展属性，通过一个字典进行存储。
    /// </summary>
    [NotNull]
    public Dictionary<string, object> Properties { get; }

    /// <summary>
    /// 参数的值是否以加密的形式存储，默认值为 False。
    /// </summary>
    public bool IsEncrypted { get; set; }

    public SettingDefinition(
        string name,
        string defaultValue = null,
        ILocalizableString displayName = null,
        ILocalizableString description = null,
        bool isVisibleToClients = false,
        bool isInherited = true,
        bool isEncrypted = false)
    {
        Name = name;
        DefaultValue = defaultValue;
        IsVisibleToClients = isVisibleToClients;
        DisplayName = displayName ?? new FixedLocalizableString(name);
        Description = description;
        IsInherited = isInherited;
        IsEncrypted = isEncrypted;

        Properties = new Dictionary<string, object>();
        Providers = new List<string>();
    }

    // 设置附加数据值。
    public virtual SettingDefinition WithProperty(string key, object value)
    {
        Properties[key] = value;
        return this;
    }

    // 设置 Provider 属性的值。
    public virtual SettingDefinition WithProviders(params string[] providers)
    {
        if (!providers.IsNullOrEmpty())
        {
            Providers.AddRange(providers);
        }

        return this;
    }
}

上面的参数定义值得注意的就是 DefaultValue 、IsVisibleToClients、IsEncrypted 这三个属性。默认值一般适用于某些系统配置，例如当前系统的默认语言。后面两个属性则更加注重于 安全问题，因为某些参数存储的是一些重要信息，这个时候就需要进行特殊处理了。

如果参数值是加密的，那么在获取参数值的时候就会进行解密操作，例如下面的代码。

SettingProvider 类中的相关代码：

// ...
public class SettingProvider : ISettingProvider, ITransientDependency
{
    // ...
    public virtual async Task<string> GetOrNullAsync(string name)
    {
        // ...
        var value = await GetOrNullValueFromProvidersAsync(providers, setting);
        // 对值进行解密处理。
        if (setting.IsEncrypted)
        {
            value = SettingEncryptionService.Decrypt(setting, value);
        }

        return value;
    }

    // ...
}

参数不对客户端可见的话，在默认的 AbpApplicationConfigurationAppService 服务类中，获取参数值的时候就会跳过。

private async Task<ApplicationSettingConfigurationDto> GetSettingConfigAsync()
{
    var result = new ApplicationSettingConfigurationDto
    {
        Values = new Dictionary<string, string>()
    };

    foreach (var settingDefinition in _settingDefinitionManager.GetAll())
    {
        // 不会展示这些属性为 False 的参数。
        if (!settingDefinition.IsVisibleToClients)
        {
            continue;
        }

        result.Values[settingDefinition.Name] = await _settingProvider.GetOrNullAsync(settingDefinition.Name);
    }

    return result;
}

2.2.2 参数定义的扫描

跟权限定义类似，所有的参数定义都被放在了 SettingDefinitionProvider 里面，如果你需要定义一堆参数，只需要继承并实现 Define(ISettingDefinitionContext) 抽象方法就可以了。

public class TestSettingDefinitionProvider : SettingDefinitionProvider
{
    public override void Define(ISettingDefinitionContext context)
    {
        context.Add(
            new SettingDefinition(TestSettingNames.TestSettingWithoutDefaultValue),
            new SettingDefinition(TestSettingNames.TestSettingWithDefaultValue, "default-value"),
            new SettingDefinition(TestSettingNames.TestSettingEncrypted, isEncrypted: true)
        );
    }
}

因为我们的 SettingDefinitionProvider 实现了 ISettingDefinitionProvider 和 ITransientDependency 接口，所以这些 Provider 都会在组件注册的时候(模块里面有定义)，添加到对应的 AbpSettingOptions 内部，方便后续进行调用。

2.2.3 参数定义的管理

我们的 参数定义提供者 和 参数值提供者 都赋值给 AbpSettingOptions 了，首先看有哪些地方使用到了 参数定义提供者。

第二个我们已经看过，是在模块启动时有用到。第一个则是有一个 SettingDefinitionManager ，顾名思义就是管理所有的 SettingDefinition 的管理器。这个管理器提供了三个方法，都是针对 SettingDefinition 的查询功能。

public interface ISettingDefinitionManager
{
    // 根据参数定义的标识查询，不存在则抛出 AbpException 异常。
    [NotNull]
    SettingDefinition Get([NotNull] string name);

    // 获得所有的参数定义。
    IReadOnlyList<SettingDefinition> GetAll();

    // 根据参数定义的标识查询，如果不存在则返回 null。
    SettingDefinition GetOrNull(string name);
}

接下来我们看一下它的默认实现 SettingDefinitionManager ，它的内部没什么说的，只是注意 SettingDefinitions 的填充方式，这里使用了线程安全的 懒加载模式。只有当用到的时候，才会调用 CreateSettingDefinitions() 方法填充数据。

public class SettingDefinitionManager : ISettingDefinitionManager, ISingletonDependency
{
    protected Lazy<IDictionary<string, SettingDefinition>> SettingDefinitions { get; }

    protected AbpSettingOptions Options { get; }

    protected IServiceProvider ServiceProvider { get; }

    public SettingDefinitionManager(
        IOptions<AbpSettingOptions> options,
        IServiceProvider serviceProvider)
    {
        ServiceProvider = serviceProvider;
        Options = options.Value;

        // 填充的时候，调用 CreateSettingDefinitions 方法进行填充。
        SettingDefinitions = new Lazy<IDictionary<string, SettingDefinition>>(CreateSettingDefinitions, true);
    }

    // ...

    protected virtual IDictionary<string, SettingDefinition> CreateSettingDefinitions()
    {
        var settings = new Dictionary<string, SettingDefinition>();

        using (var scope = ServiceProvider.CreateScope())
        {
            // 从 Options 中得到类型，然后通过 IoC 进行实例化。
            var providers = Options
                .DefinitionProviders
                .Select(p => scope.ServiceProvider.GetRequiredService(p) as ISettingDefinitionProvider)
                .ToList();

            // 执行每个 Provider 的 Define 方法填充数据。
            foreach (var provider in providers)
            {
                provider.Define(new SettingDefinitionContext(settings));
            }
        }

        return settings;
    }
}

2.3 参数值的管理

当我们构建好参数的定义之后，我们要设置某个参数的值，或者说获取某个参数的值应该怎么操作呢？查看相关的单元测试，看到了 ABP vNext 自身是注入 ISettingProvider ，调用它的 GetOrNullAsync() 获取参数值。

private readonly ISettingProvider _settingProvider;

var settingValue = await _settingProvider.GetOrNullAsync("WebSite.Title")

跳转到接口，发现它有两个实现，这里我们只讲解一下 SettingProvider 类的实现。

2.3.1 获取参数值

直奔主题，来看一下 ISettingProvider.GetOrNullAsync(string) 方法是怎么来获取参数值的。

public class SettingProvider : ISettingProvider, ITransientDependency
{
    protected ISettingDefinitionManager SettingDefinitionManager { get; }
    protected ISettingEncryptionService SettingEncryptionService { get; }
    protected ISettingValueProviderManager SettingValueProviderManager { get; }

    public SettingProvider(
        ISettingDefinitionManager settingDefinitionManager,
        ISettingEncryptionService settingEncryptionService,
        ISettingValueProviderManager settingValueProviderManager)
    {
        SettingDefinitionManager = settingDefinitionManager;
        SettingEncryptionService = settingEncryptionService;
        SettingValueProviderManager = settingValueProviderManager;
    }

    public virtual async Task<string> GetOrNullAsync(string name)
    {
        // 根据名称获取参数定义。
        var setting = SettingDefinitionManager.Get(name);

        // 从参数值提供者管理器，获得一堆参数值提供者。
        var providers = Enumerable
            .Reverse(SettingValueProviderManager.Providers);

        // 过滤符合参数定义的提供者，这里就是用到了之前参数定义的 List<string> Providers 属性。
        if (setting.Providers.Any())
        {
            providers = providers.Where(p => setting.Providers.Contains(p.Name));
        }

        //TODO: How to implement setting.IsInherited?
        //TODO: 如何实现 setting.IsInherited 功能?

        var value = await GetOrNullValueFromProvidersAsync(providers, setting);
        // 如果参数是加密的，则需要进行解密操作。
        if (setting.IsEncrypted)
        {
            value = SettingEncryptionService.Decrypt(setting, value);
        }

        return value;
    }

    protected virtual async Task<string> GetOrNullValueFromProvidersAsync(IEnumerable<ISettingValueProvider> providers,
    SettingDefinition setting)
    {
        // 只要从任意 Provider 中，读取到了参数值，就直接进行返回。
        foreach (var provider in providers)
        {
            var value = await provider.GetOrNullAsync(setting);
            if (value != null)
            {
                return value;
            }
        }

        return null;
    }

    // ...
}

所以真正干活的还是 ISettingValueProviderManager 里面存放的一堆 ISettingValueProvider ，这个 参数值管理器 的接口很简单，只提供了一个 List<ISettingValueProvider> Providers { get; } 的定义。

它会从模块配置的 ValueProviders 属性内部，通过 IoC 实例化对应的参数值提供者。

_lazyProviders = new Lazy<List<ISettingValueProvider>>(
    () => Options
        .ValueProviders
        .Select(type => serviceProvider.GetRequiredService(type) as ISettingValueProvider)
        .ToList(),
    true

2.3.2 参数值提供者

参数值提供者的接口定义是 ISettingValueProvider，它定义了一个名称和 GetOrNullAsync(SettingDefinition) 方法，后者可以通过参数定义获取存储的值。

public interface ISettingValueProvider
{
    string Name { get; }

    Task<string> GetOrNullAsync([NotNull] SettingDefinition setting);
}

注意这里的返回值是 Task<string> ，也就是说我们的参数值类型必须是 string 类型的，如果需要存储其他的类型可能就需要从 string 进行类型转换了。

在这里的 SettingValueProvider 其实类似于我们之前讲过的 权限提供者。因为 ABP vNext 考虑到了多种情况，我们的参数值有可能是根据用户获取的，同时也有可能是根据不同的租户进行获取的。所以 ABP vNext 为我们预先定义了四种参数值提供器，他们分别是 DefaultValueSettingValueProvider、GlobalSettingValueProvider、TenantSettingValueProvider、UserSettingValueProvider 。

下面我们就来讲讲这几个不同的参数提供者有啥不一样。

DefaultValueSettingValueProvider：

顾名思义，默认值参数提供者就是使用的参数定义里面的 DefaultValue 属性，当你查询某个参数值的时候，就直接返回了。

public override Task<string> GetOrNullAsync(SettingDefinition setting)
{
    return Task.FromResult(setting.DefaultValue);
}

GlobalSettingValueProvider：

这是一种全局的提供者，它没有对应的 Key，也就是说如果数据库能查到 ProviderName 是 G 的记录，就直接返回它的值了。

public class GlobalSettingValueProvider : SettingValueProvider
{
    public const string ProviderName = "G";

    public override string Name => ProviderName;

    public GlobalSettingValueProvider(ISettingStore settingStore) 
        : base(settingStore)
    {
    }

    public override Task<string> GetOrNullAsync(SettingDefinition setting)
    {
        return SettingStore.GetOrNullAsync(setting.Name, Name, null);
    }
}

TenantSettingValueProvider：

租户提供者，则是会将当前登录租户的 Id 结合 T 进行查询，也就是参数值是按照不同的租户进行隔离的。

public class TenantSettingValueProvider : SettingValueProvider
{
    public const string ProviderName = "T";

    public override string Name => ProviderName;

    protected ICurrentTenant CurrentTenant { get; }
    
    public TenantSettingValueProvider(ISettingStore settingStore, ICurrentTenant currentTenant)
        : base(settingStore)
    {
        CurrentTenant = currentTenant;
    }

    public override async Task<string> GetOrNullAsync(SettingDefinition setting)
    {
        return await SettingStore.GetOrNullAsync(setting.Name, Name, CurrentTenant.Id?.ToString());
    }
}

UserSettingValueProvider：

用户提供者，则是会将当前用户的 Id 作为查询条件，结合 U 在数据库进行查询匹配的参数值，参数值是根据不同的用户进行隔离的。

public class UserSettingValueProvider : SettingValueProvider
{
    public const string ProviderName = "U";

    public override string Name => ProviderName;

    protected ICurrentUser CurrentUser { get; }

    public UserSettingValueProvider(ISettingStore settingStore, ICurrentUser currentUser)
        : base(settingStore)
    {
        CurrentUser = currentUser;
    }

    public override async Task<string> GetOrNullAsync(SettingDefinition setting)
    {
        if (CurrentUser.Id == null)
        {
            return null;
        }

        return await SettingStore.GetOrNullAsync(setting.Name, Name, CurrentUser.Id.ToString());
    }
}

2.3.3 参数值的存储

除了 DefaultValueSettingValueProvider 是直接从参数定义获取值以外，其他的参数值提供者都是通过 ISettingStore 读取参数值的。在该模块的默认实现当中，是直接返回 null 的，只有当你使用了 Volo.Abp.SettingManagement 模块，你的参数值才是存储到数据库当中的。

我这里不再详细解析 Volo.Abp.SettingManagement 模块的其他实现，只说一下 ISettingStore 在它内部的实现 SettingStore。

public class SettingStore : ISettingStore, ITransientDependency
{
    protected ISettingManagementStore ManagementStore { get; }

    public SettingStore(ISettingManagementStore managementStore)
    {
        ManagementStore = managementStore;
    }

    public Task<string> GetOrNullAsync(string name, string providerName, string providerKey)
    {
        return ManagementStore.GetOrNullAsync(name, providerName, providerKey);
    }
}

我们可以看到它也只是个包装，真正的操作类型是 ISettingManagementStore。

2.3.4 参数值的设置

在 ABP vNext 的核心模块当中，是没有提供对参数值的变更的。只有在 Volo.Abp.SettingManagement 模块内部，它提供了 ISettingManager 管理器，可以进行参数值的变更。原理很简单，就是对数据库对应的表进行修改而已。

public async Task SetAsync(string name, string value, string providerName, string providerKey)
{
    // 操作仓储，查询记录。
    var setting = await SettingRepository.FindAsync(name, providerName, providerKey);
    
    // 新增或者更新记录。
    if (setting == null)
    {
        setting = new Setting(GuidGenerator.Create(), name, value, providerName, providerKey);
        await SettingRepository.InsertAsync(setting);
    }
    else
    {
        setting.Value = value;
        await SettingRepository.UpdateAsync(setting);
    }
}

三、总结

ABP vNext 提供了多种参数值提供者，我们可以根据自己的需要灵活选择。如果不能够满足你的需求，你也可以自己实现一个参数值提供者。我建议对于用户在界面可更改的参数，都可以使用 SettingDefinition 定义成参数，可以根据不同的情况进行配置读取。

ABP vNext 其他模块用到的许多参数，也都是使用的 SettingDefinition 进行定义。例如 Identity 模块用到的密码验证规则，就是通过 ISettingProvider 进行读取的，还有当前程序的默认语言。

需要看其他的 ABP vNext 相关文章？点击我 即可跳转到总目录。

Abp vNext 源码分析 - 9. 接口参数的认证

Wed, 23 Oct 2019 04:06:17 +0000

一、简要说明

ABP vNext 针对接口参数的校验工作，分别由过滤器和拦截器两步完成。过滤器内部使用的 ASP.NET Core MVC 所提供的 IModelStateValidator 进行处理，而拦截器使用的是 ABP vNext 自己提供的一套 IObjectValidator 进行校验工作。

关于参数验证相关的代码，分布在以下三个项目当中：

Volo.Abp.AspNetCore.Mvc
Volo.Abp.Validation
Volo.Abp.FluentValidation

通过 MVC 的过滤器和 ABP vNext 提供的拦截器，我们能够快速地对接口的参数、对象的属性进行统一的验证处理，而不会将这些代码扩散到业务层当中。

文章信息：

基于的 ABP vNext 版本：1.0.0

创作日期：2019 年 10 月 22 日晚

更新日期：暂无

二、源码分析

2.1 模型验证过滤器

模型验证过滤器是直接使用的 MVC 那一套模型验证机制，基于数据注解的方式进行校验。数据注解也就是存放在 System.ComponentModel.DataAnnotations 命名空间下面的一堆特性定义，例如我们经常在 DTO 上面使用的 [Required] 、[StringLength] 特性等，如果想知道更多的数据注解用法，可以前往 MSDN 进行学习。

2.1.1 过滤器的注入

模型验证过滤器 (AbpValidationActionFilter) 的定义存放在 Volo.Abp.AspNetCore.Mvc 项目内部，它是在模块的 ConfigureService() 方法中被注入到 IoC 容器的。

AbpAspNetCoreMvcModule 里面的相关代码：

namespace Volo.Abp.AspNetCore.Mvc
{
    [DependsOn(
        typeof(AbpAspNetCoreModule),
        typeof(AbpLocalizationModule),
        typeof(AbpApiVersioningAbstractionsModule),
        typeof(AbpAspNetCoreMvcContractsModule),
        typeof(AbpUiModule)
        )]
    public class AbpAspNetCoreMvcModule : AbpModule
    {
        //
        public override void ConfigureServices(ServiceConfigurationContext context)
        {
            // ...
            Configure<MvcOptions>(mvcOptions =>
            {
                mvcOptions.AddAbp(context.Services);
            });
        }
        // ...
    }
}

上述代码是调用对 MvcOptions 编写的 AddAbp(this MvcOptions, IServiceCollection) 扩展方法，传入了我们的 IoC 注册容器(IServiceCollection)。

AbpMvcOptionsExtensions 里面的相关代码：

internal static class AbpMvcOptionsExtensions
{
    public static void AddAbp(this MvcOptions options, IServiceCollection services)
    {
        AddConventions(options, services);
        // 注册过滤器。
        AddFilters(options);
        AddModelBinders(options);
        AddMetadataProviders(options, services);
    }

    // ...

    private static void AddFilters(MvcOptions options)
    {
        options.Filters.AddService(typeof(AbpAuditActionFilter));
        options.Filters.AddService(typeof(AbpFeatureActionFilter));
        // 我们的参数验证过滤器。
        options.Filters.AddService(typeof(AbpValidationActionFilter));
        options.Filters.AddService(typeof(AbpUowActionFilter));
        options.Filters.AddService(typeof(AbpExceptionFilter));
    }

    // ...
}

到这一步，我们的 AbpValidationActionFilter 会被添加到 IoC 容器当中，以供 ASP.NET Core Mvc 框架进行使用。

2.1.2 过滤器的验证流程

我们的验证过滤器通过上述步骤，已经被注入到 IoC 容器当中了，以后我们每次的接口调用都会进入 AbpValidationActionFilter 的 OnActionExecutionAsync() 方法内部。在这个过滤器的内部实现代码中，我们看到 ABP 为我们注入了一个 IModelStateValidator 对象。

public class AbpValidationActionFilter : IAsyncActionFilter, ITransientDependency
{
    private readonly IModelStateValidator _validator;

    public AbpValidationActionFilter(IModelStateValidator validator)
    {
        _validator = validator;
    }

    public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
    {
        //TODO: Configuration to disable validation for controllers..?
        //TODO: 是否应该增加一个配置项，以便开发人员禁用验证功能 ？

        // 判断当前请求是否是一个控制器行为，是则返回 true。
        // 第二个条件会判断当前的接口返回值是 IActionResult、JsonResult、ObjectResult、NoContentResult 的一种，是则返回 true。
        // 这里则会忽略不是控制器的方法，控制器类型不是上述类型任意一种也会被忽略。
        if (!context.ActionDescriptor.IsControllerAction() ||
            !context.ActionDescriptor.HasObjectResult())
        {
            await next();
            return;
        }

        // 调用验证器进行验证操作。
        _validator.Validate(context.ModelState);
        await next();
    }
}

过滤器的行为很简单，判断当前的 API 请求是否符合条件，不符合则不进行参数验证，否则调用 IModelStateValidator 的 Validate 方法，将模型状态传递给它进行处理。

这个接口从名字上看，应该是模型状态验证器。因为我们接口上面的参数，在 ASP.NET Core MVC 的使用当中，会进行模型绑定，即建立对象到 Http 请求参数的映射。

public interface IModelStateValidator
{
    void Validate(ModelStateDictionary modelState);

    void AddErrors(IAbpValidationResult validationResult, ModelStateDictionary modelState);
}

ABP vNext 的默认实现是 ModelStateValidator ，它的内部实现也很简单。就是遍历 ModelStateDictionary 对象的错误信息，将其添加到一个 AbpValidationResult 对象内部的 List 集合。这样做的目的，是方便后面 ABP vNext 进行错误抛出。

public class ModelStateValidator : IModelStateValidator, ITransientDependency
{
    public virtual void Validate(ModelStateDictionary modelState)
    {
        var validationResult = new AbpValidationResult();

        AddErrors(validationResult, modelState);

        if (validationResult.Errors.Any())
        {
            throw new AbpValidationException(
                "ModelState is not valid! See ValidationErrors for details.",
                validationResult.Errors
            );
        }
    }

    public virtual void AddErrors(IAbpValidationResult validationResult, ModelStateDictionary modelState)
    {
        if (modelState.IsValid)
        {
            return;
        }

        foreach (var state in modelState)
        {
            foreach (var error in state.Value.Errors)
            {
                validationResult.Errors.Add(new ValidationResult(error.ErrorMessage, new[] { state.Key }));
            }
        }
    }
}

2.1.3 结果的包装

当过滤器抛出了 AbpValidationException 异常之后，ABP vNext 会在异常过滤器 (AbpExceptionFilter) 内部捕获这个特定异常 (取决于异常继承的 IHasValidationErrors 接口)，并对其进行特殊的包装。

[Serializable]
public class AbpValidationException : AbpException, 
    IHasLogLevel, 
    // 注意这个接口。
    IHasValidationErrors, 
    IExceptionWithSelfLogging
{
    // ...
}

2.1.4 数据注解的验证

这一节相当于是一个扩展知识，帮助我们了解数据注解的工作机制，以及 ModelStateDictionary 是怎么被填充的。

扩展阅读：

2.2 对象验证拦截器

ABP vNext 除了使用 ASP.NET Core MVC 提供的模型验证功能，自己也提供了一个单独的验证模块。我们先来看看模块类型内部所执行的操作：

public class AbpValidationModule : AbpModule
{
    public override void PreConfigureServices(ServiceConfigurationContext context)
    {
        // 添加拦截器注册类。
        context.Services.OnRegistred(ValidationInterceptorRegistrar.RegisterIfNeeded);
        // 添加对象验证拦截器的辅助对象。
        AutoAddObjectValidationContributors(context.Services);
    }

    private static void AutoAddObjectValidationContributors(IServiceCollection services)
    {
        var contributorTypes = new List<Type>();

        // 在类型注册的时候，如果类型实现了 IObjectValidationContributor 接口，则认定是验证器的辅助类。
        services.OnRegistred(context =>
        {
            if (typeof(IObjectValidationContributor).IsAssignableFrom(context.ImplementationType))
            {
                contributorTypes.Add(context.ImplementationType);
            }
        });

        // 最后向 Options 类型添加辅助类的类型定义。
        services.Configure<AbpValidationOptions>(options =>
        {
            options.ObjectValidationContributors.AddIfNotContains(contributorTypes);
        });
    }
}

模块在启动时进行了两个操作，第一是为框架注册对象验证拦截器，第二则是添加 辅助类型(IObjectValidationContributor) 的定义到配置类中，方便后续进行使用。

2.2.1 拦截器的注入

拦截器的注入行为很简单，主要注册的类型实现了 IValidationEnabled 接口，就会为其注入拦截器。

public static class ValidationInterceptorRegistrar
{
    public static void RegisterIfNeeded(IOnServiceRegistredContext context)
    {
        if (typeof(IValidationEnabled).IsAssignableFrom(context.ImplementationType))
        {
            context.Interceptors.TryAdd<ValidationInterceptor>();
        }
    }
}

2.2.2 拦截器的行为

public class ValidationInterceptor : AbpInterceptor, ITransientDependency
{
    private readonly IMethodInvocationValidator _methodInvocationValidator;

    public ValidationInterceptor(IMethodInvocationValidator methodInvocationValidator)
    {
        _methodInvocationValidator = methodInvocationValidator;
    }

    public override void Intercept(IAbpMethodInvocation invocation)
    {
        Validate(invocation);
        invocation.Proceed();
    }

    public override async Task InterceptAsync(IAbpMethodInvocation invocation)
    {
        Validate(invocation);
        await invocation.ProceedAsync();
    }

    protected virtual void Validate(IAbpMethodInvocation invocation)
    {
        _methodInvocationValidator.Validate(
            new MethodInvocationValidationContext(
                invocation.TargetObject,
                invocation.Method,
                invocation.Arguments
            )
        );
    }
}

拦截器内部只会调用 IMethodInvocationValidator 对象提供的 Validate() 方法，在调用时会将方法的参数，方法类型等数据封装到 MethodInvocationValidationContext 。

这个上下文类型，本身就继承了前面提到的 AbpValidationResult 类型，在其内部增加了存储参数信息的属性。

public class MethodInvocationValidationContext : AbpValidationResult
{
    public object TargetObject { get; }

    // 方法的元数据信息。
    public MethodInfo Method { get; }

    // 方法的具体参数值。
    public object[] ParameterValues { get; }

    // 方法的参数信息。
    public ParameterInfo[] Parameters { get; }

    public MethodInvocationValidationContext(object targetObject, MethodInfo method, object[] parameterValues)
    {
        TargetObject = targetObject;
        Method = method;
        ParameterValues = parameterValues;
        Parameters = method.GetParameters();
    }
}

接下来我们看一下真正的 对象验证器 ，也就是 IMethodInvocationValidator 的默认实现 MethodInvocationValidator 当中具体的操作。

// ...
public virtual void Validate(MethodInvocationValidationContext context)
{
    // ...

    AddMethodParameterValidationErrors(context);

    if (context.Errors.Any())
    {
        ThrowValidationError(context);
    }
}

// ...

protected virtual void AddMethodParameterValidationErrors(MethodInvocationValidationContext context)
{
    // 循环调用 IObjectValidator 的 GetErrors 方法，捕获参数的具体错误。
    for (var i = 0; i < context.Parameters.Length; i++)
    {
        AddMethodParameterValidationErrors(context, context.Parameters[i], context.ParameterValues[i]);
    }
}

protected virtual void AddMethodParameterValidationErrors(IAbpValidationResult context, ParameterInfo parameterInfo, object parameterValue)
{
    var allowNulls = parameterInfo.IsOptional ||
                        parameterInfo.IsOut ||
                        TypeHelper.IsPrimitiveExtended(parameterInfo.ParameterType, includeEnums: true);

    // 添加错误信息到 Errors 里面，方便后面抛出。
    context.Errors.AddRange(
        _objectValidator.GetErrors(
            parameterValue,
            parameterInfo.Name,
            allowNulls
        )
    );
}

2.2.3 “真正”的参数验证器

我们看到，即便是在 IMethodInvocationValidator 内部，也没有真正地进行参数验证工作，而是调用了 IObjectValidator 进行对象验证处理，其接口定义如下：

public interface IObjectValidator
{
    void Validate(
        object validatingObject,
        string name = null,
        bool allowNull = false
    );

    List<ValidationResult> GetErrors(
        object validatingObject, // 待验证的值。
        string name = null,	// 参数的名字。
        bool allowNull = false	// 是否允许可空。
    );
}

它的默认实现代码如下：

public class ObjectValidator : IObjectValidator, ITransientDependency
{
    protected IHybridServiceScopeFactory ServiceScopeFactory { get; }
    protected AbpValidationOptions Options { get; }

    public ObjectValidator(IOptions<AbpValidationOptions> options, IHybridServiceScopeFactory serviceScopeFactory)
    {
        ServiceScopeFactory = serviceScopeFactory;
        Options = options.Value;
    }

    public virtual void Validate(object validatingObject, string name = null, bool allowNull = false)
    {
        var errors = GetErrors(validatingObject, name, allowNull);

        if (errors.Any())
        {
            throw new AbpValidationException(
                "Object state is not valid! See ValidationErrors for details.",
                errors
            );
        }
    }

    public virtual List<ValidationResult> GetErrors(object validatingObject, string name = null, bool allowNull = false)
    {
        // 如果待验证的值为空。
        if (validatingObject == null)
        {
            // 如果参数本身是允许可空的，那么直接返回。
            if (allowNull)
            {
                return new List<ValidationResult>(); //TODO: Returning an array would be more performent
            }
            else
            {
                // 否则在错误信息里面加入不能为空的错误。
                return new List<ValidationResult>
                {
                    name == null
                        ? new ValidationResult("Given object is null!")
                        : new ValidationResult(name + " is null!", new[] {name})
                };
            }
        }

        // 构造一个新的上下文，将其分派给辅助类进行验证。
        var context = new ObjectValidationContext(validatingObject);

        using (var scope = ServiceScopeFactory.CreateScope())
        {
            // 遍历之前模块启动的辅助类型。
            foreach (var contributorType in Options.ObjectValidationContributors)
            {
                // 通过 IoC 创建实例。
                var contributor = (IObjectValidationContributor) 
                    scope.ServiceProvider.GetRequiredService(contributorType);

                // 调用辅助类型进行具体认证。
                contributor.AddErrors(context);
            }
        }

        return context.Errors;
    }
}

所以我们的对象验证，还没有真正的进行验证处理，所有的验证操作都是由各个 验证辅助类型 处理的。而这些辅助类型有两种，第一是基于数据注解 的 验证辅助类型，第二种则是基于 FluentValidation 库编写的一种验证辅助类。

虽然 ABP vNext 套了三层，最终只是为了方便我们开发人员重写各个阶段的实现，也就更加地灵活可控。

2.2.4 默认的数据注解验证

ABP vNext 为了降低我们的学习成本，本身也是支持 ASP.NET Core MVC 那一套数据注解校验。你可以在某个非控制器类型的参数上，使用 [Required] 等数据注解特性。

它的默认实现我就不再多加赘述，基本就是通过反射得到参数对象上面的所有 ValidationAttribute 特性，显式地调用 GetValidationResult() 方法，获取到具体的错误信息，然后添加到上下文结果当中。

foreach (var attribute in validationAttributes)
{
    var result = attribute.GetValidationResult(property.GetValue(validatingObject), validationContext);
    if (result != null)
    {
        errors.Add(result);
    }
}

另外注意，这个递归验证的深度是 8 级，在辅助类型的 MaxRecursiveParameterValidationDepth 常量中进行了定义。也就是说，你这个对象图的逻辑层级不能超过 8 级。

public class A1
{
    [Required]
    public string Name { get; set;}
    
    public B2 B2 { get; set;}
}

public class B2
{
    [StringLength(8)]
    public string Name { get; set;}
}

如果你方法参数是 A1 类型的话，那么这就有 2 层了。

2.3 流畅验证库

回想上一节说的验证辅助类，还有一个基于 FluentValidation 库的类型，这里对于该库的使用方法参考单元测试即可。我这里只讲解一下，这个辅助类型是如何进行验证的。

public class FluentObjectValidationContributor : IObjectValidationContributor, ITransientDependency
{
    private readonly IServiceProvider _serviceProvider;

    public FluentObjectValidationContributor(
        IServiceProvider serviceProvider)
    {
        _serviceProvider = serviceProvider;
    }

    public void AddErrors(ObjectValidationContext context)
    {
        // 构造泛型类型，如果你对 Person 写了个验证器，那么验证器类型就是 IValidator<Person>。
        var serviceType = typeof(IValidator<>).MakeGenericType(context.ValidatingObject.GetType());
        // 通过 IoC 获得一个实例。
        var validator = _serviceProvider.GetService(serviceType) as IValidator;
        if (validator == null)
        {
            return;
        }

        // 调用验证器的方法进行验证。
        var result = validator.Validate(context.ValidatingObject);
        if (!result.IsValid)
        {
            // 获得错误数据，将 FluentValidation 的错误转换为标准的错误信息。
            context.Errors.AddRange(
                result.Errors.Select(
                    error =>
                        new ValidationResult(error.ErrorMessage)
                )
            );
        }
    }
}

单元测试当中的基本用法：

public class MyMethodInputValidator : AbstractValidator<MyMethodInput>
{
    public MyMethodInputValidator()
    {
        RuleFor(x => x.MyStringValue).Equal("aaa");
        RuleFor(x => x.MyMethodInput2.MyStringValue2).Equal("bbb");
        RuleFor(customer => customer.MyMethodInput3).SetValidator(new MyMethodInput3Validator());
    }
}

三、总结

总的来说 ABP vNext 为我们提供了多种参数验证方法，一般来说使用 MVC 过滤器配合数据注解就够了。如果你确实有一些特殊的需求，那也可以使用自己的方式对参数进行验证，只需要实现 IObjectValidationContributor 接口就行。

需要看其他的 ABP vNext 相关文章？点击我 即可跳转到总目录。

为什么要实现 IDisposable 接口?

Tue, 22 Oct 2019 01:59:50 +0000

一、背景

最近在精读《CLR Via C#》和《Effective C#》的时候，发现的一个问题点。一般来说，我们实现 IDisposable 接口，是为了释放托管资源和非托管资源。不过在 C# 类型定义里面有一个功能类似的东西，那就是 终结器。

最开始我是学 C++ 的，之后学 C# 的时候发现这玩意儿不论是写法和作用，都跟 C++ 里面的 析构函数 一样。在 C++ 里面的析构函数是在对象释放的时候会被调用，之后这个观点一直被我带到 C#，认为资源释放的动作放在终结器不就行了么。为什么还要我实现 IDisposable 接口，然后让使用者手动释放呢？

C++ 版本的析构函数：

class Line
{
   public:
      Line();  
      ~Line(); 
 
    private:
      double length;
};

C# 版本的终结器：

public class Line
{
    private double _length;
    
    public Line()
    {
        
    }
    
    ~Line()
    {
        
    }
}

二、原因

说起这个原因，首先得从 C# 终结器的 调用时机 说起。终结器的调用是 CLR 在进行 GC 时，如果某个对象写有终结器，即便它应该被释放，也不会马上回收该对象。而 C++ 的析构函数是确定性析构，取决于你调用 delete 的时机。

GC 会将其添加到一个队列当中，单独使用了一个 高优先级 线程去调用对象的终结器。因为要保证线程能够访问到终结器对象，所以本该释放的对象，以及对象相关的资源就 会被提升 1 代 ，会 增加内存占用。

一旦终结器方法带有死循环，那么 GC 将永远无法释放该资源，造成 内存泄漏。

除开内存占用增大的原因，如果你在终结器方法内部引用了其他带终结器对象，GC 无法保证终结器调用顺序，所以你可能访问到的对象是已经终结了的。

还有一种情况会导致尴尬的内存泄漏，本来对象 A 应该被释放了，结果你在终结器内部又让其他的根保持对象的引用，又会让这个对象复活。因为 GC 只会执行一次带终结器对象的终结器。执行一次过后，就再也不会执行对象的终结器了。

public class BadClass
{
    private static readonly List<BadClass> _list = new List<BadClass>();
    private string _msg;
    
    public BadClass(string msg)
    {
        _msg = (string)msg.Clone();
    }
    
    ~BadClass()
    {
        // 造成 _msg 的内存不会被释放。
        _list.Add(this);
    }
}

三、最佳实践

针对 Effective C# 所提出的最佳实践，你应该为对象实现 IDisposable 接口，以释放托管资源。如果你对象确实使用了非托管资源，那么你也应该为其编写终结器。因为非托管资源的，你不能保证调用者能够显示调用 Dispose() 方法，所以你得通过终结器来处理。

一个典型的 Dispose() 方法应该将托管资源、非托管资源全部进行释放，设置对应的标识表明对象已经被释放了，阻止垃圾回收器重复清理该对象、保证方法的 幂等性。

public class FatherClass : IDisposable
{
    private bool isDisposed = false;
    
    public void Dispose()
    {
        Dispose(true);
        // 通知 GC，这个对象已经完全被清理。
        GC.SuppressFinalize(this);
    }
    
    ~FatherClass()
    {
        Dispose(false);
    }
    
    protected virtual Dispose(bool isDisposing)
    {
        if(isDisposed) return;
        
        if(isDisposing)
        {
            // 释放托管资源。
        }
        
        // 释放非托管资源。
        isDisposed = true;
    }
    
    public void TestMethod()
    {
        if(isDisposed)
        {
            throw new ObjectDisposedException("对象已经被释放。");
        }
    }
}

public class ChildClass : FatherClass
{
    private bool isDisposed = false;
    
    protected override void Dispose(bool isDisposing)
    {
        if(isDisposed) return;
        
        if(isDisposing)
        {
            // 释放托管资源。
        }
        
        base.Dispose(isDisposing);
        
        isDisposed = true;
    }
}

在上面的实践中，我们提炼出了一个 void Dispose(bool) 方法，并将其设置为虚函数。这样做的好处有两点，第一点是方便子类重写释放逻辑，第二点是可以将终结器和 Dispose() 方法内部重复的代码提炼出来。

ABP vNext 不使用工作单元为什么会抛出异常

Tue, 15 Oct 2019 13:12:10 +0000

一、问题

该问题经常出现在 ABP vNext 框架当中，要复现该问题十分简单，只需要你注入一个 IRepository<T,TKey> 仓储，在任意一个地方调用 IRepository<T,TKey>.ToList() 方法。

[Fact]
public void TestMethod()
{
    var rep = GetRequiredService<IHospitalRepository>();

    var result = rep.ToList();
}

例如上面的测试代码，不出意外就会提示 System.ObjectDisposedException 异常，具体的异常内容信息：

System.ObjectDisposedException : Cannot access a disposed object. A common cause of this error is disposing a context that was resolved from dependency injection and then later trying to use the same context instance elsewhere in your application. This may occur if you are calling Dispose() on the context, or wrapping the context in a using statement. If you are using dependency injection, you should let the dependency injection container take care of disposing context instances.

其实已经说得十分明白了，因为你要调用的 DbContext 已经被释放了，所以会出现这个异常信息。

二、原因

2.1 为什么能够调用 LINQ 扩展?

我们之所以能够在 IRepository<TEntity,TKey> 接口上面，调用 LINQ 相关的流畅接口，是因为其父级接口 IReadOnlyRepository<TEntity,TKey> 继承了 IQueryable<TEntity> 接口。如果使用的是 Entity Framework Core 框架，那么在解析 IRepository<T,Key> 的时候，我们得到的是一个 EfCoreRepository<TDbContext, TEntity,TKey> 实例。

针对这个实例，类型 EfCoreRepository<TDbContext, TEntity> 则是它的基类型，继续跳转到其基类 RepositoryBase<TEntity> 我们就能看到它实现了 IQueryable<T> 接口必备的几个属性。

public abstract class RepositoryBase<TEntity> : BasicRepositoryBase<TEntity>, IRepository<TEntity>
    where TEntity : class, IEntity
{
    // ... 忽略的代码。
    public virtual Type ElementType => GetQueryable().ElementType;

    public virtual Expression Expression => GetQueryable().Expression;

    public virtual IQueryProvider Provider => GetQueryable().Provider;

    // ... 忽略的代码。

    IEnumerator IEnumerable.GetEnumerator()
    {
        return GetEnumerator();
    }

    public IEnumerator<TEntity> GetEnumerator()
    {
        return GetQueryable().GetEnumerator();
    }

    protected abstract IQueryable<TEntity> GetQueryable();

    // ... 忽略的代码。
}

2.2 IQueryable 使用的 DbContext

上一个小节的代码中，我们可以看出最后的 IQueryable<TEntity> 是通过抽象方法 GetQueryable() 取得的。这个抽象方法，在 EF Core 当中的实现如下。

public class EfCoreRepository<TDbContext, TEntity> : RepositoryBase<TEntity>, IEfCoreRepository<TEntity>
    where TDbContext : IEfCoreDbContext
    where TEntity : class, IEntity
{
    public virtual DbSet<TEntity> DbSet => DbContext.Set<TEntity>();

    DbContext IEfCoreRepository<TEntity>.DbContext => DbContext.As<DbContext>();

    protected virtual TDbContext DbContext => _dbContextProvider.GetDbContext();

    private readonly IDbContextProvider<TDbContext> _dbContextProvider;

    // ... 忽略的代码。

    public EfCoreRepository(IDbContextProvider<TDbContext> dbContextProvider)
    {
        _dbContextProvider = dbContextProvider;

        // ... 忽略的代码。
    }

    // ... 忽略的代码。

    protected override IQueryable<TEntity> GetQueryable()
    {
        return DbSet.AsQueryable();
    }

    // ... 忽略的代码。
}

所以我们就可以知道，当调用 IQueryable<TEntity>.ToList() 方法时，实际是使用的 IDbContextProvider<TDbContext> 解析出来的数据库上下文对象。

跳转到这个 DbContextProvider 的具体实现，可以看到他是通过 IUnitOfWorkManager(工作单元管理器) 得到可用的工作单元，然后通过工作单元提供的 IServiceProvider 解析所需要的数据库上下文对象。

public class UnitOfWorkDbContextProvider<TDbContext> : IDbContextProvider<TDbContext>
    where TDbContext : IEfCoreDbContext
{
    private readonly IUnitOfWorkManager _unitOfWorkManager;

    public UnitOfWorkDbContextProvider(
        IUnitOfWorkManager unitOfWorkManager)
    {
        _unitOfWorkManager = unitOfWorkManager;
    }

    // ... 上述代码有所精简。

    public TDbContext GetDbContext()
    {
        var unitOfWork = _unitOfWorkManager.Current;

        // ... 忽略部分代码。

        // 重点在 CreateDbContext() 方法内部。
        var databaseApi = unitOfWork.GetOrAddDatabaseApi(
            dbContextKey,
            () => new EfCoreDatabaseApi<TDbContext>(
                CreateDbContext(unitOfWork, connectionStringName, connectionString)
            ));

        return ((EfCoreDatabaseApi<TDbContext>)databaseApi).DbContext;
    }

    private TDbContext CreateDbContext(IUnitOfWork unitOfWork, string connectionStringName, string connectionString)
    {
        // ... 忽略部分代码。

        using (DbContextCreationContext.Use(creationContext))
        {
            var dbContext = CreateDbContext(unitOfWork);

            // ... 忽略部分代码。

            return dbContext;
        }
    }

    private TDbContext CreateDbContext(IUnitOfWork unitOfWork)
    {
        return unitOfWork.Options.IsTransactional
            ? CreateDbContextWithTransaction(unitOfWork)
            // 重点 ！！！
            : unitOfWork.ServiceProvider.GetRequiredService<TDbContext>();
    }

    public TDbContext CreateDbContextWithTransaction(IUnitOfWork unitOfWork) 
    {
        // ... 忽略部分代码。        
        if (activeTransaction == null)
        {
            // 重点 ！！！
            var dbContext = unitOfWork.ServiceProvider.GetRequiredService<TDbContext>();

            // ... 忽略部分代码。
            
            return dbContext;
        }
        else
        {
            // ... 忽略部分代码。
            // 重点 ！！！
            var dbContext = unitOfWork.ServiceProvider.GetRequiredService<TDbContext>();
            // ... 忽略部分代码。

            return dbContext;
        }
    }
}

2.3 DbContext 和工作单元的销毁

可以看到，仓储使用到的数据库上下文对象是通过工作单元的 IServiceProvider 进行解析的。回想之前关于工作单元的文章讲解，不论是手动开启工作单元，还是通过拦截器或者特性的方式开启，最终都是使用的 IUnitOfWorkManager.Begin() 进行构建的。

public class UnitOfWorkManager : IUnitOfWorkManager, ISingletonDependency
{
    // ... 省略的不相关的代码。

    private readonly IHybridServiceScopeFactory _serviceScopeFactory;

    // ... 省略的不相关的代码。

    public IUnitOfWork Begin(UnitOfWorkOptions options, bool requiresNew = false)
    {
        // ... 省略的不相关的代码。

        var unitOfWork = CreateNewUnitOfWork();

        // ... 省略的不相关的代码。

        return unitOfWork;
    }

    // ... 省略的不相关的代码。

    private IUnitOfWork CreateNewUnitOfWork()
    {
        var scope = _serviceScopeFactory.CreateScope();
        try
        {
            // ... 省略的不相关的代码。

            // 所以 IUnitOfWork 里面获得的 ServiceProvider 是一个子容器。
            var unitOfWork = scope.ServiceProvider.GetRequiredService<IUnitOfWork>();

            // ... 省略的不相关的代码。

            // 工作单元被释放的动作。
            unitOfWork.Disposed += (sender, args) =>
            {
                _ambientUnitOfWork.SetUnitOfWork(outerUow);

                // 子容器被释放时，通过子容器解析的 DbContext 也被释放了。
                scope.Dispose();
            };

            return unitOfWork;
        }
        catch
        {
            scope.Dispose();
            throw;
        }
    }
}

工作单元的 ServiceProvider 是通过继承 IServiceProviderAccessor 得到的，也就是说在构建工作单元的时候，这个 Provider 就是工作单元管理器创建的子容器。

那么回到之前的代码，我们得知 DbContext 是通过工作单元的 ServiceProvider 创建的，当工作单元被释放的时候，也会连带这个子容器被释放。那么我们之前解析出来的 DbContext ，也就会随着子容器的释放而被释放。如果要验证上述猜想，只需要编写类似代码即可。

[Fact]
public void TestMethod()
{
    using (var scope = GetRequiredService<IServiceProvider>().CreateScope())
    {
        var dbContext = scope.ServiceProvider.GetRequiredService<IHospitalDbContext>();
        scope.Dispose();
    }
}

既然如此，工作单元是什么时候被释放的呢…因为拦截器默认是为仓储建立了拦截器，所以在获得到 DbContext 的时候，拦截器已经将之前的 DbContext 释放掉了。

public override void Intercept(IAbpMethodInvocation invocation)
{
    if (!UnitOfWorkHelper.IsUnitOfWorkMethod(invocation.Method, out var unitOfWorkAttribute))
    {
        invocation.Proceed();
        return;
    }

    // 我在这里...
    using (var uow = _unitOfWorkManager.Begin(CreateOptions(invocation, unitOfWorkAttribute)))
    {
        invocation.Proceed();
        uow.Complete();
    }
}

要验证 DbContext 是随工作单元一起释放，也十分简单，编写以下代码即可进行测试。

[Fact]
public void TestMethod()
{
    var rep = GetRequiredService<IHospitalRepository>();
    var mgr = GetRequiredService<IUnitOfWorkManager>();

    using (var uow = mgr.Begin())
    {
        var count = rep.Count();
        uow.Dispose();
        uow.Complete();
    }
}

三、解决

解决方法很简单，在有类似操作的外部通过 [UnitOfWork] 特性或者 IUnitOfManager.Begin 开启一个新的工作单元即可。

[Fact]
public void TestMethod()
{
    var rep = GetRequiredService<IHospitalRepository>();
    var mgr = GetRequiredService<IUnitOfWorkManager>();

    using (var uow = mgr.Begin())
    {
        var count = rep.Count();
        uow.Complete();
    }
}

Abp vNext 源码分析 - 8. 审计日志

Tue, 08 Oct 2019 03:53:07 +0000

一、简要说明

ABP vNext 当中的审计模块早在 **依赖注入与拦截器**一文中有所提及，但没有详细的对其进行分析。

审计模块是 ABP vNext 框架的一个基本组件，它能够提供一些实用日志记录。不过这里的日志不是说系统日志，而是说接口每次调用之后的执行情况（执行时间、传入参数、异常信息、请求 IP）。

除了常规的日志功能以外，关于实体和聚合的审计字段接口也是存放在审计模块当中的。（创建人、创建时间、修改人、修改时间、删除人、删除时间）

二、源码分析

2.1. 审计日志拦截器

2.1.1 审计日志拦截器的注册

Volo.Abp.Auditing 的模块定义十分简单，主要是提供了 审计日志拦截器 的注册功能。下面代码即在组件注册的时候，会调用 AuditingInterceptorRegistrar.RegisterIfNeeded 方法来判定是否为实现类型(ImplementationType) 注入审计日志拦截器。

public class AbpAuditingModule : AbpModule
{
    public override void PreConfigureServices(ServiceConfigurationContext context)
    {
        context.Services.OnRegistred(AuditingInterceptorRegistrar.RegisterIfNeeded);
    }
}

跳转到具体的实现，可以看到内部会结合三种类型进行判断。分别是 AuditedAttribute 、IAuditingEnabled、DisableAuditingAttribute 。

前两个作用是，只要类型标注了 AuditedAttribute 特性，或者是实现了 IAuditingEnable 接口，都会为该类型注入审计日志拦截器。

而 DisableAuditingAttribute 类型则相反，只要类型上标注了该特性，就不会启用审计日志拦截器。某些接口需要 提升性能 的话，可以尝试使用该特性禁用掉审计日志功能。

public static class AuditingInterceptorRegistrar
{
    public static void RegisterIfNeeded(IOnServiceRegistredContext context)
    {
        // 满足条件时，将会为该类型注入审计日志拦截器。
        if (ShouldIntercept(context.ImplementationType))
        {
            context.Interceptors.TryAdd<AuditingInterceptor>();
        }
    }

    private static bool ShouldIntercept(Type type)
    {
        // 首先判断类型上面是否使用了辅助类型。
        if (ShouldAuditTypeByDefault(type))
        {
            return true;
        }

        // 如果任意方法上面标注了 AuditedAttribute 特性，则仍然为该类型注入拦截器。
        if (type.GetMethods().Any(m => m.IsDefined(typeof(AuditedAttribute), true)))
        {
            return true;
        }

        return false;
    }

    //TODO: Move to a better place
    public static bool ShouldAuditTypeByDefault(Type type)
    {
        // 下面就是根据三种辅助类型进行判断，是否为当前 type 注入审计日志拦截器。
        if (type.IsDefined(typeof(AuditedAttribute), true))
        {
            return true;
        }

        if (type.IsDefined(typeof(DisableAuditingAttribute), true))
        {
            return false;
        }

        if (typeof(IAuditingEnabled).IsAssignableFrom(type))
        {
            return true;
        }

        return false;
    }
}

2.1.2 审计日志拦截器的实现

审计日志拦截器的内部实现，主要使用了三个类型进行协同工作。它们分别是负责管理审计日志信息的 IAuditingManager，负责创建审计日志信息的 IAuditingHelper，还有统计接口执行时常的 Stopwatch 。

整个审计日志拦截器的大体流程如下：

首先是判定 MVC 审计日志过滤器是否进行处理。
再次根据特性，和类型进行二次验证是否应该创建审计日志信息。
根据调用信息，创建 AuditLogInfo 和 AuditLogActionInfo 审计日志信息。
调用 StopWatch 的计时方法，如果出现了异常则将异常信息添加到刚才构建的 AuditLogInfo 对象中。
无论是否出现异常，都会进入 finally 语句块，这个时候会调用 StopWatch 实例的停止方法，并统计完成执行时间。

public override async Task InterceptAsync(IAbpMethodInvocation invocation)
{
    if (!ShouldIntercept(invocation, out var auditLog, out var auditLogAction))
    {
        await invocation.ProceedAsync();
        return;
    }

    // 开始进行计时操作。
    var stopwatch = Stopwatch.StartNew();

    try
    {
        await invocation.ProceedAsync();
    }
    catch (Exception ex)
    {
        // 如果出现了异常，一样的将异常信息添加到审计日志结果中。
        auditLog.Exceptions.Add(ex);
        throw;
    }
    finally
    {
        // 统计完成，并将信息加入到审计日志结果中。
        stopwatch.Stop();
        auditLogAction.ExecutionDuration = Convert.ToInt32(stopwatch.Elapsed.TotalMilliseconds);
        auditLog.Actions.Add(auditLogAction);
    }
}

可以看到，只有当 ShouldIntercept() 方法返回 true 的时候，下面的统计等操作才会被执行。

protected virtual bool ShouldIntercept(
    IAbpMethodInvocation invocation, 
    out AuditLogInfo auditLog, 
    out AuditLogActionInfo auditLogAction)
{
    auditLog = null;
    auditLogAction = null;

    if (AbpCrossCuttingConcerns.IsApplied(invocation.TargetObject, AbpCrossCuttingConcerns.Auditing))
    {
        return false;
    }

    // 如果没有获取到 Scop，则返回 false。
    var auditLogScope = _auditingManager.Current;
    if (auditLogScope == null)
    {
        return false;
    }

    // 进行二次判断是否需要存储审计日志。
    if (!_auditingHelper.ShouldSaveAudit(invocation.Method))
    {
        return false;
    }

    // 构建审计日志信息。
    auditLog = auditLogScope.Log;
    auditLogAction = _auditingHelper.CreateAuditLogAction(
        auditLog,
        invocation.TargetObject.GetType(),
        invocation.Method, 
        invocation.Arguments
    );

    return true;
}

2.2 审计日志的持久化

大体流程和我们上面说的一样，不过好像缺少了重要的一步，那就是 持久化操作。你可以在 Volo.Abp.Auditing 模块发现有 IAuditingStore 接口的定义，但是它的 SaveAsync() 方法却没有在拦截器内部被调用。同样在 MVC 的审计日志过滤器实现，你也会发现没有调用持久化方法。

那么我们的审计日志是在什么时候被持久化的呢？找到 SaveAsync() 被调用的地方，发现 ABP vNext 实现了一个审计日志的 ASP.NET Core 中间件。

在这个中间件内部的实现比较简单，首先通过一个判定方法，决定是否为本次请求执行 IAuditingManager.BeginScope() 方法。如果判定通过，则执行，否则不仅行任何操作。

public async Task InvokeAsync(HttpContext context, RequestDelegate next)
{
    if (!ShouldWriteAuditLog(context))
    {
        await next(context);
        return;
    }

    using (var scope = _auditingManager.BeginScope())
    {
        try
        {
            await next(context);
        }
        finally
        {
            await scope.SaveAsync();
        }
    }
}

可以看到，在这里 ABP vNext 使用 IAuditingManager 构建，调用其 BeginScope() 构建了一个 IAuditLogSaveHandle 对象，并使用其提供的 SaveAsync() 方法进行持久化操作。

2.2.1 嵌套的持久化操作

在构造出来的 IAuditLogSaveHandle 对象里面，还是使用的 IAuditingManager 的默认实现 AuditingManager 所提供的 SaveAsync() 方法进行持久化。

阅读源码之后，发现了下面两个问题：

IAuditingManager 没有将持久化方法公开 出来，而是作为一个 protected 级别的方法。
为什么还要借助 IAuditLogSaveHandle 间接地调用 管理器的持久化方法。

这就要从中间件的代码说起了，可以看到它是构造出了一个可以被释放的 IAuditLogSaveHandle 对象。ABP vNext 这样做的目的，就是可以嵌套多个 Scope，即 只在某个范围内 才将审计日志记录下来。这种特性类似于 工作单元 的用法，其底层实现是 之前文章 讲过的 IAmbientScopeProvider 对象。

例如在某个应用服务内部，我可以这样写代码：

using (var scope = _auditingManager.BeginScope())
{
    await myAuditedObject1.DoItAsync(new InputObject { Value1 = "我是内部嵌套测试方法1。", Value2 = 5000 });
    using (var scope2 = _auditingManager.BeginScope())
    {
        await myAuditedObject1.DoItAsync(new InputObject {Value1 = "我是内部嵌套测试方法2。", Value2 = 10000});
        await scope2.SaveAsync();
    }
    await scope.SaveAsync();
}

想一下之前的代码，在拦截器内部，我们是通过 IAuditingManager.Current 拿到当前可用的 IAuditLogScope ，而这个 Scope 就是在调用 IAuditingManager.BeginScope() 之后生成的。

2.2.3 最终的持久化代码

通过上述的流程，我们得知最后的审计日志信息会通过 IAuditingStore 进行持久化。ABP vNext 为我们提供了一个默认的 SimpleLogAuditingStore 实现，其内部就是调用 ILogger 将信息输出。如果需要将审计日志持久化到数据库，你可以实现 IAUditingStore 接口，覆盖原有实现 ，或者使用 ABP vNext 提供的 Volo.Abp.AuditLogging 模块。

2.3 审计日志的序列化

审计日志的序列化处理是在 IAuditingHelper 的默认实现内部被使用，可以看到构建审计日志的方法内部，通过自定义的序列化器来将 Action 的参数进行序列化处理，方便存储。

public virtual AuditLogActionInfo CreateAuditLogAction(
    AuditLogInfo auditLog,
    Type type, 
    MethodInfo method, 
    IDictionary<string, object> arguments)
{
    var actionInfo = new AuditLogActionInfo
    {
        ServiceName = type != null
            ? type.FullName
            : "",
        MethodName = method.Name,
        // 序列化参数信息。
        Parameters = SerializeConvertArguments(arguments),
        ExecutionTime = Clock.Now
    };

    //TODO Execute contributors

    return actionInfo;
}

protected virtual string SerializeConvertArguments(IDictionary<string, object> arguments)
{
    try
    {
        if (arguments.IsNullOrEmpty())
        {
            return "{}";
        }

        var dictionary = new Dictionary<string, object>();

        foreach (var argument in arguments)
        {
            // 忽略的代码，主要作用是构建参数字典。
        }

        // 调用序列化器，序列化 Action 的调用参数。
        return AuditSerializer.Serialize(dictionary);
    }
    catch (Exception ex)
    {
        Logger.LogException(ex, LogLevel.Warning);
        return "{}";
    }
}

下面就是具体序列化器的代码：

public class JsonNetAuditSerializer : IAuditSerializer, ITransientDependency
{
    protected AbpAuditingOptions Options;

    public JsonNetAuditSerializer(IOptions<AbpAuditingOptions> options)
    {
        Options = options.Value;
    }

    public string Serialize(object obj)
    {
        // 使用 JSON.NET 进行序列化操作。
        return JsonConvert.SerializeObject(obj, GetSharedJsonSerializerSettings());
    }

    // ... 省略的代码。
}

2.4 审计日志的配置参数

针对审计日志相关的配置参数的定义，都存放在 AbpAuditingOptions 当中。下面我会针对各个参数的用途，对其进行详细的说明。

public class AbpAuditingOptions
{
    //TODO: Consider to add an option to disable auditing for application service methods?

    // 该参数目前版本暂未使用，为保留参数。
    public bool HideErrors { get; set; }

    // 是否启用审计日志功能，默认值为 true。
    public bool IsEnabled { get; set; }

    // 审计日志的应用程序名称，默认值为 null，主要在构建 AuditingInfo 被使用。
    public string ApplicationName { get; set; }

    // 是否为匿名请求记录审计日志默认值 true。
    public bool IsEnabledForAnonymousUsers { get; set; }

    // 审计日志功能的协作者集合，默认添加了 AspNetCoreAuditLogContributor 实现。
    public List<AuditLogContributor> Contributors { get; }

    // 默认的忽略类型，主要在序列化时使用。
    public List<Type> IgnoredTypes { get; }

    // 实体类型选择器。
    public IEntityHistorySelectorList EntityHistorySelectors { get; }

    //TODO: Move this to asp.net core layer or convert it to a more dynamic strategy?
    // 是否为 Get 请求记录审计日志，默认值 false。
    public bool IsEnabledForGetRequests { get; set; }

    public AbpAuditingOptions()
    {
        IsEnabled = true;
        IsEnabledForAnonymousUsers = true;
        HideErrors = true;

        Contributors = new List<AuditLogContributor>();

        IgnoredTypes = new List<Type>
        {
            typeof(Stream),
            typeof(Expression)
        };

        EntityHistorySelectors = new EntityHistorySelectorList();
    }
}

2.4 实体相关的审计信息

在文章开始就谈到，除了对 HTTP 请求有审计日志记录以外，ABP vNext 还提供了实体审计信息的记录功能。所谓的实体的审计信息，指的就是实体继承了 ABP vNext 提供的接口之后，ABP vNext 会自动维护实现的接口字段，不需要开发人员自己再进行处理。

这些接口包括创建实体操作的相关信息 IHasCreationTime、IMayHaveCreator、ICreationAuditedObject 以及删除实体时，需要记录的相关信息接口 IHasDeletionTime、IDeletionAuditedObject 等。除了审计日志模块定义的类型以外，在 Volo.Abp.Ddd.Domain 模块的 Auditing 里面也有很多审计实体的默认实现。

我在这里就不再一一列举，下面仅快速讲解一下 ABP vNext 是如何通过这些接口，实现对审计字段的自动维护的。

在审计日志模块的内部，我们看到一个接口名字叫做 IAuditPropertySetter，它提供了三个方法，分别是：

public interface IAuditPropertySetter
{
    void SetCreationProperties(object targetObject);

    void SetModificationProperties(object targetObject);

    void SetDeletionProperties(object targetObject);
}

所以，这几个方法就是用于设置创建信息、修改信息、删除信息的。现在跳转到默认实现 AuditPropertySetter，随便找一个 SetCreationTime() 方法。该方法内部首先是判断传入的 object 是否实现了 IHasCreationTime 接口，如果实现了对其进行强制类型转换，然后赋值即可。

private void SetCreationTime(object targetObject)
{
    if (!(targetObject is IHasCreationTime objectWithCreationTime))
    {
        return;
    }

    if (objectWithCreationTime.CreationTime == default)
    {
        objectWithCreationTime.CreationTime = Clock.Now;
    }
}

其他几个 Set 方法大同小异，那我们看一下有哪些地方使用到了上述三个方法。

可以看到使用者就包含有 EF Core 模块和 MongoDB 模块，这里我以 EF Core 模块为例，猜测应该是传入了实体对象过来。

果不其然…查看这个方法的调用链，发现是 DbContext 每次进行 SaveChanges/SaveChangesAsync 的时候，就会对实体进行审计字段自动赋值操作。

三、总结

审计日志是 ABP vNext 为我们提供的一个可选组件，当开启审计日志功能后，我们可以根据审计日志信息快速定位问题。但审计日志的开启，也会较大的影响性能，因为每次请求都会创建审计日志信息，之后再进行持久化。因此在使用审计日志功能时，可以结合 DisableAuditingAttribute 特性和 IAuditingManager.BeginScope()，按需开启审计日志功能。

Jenkins 结合 Docker 实现低配版的 CI&CD

Wed, 25 Sep 2019 04:42:11 +0000

随着项目的不断增多，最开始单体项目手动执行 docker build 命令，手动发布项目就不再适用了。一两个项目可能还吃得消，10 多个项目每天让你构建一次还是够呛。即便你的项目少，每次花费在发布上面的时间累计起来都够你改几个 BUG 了。

所以我们需要自动化这个流程，让项目的发布和测试不再这么繁琐。在这里我使用了 Jenkins 作为基础的 CI/CD Pipeline 工具，关于 Jenkins 的具体介绍这里就不再赘述。在版本管理、构建项目、单元测试、集成测试、环境部署我分别使用到了 Gogs、Docker、Docker Swarm(已与 Docker 整合) 这几个软件协同工作。

以下步骤我参考了 Continuous Integration with Jenkins and Docker 一文，并使用了作者提供的 groovy 文件和 slave.py 文件。

关于 Docker-CE 的安装，请参考我的另一篇博文《Linux 下的 Docker 安装与使用》。

一、Jenkins 的部署

既然都用了 Docker，我是不想在实体机上面安装一堆环境，所以我使用了 Docker 的形式来部署 Jenkins 的 Master 和 Slave，省时省力。Master 就是调度管道任务的主机，也是唯一有 UI 供用户操作的。而 Slave 就是具体的工作节点，用于执行具体的管道任务。

1.1 构建 Master 镜像

第一步，我们在主机上建立一个 master 文件夹，并使用 vi 创建两个 groovy 文件，这两个文件在后面的 Dockerfile 会被使用到，下面是 default-user.groovy 文件的代码：

import jenkins.model.*
import hudson.security.*

def env = System.getenv()

def jenkins = Jenkins.getInstance()
jenkins.setSecurityRealm(new HudsonPrivateSecurityRealm(false))
jenkins.setAuthorizationStrategy(new GlobalMatrixAuthorizationStrategy())

def user = jenkins.getSecurityRealm().createAccount(env.JENKINS_USER, env.JENKINS_PASS)
user.save()

jenkins.getAuthorizationStrategy().add(Jenkins.ADMINISTER, env.JENKINS_USER)
jenkins.save()

接着再用 vi 创建一个新的 executors.groovy 文件，并输入以下内容：

import jenkins.model.*
Jenkins.instance.setNumExecutors(0)

以上动作完成之后，在 master 文件夹下面应该有两个 groovy 文件。

两个 master 所需要的 groovy 文件已经编写完成，下面来编写 master 镜像的 Dockerfile 文件，每一步的作用我已经用中文进行了标注。

# 使用官方的 Jenkins 镜像作为基础镜像。
FROM jenkins/jenkins:latest
 
# 使用内置的 install-plugins.sh 来安装插件。
RUN /usr/local/bin/install-plugins.sh git matrix-auth workflow-aggregator docker-workflow blueocean credentials-binding
 
# 设置 Jenkins 的管理员账户和密码。
ENV JENKINS_USER admin
ENV JENKINS_PASS admin
 
# 跳过初始化安装向导。
ENV JAVA_OPTS -Djenkins.install.runSetupWizard=false
 
# 将刚刚编写的两个 groovy 脚本复制到初始化文件夹内。
COPY executors.groovy /usr/share/jenkins/ref/init.groovy.d/
COPY default-user.groovy /usr/share/jenkins/ref/init.groovy.d/

# 挂载 jenkins_home 目录到 Docker 卷。
VOLUME /var/jenkins_home

接着我们通过命令构建出 Master 镜像。

docker build -t jenkins-master .

1.2 构建 Slave 镜像

Slave 镜像的核心是一个 slave.py 的 python 脚本，它主要执行的动作是运行 slave.jar 并和 Master 建立通信，这样你的管道任务就能够交给 Slave 进行执行。这个脚本所做的工作流程如下：

st=>start: 脚本执行
stop=>end: 容器停止

op1=>operation: 导入 "jenkins" 的 python 模块
op2=>operation: 等待 Master 启动
cond1=>condition: Master 是否可用
op3=>operation: 下载 slave.jar 文件到容器内
op4=>operation: 通过 JLNP 连接到 Master 节点
op5=>operation: 使用凭据通过授权验证
op6=>operation: 成功运行 Slave

st->op1->op2->cond1
cond1(no)->op2
cond1(yes)->op3->op4->op5->op6->stop

我们再建立一个 slave 文件夹，并使用 vi 将 python 脚本复制进去。

slave.py 的内容：

from jenkins import Jenkins, JenkinsError, NodeLaunchMethod
import os
import signal
import sys
import urllib
import subprocess
import shutil
import requests
import time

slave_jar = '/var/lib/jenkins/slave.jar'
slave_name = os.environ['SLAVE_NAME'] if os.environ['SLAVE_NAME'] != '' else 'docker-slave-' + os.environ['HOSTNAME']
jnlp_url = os.environ['JENKINS_URL'] + '/computer/' + slave_name + '/slave-agent.jnlp'
slave_jar_url = os.environ['JENKINS_URL'] + '/jnlpJars/slave.jar'
print(slave_jar_url)
process = None

def clean_dir(dir):
    for root, dirs, files in os.walk(dir):
        for f in files:
            os.unlink(os.path.join(root, f))
        for d in dirs:
            shutil.rmtree(os.path.join(root, d))

def slave_create(node_name, working_dir, executors, labels):
    j = Jenkins(os.environ['JENKINS_URL'], os.environ['JENKINS_USER'], os.environ['JENKINS_PASS'])
    j.node_create(node_name, working_dir, num_executors = int(executors), labels = labels, launcher = NodeLaunchMethod.JNLP)

def slave_delete(node_name):
    j = Jenkins(os.environ['JENKINS_URL'], os.environ['JENKINS_USER'], os.environ['JENKINS_PASS'])
    j.node_delete(node_name)

def slave_download(target):
    if os.path.isfile(slave_jar):
        os.remove(slave_jar)

    loader = urllib.URLopener()
    loader.retrieve(os.environ['JENKINS_URL'] + '/jnlpJars/slave.jar', '/var/lib/jenkins/slave.jar')

def slave_run(slave_jar, jnlp_url):
    params = [ 'java', '-jar', slave_jar, '-jnlpUrl', jnlp_url ]
    if os.environ['JENKINS_SLAVE_ADDRESS'] != '':
        params.extend([ '-connectTo', os.environ['JENKINS_SLAVE_ADDRESS' ] ])

    if os.environ['SLAVE_SECRET'] == '':
        params.extend([ '-jnlpCredentials', os.environ['JENKINS_USER'] + ':' + os.environ['JENKINS_PASS'] ])
    else:
        params.extend([ '-secret', os.environ['SLAVE_SECRET'] ])
    return subprocess.Popen(params, stdout=subprocess.PIPE)

def signal_handler(sig, frame):
    if process != None:
        process.send_signal(signal.SIGINT)

signal.signal(signal.SIGINT, signal_handler)
signal.signal(signal.SIGTERM, signal_handler)

def master_ready(url):
    try:
        r = requests.head(url, verify=False, timeout=None)
        return r.status_code == requests.codes.ok
    except:
        return False

while not master_ready(slave_jar_url):
    print("Master not ready yet, sleeping for 10sec!")
    time.sleep(10)

slave_download(slave_jar)
print 'Downloaded Jenkins slave jar.'

if os.environ['SLAVE_WORING_DIR']:
    os.setcwd(os.environ['SLAVE_WORING_DIR'])

if os.environ['CLEAN_WORKING_DIR'] == 'true':
    clean_dir(os.getcwd())
    print "Cleaned up working directory."

if os.environ['SLAVE_NAME'] == '':
    slave_create(slave_name, os.getcwd(), os.environ['SLAVE_EXECUTORS'], os.environ['SLAVE_LABELS'])
    print 'Created temporary Jenkins slave.'

process = slave_run(slave_jar, jnlp_url)
print 'Started Jenkins slave with name "' + slave_name + '" and labels [' + os.environ['SLAVE_LABELS'] + '].'
process.wait()

print 'Jenkins slave stopped.'
if os.environ['SLAVE_NAME'] == '':
    slave_delete(slave_name)
    print 'Removed temporary Jenkins slave.'

上述脚本的工作基本与流程图的一致，因为 Jenkins 针对 Python 提供了 SDK ，所以原作者使用 Python 来编写的 “代理” 程序。不过 Jenkins 也有 RESTful API，你也可以使用 .NET Core 编写类似的 “代理” 程序。

接着我们来编写 Slave 镜像的 Dockerfile 文件，因为国内服务器访问 Ubuntu 的源很慢，经常因为超时导致构建失败，这里切换成了阿里云的源，其内容如下：

FROM ubuntu:16.04
 
# 安装 Docker CLI。
RUN sed -i s@/archive.ubuntu.com/@/mirrors.aliyun.com/@g /etc/apt/sources.list && apt-get clean
RUN apt-get update --fix-missing && apt-get install -y apt-transport-https ca-certificates curl openjdk-8-jre python python-pip git

# 使用阿里云的镜像源。
RUN curl -fsSL http://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | apt-key add -
RUN echo "deb [arch=amd64] http://mirrors.aliyun.com/docker-ce/linux/ubuntu xenial stable" > /etc/apt/sources.list.d/docker.list

RUN apt-get update --fix-missing && apt-get install -y docker-ce --allow-unauthenticated
RUN easy_install jenkins-webapi

# 安装 Docker-Compose 工具。
RUN curl -L https://github.com/docker/compose/releases/download/1.21.2/docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose && chmod +x /usr/local/bin/docker-compose
RUN mkdir -p /home/jenkins
RUN mkdir -p /var/lib/jenkins

# 将 slave.py 文件添加到容器。
ADD slave.py /var/lib/jenkins/slave.py

WORKDIR /home/jenkins

# 配置 Jenkins Master 的一些连接参数和 Slave 信息。
ENV JENKINS_URL "http://jenkins"
ENV JENKINS_SLAVE_ADDRESS ""
ENV JENKINS_USER "admin"
ENV JENKINS_PASS "admin"
ENV SLAVE_NAME ""
ENV SLAVE_SECRET ""
ENV SLAVE_EXECUTORS "1"
ENV SLAVE_LABELS "docker"
ENV SLAVE_WORING_DIR ""
ENV CLEAN_WORKING_DIR "true"
 
CMD [ "python", "-u", "/var/lib/jenkins/slave.py" ]

继续使用 docker build 构建 Slave 镜像：

docker build -t jenkins-slave .

1.3 编写 Docker Compose 文件

这里的 Docker Compose 文件，我取名叫 docker-compose.jenkins.yaml ，主要工作是为了启动 Master 和 Slave 容器。

version: '3.1'
services:
    jenkins:
        container_name: jenkins
        ports:
            - '8080:8080'
            - '50000:50000'
        image: jenkins-master
    jenkins-slave:
        container_name: jenkins-slave
        restart: always
        environment:
            - 'JENKINS_URL=http://jenkins:8080'
        image: jenkins-slave
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock  # 将宿主机的 Docker Daemon 挂载到容器内部。
            - /home/jenkins:/home/jenkins # 将数据挂载出来，方便后续进行释放。
        depends_on:
            - jenkins

执行 Docker Compose 之后，我们通过 宿主机 IP:8080 就可以访问到 Jenkins 内部了，如下图。

二、Gogs 的部署

我们内部开发使用的 Git 仓库是使用 Gogs 进行搭建的，Gogs 官方提供了 Docker 镜像，那我们可以直接编写一个 Docker Compose 快速部署 Gogs。

docker-compose.gogs.yaml 文件内容如下：

version: '3.1'
services:
  gogs:
    image: gogs/gogs
    container_name: 'gogs'
    expose:
      - '3000:3000'
    expose:
      - 22
    volumes:
      - /var/lib/docker/Persistence/Gogs:/data	# 挂载数据卷。
    restart: always

执行以下命令后，即可启动 Gogs 程序，访问 宿主机 IP:3000 按照配置说明安装 Gogs 即可，之后你就可以创建远程仓库了。

三、Gogs 与 Jenkins 的集成

虽然大部分都推荐 Jenkins 的 Gogs Webhook 插件，不过这个插件很久不更新了，而且不支持 版本发布 事件。针对于该问题虽然官方有 PR #62，但一直没有合并，等到合并的时候都是猴年马月了。这里还是建议使用 Generic Webhook Trigger ，用这个插件来触发 Jenkins 的管道任务。

3.1 创建流水线项目

首先找到 Jenkins 的插件中心，搜索 Generic Webhook Trigger 插件，并进行安装。

继续新建一个管道任务，取名叫做 TestProject，类型选择 Pipeline 。

首先配置项目的数据来源，选择 SCM，并且配置 Git 远程仓库的地址，如果是私有仓库则还需要设置用户名和密码。

3.2 Jenkins 的 Webhook 配置

流水线项目建立完成后，我们就可以开始设置 Generic WebHook Trigger 的一些参数，以便让远程的 Gogs 能够触发构建任务。

我们为 TestProject 创建一个 Token，这个 Token 是跟流水线任务绑定了，说白了就是流水线任务的一个标识。建议使用随机 Guid 作为 Token，不然其他人都可以随便触发你的流水线任务进行构建了。

3.3 Gogs 的 Webhook 配置

接着来到刚刚我们建好的仓库，找到 仓库设置->管理 Web 钩子->添加 Web 钩子->Gogs 。

因为触发构建不可能每次提交都触发，一般来说都是创建了某个合并请求，或者发布新版本的时候就会触发流水线任务。因此这里你可以根据自己的情况来选择触发事件，这里我以合并请求为例，你可以在钩子设置页面点击 测试推送。这样就可以看到 Gogs 发送给 Jenkins 的 JSON 结构是怎样的，你就能够在 Jenkins 那边有条件的进行处理。

不过测试推送只能够针对普通的 push 事件进行测试，像 合并请求 或者 版本发布 这种事件只能自己模拟操作了。在这里我新建了一个用户，Fork 了另一个帐号建立的 TestProject 仓库。

在 Fork 的仓库里面，我新建了一个 Readme.md 文件，然后点击创建合并，这个时候你看 Gogs 的 WebHook 推送记录就有一条新的数据推送给 Jenkins，同时你也可以在 Jenkins 看到流水线任务被触发了。

3.4 限定任务触发条件

通过上面的步骤，我们已经将 Gogs 和 Jenkins 中的具体任务进行了绑定。不过还有一个比较尴尬的问题是，Gogs 的合并事件不仅仅包括创建合并，它的原始描述是这样说的。

合并请求事件包括合并被开启、关闭、重新开启、编辑、指派、取消指派、更新标签、清除标签、设置里程碑、取消设置里程碑或代码同步。

如果我们仅仅是依靠上面的配置，那么上述所有行为都会触发构建操作，这肯定不是我们想要的效果。还好 Generic Webhook 为我们提供了变量获取，以及 Webhook 过滤。

我们从 Gogs 发往 Jenkins 的请求中可以看到，在 JSON 内部包含了一个 action 字段，里面就是本次的操作标识。那么我们就可以想到通过判断 action 字段是否等于 opened 来触发流水线任务。

首先，我们增加 4 个 Post content parameters 参数，分别获取到 Gogs 传递过来的 action 和 PR 的 Id，这里我解释一下几个文本框的意思。

除了这两个 Post 参数以外，在请求头中，Gogs 还携带了具体事件，我们将其一起作为过滤条件。需要注意的是，针对于请求头的参数，在转换成变量时，插件会将字符转为小写，并会使用 ‘_’ 代替 ‘-’。

最后我们编写一个 Optional filter ，它的 Expression 参数是正则表达式，下面的 Text 即是源字符串。实现很简单，当 Text 里面的内容满足正则表达式的时候，就会触发流水线任务。

所以我们的 Text 字符串就是由上面三个变量的值组成，然后和我们预期的值进行匹配即可。

当然，你还想整一些更加炫酷的功能，可以使用 Jenkins 提供的 Http Request 之类的插件。因为 Gogs 提供了 API 接口，你就可以在构建完成之后，回写给 Gogs，用于提示构建结果。

这样的话，这种功能就有点像 Github 上面的机器人帐号了。

四、完整的项目示例

在上一节我们通过 Jenkins 的插件完成了远程仓库推送通知，当我们合并代码时，Jenkins 会自动触发执行我们的管道任务。接下来我将建立一个 .NET Core 项目，该项目拥有一个 Controller，接收到请求之后输出 “Hello World”。随后为该项目建立一个 xUnit 的测试项目，用于执行单元测试。

整个项目的结构如下图：

我们需要编写一个 UnitTest.Dockerfile 镜像，用于执行 xUnit 单元测试。

FROM mcr.microsoft.com/dotnet/core/sdk:2.2

# 还原 NuGet 包。
WORKDIR /home/app
COPY ./ ./
RUN dotnet restore

ENTRYPOINT ["dotnet", "test" , "--verbosity=normal"]

之后为部署操作编写一个 Deploy.Dockerfile ，这个 Dockerfile 首先还原了 NuGet 包，然后通过 dotnet publish 命令发布了我们的网站。

FROM mcr.microsoft.com/dotnet/core/sdk:2.2 as build-image

# 还原 NuGet 包。
WORKDIR /home/app
COPY ./ ./
RUN dotnet restore

# 发布镜像。
COPY ./ ./
RUN dotnet publish ./TestProject.WebApi/TestProject.WebApi.csproj -o /publish/

FROM mcr.microsoft.com/dotnet/core/aspnet:2.2
WORKDIR /publish
COPY --from=build-image /publish .

ENTRYPOINT ["dotnet", "TestProject.WebApi.dll"]

两个 Dockerfile 编写完成之后，将其存放在项目的根目录，以便 Slave 进行构建。

Dockerfile 编写好了，那么我们还要分别为两个镜像编写 Docker Compose 文件，用于执行单元测试和部署行为，用于部署的文件名称叫做 docker-compose.Deploy.yaml，内容如下：

version: '3.1'

services:
  backend:
    container_name: dev-test-backend
    image: dev-test:B${BUILD_NUMBER}
    ports: 
      - '5000:5000'
    restart: always

然后我们需要编写运行单元测试的 Docker Compose 文件，名字叫做 docker-compose.UnitTest.yaml，内容如下：

version: '3.1'

services:
  backend:
    container_name: dev-test-unit-test
    image: dev-test:TEST${BUILD_NUMBER}

五、编写 Jenkinsfile

node('docker') {
 
    stage '签出代码'
        checkout scm
    stage '单元测试'
        sh "docker build -t dev-test:TEST${BUILD_NUMBER} -f UnitTest.Dockerfile ."
        sh "docker-compose -f docker-compose.UnitTest.yaml up --force-recreate --abort-on-container-exit"
        sh "docker-compose -f docker-compose.UnitTest.yaml down -v"
    stage '部署项目'
        sh "docker build -t dev-test:B${BUILD_NUMBER} -f Deploy.Dockerfile ."
        sh 'docker-compose -f docker-compose.Deploy.yaml up -d'
}

六、最后的效果

上述操作完成之后，将这些文件放在项目根目录。

回到 Jenkins，你可以手动执行一下任务，然后项目就被成功执行了。

至此，我们的 “低配版” CI、CD 环境就搭建成功了。

在 ABP vNext 中编写仓储单元测试的问题一则

Wed, 18 Sep 2019 02:54:17 +0000

一、问题

新项目是基于 ABP vNext 框架进行开发的，所以我要求为每层编写单元测试。在同事为某个仓储编写单元测试的时候，发现了一个奇怪的问题。他的对某个聚合根的 A 字段进行了更新，随后对某个导航属性 B 也进行了变更，最后通过仓储提供的 UpdateAsync() 方法对变更的数据进行持久化。

结果再次查出来的时候，发现聚合根的 A 字段倒是更新了，但是导航属性 B 的内部字段没有进行变更。例如在下面的实例当中，聚合根的 Name 字段变更成功，但是导航属性的 Street 字段变更失败了。

二、原因

数据没有更新到，说明问题肯定出在 UpdateAsync 方法内部，通过打断点单步步入之后，也没发现有什么奇怪的地方，是使用的 ABP vNext 提供的默认仓储实现。

又在想是否跟实体追踪有关，然后看同事写得单元测试代码，发现他是先使用的 GetAsync() 方法获取到实体，然后手动变更了实体的属性。变更完成之后，通过仓储提供的 UpdateAsync() 方法进行更新。

看了很久发现它们并不是公用的一个工作单元，这就导致 GetAsync() 和 UpdateAsync() 方法内部得到的 DbContext 是不一样的。在 EF Core 内部针对这种情况，称之为 Disconnected entities 即断开连接的实体，这个时候需要用户手动 Attch 追踪导航属性。

三、解决

所以有两种解决办法，第一种方法是保证使用 GetAsync() 和 UpdateAsync() 方法时，它们都处于一个工作单元下，例如下面的伪代码。

private readonly IUnitOfWorkManager _uowMgr;
private readonly IRepository<TestUser, Guid> _repository;

[Fact]
public async Task Resolve1()
{
    // 创建初始数据。
    var entityId = Guid.NewGuid();
    await _repository.InsertAsync(new TestUser
    {
        Id = entityId,
        Name = "张三",
        Address = new TestUserAddress
        {
            City = "成都市",
            Street = "春熙路"
        }
    });

    using (var outerUow = _uowMgr.Begin())
    {
        var entity = await _repository.GetAsync(entityId);
        entity.Name = "李四";
        entity.Address.Street = "琴台路";

        await _repository.UpdateAsync(entity);
        await outerUow.CompleteAsync();
    }
    
    // 最后查询街道是否成功修改。
    var result = await _repository.GetAsync(entityId);
    result.Name.ShouldBe("李四");
    result.Address.Street.ShouldBe("琴台路");
}

第二种方法变动则要大一些，导航属性没有更新的根本原因，是因为在第二个工作单元中没有追踪到这个属性，你只需要手动附加该导航属性即可。在下面的例子中，我们重写了 UpdateAsync() 方法，手动跟踪导航属性，也能够达到上述效果。

public class TestUserRepository : EfCoreRepository<XXXDbContext,TestUser,Guid>
{
    public TestUserRepository(IDbContextProvider<XXXDbContext> dbContextProvider) : base(dbContextProvider)
    {
    }

    public override IQueryable<TestUser> WithDetails()
    {
        return GetQueryable().Include(x => x.Address);
    }

    public override Task<TestUser> UpdateAsync(TestUser entity, bool autoSave = false, CancellationToken cancellationToken = new CancellationToken())
    {
        DbContext.Attach(entity.Address).State = EntityState.Modified;
        return base.UpdateAsync(entity, autoSave, cancellationToken);
    }
}

四、参考资料

CentOS 7.x 安装 ZSH 终端

Mon, 26 Aug 2019 11:46:52 +0000

一、安装基本组件

首先执行 yum 命令来安装需要的 zsh 原始程序与 git 程序来 pull 代码。
```
yum install -y zsh git
```

安装 oh my zsh 脚本 (这一步需要安装 git)。

wget https://github.com/robbyrussell/oh-my-zsh/raw/master/tools/install.sh -O - | sh

使用 which zsh 查看 zsh 的安装目录，一般都存储在 /usr/bin/zsh 目录下。
```
which zsh
```
使用 chsh 命令切换使用的 shell 程序。
```
chsh -s /usr/bin/zsh
```

二、进行可选配置

2.1 安装 ZSH 图标字体

执行以下命令在当前目录拉取图标的仓库，并切换到其目录下，执行 ./install.sh 脚本即可安装成功。

git clone https://github.com/powerline/fonts.git

2.2 更换 ZSH 主题

使用 vi 工具编辑 /root/.zshrc 文件，更改 ZSH_THEME="robbyussell" 字段为 ZSH_THEME="agnoster" 字段，并通过 source ~/.zshrc 命令更新它们的配置文件。

2.3 安装插件

使用 ZSH 替换原有的 SHELL 最主要的原因就是要使用其功能强大的插件，这里只推荐安装三个插件，它们分别是 wd、zsh-syntax-highlighting、zsh-autosuggestions 。

首先依次执行下列的命令，将后面两个插件的仓库克隆到 Oh My Zsh 的插件目录下。

cd ~/.oh-my-zsh/custom/plugins
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git
git clone https://github.com/zsh-users/zsh-autosuggestions.git

完成克隆操作之后，那么两个插件的全路径分别是：

/root/.oh-my-zsh/custom/plugins/zsh-autosuggestions/zsh-syntax-highlighting.zsh
/root/.oh-my-zsh/custom/plugins/zsh-autosuggestions/zsh-autosuggestions.zsh

继续使用 vi 编辑 ~/.zshrc 文件。

# 其他内容
plugins=(
  git
  wd
  zsh-syntax-highlighting
  zsh-autosuggestions
)

source /root/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
source /root/.oh-my-zsh/custom/plugins/zsh-autosuggestions/zsh-autosuggestions.zsh
source $ZSH/oh-my-zsh.sh
# 其他内容

编辑完成之后，执行 source ~/.zshrc 命令更新 ZSH 配置，最后的效果如下图。

Abp vNext 源码分析 - 7. 权限与验证

Sat, 10 Aug 2019 12:36:14 +0000

一、简要说明

在上篇文章里面，我们在 ApplicationService 当中看到了权限检测代码，通过注入 IAuthorizationService 就可以实现权限检测。不过跳转到源码才发现，这个接口是 ASP.NET Core 原生提供的 “基于策略” 的权限验证接口，这就说明 ABP vNext 基于原生的授权验证框架进行了自定义扩展。

让我们来看一下 Volo.Abp.Ddd.Application 项目的依赖结构(权限相关)。

本篇文章下面的内容基本就会围绕上述框架模块展开，本篇文章通篇较长，因为还涉及到 .NET Core Identity 与 IdentityServer4 这两部分。关于这两部分的内容，我会在本篇文章大概讲述 ABP vNext 的实现，关于更加详细的内容，请查阅官方文档或其他博主的博客。

二、源码分析

ABP vNext 关于权限验证和权限定义的部分，都存放在 Volo.Abp.Authorization 和 Volo.Abp.Security 模块内部。源码分析我都比较喜欢倒推，即通过实际的使用场景，反向推导 基础实现，所以后面文章编写的顺序也将会以这种方式进行。

2.1 Security 基础组件库

这里我们先来到 Volo.Abp.Security，因为这个模块代码和类型都是最少的。这个项目都没有模块定义，说明里面的东西都是定义的一些基础组件。

2.1.1 Claims 与 Identity 的快捷访问

先从第一个扩展方法开始，这个扩展方法里面比较简单，它主要是提供对 ClaimsPrincipal 和 IIdentity 的快捷访问方法。比如我要从 ClaimsPrincipal / IIdentity 获取租户 Id、用户 Id 等。

public static class AbpClaimsIdentityExtensions
{
	public static Guid? FindUserId([NotNull] this ClaimsPrincipal principal)
	{
		Check.NotNull(principal, nameof(principal));

        // 根据 AbpClaimTypes.UserId 查找对应的值。
		var userIdOrNull = principal.Claims?.FirstOrDefault(c => c.Type == AbpClaimTypes.UserId);
		if (userIdOrNull == null || userIdOrNull.Value.IsNullOrWhiteSpace())
		{
			return null;
		}

        // 返回 Guid 对象。
		return Guid.Parse(userIdOrNull.Value);
	}

2.1.2 未授权异常的定义

这个异常我们在老版本 ABP 里面也见到过，它就是 AbpAuthorizationException 。只要有任何未授权的操作，都会导致该异常被抛出。后面我们在讲解 ASP.NET Core MVC 的时候就会知道，在默认的错误码处理中，针对于程序抛出的 AbpAuthorizationException ，都会视为 403 或者 401 错误。

public class DefaultHttpExceptionStatusCodeFinder : IHttpExceptionStatusCodeFinder, ITransientDependency
{
	// ... 其他代码
	
	public virtual HttpStatusCode GetStatusCode(HttpContext httpContext, Exception exception)
	{
		// ... 其他代码
		
		// 根据 HTTP 协议对于状态码的定义，401 表示的是没有登录的用于尝试访问受保护的资源。而 403 则表示用户已经登录，但他没有目标资源的访问权限。
		if (exception is AbpAuthorizationException)
		{
			return httpContext.User.Identity.IsAuthenticated
				? HttpStatusCode.Forbidden
				: HttpStatusCode.Unauthorized;
		}
		
		// ... 其他代码
	}
	
	// ... 其他代码
}

就 AbpAuthorizationException 异常来说，它本身并不复杂，只是一个简单的异常而已。只是因为它的特殊含义，在 ABP vNext 处理异常时都会进行特殊处理。

只是在这里我说明一下，ABP vNext 将它所有的异常都设置为可序列化的，这里的可序列化不仅仅是将 Serialzable 标签打在类上就行了。ABP vNext 还创建了基于 StreamingContext 的构造函数，方便我们后续对序列化操作进行定制化处理。

关于运行时序列化的相关文章，可以参考《CLR Via C#》第 24 章，我也编写了相应的 读书笔记 。

2.1.3 当前用户与客户端

开发人员经常会在各种地方需要获取当前的用户信息，ABP vNext 将当前用户封装到 ICurrentUser 与其实现 CurrentUser 当中，使用时只需要注入 ICurrentUser 接口即可。

我们首先康康 ICurrentUser 接口的定义：

public interface ICurrentUser
{
	bool IsAuthenticated { get; }

	[CanBeNull]
	Guid? Id { get; }

	[CanBeNull]
	string UserName { get; }

	[CanBeNull]
	string PhoneNumber { get; }
	
	bool PhoneNumberVerified { get; }

	[CanBeNull]
	string Email { get; }

	bool EmailVerified { get; }

	Guid? TenantId { get; }

	[NotNull]
	string[] Roles { get; }

	[CanBeNull]
	Claim FindClaim(string claimType);

	[NotNull]
	Claim[] FindClaims(string claimType);

	[NotNull]
	Claim[] GetAllClaims();

	bool IsInRole(string roleName);
}

那么这些值是从哪儿来的呢？从带有 Claim 返回值的方法来看，肯定就是从 HttpContext.User 或者 Thread.CurrentPrincipal 里面拿到的。

那么它的实现就非常简单了，只需要注入 ABP vNext 为我们提供的 ICurrentPrincipalAccessor 访问器，我们就能够拿到这个身份容器(ClaimsPrincipal)。

public class CurrentUser : ICurrentUser, ITransientDependency
{
	// ... 其他代码

	public virtual string[] Roles => FindClaims(AbpClaimTypes.Role).Select(c => c.Value).ToArray();

	private readonly ICurrentPrincipalAccessor _principalAccessor;
	
	public CurrentUser(ICurrentPrincipalAccessor principalAccessor)
	{
		_principalAccessor = principalAccessor;
	}
	
	// ... 其他代码
	
	public virtual Claim[] FindClaims(string claimType)
	{
		// 直接使用 LINQ 查询对应的 Type 就能拿到上述信息。
		return _principalAccessor.Principal?.Claims.Where(c => c.Type == claimType).ToArray() ?? EmptyClaimsArray;
	}
	
	// ... 其他代码
}

至于 CurrentUserExtensions 扩展类，里面只是对 ClaimsPrincipal 的搜索方法进行了多种封装而已。

PS：

除了 ICurrentUser 与 ICurrentClient 之外，在 ABP vNext 里面还有 ICurrentTenant 来获取当前租户信息。通过这三个组件，取代了老 ABP 框架的 IAbpSession 组件，三个组件都没有 IAbpSession.Use() 扩展方法帮助我们临时更改当前用户/租户。

2.1.4 ClaimsPrincipal 访问器

关于 ClaimsPrincipal 的内容，可以参考杨总的 《ASP.NET Core 之 Identity 入门》 进行了解，大致来说就是存有 Claim 信息的聚合对象。

关于 ABP vNext 框架预定义的 Claim Type 都存放在 AbpClaimTypes 类型里面的，包括租户 Id、用户 Id 等数据，这些玩意儿最终会被放在 JWT(JSON Web Token) 里面去。

一般来说 ClaimsPrincipal 里面都是从 HttpContext.User 或者 Thread.CurrentPrincipal 得到的，ABP vNext 为我们抽象出了一个快速访问接口 ICurrentPrincipalAccessor。开发人员注入之后，就可以获得当前用户的 ClaimsPrincipal 对象。

public interface ICurrentPrincipalAccessor
{
	ClaimsPrincipal Principal { get; }
}

对于 Thread.CurrentPrincipal 的实现：

public class ThreadCurrentPrincipalAccessor : ICurrentPrincipalAccessor, ISingletonDependency
{
	public virtual ClaimsPrincipal Principal => Thread.CurrentPrincipal as ClaimsPrincipal;
}

而针对于 Http 上下文的实现，则是放在 Volo.Abp.AspNetCore 模块里面的。

public class HttpContextCurrentPrincipalAccessor : ThreadCurrentPrincipalAccessor
{
	// 如果没有获取到数据，则使用 Thread.CurrentPrincipal。
	public override ClaimsPrincipal Principal => _httpContextAccessor.HttpContext?.User ?? base.Principal;

	private readonly IHttpContextAccessor _httpContextAccessor;

	public HttpContextCurrentPrincipalAccessor(IHttpContextAccessor httpContextAccessor)
	{
		_httpContextAccessor = httpContextAccessor;
	}
}

扩展知识：两者的区别？

Thread.CurrentPrincipal 可以设置/获得当前线程的 ClaimsPrincipal 数据，而 HttpContext?.User 一般都是被 ASP.NET Core 中间件所填充的。

最新的 ASP.NET Core 开发建议是不要使用 Thread.CurrentPrincipal 和 ClaimsPrincipal.Current (内部实现还是使用的前者)。这是因为 Thread.CurrentPrincipal 是一个静态成员…而这个静态成员在异步代码中会出现各种问题，例如有以下代码：

// Create a ClaimsPrincipal and set Thread.CurrentPrincipal
var identity = new ClaimsIdentity();
identity.AddClaim(new Claim(ClaimTypes.Name, "User1"));
Thread.CurrentPrincipal = new ClaimsPrincipal(identity);

// Check the current user
Console.WriteLine($"Current user: {Thread.CurrentPrincipal?.Identity.Name}");

// For the method to complete asynchronously
await Task.Yield();

// Check the current user after
Console.WriteLine($"Current user: {Thread.CurrentPrincipal?.Identity.Name}");

当 await 执行完成之后会产生线程切换，这个时候 Thread.CurrentPrincipal 的值就是 null 了，这就会产生不可预料的后果。

如果你还想了解更多信息，可以参考以下两篇博文：

DAVID PINE - 《WHAT HAPPENED TO MY THREAD.CURRENTPRINCIPAL》
SCOTT HANSELMAN - 《System.Threading.Thread.CurrentPrincipal vs. System.Web.HttpContext.Current.User or why FormsAuthentication can be subtle》

2.1.5 字符串加密工具

这一套东西就比较简单了，是 ABP vNext 为我们提供的一套开箱即用组件。开发人员可以使用 IStringEncryptionService 来加密/解密你的字符串，默认实现是基于 Rfc2898DeriveBytes 的。关于详细信息，你可以阅读具体的代码，这里不再赘述。

2.2 权限与校验

在 Volo.Abp.Authorization 模块里面就对权限进行了具体定义，并且基于 ASP.NET Core Authentication 进行无缝集成。如果读者对于 ASP.NET Core 认证和授权不太了解，可以去学习一下 雨夜朦胧 大神的**《ASP.NET Core 认证于授权》**系列文章，这里就不再赘述。

2.2.1 权限的注册

在 ABP vNext 框架里面，所有用户定义的权限都是通过继承 PermissionDefinitionProvider，在其内部进行注册的。

public abstract class PermissionDefinitionProvider : IPermissionDefinitionProvider, ITransientDependency
{
    public abstract void Define(IPermissionDefinitionContext context);
}

开发人员继承了这个 Provider 之后，在 Define() 方法里面就可以注册自己的权限了，这里我以 Blog 模块的简化 Provider 为例。

public class BloggingPermissionDefinitionProvider : PermissionDefinitionProvider
{
    public override void Define(IPermissionDefinitionContext context)
    {
        var bloggingGroup = context.AddGroup(BloggingPermissions.GroupName, L("Permission:Blogging"));

				// ... 其他代码。
				
        var tags = bloggingGroup.AddPermission(BloggingPermissions.Tags.Default, L("Permission:Tags"));
        tags.AddChild(BloggingPermissions.Tags.Update, L("Permission:Edit"));
        tags.AddChild(BloggingPermissions.Tags.Delete, L("Permission:Delete"));
        tags.AddChild(BloggingPermissions.Tags.Create, L("Permission:Create"));

        var comments = bloggingGroup.AddPermission(BloggingPermissions.Comments.Default, L("Permission:Comments"));
        comments.AddChild(BloggingPermissions.Comments.Update, L("Permission:Edit"));
        comments.AddChild(BloggingPermissions.Comments.Delete, L("Permission:Delete"));
        comments.AddChild(BloggingPermissions.Comments.Create, L("Permission:Create"));
    }

		// 使用本地化字符串进行文本显示。
    private static LocalizableString L(string name)
    {
        return LocalizableString.Create<BloggingResource>(name);
    }
}

从上面的代码就可以看出来，权限被 ABP vNext 分成了 权限组定义 和 权限定义，这两个东西我们后面进行重点讲述。那么这些 Provider 在什么时候被执行呢？找到权限模块的定义，可以看到如下代码：

[DependsOn(
    typeof(AbpSecurityModule),
    typeof(AbpLocalizationAbstractionsModule),
    typeof(AbpMultiTenancyModule)
    )]
public class AbpAuthorizationModule : AbpModule
{
    public override void PreConfigureServices(ServiceConfigurationContext context)
    {
        // 在 AutoFac 进行组件注册的时候，根据组件的类型定义视情况绑定拦截器。
        context.Services.OnRegistred(AuthorizationInterceptorRegistrar.RegisterIfNeeded);

        // 在 AutoFac 进行组件注册的时候，根据组件的类型，判断是否是 Provider。
        AutoAddDefinitionProviders(context.Services);
    }

    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        // 注册认证授权服务。
        context.Services.AddAuthorization();

        // 替换掉 ASP.NET Core 提供的权限处理器，转而使用 ABP vNext 提供的权限处理器。
        context.Services.AddSingleton<IAuthorizationHandler, PermissionRequirementHandler>();

        // 这一部分是添加内置的一些权限值检查，后面我们在将 PermissionChecker 的时候会提到。
        Configure<PermissionOptions>(options =>
        {
            options.ValueProviders.Add<UserPermissionValueProvider>();
            options.ValueProviders.Add<RolePermissionValueProvider>();
            options.ValueProviders.Add<ClientPermissionValueProvider>();
        });
    }

    private static void AutoAddDefinitionProviders(IServiceCollection services)
    {
        var definitionProviders = new List<Type>();

        services.OnRegistred(context =>
        {
            if (typeof(IPermissionDefinitionProvider).IsAssignableFrom(context.ImplementationType))
            {
                definitionProviders.Add(context.ImplementationType);
            }
        });

        // 将获取到的 Provider 传递给 PermissionOptions 。
        services.Configure<PermissionOptions>(options =>
        {
            options.DefinitionProviders.AddIfNotContains(definitionProviders);
        });
    }
}

可以看到在注册组件的时候，ABP vNext 就会将这些 Provider 传递给 PermissionOptions ，我们根据 DefinitionProviders 字段找到有一个地方会使用到它，就是 PermissionDefinitionManager 类型的 CreatePermissionGroupDefinitions() 方法。

protected virtual Dictionary<string, PermissionGroupDefinition> CreatePermissionGroupDefinitions()
{
    //  创建一个权限定义上下文。
    var context = new PermissionDefinitionContext();

    // 创建一个临时范围用于解析 Provider，Provider 解析完成之后即被释放。
    using (var scope = _serviceProvider.CreateScope())
    {
        // 根据之前的类型，通过 IoC 进行解析出实例，指定各个 Provider 的 Define() 方法，会向权限上下文填充权限。
        var providers = Options
            .DefinitionProviders
            .Select(p => scope.ServiceProvider.GetRequiredService(p) as IPermissionDefinitionProvider)
            .ToList();

        foreach (var provider in providers)
        {
            provider.Define(context);
        }
    }

    // 返回权限组名称 - 权限组定义的字典。
    return context.Groups;
}

你可能会奇怪，为什么返回的是一个权限组名字和定义的键值对，而不是返回的权限数据，我们之前添加的权限去哪儿了呢？

2.2.2 权限和权限组的定义

要搞清楚这个问题，我们首先要知道权限与权限组之间的关系是怎样的。回想我们之前在 Provider 里面添加权限的代码，首先我们是构建了一个权限组，然后往权限组里面添加的权限。权限组的作用就是将权限按照组的形式进行划分，方便代码进行访问于管理。

public class PermissionGroupDefinition
{
    /// <summary>
    /// 唯一的权限组标识名称。
    /// </summary>
    public string Name { get; }

    // 开发人员针对权限组的一些自定义属性。
    public Dictionary<string, object> Properties { get; }

    // 权限所对应的本地化名称。
    public ILocalizableString DisplayName
    {
        get => _displayName;
        set => _displayName = Check.NotNull(value, nameof(value));
    }
    private ILocalizableString _displayName;

    /// <summary>
    /// 权限的适用范围，默认是租户/租主都适用。
    /// 默认值: <see cref="MultiTenancySides.Both"/>
    /// </summary>
    public MultiTenancySides MultiTenancySide { get; set; }

    // 权限组下面的所属权限。
    public IReadOnlyList<PermissionDefinition> Permissions => _permissions.ToImmutableList();
    private readonly List<PermissionDefinition> _permissions;

    // 针对于自定义属性的快捷索引器。
    public object this[string name]
    {
        get => Properties.GetOrDefault(name);
        set => Properties[name] = value;
    }

    protected internal PermissionGroupDefinition(
        string name, 
        ILocalizableString displayName = null,
        MultiTenancySides multiTenancySide = MultiTenancySides.Both)
    {
        Name = name;
        // 没有传递多语言串，则使用权限组的唯一标识作为显示内容。
        DisplayName = displayName ?? new FixedLocalizableString(Name);
        MultiTenancySide = multiTenancySide;

        Properties = new Dictionary<string, object>();
        _permissions = new List<PermissionDefinition>();
    }

    // 像权限组添加属于它的权限。
    public virtual PermissionDefinition AddPermission(
        string name, 
        ILocalizableString displayName = null,
        MultiTenancySides multiTenancySide = MultiTenancySides.Both)
    {
        var permission = new PermissionDefinition(name, displayName, multiTenancySide);

        _permissions.Add(permission);

        return permission;
    }

    // 递归构建权限集合，因为定义的某个权限内部还拥有子权限。
    public virtual List<PermissionDefinition> GetPermissionsWithChildren()
    {
        var permissions = new List<PermissionDefinition>();

        foreach (var permission in _permissions)
        {
            AddPermissionToListRecursively(permissions, permission);
        }

        return permissions;
    }

    // 递归构建方法。
    private void AddPermissionToListRecursively(List<PermissionDefinition> permissions, PermissionDefinition permission)
    {
        permissions.Add(permission);

        foreach (var child in permission.Children)
        {
            AddPermissionToListRecursively(permissions, child);
        }
    }

    public override string ToString()
    {
        return $"[{nameof(PermissionGroupDefinition)} {Name}]";
    }
}

通过权限组的定义代码你就会知道，现在我们的所有权限都会归属于某个权限组，这一点从之前 Provider 的 IPermissionDefinitionContext 就可以看出来。在权限上下文内部只允许我们通过 AddGroup() 来添加一个权限组，之后再通过权限组的 AddPermission() 方法添加它里面的权限。

权限的定义类叫做 PermissionDefinition，这个类型的构造与权限组定义类似，没有什么好说的。

public class PermissionDefinition
{
    /// <summary>
    /// 唯一的权限标识名称。
    /// </summary>
    public string Name { get; }

    /// <summary>
    /// 当前权限的父级权限，这个属性的值只可以通过 AddChild() 方法进行设置。
    /// </summary>
    public PermissionDefinition Parent { get; private set; }

    /// <summary>
    /// 权限的适用范围，默认是租户/租主都适用。
    /// 默认值: <see cref="MultiTenancySides.Both"/>
    /// </summary>
    public MultiTenancySides MultiTenancySide { get; set; }

    /// <summary>
    /// 适用的权限值提供者，这块我们会在后面进行讲解，为空的时候则使用所有的提供者进行校验。
    /// </summary>
    public List<string> Providers { get; } //TODO: Rename to AllowedProviders?

    // 权限的多语言名称。
    public ILocalizableString DisplayName
    {
        get => _displayName;
        set => _displayName = Check.NotNull(value, nameof(value));
    }
    private ILocalizableString _displayName;

    // 获取权限的子级权限。
    public IReadOnlyList<PermissionDefinition> Children => _children.ToImmutableList();
    private readonly List<PermissionDefinition> _children;

    /// <summary>
    /// 开发人员针对权限的一些自定义属性。
    /// </summary>
    public Dictionary<string, object> Properties { get; }

    // 针对于自定义属性的快捷索引器。
    public object this[string name]
    {
        get => Properties.GetOrDefault(name);
        set => Properties[name] = value;
    }

    protected internal PermissionDefinition(
        [NotNull] string name, 
        ILocalizableString displayName = null,
        MultiTenancySides multiTenancySide = MultiTenancySides.Both)
    {
        Name = Check.NotNull(name, nameof(name));
        DisplayName = displayName ?? new FixedLocalizableString(name);
        MultiTenancySide = multiTenancySide;

        Properties = new Dictionary<string, object>();
        Providers = new List<string>();
        _children = new List<PermissionDefinition>();
    }

    public virtual PermissionDefinition AddChild(
        [NotNull] string name, 
        ILocalizableString displayName = null,
        MultiTenancySides multiTenancySide = MultiTenancySides.Both)
    {
        var child = new PermissionDefinition(
            name, 
            displayName, 
            multiTenancySide)
        {
            Parent = this
        };

        _children.Add(child);

        return child;
    }

    /// <summary>
    /// 设置指定的自定义属性。
    /// </summary>
    public virtual PermissionDefinition WithProperty(string key, object value)
    {
        Properties[key] = value;
        return this;
    }

    /// <summary>
    /// 添加一组权限值提供者集合。
    /// </summary>
    public virtual PermissionDefinition WithProviders(params string[] providers)
    {
        if (!providers.IsNullOrEmpty())
        {
            Providers.AddRange(providers);
        }

        return this;
    }

    public override string ToString()
    {
        return $"[{nameof(PermissionDefinition)} {Name}]";
    }
}

2.2.3 权限管理器

继续回到权限管理器，权限管理器的接口定义是 IPermissionDefinitionManager ，从接口的方法定义来看，都是获取权限的方法，说明权限管理器主要提供给其他组件进行权限校验操作。

public interface IPermissionDefinitionManager
{
    // 根据权限定义的唯一标识获取权限，一旦不存在就会抛出 AbpException 异常。
    [NotNull]
    PermissionDefinition Get([NotNull] string name);

    // 根据权限定义的唯一标识获取权限，如果权限不存在，则返回 null。
    [CanBeNull]
    PermissionDefinition GetOrNull([NotNull] string name);

    // 获取所有的权限。
    IReadOnlyList<PermissionDefinition> GetPermissions();
    
    // 获取所有的权限组。
    IReadOnlyList<PermissionGroupDefinition> GetGroups();
}

接着我们来回答 2.2.1 末尾提出的问题，权限组是根据 Provider 自动创建了，那么权限呢？其实我们在权限管理器里面拿到了权限组，权限定义就很好构建了，直接遍历所有权限组拿它们的 Permissions 属性构建即可。

protected virtual Dictionary<string, PermissionDefinition> CreatePermissionDefinitions()
{
    var permissions = new Dictionary<string, PermissionDefinition>();

  	// 遍历权限定义组，这个东西在之前就已经构建好了。
    foreach (var groupDefinition in PermissionGroupDefinitions.Values)
    {
      	// 递归子级权限。
        foreach (var permission in groupDefinition.Permissions)
        {
            AddPermissionToDictionaryRecursively(permissions, permission);
        }
    }

  	// 返回权限唯一标识 - 权限定义 的字典。
    return permissions;
}

protected virtual void AddPermissionToDictionaryRecursively(
    Dictionary<string, PermissionDefinition> permissions, 
    PermissionDefinition permission)
{
    if (permissions.ContainsKey(permission.Name))
    {
        throw new AbpException("Duplicate permission name: " + permission.Name);
    }

    permissions[permission.Name] = permission;

    foreach (var child in permission.Children)
    {
        AddPermissionToDictionaryRecursively(permissions, child);
    }
}

2.2.4 授权策略提供者的实现

我们发现 ABP vNext 自己实现了 IAbpAuthorizationPolicyProvider 接口，实现的类型就是 AbpAuthorizationPolicyProvider 。

这个类型它是继承的 DefaultAuthorizationPolicyProvider ，重写了 GetPolicyAsync() 方法，目的就是将 PermissionDefinition 转换为 AuthorizationPolicy 。

如果去看了 雨夜朦胧 大神的博客，就知道我们一个授权策略可以由多个条件构成。也就是说某一个 AuthorizationPolicy 可以拥有多个限定条件，当所有限定条件被满足之后，才能算是通过权限验证，例如以下代码。

public void ConfigureService(IServiceCollection services)
{
    services.AddAuthorization(options =>
    {
        options.AddPolicy("User", policy => policy
            .RequireAssertion(context => context.User.HasClaim(c => (c.Type == "EmployeeNumber" || c.Type == "Role")))
        );

        // 这里的意思是，用户角色必须是 Admin，并且他的用户名是 Alice，并且必须要有类型为 EmployeeNumber 的 Claim。
        options.AddPolicy("Employee", policy => policy
            .RequireRole("Admin")
            .RequireUserName("Alice")
            .RequireClaim("EmployeeNumber")
            .Combine(commonPolicy));
    });
}

这里的 RequireRole() 、RequireUserName()、RequireClaim() 都会生成一个 IAuthorizationRequirement 对象，它们在内部有不同的实现规则。

public AuthorizationPolicyBuilder RequireClaim(string claimType)
{
    if (claimType == null)
    {
        throw new ArgumentNullException(nameof(claimType));
    }

  	// 构建了一个 ClaimsAuthorizationRequirement 对象，并添加到策略的 Requirements 组。
    Requirements.Add(new ClaimsAuthorizationRequirement(claimType, allowedValues: null));
    return this;
}

这里我们 ABP vNext 则是使用的 PermissionRequirement 作为一个限定条件。

public override async Task<AuthorizationPolicy> GetPolicyAsync(string policyName)
{
    var policy = await base.GetPolicyAsync(policyName);
    if (policy != null)
    {
        return policy;
    }

    var permission = _permissionDefinitionManager.GetOrNull(policyName);
    if (permission != null)
    {
        // TODO: 可以使用缓存进行优化。
        // 通过 Builder 构建一个策略。
        var policyBuilder = new AuthorizationPolicyBuilder(Array.Empty<string>());
        // 创建一个 PermissionRequirement 对象添加到限定条件组中。
        policyBuilder.Requirements.Add(new PermissionRequirement(policyName));
        return policyBuilder.Build();
    }

    return null;
}

与 ClaimsAuthorizationRequirement 不同的是，ABP vNext 并没有将限定条件处理器和限定条件定义放在一起实现，而是分开的，分别构成了 PermissionRequirement 和 PermissionRequirementHandler ，后者在模块配置的时候被注入到 IoC 里面。

PS：

对于 Handler 来说，我们可以编写多个 Handler 注入到 IoC 容器内部，如下代码：
services.AddSingleton<IAuthorizationHandler, BadgeEntryHandler>();
services.AddSingleton<IAuthorizationHandler, HasTemporaryStickerHandler>();

首先看限定条件 PermissionRequirement 的定义，非常简单。

public class PermissionRequirement : IAuthorizationRequirement
{
    public string PermissionName { get; }

    public PermissionRequirement([NotNull]string permissionName)
    {
        Check.NotNull(permissionName, nameof(permissionName));

        PermissionName = permissionName;
    }
}

在限定条件内部，我们只用了权限的唯一标识来进行处理，接下来看一下权限处理器。

public class PermissionRequirementHandler : AuthorizationHandler<PermissionRequirement>
{
		// 这里通过权限检查器来确定当前用户是否拥有某个权限。
    private readonly IPermissionChecker _permissionChecker;

    public PermissionRequirementHandler(IPermissionChecker permissionChecker)
    {
        _permissionChecker = permissionChecker;
    }

    protected override async Task HandleRequirementAsync(
        AuthorizationHandlerContext context,
        PermissionRequirement requirement)
    {
    		// 如果当前用户拥有某个权限，则通过 Contxt.Succeed() 通过授权验证。
        if (await _permissionChecker.IsGrantedAsync(context.User, requirement.PermissionName))
        {
            context.Succeed(requirement);
        }
    }
}

2.2.5 权限检查器

在上面的处理器我们看到了，ABP vNext 是通过权限检查器来校验某个用户是否满足某个授权策略，先看一下 IPermissionChecker 接口的定义，基本都是传入身份证(ClaimsPrincipal)和需要校验的权限进行处理。

public interface IPermissionChecker
{
    Task<bool> IsGrantedAsync([NotNull]string name);

    Task<bool> IsGrantedAsync([CanBeNull] ClaimsPrincipal claimsPrincipal, [NotNull]string name);
}

第一个方法内部就是调用的第二个方法，只不过传递的身份证是通过 ICurrentPrincipalAccessor 拿到的，所以我们的核心还是看第二个方法的实现。

public virtual async Task<bool> IsGrantedAsync(ClaimsPrincipal claimsPrincipal, string name)
{
    Check.NotNull(name, nameof(name));

    var permission = PermissionDefinitionManager.Get(name);

    var multiTenancySide = claimsPrincipal?.GetMultiTenancySide()
                            ?? CurrentTenant.GetMultiTenancySide();

    // 检查传入的权限是否允许当前的用户模式（租户/租主）进行访问。
    if (!permission.MultiTenancySide.HasFlag(multiTenancySide))
    {
        return false;
    }

    var isGranted = false;
    // 这里是重点哦，这个权限值检测上下文是之前没有说过的东西，说白了就是针对不同维度的权限检测。
    // 之前这部分东西是通过权限策略下面的 Requirement 提供的，这里 ABP vNext 将其抽象为 PermissionValueProvider。
    var context = new PermissionValueCheckContext(permission, claimsPrincipal);
    foreach (var provider in PermissionValueProviderManager.ValueProviders)
    {
        // 如果指定的权限允许的权限值提供者集合不包含当前的 Provider，则跳过处理。
        if (context.Permission.Providers.Any() &&
            !context.Permission.Providers.Contains(provider.Name))
        {
            continue;
        }

        // 调用 Provider 的检测方法，传入身份证明和权限定义进行具体校验。
        var result = await provider.CheckAsync(context);

        // 根据返回的结果，判断是否通过了权限校验。
        if (result == PermissionGrantResult.Granted)
        {
            isGranted = true;
        }
        else if (result == PermissionGrantResult.Prohibited)
        {
            return false;
        }
    }

    // 返回 true 说明已经授权，返回 false 说明是没有授权的。
    return isGranted;
}

2.2.6 PermissionValueProvider

在模块配置方法内部，可以看到通过 Configure<PermissionOptions>() 方法添加了三个 PermissionValueProvider ，即 UserPermissionValueProvider、RolePermissionValueProvider、ClientPermissionValueProvider 。在它们的内部实现，都是通过 IPermissionStore 从持久化存储 检查传入的用户是否拥有某个权限。

这里我们以 UserPermissionValueProvider 为例，来看看它的实现方法。

public class UserPermissionValueProvider : PermissionValueProvider
{
    // 提供者的名称。
    public const string ProviderName = "User";

    public override string Name => ProviderName;

    public UserPermissionValueProvider(IPermissionStore permissionStore)
        : base(permissionStore)
    {

    }

    public override async Task<PermissionGrantResult> CheckAsync(PermissionValueCheckContext context)
    {
        // 从传入的 Principal 中查找 UserId，不存在则说明没有定义，视为未授权。
        var userId = context.Principal?.FindFirst(AbpClaimTypes.UserId)?.Value;

        if (userId == null)
        {
            return PermissionGrantResult.Undefined;
        }

        // 调用 IPermissionStore 从持久化存储中，检测指定权限在某个提供者下面是否已经被授予了权限。
        // 如果被授予了权限， 则返回 true，没有则返回 false。
        return await PermissionStore.IsGrantedAsync(context.Permission.Name, Name, userId)
            ? PermissionGrantResult.Granted
            : PermissionGrantResult.Undefined;
    }
}

这里我们先不讲 IPermissionStore 的具体实现，就上述代码来看，ABP vNext 是将权限定义放在了一个管理容器(IPermissionDeftiionManager)。然后又实现了自定义的策略处理器和策略，在处理器的内部又通过 IPermissionChecker 根据不同的 PermissionValueProvider 结合 IPermissionStore 实现了指定用户标识到权限的检测功能。

2.2.7 权限验证拦截器

权限验证拦截器的注册都是在 AuthorizationInterceptorRegistrar 的 RegisterIfNeeded() 方法内实现的，只要类型的任何一个方法标注了 AuthorizeAttribute 特性，就会被关联拦截器。

private static bool AnyMethodHasAuthorizeAttribute(Type implementationType)
{
    return implementationType
        .GetMethods(BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic)
        .Any(HasAuthorizeAttribute);
}

private static bool HasAuthorizeAttribute(MemberInfo methodInfo)
{
    return methodInfo.IsDefined(typeof(AuthorizeAttribute), true);
}

拦截器和类型关联之后，会通过 IMethodInvocationAuthorizationService 的 CheckAsync() 方法校验调用者是否拥有指定权限。

public override async Task InterceptAsync(IAbpMethodInvocation invocation)
{
    // 防止重复检测。
    if (AbpCrossCuttingConcerns.IsApplied(invocation.TargetObject, AbpCrossCuttingConcerns.Authorization))
    {
        await invocation.ProceedAsync();
        return;
    }

    // 将被调用的方法传入，验证是否允许访问。
    await AuthorizeAsync(invocation);
    await invocation.ProceedAsync();
}

protected virtual async Task AuthorizeAsync(IAbpMethodInvocation invocation)
{
    await _methodInvocationAuthorizationService.CheckAsync(
        new MethodInvocationAuthorizationContext(
            invocation.Method
        )
    );
}

在具体的实现当中，首先检测方法是否标注了 IAllowAnonymous 特性，标注了则说明允许匿名访问，直接返回不做任何处理。否则就会从方法获取实现了 IAuthorizeData 接口的特性，从里面拿到 Policy 值，并通过 IAuthorizationService 进行验证。

protected async Task CheckAsync(IAuthorizeData authorizationAttribute)
{
    if (authorizationAttribute.Policy == null)
    {
        // 如果当前调用者没有进行认证，则抛出未登录的异常。
        if (!_currentUser.IsAuthenticated && !_currentClient.IsAuthenticated)
        {
            throw new AbpAuthorizationException("Authorization failed! User has not logged in.");
        }
    }
    else
    {
        // 通过 IAuthorizationService 校验当前用户是否拥有 authorizationAttribute.Policy 权限。
        await _authorizationService.CheckAsync(authorizationAttribute.Policy);
    }
}

针对于 IAuthorizationService ，ABP vNext 还是提供了自己的实现 AbpAuthorizationService，里面没有重写什么方法，而是提供了两个新的属性，这两个属性是为了方便实现 AbpAuthorizationServiceExtensions 提供的扩展方法，这里不再赘述。

三、总结

关于权限与验证部分我就先讲到这儿，后续文章我会更加详细地为大家分析 ABP vNext 是如何进行权限管理，又是如何将 ABP vNext 和 ASP.NET Identity 、IdentityServer4 进行集成的。

移除 DevExpress 的 XtraForm 标题文字阴影

Wed, 31 Jul 2019 06:24:18 +0000

问题

在使用 DevExpress 开发 WinForm 程序时，我是使用的默认皮肤进行开发。但客户要求标题栏背景色改为蓝色，标题文字颜色改为白色。

改颜色比较简单，参考了 DevExpress Support 的说明，通过获取皮肤更改 BackColor 和 ForeColor 就可以实现。不过更改之后，发现在低分屏下面，标题文字出现模糊的情况。

原因

初步猜想应该是文字阴影的问题，但搜索了大部分资料没有找到解决方案，最后在 DevExpress Support 的这篇文章看到了自定义 FormPainter 。起初我认为是重载 DrawText() 解决，不过没有找到相关的参数，之后发现它有一个 DrawTextShadow() 方法，应该就是它了。

解决

解决方法很简单，就是重写 DrawTextShadow() 方法，将其作为一个空方法就行了，不做任何阴影处理。

public class ReplaceFontFormPainter : FormPainter
{
	public ReplaceFontFormPainter(Control owner, ISkinProvider provider) : base(owner, provider)
	{
		
	}
	
	// 不再绘制标题文字阴影。
	protected override void DrawTextShadow(GraphicsCache cache, AppearanceObject appearance, Rectangle bounds)
	{
		
	}
}

来到你需要更改的窗体，重载窗体的 CreateFormBorderPainter() 方法，使用你自己创建的 FormPainter 。

public partial class MainForm : XtraForm
{
	protected override FormPainter CreateFormBorderPainter() => new ReplaceFontFormPainter(this, LookAndFeel);
}

最后的效果：

Abp vNext 源码分析 - 6. DDD 的应用层支持 (应用服务)

Thu, 25 Jul 2019 12:10:32 +0000

一、简要介绍

ABP vNext 针对于应用服务层，为我们单独设计了一个模块进行实现，即 Volo.Abp.Ddd.Application 模块。

PS：最近博主也是在恶补 DDD 相关的知识，这里推荐大家看一下 ThoughtWorks 的 DDD 相关文章。

关于 DDD 相关的著作，我这儿还是推荐经典的那三本**《领域驱动设计：软件核心复杂性应对之道》、《实现领域驱动设计》、《领域驱动设计精粹》**。

DDD 的学习整体来说是比较枯燥的，而且偏理论化的知识。所以需要结合大量实例来看，反复对照书中的概念加深理解。不仅要看别人的实例，自己也要尝试运用 DDD 的战略方法和战术方法进行设计。

应用服务层在 DDD 分层架构里面是最顶层的，一般与前端（展示层）打交道的都是应用服务层。常规的开发人员，如果没有遵循 DDD 理论来进行开发的话，应用服务层是十分臃肿的，里面全是业务逻辑。而领域层里面则是空无一物，全是贫血的领域模型对象。这种模式被称之为 贫血领域模型模式，这是一个 反模式。

这里我就不再赘述应用服务层与 DDD 之间的关系了，在这里你可以看作它是一个 API 接口实现类，你所有对外开放的接口都是通过应用服务层暴露的，接口的方法应该与用例相对应。

二、源码分析

应用服务层模块里面比较简单，只有两个文件夹，分别存放了数据传输模型（Dtos）和应用服务基类定义（Services）。

2.1 启动模块

首先我们还是按照之前的顺序，看一个模块先看他的模块类。这里我们先看一下 AbpDddApplicationModule 的代码。

[DependsOn(
	typeof(AbpDddDomainModule),
	typeof(AbpSecurityModule),
	typeof(AbpObjectMappingModule),
	typeof(AbpValidationModule),
	typeof(AbpAuthorizationModule),
	typeof(AbpHttpAbstractionsModule),
	typeof(AbpSettingsModule),
	typeof(AbpFeaturesModule)
	)]
	// 不要看上面依赖这么多模块，主要是因为基类会用到很多基础组件。
public class AbpDddApplicationModule : AbpModule
{
	public override void ConfigureServices(ServiceConfigurationContext context)
	{
		// 配置接口类型。
		Configure<ApiDescriptionModelOptions>(options =>
		{
			options.IgnoredInterfaces.AddIfNotContains(typeof(IRemoteService));
			options.IgnoredInterfaces.AddIfNotContains(typeof(IApplicationService));
			options.IgnoredInterfaces.AddIfNotContains(typeof(IUnitOfWorkEnabled));
		});
	}
}

可以看到，在上述代码里面，只做了一件事情，就是调用 ApiDescriptionModelOptions ，往里面添加了 IRemoteService、IApplicationService、IUnitOfWOrkEnabled 三种接口类型。添加了三种类型之后，ABP vNext 根据应用服务类创建控制器时，就会从这个 IgnoredInterfaces 判断哪些类型不被忽略 (即只会自动注册实现了三种接口的类型成为控制器)。

2.2 应用服务基类

ABP vNext 提供了标准基类 ApplicationService 和简单 Crud 基类 CrudAppService 给我们使用，前者只是继承了 IApplicationService 接口，并提供了基本组件的简单基类。而后者则是定义了 Crud 操作所需要的所有 API 方法，你只需要继承这个基类对象，填充相应的泛型参数，就可以快速实现一个 Crud 接口。

2.2.1 简单基类

简单基类里面我们首先需要注意的是它实现的接口，你可以发现 ApplicationService 实现了诸多接口，不过这些接口更多的是类似于标识接口。

public abstract class ApplicationService :
	IApplicationService,
	IAvoidDuplicateCrossCuttingConcerns,
	IValidationEnabled,
	IUnitOfWorkEnabled,
	IAuditingEnabled,
	ITransientDependency
{
	// ... 其他代码
}

所有应用服务都必须继承 IApplicationService，这个是肯定的，不然 ABP vNext 不会为我们生成需要的控制器。

其次是 IAvoidDuplicateCrossCuttingConcerns 接口，这个接口最早可以追溯到老版本 ABP 框架里面。它的主要作用是防止拦截器进行重复执行。

public interface IAvoidDuplicateCrossCuttingConcerns
{
	List<string> AppliedCrossCuttingConcerns { get; }
}

例如调用购买这个 API 接口，首先会进入 ASP.NET Core 的审计日志 Filter，在 Filter 里面会将这个 API 接口归属的类型的 List 容器(接口里面定义的 List )里面写入一条记录，说明已经通过审计日志过滤器记录了。

写了审计日志之后，又会进入审计日志拦截器，这个时候拦截器就会对指定的类型进行判断，看是否已经被执行过了，因为这个类型的 List 容器有了之前过滤器的记录，所以不会重复执行。

public override void Intercept(IAbpMethodInvocation invocation)
{
	if (!ShouldIntercept(invocation, out var auditLog, out var auditLogAction))
	{
		invocation.Proceed();
		return;
	}

	// ... 审计日志记录。
}

protected virtual bool ShouldIntercept(
	IAbpMethodInvocation invocation, 
	out AuditLogInfo auditLog, 
	out AuditLogActionInfo auditLogAction)
{
	// 判断实例的 List 容器里面，是否写入了 AbpCrossCuttingConcerns.Auditing。
	if (AbpCrossCuttingConcerns.IsApplied(invocation.TargetObject, AbpCrossCuttingConcerns.Auditing))
	{
		return false;
	}
	
	// ... 其他代码

	return true;
}

剩余的 IValidationEnabled、IUnitOfWorkEnabled、IAuditingEnabled、ITransientDependency 接口类似于一个启用标识，只要类型继承了该接口，就会执行一些特殊的操作。

回到之前的简单基类里面，ABP vNext 为我们注入了大量基础设施，例如获取当前用户的 ICurrentUser 组件，获取当前租户的 ICurrentTenant 组件，还有日志组件等。

除了基础组件，ABP vNext 在简单基类里面还提供了一个权限检测方法，用户检测当前用户是否具备某些权限。

protected virtual async Task CheckPolicyAsync([CanBeNull] string policyName)
{
	if (string.IsNullOrEmpty(policyName))
	{
		return;
	}

	await AuthorizationService.CheckAsync(policyName);
}

在不具备权限的时候，ABP vNext 会抛出 AbpAuthorizationException 异常。

2.2.2 Crud 基类

Crud 基类可以极大减少对于某些简单对象的代码编写，例如我有个客户管理接口，只需要简单地增删改查操作。那么我就可以直接继承自 Crud 基类，给它填写和是的泛型参数之后，ABP vNext 就会为我们生成带有增删改查操作的应用服务对象。

这个 Crud 基类拥有多个泛型定义与实现，除了真正的实现以外，其他的都是简单的调用基类方法而已。我们直接进入主题，看一下类型签名为 public abstract class CrudAppService<TEntity, TGetOutputDto, TGetListOutputDto, TKey, TGetListInput, TCreateInput, TUpdateInput> 的基类。

public abstract class CrudAppService<TEntity, TGetOutputDto, TGetListOutputDto, TKey, TGetListInput, TCreateInput, TUpdateInput>
   : ApplicationService,
	ICrudAppService<TGetOutputDto, TGetListOutputDto, TKey, TGetListInput, TCreateInput, TUpdateInput>
	where TEntity : class, IEntity<TKey>
	where TGetOutputDto : IEntityDto<TKey>
	where TGetListOutputDto : IEntityDto<TKey>
{
	public virtual async Task<TGetOutputDto> GetAsync(TKey id)
	{
		// 具体代码。
	}
	
	public virtual async Task<PagedResultDto<TGetListOutputDto>> GetListAsync(TGetListInput input)
	{
		// 具体代码。
	}
	
	public virtual async Task<TGetOutputDto> CreateAsync(TCreateInput input)
	{
		// 具体代码。
	}
	
	public virtual async Task<TGetOutputDto> UpdateAsync(TKey id, TUpdateInput input)
	{
		// 具体代码。
	}
	
	public virtual async Task DeleteAsync(TKey id)
	{
		// 具体代码。
	}
}

从上述代码可以看到基类根据传入的泛型参数，将会为我们实现常规的增删改查逻辑。我们也可以随时重写这些方法，来达到一些个性化的操作。

ABP vNext 抽象了公用接口以外，在内部还编写了诸如 MapToEntity() 和 MapToEntity() 等内部共用方法，这里就不再详细赘述，这些方法都是 protected 修饰的，你也可以随时重写来达到自己的目的。

2.3 数据传输对象

一般来说，应用服务层返回给展示层的数据肯定是某个实体对象的部分属性，或者是多个聚合的整体，这个时候就需要 DTO 来帮我们处理应用服务层与外部的数据交换了。

ABP vNext 在应用服务模块定义了常用的一些 DTO 对象，例如实体 DTO 和分页查询 DTO，关于这些 DTO 你只需将其看作一个数据容器即可，不需要太多关注，这里也没有太多要讲的。

三、总结

ABP vNext 提供的应用服务层模块还是比较简单的，里面主要是针对应用服务基类进行了预定义。方便我们开发人员进行业务开发，而不需要自己实现这些繁杂的基类。

在 DDD 当中，应用服务是表达 用户用例 和 用户故事 的主要手段，应用服务只是通过领域对象/领域服务来表达需求用例的一个组件。不要将业务逻辑泄漏到应用服务当中，这种设计最终会导致贫血领域模型。

ABP vNext 源码分析 - 5. DDD 的领域层支持 (仓储、实体、值对象)

Sat, 20 Jul 2019 02:05:28 +0000

一、简要介绍

ABP vNext 框架本身就是围绕着 DDD 理念进行设计的，所以在 DDD 里面我们能够见到的实体、仓储、值对象、领域服务，ABP vNext 框架都为我们进行了实现，这些基础设施都存放在 Volo.Abp.Ddd.Domain 项目当中。

本篇文章将会侧重于理论讲解，但也只是一个抛砖引玉的作用，关于 DDD 相关的知识可以阅读 Eric Evans 所编写的《领域驱动设计：软件核心复杂性应对之道》。

PS：

该书也是目前我正在阅读的 DDD 理论书籍，因为基于 DDD 理论，我们能够精准地划分微服务的业务边界，为后续微服务架构的可扩展性提供坚实的基础。

二、源码分析

Volo.Abp.Ddd.Domain 分为 Volo 和 Microsoft 两个文件夹，在 Microsoft 文件夹当中主要是针对仓储和实体进行自动注入。

2.1 实体 (Entity)

2.1.1 基本概念

只要用过 EF Core 框架的人，基本都知道什么是实体。不过很多人就跟我一样，只是将实体作为数据库表在 C# 语言当中的另一种展现方式，认为它跟普通的对象没什么不一样。

PS：虽然每个对象都会有一个内在的 对象引用指针 来作为唯一标识。

在 DDD 的概念当中，通过标识定义的对象被称为实体(Entity)。虽然它们的属性可能因为不同的操作而被改变（多种生命周期），但必须保证一种内在的连续性。为了保证这种内在的连续性，就需要一个有意义并且唯一的属性。

标识是否重要则完全取决于它是否有用，例如有个演唱会订票程序，你可以将座位与观众都当作一个实体处理。那么在分配座位时，每个座位肯定都会有一个唯一的座位号(唯一标识)，可也能拥有其他描述属性(是否是 VIP 座位、价格等…)。

那么座位是否需要唯一标识，是否为一个实体，就取决于不同的入场方式。假如说是一人一票制，并且每张门票上面都有固定的座位号，这个时候座位就是一个实体，因为它需要座位号来区分不同的座位。

另一种方式就是入场卷方式，门票上没有座位号，你想坐哪儿就坐哪儿。这个时候座位号就不需要与门票建立关联，在这种情况下座位就不是一个实体，所以不需要唯一标识。

* 上述例子与描述改编自《领域驱动设计：软件核心复杂性应对之道》的 ENTITY 一节。

2.1.2 如何实现

了解了 DDD 概念里面的实体描述之后，我们就来看一下 ABP vNext 为我们准备了怎样的基础设施。

首先看 Entities 文件夹下关于实体的基础定义，在实体的基础定义类里面，为每个实体定义了唯一标识。并且在某些情况下，我们需要确保 ID 在多个计算机系统之间具有唯一性。

尤其是在多个系统/平台进行对接的时候，如果每个系统针对于 “张三” 这个用户的 ID 不是一致的，都是自己生成 ID ，那么就需要介入一个新的抽象层进行关系映射。

在 IEntity<TKey> 的默认实现 Entity<TKey> 中，不仅提供了标识定义，也重写了 Equals() 比较方法和 == \ != 操作符，用于区别不同实体。它为对象统一定义了一个 TKey 属性，该属性将会作为实体的唯一标识字段。

public override bool Equals(object obj)
{
    // 比较的对象为 NULL 或者对象不是派生自 Entity<T> 都视为不相等。
	if (obj == null || !(obj is Entity<TKey>))
	{
		return false;
	}

	// 比较的对象与当前对象属于同一个引用，视为相等的。
	if (ReferenceEquals(this, obj))
	{
		return true;
	}

	// 当前比较主要适用于 EF Core，如果任意对象是使用的默认 Id，即临时对象，则其默认 ID 都为负数，视为不相等。
	var other = (Entity<TKey>)obj;
	if (EntityHelper.HasDefaultId(this) && EntityHelper.HasDefaultId(other))
	{
		return false;
	}

	// 主要判断当前对象与比较对象的类型信息，看他们两个是否属于 IS-A 关系，如果不是，则视为不相等。
	var typeOfThis = GetType().GetTypeInfo();
	var typeOfOther = other.GetType().GetTypeInfo();
	if (!typeOfThis.IsAssignableFrom(typeOfOther) && !typeOfOther.IsAssignableFrom(typeOfThis))
	{
		return false;
	}

	// 如果两个实体他们的租户 Id 不同，也视为不相等。
	if (this is IMultiTenant && other is IMultiTenant &&
		this.As<IMultiTenant>().TenantId != other.As<IMultiTenant>().TenantId)
	{
		return false;
	}

    // 通过泛型的 Equals 方法进行最后的比较。
	return Id.Equals(other.Id);
}

实体本身是支持序列化的，所以特别标注了 [Serializable] 特性。

[Serializable]
public abstract class Entity<TKey> : Entity, IEntity<TKey>
{
	// ... 其他代码。
}

针对于某些实体可能是 复合主键 的情况，ABP vNext 则推荐使用 IEntity 和 Entity 进行处理。

/// <summary>
/// 定义一个实体，但它的主键可能不是 “Id”，也有可能是否复合主键。
/// 开发人员应该尽可能使用 <see cref="IEntity{TKey}"/> 来定义实体，以便更好的与其他框架/结构进行集成。
/// </summary>
public interface IEntity
{
    /// <summary>
    /// 返回当前实体的标识数组。
    /// </summary>
    object[] GetKeys();
}

2.2 自动审计

在 Entities 文件夹里面，还有一个 Auditing 文件夹。在这个文件夹里面定义了很多对象，我们最为常用的就是 FullAuditiedEntity 对象了。从字面意思来看，它是一个包含了所有审计属性的实体。

[Serializable]
public abstract class FullAuditedEntity<TKey> : AuditedEntity<TKey>, IFullAuditedObject
{
	// 软删除标记，为 true 时说明实体已经被删除，反之亦然。
	public virtual bool IsDeleted { get; set; }

	// 删除实体的用户 Id。
	public virtual Guid? DeleterId { get; set; }

	// 实体被删除的时间。
	public virtual DateTime? DeletionTime { get; set; }
}

那么，什么是审计属性呢？在 ABP vNext 内部将以下属性定义为审计属性：创建人、创建时间、修改人、修改时间、删除人、删除时间、软删除标记。这些属性不需要开发人员手动去书写/控制，ABP vNext 框架将会自动跟踪这些属性并设置其值。

开发人员除了可以直接继承 FullAuditedEntity 以外，也可以考虑集成其他的审计实例，例如只包含创建人与创建时间的 CreationAuditedEntity。如果你觉得你只想要创建人、软删除标记、修改时间的话，也可以直接继承相应的接口。

public class TestEntity : Entity<int>,IMayHaveCreator,ISoftDelete,IHasModificationTime
{
	/// <summary>
	/// 创建人的 Id。
	/// </summary>
	public Guid? CreatorId { get; set; }
	
	/// <summary>
	/// 软删除标记。
	/// </summary>
	public bool IsDeleted { get; set; }
	
	/// <summary>
	/// 最后的修改时间。
	/// </summary>
	public DateTime? LastModificationTime { get; set; }
}

这里我只重点提一下关于审计实体相关的内容，对于聚合的根对象的审计实体，内容也是相似的，就不再赘述。

2.3 值对象 (ValueObject)

2.3.1 基本概念

DDD 关于值对象某一个概念来说，每个值对象都是单一的副本，这个概念你可以类比 C# 里面关于值对象和引用对象的区别。

值对象与实体最大的区别就在于，值对象是没有概念标识的，还有比较重要的一点就是值对象是不可变的，所谓的不可变，就是值对象产生任何变化应该直接替换掉原有副本，而不是在原有副本上进行修改。**如果值对象是可变的，那么它一定不能被共享。**值对象可以引用实体或者其他的值对象。

这里仍然以书中的例子进行说明值对象的标识问题，例如 “地址” 这个概念。

如果我在淘宝买了一个键盘，我的室友也从淘宝买了同款键盘。对于淘宝系统来说，我们两个是否处于同一个地址并不重要，所以这里 “地址” 就是一个值对象。因为系统不需要关心两个地址的唯一标识是否一致，在业务上来说也没有这个需要。

另一个情况就是家里停电了，我和我的室友同时在电力服务系统提交了工单。这个时候对于电力系统来说，如果两个工单的地址是在同一个地方，那么只需要派一个人去进行维修即可。这种情况下，地址就是一个实体，因为地址涉及到比较，而比较的依据则是地址的唯一标识。

上述情况还有的另一种实现方式，即我们将住处抽象为一个实体，电力系统与住处进行关联。住处里面包含地址，这个时候地址就是一个值对象。因为这个时候电力系统关心的是住处是否一致，而地址则作为一个普通的属性而已。

关于值对象的另一个用法则更加通俗，例如一个 Person 类，他原来的定义是拥有一个 Id、姓名、街道、社区、城市。那么我们可以将街道、社区、城市抽象到一个值对象 Address 类里面，每个值对象内部包含的属性应该形成一个概念上的整体。

2.3.2 如何实现

ABP vNext 对于值对象的实现是比较粗糙的，他仅参考 MSDN 定义了一个简单的 ValueObject 类型，具体的用法开发人员可以参考 MSDN 实现值对象的细节，下文仅是摘抄部分内容进行简要描述。

MSDN 也是以地址为例，他将 Address 定义为一个值对象，如下代码。

public class Address : ValueObject
{
    public String Street { get; private set; }
    public String City { get; private set; }
    public String State { get; private set; }
    public String Country { get; private set; }
    public String ZipCode { get; private set; }

    private Address() { }

    public Address(string street, string city, string state, string country, string zipcode)
    {
        Street = street;
        City = city;
        State = state;
        Country = country;
        ZipCode = zipcode;
    }

    protected override IEnumerable<object> GetAtomicValues()
    {
        // Using a yield return statement to return each element one at a time
        yield return Street;
        yield return City;
        yield return State;
        yield return Country;
        yield return ZipCode;
    }
}

不过我们知道，如果一个值对象需要持久化到数据库，没有 Id 标识咋办？MSDN 上面也说明了在 EF Core 1.1 和 EF Core 2.0 的处理方法，这里我们只着重说明 EF Core 2.0 的处理方法。

EF Core 2.0 可以使用 owned entity(固有实体类型) 来实现值对象，固有实体的以下特征可以帮助我们实现值对象。

固有对象可以用作属性，并且没有自己的标识。
在查询所有实体时，固有实体将会包含进去。例如我查询订单 A，那么就会将地址这个值对象包含到订单 A 的结果当中。

但一个类型不管怎样都是会拥有它自己的标识的，这里不再详细叙述，更加详细的可以参考 MSDN 英文原版说明。(中文版翻译有问题)

The identity of the owner

The navigation property pointing to them

In the case of collections of owned types, an independent component (not yet supported in EF Core 2.0, coming up on 2.2).

EF Core 不会自动发现固有实体类型，需要显示声明，这里以 MSDN 官方的 eShopOnContainers DEMO 为例。

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.ApplyConfiguration(new ClientRequestEntityTypeConfiguration());
    modelBuilder.ApplyConfiguration(new PaymentMethodEntityTypeConfiguration());
    modelBuilder.ApplyConfiguration(new OrderEntityTypeConfiguration());
    modelBuilder.ApplyConfiguration(new OrderItemEntityTypeConfiguration());
    //...Additional type configurations
}

接着我们来到 OrderEntityTypeConfiguration 类型的 Configure() 方法中。

public void Configure(EntityTypeBuilder<Order> orderConfiguration)
{
    orderConfiguration.ToTable("orders", OrderingContext.DEFAULT_SCHEMA);
    orderConfiguration.HasKey(o => o.Id);
    orderConfiguration.Ignore(b => b.DomainEvents);
    orderConfiguration.Property(o => o.Id)
        .ForSqlServerUseSequenceHiLo("orderseq", OrderingContext.DEFAULT_SCHEMA);

    // 说明 Address 属性是 Order 类型的固有实体。
    orderConfiguration.OwnsOne(o => o.Address);

    orderConfiguration.Property<DateTime>("OrderDate").IsRequired();

    //...Additional validations, constraints and code...
    //...
}

默认情况下，EF Core 会将固有实体的数据库列名，以 <实体的属性名>_<固有实体的属性>。以上面的 Address 类型字段为例，将会生成 Address_Street 、Address_City 这样的名称。你也可以通过流畅接口来重命名这些列，代码如下：

orderConfiguration.OwnsOne(p => p.Address)
                            .Property(p=>p.Street).HasColumnName("ShippingStreet");

orderConfiguration.OwnsOne(p => p.Address)
                            .Property(p=>p.City).HasColumnName("ShippingCity");

2.4 聚合

如果说实体的概念还比较好理解的话，那么聚合则是在实体之上新的抽象。聚合就是一组相关对象的集合，他会有一个根对象(root)，和它的一个边界(boundary)。对于聚合外部来说，只能够引用它的根对象，而在聚合内部的其他对象则可以相互引用。

一个简单的例子(《领域驱动设计》)来说，汽车是一个具有全局标识的实体，每一辆汽车都拥有自己唯一的标识。在某些时候，我们可能会需要知道轮胎的磨损情况与公里数，因为汽车有四个轮胎，所以我们也需要将轮胎视为实体，为其分配唯一本地的标识，这个标识是聚合内唯一的。但是在脱离了汽车这个边界之后，我们就不需要关心这些轮胎的标识。

所以在上述例子当中，汽车是一个聚合的根实体，而轮胎处于这个聚合的边界之内。

那么一个聚合应该怎样进行设计呢？这里我引用汤雪华大神的《关于领域驱动设计（DDD）中聚合设计的一些思考》和《聚合（根）、实体、值对象精炼思考总结》说明一下聚合根要怎么设计才合理。

聚合的几大设计原则：

聚合是用来封装不变性（即固定规则），而不是将领域对象简单组合到一起。
聚合应该尽量设计成小聚合。
聚合与聚合之间的关系应该通过 Id 进行引用。
聚合内部应该是强一致性（同一事务），聚合之间只需要追求最终一致性即可。

以上内容我们还是以经典的订单系统来举例子，说明我们的实体与聚合应该怎样进行划分。我们有一个订单系统，其结构如下图：

其中有一个固定规则，就是采购项(Line Item)的总量不能够超过 PO 总额(approved limit)的限制，这里的 Part 是具体采购的部件(产品)，它拥有一个 price 属性作为它的金额。

从上述业务场景我们就可以得出以下问题：

固定规则的实施，即添加新的采购项时，PO 需要检查总额，如果超出限制视为无效。
当 PO 被删除或者存档时，采购项也应该一并处理。（同生共死原则）
多用户的竞争问题，如果在采购过程中，采购项与部件都被用户修改，会产生问题。

场景 1：

当用户编辑任何一个对象时，锁定该对象，直到编辑完成提交事务。这样就会造成 George 编辑订单 #0001 的采购项 001 时，Amanda 无法修改该采购项。但是 Amanda 可以修改其他的采购项，这样最后提交的时候就会导致 #0001 订单破坏了固定规则。

场景 2：

如果锁定单行对象不行，那么我们直接锁定 PO 对象，并且为了防止 Part 的价格被修改，Part 对象也需要被锁定。这样就会造成太多的数据争用，现在 3 个人都需要等待。

从上述场景来看，我们可以得出以下结论：

Part 在很多 PO 当中被使用。
对 Part 的修改少于对 PO 的修改。
PO 与采购项不能分开，后者独立存在没有意义。
对 Part 的价格修改不一定要实时传播给 PO，仅取决于修改价格时 PO 处于什么状态。

有以上结论可以知道，我们可以将 Part 的价格冗余到采购项，PO 和采购项的创建与删除是很自然的业务规则，而 Part 的创建与删除是独立的，所以将 PO 与采购项能划为一个聚合。

Abp vNext 框架也为我们提供了聚合的定义与具体实现，即 AggregateRoot 类型。该类型也继承自 Entity 类型，并且内部提供了一个并发令牌防止并发冲突。

并且在其内部也提供了领域事件的快速增删方法，其他的与常规实体基本一致。通过领域事件，我们可以完成对事务的拆分。例如上述的例子当中，我们也可以为 Part 增加一个领域事件，当价格被更新时，PO 可以订阅这个事件，实现对应的采购项更新。

只是这里你会奇怪，增加的事件到哪儿去了呢？他们这些事件最终会被添加到 EntityChangeReport 类型的 DomainEvents 集合里面，并且在实体变更时进行触发。

关于聚合的示例，在 ABP vNext 官网已经有十分详细的描述，这里我贴上代码供大家理解以下，官方的例子仍然是以订单和采购项来说的。

public class Order : AggregateRoot<Guid>
{
    public virtual string ReferenceNo { get; protected set; }

    public virtual int TotalItemCount { get; protected set; }

    public virtual DateTime CreationTime { get; protected set; }

    public virtual List<OrderLine> OrderLines { get; protected set; }

    protected Order()
    {

    }

    public Order(Guid id, string referenceNo)
    {
        Check.NotNull(referenceNo, nameof(referenceNo));
        
        Id = id;
        ReferenceNo = referenceNo;
        
        OrderLines = new List<OrderLine>();
    }

    public void AddProduct(Guid productId, int count)
    {
        if (count <= 0)
        {
            throw new ArgumentException(
                "You can not add zero or negative count of products!",
                nameof(count)
            );
        }

        var existingLine = OrderLines.FirstOrDefault(ol => ol.ProductId == productId);

        if (existingLine == null)
        {
            OrderLines.Add(new OrderLine(this.Id, productId, count));
        }
        else
        {
            existingLine.ChangeCount(existingLine.Count + count);
        }

        TotalItemCount += count;
    }
}

public class OrderLine : Entity
{
    public virtual Guid OrderId { get; protected set; }

    public virtual Guid ProductId { get; protected set; }

    public virtual int Count { get; protected set; }

    protected OrderLine()
    {

    }

    internal OrderLine(Guid orderId, Guid productId, int count)
    {
        OrderId = orderId;
        ProductId = productId;
        Count = count;
    }

    internal void ChangeCount(int newCount)
    {
        Count = newCount;
    }
}

2.5 服务 (Service)

根据 DDD 理论来说，每个实体或者值对象已经具有一些业务方法，为什么还需要服务对象来进行处理呢？

因为在某些情况下，某些重要的领域动作都不属于任何实体或者值对象，强行将它归纳在某一个对象里面，那么就会产生概念上的混淆。

服务都是没有自己的状态，它们除了承载领域操作以外没有其他任何意义。服务则是作为一种接口提供操作，一个良好的服务定义拥有一下几个特征。

与领域概念相关的操作不是实体或者值对象的自然组成部分。
接口是根据领域模型的其他元素定义的。
操作是无状态的。

从上述定义来看，我们的**控制器(Controller)**就符合这几个特征，尤其是无状态的定义。那么我们哪些操作能够放到服务对象当中呢？根据 DDD 理论来说，只有领域当中某个重要的过程或者转换操作不是实体或值对象的自然职责的时候，就应该添加一个独立的服务来承载这些操作。

那么问题来了，在层级架构来说，领域层的服务对象和应用层的服务对象最难以区分。以书中的例子举例，当客户余额小于某个阈值的时候，就会向客户发送电子邮件。在这里，应用服务负责通知的设置，而领域服务则需要确定客户是否满足阈值。这里就涉及到了银行领域的业务，说白了领域服务是会涉及到具体业务规则的。

下面就是书中关于不同分层当中服务对象的划分：

从上面的描述来看，领域层的应用服务就对应着 ABP vNext 框架当中的应用服务。所以我们可以将应用服务作为 API 接口暴露给前端(表现层)，因为应用服务仅仅是起一个协调领域层和基础设施层的作用。(类似脚本)

2.5.1 领域服务 (Domain Service)

上面我们了解了什么是领域服务，ABP vNext 为我们提供了领域服务的基本抽象定义 IDomainService 与 DomainService。

它们的内部实现比较简单，只注入了一些常用的基础组件，我们使用的时候直接继承 DomainService 类型即可。

public abstract class DomainService : IDomainService
{
	public IServiceProvider ServiceProvider { get; set; }
	protected readonly object ServiceProviderLock = new object();
	protected TService LazyGetRequiredService<TService>(ref TService reference)
	{
		// 比较简单的双重检查锁定模式。
		if (reference == null)
		{
			lock (ServiceProviderLock)
			{
				if (reference == null)
				{
					reference = ServiceProvider.GetRequiredService<TService>();
				}
			}
		}

		return reference;
	}

	public IClock Clock => LazyGetRequiredService(ref _clock);
	private IClock _clock;

	// Guid 生成器。
	public IGuidGenerator GuidGenerator { get; set; }

	// 日志工厂。
	public ILoggerFactory LoggerFactory => LazyGetRequiredService(ref _loggerFactory);
	private ILoggerFactory _loggerFactory;
	
	// 获取当前租户。
	public ICurrentTenant CurrentTenant => LazyGetRequiredService(ref _currentTenant);
	private ICurrentTenant _currentTenant;

	// 日志组件。
	protected ILogger Logger => _lazyLogger.Value;
	private Lazy<ILogger> _lazyLogger => new Lazy<ILogger>(() => LoggerFactory?.CreateLogger(GetType().FullName) ?? NullLogger.Instance, true);
	
	protected DomainService()
	{
		GuidGenerator = SimpleGuidGenerator.Instance;
	}
}

2.5.2 应用服务 (Application Service)

应用服务的内容比较复杂繁多，会在下一篇文章《[Abp vNext 源码分析] - 6. DDD 的应用层支持 (应用服务)》里面进行详细描述，这里就暂不进行说明。

2.6 仓储 (Repository)

仓储这个东西大家应该都不会陌生，毕竟仓储模式这玩意儿玩了这么久了，我等 Crud 码农必备利器。那么这里的仓储和 DDD 概念里面的仓储有什么异同呢？

2.6.1 背景

我们首先要明确 DDD 里面为什么会引入仓储这个概念，虽然我们可以通过遍历对象的关联来获取相关的对象，但总是要有一个起点。传统开发人员会构造一个 SQL 查询，将其传递给基础设施层的某个查询服务，然后根据得到的表/行数据重建实体对象，ORM 框架就是这样诞生的。

通过上述手段，开发人员就会试图绕开领域模型，转而直接获取或者操作它们所需要的数据，这样就会导致越来越多的领域规则被嵌入到查询代码当中。更为严重的是，开发人员将会直接查询数据库从中提取它们需要的数据，而不是通过聚合的根来得到这些对象。这样就会导致领域逻辑(业务规则)进入查询代码当中，而我们的实体和值对象最终只是存放数据的容器而已。最后我们的领域层只是一个空壳，最后使得模型无关紧要。

所以我们需要一种组件，能够通过根遍历查找对象，并且禁止其他方法对聚合内部的任何对象进行访问。而持久化的值对象可以通过遍历某个实体找到，所以值对象是不需要全局搜索的。

而仓储就能够解决上述问题，仓储可以将某种类型的所有对象表示为一个概念上的集合。开发人员只需要调用仓储对外提供的简单接口，就可以重建实体，而具体的查询、插入等技术细节完全被仓储封装。这样开发人员只需要关注领域模型。

仓储的优点有以下几点：

提供简单的模型，可用来获取持久化对象并管理它们的生命周期。
将应用程序与持久化技术解耦。
利于进行单元测试，例如使用内存数据库替换掉实际访问的数据库。

2.6.2 实现

ABP vNext 为我们提供了几种类型的仓储 IRepository、IBasicRepository、IReadOnlyRepository 等，其实从名字就可以看出来它们具体的职责。首先我们来看 IReadonly<XXX> 仓储，很明显这种类型的仓储只提供了查询方法，因为它们是只读的。

public interface IReadOnlyBasicRepository<TEntity> : IRepository
	where TEntity : class, IEntity
{
	// 获得所有实体对象。
	List<TEntity> GetList(bool includeDetails = false);

	// 获得所有实体对象。
	Task<List<TEntity>> GetListAsync(bool includeDetails = false, CancellationToken cancellationToken = default);

	// 获得实体对象的数据量。
	long GetCount();

	// 获得实体对象的数据量。
	Task<long> GetCountAsync(CancellationToken cancellationToken = default);
}

public interface IReadOnlyBasicRepository<TEntity, TKey> : IReadOnlyBasicRepository<TEntity>
	where TEntity : class, IEntity<TKey>
{
	// 根据实体的唯一标识重建对象，没有找到对象时抛出 EntityNotFoundException 异常。
	[NotNull]
	TEntity Get(TKey id, bool includeDetails = true);

	[NotNull]
	Task<TEntity> GetAsync(TKey id, bool includeDetails = true, CancellationToken cancellationToken = default);

	//  根据实体的唯一标识重建对象，没有找到对象时返回 null。
	[CanBeNull]
	TEntity Find(TKey id, bool includeDetails = true);

	Task<TEntity> FindAsync(TKey id, bool includeDetails = true, CancellationToken cancellationToken = default);
}

除了只读仓储以外，还拥有支持插入、更新、删除的仓储定义，它们都存放在 IBasicRepository 当中。在 Volo.Abp.Ddd.Domain 模块里面为我们提供了仓储类型的抽象实现 RepositoryBase 。

这个抽象基类里面我们需要注意几个基础组件：

BasicRepositoryBase 基类里面注入的 ICancellationTokenProvider 对象。
RepositoryBase 基类注入的 IDataFilter 对象。
RepositoryBase 基类注入的 ICurrentTenant 对象。

以上三个对象都不是我们讲过的组件，这里我先大概说一下它们的作用。

2.6.2.1 ICancellationTokenProvider

CancellationToken 很多人都用过，它的作用是用来取消某个耗时的异步任务。ICancellationTokenProvider 顾名思义就是 CancellationToken 的提供者，那么谁提供呢？

可以看到它有两个定义，一个是从 Http 上下文获取，一个是默认实现，首先来看一般都很简单的默认实现。

public class NullCancellationTokenProvider : ICancellationTokenProvider
{
	public static NullCancellationTokenProvider Instance { get; } = new NullCancellationTokenProvider();

	public CancellationToken Token { get; } = CancellationToken.None;

	private NullCancellationTokenProvider()
	{
		
	}
}

emmm，确实很简单，他直接返回的就是 CancellationToken.None 空值。那我们现在去看一下 Http 上下文的实现吧：

[Dependency(ReplaceServices = true)]
public class HttpContextCancellationTokenProvider : ICancellationTokenProvider, ITransientDependency
{
	public CancellationToken Token => _httpContextAccessor.HttpContext?.RequestAborted ?? CancellationToken.None;

	private readonly IHttpContextAccessor _httpContextAccessor;

	public HttpContextCancellationTokenProvider(IHttpContextAccessor httpContextAccessor)
	{
		_httpContextAccessor = httpContextAccessor;
	}
}

从上面可以看到，这个提供者是从 HttpContext 里面拿的 RequestAborted ，这个属性是哪儿来的呢？看它的说明是：

Notifies when the connection underlying this request is aborted and thus request operations should be cancelled.

Soga，这个意思就是如果一个 Http 请求被中止的时候，就会触发的取消标记哦。

那么它放在仓储基类里面干什么呢？肯定是要取消掉耗时的查询/持久化异步任务啊，不然一直等么…

2.6.2.2 IDataFilter

这个接口名字跟之前一样，很通俗，数据过滤器，用来过滤查询数据用的。使用过 ABP 框架的同学肯定知道这玩意儿，主要是用来过滤多租户和软删除标记的。

protected virtual TQueryable ApplyDataFilters<TQueryable>(TQueryable query)
	where TQueryable : IQueryable<TEntity>
{
	// 如果实体实现了软删除标记，过滤掉已删除的数据。
	if (typeof(ISoftDelete).IsAssignableFrom(typeof(TEntity)))
	{
		query = (TQueryable)query.WhereIf(DataFilter.IsEnabled<ISoftDelete>(), e => ((ISoftDelete)e).IsDeleted == false);
	}

	// 如果实体实现了多租户标记，根据租户 Id 过滤数据。
	if (typeof(IMultiTenant).IsAssignableFrom(typeof(TEntity)))
	{
		var tenantId = CurrentTenant.Id;
		query = (TQueryable)query.WhereIf(DataFilter.IsEnabled<IMultiTenant>(), e => ((IMultiTenant)e).TenantId == tenantId);
	}

	return query;
}

更加详细的我们放在后面说明…这里你只需要知道它是用来过滤数据的就行了。

2.6.2.3 ICurrentTenant

英语在学习编程的时候还是很重要的，这个接口的意思是当前租户，肯定这玩意儿就是提供当前登录用户的租户 Id 咯，在上面的例子里面有使用到。

2.6.3 仓储的注册

不论是 ABP vNext 提供的默认仓储也好，还是说我们自己定义的仓储也好，都需要注入到 IoC 容器当中。ABP vNext 为我们提供了一个仓储注册基类 RepositoryRegisterarBase<TOptions> ，查看这个基类的实现就会发现仓储的具体实现模块都实现了这个基类。

这是因为仓储肯定会有多种实现的，例如 EF Core 的仓储实现肯定有自己的一套注册机制，所以这里仅提供了一个抽象基类给开发人员。

在基类里面，ABP vNext 首先会注册自定义的仓储类型，因为从仓储的 DDD 定义来看，我们有些业务可能会需要一些特殊的仓储接口，这个时候就需要自定义仓储了。

public virtual void AddRepositories()
{
    // 遍历自定义仓储。
	foreach (var customRepository in Options.CustomRepositories)
	{
        // 调用注册方法，注册这些仓储。
		Options.Services.AddDefaultRepository(customRepository.Key, customRepository.Value);
	}

    // 是否注册 ABP vNext 生成的默认仓储。
	if (Options.RegisterDefaultRepositories)
	{
		RegisterDefaultRepositories();
	}
}

CustomRepositories 里面的仓储是通过基类 CommonDbContextRegistrationOptions 所定义的 AddRepository() 方法进行添加的。例如单元测试里面就有使用范例：

public override void ConfigureServices(ServiceConfigurationContext context)
{
	var connStr = Guid.NewGuid().ToString();

	Configure<DbConnectionOptions>(options =>
	{
		options.ConnectionStrings.Default = connStr;
	});

	// 添加自定义仓储。
	context.Services.AddMemoryDbContext<TestAppMemoryDbContext>(options =>
	{
		options.AddDefaultRepositories();
		options.AddRepository<City, CityRepository>();
	});
}

接着我们看自定义仓储是如何注册到 IoC 容器里面的呢？这里调用的 AddDefaultRepository() 方法就是在 Microsoft 文件夹里面定义的注册扩展方法。

public static IServiceCollection AddDefaultRepository(this IServiceCollection services, Type entityType, Type repositoryImplementationType)
{
	// 注册复合主键实体所对应的仓储。
	//IReadOnlyBasicRepository<TEntity>
	var readOnlyBasicRepositoryInterface = typeof(IReadOnlyBasicRepository<>).MakeGenericType(entityType);
	if (readOnlyBasicRepositoryInterface.IsAssignableFrom(repositoryImplementationType))
	{
		services.TryAddTransient(readOnlyBasicRepositoryInterface, repositoryImplementationType);

		//IReadOnlyRepository<TEntity>
		var readOnlyRepositoryInterface = typeof(IReadOnlyRepository<>).MakeGenericType(entityType);
		if (readOnlyRepositoryInterface.IsAssignableFrom(repositoryImplementationType))
		{
			services.TryAddTransient(readOnlyRepositoryInterface, repositoryImplementationType);
		}

		//IBasicRepository<TEntity>
		var basicRepositoryInterface = typeof(IBasicRepository<>).MakeGenericType(entityType);
		if (basicRepositoryInterface.IsAssignableFrom(repositoryImplementationType))
		{
			services.TryAddTransient(basicRepositoryInterface, repositoryImplementationType);

			//IRepository<TEntity>
			var repositoryInterface = typeof(IRepository<>).MakeGenericType(entityType);
			if (repositoryInterface.IsAssignableFrom(repositoryImplementationType))
			{
				services.TryAddTransient(repositoryInterface, repositoryImplementationType);
			}
		}
	}

	// 首先获得实体的主键类型，再进行注册。
	var primaryKeyType = EntityHelper.FindPrimaryKeyType(entityType);
	if (primaryKeyType != null)
	{
		//IReadOnlyBasicRepository<TEntity, TKey>
		var readOnlyBasicRepositoryInterfaceWithPk = typeof(IReadOnlyBasicRepository<,>).MakeGenericType(entityType, primaryKeyType);
		if (readOnlyBasicRepositoryInterfaceWithPk.IsAssignableFrom(repositoryImplementationType))
		{
			services.TryAddTransient(readOnlyBasicRepositoryInterfaceWithPk, repositoryImplementationType);

			//IReadOnlyRepository<TEntity, TKey>
			var readOnlyRepositoryInterfaceWithPk = typeof(IReadOnlyRepository<,>).MakeGenericType(entityType, primaryKeyType);
			if (readOnlyRepositoryInterfaceWithPk.IsAssignableFrom(repositoryImplementationType))
			{
				services.TryAddTransient(readOnlyRepositoryInterfaceWithPk, repositoryImplementationType);
			}

			//IBasicRepository<TEntity, TKey>
			var basicRepositoryInterfaceWithPk = typeof(IBasicRepository<,>).MakeGenericType(entityType, primaryKeyType);
			if (basicRepositoryInterfaceWithPk.IsAssignableFrom(repositoryImplementationType))
			{
				services.TryAddTransient(basicRepositoryInterfaceWithPk, repositoryImplementationType);

				//IRepository<TEntity, TKey>
				var repositoryInterfaceWithPk = typeof(IRepository<,>).MakeGenericType(entityType, primaryKeyType);
				if (repositoryInterfaceWithPk.IsAssignableFrom(repositoryImplementationType))
				{
					services.TryAddTransient(repositoryInterfaceWithPk, repositoryImplementationType);
				}
			}
		}
	}

	return services;
}

上面代码没什么好说的，只是根据不同的类型来进行不同的注册而已。

以上是注册我们自定义的仓储类型，只要开发人员调用过 AddDefaultRepositories() 方法，那么 ABP vNext 会为每个不同的实体注册响应的默认仓库。

public ICommonDbContextRegistrationOptionsBuilder AddDefaultRepositories(bool includeAllEntities = false)
{
    // 可以看到将参数设置为 true 了。
	RegisterDefaultRepositories = true;
	IncludeAllEntitiesForDefaultRepositories = includeAllEntities;

	return this;
}

默认仓库仅包含基础仓储所定义的增删改查等方法，开发人员只需要注入相应的接口就能够直接使用。既然要为每个实体类型注入对应的默认仓储，肯定就需要知道当前项目有多少个实体，并获得它们的类型定义。

这里我们基类仅仅是调用抽象方法 GetEntityTypes() ，然后根据具体实现返回的类型定义来注册默认仓储。

protected virtual void RegisterDefaultRepositories()
{
	foreach (var entityType in GetEntityTypes(Options.OriginalDbContextType))
	{
        // 判断该实体类型是否需要注册默认仓储。
		if (!ShouldRegisterDefaultRepositoryFor(entityType))
		{
			continue;
		}

        // 为实体对象注册相应的默认仓储，这里仍然调用之前的扩展方法进行注册。
		RegisterDefaultRepository(entityType);
	}
}

找到 EF Core 定义的仓储注册器，就能够看到他是通过遍历 DbContext 里面的属性来获取所有实体类型定义的。

public static IEnumerable<Type> GetEntityTypes(Type dbContextType)
{
	return
		from property in dbContextType.GetTypeInfo().GetProperties(BindingFlags.Public | BindingFlags.Instance)
		where
			ReflectionHelper.IsAssignableToGenericType(property.PropertyType, typeof(DbSet<>)) &&
			typeof(IEntity).IsAssignableFrom(property.PropertyType.GenericTypeArguments[0])
		select property.PropertyType.GenericTypeArguments[0];
}

最后的最后，这个注册器在什么时候被调用的呢？注册器一般是在项目的基础设施模块当中进行调用，这里以单元测试的代码为例，它是使用的 EF Core 作为持久层的基础设施。

[DependsOn(typeof(AbpEntityFrameworkCoreModule))]
public class AbpEfCoreTestSecondContextModule : AbpModule
{
	public override void ConfigureServices(ServiceConfigurationContext context)
	{
		// 注意这里。
		context.Services.AddAbpDbContext<SecondDbContext>(options =>
		{
			options.AddDefaultRepositories();
		});

		// 注意这里。
		context.Services.AddAbpDbContext<ThirdDbContext.ThirdDbContext>(options =>
		{
			options.AddDefaultRepositories<IThirdDbContext>();
		});
	}
}

跳转到 ABP vNext 提供的 EF Core模块，找到 AddAbpDbContext() 方法当中，发现了仓储注册器。

public static class AbpEfCoreServiceCollectionExtensions
{
	public static IServiceCollection AddAbpDbContext<TDbContext>(
		this IServiceCollection services, 
		Action<IAbpDbContextRegistrationOptionsBuilder> optionsBuilder = null)
		where TDbContext : AbpDbContext<TDbContext>
	{
		services.AddMemoryCache();

		var options = new AbpDbContextRegistrationOptions(typeof(TDbContext), services);
		optionsBuilder?.Invoke(options);

		services.TryAddTransient(DbContextOptionsFactory.Create<TDbContext>);

		foreach (var dbContextType in options.ReplacedDbContextTypes)
		{
			services.Replace(ServiceDescriptor.Transient(dbContextType, typeof(TDbContext)));
		}

        // 在这里。
		new EfCoreRepositoryRegistrar(options).AddRepositories();

		return services;
	}
}

2.7 领域事件

在 ABP vNext 中，除了本地事件总线以外，还为我们提供了基于 Rabbit MQ 的分布式事件总线。关于事件总线的内容，这里就不再详细赘述，后面会有专门的文章讲解事件总线的相关知识。

在这里，主要提一下什么是领域事件。其实领域事件与普通的事件并没什么本质上的不同，只是它们触发的地方和携带的参数有点特殊罢了。并且按照聚合的特性来说，其实聚合与聚合之间的通讯，主要是通过领域事件来实现的。

这里的领域事件都是针对于实体产生变更时需要被触发的事件，例如我们有一个学生实体，在它被修改之后，ABP vNext 框架就会触发一个实体更新事件。

触发领域事件这些动作都被封装在 EntityChangeEventHelper 里面，以刚才的例子来说，我们可以看到它会触发以下代码：

public virtual async Task TriggerEntityUpdatedEventOnUowCompletedAsync(object entity)
{
    // 触发本地事件总线。
	await TriggerEventWithEntity(
		LocalEventBus,
		typeof(EntityUpdatedEventData<>),
		entity,
		false
	);

	var eto = EntityToEtoMapper.Map(entity);
	if (eto != null)
	{
        // 触发分布式事件总线。
		await TriggerEventWithEntity(
			DistributedEventBus,
			typeof(EntityUpdatedEto<>),
			eto,
			false
		);
	}
}

关于领域事件其他的细节就不再描述，如果大家想要更加全面的了解，请直接阅读 ABP vNext 的相关源码。

三、总结

本篇文章更多的注重 DDD 理论，关于 ABP vNext 的技术实现细节并未体现在当前模块，后续我会在其他章节注重描述关于上述 DDD 概念的技术实现。