Basit bir uzantı oluşturma

  • Makale

İlk uzantınızı oluşturma bölümünde VisualStudio.Genişletilebilirlik proje şablonunu kullanarak bir uzantı projesi oluşturmayı ve Visual Studio'nun deneysel örneğinde hata ayıklamayı öğrendiniz.

Bu öğreticide, Visual Studio düzenleyicisinde bir şeyler yapmaya yönelik basit bir komutla uzantı oluşturmayı öğreneceksiniz. Bu durumda, yeni oluşturulan bir GUID ekler. Ayrıca, Visual Studio'ya GUID uzantısının hangi dosya türleri için etkinleştirildiğini ve yeni komutun araç çubuğu veya menü öğesi olarak gösterilmesini nasıl sağlayacağınızı da görürsünüz.

Bu öğretici için tamamlanmış örnek burada bulunabilir.

Öğretici aşağıdaki adımları içerir:

Komutu yapılandırma

Bu adımda, komutu yapılandırma ve yerleştirme seçenekleri hakkında bilgi edineceksiniz. Komutu barındırmanın amacı, menü öğesi veya komut çubuğu düğmesi ekleme gibi bir şekilde kullanıcıya göstermektir.

İlk uzantınızı oluşturma öğreticisinde oluşturduğunuz proje şablonu veya örnek, zaten bir sınıf içeren tek bir Command C# dosyasından oluşur. Bunu yerinde güncelleştirebilirsiniz.

  1. dosyasını InsertGuidCommand.csolarak yeniden adlandırınCommand1.cs, sınıfını InsertGuidCommandyeniden adlandırın, özelliğini güncelleştirinCommandConfiguration.

    public override CommandConfiguration CommandConfiguration => new("%InsertGuidCommand.DisplayName%")
{
    Placements = new[] { CommandPlacement.KnownPlacements.ExtensionsMenu },
};

    Placements komutun IDE'de nerede görüneceğini belirtir. Bu durumda, komut Visual Studio'nun en üst düzey menülerinden biri olan Uzantılar menüsüne yerleştirilir.

    Oluşturucunun CommandConfiguration bağımsız değişkeni, komutun görünen adıdır ve bu da menü metnidir. Görünen ad, yerelleştirmeyi desteklemek için bir dize kaynağına .vsextension/string-resources.json başvuracağından karakterlerle % çevrilir.

  2. görünen adıyla güncelleştirin .vsextension/string-resources.json InsertGuidCommand.

    {
  "InsertGuidCommand.DisplayName": "Insert new guid"
}

  3. Icon özelliğini ekleyin.

    public override CommandConfiguration CommandConfiguration => new("%InsertGuidCommand.DisplayName%")
{
    Placements = new[] { CommandPlacement.KnownPlacements.ExtensionsMenu },
    Icon = new(ImageMoniker.KnownValues.OfficeWebExtension, IconSettings.IconAndText),
};

    Bu örnekte OfficeWebExtensionbilinen bir yerleşik simge belirtebilir veya Visual Studio komutları ekleme bölümünde açıklandığı gibi simge için görüntüleri karşıya yükleyebilirsiniz. İkinci bağımsız değişken, komutun araç çubuklarında (menüdeki yerine ek olarak) nasıl görüneceğini belirleyen bir numaralandırmadır. seçeneği IconSettings.IconAndText , simgeyi ve görünen adı yan yana gösterme anlamına gelir.

  4. VisibleWhen Öğenin kullanıcıya görünmesi için uygulanması gereken koşulları belirten özelliğini ekleyin.

    public override CommandConfiguration CommandConfiguration => new("%InsertGuidCommand.DisplayName%")
{
    Placements = new[] { CommandPlacement.KnownPlacements.ExtensionsMenu },
    Icon = new(ImageMoniker.KnownValues.OfficeWebExtension, IconSettings.IconAndText),
    VisibleWhen = ActivationConstraint.ClientContext(ClientContextKey.Shell.ActiveEditorContentType, ".+"),
};

Daha fazla bilgi için bkz . kural tabanlı etkinleştirme kısıtlamalarını kullanma.

Yürütme yöntemini oluşturma

