GlobalUsing、JSON Schema、NuGet使用方法

一、速通一图流

二、GlobalUsing 使用

1. 关于 GlobalUsing

在 .NET 6/C# 10 之后，微软引入了 GlobalUsings 机制。这个机制允许你在项目根目录下创建一个 GlobalUsings.cs 文件，并在其中定义全局的 using 指令。这样一来，项目中的其他 .cs 文件就不需要再重复书写这些 using 指令，大大提高了开发效率，并使代码更加简洁。

2. 必要配置

启用 GlobalUsings 机制需要以下两个步骤：

1. 创建 GlobalUsings.cs 文件：
   在项目根目录创建一个名为 GlobalUsings.cs 的文件。如果多个项目层需要使用全局 using，则每个层都应该有一个 GlobalUsings.cs 文件。

2. 编辑项目的 .csproj 文件：
   在 .csproj 文件的 中添加 enable，通常与 同级。

示例：

<PropertyGroup>
  <TargetFramework>net6.0TargetFramework>
  <ImplicitUsings>enableImplicitUsings>
PropertyGroup>

3. 基本使用

配置完成后，可以将常用的 using 语句放到 GlobalUsings.cs 文件中，写法如下
Furion 推荐的全局命名空间：

global using Furion;  // 引入 Furion 核心命名空间
global using Furion.DatabaseAccessor;  // 引入数据库访问器命名空间
global using Furion.DataEncryption;  // 引入数据加密命名空间
global using Furion.DataValidation;  // 引入数据验证命名空间
global using Furion.DependencyInjection;  // 引入依赖注入命名空间
global using Furion.DynamicApiController;  // 引入动态 API 控制器命名空间
global using Furion.Extensions;  // 引入扩展方法命名空间
global using Furion.FriendlyException;  // 引入友好异常处理命名空间
global using Furion.Logging;  // 引入日志处理命名空间
global using Mapster;  // 引入对象映射工具 Mapster 的命名空间
global using Microsoft.AspNetCore.Authorization;  // 引入授权相关命名空间
global using Microsoft.AspNetCore.Http;  // 引入 Http 上下文相关命名空间
global using Microsoft.AspNetCore.Mvc;  // 引入 MVC 框架相关命名空间
global using Microsoft.CodeAnalysis;  // 引入代码分析工具命名空间
global using Microsoft.EntityFrameworkCore;  // 引入 Entity Framework Core 的命名空间
global using System.ComponentModel.DataAnnotations;  // 引入数据注解命名空间

注意：全局 using 必须以 global 开头。

4. 小知识

• 推荐做法：建议将实体类的命名空间也放到 GlobalUsings.cs 中，因为仓储接口 IRepository 的使用频率非常高。
• CodeMaid 插件：建议在 Visual Studio 中安装 CodeMaid 插件（适用于 2019 和 2022 版本），自动清理解决方案中所有无用的 using，结合 GlobalUsings.cs 使用效果更佳。

5. 个别情况

如果由于 Visual Studio 版本的问题，导致 GlobalUsings.cs 中的定义出错，可以在 using 后面加上 global::，如：

global using global::Furion;

6. 默认全局 using

微软已经自动将一些常用的 using 在编译后的代码中补上。这些文件路径位于 项目/obj/Debug/net6.0/项目.GlobalUsings.cs，内容如下：

// 
global using global::System;
global using global::System.Collections.Generic;
global using global::System.IO;
global using global::System.Linq;
global using global::System.Net.Http;
global using global::System.Threading;
global using global::System.Threading.Tasks;

以上的 using 无需写在你创建的 GlobalUsings.cs 中，微软会在编译时自动合并。

7. .NET 5 项目开启支持

默认情况下，.NET 5 采用 C# 9.0 编译，而 GlobalUsing 是从 C# 10.0 开始支持的。要在 .NET 5 项目中使用 GlobalUsing 机制，只需要编辑项目的 .csproj 文件并添加 10.0 即可：

<PropertyGroup>
    <TargetFramework>net5.0TargetFramework>
    <LangVersion>10.0LangVersion>
    
PropertyGroup>

如需使用最新版，可以将 配置为 latest。

---

三、 JSON Schema 使用

1. 关于 JSON Schema

JSON Schema 是一个用于验证 JSON 数据结构的强大工具。Schema 可以理解为模式或者规则，有了 JSON Schema，可以防止配置文件中出现错误或不符合预期的数据结构。

2. 学习 JSON Schema 编写

JSON Schema 的编写对于提供智能提示和校验功能非常有用。如果你想学习 JSON Schema 编写，可以参考以下文档：

• JSON Schema 官方文档
• 知乎文章：深入浅出 JSON Schema

