Petunjuk Langkah-demi-Langkah: Menampilkan Saran Lampu

2025-06-12

Bola lampu adalah ikon di editor Visual Studio yang diperluas untuk menampilkan serangkaian tindakan, misalnya, perbaikan untuk masalah yang diidentifikasi oleh penganalisis kode bawaan atau pemfaktoran ulang kode.

Di editor Visual C# dan Visual Basic, Anda juga dapat menggunakan .NET Compiler Platform ("Roslyn") untuk menulis dan mengemas penganalisis kode Anda sendiri dengan tindakan yang menampilkan bola lampu secara otomatis. Untuk informasi selengkapnya, lihat:

Cara: Menulis diagnostik C# dan perbaikan kode
Cara: Menulis diagnostik Visual Basic dan perbaikan kode

Bahasa lain seperti C++ juga menyediakan bola lampu untuk beberapa tindakan cepat, seperti, saran untuk membuat implementasi stub dari fungsi tersebut.

Bola lampu terlihat seperti ini. Dalam proyek Visual Basic atau Visual C#, garis merah bergelombang muncul di bawah nama variabel ketika variabel tersebut tidak valid. Jika Anda mengarahkan mouse ke pengidentifikasi yang tidak valid, bola lampu muncul di dekat kursor.

Jika Anda klik panah bawah di samping bola lampu, sekumpulan tindakan yang disarankan akan muncul, bersama dengan pratinjau tindakan yang dipilih. Dalam hal ini, ini menunjukkan perubahan yang dibuat pada kode Anda jika Anda menjalankan tindakan.

pratinjau bola lampu

Anda dapat menggunakan bola lampu untuk memberikan tindakan yang anda sarankan sendiri. Misalnya, Anda dapat memberikan langkah memindahkan kurung kurawal pembuka ke baris baru atau ke akhir baris sebelumnya. Panduan berikut menunjukkan cara membuat bola lampu yang muncul pada kata saat ini dan memiliki dua tindakan yang disarankan: Ubah menjadi huruf besar dan Ubah menjadi huruf kecil.

Membuat proyek Managed Extensibility Framework (MEF)

Buat proyek C# VSIX. (Dalam dialog Proyek Baru, pilih Visual C# / Ekstensibilitas, lalu Proyek VSIX .) Beri nama solusi LightBulbTest.
Tambahkan templat item Pengklasifikasi Editor ke proyek. Untuk informasi selengkapnya, lihat Membuat ekstensi dengan templat item editor.
Hapus file kelas yang ada.
Tambahkan referensi berikut ke proyek, dan atur Salin Lokal ke False:

Microsoft.VisualStudio.Language.Intellisense
Tambahkan file kelas baru dan beri nama LightBulbTest.

Tambahkan yang berikut ini dengan menggunakan perintah:

using System;
using System.Linq;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.VisualStudio.Language.Intellisense;
using Microsoft.VisualStudio.Text;
using Microsoft.VisualStudio.Text.Editor;
using Microsoft.VisualStudio.Text.Operations;
using Microsoft.VisualStudio.Utilities;
using System.ComponentModel.Composition;
using System.Threading;

Menerapkan penyedia sumber bola lampu

Dalam file kelas LightBulbTest.cs, hapus kelas LightBulbTest. Tambahkan kelas bernama TestSuggestedActionsSourceProvider yang mengimplementasikan ISuggestedActionsSourceProvider. Ekspor dengan Nama Uji Tindakan yang Disarankan dan ContentTypeAttribute "teks".
```
[Export(typeof(ISuggestedActionsSourceProvider))]
[Name("Test Suggested Actions")]
[ContentType("text")]
internal class TestSuggestedActionsSourceProvider : ISuggestedActionsSourceProvider
```

Di dalam kelas penyedia sumber, impor ITextStructureNavigatorSelectorService dan tambahkan sebagai properti.

[Import(typeof(ITextStructureNavigatorSelectorService))]
internal ITextStructureNavigatorSelectorService NavigatorService { get; set; }

Terapkan metode CreateSuggestedActionsSource untuk mengembalikan objek ISuggestedActionsSource. Sumber dibahas di bagian berikutnya.

public ISuggestedActionsSource CreateSuggestedActionsSource(ITextView textView, ITextBuffer textBuffer)
{
    if (textBuffer == null || textView == null)
    {
        return null;
    }
    return new TestSuggestedActionsSource(this, textView, textBuffer);
}

Menerapkan sumber ISuggestedAction

Sumber tindakan yang disarankan bertanggung jawab untuk mengumpulkan serangkaian tindakan yang disarankan dan menambahkannya dalam konteks yang tepat. Dalam hal ini, konteksnya adalah kata saat ini dan tindakan yang disarankan adalah UpperCaseSuggestedAction dan LowerCaseSuggestedAction, yang dibahas di bagian berikut.

Tambahkan kelas TestSuggestedActionsSource yang mengimplementasikan ISuggestedActionsSource.
```
internal class TestSuggestedActionsSource : ISuggestedActionsSource
```