Bu adımda, kullanıcı menü öğesini seçtiğinde veya komutunuzun ExecuteCommandAsync araç çubuğundaki öğeye bastığında ne olacağını tanımlayan komutun yöntemini uygularsınız.

yöntemini uygulamak için aşağıdaki kodu kopyalayın.

public override async Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
    {
        Requires.NotNull(context, nameof(context));
        var newGuidString = Guid.NewGuid().ToString("N", CultureInfo.CurrentCulture);

        using var textView = await context.GetActiveTextViewAsync(cancellationToken);
        if (textView is null)
        {
            this.logger.TraceInformation("There was no active text view when command is executed.");
            return;
        }

        await this.Extensibility.Editor().EditAsync(
            batch =>
            {
                textView.Document.AsEditable(batch).Replace(textView.Selection.Extent, newGuidString);
            },
            cancellationToken);
    }

İlk satır bağımsız değişkenleri doğrular, ardından daha sonra kullanmak üzere yeni Guid bir oluştururuz.

Ardından, zaman uyumsuz yöntemini GetActiveTextViewAsyncçağırarak bir ITextViewSnapshot (textViewburadaki nesne) oluştururuz. Zaman uyumsuz isteği iptal etme özelliğini korumak için bir iptal belirteci geçirilir, ancak bu bölüm bu örnekte gösterilmiyor. Metin görünümünü başarıyla alamazsak günlüğe yazar ve başka bir şey yapmadan sonlandırabiliriz.

Artık Visual Studio'nun düzenleyicisine düzenleme isteği gönderen zaman uyumsuz yöntemi çağırmaya hazırız. İstediğimiz yöntemdir EditAsync. Bu, IDE'de çalışan Visual Studio Düzenleyicisi ile etkileşime izin veren sınıfının bir üyesidir EditorExtensibility . Command Kendi InsertGuidCommand sınıfınızın devraldığı türün nesnesine EditorExtensibility erişim sağlayan bir üyesi Extensibility vardır, böylece sınıfına EditorExtensibility this.Extensibility.Editor()çağrısıyla ulaşabiliriz.

EditAsync yöntemi parametre olarak bir Action<IEditBatch> alır. Bu parametre olarak adlandırılır editorSource.

çağrısı EditAsync bir lambda ifadesi kullanır. Bunu biraz bölmek için bu çağrıyı aşağıdaki gibi de yazabilirsiniz:

await this.Extensibility.Editor().EditAsync(
    batch =>
    {
        var editor = textView.Document.AsEditable(batch);
        // specify the desired changes here:
        editor.Replace(textView.Selection.Extent, newGuidString);
    },
    cancellationToken);

Bu çağrıyı Visual Studio düzenleyicisi işleminde çalıştırmak istediğiniz kodu belirtmek olarak düşünebilirsiniz. Lambda ifadesi, düzenleyicide nelerin değiştirilmesini istediğinizi belirtir. batch türündedir IEditBatchve burada tanımlanan lambda ifadesinin, kullanıcı veya dil hizmeti tarafından yapılan diğer düzenlemeler tarafından kesintiye uğramak yerine birim olarak gerçekleştirilmesi gereken küçük bir değişiklik kümesi yaptığını gösterir. Kod çok uzun süre yürütülürse bu yanıt vermemeye yol açabilir, bu nedenle bu lambda ifadesinde yapılan değişiklikleri sınırlı tutmak ve gecikmelere neden olabilecek her şeyi anlamak önemlidir.

Belgedeki AsEditable yöntemini kullanarak, istediğiniz değişiklikleri belirtmek için kullanabileceğiniz geçici bir düzenleyici nesnesi alırsınız. Lambda ifadesindeki her şeyi, Visual Studio düzenleyicisi genişletilebilirliğini kullanma bölümünde açıklandığı gibi, uzantılardan gelen bu zaman uyumsuz düzenleme isteklerini işlemeye yönelik belirli bir protokol olduğundan ve kullanıcının çakışma oluşturan aynı anda değişiklikler yapıyor olması gibi kabul edilmeme olasılığı olduğundan, lambda ifadesindeki her şeyi yürütme isteği olarak düşünün.

Desen, EditAsync "burada istediğiniz değişiklikleri belirtin" açıklamasından sonra yaptığınız değişiklikleri belirterek metni genel olarak değiştirmek için kullanılabilir.