Meilleures pratiques pour implémenter un plug-in de contrôle de code sourceBest practices for implementing a source control plug-in

Les détails techniques suivantes peuvent vous aider à implémenter de manière fiable un plug-in de contrôle de code source Visual StudioVisual Studio.The following technical details can help you reliably implement a source control plug-in in Visual StudioVisual Studio.

Problèmes de gestion de mémoireMemory management issues

Dans la plupart des cas, l’environnement de développement intégré (IDE), qui est l’appelant, libère et alloue de la mémoire.In most cases, the integrated development environment (IDE), which is the caller, releases and allocates memory. Le plug-in de contrôle de code source retourne des chaînes et autres éléments dans les mémoires tampons allouées par l’appelant.The source control plug-in returns strings and other items in caller-allocated buffers. Exceptions sont notées dans les descriptions des fonctions spécifiques où elles se produisent.Exceptions are noted in descriptions of specific functions where they occur.

Tableaux de noms de fichiersArrays of file names

Lorsqu’un tableau de fichiers est passé, n’est pas passé en tant que tableau contigu de noms de fichiers.When an array of files is passed, it is not passed as a contiguous array of file names. Il est transmis en tant que tableau de pointeurs aux noms de fichiers.It is passed as an array of pointers to file names. Par exemple, dans le SccGet, les noms de fichiers sont passés par le lpFileNames paramètre, où lpFileNames est en fait un pointeur vers un char **.For example, in the SccGet, the file names are passed by the lpFileNames parameter, where lpFileNames is actually a pointer to a char **. lpFileNames[0] est un pointeur vers le premier nom lpFileNames[1] est un pointeur vers le nom du deuxième et ainsi de suite.lpFileNames[0] is a pointer to the first name, lpFileNames[1] is a pointer to the second name, and so on.

Modèle de grande tailleLarge model

Tous les pointeurs font 32 bits, même sur les systèmes d’exploitation 16 bits.All pointers are 32 bits, even on 16-bit operating systems.

Chemins qualifiés completsFully qualified paths

Où les noms de fichiers ou répertoires sont spécifiés en tant qu’arguments, ils doivent être des chemins qualifiés complets ou des chemins d’accès UNC, sans la barre oblique inverse de fin.Where file names or directories are specified as arguments, they must be fully qualified paths or UNC paths, without the ending backslashes. Il est la responsabilité du contrôle de source de plug-in pour traduire ces chemins d’accès relatif si qui est une spécification pour le système de contrôle source sous-jacent.It is the responsibility of the source control plug-in to translate these to relative paths if that is a requirement of the underlying source control system.

Spécifiez un chemin d’accès qualifié complet pour la DLL enregistréeSpecify a fully qualified path for the registered DLL

L’IDE ne charge plus DLL à partir de chemins d’accès relatifs (par exemple, .\NewProvider.dll).The IDE no longer loads DLLs from relative paths (for example, .\NewProvider.dll). Un chemin d’accès complet de la DLL doit être spécifié (par exemple, C:\Providers\NewProvider.dll).A full path of the DLL must be specified (for example, C:\Providers\NewProvider.dll). Cela renforce la sécurité de l’IDE en empêchant le chargement des DLL du contrôle de source non autorisés ou avec emprunt d’identité.This requirement strengthens the security of the IDE by preventing the loading of unauthorized or impersonated source control DLLs.

Recherchez un plug-in de VSSCI existant lorsque vous installez votre plug-in de contrôle de code sourceCheck for an existing VSSCI plug-in when you install your source control plug-in

Un utilisateur qui a l’intention d’installer votre plug-in de contrôle de code source peut-être déjà un source contrôle existant plug-in installé sur l’ordinateur.A user who plans to install your source control plug-in may already have an existing source control plug-in installed on the computer. Le programme d’installation (programme d’installation) pour le plug-in que vous créez doit déterminer s’il existe des valeurs existantes pour les clés de Registre appropriées.The installation (setup) program for the plug-in that you create should determine whether there are existing values for the relevant registry keys. Si ces clés sont déjà définies, le programme d’installation doit demander l’utilisateur à inscrire votre plug-in en tant que le plug-in de contrôle de code source par défaut et remplacer celle qui est déjà installé.If these keys are already set, your installation program should ask the user whether to register your plug-in as the default source control plug-in and replace the one that is already installed.

Codes de résultat d’erreur et la création de rapportsError result codes and reporting

Le SCC_OK renvoyer le code d’une fonction de contrôle de source indique que l’opération a réussi pour tous les fichiers.The SCC_OK return code for a source control function indicates that the operation has succeeded for all files. Si l’opération échoue, il est prévu pour retourner le dernier code d’erreur rencontré.If the operation fails, it is expected to return the last error code encountered.

