Criar arquivos de tabela de comando XML (.vsct)

Um arquivo de tabela de comandoS XML (.vsct) descreve o layout e a aparência dos itens de comando para um VSPackage. Os itens de comando incluem botões, caixas de combinação, menus, barras de ferramentas e grupos de itens de comando. Este artigo descreve arquivos de tabela de comando XML, como eles afetam itens de comando e menus e como criá-los.

Comandos, menus, grupos e o arquivo .vsct

Os arquivos .vsct são organizados em torno de comandos, menus e grupos de comandos. As marcas XML no arquivo .vsct representam cada um desses itens, juntamente com outros itens associados, como botões de comando, posicionamento de comando e bitmaps.

Quando você cria um novo VSPackage executando o modelo de pacote do Visual Studio, o modelo gera um arquivo .vsct com os elementos necessários para um comando de menu, janela de ferramenta ou editor personalizado, dependendo de suas seleções. Esse arquivo .vsct pode ser modificado para atender aos requisitos de um VSPackage específico. Para obter exemplos de como modificar um arquivo .vsct , consulte Estender menus e comandos.

Para criar um novo arquivo .vsct em branco, consulte Como criar um arquivo .vsct. Depois de criado, você adiciona elementos XML, atributos e valores ao arquivo para descrever o layout do item de comando. Para obter um esquema XML detalhado, consulte a referência de esquema XML do VSCT.

Diferenças entre arquivos .ctc e .vsct

Embora o significado por trás das marcas XML em um arquivo .vsct seja o mesmo que essas marcas no formato de arquivo .ctc preterido, sua implementação é um pouco diferente:

• A nova <marca extern> é onde você faz referência a outros arquivos .h a serem compilados, como esses arquivos para a barra de ferramentas do Visual Studio.

• Embora os arquivos .vsct ofereçam suporte à instrução /include , como fazem os arquivos .ctc , ele também apresenta um novo <elemento de importação> . A diferença é que /include traz todas as informações, enquanto <a importação> traz apenas os nomes.

• Embora os arquivos .ctc exijam um arquivo de cabeçalho no qual você define suas diretivas de pré-processador, um não é necessário para arquivos .vsct . Em vez disso, coloque suas diretivas na tabela de símbolos, localizada nos elementos <Símbolo>, localizada na parte inferior do arquivo .vsct.

• Os arquivos .vsct apresentam uma <marca de anotação> , que permite inserir qualquer informação desejada, como anotações ou até mesmo imagens.

• Os valores são armazenados como atributos no item.

• Os sinalizadores de comando podem ser armazenados individualmente ou empilhados. O IntelliSense, no entanto, não funciona em sinalizadores de comando empilhados. Para obter mais informações sobre sinalizadores de comando, consulte o elemento CommandFlag.

• Você pode especificar vários tipos, como listas suspensas divididas, combinações etc.

• Os GUIDs não são validados.

• Cada elemento de interface do usuário tem uma cadeia de caracteres que representa o texto exibido com ele.

• O pai é opcional. Se omitido, o valor Grupo Desconhecido será usado.

• O argumento Ícone é opcional.

• Seção Bitmap: esta seção é a mesma de um arquivo .ctc , exceto que agora você pode especificar um nome de arquivo por meio do Href que será extraído pelo compilador vsct.exe no momento da compilação.

• ResID: o ID antigo de recurso bitmap pode ser usado e ainda funciona da mesma forma que nos arquivos .ctc.

• HRef: um novo método que permite especificar um nome de arquivo para o recurso de bitmap. Ele pressupõe que todos sejam usados, assim você pode omitir a seção Usados. O compilador primeiro procurará recursos locais para o arquivo, em seguida, em quaisquer compartilhamentos líquidos e quaisquer recursos definidos pela opção /I .

• Associação de chaves: você não precisa mais especificar um emulador. Se você especificar um, o compilador assumirá que o editor e o emulador são os mesmos.

• Keychord: Keychord foi descartado. O novo formato é Key1, Mod1, Key2, Mod2. Você pode especificar um caractere, um valor hexadecimal ou uma constante VK.

O novo compilador, vsct.exe, compila arquivos .ctc e .vsct . No entanto, o compilador dectc.exe antigo não reconhecerá nem compilará arquivos .vsct .

Você pode usar o compilador vsct.exe para converter um arquivo .cto existente em um arquivo .vsct . Para obter mais informações, consulte Como criar um arquivo .vsct de um arquivo .cto existente.

Os elementos de arquivo .vsct

A tabela de comandos tem a seguinte hierarquia e elementos:

• Elemento CommandTable: representa todos os comandos, grupos de menus e menus associados ao VSPackage.

