Kodgenererings-, kompilerings- och namngivningskonventioner i Microsoft Fakes

Den här artikeln beskriver alternativ och problem i generering och kompilering av kod för förfalskningar och beskriver namngivningskonventionerna för förfalskningsgenererade typer, medlemmar och parametrar.

Requirements

• Visual Studio Enterprise

• Ett .NET Framework-projekt

• Projektstöd i .NET Core, .NET 5.0 eller senare och SDK-format förhandsgranskas i Visual Studio 2019 Update 6 och är aktiverat som standard i Uppdatering 8. Mer information finns i Microsoft Fakes for .NET Core- och SDK-liknande projekt.

Kodgenerering och kompilering

Konfigurera kodgenerering av stubbar

Genereringen av stub-typer konfigureras i en XML-fil med filnamnstillägget .fakes . Ramverket Fakes integreras i byggprocessen via anpassade MSBuild-uppgifter och identifierar filerna vid byggtiden. Kodgeneratorn Fakes kompilerar stub-typerna till en sammansättning och lägger till referensen till projektet.

I följande exempel visas stub-typer som definierats i FileSystem.dll:

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

Typfiltrering

Filter kan anges i .fakes-filen för att begränsa vilka typer som ska stubbas. Du kan lägga till ett obundet antal clear-, add-, remove-element under StubGeneration-elementet för att skapa listan över valda typer.

Följande .fakes-fil genererar till exempel stubs för typer under system- och System.IO namnrymder, men exkluderar alla typer som innehåller "Handle" i 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>

Filtersträngarna använder en enkel grammatik för att definiera hur matchningen ska göras:

• Filter är skiftlägesokänsliga som standard; filter utför en delsträngsmatchning.

  el matchar "hej"

• Om du lägger ! till i slutet av filtret blir det en exakt skiftlägeskänslig matchning:

  el! matchar inte "hej"

  hello! motsvarar "hello"

• Om du lägger * till i slutet av filtret matchar det prefixet för strängen:

  el* matchar inte "hej"

  he* matchar "hello"

• Flera filter i en semikolonavgränsad lista kombineras som en disjunction:

  el;wo matchar "hello" och "world"

Stub konkreta klasser och virtuella metoder

Som standard genereras stub-typer för alla icke-förseglade klasser. Det är möjligt att begränsa stub-typerna till abstrakta klasser via konfigurationsfilen .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>

Interna typer

Kodgeneratorn Fakes skapar shim-typer och stub-typer för typer som är åtkomliga i den genererade Fakes-assemblyn. För att göra interna typer av en shimmed assembly synlig för Fakes och din testassembly lägger du till InternalsVisibleToAttribute attribut till koden för den shimmed assembly som ger synlighet för den genererade Fakes-assemblyn och till testassemblyn. Här är ett exempel:

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

Interna typer i starkt namngivna sammansättningar

Om en shimmad sammansättning har ett starkt namn och du vill komma åt interna typer av denna sammansättning:

• Både testsammansättningen och sammansättningen Fakes måste namnges starkt.

• Lägg till de offentliga nycklarna för test- och Fakes-sammansättningen i attributen InternalsVisibleToAttribute i de shimmed-sammansättningarna. Så här skulle exempelattributen i den shimade sammansättningen se ut när den shimade sammansättningen är starkt namngiven.

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

Om den shimmed sammansättningen namnges starkt, signerar Fakes-ramverket automatiskt starkt den genererade Fakes-sammansättningen. Du måste starkt signera testmonteringen. Se även Strong-Named sammansättningar.

Ramverket Fakes använder samma nyckel för att signera alla genererade sammansättningar, så du kan använda det här kodfragmentet som utgångspunkt för att lägga till attributet InternalsVisibleTo för fakes-assemblyn i din shim-sammansättningskod.

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

Du kan ange en annan offentlig nyckel för Fakes-sammansättningen, till exempel en nyckel som du har skapat för shim-sammansättningen, genom att ange den fullständiga sökvägen till .snk-filen som innehåller den alternativa nyckeln som attributvärde för KeyFile i elementet Fakes\Compilation av .fakes-filen. Till exempel:

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

Sedan måste du använda den offentliga nyckeln för den alternativa .snk-filen som den andra parametern i attributet InternalVisibleTo för Fakes-sammansättningen i den shimmed sammansättningskoden:

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

I exemplet ovan kan värdena Alternate_public_key och Test_assembly_public_key kan vara desamma.

Optimera byggtider

