-
Notifications
You must be signed in to change notification settings - Fork 4
Getting Started
The information on this page is meant to help you get up and running with Fasterflect in no time.
These are the topics you'll find covered on this page: Using Fasterflect
In order to get started with the library you must add a reference to the Fasterflect assembly (which is the Fasterflect.dll file) and add a using directive to the Fasterflect namespace in your source files. Fasterflect does not use a configuration file or section, nor does it currently provide any other means of configuration.
Fasterflect offers 3 major areas of functionality, click the links provided to explore more about them.
- Querying: Fasterflect allows you to query .NET metadata such as looking-up types in an assembly, searching for methods matching a partial name, finding all constructors of a type etc.
- Accessing: Fasterflect allow you to perform reflective invocations on constructors, indexers, fields, properties and methods for both reference types (including arrays) and struct types. Fasterflect also supports working with ref/out parameters, inferring parameter types to simplify invocations etc. These are backed by the dynamic code generation mechanism.
- Services: Built on top of the core querying and accessing services, Fasterflect implements various helper functionality such as deep object cloning, creating types w/o knowing a specific constructor, and perform object mapping.
Much like standard reflection allows you to customize the behavior of its operations by passing in a BindingFlags value, Fasterflect provides a Flags struct that serves the same purpose. Since Fasterflect is built on top of reflection you'll find that it contains many of the same values as the BindingFlags enum and in fact provides implicit conversion operators to convert between the two types. This allows you to pass a BindingFlags value to methods that expect a Flags instance, although doing so will limit the capabilities of Fasterflect to that of standard reflection.
The primary reason for not simply reusing the existing BindingFlags enumeration is that you cannot extend an enumeration with additional values or remove unsupported values. Adding a second enumeration parameter to carry Fasterflect-specific flags would hurt usability as well as maintainability ("death by overload"). Enumerations in .NET are also limited in that you cannot define methods or operators on them, which can make working with bitmask combinations somewhat cumbersome.
The solution is an immutable struct called Flags, which exposes static fields for every supported value of BindingFlags as well as a number of Fasterflect-specific additions. There are also static fields that provide access to the most commonly used combinations of Flags, which makes it easier to create new custom combinations.
Unless otherwise is noted in the descriptions below these flags do the same as the corresponding BindingFlags. You can find examples of how to use these flags on the Standard Queries page.
- Public Include public members in the search.
- NonPublic Include non-public (protected, internal and private) members in the search.
- Instance Include instance members in the search.
- Static Include static members in the search.
- IgnoreCase Use case-insensitive comparisons (StringComparison.OrdinalIgnoreCase) when querying for members by name or substring. The default is to perform case-sensitive comparisons (StringComparison.Ordinal).
- DeclaredOnly Only search for members declared on the type being reflected on, ignoring members from base types.
- ExactBinding Match parameter types exactly rather than by assignment compatibility. Note that this flag is respected by Fasterflect even in cases where normal Reflection calls would ignore it.
- None This represents the empty set of flags and corresponds to the unmapped BindingFlags.Default value. A different name was chosen because Fasterflect does not use the empty set of flags as its default.
As you may have noticed, the FlattenHierarchy flag is not listed above. This is because Fasterflect will include members from anywhere in the type hierarchy by default, regardless of whether you are querying for instance or static members. None of the BindingFlags values related to accessing members are supported as Fasterflect provides an alternate API to provide these capabilities. It should also be noted that Fasterflect will never return any members defined on the System.Object base class as it would be both faster and easier to access these directly.
These flags allow Fasterflect to provide querying capabilities that go beyond what is found in standard reflection. You can find examples of how to use these flags on the Advanced Queries page.
- PartialNameMatch Querying for named members will use partial matching (using string.Contains) instead of looking for an exact match (string.Equals).
- TrimExplicitlyImplemented Querying for named members will strip off the namespace and interface name from explicitly implemented members before doing any comparison operations. Use this when you want to include explicitly implemented members in the search.
- ExcludeExplicitlyImplemented Querying for members will exclude explicitly implemented interface members.
- ExcludeBackingMembers Querying for members will exclude backing members. This includes backing fields for automatic properties, the getter/setter methods for properties, as well as overridden virtual methods.
- ExcludeHiddenMembers Querying for members will exclude base members that have either been overridden or shadowed. This is implemented by comparing member names (and for methods, also the method signature; method return types are not considered). Only the first unique match is included.
- AnyVisibility Public | NonPublic
- InstanceAnyVisibility Instance | AnyVisibility
- StaticAnyVisibility Static | AnyVisibility
- StaticInstanceAnyVisibility Static | Instance | AnyVisibility
- InstanceAnyDeclaredOnly InstanceAnyVisibility | DeclaredOnly
- StaticAnyDeclaredOnly StaticAnyVisibility | DeclaredOnly
Fasterflect will use either InstanceAnyVisibility or StaticAnyVisibility (depending on the context) whenever the Flags parameter is omitted.
Fasterflect uses light-weight code generation (LWCG) using dynamic methods to speed up access operations, i.e. method invocation, field value retrieval etc. (unfortunately, the same cannot be done for the lookup operations). Although generating the dynamic method is very fast it takes a significant amount of time to JIT-compile the code. To minimize this overhead Fasterflect caches all of the dynamic methods it creates. The underlying cache is thread safe and cache entries are wrapped in WeakReference objects to allow them to be reclaimed by the garbage collector if you're running low on memory. As such you don't really need to worry about the presence of the cache, since it operates silently and safely behind the scenes.
However, it is worth noting that invoking the dynamic method generated by Fasterflect directly avoids the cache lookup, which for repeated operations can provide a significant speed boost. If you have performance-critical code this option is worth keeping in mind. Head over to the Benchmarks page to see some numbers on the performance differences or jump directly to Using Delegates to learn how to take advantage of this.