Menambahkan ekstensi Protokol Server Bahasa

Protokol Server Bahasa (LSP) adalah protokol umum, dalam bentuk JSON RPC v2.0, digunakan untuk menyediakan fitur layanan bahasa ke berbagai editor kode. Dengan menggunakan protokol, pengembang dapat menulis server bahasa tunggal untuk menyediakan fitur layanan bahasa seperti IntelliSense, diagnostik kesalahan, menemukan semua referensi, dan sebagainya, ke berbagai editor kode yang mendukung LSP. Secara tradisional, layanan bahasa di Visual Studio dapat ditambahkan dengan menggunakan file tata bahasa TextMate untuk menyediakan fungsionalitas dasar seperti penyorotan sintaksis atau dengan menulis layanan bahasa kustom yang menggunakan set lengkap API ekstensibilitas Visual Studio untuk menyediakan data yang lebih kaya. Dengan dukungan Visual Studio untuk LSP, ada opsi ketiga.

Untuk memastikan pengalaman pengguna sebaik mungkin, pertimbangkan juga menerapkan Language Configuration, yang menyediakan pemrosesan lokal dari banyak operasi yang sama, dan oleh karena itu dapat meningkatkan performa banyak operasi editor khusus bahasa yang didukung oleh LSP.

Protokol Server Bahasa

Artikel ini menjelaskan cara membuat ekstensi Visual Studio yang menggunakan server bahasa berbasis LSP. Ini mengasumsikan bahwa Anda telah mengembangkan server bahasa berbasis LSP dan hanya ingin mengintegrasikannya ke Visual Studio.

Untuk dukungan dalam Visual Studio, server bahasa dapat berkomunikasi dengan klien (Visual Studio) melalui mekanisme transmisi berbasis aliran apa pun, misalnya:

• Alur input/output standar
• Pipa bernama
• Socket (hanya untuk TCP)

