技術文章 » dotnet 用 SourceGenerator 原始碼生成技術實現中文程式語言

dotnet 用 SourceGenerator 原始碼生成技術實現中文程式語言

2022-10-19 09:01:01

相信有很多夥伴都很喜歡自己造程式語言，在有現代的很多工具鏈的幫助下，實現一門程式語言，似乎已不是一件十分困難的事情。我利用 SourceGenerator 原始碼生成技術實現了一個簡易的中文程式語言，核心原理是將中文程式語言翻譯為 C# 語言，從而完成後續的所有對接，完成了最簡單的構建和執行。本文將告訴大家這個有趣的方式是如何實現

開始之前，先給大家看看效果

這是我設計的 csg 格式（Chinese programming language by SourceGenerator）的中文程式語言，設計上完全參考（抄襲）了中文宏的實現方式。原本我是考慮抄襲 易語言 的，但是 易語言 更貼近是 VB 系的方式（？ 似乎也不能這麼說）感覺不是我隨便就能寫出來的。我只是想著學習原始碼生成技術，順帶測試一下自己能否很隨意的就寫出一個新的程式語言。當然，測試結果是我不能很隨意就寫出一個新的程式語言

本文所設計的 csg 格式的中文程式語言，僅僅只能用來做演示使用，絲毫不能用在實際專案裡。本文僅僅只是用來告訴大家一個簡易的方法來完成自己建立一門程式語言

本文所設計的 csg 格式的中文程式語言，能夠和 C# 完美的結合，畢竟實際參與構建的就是 C# 程式碼。我在本文的最後給出了所有的程式碼的下載方式，要求在 VS 2022 較新版本上才能成功執行

以下是 csg 的程式碼，也是本文效果裡所使用的程式碼

參照名稱空間 系統;

定義名稱空間 這是一個名稱空間;

型別 這是測試型別
{
    公開的 靜態的 無返回值型別的 測試輸出()
    {
        控制檯.輸出一行文字("你好");
    }
}

可以看到，這是全部採用中文編寫的一段程式碼。相信大家看到上面的程式碼，在熟悉 C# 的前提下，能反應過來這段程式碼的作用

儘管這是採用中文編寫的，但不代表著任何人都能讀懂這段程式碼的作用。因為這僅僅只是使用中文對 C# 的關鍵詞進行翻譯而已。同理的，也不是任何會英文的人都能讀懂程式碼

那以上程式碼可以被如何呼叫呢？可以完全和 C# 互動，被 C# 直接呼叫，如以下程式碼，在 C# 程式碼的主函數裡面呼叫 測試輸出() 方法。這是利用了 C# 裡面允許識別符號支援 Utf-8 編寫，而不僅僅是 ASCII 編碼的字元。換句話說是使用中文作用方法名、類名、屬性名等，在 C# 裡都是合法的

// Program.cs

using 這是一個名稱空間;

這是測試型別.測試輸出();

以上是採用 C# 9.0 新特性——頂級語句，無須加上型別和主函數定義，直接編寫程式碼體即主函數執行程式碼體的。如此可以極大簡化程式碼量

執行程式碼，可以看到控制檯輸出了 你好 字串，證明了程式碼的構建執行正常

接下來將告訴大家實現的原理和實現的細節方法，在開始之前，期望大家已對 C# dotnet 的基礎知識熟悉，對 dotnet 整個構建過程熟悉，瞭解原始碼生成技術，本文將略過基礎知識

先新建兩個專案，分別是 JelallnalukebaqeLairjaybearjair 和 JelallnalukebaqeLairjaybearjair.Analyzers 兩個控制檯專案。其中 JelallnalukebaqeLairjaybearjair 專案就是用來編寫中文程式設計的專案。而 JelallnalukebaqeLairjaybearjair.Analyzers 是一個分析器專案，將在此專案裡編寫原始碼生成邏輯，用來支援將編寫的中文程式碼轉換為 C# 程式碼，從而參與後續的構建和執行

在 JelallnalukebaqeLairjaybearjair 專案裡，將對 JelallnalukebaqeLairjaybearjair.Analyzers 專案進行參照，從而用來啟動此分析器的內容。新增參照時設定 OutputItemType 為 Analyzer 型別，且設定不使用不參照 JelallnalukebaqeLairjaybearjair.Analyzers 程式集。參照之後的 JelallnalukebaqeLairjaybearjair 專案的 csproj 專案檔案的參照程式碼如下

  <ItemGroup>
    <ProjectReference Include="..\JelallnalukebaqeLairjaybearjair.Analyzers\JelallnalukebaqeLairjaybearjair.Analyzers.csproj" OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
  </ItemGroup>

