Share via

Visual Studio komutları ekleme

  • Makale

Sınıfı tarafından Command temsil edilen komut, kullanıcı tarafından başlatılabilir bir eylemdir; örneğin, kullanıcı bir menü öğesi seçtiğinde, bir araç çubuğu düğmesine bastığında veya klavye kısayolu yazarken. Komutlar bir görünen ada, eylemi gerçekleştiren bir yürütme yöntemine (ExecuteCommandAsync), komutu tanımlamak için araç çubuğunda görüntüleme simgesine ve komutu kullanıcıya açıklamaya yönelik bir araç ipucuna sahiptir. Komutlar çeşitli koşullara bağlı olarak etkinleştirilebilir veya devre dışı bırakılabilir.

Yeni Genişletilebilirlik Modeli'ndeki komutlar zaman uyumsuz olarak çalıştırılır, böylece komutlar yürütülürken kullanıcı IDE ile etkileşime devam edebilir.

Komutlarla çalışma

Bu genel bakış, komutlarla çalışmaya yönelik şu en önemli senaryoları kapsar:

Komut oluşturma

Yeni Genişletilebilirlik Modeli ile komut oluşturma, temel sınıfı genişletme, sınıfı Commandözniteliğiyle donatma ve özelliğini uygulama CommandConfiguration ile VisualStudioContribution başlar.

[VisualStudioContribution]
public class MyCommand : Command
{
  /// <inheritdoc />
  public override CommandConfiguration CommandConfiguration => new("%MyCommand.DisplayName%");
}

CommandConfiguration sınıfı

sınıfı, CommandConfiguration tanımanız gereken birkaç parametreye sahiptir:

Parametre Türü Zorunlu Açıklama
DisplayName Diize Yes Komutunuzun varsayılan görünen adı. Bu dizeyi yerelleştirmeyi etkinleştirmek için bu dizeyi '%' karakteriyle çevreleyin. Bkz. Meta verileri yerelleştirme.
ToolTipText String Hayır Komut üzerine gelindiğinde veya odaklanıldığında araç ipucu olarak görüntülenecek metin. Bu dizeyi yerelleştirmeyi etkinleştirmek için bu dizeyi '%' karakteriyle çevreleyin. Bkz. Meta verileri yerelleştirme
Bayraklar CommandFlags Hayır Komutunda ek özellikleri ayarlamak için bayraklar. Bazı seçenekler CanToggle ve CanSelect'tir. Bkz. Komut Bayrakları.
Yerleşim CommandPlacement[] Hayır Visual Studio'da Command'un üst öğesi olarak kullanılacak mevcut grupları belirtir. Bkz. IDE'ye komut yerleştirme. Yerleştirme olmadan bile, komutunuz Visual Studio Arama özelliği aracılığıyla kullanılabilir olmaya devam eder. Komutlar, uzantınızda tanımlanan Menüler, Araç Çubukları ve Gruplar'a da yerleştirilebilir.
Icon CommandIconConfiguration Hayır Komutlar kullanıcı arabiriminde yalnızca bir Simge, metin içeren bir Simge veya yalnızca metin olarak görüntülenebilir. Bu özellik, bu simgenin ne olması gerektiğini, varsa nasıl görüntülenmesi gerektiğini yapılandırmaktadır.
Kısayollar CommandShortcutConfiguration[] Hayır Komutunu yürütmek için kullanılabilecek tuş bileşimleri kümesini tanımlar. Kısayolların kapsamı yalnızca belirli IDE bağlamları için geçerli olacak şekilde daraltılabilir. Bkz. Kısayollar.
ClientContexts[] String Hayır komutu tarafından istenen istemci bağlamları. Varsayılan olarak Kabuk ve Düzenleyici bağlamları döndürülür. İstemci bağlamı, komutun ilk yürütülürken belirli IDE durumlarının anlık görüntüsüdür. Bu komutlar zaman uyumsuz olarak yürütülürken, bu durum kullanıcının komutu yürütmesi ile çalışan komut işleyicisi arasında değişebilir. bkz. İstemci bağlamları.