Tujuan dari LSP dan dukungan untuk itu di Visual Studio adalah untuk onboard layanan bahasa yang bukan bagian dari produk Visual Studio. Ini tidak dimaksudkan untuk memperluas layanan bahasa yang ada (seperti C#) di Visual Studio. Untuk memperluas bahasa yang ada, lihat panduan ekstensibilitas layanan bahasa (misalnya, Platform Kompilator .NET Roslyn") atau lihat Memperluas editor dan layanan bahasa.

Untuk informasi selengkapnya tentang protokol itu sendiri, lihat dokumentasi di sini.

Untuk informasi selengkapnya tentang cara membuat server bahasa sampel atau cara mengintegrasikan server bahasa yang ada ke dalam Visual Studio Code, lihat dokumentasi di sini.

Fitur yang didukung Protokol Server Bahasa

Tabel berikut menunjukkan fitur LSP mana yang didukung di Visual Studio:

Mulai sekarang

Membuat proyek VSIX

Untuk membuat ekstensi layanan bahasa menggunakan server bahasa berbasis LSP, pertama-tama pastikan Anda memiliki pengembangan ekstensi untuk Visual Studio Workload yang diinstal untuk instansi VS Anda.

Selanjutnya, buat proyek VSIX baru dengan menavigasi ke File>Proyek Baru>Visual C#>Ekstensibilitas>Proyek VSIX:

Instalasi server bahasa dan runtime

Secara default, ekstensi yang dibuat untuk mendukung server bahasa berbasis LSP di Visual Studio tidak berisi server bahasa itu sendiri atau runtime yang diperlukan untuk menjalankannya. Pengembang ekstensi bertanggung jawab untuk mendistribusikan server bahasa dan runtime yang diperlukan. Ada beberapa cara untuk melakukannya:

• Server bahasa dapat disematkan di VSIX sebagai file konten.
• Buat MSI untuk menginstal server bahasa dan/atau runtime yang diperlukan.
• Berikan instruksi pada Marketplace yang memberi tahu pengguna cara mendapatkan runtime dan server bahasa.

File tata letak TextMate

LSP tidak menyertakan spesifikasi tentang cara menyediakan pewarnaan teks untuk bahasa. Untuk menyediakan pewarnaan kustom untuk bahasa di Visual Studio, pengembang ekstensi dapat menggunakan file tata bahasa TextMate. Untuk menambahkan tata bahasa atau file tema TextMate kustom, ikuti langkah-langkah berikut:

1. Buat folder bernama "Tata Bahasa" di dalam ekstensi Anda (atau dapat berupa nama apa pun yang Anda pilih).

2. Di dalam folder Tata Bahasa, sertakan *.tmlanguage, *.plist, *.tmtheme, atau *.json file yang memberikan pewarnaan kustom sesuai keinginan Anda.

   Saran

   File .tmtheme menentukan bagaimana cakupan memetakan ke klasifikasi Visual Studio yang dinamai kunci warna. Untuk panduan, Anda dapat merujuk file .tmtheme global di direktori %ProgramFiles(x86)%\Microsoft Visual Studio\<versi>\<SKU>\Common7\IDE\CommonExtensions\Microsoft\TextMate\Starterkit\Themesg.

3. Buat file .pkgdef dan tambahkan baris yang mirip dengan ini:

   [$RootKey$\TextMate\Repositories]
   "MyLang"="$PackageFolder$\Grammars"
   

4. Klik kanan pada file dan pilih properti . Ubah tindakan Build menjadi Konten dan ubah properti Sertakan dalam VSIX menjadi true.

Setelah menyelesaikan langkah-langkah sebelumnya, folder tata bahasa ditambahkan ke direktori penginstalan paket sebagai sumber repositori bernama 'MyLang' ('MyLang' hanyalah nama untuk disambiguasi dan dapat berupa string unik apa pun). Semua tata bahasa (file .tmlanguage) dan file tema (file .tmtheme) dalam direktori ini dianggap sebagai kandidat potensial dan menggantikan tata bahasa bawaan yang disediakan dengan TextMate. Jika ekstensi yang dinyatakan dalam file aturan tata bahasa cocok dengan ekstensi file yang sedang dibuka, TextMate akan mengambil alih.

Membuat klien bahasa sederhana

Antarmuka utama - ILanguageClient

Setelah membuat proyek VSIX Anda, tambahkan paket NuGet berikut ke proyek Anda:

• Microsoft.VisualStudio.LanguageServer.Client

Anda kemudian dapat membuat kelas baru yang mengimplementasikan antarmuka ILanguageClient, yang merupakan antarmuka utama yang diperlukan untuk klien bahasa yang terhubung ke server bahasa berbasis LSP.

Berikut ini adalah sampel:

namespace MockLanguageExtension
{
    [ContentType("bar")]
    [Export(typeof(ILanguageClient))]
    public class BarLanguageClient : ILanguageClient
    {
        public string Name => "Bar Language Extension";

        public IEnumerable<string> ConfigurationSections => null;

        public object InitializationOptions => null;

        public IEnumerable<string> FilesToWatch => null;

        public event AsyncEventHandler<EventArgs> StartAsync;
        public event AsyncEventHandler<EventArgs> StopAsync;

        public async Task<Connection> ActivateAsync(CancellationToken token)
        {
            await Task.Yield();

            ProcessStartInfo info = new ProcessStartInfo();
            info.FileName = Path.Combine(Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location), "Server", @"MockLanguageServer.exe");
            info.Arguments = "bar";
            info.RedirectStandardInput = true;
            info.RedirectStandardOutput = true;
            info.UseShellExecute = false;
            info.CreateNoWindow = true;

            Process process = new Process();
            process.StartInfo = info;

            if (process.Start())
            {
                return new Connection(process.StandardOutput.BaseStream, process.StandardInput.BaseStream);
            }

            return null;
        }

        public async Task OnLoadedAsync()
        {
            await StartAsync.InvokeAsync(this, EventArgs.Empty);
        }

        public Task OnServerInitializeFailedAsync(Exception e)
        {
            return Task.CompletedTask;
        }

        public Task OnServerInitializedAsync()
        {
            return Task.CompletedTask;
        }
    }
}