另外，推荐一个便捷的在线工具，可以根据 JSON 文件内容自动生成 JSON Schema，并支持进一步的修改：

• JSON Schema Visual Editor

3. Furion 框架提供

Furion 框架提供了完整的 Furion 和 ASP.NET Core 的 JSON Schema 文件。通过这些文件，可以在编写配置文件时获得完整的智能提示和校验支持。

4. 如何使用

使用 JSON Schema 的方式非常简单，只需要在 .json 文件的头部添加 $schema 字段，指向 Furion 提供的 JSON Schema 文件即可。例如：

{
  "$schema": "https://gitee.com/dotnetchina/Furion/raw/v4/schemas/v4/furion-schema.json",

  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information",
      "Microsoft.EntityFrameworkCore": "Information",
      "Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware": "Information"
    }
  },
  "AllowedHosts": "*"
}

5. JSON Schema 失效解决

如果在添加了 $schema 字段后，依然无法进行智能提示和校验，可以尝试以下步骤：

1. 关闭并重新打开 .json 文件：有时只需要重新加载文件即可解决问题。
2. 重启 IDE：

• Visual Studio：关闭并重新打开 Visual Studio。
• Visual Studio Code：重启 Visual Studio Code 即可。

6. 更新 JSON Schema 缓存

默认情况下，JSON Schema 在第一次获取后会被自动缓存，这可能会导致 .json 文件的提示错误。要更新缓存，只需删除缓存文件即可。

1. Visual Studio：

• 打开运行窗口，输入 %AppData%。
• 进入 C:\Users\你的电脑用户名\AppData\Local\Microsoft\VisualStudio 路径。
• 删除以 http/https 开头的缓存文件。

2. Visual Studio Code：

• 打开运行窗口，输入 %AppData%。
• 进入 C:\Users\你的电脑用户名\AppData\Roaming\Code\User\globalStorage\vscode.json-language-features\json-schema-cache 路径。
• 删除缓存文件。

---

三、NuGet 本地调试包

1. 私有 NuGet 平台搭建

搭建私有 NuGet 服务器是为了在企业内部或团队之间管理和分发私有软件包。这些包可能包含了专有的代码库或敏感的组件，不适合公开发布到公共的 NuGet.org。可以使用 BaGet 来搭建私有 NuGet 服务器：

• BaGet 官方仓库
  搭建后，可通过下列脚本发布包：

# 支持 .nupkg 和 .snupkg 包
dotnet nuget push -s http://localhost:5000/v3/index.json Furion.1.0.0.nupkg

2. 关于本地测试包

通常情况下，我们通过 NuGet 在线平台（如 Visual Studio 内置的 NuGet 包管理器）安装依赖包，但有时我们不希望将包发布到公共平台，或者只想在本地使用或测试后再发布。
本地测试包的好处：

1. 可以有效保护公司核心代码。
2. 方便开源项目测试。

3. 如何配置本地测试包

3.1 测试包命名规则

默认情况下，Furion 会根据 Furion.版本号-beta.Issue编号 规则生成 .nupkg 和 .snupkg 包。前者是不包含调试符号的 NuGet 包，后者则是带有调试符号的包（方便 IDE 调试）。例如：

D:\Furion_NuGet_Test_Packages
Furion.4.2.3-beta-I5MM3O.nupkg
Furion.4.2.3-beta-I5MM3O.snupkg

其中，I5MM3O 对应的是 Issue 的编号：Issue Link。

3.2 配置本地包路径

将生成的包放到本地磁盘的一个文件夹中，如 D:\Furion_NuGet_Test_Packages。

3.3 在 Visual Studio 中配置路径

在 Visual Studio 中，配置本地包路径以便项目可以引用这些包：

1. 打开 NuGet 包管理器设置。

2. 添加本地包源，指向 D:\Furion_NuGet_Test_Packages。

3.4 通过命令行操作

如果不使用可视化 IDE 进行配置，可以通过以下命令行配置本地包源：

dotnet restore "YourProject.Web.Entry/YourProject.Web.Entry.csproj" -s "D:\Furion_NuGet_Test_Packages";
dotnet restore "YourProject.Web.Entry/YourProject.Web.Entry.csproj" -s "https://api.nuget.org/v3/index.json";

3.5 选择测试版安装或更新

测试通过后，可以删除之前的配置，也可以继续使用本地包。

4. Visual Studio 调试 NuGet 包

Furion 提供了 .snupkg 包，安装 Furion 时会自动下载到本地。如果需要启用源码调试，只需要启用以下配置：

1. 在 Visual Studio 中启用 Enable source server support 选项。
2. 启用 Enable Just My Code 选项以进行调试。
   启用这些选项后，重新编译解决方案即可通过 F12 跳转到源代码并调试。