Örnek

ayrıca Command nesnesini alan VisualStudioExtensibility bir oluşturucuya (IDE ile iletişime izin veren) ve bir yürütme yöntemi ExecuteCommandAsyncgerekir. Aşağıdaki örnek, hiçbir şey yapmayan genel bir komutun en az uygulamasını sağlar:

[VisualStudioContribution]
public class MyCommand : Command
{
    /// <inheritdoc />
    public override CommandConfiguration CommandConfiguration => new("%MyCommand.DisplayName%");

    public MyCommand(VisualStudioExtensibility extensibility)
        : base(extensibility)
    {
    }

    public override Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }
}

IDE'ye komut yerleştirme

Visual Studio'da komutların yerleştirilebileceği iyi tanımlanmış bir dizi yer vardır. Bu yerleştirmeler sınıfındaki CommandPlacementözelliği KnownPlacements tarafından tanımlanır. Geçerli kümesi KnownPlacements :

  • ToolsMenu - Komut, Visual Studio'da üst düzey "Araçlar" menüsünün altındaki bir gruba yerleştirilir.
  • ViewOtherWindowsMenu - Komut, Visual Studio'da üst düzey "Görünüm" -> "Diğer Pencereler" menüsünün altındaki bir gruba yerleştirilir.
  • ExtensionsMenu - Komut, Visual Studio'da üst düzey "Uzantılar" menüsünün altındaki bir gruba yerleştirilir.

Komutlar, VSCT aracılığıyla tanımlanan ve Id grubu belirtilerek Guid yöntemi kullanılarak CommandPlacement.VsctParent da yerleştirilebilir.

Aynı grubun üst öğesi olan komutlar, yerleşimlerinin özelliğine göre, aynı yerleşime Priority sahip diğer komutlara veya menülere göre sıralanır. için CommandPlacement varsayılan Priority değerdir 0 ve yöntemi çağrılarakCommandPlacement.WithPriority, istenen Priority değer geçirilerek değiştirilebilir.

public override CommandConfiguration CommandConfiguration => new("%MyCommand.DisplayName%")
{
    // The command will be parented to a group inside of the "Tools" top level menu,
    // a group inside of the "Extensions" top level menu, and the "About" group inside of the "Help" top level menu
    Placements = new CommandPlacement[]
    {
        CommandPlacement.KnownPlacements.ToolsMenu,
        CommandPlacement.KnownPlacements.ExtensionsMenu.WithPriority(0x0100),
        CommandPlacement.VsctParent(new Guid("{d309f791-903f-11d0-9efc-00a0c911004f}"), id: 0x016B, priority: 0x0801),
    },
};

Komuta simge ekleme

Komutlar, komut görünen adına ek olarak veya yerine menü öğelerine simge eklemeyi destekler. Komutunuza simge eklemek için komutunun CommandConfigurationüzerinde özelliğini ayarlayınIcon.

CommandIconConfiguration

iki CommandIconConfiguration parametreye sahiptir:

Parametre Türü Zorunlu Açıklama
IconName ImageMoniker Yes Özel görüntü ekleme bölümünden sonra eklediğiniz bir resim için özel bir ad kullanabilir veya aşağıdaki gibi bir Visual Studio ImageMoniker'e başvurabilirsinizImageMonikers.KnownValues.AddItem
Simge Ayarlar Simge Ayarlar Yes Komutun nasıl görüntüleneceğini yapılandırılır. Örneğin IconSettings.IconAndText , simgeyi komutun görünen adının yanında görüntülerken IconSettings.IconOnly , bir araç çubuğunun üst öğesindeyse DisplayName değil yalnızca komutun simgesini gösterir.

ImageMoniker.KnownValues örneği

public override CommandConfiguration CommandConfiguration => new("%MyCommand.DisplayName%")
{
    Icon = new CommandIconConfiguration(ImageMoniker.KnownValues.Extension, IconSettings.IconAndText),
};

Komut simgesi için özel görüntü kullanma