Kompilering av Fakes-sammansättningar kan avsevärt öka din kompileringstid. Du kan minimera byggtiden genom att generera förfalskningssammansättningar för .NET System-sammansättningar och sammansättningar från tredje part i ett separat centraliserat projekt. Eftersom sådana sammansättningar sällan ändras på datorn kan du återanvända de genererade förfalskningssammansättningarna i andra projekt.

Från dina enhetstestprojekt lägger du till en referens till de kompilerade förfalskningssammansättningarna som placeras under FakesAssemblies i projektmappen.

1. Skapa ett nytt klassbibliotek med .NET-körningsversionen som matchar dina testprojekt. Låt oss kalla det Fakes.Prebuild. Ta bort class1.cs-filen från projektet, behövs inte.

2. Lägg till referens till alla system- och tredjepartssammansättningar som du behöver förfalskningar för.

3. Lägg till en .fakes-fil för var och en av sammansättningarna och bygget.

4. Från ditt testprojekt

   • Kontrollera att du har en referens till Fakes-runtime-DLL:en.

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

   • För varje sammansättning som du har skapat förfalskningar för lägger du till en referens till motsvarande DLL-fil i mappen Fakes.Prebuild\FakesAssemblies i projektet.

Undvik att sammansättningsnamnet kolliderar

I en Team Build-miljö sammanfogas alla byggutdata till en enda katalog. Om flera projekt använder förfalskningar kan det hända att förfalskningssammansättningar från olika versioner åsidosätter varandra. TestProject1 simulerar till exempel mscorlib.dll från .NET Framework 2.0 och TestProject2 simulerar mscorlib.dll för .NET Framework 4 skulle båda resultera i en mscorlib.Fakes.dll Fakes-samling.

För att undvika det här problemet bör Fakes automatiskt skapa versionskvalificerade assemblenamn för icke-projektreferenser när du lägger till .fakes-filerna. Ett versionskvalificerat sammansättningsnamn för Fakes bäddar in ett versionsnummer när du skapar sammansättningsnamnet Fakes:

Med tanke på en sammansättning MyAssembly och en version 1.2.3.4 är Fakes sammansättningsnamn MyAssembly.1.2.3.4.Fakes.

Du kan ändra eller ta bort den här versionen genom att redigera attributet Version för sammansättningselementet i .fakes:

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

Förfalskningar namngivningskonventioner

Namngivningskonventioner för shim-typen och stub-typen

Namespaces

• Suffixet Fakes läggs till i namnområdet.

  Till exempel innehåller System.Fakes-namnområdet shim-typerna för System-namnområdet.

• Global.Fakes innehåller shim-typen för det tomma namnområdet.

  Skriv namn

• Shim-prefixet läggs till i typnamnet för att skapa namnet på shim-typen.

  ShimExample är till exempel shim-typen av exempeltyp.

• Stub-prefix läggs till i typnamnet för att skapa stub-typnamnet.

  Till exempel är StubIExample stub-typen av IExample-typ.

  Typargument och kapslade typstrukturer

• Allmänna typargument kopieras.

• Kapslad typstruktur kopieras för shim-typer.

Namngivningskonventioner för Shim-delegategenskap eller stub-delegatefält

Grundläggande regler för namngivning av fält, med början från ett tomt namn:

• Metodnamnet läggs till.

• Om metodnamnet är en explicit gränssnittsimplementering tas punkterna bort.

• Om metoden är generisk Of läggs n till där n är antalet generiska metodargument.

  Särskilda metodnamn som egenskapshämtare eller -inställare behandlas som beskrivs i följande tabell.

Namngivningskonventioner för parametertyp

Rekursiva regler

Följande regler tillämpas rekursivt:

• Eftersom Fakes använder C# för att generera Fakes-samlingar, ersätts alla tecken som skulle resultera i ett ogiltigt C#-token med "_" (understreck).

• Om ett resulterande namn krockar med någon medlem av deklareringstypen används ett numreringsschema genom att lägga till en tvåsiffrig räknare från och med 01.

Använda Microsoft Fakes i kontinuerlig integration

Microsoft Fakes sammansättningsgenerering

Microsoft Fakes är en funktion som är exklusivt tillgänglig i Visual Studio Enterprise. Därför kräver genereringen av Fakes Assemblies användningen av Visual Studio Build Task när du skapar projektet.

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

Den här referensen måste läggas till manuellt, särskilt för SDK-liknande projekt (dvs. .NET Core, .NET 5+ och .NET Framework), eftersom dessa projekt nu implicit lägger till sammansättningsreferenser. Om du bestämmer dig för att använda den här metoden måste du uppdatera Fakes assembly när huvudassemblyn genomgår ändringar.

Relaterat innehåll

• Isolera testad kod med Microsoft Fakes