Práticas recomendadas para implementar um plug-in de controle do código-fonte
Os detalhes técnicos a seguir podem ajudá-lo a implementar de forma confiável um plug-in de controle de origem no Visual Studio.
Problemas de gerenciamento de memória
Na maioria dos casos, o ambiente de desenvolvimento integrado (IDE), que é o chamador, libera e aloca memória. O plug-in de controle de origem retorna cadeias de caracteres e outros itens em buffers alocados pelo chamador. Exceções são observadas em descrições de funções específicas onde ocorrem.
Matrizes de nomes de arquivo
Quando uma matriz de arquivos é passada, ela não é passada como uma matriz contígua de nomes de arquivos. Ele é passado como uma matriz de ponteiros para nomes de arquivo. Por exemplo, no SccGet, os nomes de lpFileNames arquivo são passados pelo parâmetro, onde lpFileNames na verdade é um ponteiro para um char **arquivo . lpFileNames[0] é um ponteiro para o primeiro nome, [1] é um ponteiro para o segundo nome, lpFileNamese assim por diante.
Modelo grande
Todos os ponteiros são de 32 bits, mesmo em sistemas operacionais de 16 bits.
Caminhos totalmente qualificados
Onde nomes de arquivo ou diretórios são especificados como argumentos, eles devem ser caminhos totalmente qualificados ou caminhos UNC, sem as barras invertidas finais. É responsabilidade do plug-in de controle do código-fonte traduzi-los em caminhos relativos, se esse for um requisito do sistema de controle do código-fonte subjacente.
Especifique um caminho totalmente qualificado para a DLL registrada
O IDE não carrega mais DLLs de caminhos relativos (por exemplo, .\NewProvider.dll). Um caminho completo da DLL deve ser especificado (por exemplo, C:\Providers\NewProvider.dll). Esse requisito fortalece a segurança do IDE, impedindo o carregamento de DLLs de controle de origem não autorizadas ou representadas.
Verifique se há um plug-in VSSCI existente ao instalar o plug-in de controle do código-fonte
Um usuário que planeja instalar o plug-in de controle do código-fonte pode já ter um plug-in de controle do código-fonte instalado no computador. O programa de instalação (instalação) para o plug-in que você criar deve determinar se há valores existentes para as chaves do Registro relevantes. Se essas chaves já estiverem definidas, o programa de instalação deve perguntar ao usuário se deseja registrar o plug-in como o plug-in de controle de origem padrão e substituir o que já está instalado.
Códigos de resultado de erro e relatórios
O SCC_OK código de retorno para uma função de controle de origem indica que a operação foi bem-sucedida para todos os arquivos. Se a operação falhar, espera-se que retorne o último código de erro encontrado.
A regra para relatar é que, se ocorrer um erro no IDE, o IDE será responsável por relatá-lo. Se ocorrer um erro no sistema de controle do código-fonte, o plug-in de controle do código-fonte será responsável por relatá-lo. Por exemplo, Nenhum arquivo selecionado no momento seria relatado pelo IDE, enquanto que o check-out desse arquivo já seria relatado pelo plug-in.
A estrutura do contexto
Durante a chamada para o SccInitialize, o chamador passa o ppvContext parâmetro, que é um identificador não inicializado para um void. O plug-in de controle do código-fonte pode ignorar esse parâmetro ou pode alocar uma estrutura de qualquer tipo e colocar um ponteiro para essa estrutura no ponteiro passado. O IDE não entende essa estrutura, mas passa um ponteiro para essa estrutura em todas as outras chamadas no plug-in. Isso fornece informações valiosas de cache de contexto para o plug-in que ele pode usar para manter informações de estado global que persistem em chamadas de função sem usar variáveis globais. O plug-in é responsável por liberar a estrutura em uma chamada para o SccUninitialize.
Se o plug-in definir o SCC_CAP_REENTRANT bit no SccInitialize (especificamente, no lpSccCaps parâmetro), várias estruturas de contexto serão usadas para controlar todos os projetos abertos.
Bitflags e outras opções de comando
Para cada comando, como o SccGet, o IDE pode especificar muitas opções que alteram o comportamento do comando.
A API oferece suporte à configuração de determinadas opções pelo IDE por meio do fOptions parâmetro. Essas opções são descritas em Bitflags usados por comandos específicos juntamente com os comandos que eles afetam. Em geral, essas são opções para as quais o usuário não seria solicitado.
A maioria das opções de configuração configuráveis pelo usuário não são definidas dessa maneira, porque variam muito entre os plug-ins de controle do código-fonte. Portanto, o mecanismo recomendado é um botão Avançado . Por exemplo, na caixa de diálogo Obter , o IDE exibe apenas as informações que ele entende, mas também exibe um botão Avançado se o plug-in tiver opções para esse comando. Quando o usuário clica no botão Avançado, o IDE chama o SccGetCommandOptions para habilitar o plug-in de controle do código-fonte para solicitar informações ao usuário, como bitflags ou uma data/hora. O plug-in retorna essas informações em uma estrutura que é passada de volta durante o SccGet comando.