Code generation, compilation, and naming conventions in Microsoft Fakes
This article discusses options and issues in Fakes code generation and compilation, and describes the naming conventions for Fakes generated types, members, and parameters.
- Visual Studio Enterprise
- A .NET Framework project
.NET Standard projects are not supported.
Code generation and compilation
Configure code generation of stubs
The generation of stub types is configured in an XML file that has the .fakes file extension. The Fakes framework integrates in the build process through custom MSBuild tasks and detects those files at build time. The Fakes code generator compiles the stub types into an assembly and adds the reference to the project.
The following example illustrates stub types defined in FileSystem.dll:
<Fakes xmlns="http://schemas.microsoft.com/fakes/2011/"> <Assembly Name="FileSystem"/> </Fakes>
Filters can be set in the .fakes file to restrict which types should be stubbed. You can add an unbounded number of Clear, Add, Remove elements under the StubGeneration element to build the list of selected types.
For example, the following .fakes file generates stubs for types under the System and System.IO namespaces, but excludes any type containing "Handle" in 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>
The filter strings use a simple grammar to define how the matching should be done:
Filters are case-insensitive by default; filters perform a substring matching:
!to the end of the filter makes it a precise case-sensitive match:
el!does not match "hello"
*to the end of the filter makes it match the prefix of the string:
el*does not match "hello"
Multiple filters in a semicolon-separated list are combined as a disjunction:
el;womatches "hello" and "world"
Stub concrete classes and virtual methods
By default, stub types are generated for all non-sealed classes. It is possible to restrict the stub types to abstract classes through the .fakes configuration file:
<Fakes xmlns="http://schemas.microsoft.com/fakes/2011/"> <Assembly Name="mscorlib" /> <!-- user code --> <StubGeneration> <Types> <Clear /> <Add AbstractClasses="true"/> </Types> </StubGeneration> <!-- /user code --> </Fakes>
The Fakes code generator generates shim types and stub types for types that are visible to the generated Fakes assembly. To make internal types of a shimmed assembly visible to Fakes and your test assembly, add InternalsVisibleToAttribute attributes to the shimmed assembly code that gives visibility to the generated Fakes assembly and to the test assembly. Here's an example:
// FileSystem\AssemblyInfo.cs [assembly: InternalsVisibleTo("FileSystem.Fakes")] [assembly: InternalsVisibleTo("FileSystem.Tests")]
Internal types in strongly named assemblies
If the shimmed assembly is strongly named, and you want to access internal types of the assembly:
Both your test assembly and the Fakes assembly must be strongly named.
Add the public keys of the test and Fakes assembly to the InternalsVisibleToAttribute attributes in the shimmed assemblies. Here's how the example attributes in the shimmed assembly code would look when the shimmed assembly is strongly named:
// FileSystem\AssemblyInfo.cs [assembly: InternalsVisibleTo("FileSystem.Fakes", PublicKey=<Fakes_assembly_public_key>)] [assembly: InternalsVisibleTo("FileSystem.Tests", PublicKey=<Test_assembly_public_key>)]
If the shimmed assembly is strongly named, the Fakes framework automatically strongly signs the generated Fakes assembly. You have to strong sign the test assembly. See Strong-Named assemblies.
The Fakes framework uses the same key to sign all generated assemblies, so you can use this snippet as a starting point to add the InternalsVisibleTo attribute for the fakes assembly to your shimmed assembly code.
[assembly: InternalsVisibleTo("FileSystem.Fakes, PublicKey=0024000004800000940000000602000000240000525341310004000001000100e92decb949446f688ab9f6973436c535bf50acd1fd580495aae3f875aa4e4f663ca77908c63b7f0996977cb98fcfdb35e05aa2c842002703cad835473caac5ef14107e3a7fae01120a96558785f48319f66daabc862872b2c53f5ac11fa335c0165e202b4c011334c7bc8f4c4e570cf255190f4e3e2cbc9137ca57cb687947bc")]
You can specify a different public key for the Fakes assembly, such as a key you have created for the shimmed assembly, by specifying the full path to the .snk file that contains the alternate key as the
KeyFile attribute value in the
Compilation element of the .fakes file. For example:
<-- FileSystem.Fakes.fakes --> <Fakes ...> <Compilation KeyFile="full_path_to_the_alternate_snk_file" /> </Fakes>
You then have to use the public key of the alternate .snk file as the second parameter of the InternalVisibleTo attribute for the Fakes assembly in the shimmed assembly code:
// FileSystem\AssemblyInfo.cs [assembly: InternalsVisibleTo("FileSystem.Fakes", PublicKey=<Alternate_public_key>)] [assembly: InternalsVisibleTo("FileSystem.Tests", PublicKey=<Test_assembly_public_key>)]
In the example above, the values
Alternate_public_key and the
Test_assembly_public_key can be the same.
Optimize build times
The compilation of Fakes assemblies can significantly increase your build time. You can minimize the build time by generating the Fakes assemblies for .NET System assemblies and third-party assemblies in a separate centralized project. Because such assemblies rarely change on your machine, you can reuse the generated Fakes assemblies in other projects.
From your unit test projects, add a reference to the compiled Fakes assemblies that are placed under FakesAssemblies in the project folder.
Create a new Class Library with the .NET runtime version matching your test projects. Let's call it Fakes.Prebuild. Remove the class1.cs file from the project, not needed.
Add reference to all the System and third-party assemblies you need Fakes for.
Add a .fakes file for each of the assemblies and build.
From your test project
Make sure that you have a reference to the Fakes runtime DLL:
%ProgramFiles(x86)%\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\PublicAssemblies\Microsoft.QualityTools.Testing.Fakes.dll
For each assembly that you have created Fakes for, add a reference to the corresponding DLL file in the Fakes.Prebuild\FakesAssemblies folder of your project.
Avoid assembly name clashing
In a Team Build environment, all build outputs are merged into a single directory. If multiple projects use Fakes, it might happen that Fakes assemblies from different versions override each other. For example, TestProject1 fakes mscorlib.dll from the .NET Framework 2.0 and TestProject2 fakes mscorlib.dll for the .NET Framework 4 would both yield to a mscorlib.Fakes.dll Fakes assembly.
To avoid this issue, Fakes should automatically create version qualified Fakes assembly names for non-project references when adding the .fakes files. A version-qualified Fakes assembly name embeds a version number when you create the Fakes assembly name:
Given an assembly MyAssembly and a version 22.214.171.124, the Fakes assembly name is MyAssembly.126.96.36.199.Fakes.
You can change or remove this version by the editing the Version attribute of the Assembly element in the .fakes:
attribute of the Assembly element in the .fakes: <Fakes ...> <Assembly Name="MyAssembly" Version="188.8.131.52" /> ... </Fakes>
Fakes naming conventions
Shim type and stub type naming conventions
.Fakes suffix is added to the namespace.
System.Fakesnamespace contains the shim types of System namespace.
Global.Fakes contains the shim type of the empty namespace.
Shim prefix is added to the type name to build the shim type name.
For example, ShimExample is the shim type of the Example type.
Stub prefix is added to the type name to build the stub type name.
For example, StubIExample is the stub type of the IExample type.
Type Arguments and Nested Type Structures
Generic type arguments are copied.
Nested type structure is copied for shim types.
Shim delegate property or stub delegate field naming conventions
Basic rules for field naming, starting from an empty name:
The method name is appended.
If the method name is an explicit interface implementation, the dots are removed.
If the method is generic,
Ofn is appended where n is the number of generic method arguments.
Special method names such as property getter or setters are treated as described in the following table:
|If method is...||Example||Method name appended|
|A static constructor||
|An accessor with method name composed of two parts separated by "_" (such as property getters)||kind_name (common case, but not enforced by ECMA)||NameKind, where both parts have been capitalized and swapped|
|Getter of property
|Setter of property
|An operator composed of two parts||
|For example: + operator||
|For a conversion operator, the return type is appended.||
- Getters and setters of indexers are treated similarly to the property. The default name for an indexer is
- Parameter type names are transformed and concatenated.
- Return type is ignored unless there's an overload ambiguity. If there's an overload amiguity, the return type is appended at the end of the name.
Parameter type naming conventions
|Given||Appended string is...|
The namespace, nested structure, and generic tics are dropped.
|An out parameter
|A ref parameter
|An array type
|A multi-dimensional array type
|A pointer type
|A generic type
|A generic type argument
|A generic method argument
|A nested type
The following rules are applied recursively:
Because Fakes uses C# to generate the Fakes assemblies, any character that would produce an invalid C# token is escaped to "_" (underscore).
If a resulting name clashes with any member of the declaring type, a numbering scheme is used by appending a two-digit counter, starting at 01.