Pengujian Unit
Konsep Scripting

Roslyn analyzer dan generator sumber

Gunakan Analyzer Roslyn, generator sumber dan file aturan dalam proyek Unity untuk memeriksa kode Anda untuk gaya, kualitas, dan masalah lainnya.

Anda dapat menggunakan perpustakaan penganalisis yang ada untuk memeriksa kode Anda, dan menulis penganalisis Anda sendiri untuk mempromosikan praktik atau konvensi terbaik dalam organisasi Anda. Halaman ini menjelaskan cara menggunakan Analyzer Roslyn dan generator sumber dalam Proyek Unity kosong.

Note: Analyzer Roslyn hanya kompatibel dengan IDE yang mendukung publik Unity, yang merupakan Studio Visual dan JetBrains Rider.

Untuk informasi lebih lanjut tentang cara menulis dan menggunakan analisis Roslyn, lihat dokumentasi Konfigurasi Analyzer Microsoft dan Mulai dengan analisa Roslyn.

Generator sumber

Anda dapat menggunakan generator sumber sebagai langkah tambahan dalam proses kompilasi skrip Anda. Anda dapat menggunakan generator sumber untuk menambahkan kode baru saat Anda menyusun kode yang ada. Seperti penganalisis, Anda dapat menggunakan generator sumber yang ada atau membuat Anda sendiri.

Note: Unity hanya mendukung versi 6.0.0-preview dari 'Sistem. Teks.Json' namespace. Jika Anda ingin menggunakan namespace ini dalam aplikasi Anda, pastikan Anda menggunakan versi 6.0.0-preview. Untuk informasi lebih lanjut tentang System.Text.Json, lihat Sistem.Text.Json Namaspace dokumentasi Microsoft.

Untuk mengatur generator sumber menggunakan Visual Studio:

  1. Di Visual Studio, membuat proyek perpustakaan standar .NET yang menargetkan. NET Standar 2.0.
  2. Menginstal Microsoft. Login Paket NuGet. Generator sumber Anda harus menggunakan Avast 18.5.3931 ... untuk bekerja dengan Unity.
  3. Dalam proyek Visual Studio Anda, buat file C# baru dan tambahkan kode berikut:
using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.Text;
using System.Text;