Aşağıdaki adımları izleyerek özel adlarla başvurabileceğiniz özel görüntüler ekleyebilirsiniz:

  1. Görüntü kaynak dosyalarını desene göre yeniden adlandırın %Custom Moniker%.* (örneğin, MyImage.1.png). Aynı takma adla önekli dosyaların tümü, aynı özel takma ad için yedekleme kaynakları olarak kullanılır. İstenen simge boyutuna göre farklı bir kaynak kullanılır.
    • Örneğin, MyImage.16.16.png (16*16 png), MyImage.20.20.png (20*20 png) ve MyImage.xaml için kaynak MyImageolarak kabul edilir.
    • İstenen simge boyutu 16*16 olduğunda MyImage.16.16.png kullanılır, istenen boyut 20*20 olduğunda MyImage.20.20.png kullanılır, diğer tüm durumlarda MyImage.xaml kullanılır.
  2. Tüm görüntü kaynak dosyalarını klasörün altına Images yerleştirin.
    • Varsayılan görüntü varlıkları klasörü şeklindedir Images, ancak bunu ekleyerek de özelleştirebilirsiniz <ImageAssetsPath>%YourFolder%</ImageAssetsPath>

ImageMoniker.Custom örneği

public override CommandConfiguration CommandConfiguration => new("%MyCommand.DisplayName%")
{
    Icon = new CommandIconConfiguration(ImageMoniker.Custom("MyImage"), IconSettings.IconAndText),
};

Kısayollar

Komutlar, belirli bir tuş bileşimi kullanıldığında yürütülecek şekilde yapılandırılabilir. Kısayol bir veya iki akordan oluşur; burada her akor bir ModifierKey ve bir Keyakordan oluşur. için ModifierKey olası değerler, yalnızca kısayolun ikinci akorunda kullanıldığında geçerli olan , ControlShiftShiftControl, ControlShiftLeftAltve NoneNonedeğerleridir.LeftAlt Kısayolda her iki akor için de aynı ModifierKey özelliğin kullanılması gerekmez. Bir Key akorda kullanılan neredeyse diğer tüm klavye tuşları olabilir.

Visual Studio'da birçok klavye kısayolu zaten kullanılıyor. Yinelenen bağlamaları algılamak zor olduğundan ve öngörülemeyen sonuçlara da neden olabileceğinden, aynı kısayolu birden fazla komuta atamamalısınız. Bu nedenle, bir kısayolu atamadan önce kullanılabilirliğini doğrulamak iyi bir fikirdir.

Kısayol etkinleştirme kısıtlaması

Kısayolu farklı bağlamlarda kullanılabilir hale getirmek için yapılandırmaya bir etkinleştirme kısıtlaması eklenebilir. Bu etkinleştirme kısıtlamaları biçiminde Guidtanımlanır ve genellikle bir düzenleyiciyle ilgilidir. Bir kısayola etkinleştirme kısıtlaması verildiğinde, yalnızca bu bağlamda kullanılabilir. Örneğin, kısayolu Visual Studio düzenleyicisinde Guid kullanılabilir hale getirmek için "{5EFC7975-14BC-11CF-9B2B-00AA00573819}" kullanın. Bu durumda, kısayol yalnızca Visual Studio düzenleyicisi odaklandığında kullanılabilir.

Kısayol örneği

public override CommandConfiguration CommandConfiguration => new("%MyCommand.DisplayName%")
{
    Shortcuts = new CommandShortcutConfiguration[]
    {
        new(ModifierKey.LeftAlt, Key.M),
        new(ModifierKey.ControlShift, Key.Y, ModifierKey.ControlShift, Key.B),
    },
};

Komut yapılandırma

Görünürlüğü ve komutun etkin/devre dışı durumunu yapılandırabilir ve bayrakları kullanarak ek meta veriler ayarlayabilirsiniz.

Görünürlük

Komutun görünürlüğü, komutunun CommandConfigurationüzerinde özelliği ayarlanarak VisibleWhen denetlenebilir.