在本文的例子裡，在 JelallnalukebaqeLairjaybearjair 專案裡只有兩個檔案，一個是 Program.cs 檔案，一個是 這是測試型別.csg 檔案。其中 Program.cs 檔案就是傳統的 C# 專案，採用 C# 9.0 的頂層語句，編寫的程式碼如下

using 這是一個名稱空間;

這是測試型別.測試輸出();

而 這是測試型別.csg 檔案裡的內容就是本文開頭的中文程式碼內容

接著，為了讓分析器能瞭解到 這是測試型別.csg 檔案是需要參與構建的，額外在 JelallnalukebaqeLairjaybearjair 的 csproj 專案檔案裡面新增 AdditionalFiles 列表。通過 AdditionalFiles 列表，可以在後續的分析器裡面，在增量構建裡，通過 AdditionalTextsProvider 監聽獲取到這部分檔案內容。編輯 JelallnalukebaqeLairjaybearjair 的 csproj 專案檔案，新增如下程式碼

  <ItemGroup>
      <AdditionalFiles Include="這是測試型別.csg" />
  </ItemGroup>

以上就是 JelallnalukebaqeLairjaybearjair 專案的所有檔案和核心邏輯了。完成了準備工作之後，開始編寫 JelallnalukebaqeLairjaybearjair.Analyzers 分析器專案。為了能夠在 Visual Studio 裡面載入上分析器，以及同時在 dotnet 命令列裡載入分析器，設定 TargetFramework 為 .NET Standard 2.0 版本。因為 Visual Studio 採用的是 .NET Framework 執行時，而 dotnet 命令列工具採用的是 .NET Core 執行時，於是分析器採用 .NET Standard 2.0 版本就能剛好在這兩個執行時載入

為了編寫分析器專案，按照慣例，還需要參照必要的 NuGet 包。這裡需要參照 Microsoft.CodeAnalysis.Analyzers 和 Microsoft.CodeAnalysis.CSharp 程式集

編輯 JelallnalukebaqeLairjaybearjair.Analyzers 的 csproj 專案檔案為如下程式碼

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.3.3" PrivateAssets="all" />
    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.2.0" PrivateAssets="all" />
  </ItemGroup>

</Project>

完成了安裝庫之後，即可開始編寫核心程式碼。需求是將 csg 格式的中文程式語言，轉換為 C# 程式碼，從而參與後續的構建和執行

新建一個叫 CsgIncrementalGenerator 型別，繼承 IIncrementalGenerator 介面，順帶加上 GeneratorAttribute 特性標識這是生成 C# 程式碼的。型別名可以自己發揮，只是本文作為例子叫成 CsgIncrementalGenerator 而已

    [Generator(LanguageNames.CSharp)]
    public class CsgIncrementalGenerator : IIncrementalGenerator
    {
        // 忽略程式碼
    }

繼承 IIncrementalGenerator 介面，需要實現 public void Initialize(IncrementalGeneratorInitializationContext context) 方法。如 嘗試 IIncrementalGenerator 進行增量 Source Generator 生成程式碼 部落格所述，在進行增量構建時，只有 Initialize 方法。在 Initialize 方法裡面，加上分析器感興趣的檔案以及對這些檔案的處理方法即可

咱這裡的中文程式語言採用字尾名為 .csg 的檔案，在 JelallnalukebaqeLairjaybearjair 專案裡也將 csg 檔案在 csproj 專案檔案裡新增到 AdditionalFiles 列表裡面。在 Initialize 方法裡面，先告訴分析器感興趣的檔案就是 csg 檔案，只有有 csg 檔案的變更，那將自動觸發更新邏輯，在更新邏輯裡執行實際的轉換程式碼

        public void Initialize(IncrementalGeneratorInitializationContext context)
        {
            var csgFileIncrementalValuesProvider =
            context.AdditionalTextsProvider.Where(t =>
                string.Equals(Path.GetExtension(t.Path), ".csg", StringComparison.OrdinalIgnoreCase));
            // 忽略檔案
        }

以上程式碼的 AdditionalTextsProvider 不是實際立刻提供了檔案，而是用來編寫檔案變更時的過濾命令，這也是增量程式碼生成的核心邏輯。通過編寫過濾命令的方式，可以減少程式碼生成實際轉換邏輯的執行次數，只有在遇到感興趣的檔案的變更的時候才會觸發實際的執行邏輯，從而極大的提升效能

接下來將此過濾條件加入註冊，在過濾條件 csgFileIncrementalValuesProvider 能過濾出有檔案變更時，將執行轉換程式碼。轉換程式碼的輸入是 csg 中文程式語言的程式碼檔案，輸出是加入到構建的 C# 的程式碼字串

通過 RegisterSourceOutput 方法進行註冊，註冊在滿足 csgFileIncrementalValuesProvider 過濾條件時，支援新增額外的參與構建程式碼

            context.RegisterSourceOutput(csgFileIncrementalValuesProvider, (sourceProductionContext, csg) =>
            {
                // 忽略程式碼
            });

