test/Documentation/SETUP_UNITY_EDITOR_ANALYZER.md

Hướng Dẫn Thiết Lập Cảnh Báo #if UNITY_EDITOR

Tài liệu này hướng dẫn cách thiết lập IDE để cảnh báo khi sử dụng hàm/method được wrap trong #if UNITY_EDITOR từ code không có directive này, có thể gây lỗi build.

Phương Pháp 1: Custom Roslyn Analyzer (Khuyến nghị)

Bước 1: Build Analyzer

Mở PowerShell hoặc Command Prompt và chạy:

cd E:\Projects\perfect-world-unity\UnityEditorOnlyAnalyzer
dotnet build -c Release

Bước 2: Thêm Analyzer vào Unity Project

Sau khi Unity generate lại .csproj files, bạn cần thêm analyzer vào các file .csproj chính:

Cách tự động (sử dụng AssetPostprocessor):

Tạo file Assets/Editor/AddAnalyzerPostprocessor.cs:

using System.IO;
using UnityEditor;
using UnityEngine;

public class AddAnalyzerPostprocessor : AssetPostprocessor
{
    private static void OnGeneratedCSProjectFiles()
    {
        string analyzerPath = Path.GetFullPath("UnityEditorOnlyAnalyzer/bin/Release/netstandard2.0/UnityEditorOnlyAnalyzer.dll");
        
        if (!File.Exists(analyzerPath))
        {
            Debug.LogWarning($"Analyzer not found at {analyzerPath}. Please build the analyzer first.");
            return;
        }

        string[] csprojFiles = Directory.GetFiles(".", "*.csproj", SearchOption.TopDirectoryOnly);
        
        foreach (string csprojFile in csprojFiles)
        {
            if (csprojFile.Contains("Assembly-CSharp") || csprojFile.Contains("Assembly-CSharp-firstpass"))
            {
                string content = File.ReadAllText(csprojFile);
                
                if (!content.Contains("UnityEditorOnlyAnalyzer.dll"))
                {
                    string analyzerInclude = $@"    <ItemGroup>
      <Analyzer Include=""{analyzerPath.Replace("\\", "\\\\")}"" />
    </ItemGroup>
  </Project>";
                    
                    content = content.Replace("  </Project>", analyzerInclude);
                    File.WriteAllText(csprojFile, content);
                }
            }
        }
    }
}

Cách thủ công:

Mở file Assembly-CSharp.csproj và thêm vào trước thẻ </Project>:

  <ItemGroup>
    <Analyzer Include="E:\Projects\perfect-world-unity\UnityEditorOnlyAnalyzer\bin\Release\netstandard2.0\UnityEditorOnlyAnalyzer.dll" />
  </ItemGroup>
</Project>

Bước 3: Reload Project trong Visual Studio

1. Đóng Visual Studio
2. Mở lại Unity project
3. Visual Studio sẽ tự động reload và áp dụng analyzer

Phương Pháp 2: Sử dụng EditorConfig (Hỗ trợ một phần)

File .editorconfig đã được tạo ở root project. Một số IDE (như Visual Studio 2019+, VS Code với C# extension) sẽ đọc file này.

Tuy nhiên, EditorConfig không thể tự động phát hiện #if UNITY_EDITOR - bạn vẫn cần Roslyn Analyzer.

Phương Pháp 3: Visual Studio Code Rules (Nếu dùng VS Code)

Nếu bạn sử dụng VS Code với C# extension, analyzer sẽ tự động hoạt động sau khi được thêm vào .csproj.

Đảm bảo bạn có extension:

• C# (Microsoft)
• C# Dev Kit (Microsoft) - Khuyến nghị

Kiểm Tra

Sau khi setup, tạo file test:

// TestFile.cs
#if UNITY_EDITOR
public class EditorOnlyClass
{
    public static void EditorMethod() { }
}
#endif

public class RegularClass
{
    public void Test()
    {
        EditorOnlyClass.EditorMethod(); // ⚠️ Nên có cảnh báo ở đây
    }
}

Bạn sẽ thấy warning:

UNITY_EDITOR_ONLY_USAGE: Method/Type 'EditorMethod' is only available in UNITY_EDITOR and may cause build errors

Troubleshooting

Analyzer không hoạt động

1. Kiểm tra analyzer đã được build chưa:

   Test-Path "UnityEditorOnlyAnalyzer\bin\Release\netstandard2.0\UnityEditorOnlyAnalyzer.dll"
   

2. Kiểm tra đường dẫn trong .csproj:

   • Đường dẫn phải là absolute path hoặc relative path đúng
   • Đảm bảo file .dll tồn tại

3. Reload project:

   • Đóng và mở lại Visual Studio/VS Code
   • Hoặc trong Visual Studio: Project > Reload Project

4. Kiểm tra Output window:

   • Trong Visual Studio, xem Output window để xem có lỗi load analyzer không

Warning không hiển thị

1. Đảm bảo code thực sự có vấn đề (method trong #if UNITY_EDITOR được gọi từ code không có directive)
2. Kiểm tra Error List trong Visual Studio (View > Error List)
3. Đảm bảo Warning level không bị tắt trong project settings

Tùy Chỉnh Severity

Bạn có thể thay đổi severity từ Warning sang Error trong .editorconfig:

[*.cs]
dotnet_diagnostic.UNITY_EDITOR_ONLY_USAGE.severity = error

Hoặc disable hoàn toàn:

[*.cs]
dotnet_diagnostic.UNITY_EDITOR_ONLY_USAGE.severity = none

Lưu Ý

• Analyzer chỉ hoạt động khi IDE đang mở project
• Unity build process có thể không hiển thị warnings này, nhưng Visual Studio sẽ hiển thị
• Nếu bạn sử dụng CI/CD, cần đảm bảo analyzer được include trong build process

Tài Liệu Tham Khảo

• Roslyn Analyzers Documentation
• Unity Code Analysis