Použití kontextu uživatelského rozhraní založeného na pravidlech pro rozšíření sady Visual Studio

Článek
10/10/2023

Visual Studio umožňuje načítání balíčků VSPackage při aktivaci určitých známých UIContextbalíčků. Tyto kontexty uživatelského rozhraní ale nejsou jemně odstupňované, což autorům rozšíření nezvolí, ale vybere dostupný kontext uživatelského rozhraní, který se aktivuje před bodem, ve kterém skutečně chtěli balíček VSPackage načíst. Seznam známých kontextů uživatelského rozhraní najdete v tématu KnownUIContexts.

Načítání balíčků může mít dopad na výkon a jejich načítání dříve, než je potřeba, není osvědčeným postupem. Visual Studio 2015 představilo koncept kontextů uživatelského rozhraní založených na pravidlech, což je mechanismus, který autorům rozšíření umožňuje definovat přesné podmínky, za kterých je kontext uživatelského rozhraní aktivován a přidružené balíčky VSPackage se načítají.

Kontext uživatelského rozhraní založeného na pravidlech

Pravidlo se skládá z nového kontextu uživatelského rozhraní (GUID) a logického výrazu, který odkazuje na jeden nebo více termínů v kombinaci s logickými operacemi "and", "or", "not". Výrazy se vyhodnocují dynamicky v době běhu a výraz se znovu vyhodnotí, kdykoli se některý z jeho termínů změní. Když se výraz vyhodnotí jako true, aktivuje se přidružený kontext uživatelského rozhraní. Jinak se kontext uživatelského rozhraní deaktivuje.

Kontext uživatelského rozhraní založeného na pravidlech lze použít různými způsoby:

Zadejte omezení viditelnosti pro příkazy a okna nástrojů. Příkazy nebo nástroje můžete skrýt, dokud nebude splněno pravidlo kontextu uživatelského rozhraní.
Jako omezení automatického načítání: balíčky automatického načítání se načítají jenom v případech, kdy je pravidlo splněno.
Zpožděný úkol: Zpoždění načítání do uplynutí zadaného intervalu a splnění pravidla.

Mechanismus může používat jakékoli rozšíření sady Visual Studio.

Vytvoření kontextu uživatelského rozhraní založeného na pravidlech

Předpokládejme, že máte rozšíření s názvem TestPackage, které nabízí příkaz nabídky, který se vztahuje pouze na soubory s příponou .config . Před VS2015 byla nejlepší možností načíst TestPackage při SolutionExistsAndFullyLoadedContext aktivaci kontextu uživatelského rozhraní. Načtení testovacího balíčku tímto způsobem není efektivní, protože načtené řešení nemusí ani obsahovat soubor .config . Tyto kroky ukazují, jak lze kontext uživatelského rozhraní založený na pravidlech použít k aktivaci kontextu uživatelského rozhraní pouze v případě, že je vybrán soubor s příponou .config , a načtení TestPackage při aktivaci kontextu uživatelského rozhraní.

Definujte nový identifikátor GUID UIContext a přidejte ho do třídy ProvideAutoLoadAttribute VSPackage a ProvideUIContextRuleAttribute.

Předpokládejme například, že se přidá nový UIContext UIContextGuid. Vytvořený identifikátor GUID (můžete vytvořit identifikátor GUID kliknutím na Příkazy>Vytvořit GUID) je "8B40D5E2-5626-42AE-99EF-3DD1EFF46E7B". Pak do třídy balíčku přidáte následující deklaraci:
```
public const string UIContextGuid = "8B40D5E2-5626-42AE-99EF-3DD1EFF46E7B";
```
Pro atributy přidejte následující hodnoty: (Podrobnosti o těchto atributech budou vysvětleny později)
```
[ProvideAutoLoad(TestPackage.UIContextGuid)]
[ProvideUIContextRule(TestPackage.UIContextGuid,
    name: "Test auto load",
    expression: "DotConfig",
    termNames: new[] { "DotConfig" },
    termValues: new[] { "HierSingleSelectionName:.config$" })]
```
Tato metadata definují nový identifikátor GUID UIContext (8B40D5E2-5626-42AE-99EF-3DD1EFF46E7B) a výraz odkazující na jeden termín DotConfig. Termín DotConfig se vyhodnotí jako true, kdykoli má aktuální výběr v aktivní hierarchii název, který odpovídá vzoru regulárního výrazu \.config$ (končí na .config). Hodnota (Výchozí) definuje volitelný název pravidla, které je užitečné pro ladění.

Hodnoty atributu se přidají do pkgdef vygenerované během doby sestavení poté.
V souboru VSCT pro příkazy TestPackage přidejte do příslušných příkazů příznak DynamicVisibility:
```
<CommandFlag>DynamicVisibility</CommandFlag>
```