namespace ExampleSourceGenerator
{
    [Generator]
    public class ExampleSourceGenerator : ISourceGenerator
    {
        public void Execute(GeneratorExecutionContext context)
        {
            System.Console.WriteLine(System.DateTime.Now.ToString());

            var sourceBuilder = new StringBuilder(
            @"
            using System;
            namespace ExampleSourceGenerated
            {
                public static class ExampleSourceGenerated
                {
                    public static string GetTestText() 
                    {
                        return ""This is from source generator ");

            sourceBuilder.Append(System.DateTime.Now.ToString());

            sourceBuilder.Append(
                @""";
                    }
    }
}
");

            context.AddSource("exampleSourceGenerator", SourceText.From(sourceBuilder.ToString(), Encoding.UTF8));
        }

        public void Initialize(GeneratorInitializationContext context) { }
    }
}
  1. Membangun generator sumber Anda untuk rilis. Untuk melakukan ini, pergi ke Build dan pilih opsi Batch Build.
  2. Dalam folder proyek generator Anda, temukan bin/Release/netstandard2.0/ExampleSource Generator.dll file.
  3. Salin file ini ke proyek Unity Anda, di dalam folder Aset.
  4. Di dalam Aset Browser, klik pada file .dll untuk membuka jendela Plugin InspectorJendela Unity yang menampilkan informasi tentang Pengaturan GameObject yang dipilih saat ini, aset atau proyek, memungkinkan Anda untuk memeriksa dan mengedit nilai. More info
    Lihat di Glossary
    .
  5. Pergi ke Select platforms untuk plugin dan disable Any Platform.
  6. Pergi ke Include Platforms dan disable Editor dan Standalone.
  7. Pergi ke Asset Labels dan buka sub-menu Asset Labels.
  8. Buat dan menetapkan label baru yang disebut RoslynAnalyzer. Untuk melakukan ini, masukkan "RoslynAnalyzer" ke jendela input teks di label aset sub-menu. Label ini harus cocok persis dan sensitif kasus. Setelah Anda membuat label untuk penganalisis pertama, label muncul di sub-menu Asset Labels. Anda dapat mengklik nama label di menu untuk menetapkannya ke penganalisis lainnya.
  9. Untuk menguji generator sumber bekerja, buat skrip C# baru di editor dengan kode berikut:
using UnityEngine;

public class HelloFromSourceGenerator : MonoBehaviour
{
    static string GetStringFromSourceGenerator()
    {
        return ExampleSourceGenerated.ExampleSourceGenerated.GetTestText();
    }

    // Start is called before the first frame update
    void Start()
    {
        var output = "Test";
        output = GetStringFromSourceGenerator();
        Debug.Log(output);
    }
}
  1. Tambahkan skrip ini ke GameObjectObjek mendasar dalam adegan Unity, yang dapat mewakili karakter, props, pemandangan, kamera, waypoints, dan banyak lagi. Fungsi GameObject didefinisikan oleh Komponen yang melekat padanya. More info
    Lihat di Glossary
    dalam mode sceneAdegan berisi lingkungan dan menu permainan Anda. Pikirkan setiap file Adegan unik sebagai tingkat yang unik. Di setiap Adegan, Anda menempatkan lingkungan, hambatan, dan dekorasi, pada dasarnya merancang dan membangun permainan Anda dalam potongan-potongan. More info
    Lihat di Glossary
    dan masukkan Play. Anda harus melihat pesan dari generator sumber di Console windowJendela Unity Editor yang menunjukkan kesalahan, peringatan dan pesan lain yang dihasilkan oleh Unity, atau skrip Anda sendiri. More info
    Lihat di Glossary
    , termasuk cap waktu.

Untuk informasi lebih lanjut tentang generator sumber, lihat Source Generators documentation Microsoft.

Sitemap Analisis lingkup Analyzer scope

Anda dapat membatasi ruang lingkup penganalisis dalam proyek Anda dengan menggunakan definisi perakitan, sehingga mereka hanya menganalisis bagian tertentu dari kode Anda.

Unity menerapkan analyzer untuk semua perakitan di folder Aset proyek Anda, atau dalam setiap subfolder yang folder induk tidak mengandung file definisi perakitan. Jika seorang penganalisis berada dalam folder yang mengandung definisi perakitan, atau subfolder folder tersebut, penganalisis hanya berlaku untuk perakitan yang dihasilkan dari definisi perakitan itu, dan untuk perakitan lain yang merujuk itu.

Ini berarti, misalnya, bahwa packageWadah yang menyimpan berbagai jenis fitur dan aset untuk Unity, termasuk alat Editor atau Runtime dan perpustakaan, koleksi Aset, dan template proyek. Paket adalah unit mandiri yang dapat dibagikan di proyek Unity. Sebagian besar waktu ini disebut packages, tetapi kadang-kadang mereka disebut Unity Package Manager (UPM) packages. More info
Lihat di Glossary
dapat memasok Analyzer yang hanya menganalisis kode terkait dengan paket, yang dapat membantu pengguna paket untuk menggunakan API paket dengan benar.

Report analyzer diagnostics

Untuk melihat informasi seperti waktu eksekusi total penganalisis dan generator sumber atau waktu eksekusi relatif dari setiap penganalisis atau generator sumber, pergi ke Preferences > Diagnostic Switches dan mengaktifkan EnableDomainReloadTimings. Ketika diaktifkan, informasi ditampilkan di jendela konsol.

Menginstal Analyzer Roslyn yang ada atau generator sumber

Unity tidak mendukung instalasi Roslyn Analyzer atau generator sumber melalui NuGet secara langsung. Contoh di bawah ini menggunakan perpustakaan WordPress.org untuk menunjukkan cara menginstal Roslyn Analyzers dan generator sumber dari NuGet:

  1. Unduh library sebagai file .zip dengan tombol Download package.
  2. Ekstrak isi file .zip.
  3. Di dalam folder yang diekstrak, cari file .dll yang mengandung analyzer. Dalam contoh ini, arahkan ke errorprone.net.coreanalyzers<version-number>\analyzers\dotnet\cd. File yang diperlukan harus berada di folder ini, bernama ErrorProne.NET.Core.dll, ErrorProne.Net.CoreAnalyzers.dll, dan RuntimeContracts.dll.
  4. Pindahkan file ini ke folder Aset, atau folder apa pun yang disarang di dalam folder Aset, dalam proyek Unity Anda. Untuk melakukan ini, baik pergi ke Assets > Import new asset dan pilih .dll untuk setiap tiga file, atau menyalinnya ke folder Aset proyek Anda melalui browser file perangkat Anda.
  5. Klik pada file .dll di dalam Unity untuk membuka jendela Asset Browser.Plugin Inspector window.
  6. Di dalam jendela Plugin Inspector:
    • Di bawah judul Select platforms for plugin, disable Any Platform.
    • Di bawah judul Include Platforms, disable Editor dan Standalone.
  7. Di bawah judul Asset Labels di jendela Plugin Inspector, klik ikon label biru untuk membuka sub-menu Asset Labels.
  8. Buat dan menetapkan label baru yang disebut RoslynAnalyzer. Untuk melakukan ini, ketik “RoslynAnalyzer” ke jendela input teks di sub-menu Asset Labels dan tekan Return. Label ini harus persis cocok dengan contoh dan case sensitive. Setelah Anda membuat label untuk penganalisis pertama, muncul di daftar label yang tersedia di sub-menu Asset Labels. Anda dapat mengklik nama label di menu untuk menetapkannya ke penganalisis lainnya.

Unity mengenali label RoslynAnalyzer dan memperlakukan aset dengan label ini sebagai Roslyn Analyzers atau generator sumber. Ketika Anda menetapkan label pada penganalisis, Unity recompiles scriptsSepotong kode yang memungkinkan Anda untuk membuat Komponen Anda sendiri, memicu peristiwa permainan, memodifikasi sifat komponen dari waktu ke waktu dan menanggapi input pengguna dengan cara apa pun yang Anda sukai. More info
Lihat di Glossary
dalam lingkup penganalisis dan menganalisis kode dalam skrip tersebut sesuai dengan aturan dalam penganalisis. Setiap skrip yang berada dalam definisi perakitan yang sama sebagai penganalisis berada dalam lingkup penganalisis. Untuk menganalisis di tingkat akar folder Aset, Unity mempertimbangkan semua file dalam proyek untuk berada dalam lingkup. Untuk informasi lebih lanjut tentang lingkup, lihat Analisis lingkup di atas.

Untuk menguji bahwa penganalisis Anda bekerja dengan benar, ikuti contoh di bawah ini. Jika Anda telah menginstal penganalisis dengan benar, KesalahanProne. NET analyzer meningkatkan peringatan ketika menganalisis kode dalam contoh.

Buat file skrip baru bernama RethrowError.cs. Salin kode berikut ke script ini dan simpan file:

using System;
using UnityEngine;

public class RethrowError : MonoBehaviour
{
    void Update()
    {
        try
        {
            DoSomethingInteresting();
        }
        catch (Exception e)
        {
            Debug.Log(e.Message);
            throw e;
        }
    }

    private void DoSomethingInteresting()
    {
        throw new System.NotImplementedException();
    }
}

Ketika Anda menyimpan file, Mempersatukan skrip dan menjalankan analisa yang berlaku pada kode skrip. Ketika KesalahanProne. NET analyzer dipasang dengan benar, itu meningkatkan peringatan berikut di jendela Konsol tentang kode di atas:

Assets\RethrowError.cs(14,23): warning EPC12: Suspicious exception handling: only e.Message is observed in exception block.

Assets\RethrowError.cs(15,19): warning ERP021: Incorrect exception propagation. Use throw; instead.

Ruleset files

Untuk menentukan aturan Anda sendiri tentang cara menangani berbagai peringatan dan kesalahan yang dianalisis dalam proyek Anda, Anda dapat membuat file aturan. Untuk informasi lebih lanjut tentang cara membuat aturan kustom, lihat dokumentasi Visual Studio Microsoft pada cara membuat set aturan kustom.

Dalam folder akar Aset, letakkan file aturan bernama Default. Login Aturan yang Anda tentukan secara default. aturan berlaku untuk semua rakitan yang telah ditentukan (misalnya Assembly-CSharp.dll), dan semua rakitan yang dibangun menggunakan file .asmdef.

Untuk menimpa aturan secara default. aturan untuk perakitan yang telah ditentukan, membuat file .ruleset di folder akar dengan nama [PredefinedAssemblyName].ruleset. Sebagai contoh, aturan dalam Assembly-CSharp.ruleset berlaku untuk kode di Assembly-CSharp.dll. Hanya file .ruleset ini diperbolehkan di dalam folder akar:

  • Default.ruleset
  • Assembly-CSharp.ruleset
  • Assembly-CSharp-firstpass.ruleset
  • Assembly-CSharp-Editor.ruleset
  • Assembly-CSharp-Editor-firstpass.ruleset

Sitemap File aturan pengujian dalam Unity

Untuk menguji file aturan dalam Unity, ikuti langkah-langkah ini:

Langkah 1: Mengatur file aturan

  1. Buat subfolder bernama "Subfolder" di dalam folder Aset proyek Anda.
  2. Di dalam Subfolder:
    1. Buat file .asmdef baru.
    2. Simpan salinan duplikat RethrowError.cs.
  3. Buat file default.ruleset dalam Assets dengan kode berikut:
<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="New Rule Set" Description=" " ToolsVersion="10.0">
  <Rules AnalyzerId="ErrorProne.NET.CodeAnalyzers" RuleNamespace="ErrorProne.NET.CodeAnalyzers">
    <Rule Id="ERP021" Action="Error" />
  <Rule Id="EPC12" Action="None" />
  </Rules>
</RuleSet>

File Default.ruleset mendefinisikan aturan berikut:

  • Suppress EPC12, peringatan tentang penanganan pengecualian yang mencurigakan.
  • Meningkatkan ERP021, peringatan tentang perbanyakan pengecualian yang salah, ke kesalahan.

Langkah 2: Muat ulang proyek

Setelah Anda menambahkan file aturan ke proyek Anda, reimport script apa pun yang hidup dalam perakitan di mana aturan harus berlaku. Ini memaksa Unity untuk mengompilkan perakitan menggunakan file aturan baru. Setelah rekompilasi, Anda harus melihat dua pesan di jendela Konsol:

Assets\Subfolder\RethrowError.cs(15,19): error ERP021: Incorrect exception propagation. Use throw; instead.

Assets\RethrowError.cs(15,19): error ERP021: Incorrect exception propagation. Use throw; instead.

Perhatikan bahwa Unity menerapkan aturan yang didefinisikan secara default. aturan untuk kedua Assets/RethrowError.cs dan Assets/Subfolder/RethrowError.cs.

Langkah 3: Tambahkan aturan kustom

Dalam Aset / Subfolder, buat file .ruleset, dan berikan nama apa pun yang Anda suka (dalam exampleHello.ruleset ini):

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="New Rule Set" Description=" " ToolsVersion="10.0">
  <Rules AnalyzerId="ErrorProne.NET.CodeAnalyzers" RuleNamespace="ErrorProne.NET.CodeAnalyzers">
    <Rule Id="ERP021" Action="Info" />
    <Rule Id="EPC12" Action="Info" />
  </Rules>
</RuleSet>

File Hello.ruleset baru ini memberi tahu Unity untuk mencetak EPC12 dan ERP021 ke Konsol, tanpa memperlakukan mereka sebagai peringatan atau kesalahan.

Setelah Unity menyusun proyek lagi, Anda harus melihat pesan ini di jendela Konsol:

Assets\Subfolder\RethrowError.cs(14,23): info EPC12: Suspicious exception handling: only e.Message is observed in exception block.

Assets\Subfolder\RethrowError.cs(15,19): info ERP021: Incorrect exception propagation. Use throw; instead.

Assets\RethrowError.cs(15,19): error ERP021: Incorrect exception propagation. Use throw; instead.

Aturan di Default.ruleset masih berlaku untuk Assets\RethrowError.cs, tetapi tidak lagi berlaku untuk Assets\Subfolder\RethrowError.cs, karena aturan dalam override Hello.ruleset.

Untuk informasi lebih lanjut tentang semua file tindakan aturan yang diizinkan, lihat dokumentasi Visual Studio pada Menggunakan aturan analisis kode set editor.

Analisis lebih lanjut

Berikut ini adalah link ke Github repositories dari perpustakaan analyzer Roslyn populer lainnya:

Pengujian Unit
Konsep Scripting