Metode utama yang perlu diimplementasikan adalah OnLoadedAsync dan ActivateAsync. OnLoadedAsync dipanggil ketika Visual Studio telah memuat ekstensi Anda dan server bahasa Anda siap untuk dimulai. Dalam metode ini, Anda dapat segera memanggil delegasi StartAsync untuk memberi sinyal bahwa server bahasa harus dimulai, atau Anda dapat melakukan logika tambahan dan memanggil StartAsync nanti. Untuk mengaktifkan server bahasa Anda, Anda harus memanggil StartAsync di beberapa titik.

ActivateAsync adalah metode yang akhirnya dipanggil dengan memanggil delegasi StartAsync. Ini berisi logika untuk memulai server bahasa dan membuat koneksi ke server tersebut. Objek koneksi yang berisi aliran untuk menulis ke server dan membaca dari server harus dikembalikan. Setiap pengecualian yang terjadi di sini ditangkap dan ditampilkan kepada pengguna dalam bentuk pesan InfoBar di Visual Studio.

Pengaktifan

Setelah kelas klien bahasa Anda diimplementasikan, Anda harus menentukan dua atribut untuk itu untuk menentukan bagaimana itu akan dimuat ke Visual Studio dan diaktifkan:

  [Export(typeof(ILanguageClient))]
  [ContentType("bar")]

MEF

Visual Studio menggunakan MEF (Managed Extensibility Framework) untuk mengelola titik ekstensibilitasnya. Atribut Export menunjukkan kepada Visual Studio bahwa kelas ini harus diambil sebagai titik ekstensi dan dimuat pada waktu yang sesuai.

Untuk menggunakan MEF, Anda juga harus menentukan MEF sebagai Aset dalam manifes VSIX.

Buka perancang manifes VSIX Anda dan navigasikan ke tab Aset:

Klik Baru untuk membuat aset baru:

• Type: Microsoft.VisualStudio.MefComponent
• Sumber : Proyek dalam solusi saat ini
• Project: [Proyek Anda]

Definisi jenis konten

Saat ini, satu-satunya cara untuk memuat ekstensi server bahasa berbasis LSP Anda adalah dengan jenis konten file. Artinya, saat menentukan kelas klien bahasa Anda (yang mengimplementasikan ILanguageClient), Anda harus menentukan jenis file yang, ketika dibuka, akan menyebabkan ekstensi Anda dimuat. Jika tidak ada file yang cocok dengan tipe konten yang Anda tentukan yang dibuka, ekstensi Anda tidak akan dimuat.

Ini dilakukan dengan mendefinisikan satu atau beberapa kelas ContentTypeDefinition:

namespace MockLanguageExtension
{
    public class BarContentDefinition
    {
        [Export]
        [Name("bar")]
        [BaseDefinition(CodeRemoteContentDefinition.CodeRemoteContentTypeName)]
        internal static ContentTypeDefinition BarContentTypeDefinition;

        [Export]
        [FileExtension(".bar")]
        [ContentType("bar")]
        internal static FileExtensionToContentTypeDefinition BarFileExtensionDefinition;
    }
}

Dalam contoh sebelumnya, definisi jenis konten dibuat untuk file yang berakhiran ekstensi file .bar. Definisi jenis konten diberi nama "bar" dan harus berasal dari CodeRemoteContentTypeName.

Setelah menambahkan definisi jenis konten, Anda kemudian dapat menentukan kapan harus memuat ekstensi klien bahasa Anda di kelas klien bahasa:

    [ContentType("bar")]
    [Export(typeof(ILanguageClient))]
    public class BarLanguageClient : ILanguageClient
    {
    }

Menambahkan dukungan untuk server bahasa LSP tidak mengharuskan Anda untuk menerapkan sistem proyek Anda sendiri di Visual Studio. Pelanggan dapat membuka satu file atau folder di Visual Studio untuk mulai menggunakan layanan bahasa Anda. Bahkan, dukungan untuk server bahasa LSP dirancang untuk hanya berfungsi dalam skenario folder/file terbuka. Jika sistem proyek kustom diterapkan, beberapa fitur (seperti pengaturan) tidak akan berfungsi.