在 RegisterSourceOutput 的開始，是先註冊框架部分的程式碼，如上面的中文程式碼，可以看到用到了一些需要預設的框架程式碼，例如 控制檯.輸出一行文字("你好"); 這句程式碼就需要先有預設的名為 控制檯 的型別。先新增框架程式碼如下

            context.RegisterSourceOutput(csgFileIncrementalValuesProvider, (sourceProductionContext, csg) =>
            {
                AddFrameworkCode(sourceProductionContext);
                // 忽略程式碼
            });

這裡拿到的 sourceProductionContext 引數，可以用來設定構建的生成程式碼。在 AddFrameworkCode 裡面，新增框架需要的預設程式碼，程式碼如下

        /// <summary>
        /// 新增框架程式碼
        /// </summary>
        /// <param name="sourceProductionContext"></param>
        private static void AddFrameworkCode(SourceProductionContext sourceProductionContext)
        {
            string consoleText = @"
using System;

namespace 系統;

static class 控制檯
{
    public static void 輸出一行文字(string 文字)
    {
        Console.WriteLine(文字);
    }
}";
            sourceProductionContext.AddSource("DefaultConsole", consoleText);
        }

本文這裡只新增了用來演示的名為 控制檯 的型別，新增方法如上程式碼。以上程式碼將會在專案裡，新增一個叫做 DefaultConsole 的生成程式碼，如此即可讓中文程式設計程式碼裡有可以使用的控制檯輔助型別

接下來是獲取到發生變更的 csg 中文程式語言的檔案的內容，用來轉換為 C# 程式碼

            context.RegisterSourceOutput(csgFileIncrementalValuesProvider, (sourceProductionContext, csg) =>
            {
                AddFrameworkCode(sourceProductionContext);

                var csgSource = csg.GetText();
                if (csgSource == null) return;
                // 忽略程式碼
            });

通過 GetText 即可獲取到其文字內容

獲取到內容之後，需要將 csg 中文程式語言的內容轉換為 C# 程式碼字串內容。我這裡抄襲了中文宏的方法，使用關鍵詞替換。本文這裡只是替換了演示所需要的關鍵詞，沒有對其他的關鍵詞進行替換

                var keyDictionary = new Dictionary<string, string>()
                {
                    {"參照名稱空間 ","using "},
                    {"定義名稱空間 ","namespace "},
                    {"型別 ","class "},
                    {"公開的 ","public "},
                    {"靜態的 ","static "},
                    {"無返回值型別的 ","void "},
                };

                var stringBuilder = new StringBuilder();
                foreach (var textLine in csgSource.Lines)
                {
                    var text = textLine.ToString();
                    if (!string.IsNullOrEmpty(text))
                    {
                        foreach (var keyValuePair in keyDictionary)
                        {
                            text = text.Replace(keyValuePair.Key, keyValuePair.Value);
                        }
                    }

                    stringBuilder.AppendLine(text);
                }

如此一行行進行替換，即可拿到一段 C# 程式碼

將 stringBuilder 裡的 C# 程式碼作為生成程式碼，新增到 sourceProductionContext 用於參與構建

                sourceProductionContext.AddSource(Path.GetFileNameWithoutExtension(csg.Path) + ".g.cs", stringBuilder.ToString());

新增的時候，設定了 hintName 引數為 Path.GetFileNameWithoutExtension(csg.Path) + ".g.cs" 如此即可在相同的一個 csg 檔案變更的時候，生成的程式碼可以替換舊的生成程式碼。生成程式碼之間的替換就是採用 hintName 引數作為判斷條件

如此即可完成將 csg 中文程式語言轉換為 C# 程式碼，且加入到構建裡

本文只是作為一個演示，告訴大家可以利用 Source Generator 技術，將中文程式語言轉換為 C# 程式碼，方便的加入到構建裡，從而複用整個 dotnet 的機制

本文的程式碼放在github 和 gitee 歡迎存取

可以通過如下方式獲取本文的原始碼，先建立一個空資料夾，接著使用命令列 cd 命令進入此空資料夾，在命令列裡面輸入以下程式碼，即可獲取到本文的程式碼

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin bba0c728bbc1d850f6f1929ab14a42e995e23e3b

以上使用的是 gitee 的源，如果 gitee 不能存取，請替換為 github 的源。請在命令列繼續輸入以下程式碼

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git
git pull origin bba0c728bbc1d850f6f1929ab14a42e995e23e3b

獲取程式碼之後，進入 JelallnalukebaqeLairjaybearjair 資料夾

更多增量構建請看 嘗試 IIncrementalGenerator 進行增量 Source Generator 生成程式碼

更多編譯器、程式碼分析、程式碼生成相關部落格，請參閱我的 部落格導航