Conventions de génération, de compilation et d’affectation de noms de code dans Microsoft Fakes

Cet article décrit les options et les problèmes liés à la génération et à la compilation du code Fakes, et décrit les conventions d’affectation de noms pour les types, membres et paramètres générés par Fakes.

Exigences

  • Visual Studio Enterprise

  • Un projet .NET Framework

  • .NET Core, .NET 5.0 ou version ultérieure, et le support des projets de style SDK en préversion dans Visual Studio 2019 Mise à jour 6, et activé par défaut dans la Mise à jour 8. Pour plus d’informations, consultez Microsoft Fakes pour les projets de style .NET Core et SDK.

Génération et compilation du code

Configurer la génération de code de stubs

La génération de types stub est configurée dans un fichier XML ayant pour extension .fakes. L’infrastructure Fakes s’intègre dans le processus de génération via des tâches MSBuild personnalisées et détecte ces fichiers au moment de la génération. Le générateur de code Fakes compile les types stub dans un assembly et ajoute la référence au projet.

L’exemple suivant illustre les types stub définis dans FileSystem.dll:

<Fakes xmlns="http://schemas.microsoft.com/fakes/2011/">
    <Assembly Name="FileSystem"/>
</Fakes>

Filtrage de type

Les filtres peuvent être définis dans le fichier .fakes pour restreindre les types à frotter. Vous pouvez ajouter un nombre illimité d’éléments Clear, Add, Remove sous l’élément StubGeneration pour générer la liste des types sélectionnés.

Par exemple, le fichier .fakes suivant génère des stubs pour les types sous les espaces de noms System et System.IO, mais exclut tout type contenant « Handle » dans System :

<Fakes xmlns="http://schemas.microsoft.com/fakes/2011/">
  <Assembly Name="mscorlib" />
  <!-- user code -->
  <StubGeneration>
    <Clear />
    <Add Namespace="System!" />
    <Add Namespace="System.IO!"/>
    <Remove TypeName="Handle" />
  </StubGeneration>
  <!-- /user code -->
</Fakes>

Les chaînes de filtre utilisent une grammaire simple pour définir la façon dont la correspondance doit être effectuée :

  • Les filtres sont insensibles à la casse par défaut et effectuent une correspondance de sous-chaîne.

    el correspond à « hello »

  • L'ajout de ! à la fin du filtre rend le filtre une correspondance exacte et sensible à la casse :

    el! ne correspond pas à « hello »

    hello! correspond à « hello »

  • L’ajout * à la fin du filtre fait correspondre le préfixe de la chaîne :

    el* ne correspond pas à « hello »

    he* correspond à « hello »

  • Plusieurs filtres dans une liste séparée par des points-virgules sont combinés sous forme de disjonction :

    el;wo correspond à « hello » et « world »

Classes concrètes stub et méthodes virtuelles

Par défaut, les types stub sont générés pour toutes les classes non scellées. Il est possible de restreindre les types stub aux classes abstraites via le fichier de configuration .fakes :

<Fakes xmlns="http://schemas.microsoft.com/fakes/2011/">
  <Assembly Name="mscorlib" />
  <!-- user code -->
  <StubGeneration>
    <Types>
      <Clear />
      <Add AbstractClasses="true"/>
    </Types>
  </StubGeneration>
  <!-- /user code -->
</Fakes>

Types internes

Le générateur de code Fakes produit des types shim et stub pour les types visibles dans l'assemblage Fakes généré. Pour rendre les types internes d’un assembly shimmed visibles par Fakes et votre assembly de test, ajoutez InternalsVisibleToAttribute des attributs au code d’assembly shimmed qui donne une visibilité à l’assembly Fakes généré et à l’assembly de test. Voici un exemple :

// FileSystem\AssemblyInfo.cs
[assembly: InternalsVisibleTo("FileSystem.Fakes")]
[assembly: InternalsVisibleTo("FileSystem.Tests")]

Types internes dans des assemblys fortement nommés

Si l’assembly shimmed porte un nom fort et que vous souhaitez accéder aux types internes de l’assemblage :

  • Votre assembly de test et l’assembly Fakes doivent être fortement nommés.

  • Ajoutez les clés publiques des assemblys de test et Fakes aux attributs InternalsVisibleToAttribute dans les assemblys shimmed. Voici à quoi ressembleraient les exemples d’attributs dans le code d'assemblage interposé lorsque l’assemblage interposé porte un nom fort :

    // FileSystem\AssemblyInfo.cs
[assembly: InternalsVisibleTo("FileSystem.Fakes",
    PublicKey=<Fakes_assembly_public_key>)]
[assembly: InternalsVisibleTo("FileSystem.Tests",
    PublicKey=<Test_assembly_public_key>)]

