新增移除常量字段 pass的文档

Author: pirunxi

docs/manual/configuration.md

@@ -121,6 +121,14 @@ Obfuz提供了极其丰富的配置选项和灵活的混淆规则配置文件，
 |Encryption level|加密级别，取值范围为`[1, 4]`,默认为1。 加密级别越高，加密越复杂，解密也会越耗时。|
 |Rule Files| 加密规则文件列表。可以为0到多个。如果为空会对所有常量进行混淆。详细配置规则见[常量混淆](./const-encryption)。|
 
+### Remove Const Field Settings
+
+移除const常量字段相关设置。支持通过规则文件精细地控制要保留哪些const字段。补充文档见[移除常量字段](./remove-const-field)。
+
+|选项|描述|
+|-|-|
+|Rule Files| 加密规则文件列表。可以为0到多个。如果为空会对所有常量进行混淆。详细配置规则见[移除常量字段](./remove-const-field)。|
+
 ### Eval Stack Obfus Settings
 
 执行栈的混淆设置。支持通过规则文件非常精细地控制范围和加密效果。补充文档见[执行栈混淆](./eval-stack-obfuscation)。

docs/manual/field-encryption.md

@@ -78,8 +78,8 @@ class A
 <obfuz>
     <assembly name="Obfus1">
         <type name="*">
-            <field name="a" encrypt="1"/>
-            <field name="a" encrypt="0"/>
+            <field name="a"/>
+            <field name="b"/>
         </type>
     </assembly>
 </obfuz>
@@ -108,5 +108,4 @@ assembly的子元素只能为type。
 
 |属性|可空|默认值|描述|
 |-|-|-|-|
-|name|否||类型名的通配字符串，如果为空表示匹配所有类型|
-|encrypt|是|0|是否加密此字段|
+|name|否||被加密的字段名。字段名的通配字符串，如果为空表示匹配所有类型|

docs/manual/obfuscation-pass.md

@@ -22,6 +22,7 @@ Obfuz的混淆（或加密）流程的执行方式为先判定对目标是否启
 
 - Symbol Obfuscation（符号混淆）
 - Const Encryption（常量加密）
+- Remove Const Field （移除const常量字段）
 - Eval Stack Obfusaction （局部与临时变量混淆）
 - Expr Obfusaction （表达式混淆）
 - Field Encryption（字段加密）
@@ -32,8 +33,6 @@ Obfuz的混淆（或加密）流程的执行方式为先判定对目标是否启
 
 后续将会支持的Obfuscation Pass有：
 
-- Expression Obfusaction（表达式混淆）
-- ControlFlow Obfuscation（控制流混淆）
 - 加水印
 - Anti-Debugger、Anti-Damper、Anti-Dumping
 
@@ -100,7 +99,7 @@ enable与disable属性用于设置当前规则中开启或者禁用哪些Pass。
 
 - 如果值以`+`开关，则表示是在父节点上启用的pass上进行增量修改。
 - 如果没有以`+`开启，则表示在`ObfuscationPassSettings.EnabledPasses`的值的基础上启用或者禁用某些Pass。
-- PASS_NAME的取值可以为`ConstEncrypt、FieldEncrypt、SymbolObfus、CallObfus、ExprObfus、ControlFlowObfus、EvalStackObfus`等Pass类型。详见`Obfuz.ObfusPasses.ObfuscationPassType`类定义。
+- PASS_NAME的取值可以为`ConstEncrypt、RemoveConstField、FieldEncrypt、SymbolObfus、CallObfus、ExprObfus、ControlFlowObfus、EvalStackObfus`等Pass类型。详见`Obfuz.ObfusPasses.ObfuscationPassType`类定义。
 
 例如，假设EnabledPass=`SymbolObfus|ConstEncrypt|FieldEncrypt`，使用以下配置。
 

docs/manual/remove-const-field.md

@@ -0,0 +1,77 @@
+# 移除常量字段
+
+const常量字段大多数情况下只在源码中有意义，编译为dll时会inline对常量字段的访问，即编译后的代码并不会引用const字段。
+因此移除const字段并不会引发代码错误，除非需要反射访问该字段。
+
+移除const字段可以减少混淆后的代码的有效信息，因此混淆时默认会移除这些字段。
+
+## 设置
+
+`ObfuzSettings.RemoveConstFieldSettings`中包含相关设置，详细见文档[设置](./configuration)。
+
+## `[ObfuzIgnore]`
+
+被`[ObfuzIgnore(ObfuzScope.Field)]`影响的常量字段不会被移除。
+
+例如下面的ConstEncryptTestClass类的removedField会被移除，而preservedField和preservedField2字段都会被保留。
+
+```csharp
+    class ConstEncryptTestClass
+    {
+        // This const field should be removed by the obfuscator.
+        public const int removedField = 1;
+
+        [ObfuzIgnore(ObfuzScope.Field)]
+        public const int preservedField = 2;
+
+        [ObfuzIgnore]
+        public const int preservedField2 = 2;
+    }
+```
+
+## 规则文件
+
+支持通过规则文件精细地控制保留哪些常量字段。`RemoveConstFieldSettings.RuleFiles`选项中可以配置0-N个规则文件。
+规则文件的相对路径为项目目录，有效的规则文件路径类似这样：`Assets/XXX/YYY.xml`。
+
+出现在规则文件中的字段**不会被移除**。
+
+配置示例如下：
+
+```xml
+
+<?xml version="1.0" encoding="UTF-8"?>
+
+<obfuz>
+    <assembly name="Obfus1">
+        <type name="Tests.RemoveConstField.ConstEncryptTestClass">
+            <field name="preservedField2"/>
+        </type>
+    </assembly>
+</obfuz>
+```
+
+- 顶层tag必须是obfuz
+- 次级tag必须是assembly
+
+### assembly
+
+|属性|可空|默认值|描述|
+|-|-|-|-|
+|name|否||程序集名，必须在混淆程序集列表中|
+
+assembly的子元素只能为type。
+
+### type
+
+|属性|可空|默认值|描述|
+|-|-|-|-|
+|name|否||类型名的通配字符串，如果为空表示匹配所有类型。嵌套类型使用`/`划分声明所在类型和被包围的子类型，如`test.ClassA/ClassB`。|
+
+由于字段加密只能作用于字段，因此type的子元素只能为field。
+
+### field
+
+|属性|可空|默认值|描述|
+|-|-|-|-|
+|name|否||要保留的常量字段名。字段名的通配字符串，如果为空表示匹配所有类型。|

sidebars.ts

@@ -59,6 +59,7 @@ const sidebars: SidebarsConfig = {
         'manual/obfuscation-instincts',
         'manual/symbol-obfuscation',
         'manual/const-encryption',
+        'manual/remove-const-field',
         'manual/field-encryption',
         'manual/eval-stack-obfuscation',
         'manual/expr-obfuscation',