返回提交历史
Modified
README.md
+237
-67
Added
README_zh.md
+356
-0
Modified
XFEExtension.NetCore.AutoConfig/XFEExtension.NetCore.AutoConfig.csproj
+4
-0
XFEstudio/XFEExtension.NetCore.AutoConfig
docs: update Chinese README, add English README with badges and API docs
Agent-Logs-Url: https://github.com/XFEstudio/XFEExtension.NetCore.AutoConfig/sessions/a61d1f59-f37b-408e-b652-4fa83f0194b9 Co-authored-by: XFEstudio <132526994+XFEstudio@users.noreply.github.com>
4e74d4e
代码差异
3 个文件
+597
-67
@@ -1,86 +1,175 @@
1
1
# XFEExtension.NetCore.AutoConfig
2
2
3
## 描述
3
[](https://www.nuget.org/packages/XFEExtension.NetCore.AutoConfig/)
4
[](https://www.nuget.org/packages/XFEExtension.NetCore.AutoConfig/)
5
[](https://opensource.org/licenses/MIT)
6
[](https://dotnet.microsoft.com/download/dotnet/8.0)
4
7
5
XFEExtension.NetCore.AutoConfig是一个可以自动实现配置文件存储的工具
8
English | [中文](README_zh.md)
6
9
7
## 自动实现配置文件的存储
10
## Description
8
11
9
#### 基础用法
12
XFEExtension.NetCore.AutoConfig is a .NET library powered by Roslyn incremental source generators. It automatically generates static properties, load/save methods, and persistence logic for any `partial` class that inherits from `XFEProfile`, eliminating the need to write boilerplate configuration code.
13
14
## Getting Started
15
16
### Installation
17
18
```shell
19
dotnet add package XFEExtension.NetCore.AutoConfig
20
```
21
22
### Basic Usage
23
24
Annotate fields with `[ProfileProperty]`. The source generator will create a corresponding static property that automatically saves whenever it is assigned:
10
25
11
26
```csharp
12
//创建配置文件类
27
// Define a profile class
28
[AutoLoadProfile]
13
29
partial class SystemProfile : XFEProfile
14
30
{
15
31
[ProfileProperty]
16
string name;
32
string name = string.Empty;
17
33
18
34
[ProfileProperty]
19
35
int _age;
20
36
}
21
37
22
//使用配置文件
38
// Use the profile
23
39
class Program
24
40
{
25
41
static void Main(string[] args)
26
42
{
27
SystemProfile.Name = "Test";//在设置值的时候会自动记录并储存
28
//SystemProfile.Age = 1;
43
SystemProfile.Name = "Test"; // Automatically saved on assignment
29
44
Console.WriteLine(SystemProfile.Name);
30
Console.WriteLine(SystemProfile.Age);//下次打开程序会自动读取上次程序退出时储存的值
45
Console.WriteLine(SystemProfile.Age); // Restored from disk on next run
31
46
}
32
47
}
33
48
```
34
49
35
#### 修改存储格式
50
> **Note:** The `[AutoLoadProfile]` attribute instructs the framework to call `LoadProfile()` inside the static constructor, so the configuration is restored automatically when the program starts.
51
52
---
53
54
## Detailed Usage
55
56
### Changing the Storage Format
57
58
Set `DefaultProfileOperationMode` inside the instance constructor to switch the storage format. The file extension is updated automatically:
36
59
37
60
```csharp
38
//配置文件类
61
[AutoLoadProfile]
39
62
partial class SystemProfile : XFEProfile
40
63
{
41
64
[ProfileProperty]
42
string name;
65
string name = string.Empty;
43
66
44
67
[ProfileProperty]
45
68
int _age;
46
69
47
70
public SystemProfile()
48
71
{
49
DefaultProfileOperationMode = ProfileOperationMode.Xml; // 改用XML格式存储配置文件，文件扩展名会自动更改为.xml
72
DefaultProfileOperationMode = ProfileOperationMode.Xml; // Switch to XML; extension becomes .xml
73
// Available modes: XFEDictionary (default), Json, Xml, Custom
50
74
}
51
75
}
52
76
```
53
77
54
#### 自定义存储路径、文件扩展名和存储方法
78
### Custom Storage Path and File Extension
79
80
Use the generated static properties `ProfilePath` and `ProfileExtension` to control where the file is stored:
55
81
56
82
```csharp
57
//配置文件类
83
[AutoLoadProfile]
58
84
partial class SystemProfile : XFEProfile
59
85
{
60
86
[ProfileProperty]
61
string name;
87
string name = string.Empty;
62
88
63
89
[ProfileProperty]
64
90
int _age;
65
91
66
92
public SystemProfile()
67
93
{
68
DefaultProfileOperationMode = ProfileOperationMode.Custom; // 设置为自定义存储方法
69
ProfilePath = $"MyPath/MySubPath/{nameof(SystemProfile)}"; // 设置路径为MyPath/MySubPath/SystemProfile
70
ProfileExtension = ".ini"; // 设置文件扩展名为.ini文件
71
LoadOperation = (profileInstance, profileString, propertyInfoDictionary, propertySetFuncDictionary) => return XXX; // 自定义配置文件的加载方法，使用Lambda表达式
72
SaveOperation = MyCustomSaveProfileOperation; // 自定义配置文件的保存方法，使用已有的方法
94
ProfilePath = $"MyPath/MySubPath/{nameof(SystemProfile)}"; // Path without extension
95
ProfileExtension = ".ini"; // Custom file extension
73
96
}
97
}
98
```
99
100
> `ProfilePath` and `ProfileExtension` are generated static properties and can also be set from outside the class:
101
> ```csharp
102
> SystemProfile.ProfilePath = "custom/path/SystemProfile";
103
> SystemProfile.ProfileExtension = ".cfg";
104
> ```
105
106
### Using the `[ProfilePath]` Attribute
107
108
```csharp
109
[AutoLoadProfile]
110
[ProfilePath("MyPath/MySubPath/SystemProfile")]
111
partial class SystemProfile : XFEProfile
112
{
113
[ProfileProperty]
114
string name = string.Empty;
74
115
75
// 自定义的配置文件保存方法
76
public static string MyCustomSaveProfileOperation(XFEProfile profileInstance, Dictionary<string, Type> propertyInfoDictionary, Dictionary<string, GetValueDelegate> propertyGetFuncDictionary) => return XXX;
116
[ProfileProperty]
117
int _age;
77
118
}
78
119
```
79
120
80
#### 使用ProfileList和ProfileDictionary来储存集合或字典
121
### Custom Load and Save Operations
122
123
Set `DefaultProfileOperationMode` to `Custom` and provide your own load/save delegates:
81
124
82
125
```csharp
83
//配置文件类
126
[AutoLoadProfile]
127
partial class SystemProfile : XFEProfile
128
{
129
[ProfileProperty]
130
string name = string.Empty;
131
132
[ProfileProperty]
133
int _age;
134
135
public SystemProfile()
136
{
137
DefaultProfileOperationMode = ProfileOperationMode.Custom;
138
ProfilePath = $"MyPath/MySubPath/{nameof(SystemProfile)}";
139
ProfileExtension = ".ini";
140
LoadOperation = MyCustomLoadProfileOperation;
141
SaveOperation = MyCustomSaveProfileOperation;
142
}
143
144
// Custom load method
145
public static XFEProfile? MyCustomLoadProfileOperation(
146
XFEProfile profileInstance,
147
string profileString,
148
Dictionary<string, Type> propertyInfoDictionary,
149
Dictionary<string, SetValueDelegate> propertySetFuncDictionary)
150
{
151
// Implement custom load logic here
152
return null;
153
}
154
155
// Custom save method
156
public static string MyCustomSaveProfileOperation(
157
XFEProfile profileInstance,
158
Dictionary<string, Type> propertyInfoDictionary,
159
Dictionary<string, GetValueDelegate> propertyGetFuncDictionary)
160
{
161
// Implement custom save logic here
162
return string.Empty;
163
}
164
}
165
```
166
167
### Storing Collections with `ProfileList` and `ProfileDictionary`
168
169
`ProfileList<T>` and `ProfileDictionary<TKey, TValue>` automatically trigger a save whenever the collection is modified (add, remove, clear, etc.):
170
171
```csharp
172
[AutoLoadProfile]
84
173
partial class SystemProfile : XFEProfile
85
174
{
86
175
[ProfileProperty]
@@ -94,100 +183,181 @@ partial class SystemProfile : XFEProfile
94
183
ProfileDictionary<string, long> nameIdDictionary = [];
95
184
}
96
185
97
//使用配置文件
98
186
class Program
99
187
{
100
188
static void Main(string[] args)
101
189
{
102
SystemProfile.NameList.Add("张三"); //在添加值的时候会自动记录并储存
103
SystemProfile.NameList.AddRange(["李四", "王五"]); //添加多条记录
104
SystemProfile.NameList.Remove("李四"); //删除值的时候也会自动记录
105
SystemProfile.NameIdDictionary.Add("张三", "0da87wd89a-0dwa8d"); //字典也是一样
190
SystemProfile.NameList.Add("Alice"); // Auto-saved on add
191
SystemProfile.NameList.AddRange(["Bob", "Carol"]); // Batch add
192
SystemProfile.NameList.Remove("Bob"); // Auto-saved on remove
193
SystemProfile.NameIdDictionary.Add("Alice", 100L); // Dictionary works the same way
106
194
}
107
195
}
108
196
```
109
197
110
#### 设置get和set方法
198
### Injecting Code into `get`/`set` Accessors
199
200
Use `[ProfilePropertyAddGet]` and `[ProfilePropertyAddSet]` to insert code snippets directly into the generated property accessors:
111
201
112
202
```csharp
203
[AutoLoadProfile]
113
204
partial class SystemProfile : XFEProfile
114
205
{
115
206
[ProfileProperty]
116
[ProfilePropertyAddGet(@"Console.WriteLine(""获取了Name"")")]
207
[ProfilePropertyAddGet(@"Console.WriteLine(""Getting Name"")")]
117
208
[ProfilePropertyAddGet("return Current.name")]
118
[ProfilePropertyAddSet(@"Console.WriteLine(""设置了Name"")")]
209
[ProfilePropertyAddSet(@"Console.WriteLine(""Setting Name"")")]
119
210
[ProfilePropertyAddSet("Current.name = value")]
120
211
string name = string.Empty;
121
212
122
213
[ProfileProperty]
123
[ProfilePropertyAddGet(@"Console.WriteLine(""获取了Age"")")]
214
[ProfilePropertyAddGet(@"Console.WriteLine(""Getting Age"")")]
124
215
[ProfilePropertyAddGet("return Current._age")]
125
[ProfilePropertyAddSet(@"Console.WriteLine(""设置了Age"")")]
216
[ProfilePropertyAddSet(@"Console.WriteLine(""Setting Age"")")]
126
217
[ProfilePropertyAddSet("Current._age = value")]
127
218
int _age;
128
219
}
129
220
```
130
221
131
#### 设置初始值
222
> **Note:** When using `[ProfilePropertyAddGet]`, you must handle the full `return` statement yourself in the last `get` snippet.
223
224
### Partial Method Hooks
225
226
The generator creates `static partial void GetXxxProperty()` and `static partial void SetXxxProperty(ref T value)` for each property. Implement them in your own partial class to intercept reads and writes:
132
227
133
228
```csharp
229
[AutoLoadProfile]
134
230
partial class SystemProfile : XFEProfile
135
231
{
136
232
[ProfileProperty]
137
string name = "John Wick";
233
string name = string.Empty;
138
234
139
235
[ProfileProperty]
140
int _age = 59;
236
int _age;
237
238
static partial void GetNameProperty()
239
{
240
Console.WriteLine("Name was read");
241
}
242
243
static partial void SetNameProperty(ref string value)
244
{
245
Console.WriteLine($"Name changing: {Name} -> {value}");
246
}
247
248
static partial void GetAgeProperty()
249
{
250
Console.WriteLine("Age was read");
251
}
252
253
static partial void SetAgeProperty(ref int value)
254
{
255
value = 1999; // Modify the value before it is stored
256
Console.WriteLine($"Age forced to 1999");
257
}
141
258
}
142
259
```
143
260
144
#### 为属性添加注释
261
### Default Field Values
262
263
Assign values directly at the field declaration site:
145
264
146
265
```csharp
266
[AutoLoadProfile]
147
267
partial class SystemProfile : XFEProfile
148
268
{
149
/// <summary>
150
/// 名称
151
/// 这段注释会自动添加至自动生成的Name属性上
152
/// </summary>
153
269
[ProfileProperty]
154
string name;
270
string name = "John Wick";
155
271
156
272
[ProfileProperty]
157
int _age;
273
int _age = 59;
158
274
}
159
275
```
160
276
161
#### 使用部分方法来设置get和set方法
277
### XML Documentation Comments
278
279
XML doc comments placed on a field are automatically propagated to the generated static property:
162
280
163
281
```csharp
282
[AutoLoadProfile]
164
283
partial class SystemProfile : XFEProfile
165
284
{
285
/// <summary>
286
/// The user's name. This comment is copied to the generated Name property.
287
/// </summary>
166
288
[ProfileProperty]
167
string name;
289
string name = string.Empty;
168
290
169
291
[ProfileProperty]
170
292
int _age;
293
}
294
```
171
295
172
static partial void GetNameProperty()
173
{
174
Console.WriteLine("获取了Name");
175
}
296
### Manual Load / Save / Delete / Export / Import
176
297
177
static partial void SetNameProperty(ref string value)
178
{
179
Console.WriteLine($"设置了Name：从{Name}变为了{value}");
180
}
298
The following static methods are generated for every profile class:
181
299
182
static partial void GetAgeProperty()
183
{
184
Console.WriteLine("获取了Age");
185
}
300
```csharp
301
SystemProfile.LoadProfile(); // Load from file
302
SystemProfile.SaveProfile(); // Save to file
303
SystemProfile.DeleteProfile(); // Delete the config file
304
string exported = SystemProfile.ExportProfile(); // Export config as a string
305
SystemProfile.ImportProfile(exported); // Import config from a string
306
```
186
307
187
static partial void SetAgeProperty(ref int value)
188
{
189
value = 1999; // 可以直接设置值
190
Console.WriteLine($"设置了Age：从{Age}变为了1999");
191
}
192
}
193
```
308
---
309
310
## API Reference
311
312
### Attributes
313
314
| Attribute | Target | Description |
315
|-----------|--------|-------------|
316
| `[ProfileProperty]` | Field | Marks the field for code generation. Optionally specify a property name: `[ProfileProperty("CustomName")]` |
317
| `[ProfilePropertyAddGet(code)]` | Field | Appends a code line to the generated `get` accessor. Supports multiple attributes. |
318
| `[ProfilePropertyAddSet(code)]` | Field | Appends a code line to the generated `set` accessor. Supports multiple attributes. |
319
| `[AutoLoadProfile]` | Class | Calls `LoadProfile()` automatically in the static constructor. |
320
| `[ProfilePath(path)]` | Class | Sets the storage path for the config file. |
321
322
### Storage Modes (`ProfileOperationMode`)
323
324
| Value | Extension | Description |
325
|-------|-----------|-------------|
326
| `XFEDictionary` (default) | `.xpf` | XFE dictionary format |
327
| `Json` | `.json` | JSON serialization |
328
| `Xml` | `.xml` | XML serialization |
329
| `Custom` | custom | User-provided load/save delegates |
330
331
### Auto-Generated Static Members
332
333
For every `partial` class that inherits `XFEProfile` and uses `[ProfileProperty]`, the source generator produces:
334
335
| Member | Kind | Description |
336
|--------|------|-------------|
337
| `Current` | `static T` | The singleton profile instance |
338
| `ProfilePath` | `static string` | Storage path (without extension) |
339
| `ProfileExtension` | `static string` | File extension (auto-detected when empty) |
340
| `LoadProfile()` | `static void` | Loads config from file |
341
| `SaveProfile()` | `static void` | Saves config to file |
342
| `DeleteProfile()` | `static void` | Deletes the config file |
343
| `ExportProfile()` | `static string` | Exports config as a string |
344
| `ImportProfile(string)` | `static void` | Imports config from a string |
345
| `XxxProperty` (per field) | `static T` | Auto-generated static property; saves on set |
346
| `InstanceXxx` (per field) | `T` (instance) | Corresponding instance property |
347
| `GetXxxProperty()` | `static partial void` | Invoked when the property is read |
348
| `SetXxxProperty(ref T)` | `static partial void` | Invoked when the property is written |
349
350
### `XFEProfile` Base Class Members
351
352
| Member | Kind | Description |
353
|--------|------|-------------|
354
| `DefaultProfileOperationMode` | `ProfileOperationMode` | Load/save mode |
355
| `LoadOperation` | `ProfileLoadOperation` | Custom load delegate |
356
| `SaveOperation` | `ProfileSaveOperation` | Custom save delegate |
357
| `ProfilesDefaultPath` | `static string` | Default root directory for all profile files |
358
359
---
360
361
## License
362
363
This project is licensed under the [MIT License](LICENSE.txt).
@@ -0,0 +1,356 @@
1
# XFEExtension.NetCore.AutoConfig
2
3
[](https://www.nuget.org/packages/XFEExtension.NetCore.AutoConfig/)
4
[](https://www.nuget.org/packages/XFEExtension.NetCore.AutoConfig/)
5
[](https://opensource.org/licenses/MIT)
6
[](https://dotnet.microsoft.com/download/dotnet/8.0)
7
8
[English](README.md) | 中文
9
10
## 描述
11
12
XFEExtension.NetCore.AutoConfig 是一个基于 Roslyn 增量源生成器的 .NET 库，可以自动为继承自 `XFEProfile` 的配置文件类生成属性、加载/保存方法，实现配置文件的自动持久化存储。
13
14
## 快速开始
15
16
### 安装
17
18
```shell
19
dotnet add package XFEExtension.NetCore.AutoConfig
20
```
21
22
### 基础用法
23
24
为字段添加 `[ProfileProperty]` 特性，框架将自动生成对应的静态属性，并在赋值时自动保存配置：
25
26
```csharp
27
// 创建配置文件类
28
[AutoLoadProfile]
29
partial class SystemProfile : XFEProfile
30
{
31
[ProfileProperty]
32
string name = string.Empty;
33
34
[ProfileProperty]
35
int _age;
36
}
37
38
// 使用配置文件
39
class Program
40
{
41
static void Main(string[] args)
42
{
43
SystemProfile.Name = "Test"; // 赋值时自动保存
44
Console.WriteLine(SystemProfile.Name);
45
Console.WriteLine(SystemProfile.Age); // 下次启动自动读取上次保存的值
46
}
47
}
48
```
49
50
> **说明：** `[AutoLoadProfile]` 特性会让框架在静态构造函数中自动调用 `LoadProfile()`，程序启动时无需手动加载。
51
52
---
53
54
## 详细用法
55
56
### 修改存储格式
57
58
通过在实例构造函数中设置 `DefaultProfileOperationMode` 来更改存储格式，文件扩展名会自动更改：
59
60
```csharp
61
[AutoLoadProfile]
62
partial class SystemProfile : XFEProfile
63
{
64
[ProfileProperty]
65
string name = string.Empty;
66
67
[ProfileProperty]
68
int _age;
69
70
public SystemProfile()
71
{
72
DefaultProfileOperationMode = ProfileOperationMode.Xml; // 改用 XML 格式，扩展名自动变为 .xml
73
// 可选值：ProfileOperationMode.XFEDictionary（默认）、Json、Xml、Custom
74
}
75
}
76
```
77
78
### 自定义存储路径和文件扩展名
79
80
通过静态属性 `ProfilePath` 和 `ProfileExtension` 自定义存储位置：
81
82
```csharp
83
[AutoLoadProfile]
84
partial class SystemProfile : XFEProfile
85
{
86
[ProfileProperty]
87
string name = string.Empty;
88
89
[ProfileProperty]
90
int _age;
91
92
public SystemProfile()
93
{
94
ProfilePath = $"MyPath/MySubPath/{nameof(SystemProfile)}"; // 自定义路径（不含扩展名）
95
ProfileExtension = ".ini"; // 自定义文件扩展名
96
}
97
}
98
```
99
100
> `ProfilePath` 和 `ProfileExtension` 均为框架自动生成的静态属性，也可在类外部直接赋值：
101
> ```csharp
102
> SystemProfile.ProfilePath = "custom/path/SystemProfile";
103
> SystemProfile.ProfileExtension = ".cfg";
104
> ```
105
106
### 使用 `[ProfilePath]` 特性指定存储路径
107
108
```csharp
109
[AutoLoadProfile]
110
[ProfilePath("MyPath/MySubPath/SystemProfile")]
111
partial class SystemProfile : XFEProfile
112
{
113
[ProfileProperty]
114
string name = string.Empty;
115
116
[ProfileProperty]
117
int _age;
118
}
119
```
120
121
### 自定义存储方法
122
123
将 `DefaultProfileOperationMode` 设为 `Custom`，并自行提供加载和保存方法：
124
125
```csharp
126
[AutoLoadProfile]
127
partial class SystemProfile : XFEProfile
128
{
129
[ProfileProperty]
130
string name = string.Empty;
131
132
[ProfileProperty]
133
int _age;
134
135
public SystemProfile()
136
{
137
DefaultProfileOperationMode = ProfileOperationMode.Custom;
138
ProfilePath = $"MyPath/MySubPath/{nameof(SystemProfile)}";
139
ProfileExtension = ".ini";
140
LoadOperation = MyCustomLoadProfileOperation;
141
SaveOperation = MyCustomSaveProfileOperation;
142
}
143
144
// 自定义加载方法
145
public static XFEProfile? MyCustomLoadProfileOperation(XFEProfile profileInstance, string profileString, Dictionary<string, Type> propertyInfoDictionary, Dictionary<string, SetValueDelegate> propertySetFuncDictionary)
146
{
147
// 在此实现自定义加载逻辑
148
return null;
149
}
150
151
// 自定义保存方法
152
public static string MyCustomSaveProfileOperation(XFEProfile profileInstance, Dictionary<string, Type> propertyInfoDictionary, Dictionary<string, GetValueDelegate> propertyGetFuncDictionary)
153
{
154
// 在此实现自定义保存逻辑
155
return string.Empty;
156
}
157
}
158
```
159
160
### 使用 `ProfileList` 和 `ProfileDictionary` 存储集合
161
162
`ProfileList<T>` 和 `ProfileDictionary<TKey, TValue>` 在集合发生变更（添加、删除等操作）时会自动触发保存：
163
164
```csharp
165
[AutoLoadProfile]
166
partial class SystemProfile : XFEProfile
167
{
168
[ProfileProperty]
169
[ProfilePropertyAddGet("Current.nameList.CurrentProfile = Current")]
170
[ProfilePropertyAddGet("return Current.nameList")]
171
ProfileList<string> nameList = [];
172
173
[ProfileProperty]
174
[ProfilePropertyAddGet("Current.nameIdDictionary.CurrentProfile = Current")]
175
[ProfilePropertyAddGet("return Current.nameIdDictionary")]
176
ProfileDictionary<string, long> nameIdDictionary = [];
177
}
178
179
class Program
180
{
181
static void Main(string[] args)
182
{
183
SystemProfile.NameList.Add("张三"); // 添加时自动保存
184
SystemProfile.NameList.AddRange(["李四", "王五"]); // 批量添加
185
SystemProfile.NameList.Remove("李四"); // 删除时也自动保存
186
SystemProfile.NameIdDictionary.Add("张三", 100L); // 字典同理
187
}
188
}
189
```
190
191
### 在 `get`/`set` 中插入自定义代码
192
193
使用 `[ProfilePropertyAddGet]` 和 `[ProfilePropertyAddSet]` 在生成的属性访问器中插入代码片段：
194
195
```csharp
196
[AutoLoadProfile]
197
partial class SystemProfile : XFEProfile
198
{
199
[ProfileProperty]
200
[ProfilePropertyAddGet(@"Console.WriteLine(""获取了 Name"")")]
201
[ProfilePropertyAddGet("return Current.name")]
202
[ProfilePropertyAddSet(@"Console.WriteLine(""设置了 Name"")")]
203
[ProfilePropertyAddSet("Current.name = value")]
204
string name = string.Empty;
205
206
[ProfileProperty]
207
[ProfilePropertyAddGet(@"Console.WriteLine(""获取了 Age"")")]
208
[ProfilePropertyAddGet("return Current._age")]
209
[ProfilePropertyAddSet(@"Console.WriteLine(""设置了 Age"")")]
210
[ProfilePropertyAddSet("Current._age = value")]
211
int _age;
212
}
213
```
214
215
> **注意：** 使用 `[ProfilePropertyAddGet]` / `[ProfilePropertyAddSet]` 时，需要自行完整处理返回值/赋值逻辑，最后一条 get 语句需包含 `return`。
216
217
### 使用部分方法钩子
218
219
框架为每个属性自动生成 `static partial void GetXxxProperty()` 和 `static partial void SetXxxProperty(ref T value)` 分部方法，可在用户代码中实现：
220
221
```csharp
222
[AutoLoadProfile]
223
partial class SystemProfile : XFEProfile
224
{
225
[ProfileProperty]
226
string name = string.Empty;
227
228
[ProfileProperty]
229
int _age;
230
231
static partial void GetNameProperty()
232
{
233
Console.WriteLine("获取了 Name");
234
}
235
236
static partial void SetNameProperty(ref string value)
237
{
238
Console.WriteLine($"设置了 Name：从 {Name} 变为 {value}");
239
}
240
241
static partial void GetAgeProperty()
242
{
243
Console.WriteLine("获取了 Age");
244
}
245
246
static partial void SetAgeProperty(ref int value)
247
{
248
value = 1999; // 可直接修改即将写入的值
249
Console.WriteLine($"设置了 Age：从 {Age} 变为 1999");
250
}
251
}
252
```
253
254
### 设置属性初始值
255
256
在字段声明处直接赋值即可：
257
258
```csharp
259
[AutoLoadProfile]
260
partial class SystemProfile : XFEProfile
261
{
262
[ProfileProperty]
263
string name = "John Wick";
264
265
[ProfileProperty]
266
int _age = 59;
267
}
268
```
269
270
### 为字段添加 XML 文档注释
271
272
字段上的 `<summary>` 注释会被自动复制到生成的静态属性上：
273
274
```csharp
275
[AutoLoadProfile]
276
partial class SystemProfile : XFEProfile
277
{
278
/// <summary>
279
/// 用户名称（此注释会自动同步至生成的 Name 属性）
280
/// </summary>
281
[ProfileProperty]
282
string name = string.Empty;
283
284
[ProfileProperty]
285
int _age;
286
}
287
```
288
289
### 手动调用加载/保存/删除/导入/导出
290
291
框架为每个配置文件类自动生成以下静态方法：
292
293
```csharp
294
SystemProfile.LoadProfile(); // 从文件加载配置
295
SystemProfile.SaveProfile(); // 将配置保存到文件
296
SystemProfile.DeleteProfile(); // 删除配置文件
297
string exported = SystemProfile.ExportProfile(); // 将当前配置导出为字符串
298
SystemProfile.ImportProfile(exported); // 从字符串导入配置
299
```
300
301
---
302
303
## API 参考
304
305
### 特性（Attributes）
306
307
| 特性 | 应用目标 | 说明 |
308
|------|----------|------|
309
| `[ProfileProperty]` | 字段 | 标记该字段参与自动生成，可指定属性名 `[ProfileProperty("CustomName")]` |
310
| `[ProfilePropertyAddGet(code)]` | 字段 | 在生成的 `get` 访问器中追加代码行，支持多个 |
311
| `[ProfilePropertyAddSet(code)]` | 字段 | 在生成的 `set` 访问器中追加代码行，支持多个 |
312
| `[AutoLoadProfile]` | 类 | 在静态构造函数中自动调用 `LoadProfile()` |
313
| `[ProfilePath(path)]` | 类 | 指定配置文件存储路径 |
314
315
### 存储模式（ProfileOperationMode）
316
317
| 值 | 文件扩展名 | 说明 |
318
|----|------------|------|
319
| `XFEDictionary`（默认）| `.xpf` | 使用 XFE 字典格式 |
320
| `Json` | `.json` | 使用 JSON 序列化 |
321
| `Xml` | `.xml` | 使用 XML 序列化 |
322
| `Custom` | 自定义 | 使用自定义的加载/保存委托 |
323
324
### 自动生成的静态成员
325
326
对于每个继承 `XFEProfile` 并使用 `[ProfileProperty]` 的 `partial` 类，框架将自动生成：
327
328
| 成员 | 类型 | 说明 |
329
|------|------|------|
330
| `Current` | `static T` | 当前配置文件实例 |
331
| `ProfilePath` | `static string` | 配置文件路径（不含扩展名） |
332
| `ProfileExtension` | `static string` | 配置文件扩展名（空则自动推断） |
333
| `LoadProfile()` | `static void` | 从文件加载配置 |
334
| `SaveProfile()` | `static void` | 将配置保存到文件 |
335
| `DeleteProfile()` | `static void` | 删除配置文件 |
336
| `ExportProfile()` | `static string` | 导出配置为字符串 |
337
| `ImportProfile(string)` | `static void` | 从字符串导入配置 |
338
| `XxxProperty`（每个字段）| `static T` | 自动生成的静态属性，读写时自动持久化 |
339
| `InstanceXxx`（每个字段）| `T`（实例）| 对应的实例属性 |
340
| `GetXxxProperty()` | `static partial void` | get 钩子分部方法 |
341
| `SetXxxProperty(ref T)` | `static partial void` | set 钩子分部方法 |
342
343
### XFEProfile 基类成员
344
345
| 成员 | 类型 | 说明 |
346
|------|------|------|
347
| `DefaultProfileOperationMode` | `ProfileOperationMode` | 存储/加载模式 |
348
| `LoadOperation` | `ProfileLoadOperation` | 自定义加载委托 |
349
| `SaveOperation` | `ProfileSaveOperation` | 自定义保存委托 |
350
| `ProfilesDefaultPath` | `static string` | 所有配置文件的默认根目录 |
351
352
---
353
354
## 许可证
355
356
本项目基于 [MIT 许可证](LICENSE.txt) 开源。
@@ -46,6 +46,10 @@
46
46
<Pack>True</Pack>
47
47
<PackagePath>\</PackagePath>
48
48
</None>
49
<None Include="..\README_zh.md">
50
<Pack>True</Pack>
51
<PackagePath>\</PackagePath>
52
</None>
49
53
<None Include="..\XFEExtension.NetCore.AutoConfig.Analyzer\bin\Release\netstandard2.0\XFEExtension.NetCore.AutoConfig.Analyzer.dll" Pack="true" PackagePath="analyzers/dotnet/cs" Visible="false" />
50
54
</ItemGroup>
51
55