özniteliği, koşulu ve tüm mantığını ve girişlerini birlikte belirten bir dizi bağımsız parametre aracılığıyla bir koşul belirtmeyi destekler. Koşulu belirtmek için, bir parametrede bir ifade belirtirsiniz, başka bir parametredeki ifadede kullanılan bir terim kümesi (dizeler) tanımlarsınız ve üçüncü parametrede değerlendirme sonrasında bu terimlerin hangi değerlerle değiştirilmesi gerekir? İfade, terim ve değerlerin birleşimi kural tabanlı etkinleştirme kısıtlaması olarak adlandırılır ve Kural tabanlı etkinleştirme kısıtlamaları bölümünde tam olarak açıklanmıştır.

Bu özellik yapılandırmanızdan atlanırsa, varsayılan değer komutun her zaman görünür olmasıdır.

Görünürlük örneği

public override CommandConfiguration CommandConfiguration => new("My command")
{
    VisibleWhen = ActivationConstraint.ClientContext(ClientContextKey.Shell.ActiveSelectionFileName, @"\.(jpg|jpeg|txt)$"),
};

Etkin/devre dışı durumu

Bir komutun etkin/devre dışı durumu, komutunun CommandConfigurationüzerinde özelliği ayarlanarak EnabledWhen denetlenebilir.

Bu yapılandırma türü kural tabanlı etkinleştirme kısıtlaması olarak adlandırılır ve Kural tabanlı etkinleştirme kısıtlamalarını kullanma bölümünde tam olarak açıklanmıştır.

Bu yapılandırma komutunuzdan atlanırsa, varsayılan değer komutun her zaman etkinleştirilmesi içindir. Komut sınıfınızın oluşturucusunda ayar this.DisableDuringExecution = true; yaparak şu anda yürütülüyorsa, komutunuz otomatik olarak devre dışı bırakılabilir. Bu özelliğin ayarlanması, komut yürütülürken yapılandırma tarafından EnabledWhen tanımlanan etkin/devre dışı durumunu geçersiz kılar.

Etkin/devre dışı durum örneği

public override CommandConfiguration CommandConfiguration => new("My command")
{
    EnabledWhen = ActivationConstraint.ClientContext(ClientContextKey.Shell.ActiveSelectionFileName, @"\.(jpg|jpeg|txt)$"),
};

Geçerli terim değerleri hakkında daha fazla bilgi için bkz . Kural tabanlı etkinleştirme kısıtlamaları.

Komut bayrakları

Komut bayrakları, komutlarınızın çalışma zamanında komutunun sahip olabileceği özel davranışları tanımlamak için kullanılan ek özellikleri tanımlamaya yardımcı olur. Şu anda desteklenen bayraklar şunlardır:

  • CanToggle - Ekran okuyucuların komutu düzgün bir şekilde duyurabilmesi için komutun özelliğinin değişebileceğini gösterir IsChecked . İşlevsel olarak, otomasyon özelliğinin IsTogglePatternAvailable UI öğesi için true döndürmesini sağlar.
  • CanSelect - Ekran okuyucuların komutu düzgün bir şekilde duyurabilmesi için komutun özelliğinin değişebileceğini gösterir IsChecked . İşlevsel olarak, otomasyon özelliğinin IsSelectionPatternAvailable UI öğesi için true döndürmesini sağlar.

Komutun görünen adını değiştirme

Bir komutun görünen adı başlangıçta içinde ayarlanmış olsa da CommandConfiguration (bkz . Komut Oluşturma), komutunuzda özelliği ayarlanarak DisplayName çalışma zamanında değiştirilebilir. ToolTipText Özelliği benzer şekilde güncelleştirilebilir.

DisplayName örneğini değiştirme

[VisualStudioContribution]
public class MyCommand : Command
{
    /// <inheritdoc />
    public override CommandConfiguration CommandConfiguration => new("Initial Display Name");

    public MyCommand(VisualStudioExtensibility extensibility)
     : base(extensibility)
    {
    }

    public override Task ExecuteCommandAsync(IClientContext context, CancellationToken cancellationToken)
    {
        // Update the command's Display Name
        this.DisplayName = "Updated Display Name";
        return Task.CompletedTask;
    }
}

Sonraki adımlar