La règle de création de rapports est que si une erreur se produit dans l’IDE, l’IDE est responsable de la signaler.The rule for reporting is that if an error occurs in the IDE, the IDE is responsible for reporting it. Si une erreur se produit dans le système de contrôle source, le plug-in de contrôle de code source est responsable de la signaler.If an error occurs in the source control system, the source control plug-in is responsible for reporting it. Par exemple, aucun fichier actuellement sélectionné serait signalé par l’IDE, tandis que ce fichier est déjà extrait serait signalé par le plug-in.For instance, No files are currently selected would be reported by the IDE, whereas This file is already checked out would be reported by the plug-in.

La structure de contexteThe context structure

Pendant l’appel à la SccInitialize, l’appelant passe le ppvContext paramètre, qui est un handle non initialisé à une valeur void.During the call to the SccInitialize, the caller passes the ppvContext parameter, which is an uninitialized handle to a void. Le plug-in de contrôle de code source peut ignorer ce paramètre, ou elle peut allouer une structure quelconque et placer un pointeur à cette structure dans le pointeur passé.The source control plug-in can ignore this parameter or it can allocate a structure of any kind and put a pointer to that structure into the passed pointer. L’IDE ne comprend pas cette structure, mais il passe un pointeur vers cette structure dans chaque autre appel dans le plug-in.The IDE does not understand this structure, but it passes a pointer to this structure into every other call in the plug-in. Cela fournit des informations de cache d’un contexte précieux pour le plug-in qu’il peut utiliser pour gérer les informations d’état global qui persiste lors des appels de fonction sans utiliser de variables globales.This provides valuable context cache information to the plug-in that it can use to maintain global state information that persists across function calls without using global variables. Le plug-in est chargé de libérer la structure dans un appel à la SccUninitialize.The plug-in is responsible for freeing the structure on a call to the SccUninitialize.

Si les jeux de plug-in le SCC_CAP_REENTRANT bit dans le SccInitialize (en particulier, dans le lpSccCaps paramètre), plusieurs structures de contexte sont utilisées pour effectuer le suivi de tous les projets qui sont ouverts.If the plug-in sets the SCC_CAP_REENTRANT bit in the SccInitialize (specifically, in the lpSccCaps parameter), multiple context structures are used to track all the projects that are open.

Indicateurs de bits et d’autres options de commandeBitflags and other command options

Pour chaque commande, telles que la SccGet, l’IDE peut spécifier de nombreuses options qui modifient le comportement de la commande.For each command, such as the SccGet, the IDE can specify many options that change the behavior of the command.

L’API prend en charge le paramètre de certaines options par l’IDE via le fOptions paramètre.The API supports the setting of certain options by the IDE through the fOptions parameter. Ces options sont décrites dans indicateurs de bits utilisés par des commandes spécifiques ainsi que les commandes qu’elles affectent.These options are described in Bitflags used by specific commands together with the commands that they affect. En règle générale, il s’agit d’options pour lequel l’utilisateur ne doit pas être invité.In general, these are options for which the user would not be prompted.

Plus les options de paramètre configurable par l’utilisateur ne sont pas définies de cette manière, car ils peuvent varier entre les plug-ins de contrôle de code source. Par conséquent, le mécanisme recommandé est un avancé bouton.Most user-configurable setting options are not defined in this manner, because they vary widely among source control plug-ins. Therefore, the recommended mechanism is an Advanced button. Par exemple, dans le obtenir boîte de dialogue, l’IDE affiche uniquement les informations qu’il comprend, mais elle affiche également une avancé bouton si le plug-in a des options de cette commande.For instance, in the Get dialog box, the IDE displays only information that it understands, but it also displays an Advanced button if the plug-in has options for this command. Lorsque l’utilisateur clique sur le avancé bouton, les appels de l’IDE le SccGetCommandOptions pour activer le plug-in pour inviter l’utilisateur pour plus d’informations, telles que les indicateurs de bits ou une date/heure de contrôle de code source.When the user clicks the Advanced button, the IDE calls the SccGetCommandOptions to enable the source control plug-in to prompt the user for information, such as bitflags or a date/time. Le plug-in retourne cette information dans une structure qui est retournée pendant la SccGet commande.The plug-in returns this information in a structure that is passed back during the SccGet command.

Voir aussiSee also

Plug-ins de contrôle de code source Source control plug-ins
Créer un contrôle de source de plug-inCreate a source control plug-in