Fitur tingkat lanjut

Pengaturan

Dukungan untuk pengaturan khusus server bahasa kustom tersedia, tetapi masih dalam proses ditingkatkan. Pengaturan khusus untuk apa yang didukung server bahasa dan biasanya mengontrol bagaimana server bahasa memancarkan data. Misalnya, server bahasa mungkin memiliki pengaturan untuk jumlah maksimum kesalahan yang dilaporkan. Penulis ekstensi akan menentukan nilai default, yang dapat diubah oleh pengguna untuk proyek tertentu.

Ikuti langkah-langkah berikut untuk menambahkan dukungan untuk pengaturan ke ekstensi layanan bahasa LSP Anda:

1. Tambahkan file JSON (misalnya, MockLanguageExtensionSettings.json) ke proyek Anda yang berisi pengaturan dan nilai defaultnya. Misalnya:

   {
       "foo.maxNumberOfProblems": -1
   }
   

2. Klik kanan pada file JSON dan pilih properti . Ubah tindakan Build menjadi "Konten" dan properti "Sertakan dalam VSIX' menjadi true.

3. Terapkan ConfigurationSections dan kembalikan daftar awalan untuk pengaturan yang ditentukan di file JSON (Di Visual Studio Code, ini akan dipetakan ke nama bagian konfigurasi di package.json).

   public IEnumerable<string> ConfigurationSections
   {
       get
       {
           yield return "foo";
       }
   }
   

4. Tambahkan file .pkgdef ke proyek (tambahkan file teks baru dan ubah ekstensi file ke .pkgdef). File pkgdef harus berisi info ini:

   [$RootKey$\OpenFolder\Settings\VSWorkspaceSettings\[settings-name]]
   @="$PackageFolder$\[settings-file-name].json"
   

   Contoh:

   [$RootKey$\OpenFolder\Settings\VSWorkspaceSettings\MockLanguageExtension]
   @="$PackageFolder$\MockLanguageExtensionSettings.json"
   

5. Klik kanan pada file .pkgdef dan pilih properti . Ubah tindakan Build menjadi Konten dan properti Include in VSIX menjadi true.

6. Buka file source.extension.vsixmanifest dan tambahkan aset di tab Aset.

   

   • Type: Microsoft.VisualStudio.VsPackage
   • Source: File pada sistem file
   • Path: [Jalur ke file .pkgdef Anda]

Pengeditan pengaturan pengguna untuk ruang kerja

1. Pengguna membuka ruang kerja yang berisi file yang dimiliki server Anda.

2. Pengguna menambahkan file di folder .vs yang disebut VSWorkspaceSettings.json.

3. Pengguna menambahkan baris ke file VSWorkspaceSettings.json untuk pengaturan yang disediakan server. Misalnya:

   {
       "foo.maxNumberOfProblems": 10
   }
   

Mengaktifkan pelacakan diagnostik

Pelacakan diagnostik dapat diaktifkan untuk menghasilkan semua pesan antara klien dan server, yang dapat berguna saat men-debug masalah. Untuk mengaktifkan pelacakan diagnostik, lakukan hal berikut:

1. Buka atau buat file pengaturan ruang kerja VSWorkspaceSettings.json (lihat "Pengeditan pengaturan oleh pengguna untuk ruang kerja").
2. Tambahkan baris berikut dalam file json pengaturan:

{
    "foo.trace.server": "Off"
}

Ada tiga nilai yang mungkin untuk verbositas pelacakan:

• "Nonaktif": pelacakan dimatikan sepenuhnya
• "Pesan": pelacakan diaktifkan tetapi hanya nama metode dan ID respons yang dilacak.
• "Verbose": pelacakan diaktifkan; seluruh pesan rpc dilacak.

Ketika pelacakan diaktifkan, konten ditulis ke file di direktori %temp%\VisualStudio\LSP. Log mengikuti format penamaan [LanguageClientName]-[Datetime Stamp].log. Saat ini, pelacakan hanya dapat diaktifkan untuk skenario folder terbuka. Membuka satu file untuk mengaktifkan server bahasa tidak memiliki dukungan pelacakan diagnostik.