Tambahkan bidang privat baca-saja untuk penyedia sumber tindakan yang disarankan, buffer teks, dan tampilan teks.

private readonly TestSuggestedActionsSourceProvider m_factory;
private readonly ITextBuffer m_textBuffer;
private readonly ITextView m_textView;

Tambahkan konstruktor yang mengatur bidang privat.

public TestSuggestedActionsSource(TestSuggestedActionsSourceProvider testSuggestedActionsSourceProvider, ITextView textView, ITextBuffer textBuffer)
{
    m_factory = testSuggestedActionsSourceProvider;
    m_textBuffer = textBuffer;
    m_textView = textView;
}

Tambahkan metode privat yang mengembalikan kata yang saat ini berada di bawah kursor. Metode berikut melihat lokasi kursor saat ini dan meminta navigator struktur teks sejauh mana kata tersebut. Jika kursor berada pada sebuah kata, TextExtent dikembalikan dalam parameter keluaran; jika tidak, parameter out adalah null dan metode mengembalikan false.

private bool TryGetWordUnderCaret(out TextExtent wordExtent)
{
    ITextCaret caret = m_textView.Caret;
    SnapshotPoint point;

    if (caret.Position.BufferPosition > 0)
    {
        point = caret.Position.BufferPosition - 1;
    }
    else
    {
        wordExtent = default(TextExtent);
        return false;
    }

    ITextStructureNavigator navigator = m_factory.NavigatorService.GetTextStructureNavigator(m_textBuffer);

    wordExtent = navigator.GetExtentOfWord(point);
    return true;
}

Terapkan metode HasSuggestedActionsAsync. Editor memanggil metode ini untuk mengetahui apakah akan menampilkan bola lampu. Panggilan ini sering dilakukan, misalnya, setiap kali kursor bergerak dari satu baris ke baris lain, atau ketika mouse melayang di atas garis bergelombang penanda kesalahan. Ini asinkron untuk memungkinkan operasi UI lain untuk dilaksanakan saat metode ini berfungsi. Dalam kebanyakan kasus, metode ini perlu melakukan beberapa penguraian dan analisis baris saat ini, sehingga pemrosesan mungkin memakan waktu.

Dalam implementasi ini, secara asinkron mengambil TextExtent dan menentukan apakah ukurannya signifikan, yaitu apakah ia memiliki beberapa teks selain spasi.
```
public Task<bool> HasSuggestedActionsAsync(ISuggestedActionCategorySet requestedActionCategories, SnapshotSpan range, CancellationToken cancellationToken)
{
    return Task.Factory.StartNew(() =>
    {
        TextExtent extent;
        if (TryGetWordUnderCaret(out extent))
        {
            // don't display the action if the extent has whitespace
            return extent.IsSignificant;
          }
        return false;
    });
}
```

Terapkan metode GetSuggestedActions, yang mengembalikan array objek SuggestedActionSet yang berisi objek ISuggestedAction yang berbeda. Metode ini dipanggil ketika bola lampu diperluas.

Peringatan

Anda harus memastikan bahwa implementasi HasSuggestedActionsAsync() dan GetSuggestedActions() konsisten; artinya, jika HasSuggestedActionsAsync() mengembalikan true, maka GetSuggestedActions() harus memiliki beberapa tindakan untuk ditampilkan. Dalam banyak kasus, HasSuggestedActionsAsync() dipanggil tepat sebelum GetSuggestedActions(), tetapi ini tidak selalu terjadi. Misalnya, jika pengguna memanggil tindakan bola lampu dengan menekan (CTRL+ .) hanya GetSuggestedActions() yang dipanggil.

public IEnumerable<SuggestedActionSet> GetSuggestedActions(ISuggestedActionCategorySet requestedActionCategories, SnapshotSpan range, CancellationToken cancellationToken)
{
    TextExtent extent;
    if (TryGetWordUnderCaret(out extent) && extent.IsSignificant)
    {
        ITrackingSpan trackingSpan = range.Snapshot.CreateTrackingSpan(extent.Span, SpanTrackingMode.EdgeInclusive);
        var upperAction = new UpperCaseSuggestedAction(trackingSpan);
        var lowerAction = new LowerCaseSuggestedAction(trackingSpan);
        return new SuggestedActionSet[] { new SuggestedActionSet(new ISuggestedAction[] { upperAction, lowerAction }) };
    }
    return Enumerable.Empty<SuggestedActionSet>();
}

Tentukan peristiwa SuggestedActionsChanged.

public event EventHandler<EventArgs> SuggestedActionsChanged;

Untuk menyelesaikan implementasi, tambahkan implementasi untuk metode Dispose() dan TryGetTelemetryId(). Anda tidak ingin melakukan telemetri, jadi kembalikan false dan atur GUID ke Empty.

public void Dispose()
{
}