• Elemento Extern: faz referência a todos os arquivos .h externos que você deseja mesclar com o arquivo .vsct .

• Elemento Include: faz referência a arquivos de cabeçalho adicionais (.h) que você deseja compilar junto com o arquivo .vsct. Um arquivo .vsct pode incluir arquivos .h que contêm constantes que definem comandos, grupos de menus e menus que o IDE ou outro VSPackage fornece.

• Elemento de Comandos: representa todos os comandos individuais que podem ser executados. Cada comando tem os seguintes quatro elementos filho:

• Elemento Menus: representa todos os menus e barras de ferramentas no VSPackage. Os menus são contêineres para grupos de comandos.

• Elemento Groups: representa todos os grupos no VSPackage. Os grupos são coleções de comandos individuais.

• Elemento Buttons: representa todos os botões de comando e itens de menu no VSPackage. Botões são controles visuais que podem ser associados a comandos.

• Elemento Bitmaps: representa todos os bitmaps para todos os botões no VSPackage. Bitmaps são imagens que são exibidas ao lado ou nos botões de comando, dependendo do contexto.

• Elemento CommandPlacements: indica locais adicionais em que os comandos individuais devem ser colocados nos menus do VSPackage.

• Elemento VisibilityConstraints: especifica se um comando é exibido o tempo todo ou apenas em determinados contextos, como quando uma caixa de diálogo ou janela específica é exibida. Menus e comandos que têm um valor para esse elemento serão exibidos somente quando o contexto especificado estiver ativo. O comportamento padrão é exibir o comando o tempo todo.

• Elemento KeyBindings: especifica todas as associações de chave para os comandos. Ou seja, uma ou mais combinações de teclas que devem ser pressionadas para executar o comando, como Ctrl+S.

• Elemento UsedCommands: informa ao ambiente do Visual Studio que, embora o comando especificado seja implementado por outro código, quando o VSPackage atual está ativo, ele fornece a implementação de comando.

• Elemento Symbols: contém os nomes dos símbolos e as IDs GUID de todos os comandos no seu pacote.

Diretrizes de design de arquivo .vsct

Para criar com êxito um arquivo .vsct , siga estas diretrizes.

• Os comandos só podem ser colocados em grupos, os grupos só podem ser colocados em menus e os menus só podem ser colocados em grupos. Somente os menus são realmente exibidos no IDE, grupos e comandos não são.

• O submenu não pode ser atribuído diretamente a um menu, mas deve ser atribuído a um grupo, que, por sua vez, é atribuído a um menu.

• Comandos, submenus e grupos podem ser atribuídos a um grupo ou menu pai usando o campo pai de sua diretiva de definição.

• Organizar uma tabela de comandos somente por meio dos campos pai nas diretivas tem uma limitação significativa. As diretivas que definem objetos podem aceitar apenas um argumento pai.

• Reutilização de comandos, grupos ou submenus requer o uso de uma nova diretiva para criar uma nova instância do objeto com seu próprio GUID:ID par.

• Cada GUID:ID par deve ser exclusivo. A reutilização de um comando que, por exemplo, foi colocada em um menu, uma barra de ferramentas ou em um menu de contexto, é tratada pela IOleCommandTarget interface.

• Comandos e submenus também podem ser atribuídos a vários grupos, e os grupos podem ser atribuídos a vários menus usando o elemento Commands.

Notas de arquivo .vsct

Se você fizer alterações em um arquivo .vsct depois de compilá-lo e colocá-lo em uma DLL satélite nativa, deverá executar devenv.exe /setup /nosetupvstemplates. Isso força os recursos do VSPackage especificados no registro experimental a serem relidos e o banco de dados interno que descreve o Visual Studio seja recriado.

Durante o desenvolvimento, é possível que vários projetos DO VSPackage sejam criados e registrados no hive do registro experimental, o que pode levar a confusão no IDE. Para corrigir isso, você pode redefinir o hive experimental para as configurações padrão para remover todos os VSPackages registrados e quaisquer alterações que possam ter feito no IDE. Para redefinir o hive experimental, use a ferramenta CreateExpInstance.exe que vem com o SDK do Visual Studio. Você pode encontrá-lo em:

%PROGRAMFILES(x86)%\Visual Studio\<version> SDK\VisualStudioIntegration\Tools\Bin\CreateExpInstance.exe

Execute a ferramenta usando o comando CreateExpInstance /Reset. Lembre-se de que essa ferramenta remove do hive experimental todos os VSPackages registrados que normalmente não são instalados com o Visual Studio.

Conteúdo relacionado

• Estender menus e comandos