Pesan kustom

Ada API untuk memfasilitasi meneruskan pesan ke dan menerima pesan dari server bahasa yang bukan bagian dari Protokol Server Bahasa standar. Untuk menangani pesan kustom, terapkan antarmuka ILanguageClientCustomMessage2 di kelas klien bahasa Anda. pustaka VS-StreamJsonRpc digunakan untuk mengirimkan pesan kustom antara klien bahasa dan server bahasa Anda. Karena ekstensi klien bahasa LSP Anda sama seperti ekstensi Visual Studio lainnya, Anda dapat memutuskan untuk menambahkan fitur tambahan (yang tidak didukung oleh LSP) ke Visual Studio (menggunakan VISUAL Studio API lainnya) di ekstensi Anda melalui pesan kustom.

Menerima pesan kustom

Untuk menerima pesan kustom dari server bahasa, terapkan properti [CustomMessageTarget](/dotnet/api/microsoft.visualstudio.languageserver.client.ilanguageclientcustommessage.custommessagetarget) pada ILanguageClientCustomMessage2 dan mengembalikan objek yang tahu cara menangani pesan kustom Anda. Contoh di bawah ini:

(/dotnet/api/microsoft.visualstudio.languageserver.client.ilanguageclientcustommessage.custommessagetarget) properti pada ILanguageClientCustomMessage2 dan mengembalikan objek yang tahu cara menangani pesan kustom Anda. Contoh di bawah ini:

internal class MockCustomLanguageClient : MockLanguageClient, ILanguageClientCustomMessage2
{
    private JsonRpc customMessageRpc;

    public MockCustomLanguageClient() : base()
    {
        CustomMessageTarget = new CustomTarget();
    }

    public object CustomMessageTarget
    {
        get;
        set;
    }

    public class CustomTarget
    {
        public void OnCustomNotification(JToken arg)
        {
            // Provide logic on what happens OnCustomNotification is called from the language server
        }

        public string OnCustomRequest(string test)
        {
            // Provide logic on what happens OnCustomRequest is called from the language server
        }
    }
}

Mengirim pesan kustom

Untuk mengirim pesan kustom ke server bahasa, terapkan metode AttachForCustomMessageAsync pada ILanguageClientCustomMessage2. Metode ini dipanggil ketika server bahasa Anda dimulai dan siap untuk menerima pesan. Objek JsonRpc diteruskan sebagai parameter, yang kemudian dapat Anda simpan untuk mengirim pesan ke server bahasa menggunakan API VS-StreamJsonRpc. Contoh di bawah ini:

internal class MockCustomLanguageClient : MockLanguageClient, ILanguageClientCustomMessage2
{
    private JsonRpc customMessageRpc;

    public MockCustomLanguageClient() : base()
    {
        CustomMessageTarget = new CustomTarget();
    }

    public async Task AttachForCustomMessageAsync(JsonRpc rpc)
    {
        await Task.Yield();

        this.customMessageRpc = rpc;
    }

    public async Task SendServerCustomNotification(object arg)
    {
        await this.customMessageRpc.NotifyWithParameterObjectAsync("OnCustomNotification", arg);
    }

    public async Task<string> SendServerCustomMessage(string test)
    {
        return await this.customMessageRpc.InvokeAsync<string>("OnCustomRequest", test);
    }
}

Lapisan tengah

Terkadang pengembang ekstensi mungkin ingin mencegat pesan LSP yang dikirim ke dan diterima dari server bahasa. Misalnya, pengembang ekstensi mungkin ingin mengubah parameter pesan yang dikirim untuk pesan LSP tertentu, atau memodifikasi hasil yang dikembalikan dari server bahasa untuk fitur LSP (misalnya penyelesaian). Jika diperlukan, pengembang ekstensi dapat menggunakan MIDDLELayer API untuk mencegat pesan LSP.