public bool TryGetTelemetryId(out Guid telemetryId)
{
    // This is a sample provider and doesn't participate in LightBulb telemetry
    telemetryId = Guid.Empty;
    return false;
}

Melaksanakan tindakan terkait bola lampu

Dalam proyek, tambahkan referensi ke Microsoft.VisualStudio.Imaging.Interop.14.0.DesignTime.dll dan atur Salin Lokal ke False.
Buat dua kelas, yang pertama bernama UpperCaseSuggestedAction dan yang kedua bernama LowerCaseSuggestedAction. Kedua kelas menerapkan ISuggestedAction.
```
internal class UpperCaseSuggestedAction : ISuggestedAction
internal class LowerCaseSuggestedAction : ISuggestedAction
```
Kedua kelas sama kecuali yang satu memanggil ToUpper dan yang lainnya memanggil ToLower. Langkah-langkah berikut hanya mencakup kelas tindakan huruf besar, tetapi Anda harus mengimplementasikan kedua kelas. Gunakan langkah-langkah untuk menerapkan tindakan huruf besar sebagai pola untuk menerapkan tindakan huruf kecil.

Tambahkan direktif berikut untuk kelas-kelas ini:

using Microsoft.VisualStudio.Imaging.Interop;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Documents;
using System.Windows.Media;

Deklarasikan sekumpulan variabel privat.

private ITrackingSpan m_span;
private string m_upper;
private string m_display;
private ITextSnapshot m_snapshot;

Tambahkan konstruktor yang mengatur bidang.

public UpperCaseSuggestedAction(ITrackingSpan span)
{
    m_span = span;
    m_snapshot = span.TextBuffer.CurrentSnapshot;
    m_upper = span.GetText(m_snapshot).ToUpper();
    m_display = string.Format("Convert '{0}' to upper case", span.GetText(m_snapshot));
}

Terapkan metode GetPreviewAsync sehingga menampilkan pratinjau tindakan.

public Task<object> GetPreviewAsync(CancellationToken cancellationToken)
{
    var textBlock = new TextBlock();
    textBlock.Padding = new Thickness(5);
    textBlock.Inlines.Add(new Run() { Text = m_upper });
    return Task.FromResult<object>(textBlock);
}

Terapkan metode GetActionSetsAsync sehingga mengembalikan enumerasi SuggestedActionSet kosong.

public Task<IEnumerable<SuggestedActionSet>> GetActionSetsAsync(CancellationToken cancellationToken)
{
    return Task.FromResult<IEnumerable<SuggestedActionSet>>(null);
}

Terapkan properti sebagai berikut.

public bool HasActionSets
{
    get { return false; }
}
public string DisplayText
{
    get { return m_display; }
}
public ImageMoniker IconMoniker
{
   get { return default(ImageMoniker); }
}
public string IconAutomationText
{
    get
    {
        return null;
    }
}
public string InputGestureText
{
    get
    {
        return null;
    }
}
public bool HasPreview
{
    get { return true; }
}

Terapkan metode Invoke dengan mengganti teks dalam rentang dengan huruf besar yang setara.
```
public void Invoke(CancellationToken cancellationToken)
{
    m_span.TextBuffer.Replace(m_span.GetSpan(m_snapshot), m_upper);
}
```
Peringatan

Tindakan bola lampu Memanggil metode tidak diharapkan untuk menampilkan UI. Jika tindakan Anda memunculkan UI baru (misalnya dialog pratinjau atau pilihan), jangan tampilkan UI langsung dari dalam metode Panggil tetapi jadwalkan untuk menampilkan UI Anda setelah kembali dari Panggil.

Untuk menyelesaikan implementasi, tambahkan metode Dispose() dan TryGetTelemetryId().

public void Dispose()
{
}

public bool TryGetTelemetryId(out Guid telemetryId)
{
    // This is a sample action and doesn't participate in LightBulb telemetry
    telemetryId = Guid.Empty;
    return false;
}

Jangan lupa untuk melakukan hal yang sama untuk LowerCaseSuggestedAction dengan mengubah teks yang ditampilkan menjadi "Konversi '{0}' ke huruf kecil" dan panggilan ToUpper ke ToLower.

Membangun dan menguji kode

Untuk menguji kode ini, buat solusi LightBulbTest dan jalankan dalam instans Eksperimental.

Bangun solusinya.
Saat Anda menjalankan proyek ini dalam debugger, Visual Studio memulai instans kedua.
Buat file teks dan ketik beberapa teks. Anda akan melihat bola lampu di sebelah kiri teks.
Arahkan ke bola lampu. Anda seharusnya melihat panah ke bawah.
Saat Anda mengklik bola lampu, dua tindakan yang disarankan harus ditampilkan, bersama dengan pratinjau tindakan yang dipilih.
Jika Anda mengklik tindakan pertama, semua teks dalam kata saat ini harus dikonversi ke huruf besar. Jika Anda mengklik tindakan kedua, semua teks harus dikonversi ke huruf kecil.

Bagikan melalui