V části Viditelnost Omezení VSCT propojte příslušné příkazy s novým identifikátorem GUID UIContext definovaným v souboru #1:

<VisibilityConstraints>
    <VisibilityItem guid="guidTestPackageCmdSet" id="TestId"  context="UIContextGuid"/>
</VisibilityConstraints>

V části Symboly přidejte definici UIContext:
```
<GuidSymbol name="UIContextGuid" value="{8B40D5E2-5626-42AE-99EF-3DD1EFF46E7B}" />
```
Příkazy místní nabídky pro soubory *.config budou nyní viditelné pouze v případě, že vybraná položka v Průzkumníku řešení je soubor .config a balíček se nenačte, dokud nebude vybrán jeden z těchto příkazů.

V dalším kroku pomocí ladicího programu ověřte, že se balíček načte pouze v případě, že ho očekáváte. Ladění testovacího balíčku:
Nastavte zarážku v Initialize metodě.
Sestavte TestPackage a spusťte ladění.
Vytvořte projekt nebo ho otevřete.
Vyberte libovolný soubor s jinou příponou než .config. Zarážka by neměla být nalezena.
Vyberte soubor App.Config.

TestPackage se načte a zastaví na zarážce.

Přidání dalších pravidel pro kontext uživatelského rozhraní

Vzhledem k tomu, že pravidla kontextu uživatelského rozhraní jsou logické výrazy, můžete přidat další omezená pravidla pro kontext uživatelského rozhraní. Například ve výše uvedeném kontextu uživatelského rozhraní můžete určit, že pravidlo platí pouze v případě, že se načte řešení s projektem. Příkazy se tak nezobrazí, pokud otevřete soubor .config jako samostatný soubor, ne jako součást projektu.

[ProvideAutoLoad(TestPackage.UIContextGuid)]
[ProvideUIContextRule(TestPackage.UIContextGuid,
    name: "Test auto load",
    expression: "(SingleProject | MultipleProjects) & DotConfig",
    termNames: new[] { "SingleProject", "MultipleProjects","DotConfig" },
    termValues: new[] { VSConstants.UICONTEXT.SolutionHasSingleProject_string , VSConstants.UICONTEXT.SolutionHasMultipleProjects_string , "HierSingleSelectionName:.config$" })]

Výraz teď odkazuje na tři termíny. První dva termíny, SingleProject a MultipleProjects, odkazují na další dobře známé kontexty uživatelského rozhraní (pomocí jejich identifikátorů GUID). Třetím termínem "DotConfig" je kontext uživatelského rozhraní založený na pravidlech definovaný dříve v tomto článku.

Zpožděná aktivace

Pravidla můžou mít volitelnou prodlevu. Zpoždění se zadává v milisekundách. Pokud je k dispozici, zpoždění způsobí, že aktivace nebo deaktivace kontextu uživatelského rozhraní pravidla se v daném časovém intervalu zpozdí. Pokud se pravidlo změní zpět před intervalem zpoždění, nic se nestane. Tento mechanismus lze použít k "rozkročení" inicializačních kroků – zejména jednorázové inicializace, aniž byste museli spoléhat na časovače nebo registrovat nečinná oznámení.

Můžete například zadat pravidlo testovacího zatížení, které bude mít zpoždění 100 milisekund:

[ProvideAutoLoad(TestPackage.UIContextGuid)]
[ProvideUIContextRule(TestPackage.UIContextGuid,
    name: "Test auto load",
    expression: "DotConfig",
    termNames: new[] { "DotConfig" },
    termValues: new[] { "HierSingleSelectionName:.config$" },
    delay: 100)]

Typy termínů

Tady jsou různé typy podporovaných termínů:

Období	Popis
{nnnnnnnn-nnnn-nnnn-nnnnnn}	Identifikátor GUID odkazuje na kontext uživatelského rozhraní. Termín bude pravdivý vždy, když je kontext uživatelského rozhraní aktivní a jinak nepravda.
HierSingleSelectionName:<pattern>	Termín bude pravdivý vždy, když je výběr v aktivní hierarchii jedinou položkou a název vybrané položky odpovídá regulárnímu výrazu .NET zadanému "vzorem".
User Nastavení StoreQuery:<query>	Dotaz představuje úplnou cestu k úložišti uživatelských nastavení, která se musí vyhodnotit na nenulovou hodnotu. Dotaz se rozdělí na "kolekci" a "propertyName" na poslední lomítko.
Konfigurace Nastavení StoreQuery:<query>	Dotaz představuje úplnou cestu k úložišti nastavení konfigurace, která se musí vyhodnotit na nenulovou hodnotu. Dotaz se rozdělí na "kolekci" a "propertyName" na poslední lomítko.
ActiveProjectFlavor:<projectTypeGuid>	Termín bude pravdivý vždy, když je aktuálně vybraný projekt příchuť (agregovaný) a má příchuť odpovídající identifikátoru GUID daného typu projektu.
ActiveEditorContentType:<contentType>	Termín bude pravdivý, pokud je vybraný dokument textovým editorem s daným typem obsahu. Poznámka: Při přejmenování vybraného dokumentu se tento termín neaktualizuje, dokud se soubor nezavře a znovu neotevře.
ActiveProjectCapability:<Expression>	Termín je pravdivý, pokud aktivní možnosti projektu odpovídají zadanému výrazu. Výraz může být něco jako VB \| Csharp.
SolutionHasProjectCapability:<Expression>	Podobně jako u výše uvedených termínů platí, pokud má řešení načtený projekt, který odpovídá výrazu.
SolutionHasProjectFlavor:<projectTypeGuid>	Termín bude pravdivý vždy, když má řešení projekt, který je ochucený (agregovaný) a má příchuť odpovídající identifikátoru GUID daného typu projektu.
ProjectAddedItem:<pattern>	Termín je pravdivý, pokud se do projektu, který je otevřený, přidá soubor odpovídající vzoru.
ActiveProjectOutputType:<outputType>	Termín je pravdivý, pokud typ výstupu aktivního projektu přesně odpovídá. OutputType může být celé číslo nebo __VSPROJOUTPUTTYPE typ.
ActiveProjectBuildProperty:<buildProperty>=<regex>	Termín je pravdivý, pokud má aktivní projekt zadanou vlastnost sestavení a hodnotu vlastnosti odpovídá zadanému filtru regulárních výrazů. Další podrobnosti o vlastnostech sestavení najdete v tématu Zachování dat v souborech projektu MSBuild.
SolutionHasProjectBuildProperty:<buildProperty>=<regex>	Termín je pravdivý, pokud má řešení načtený projekt se zadanou vlastností sestavení a hodnotou vlastnosti odpovídá zadanému filtru regulárních výrazů.

Kompatibilita s rozšířením mezi verzemi

Kontexty uživatelského rozhraní založené na pravidlech jsou novou funkcí v sadě Visual Studio 2015 a nebudou přeneseny do dřívějších verzí. Při přenosu do dřívějších verzí dochází k potížím s rozšířeními nebo balíčky, které cílí na více verzí sady Visual Studio. Tyto verze by se musely automaticky načíst v sadě Visual Studio 2013 a starších verzích, ale můžou využívat kontexty uživatelského rozhraní založené na pravidlech, aby se zabránilo automatickému načtení v sadě Visual Studio 2015.

Aby bylo možné tyto balíčky podporovat, mohou položky AutoLoadPackages v registru nyní v poli s hodnotou poskytnout příznak, který označuje, že položka by se měla přeskočit v sadě Visual Studio 2015 a vyšší. To lze provést přidáním příznaku do PackageAutoLoadFlags. VSPackages teď můžou do atributu ProvideAutoLoadAttribute přidat možnost SkipWhenUIContextRulesActive, která označuje, že položka by se měla v sadě Visual Studio 2015 a novější ignorovat.

Pravidla kontextu rozšiřitelného uživatelského rozhraní

Balíčky někdy nemůžou používat statická pravidla kontextu uživatelského rozhraní. Předpokládejme například, že máte balíček podporující rozšiřitelnost tak, aby stav příkazu byl založen na typech editoru podporovaných importovanými poskytovateli MEF. Příkaz je povolený, pokud existuje rozšíření podporující aktuální typ úprav. V takových případech samotný balíček nemůže použít statické pravidlo kontextu uživatelského rozhraní, protože termíny by se změnily v závislosti na tom, které rozšíření MEF jsou k dispozici.

Aby bylo možné tyto balíčky podporovat, kontexty uživatelského rozhraní založené na pravidlech podporují pevně zakódovaný výraz "*", který označuje všechny termíny, které jsou pod ním, budou připojeny k or. Díky tomu může hlavní balíček definovat známý kontext uživatelského rozhraní založený na pravidlech a svázat jeho stav příkazu s tímto kontextem. Následně může jakékoli rozšíření MEF cílené na hlavní balíček přidat jeho termíny pro editory, které podporuje, aniž by to mělo vliv na jiné termíny nebo hlavní výraz.

Dokumentace ke konstruktoru ProvideExtensibleUIContextRuleAttribute ukazuje syntaxi pro rozšiřitelná pravidla kontextu uživatelského rozhraní.

Sdílet prostřednictvím