Untuk mencegat pesan tertentu, buat kelas yang mengimplementasikan antarmuka ILanguageClientMiddleLayer. Kemudian, terapkan antarmuka ILanguageClientCustomMessage2 di kelas klien bahasa Anda dan kembalikan instans objek Anda di properti MiddleLayer. Contoh di bawah ini:

public class MockLanguageClient : ILanguageClient, ILanguageClientCustomMessage2
{
  public object MiddleLayer => DiagnosticsFilterMiddleLayer.Instance;

  private class DiagnosticsFilterMiddleLayer : ILanguageClientMiddleLayer
  {
    internal readonly static DiagnosticsFilterMiddleLayer Instance = new DiagnosticsFilterMiddleLayer();

    private DiagnosticsFilterMiddleLayer() { }

    public bool CanHandle(string methodName)
    {
      return methodName == "textDocument/publishDiagnostics";
    }

    public async Task HandleNotificationAsync(string methodName, JToken methodParam, Func<JToken, Task> sendNotification)
    {
      if (methodName == "textDocument/publishDiagnostics")
      {
        var diagnosticsToFilter = (JArray)methodParam["diagnostics"];
        // ony show diagnostics of severity 1 (error)
        methodParam["diagnostics"] = new JArray(diagnosticsToFilter.Where(diagnostic => diagnostic.Value<int?>("severity") == 1));

      }
      await sendNotification(methodParam);
    }

    public async Task<JToken> HandleRequestAsync(string methodName, JToken methodParam, Func<JToken, Task<JToken>> sendRequest)
    {
      return await sendRequest(methodParam);
    }
  }
}

Fitur lapisan tengah masih dalam pengembangan dan belum komprehensif.

Sampel ekstensi server bahasa LSP

Untuk melihat kode sumber ekstensi sampel menggunakan API klien LSP di Visual Studio, lihat sampel VSSDK-Extensibility-Samples LSP.

FAQ

saya ingin membangun sistem proyek kustom untuk melengkapi server bahasa LSP saya untuk memberikan dukungan fitur yang lebih kaya di Visual Studio, bagaimana cara melakukannya?

Dukungan untuk server bahasa berbasis LSP di Visual Studio bergantung pada fitur folder terbuka dan dirancang untuk tidak memerlukan sistem proyek kustom. Anda dapat membangun sistem proyek kustom Anda sendiri mengikuti instruksi di sini, tetapi beberapa fitur, seperti pengaturan, mungkin tidak berfungsi. Logika inisialisasi default untuk server bahasa LSP adalah meneruskan lokasi folder akar folder yang saat ini sedang dibuka, jadi jika Anda menggunakan sistem proyek kustom, Anda mungkin perlu memberikan logika kustom selama inisialisasi untuk memastikan server bahasa Anda dapat dimulai dengan benar.

Bagaimana cara menambahkan dukungan debugger?

Kami akan memberikan dukungan untuk protokol debugging umum dalam rilis mendatang.

Jika sudah ada layanan bahasa yang didukung VS yang diinstal (misalnya, JavaScript), apakah saya masih dapat menginstal ekstensi server bahasa LSP yang menawarkan fitur tambahan (seperti linting)?

Ya, tetapi tidak semua fitur akan berfungsi dengan baik. Tujuan utama untuk ekstensi server bahasa LSP adalah untuk mengaktifkan layanan bahasa yang tidak didukung secara asli oleh Visual Studio. Anda dapat membuat ekstensi yang menawarkan dukungan tambahan menggunakan server bahasa LSP, tetapi beberapa fitur (seperti IntelliSense) tidak akan menjadi pengalaman yang lancar. Secara umum, disarankan agar ekstensi server bahasa LSP digunakan untuk memberikan pengalaman bahasa baru, tidak memperluas yang ada.

Di mana saya menerbitkan VSIX server bahasa LSP saya yang telah selesai?

Lihat instruksi Marketplace di sini.

Konten terkait

• Menambahkan dukungan editor Visual Studio untuk bahasa lain

• Menyesuaikan perilaku editor dengan menggunakan Konfigurasi Bahasa