Si l'assembleur instrumenté est fortement nommé, le framework Fakes signe automatiquement l'assembleur Fakes généré. Vous devez signer avec une signature renforcée l'assemblage de test. Consultez assemblages à nom fort.

L’infrastructure Fakes utilise la même clé pour signer tous les assemblys générés. Vous pouvez donc utiliser cet extrait de code comme point de départ pour ajouter l’attribut InternalsVisibleTo pour l’assembly fakes à votre code d’assembly shimmed.

[assembly: InternalsVisibleTo("FileSystem.Fakes, PublicKey=0024000004800000940000000602000000240000525341310004000001000100e92decb949446f688ab9f6973436c535bf50acd1fd580495aae3f875aa4e4f663ca77908c63b7f0996977cb98fcfdb35e05aa2c842002703cad835473caac5ef14107e3a7fae01120a96558785f48319f66daabc862872b2c53f5ac11fa335c0165e202b4c011334c7bc8f4c4e570cf255190f4e3e2cbc9137ca57cb687947bc")]

Vous pouvez spécifier une autre clé publique pour l’assembly Fakes, par exemple une clé que vous avez créée pour l’assembly shimmed, en spécifiant le chemin complet du fichier .snk qui contient la clé de remplacement comme KeyFile valeur d’attribut dans l’élémentFakes\Compilationdu fichier .fakes. Par exemple:

<-- FileSystem.Fakes.fakes -->
<Fakes ...>
  <Compilation KeyFile="full_path_to_the_alternate_snk_file" />
</Fakes>

Vous devez ensuite utiliser la clé publique du fichier .snk alternatif comme deuxième paramètre de l'attribut InternalVisibleTo pour l'assembly Fakes dans le code d'assemblage shimmed :

// FileSystem\AssemblyInfo.cs
[assembly: InternalsVisibleTo("FileSystem.Fakes",
    PublicKey=<Alternate_public_key>)]
[assembly: InternalsVisibleTo("FileSystem.Tests",
    PublicKey=<Test_assembly_public_key>)]

Dans l’exemple ci-dessus, les valeurs Alternate_public_key et Test_assembly_public_key peuvent être identiques.

Optimiser les temps de génération

La compilation des assemblages Fakes peut augmenter considérablement votre temps de compilation. Vous pouvez réduire le temps de génération en créant les assemblies Fakes pour les assemblies système .NET et les assemblies tiers dans un projet centralisé distinct. Étant donné que ces assemblys changent rarement sur votre machine, vous pouvez réutiliser les assemblys Fakes générés dans d’autres projets.

À partir de vos projets de test unitaire, ajoutez une référence aux assemblys Fakes compilés placés sous FakesAssemblies dans le dossier du projet.

  1. Créez une bibliothèque de classes avec la version du runtime .NET correspondant à vos projets de test. Nous allons l’appeler Fakes.Prebuild. Supprimez le fichier class1.cs du projet, non nécessaire.

  2. Ajoutez une référence à tous les assemblys système et tiers dont vous avez besoin pour Fakes.

  3. Ajoutez un fichier .fakes pour chacun des assemblys et build.

  4. À partir de votre projet de test

    • Vérifiez que vous disposez d’une référence à la DLL d'exécution de Fakes :

      %ProgramFiles(x86)%\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\PublicAssemblies\Microsoft.QualityTools.Testing.Fakes.dll

    • Pour chaque assembly pour lequel vous avez créé Fakes, ajoutez une référence au fichier DLL correspondant dans le dossier Fakes.Prebuild\FakesAssemblies de votre projet.

Éviter les conflits de noms d'assemblages

Dans un environnement Team Build, toutes les sorties de build sont fusionnées dans un seul répertoire. Si plusieurs projets utilisent Fakes, il se peut que les assemblies Fakes de différentes versions se remplacent mutuellement. Par exemple, TestProject1 fake mscorlib.dll du .NET Framework 2.0 et TestProject2 fake mscorlib.dll pour le .NET Framework 4 produisent tous les deux un assembly mscorlib.Fakes.dll Fakes.

Pour éviter ce problème, Fakes doit créer automatiquement des noms d’assembly qualifiés de version pour Fakes pour les références qui ne sont pas liées au projet lors de l’ajout d'fichiers .fakes. Un nom d’assembly Fakes qualifié de version incorpore un numéro de version lorsque vous créez le nom de l’assembly Fakes :

Étant donné un assembly MyAssembly et une version 1.2.3.4, le nom de l’assembly Fakes est MyAssembly.1.2.3.4.Fakes.

Vous pouvez modifier ou supprimer cette version en modifiant l’attribut Version de l’élément Assembly dans les fichiers .fakes :

attribute of the Assembly element in the .fakes:
<Fakes ...>
  <Assembly Name="MyAssembly" Version="1.2.3.4" />
  ...
