Code generation, compilation, and naming conventions in Microsoft Fakes
For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.
This topic 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
- Configuring code generation of stubs • Type filtering • Stubbing concrete classes and virtual methods • Internal types • Optimizing build times • Avoiding assembly name clashing
- Shim type and stub type naming conventions • Shim delegate property or stub delegate field naming conventions • Parameter type naming conventions • Recursive rules
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, this .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 will make it a precise case-sensitive match:
el!does not match "hello"
*to the end of the filter will make 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"
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 will generate 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 access internal types of the assembly:
Both your test assembly and the Fakes assembly must be strongly named.
You must add the public keys of the test and Fakes assembly to the InternalsVisibleToAttribute attributes in the shimmed assemblies. Here's how our example attributes in the shimmed assembly code would look when the shimmed assembly is strongly named:
If the shimmed assembly is strongly named, the Fakes framework will automatically strongly sign the generated Fakes assembly. You have to strong sign the test assembly. See Creating and Using 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.
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, you can simply take a reference to the compiled Fakes assemblies that are placed under the 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:
C:\Program Files\Microsoft Visual Studio 12.0\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.
In a Team Build environment, all build outputs are merged into a single directory. In the case of multiple projects using Fakes, it might happen that Fakes assemblies from different version 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 188.8.131.52, the Fakes assembly name is MyAssembly.184.108.40.206.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="220.127.116.11" /> ... </Fakes>
.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.
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 this is the case, the return type is appended at the end of the name
|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.