メイン コンテンツにジャンプします

6. 高级编译技巧

API 规范​

  • With 系列 API： 带有关闭、排除、枚举附加值等条件状态开关时使用的 API。 例如： WithCombineUsingCode 和 WithoutCombineUsingCode, WithHighVersionDependency、WithLowVersionDependency、WithDebugCompile、WithReleaseCompile、WithFileOutput 等,又例如编译选项的 API 都是作为附加条件赋给选项的，因此都由 With 开头(注：与 Roslyn 风格不同，With 方法不返回新对象).

  • Set 系列 API： 属单向赋值类 API, 例如：SetDllFilePath、SetReferencesFilter 等.

  • Config 系列 API： 具有对主类中，某重要组件的额外配置，通常是各类 options 操作的 API, 例如：ConfigCompilerOption、ConfigSyntaxOptions 等.

  • 特殊功能 API： 此类 API 需要非常独立且明确的功能，常用而显眼，例如 UseRandomDomain、UseSmartMode、OutputAsFullAssembly、GetAssembly 等显眼包 API.

动态调试​

Natasha 最新版支持动态源代码调试，您可以使用 API 来开启调试。

//调试信息写入文件，原始的写入方式，可能会造成跨平台兼容性问题
builder.WithDebugCompile(item=>item.WriteToFileOriginal())
//调试信息写入文件，兼容性写入方式
builder.WithDebugCompile(item=>item.WriteToFile())
//调试信息整合到程序集中
builder.WithDebugCompile(item=>item.WriteToAssembly())
//Release 发布无法进行调试，
builder.WithReleaseCompile()
//Release 模式将携带 debugInfo 一起输出
builder.WithFullReleaseCompile()

生成程序集​

在程序集被编译前，你可能需要进行的配置

程序集名称​

//设置程序集名字
builder.SetAssemblyName();
//使用随机名(初始化不传入名字，默认用的是随机名)
builder.WithRandomAssenblyName();

语义相关配置​

//启用语义检查
buidler.WithSemanticCheck()
//关闭语义检查
buidler.WithoutSemanticCheck()
//在语义创建过程中开启访问级别检查
builder.WithAnalysisAccessibility();
//在语义创建过程中关闭访问性检查
builder.WithoutAnalysisAccessibility();
//增加语义处理插件
builder.AddSemanticAnalysistor();
//清除内置的语义处理插件
builder.ClearInnerSemanticAnalysistor();

配置编译细节​

//首先使用 API 
builder.ConfigCompilerOption(opt=>opt);
    //即使是被禁断的提示，也要报告出来(功能待挖掘)
    opt.WithSuppressReportor()
    //指定编译平台
    opt.WithPlatform()
    //指定编译标识
    opt.WithCompilerFlag()
    //指定输出方式，类库、应用程序还是其他
    opt.WithOutputKind()
    //导入所有的元数据
    opt.WithAllMetadata()
    //仅导入内部元数据
    opt.WithInternalMetadata()
    //仅导入公共元数据
    opt.WithPublicMetadata()
    //指定诊断信息作为何种级别报告出来
    opt.WithDiagnosticLevel()
    //允许同名低版本程序集存在
    opt.WithLowerVersionsAssembly()
    //指定空引用的检查级别
    opt.WithNullableCompile()
    //开启非安全上下文编译
    opt.WithoutUnsafeCompile()

出力​

ファイル出力​

Natashaは、dll/pdb/xmlファイルの出力をサポートしており、xmlにはアセンブリのコメント関連情報が格納されています。APIを参照してください

//このメソッドを使用すると、アセンブリがデフォルトのフォルダにdll/pdb/xmlファイルとして出力されます
//フォルダのパスを渡すこともできます
//また、3つのファイルのパスを渡すこともできます
builder.WithFileOutput(string dllFilePath, string? pdbFilePath = null, string? commentFilePath = null)
builder.WithFileOutput(string? folder = null);
//分離されたAPI
builder.SetDllFilePath/SetPdbFilePath/SetCommentFilePath();

注意：Releaseモードでは、pdbファイルは生成されません。

アセンブリの出力​

Natashaには、アセンブリに関連する設定があります

//完全なアセンブリを出力
builder.OutputAsFullAssembly();
//参照アセンブリを出力し、この時点ではプライベートメンバーはデフォルトで含まれません
builder.OutputAsRefAssembly();
//プライベートメンバーを含むように出力
builder.WithPrivateMembers();
//プライベートメンバーを含まないように出力
builder.WithoutPrivateMembers();

//コンパイル結果は参照アセンブリとして出力され、ファイルに書き込まれ、ドメインにはロードされません。
builder
  .OutputAsRefAssembly();
  .WithFileOutput()
  .WithoutInjectToDomain();