</Fakes>

Conventions d’affectation de noms fakes

Conventions de nomenclature des types shim et stub

Espaces de noms

  • Le suffixe .Fakes est ajouté à l'espace de noms.

    Par exemple, l’espace de noms System.Fakes contient les types de shim de l’espace de noms System.

  • Global.Fakes contient le type de shim de l’espace de noms vide.

    Noms de types

  • Le préfixe shim est ajouté au nom du type pour générer le nom du type shim.

    Par exemple, ShimExample est le type shim du type Example.

  • Le préfixe stub est ajouté au nom de type pour générer le nom du type stub.

    Par exemple, StubIExample est le type stub du type IExample.

    Arguments de type et structures de type imbriquées

  • Les arguments de type générique sont copiés.

  • La structure de type imbriquée est copiée pour les types shim.

Conventions de nommage de propriété déléguée shim ou de champ de stub délégué

Règles de base pour le nommage de champ, à partir d’un nom vide :

  • Le nom de la méthode est ajouté.

  • Si le nom de la méthode est une implémentation d’interface explicite, les points sont supprimés.

  • Si la méthode est générique, Ofn est ajouté où n correspond au nombre d’arguments de méthode générique.

    Les noms de méthodes spéciales tels que getters de propriétés ou setters sont traités comme indiqué dans le tableau suivant :

Si la méthode est... Example Nom de la méthode ajouté
Constructeur .ctor Constructor
Constructeur statique .cctor StaticConstructor
Un accesseur avec un nom de méthode composé de deux parties séparées par «_» (par exemple, accesseurs de propriété) kind_name (cas courant, mais pas appliqué par ECMA) NameKind, où les deux parties ont été capitalisées et permutées
Accesseur de la propriété Prop PropGet
Mutateur de propriété Prop PropSet
Ajouteur d'événements Add
Outil de suppression d'événements Remove
Opérateur composé de deux parties op_name NameOp
Par exemple : + opérateur op_Add AddOp
Pour un opérateur de conversion, le type de retour est ajouté. T op_Implicit ImplicitOpT

Note

  • Les getters et les setters des indexeurs sont traités de la même façon que les propriétés. Le nom par défaut d’un indexeur est Item.
  • Les noms de type de paramètre sont transformés et concaténés.
  • Le type de retour est ignoré, sauf s’il existe une ambiguïté de surcharge. S’il existe une ambiguïté de surcharge, le type de retour est ajouté à la fin du nom.

Conventions de nomenclature des types de paramètres

Étant donné Chaîne ajoutée est...
TypeT T

L’espace de noms, la structure imbriquée et les tics génériques sont supprimés.
Paramètre de sortieout T TOut
Paramètre refref T TRef
Type de tableauT[] TArray
Type de tableau multidimensionnelT[ , , ] T3
Type de pointeurT* TPtr
Type génériqueT<R1, ...> TOfR1
Argument de type générique de type!iC<TType> Ti
Argument générique pour une méthode!!iM<MMethod> Mi
Type imbriquéN.T N est ajouté, puis T

Règles récursives

Les règles suivantes sont appliquées de manière récursive :

  • Étant donné que Fakes utilise C# pour générer les assemblys Fakes, tout caractère qui produirait un jeton C# non valide est placé dans « _ » (trait de soulignement).

  • Si un nom résultant est en conflit avec un membre du type déclarant, un schéma de numérotation est utilisé en ajoutant un compteur à deux chiffres, à partir de 01.

Utilisation de Microsoft Fakes dans l’intégration continue

Génération d’assemblies Microsoft Fakes

Microsoft Fakes est une fonctionnalité disponible exclusivement dans Visual Studio Enterprise. Par conséquent, la génération des Fakes Assemblies nécessite l’utilisation de la tâche de build de Visual Studio lors de la compilation de votre projet.

Note

Une autre stratégie consiste à vérifier vos assemblys Fakes directement dans le système d’intégration continue (CI) et à utiliser la tâche MSBuild. Si vous optez pour cette approche, vous devez vous assurer d’inclure une référence d’assembly à l’assembly Fakes généré dans votre projet de test, comme indiqué dans l’extrait de code suivant :

<Project Sdk="Microsoft.NET.Sdk">
    <ItemGroup>
        <Reference Include="FakesAssemblies\System.Fakes.dll"/>
    </ItemGroup>
</Project>

Cette référence doit être ajoutée manuellement, spécifiquement pour les projets de style SDK (autrement dit, .NET Core, .NET 5+ et .NET Framework), car ces projets ajoutent implicitement des références d’assembly. Si vous décidez d’utiliser cette méthode, veillez à mettre à jour l’assembly Fakes chaque fois que l’assembly parent subit des modifications.

Contenu connexe

  • Last updated on