From 2b3c6a5aa33901247853b71744c9d1135e634898 Mon Sep 17 00:00:00 2001 From: Steve Wilkes Date: Mon, 26 Nov 2018 20:38:57 +0000 Subject: [PATCH 1/2] Fixing code samples to C# with VS2015 highlighting --- docs/src/Assembly-Scanning.md | 2 +- docs/src/Cloning-Mappers.md | 2 +- docs/src/Collections.md | 2 +- docs/src/Configuration-Classes.md | 16 ++++++------ docs/src/Configuring-Constructor-Arguments.md | 6 ++--- docs/src/Configuring-Exception-Handling.md | 8 +++--- docs/src/Configuring-Mapping-Callbacks.md | 10 +++---- docs/src/Configuring-Member-Name-Patterns.md | 12 ++++----- docs/src/Configuring-Member-Values.md | 26 +++++++++---------- docs/src/Configuring-Object-Construction.md | 6 ++--- docs/src/Configuring-Object-Identifiers.md | 4 +-- docs/src/Dependency-Injection.md | 8 +++--- docs/src/Derived-Types.md | 8 +++--- docs/src/Dictionary-Mapping-Configuration.md | 20 +++++++------- docs/src/Dictionary-Mapping.md | 8 +++--- docs/src/Dynamic-Mapping-Configuration.md | 20 +++++++------- docs/src/Dynamic-Mapping.md | 8 +++--- docs/src/Entity-Mapping.md | 2 +- docs/src/Enum-Mapping.md | 8 +++--- docs/src/Ignoring-Target-Members.md | 18 ++++++------- docs/src/Inline-Configuration.md | 12 ++++----- docs/src/Join-Entities.md | 4 +-- docs/src/Mapped-Object-Tracking.md | 6 ++--- docs/src/Mapping-Extension-Methods.md | 10 +++---- docs/src/Member-Matching.md | 2 +- docs/src/Meta-Members.md | 2 +- docs/src/Null-Results.md | 4 +-- docs/src/Object-Flattening.md | 8 +++--- docs/src/Object-Unflattening.md | 6 ++--- docs/src/Pairing-Derived-Types.md | 8 +++--- docs/src/Performing-Merges.md | 4 +-- docs/src/Performing-Updates.md | 4 +-- .../src/Projecting-Recursive-Relationships.md | 8 +++--- docs/src/Projecting-to-Derived-Types.md | 2 +- docs/src/Query-Projection-Configuration.md | 4 +-- docs/src/Query-Projection.md | 6 ++--- docs/src/Static-vs-Instance-Mappers.md | 8 +++--- docs/src/To-String-Formatting.md | 2 +- docs/src/Type-Conversion.md | 2 +- docs/src/Using-Execution-Plans.md | 6 ++--- docs/src/Validating-Mappings.md | 6 ++--- docs/src/index.md | 12 ++++----- mkdocs.yml | 2 ++ 43 files changed, 162 insertions(+), 160 deletions(-) diff --git a/docs/src/Assembly-Scanning.md b/docs/src/Assembly-Scanning.md index 4c1db82f9..8c40d9d9a 100644 --- a/docs/src/Assembly-Scanning.md +++ b/docs/src/Assembly-Scanning.md @@ -1,6 +1,6 @@ By default, the assembly in which a base type is declared is searched for derived types. If there are additional assemblies which should be searched, use: -```C# +```cs Mapper.WhenMapping.LookForDerivedTypesIn( typeof(DerivedType1).Assembly, typeof(DerivedType2).Assembly); diff --git a/docs/src/Cloning-Mappers.md b/docs/src/Cloning-Mappers.md index 0dd0a5fec..0180efdb7 100644 --- a/docs/src/Cloning-Mappers.md +++ b/docs/src/Cloning-Mappers.md @@ -1,6 +1,6 @@ Mappers can be cloned, to enable 'derived' mappers to inherit, add to and override a 'root' configuration: -``` C# +```cs var baseMapper = Mapper.CreateNew(); // Setup the base configuration: diff --git a/docs/src/Collections.md b/docs/src/Collections.md index 8124181e6..3e4aacf9b 100644 --- a/docs/src/Collections.md +++ b/docs/src/Collections.md @@ -23,7 +23,7 @@ Generic `List` instances are created for interface-type members except `ISet< By default, if the source collection matching a target collection is null, the target collection is populated with an empty collection. You can configure setting the target collection to null instead like this: -```C# +```cs // Map null-source collections to null for all source // and target types: Mapper.WhenMapping.MapNullCollectionsToNull(); diff --git a/docs/src/Configuration-Classes.md b/docs/src/Configuration-Classes.md index 382253a2a..c9bad61b4 100644 --- a/docs/src/Configuration-Classes.md +++ b/docs/src/Configuration-Classes.md @@ -6,7 +6,7 @@ Multiple, dedicated configuration classes can be created by deriving from the ab Mapper configuration is set up by implementing the abstract `Configure` method: -```C# +```cs public class ProductMappingConfiguration : MapperConfiguration { protected override void Configure() @@ -34,21 +34,21 @@ In this example the default mapper is configured - the one used via the [static] To apply a particular `MapperConfiguration` Type, supply it explicitly: -```C# +```cs Mapper.WhenMapping .UseConfigurations.From(); ``` To apply all `MapperConfiguration` Types from an Assembly, supply a Type from that Assembly: -```C# +```cs Mapper.WhenMapping .UseConfigurations.FromAssemblyOf(); ``` To apply all `MapperConfiguration` Types from multiple Assemblies, supply the Assemblies: -```C# +```cs // Scan all Assemblies from the AppDomain: Mapper.WhenMapping .UseConfigurations.From(assembly1, assembly2, assembly3); @@ -63,7 +63,7 @@ Mapper.WhenMapping To apply all `MapperConfiguration` Types from the Assemblies current loaded into the `AppDomain`, use: -```C# +```cs // Scan all Assemblies from the AppDomain: Mapper.WhenMapping .UseConfigurations.FromCurrentAppDomain(); @@ -79,7 +79,7 @@ Mapper.WhenMapping Calling `GetPlansFor().To()` caches the mapping function at the point you call it. If Types configured in the object graph are configured in more than one `MapperConfiguration`, you might need to define an order in which configuration classes are applied. Use: -```C# +```cs // Configure aspects of Parent -> Parent mapping, which includes // mapping Child -> Child. Automatically apply ChildMapperConfiguration, // then apply this configuration afterwards. @@ -100,7 +100,7 @@ Chains of `ApplyAfter` attributes will be followed, with all configurations auto [Configured Service Providers](Dependency-Injection) are available to `MapperConfiguration` classes. For example: -```C# +```cs // Get a Dependency Injection container: var diContainer = GetDiContainer(); @@ -114,7 +114,7 @@ Mapper.WhenMapping ...the DI container and its registered services are now available to the `MapperConfiguration` class via the `GetService()` and `GetServiceProvider()` methods: -```C# +```cs public class MyMappingConfiguration : MapperConfiguration { protected override void Configure() diff --git a/docs/src/Configuring-Constructor-Arguments.md b/docs/src/Configuring-Constructor-Arguments.md index 8030159bf..36b586d9b 100644 --- a/docs/src/Configuring-Constructor-Arguments.md +++ b/docs/src/Configuring-Constructor-Arguments.md @@ -4,7 +4,7 @@ Constructor arguments can be configured by type or name, and constant values or For example, to configure mapping these types: -```C# +```cs public class CustomerDto { public string CustomerNum { get; set; } @@ -21,7 +21,7 @@ public class Customer ...use: -```C# +```cs Mapper.WhenMapping .From() // Apply to CustomerDto mappings .ToANew() // Apply to Customer creations @@ -34,7 +34,7 @@ Mapper.WhenMapping ...or, if inline configuration is preferred: -```C# +```cs // Source, target and mapping types are implicit from the mapping: Mapper .Map(customerDto).ToANew(cfg => cfg diff --git a/docs/src/Configuring-Exception-Handling.md b/docs/src/Configuring-Exception-Handling.md index 32d505fb3..d3915e297 100644 --- a/docs/src/Configuring-Exception-Handling.md +++ b/docs/src/Configuring-Exception-Handling.md @@ -1,13 +1,13 @@ By default, an `Exception` thrown during a mapping is wrapped in a [`MappingException`](/agileobjects/AgileMapper/blob/master/AgileMapper/MappingException.cs) and rethrown. To configure a mapper to swallow exceptions and return null instead, use: -```C# +```cs Mapper.WhenMapping .SwallowAllExceptions(); ``` Alternatively, to have a mapper call a callback in the event of an exception use: -```C# +```cs Mapper.WhenMapping .PassExceptionsTo(ctx => { @@ -23,7 +23,7 @@ Mapper.WhenMapping To only swallow exceptions thrown when mapping particular types, use: -```C# +```cs Mapper.WhenMapping .From() // Apply to PersonViewModel mappings (optional) .To() // Apply to Person creation, updates and merges @@ -32,7 +32,7 @@ Mapper.WhenMapping ...and to have a callback called for a particular type, use: -```C# +```cs Mapper.WhenMapping .To() .PassExceptionsTo(ctx => diff --git a/docs/src/Configuring-Mapping-Callbacks.md b/docs/src/Configuring-Mapping-Callbacks.md index 11295552a..691a77d02 100644 --- a/docs/src/Configuring-Mapping-Callbacks.md +++ b/docs/src/Configuring-Mapping-Callbacks.md @@ -2,7 +2,7 @@ You can configure code to be executed at specific points in a mapping - conditio Before mapping of a specified type begins: -```C# +```cs mapper.WhenMapping .To() // Apply to Customer creation, updates and merges .Before @@ -13,7 +13,7 @@ mapper.WhenMapping Before an instance of a specified type is created: -```C# +```cs mapper.WhenMapping .From() // Apply to AddressDto mappings .ToANew
() // Apply to Address creation @@ -24,7 +24,7 @@ mapper.WhenMapping After an instance of a specified type is created: -```C# +```cs mapper .After .CreatingInstancesOf
() @@ -34,7 +34,7 @@ mapper On either side of the mapping of a particular member: -```C# +```cs mapper.WhenMapping .From() // Apply to Person mappings .Over() // Apply to PersonVm updates @@ -49,7 +49,7 @@ mapper.WhenMapping At the end of any mapping (conditionally): -```C# +```cs Mapper .After .MappingEnds diff --git a/docs/src/Configuring-Member-Name-Patterns.md b/docs/src/Configuring-Member-Name-Patterns.md index 1d0ad2f52..1b13ac3e9 100644 --- a/docs/src/Configuring-Member-Name-Patterns.md +++ b/docs/src/Configuring-Member-Name-Patterns.md @@ -1,6 +1,6 @@ If a naming convention prevents normal [member matching](Member-Matching), you can configure naming patterns to use to match names up. For example: -```C# +```cs public class ProductDto { public string strName { get; set; } @@ -15,21 +15,21 @@ public class Product To have the name prefixes `str` and `dec` ignored when matching member names, use: -```C# +```cs Mapper.WhenMapping .UseNamePrefixes("str", "dec"); ``` You can also configure name suffixes: -```C# +```cs Mapper.WhenMapping .UseNameSuffix("Value"); // Match 'PriceValue' to 'Price' ``` ...or a regex pattern: -```C# +```cs Mapper.WhenMapping .UseNamePattern("^_(.+)Value$"); // Match '_PriceValue' to 'Price' ``` @@ -38,7 +38,7 @@ Configured regex patterns must start with `^` and end with `$`, contain the capt Naming patterns can also be configured [inline](Inline-Configuration) -```C# +```cs var anonSource = new { _PriceValue = default(double) }; // Source, target and mapping types are implicit from the mapping: @@ -49,7 +49,7 @@ Mapper ...or for specific source and target types: -```C# +```cs var anonSource = new { _PriceValue = default(double) }; Mapper.WhenMapping diff --git a/docs/src/Configuring-Member-Values.md b/docs/src/Configuring-Member-Values.md index 1bbe4479c..1ff49e742 100644 --- a/docs/src/Configuring-Member-Values.md +++ b/docs/src/Configuring-Member-Values.md @@ -2,7 +2,7 @@ There are several ways of configuring a custom data source for a target member. **A source member**: -```C# +```cs Mapper.WhenMapping .From() // Apply to ProductDto mappings .To() // Apply to Product creation, updates and merges @@ -18,7 +18,7 @@ Mapper.WhenMapping **A source expression** (in this example, supplied [inline](Inline-Configuration)): -```C# +```cs // Source, target and mapping types are implicit from the mapping: Mapper.Map(productDto).ToANew(cfg => cfg .Map(ctx => "$" + ctx.Source.Price) // ctx.Source is the ProductDto @@ -27,7 +27,7 @@ Mapper.Map(productDto).ToANew(cfg => cfg **A constant value**: -```C# +```cs Mapper.WhenMapping .From() // Apply to ProductDto mappings .OnTo() // Apply to Product merges only @@ -42,7 +42,7 @@ Mapper.WhenMapping **A value from an [injected service](Dependency-Injection)**: -```C# +```cs // Retrieve an IDateTimeProvider instance from a configured // service provider, and use its UtcNow value: Mapper.WhenMapping @@ -54,7 +54,7 @@ Mapper.WhenMapping **The result of a function call** ([inline](Inline-Configuration)): -```C# +```cs Func companyNameFactory = (dto, p) => dto.ManufaturerName + " Ltd"; @@ -68,7 +68,7 @@ Mapper.Map(productDto).ToANew(cfg => cfg Any of these methods can be configured to be conditional: -```C# +```cs Mapper.WhenMapping .From() // Apply to ProductDto mappings .ToANew() // Apply to Product creation only @@ -79,7 +79,7 @@ Mapper.WhenMapping And in an [inline](Inline-Configuration) example: -```C# +```cs Mapper.Map(productDto).ToANew(cfg => cfg .If((dto, p) => dto.CompanyId == 0) // Apply only if CompanyId is 0 .Map("No-one") // Always the same value @@ -92,13 +92,13 @@ By default, configured data sources only apply in the direction configured - con To make every source- to target-member pairing you configure apply to mappings in either direction, use: -```C# +```cs Mapper.WhenMapping.AutoReverseConfiguredDataSources(); ``` To make every source- to target-member pairing you configure for a particular pair of Types apply to mappings in either direction, use: -```C# +```cs Mapper.WhenMapping .From().To() .AutoReverseConfiguredDataSources(); @@ -106,7 +106,7 @@ Mapper.WhenMapping To make a source- to target-member pairing you configure apply to mappings in either direction, use: -```C# +```cs Mapper.WhenMapping .From().To() .Map(p => p.Specification, dto => dtp.Spec) @@ -117,7 +117,7 @@ Mapper.WhenMapping If you use the mapper-level `AutoReverseConfiguredDataSources()` to set the default behaviour, source- to target-member pairings you configure for a particular pair of Types can opt out using: -```C# +```cs // Set the default behaviour: Mapper.WhenMapping.AutoReverseConfiguredDataSources(); @@ -129,7 +129,7 @@ Mapper.WhenMapping ...and individual source- to target-member pairings can opt out with: -```C# +```cs Mapper.WhenMapping .From().To() .Map(p => p.Specification, dto => dtp.Spec) @@ -140,7 +140,7 @@ Mapper.WhenMapping To map a data source to the root target object, use, *e.g*: -```C# +```cs // Source class - has a nested member 'Statistics': class Video { diff --git a/docs/src/Configuring-Object-Construction.md b/docs/src/Configuring-Object-Construction.md index 608d9884e..1566ff5d6 100644 --- a/docs/src/Configuring-Object-Construction.md +++ b/docs/src/Configuring-Object-Construction.md @@ -1,6 +1,6 @@ Configure a custom factory for a particular type using: -```C# +```cs Mapper.WhenMapping .InstancesOf() // Apply to Customer creation, updates and merges .CreateUsing(ctx => new Customer @@ -11,7 +11,7 @@ Mapper.WhenMapping Configure a custom factory for a particular type when mapping between particular types using: -```C# +```cs Mapper.WhenMapping .From() // Apply to PersonViewModel mappings .To() // Apply to Customer creation, updates and merges @@ -23,7 +23,7 @@ Mapper.WhenMapping Configure a conditional custom factory using ([inline](Inline-Configuration) example): -```C# +```cs Mapper.Map(customerViewModels).ToANew(cfg => cfg .WhenMapping .From() diff --git a/docs/src/Configuring-Object-Identifiers.md b/docs/src/Configuring-Object-Identifiers.md index c350ab9c8..2216f2f9f 100644 --- a/docs/src/Configuring-Object-Identifiers.md +++ b/docs/src/Configuring-Object-Identifiers.md @@ -7,7 +7,7 @@ Objects are identified during collection [updates](Performing-Updates) and [merg You can configure an object to be uniquely identified with a different member using: -```C# +```cs Mapper.WhenMapping .InstancesOf() // Apply to NamedCustomer mappings .IdentifyUsing(c => c.Name); // Identify using NamedCustomer.Name @@ -15,7 +15,7 @@ Mapper.WhenMapping Or, configured [inline](Inline-Configuration): -```C# +```cs Mapper .Map(customerDtos).ToANew(cfg => cfg .WhenMapping diff --git a/docs/src/Dependency-Injection.md b/docs/src/Dependency-Injection.md index c2845696b..2bebee3bd 100644 --- a/docs/src/Dependency-Injection.md +++ b/docs/src/Dependency-Injection.md @@ -4,7 +4,7 @@ A service provider object or pair of functions can be configured to be available To configure a service provider, use: -```C# +```cs // Use a given Type => object provider Func: Mapper.WhenMapping.UseServiceProvider(serviceType => CreateService(serviceType)); @@ -44,7 +44,7 @@ Which methods the registered container supports dictates which service-resolutio Once a provider is configured, services can be accessed via the mapping context: -```C# +```cs // Register a duck-typed provider: Mapper.WhenMapping.UseServiceProvider(serviceProvider); @@ -64,7 +64,7 @@ To retrieve the originally-configured provider, use `ctx.GetServiceProvider("MyService")`) and: To test a `MapperConfiguration` without a service provider instance, use: -```C# +```cs using AgileObjects.AgileMapper.Testing; var logger = new Mock().Object; diff --git a/docs/src/Derived-Types.md b/docs/src/Derived-Types.md index 66ca6ac99..abdb76266 100644 --- a/docs/src/Derived-Types.md +++ b/docs/src/Derived-Types.md @@ -2,7 +2,7 @@ For most cases, derived types are supported without configuration. For example, with the following classes: -```C# +```cs public class Person {} public class Customer : Person { @@ -18,7 +18,7 @@ public class CustomerViewModel : PersonViewModel ...the derived `Customer` type is recognised and mapped to a `CustomerViewModel`, even though the source variable is of type `Person` and the requested target type is `PersonViewModel`: -```C# +```cs var person = new Customer { Discount = 0.1f } as Person; var viewModel = Mapper.Map(person).ToANew(); // viewModel is of type CustomerViewModel @@ -27,7 +27,7 @@ var viewModel = Mapper.Map(person).ToANew(); Derived types are also paired up automatically - for example, with the following classes: -```C# +```cs public class Animal {} public class Dog : Animal {} public class Cat : Animal {} @@ -39,7 +39,7 @@ public class CatDto : AnimalDto {} The following mappings are performed: -```C# +```cs var sourceAnimal = new Dog() as Animal; var resultAnimal = Mapper.Map(sourceDog).ToANew(); // resultAnimal is of type Dog diff --git a/docs/src/Dictionary-Mapping-Configuration.md b/docs/src/Dictionary-Mapping-Configuration.md index 6f2bb00e8..0bfb89736 100644 --- a/docs/src/Dictionary-Mapping-Configuration.md +++ b/docs/src/Dictionary-Mapping-Configuration.md @@ -4,7 +4,7 @@ Dictionary mapping can be configured in various ways. If your source dictionary keys don't match target member names, you can configure full keys or member name key parts to use instead. For example, this source dictionary: -```C# +```cs var source = new Dictionary { ["ContactName"] = "Steve", @@ -15,7 +15,7 @@ var source = new Dictionary ...can be configured to map to a `ContactDetails` object like so: -```C# +```cs Mapper.WhenMapping .FromDictionaries .To() @@ -30,7 +30,7 @@ Mapper.WhenMapping If the parts of nested member names in your source dictionary keys aren't separated with dots, you can configure what to use instead. For example, this source dictionary: -```C# +```cs var source = new Dictionary { ["Name"] = "Steve", @@ -41,7 +41,7 @@ var source = new Dictionary ...uses '-' to separate member name parts, and can be configured to map to `ContactDetails` like so: -```C# +```cs Mapper.WhenMapping .FromDictionaries .To() // Optional @@ -52,7 +52,7 @@ The `To()` line in this examples is optional - excluding it sets To map an object to a dictionary without using separators, use: -```C# +```cs Mapper.WhenMapping .From() .ToDictionaries @@ -65,7 +65,7 @@ Mapper.WhenMapping If your keys don't have enumerable member element indexes formatted as '[i]', you can configure the pattern to use instead. For example, this source dictionary: -```C# +```cs var source = new Dictionary { ["Name"] = "Steve", @@ -76,7 +76,7 @@ var source = new Dictionary ...can be configured to map to `ContactDetails` like so: -```C# +```cs Mapper.WhenMapping .FromDictionaries .To() @@ -93,7 +93,7 @@ All configurations which can be applied to non-dictionary sources can be applied A dictionary can be configured to map to various derived types based on a configured condition. For example, this source dictionary: -```C# +```cs var source = new Dictionary { ["[0].Name"] = "Fido", @@ -109,7 +109,7 @@ var source = new Dictionary Can be configured to map to an `Animal`, `Dog : Animal`, `Cat : Animal` hierarchy like so: -```C# +```cs Mapper.WhenMapping .FromDictionaries .To() @@ -128,7 +128,7 @@ var animals = Mapper.Map(source).ToANew>(); Custom conditions can be configured which must be satisfied for a member to be mapped. For example: -```C# +```cs Mapper.WhenMapping .FromDictionaries .To() diff --git a/docs/src/Dictionary-Mapping.md b/docs/src/Dictionary-Mapping.md index f3dea86a3..4cb33a025 100644 --- a/docs/src/Dictionary-Mapping.md +++ b/docs/src/Dictionary-Mapping.md @@ -11,7 +11,7 @@ AgileMapper has extensive support for mapping to and from Dictionaries. Out of t For example, the following target type: -```C# +```cs public class ContactDetails { public string Name { get; set; } @@ -27,7 +27,7 @@ public class Address ...can be mapped from the following source dictionary: -```C# +```cs var source = new Dictionary { ["Name"] = "Steve", @@ -58,7 +58,7 @@ Note that the `StreetName` key had no separator, but the mapping works anyway. The following source `ContactDetails`: -```C# +```cs var source = new ContactDetails { Name = "Bob", @@ -73,7 +73,7 @@ var source = new ContactDetails ...can be mapped to a dictionary: -```C# +```cs var dictionary = Mapper.Map(source).ToANew>(); // or: var dictionaryInterface = Mapper.Map(source).ToANew>(); diff --git a/docs/src/Dynamic-Mapping-Configuration.md b/docs/src/Dynamic-Mapping-Configuration.md index a535720c5..048eb6146 100644 --- a/docs/src/Dynamic-Mapping-Configuration.md +++ b/docs/src/Dynamic-Mapping-Configuration.md @@ -4,7 +4,7 @@ If your source ExpandoObject member names don't match target member names, you can configure full names or name parts to use instead. For example, this source ExpandoObject: -```C# +```cs dynamic source = new ExpandoObject(); source.ContactName = "Steve"; source.PhoneNums_0 = "01234 567890"; @@ -13,7 +13,7 @@ source.PhoneNums_1 = "07890 654321"; ...can be configured to map to a `ContactDetails` object like so: -```C# +```cs Mapper.WhenMapping .FromDynamics .To() @@ -28,7 +28,7 @@ Mapper.WhenMapping If the parts of nested member names in your source ExpandoObject aren't separated with underscores, you can configure what to use instead. For example, this source ExpandoObject: -```C# +```cs IDictionary source = new ExpandoObject(); source["Name"] = "Sandra"; source["Addresses_0-HouseNumber"] = "123"; @@ -37,7 +37,7 @@ source["Addresses_0-StreetName"] = "Dynamic Lane"; ...uses '-' to separate member name parts, and can be configured to map to `ContactDetails` like so: -```C# +```cs Mapper.WhenMapping .FromDynamics .To() // Optional @@ -48,7 +48,7 @@ The `To()` line in this examples is optional - excluding it sets To map an object to an ExpandoObject without using separators, use: -```C# +```cs Mapper.WhenMapping .From() .ToDynamics @@ -61,7 +61,7 @@ Mapper.WhenMapping If your member names don't have enumerable member element indexes formatted as '_i', you can configure the pattern to use instead. For example, this source ExpandoObject: -```C# +```cs dynamic source = new ExpandoObject(); source.Name = "Steve"; source.PhoneNumbers_0_ = "01234 567890"; @@ -70,7 +70,7 @@ source.PhoneNumbers_1_ = "07890 654321"; ...can be configured to map to `ContactDetails` like so: -```C# +```cs Mapper.WhenMapping .FromDynamics .To() @@ -87,7 +87,7 @@ All configurations which can be applied to non-ExpandoObject sources can be appl An ExpandoObject can be configured to map to various derived types based on a configured condition. For example, this source ExpandoObject: -```C# +```cs dynamic source = new ExpandoObject(); source._0_Name = "Fido"; source._0_Type = AnimalType.Dog; // enum value @@ -101,7 +101,7 @@ source._1_LovesCatnip = true; Can be configured to map to an `Animal`, `Dog : Animal`, `Cat : Animal` hierarchy like so: -```C# +```cs Mapper.WhenMapping .FromDynamics .To() @@ -122,7 +122,7 @@ The source ExpandoObject in this configuration - for example in `d["Type"]` - is Custom conditions can be configured which must be satisfied for a member to be mapped. For example: -```C# +```cs Mapper.WhenMapping .FromDynamics .To() diff --git a/docs/src/Dynamic-Mapping.md b/docs/src/Dynamic-Mapping.md index ec1d303ea..08df84fdf 100644 --- a/docs/src/Dynamic-Mapping.md +++ b/docs/src/Dynamic-Mapping.md @@ -12,7 +12,7 @@ Out of the box: For example, the following target type: -```C# +```cs public class Doctor { public string Name { get; set; } @@ -28,7 +28,7 @@ public class Specialty ...can be mapped from the following source ExpandoObject: -```C# +```cs dynamic source = new ExpandoObject(); source.Name = "Andy"; source.PhoneNumbers_0 = "01234 567890"; @@ -59,7 +59,7 @@ Note that the elements of the second `Specialty` have no separator, but the mapp The following source `Doctor`: -```C# +```cs var source = new Doctor { Name = "Bob", @@ -73,7 +73,7 @@ var source = new Doctor ...can be mapped to an ExpandoObject: -```C# +```cs dynamic expando = Mapper.Map(source).ToANew(); // or: dynamic result = Mapper.Map(source).ToANew(); diff --git a/docs/src/Entity-Mapping.md b/docs/src/Entity-Mapping.md index 6bc09c206..6c7602f0a 100644 --- a/docs/src/Entity-Mapping.md +++ b/docs/src/Entity-Mapping.md @@ -12,7 +12,7 @@ A nullable numeric member named **Id** will not be mapped to zero if For example: -```C# +```cs class CategoryDto { public int? Id { get; set; } diff --git a/docs/src/Enum-Mapping.md b/docs/src/Enum-Mapping.md index fba766097..4fce7868b 100644 --- a/docs/src/Enum-Mapping.md +++ b/docs/src/Enum-Mapping.md @@ -11,7 +11,7 @@ Flags enums are mapped automatically from numeric, string, enum and character so [Mapping plans](Using-Execution-Plans) warn you of enum mapping mismatches when mapping from one enum type to another. For example, a mapping between the following enums: -```C# +```cs // Source enum: enum PaymentTypeUs { Cash, Card, Check } // Target enum: @@ -20,7 +20,7 @@ enum PaymentTypeUk { Cash, Card, Cheque } ...has the following warning in its mapping plan: -```C# +```cs // WARNING - enum mismatches mapping PaymentTypeUs to PaymentTypeUk: // - PaymentTypeUs.Check matches no PaymentTypeUk ``` @@ -31,7 +31,7 @@ enum PaymentTypeUk { Cash, Card, Cheque } To have `PaymentTypeUs.Check` map to `PaymentTypeUk.Cheque`, use: -```C# +```cs Mapper.WhenMapping .PairEnum(PaymentTypeUs.Check).With(PaymentTypeUk.Cheque); ``` @@ -40,7 +40,7 @@ Mapper.WhenMapping Enum pairing can also be configured [inline](Inline-Configuration): -```C# +```cs Mapper.Map(usTransaction).ToANew(cfg => cfg .PairEnum(PaymentTypeUs.Check).With(PaymentTypeUk.Cheque)); ``` \ No newline at end of file diff --git a/docs/src/Ignoring-Target-Members.md b/docs/src/Ignoring-Target-Members.md index 94cacb29c..4c26c7574 100644 --- a/docs/src/Ignoring-Target-Members.md +++ b/docs/src/Ignoring-Target-Members.md @@ -1,6 +1,6 @@ Target members which have no [matching](Member-Matching), [compatible](Type-Conversion) source member are ignored by default, but you can also tell a mapper to ignore members which would usually be mapped. For example: -```C# +```cs public class OrderDto { public int Id { get; set; } @@ -15,7 +15,7 @@ public class Order `Order.DateCreated` will be ignored because `OrderDto` has no matching member, but out of the box the `Id` property will be updated. You can stop this using: -```C# +```cs Mapper.WhenMapping .From() // Apply when mapping from OrderDto (optional) .To() // Apply the ignore to Order creation, updates and merges @@ -24,7 +24,7 @@ Mapper.WhenMapping Multiple fields can be ignored with a single configuration, and ignores can be made conditional. Here's an [inline configuration](Inline-Configuration) example: -```C# +```cs // Source, target and mapping types are implicit from the mapping: Mapper .Map(orderDto).Over(order, cfg => cfg @@ -40,7 +40,7 @@ Target members can be ignored in several other ways, either globally (for all so You can ignore members by Type: -```C# +```cs Mapper.WhenMapping .IgnoreTargetMembersOfType(); // Global ignore @@ -52,7 +52,7 @@ Mapper.WhenMapping ...by member type: -```C# +```cs Mapper.WhenMapping .IgnoreTargetMembersWhere(m => m.IsSetMethod); // Global ignore @@ -68,7 +68,7 @@ Mapper.WhenMapping ...by member name: -```C# +```cs Mapper.WhenMapping .IgnoreTargetMembersWhere(m => m.Name.Contains("NOPE")); // Global ignore @@ -79,7 +79,7 @@ Mapper.WhenMapping ...by Attribute: -```C# +```cs Mapper.WhenMapping .IgnoreTargetMembersWhere(m => m.HasAttribute()); // Global ignore @@ -92,7 +92,7 @@ Mapper.WhenMapping ...by member path: -```C# +```cs Mapper.WhenMapping .IgnoreTargetMembersWhere(m => m.Path.Contains("Customer.Address")); // Global ignore @@ -105,7 +105,7 @@ Mapper.WhenMapping ...or by `MemberInfo` matcher: -```C# +```cs Mapper.WhenMapping .IgnoreTargetMembersWhere(m => m.IsFieldMatching(f => f.IsAssembly)); // Global ignore diff --git a/docs/src/Inline-Configuration.md b/docs/src/Inline-Configuration.md index 32739df0a..e53f341a1 100644 --- a/docs/src/Inline-Configuration.md +++ b/docs/src/Inline-Configuration.md @@ -1,6 +1,6 @@ To supply some or all of a configuration inline - at the point the mapping is performed - use: -```C# +```cs var dto = mapper .Map(product).ToANew(cfg => cfg .Map((p, d) => p.Spec).To(d => d.Specification)); @@ -8,7 +8,7 @@ var dto = mapper ...which also works in [query projections](Query-Projection), for example: -```C# +```cs var dto = await context .Products .Project().To(cfg => cfg @@ -18,7 +18,7 @@ var dto = await context To supply multiple lines of configuration, use: -```C# +```cs var dto = mapper .Map(product).ToANew(cfg => cfg .Map((p, d) => p.Spec).To(d => d.Specification) @@ -34,7 +34,7 @@ var dto = mapper To combine mapper configuration with inline configuration, use: -```C# +```cs // Configuration in app startup code: mapper.WhenMapping .From().To() @@ -52,7 +52,7 @@ Inline configuration can be supplied via the [static](Static-vs-Instance-Mappers If inline configuration is invalid, a `MappingConfigurationException` will be thrown when the mapping is attempted. For example: -```C# +```cs // Supply two different sources for ProductDto.Specification; // throws an Exception! var dto = mapper @@ -70,7 +70,7 @@ The first time an inline-configured mapping is performed, the mapper's configura Finding the combined configuration for subsequent mappings incurs a [very] small performance penalty. For example, in the following mapping: -```C# +```cs public class Product { public string Spec { get; set; } diff --git a/docs/src/Join-Entities.md b/docs/src/Join-Entities.md index b3d2c4499..9dd557817 100644 --- a/docs/src/Join-Entities.md +++ b/docs/src/Join-Entities.md @@ -1,6 +1,6 @@ Many-to-many relationships are sometimes (_e.g._ [EF Core 2](https://www.learnentityframeworkcore.com/configuration/many-to-many-relationship-configuration)) modelled using a joining type which joins one set of entities to another. For example: -```C# +```cs class Course { [Key] @@ -31,7 +31,7 @@ class CourseStudent Often when projecting from entities to other types, we don't want the join entity, we want the _joined_ entity. For example: -```C# +```cs class CourseDto { public ICollection Students { get; set; } diff --git a/docs/src/Mapped-Object-Tracking.md b/docs/src/Mapped-Object-Tracking.md index 4b5b52b92..ab151555e 100644 --- a/docs/src/Mapped-Object-Tracking.md +++ b/docs/src/Mapped-Object-Tracking.md @@ -4,7 +4,7 @@ There are two circumstances in which you might want to keep track of mapped obje To avoid stack overflows, objects are automatically tracked when mapping circular references. If you know your object tree doesn't contain a circular reference, you can switch this behaviour off. For example: -```C# +```cs var child = new Child(); var parent = new Parent(); child.Parent = parent; @@ -25,7 +25,7 @@ Mapper.Map(child).ToANew(cfg => cfg.DisableObjectTracking()); If you want to maintain a 1-to-1 relationship between source and destination objects, you can switch on identity integrity, which uses object tracking. For example: -```C# +```cs var person = new Person(); // use the same instance twice in a source array: var people = new[] { person, person }; @@ -43,7 +43,7 @@ var dtos2 = Mapper To switch object tracking off - or identity integrity on - in all mappings, use: -```C# +```cs // Never track objects - when your object *types* contain circular references, // but you're sure your *instances* of those types never do: Mapper.WhenMapping.DisableObjectTracking(); diff --git a/docs/src/Mapping-Extension-Methods.md b/docs/src/Mapping-Extension-Methods.md index f2d017427..6cea0e21d 100644 --- a/docs/src/Mapping-Extension-Methods.md +++ b/docs/src/Mapping-Extension-Methods.md @@ -1,12 +1,12 @@ If you include: -```C# +```cs using AgileObjects.AgileMapper.Extensions; ``` ...mapping can be performed via extension methods. For example: -```C# +```cs // Create a new CustomerViewModel from a Customer: var customerViewModel = customer.Map().ToANew(); @@ -24,7 +24,7 @@ customerDto.Map().OnTo(customer); Mappings performed via these extension methods use the default mapper - the same one you map with via the [static Mapper API](Static-vs-Instance-Mappers). To use an instance mapper with an extension method, use: -```C# +```cs // Deep-clone a Customer using // the given instance-scoped mapper: var clonedCustomer = customer @@ -43,7 +43,7 @@ customerSaveRequest You can also configure extension-method mappings inline, for example: -```C# +```cs var customerSaveRequest = customerDto.Map().ToANew(cfg => cfg .Map((dto, csr) => dto.Id) .To(csr => csr.CustomerId)); @@ -51,7 +51,7 @@ var customerSaveRequest = customerDto.Map().ToANew(cfg => c ...and combine that with an instance-scoped mapper, for example: -```C# +```cs customerSaveRequest .MapUsing(instanceMapper) .Over(customer, cfg => cfg diff --git a/docs/src/Member-Matching.md b/docs/src/Member-Matching.md index 522115194..e6cf938a8 100644 --- a/docs/src/Member-Matching.md +++ b/docs/src/Member-Matching.md @@ -9,7 +9,7 @@ By default: For example: -```C# +```cs public class CustomerViewModel { public string Name { get; set; } diff --git a/docs/src/Meta-Members.md b/docs/src/Meta-Members.md index b8b840dee..c0e9d72e7 100644 --- a/docs/src/Meta-Members.md +++ b/docs/src/Meta-Members.md @@ -1,6 +1,6 @@ With the following Types: -```C# +```cs class Account { public int Id { get; set; } diff --git a/docs/src/Null-Results.md b/docs/src/Null-Results.md index b6b4149ad..1d2abcdc7 100644 --- a/docs/src/Null-Results.md +++ b/docs/src/Null-Results.md @@ -2,7 +2,7 @@ If a target complex type member has no [matching source member](Member-Matching) For example: -```C# +```cs var source = new { Name = "Frank" }; var target = new Person { Name = "Charlie", Address = default(Address) }; Mapper.Map(source).Over(target); @@ -12,7 +12,7 @@ Mapper.Map(source).Over(target); To configure a condition under which a complex type mapping should return null instead of an instantiated object, use (e.g.): -```C# +```cs Mapper.WhenMapping .ToANew
() .If((o, a) => diff --git a/docs/src/Object-Flattening.md b/docs/src/Object-Flattening.md index 8e5586d1c..5a01aee50 100644 --- a/docs/src/Object-Flattening.md +++ b/docs/src/Object-Flattening.md @@ -6,7 +6,7 @@ AgileMapper matches flattened member names [as you'd expect](Member-Matching), b Flattening produces an object including all the source object's string or value-type members. For example: -```C# +```cs var customer = new Customer { Name = "Mrs Customer", @@ -21,7 +21,7 @@ var customer = new Customer ...can be flattened to a Dictionary using: -```C# +```cs var flat = Mapper.Flatten(myObject).ToDictionary(); // flat is a Dictionary containing: // ["Name"] = "Mrs Customer" @@ -32,7 +32,7 @@ var flat = Mapper.Flatten(myObject).ToDictionary(); ...or a dynamic using: -```C# +```cs dynamic flat = myInstanceMapper.Flatten(myObject).ToDynamic(); // flat is an ExpandoObject with members: // flat.Name = "Mrs Customer" @@ -43,7 +43,7 @@ dynamic flat = myInstanceMapper.Flatten(myObject).ToDynamic(); ...or a query string-formatted string using: -```C# +```cs var flat = myObject.Flatten().ToQueryString(); // flat is a query-string-formatted string with: // Name=Mrs%20Customer diff --git a/docs/src/Object-Unflattening.md b/docs/src/Object-Unflattening.md index 69c38c3bd..fd71633ca 100644 --- a/docs/src/Object-Unflattening.md +++ b/docs/src/Object-Unflattening.md @@ -8,7 +8,7 @@ Unflattening produces an object populated using the source's [flattened](Object- For example, this Dictionary: -```C# +```cs var dictionary = new Dictionary { ["Name"] = "Mrs Customer" @@ -20,7 +20,7 @@ var dictionary = new Dictionary ...and the `QueryString` object created from this string-formatted string: -```C# +```cs var queryString = "Name=Mrs%20Customer" + "&Dob=11%2F5%2F1985%2012%3A00%3A00%20AM" + @@ -31,7 +31,7 @@ var queryString = ...can both be unflattened to this `Customer` object: -```C# +```cs var customer = new Customer { diff --git a/docs/src/Pairing-Derived-Types.md b/docs/src/Pairing-Derived-Types.md index eb3242d08..d464f581a 100644 --- a/docs/src/Pairing-Derived-Types.md +++ b/docs/src/Pairing-Derived-Types.md @@ -2,7 +2,7 @@ Derived type pairing matches particular derived sources types to particular deri For example: -```C# +```cs Mapper.WhenMapping .From() // Apply to AnimalViewModel mappings .ToANew() // Apply to Animal creation only @@ -12,7 +12,7 @@ Mapper.WhenMapping Type pairs are used when mapping complex types: -```C# +```cs var animalViewModel = new CanineViewModel() as AnimalViewModel; var animal = Mapper.Map(animalViewModel).ToANew(); // animal is of type Dog @@ -20,7 +20,7 @@ var animal = Mapper.Map(animalViewModel).ToANew(); ...and collections: -```C# +```cs var animalViewModels = new[] { new AnimalViewModel(), @@ -33,7 +33,7 @@ var animals = Mapper.Map(animalViewModels).ToANew>(); ...and can be applied conditionally ([inline](Inline-Configuration) example): -```C# +```cs Mapper .Map(animalViewModels).ToANew(cfg => cfg .WhenMapping diff --git a/docs/src/Performing-Merges.md b/docs/src/Performing-Merges.md index 2507db25b..5cfb37973 100644 --- a/docs/src/Performing-Merges.md +++ b/docs/src/Performing-Merges.md @@ -1,12 +1,12 @@ Update an object's unpopulated members with values from another using: -```C# +```cs Mapper.Map(customerViewModel).OnTo(customer); ``` When merging collections, objects are matched by id ([configurable](Configuring-Object-Identifiers) if necessary). For example: -```C# +```cs var source = new Collection { new CustomerViewModel { Id = 1, Name = "Rod" }, diff --git a/docs/src/Performing-Updates.md b/docs/src/Performing-Updates.md index 281347178..9f6be6d65 100644 --- a/docs/src/Performing-Updates.md +++ b/docs/src/Performing-Updates.md @@ -1,12 +1,12 @@ Update an object's members with values from another using: -```C# +```cs Mapper.Map(customerViewModel).Over(customer); ``` When updating a collection, objects are matched by id ([configurable](Configuring-Object-Identifiers) if necessary). For example: -```C# +```cs var source = new[] { new CustomerViewModel { Id = 1, Name = "Rod" }, diff --git a/docs/src/Projecting-Recursive-Relationships.md b/docs/src/Projecting-Recursive-Relationships.md index fb5a93d29..17d284320 100644 --- a/docs/src/Projecting-Recursive-Relationships.md +++ b/docs/src/Projecting-Recursive-Relationships.md @@ -1,6 +1,6 @@ If your [`IQueryProvider`](https://docs.microsoft.com/en-us/dotnet/api/system.linq.iqueryprovider) [supports](Entity-Framework#recursion) it, you can project recursive relationships to a specified depth. For example, with these classes: -```C# +```cs // Entity: public class Category { @@ -49,7 +49,7 @@ public class CategoryDto To project a particular node of the tree to DTOs, the mapper has to know up-front how many levels deep you want to go in the tree. For example, without a specified recursion depth: -```C# +```cs // Using an EF Core DbContext: var stringsDto = await context .Categories @@ -63,7 +63,7 @@ var stringsDto = await context ...or with a recursion depth of 1: -```C# +```cs var stringsDto = await context .Categories .Project().To(cfg => cfg.RecurseToDepth(1)) @@ -78,7 +78,7 @@ var stringsDto = await context ...or with a recursion depth of 2: -```C# +```cs var stringsDto = await context .Categories .Project().To(cfg => cfg.RecurseToDepth(2)) diff --git a/docs/src/Projecting-to-Derived-Types.md b/docs/src/Projecting-to-Derived-Types.md index 7ef33e6d5..790a8aef4 100644 --- a/docs/src/Projecting-to-Derived-Types.md +++ b/docs/src/Projecting-to-Derived-Types.md @@ -1,6 +1,6 @@ If your [`IQueryProvider`](https://docs.microsoft.com/en-us/dotnet/api/system.linq.iqueryprovider) [supports](Entity-Framework#derived-types) casting projected instances to a base Type, you can project to derived Types via configured conditions. For example: -```C# +```cs // Using an EF Core DbContext: var animalDtos = await context .Animals diff --git a/docs/src/Query-Projection-Configuration.md b/docs/src/Query-Projection-Configuration.md index c58e6c3b6..429eb5494 100644 --- a/docs/src/Query-Projection-Configuration.md +++ b/docs/src/Query-Projection-Configuration.md @@ -4,7 +4,7 @@ For example: -```C# +```cs // Configured on the default mapper, via the static API: Mapper.WhenMapping .From() // Apply to Product mappings @@ -26,7 +26,7 @@ In this case, the `Product.Spec` -> `ProductDto.Specification` custom [member va You can achieve the same thing using an instance mapper by using `.ProjectUsing(mapper)` instead of `.Project()`. Any inline configuration you supply will be merged with the instance mapper's configuration in the usual way. For example: -```C# +```cs // Configure an instance mapper via its API: mapper.WhenMapping .From() // Apply to Product mappings diff --git a/docs/src/Query-Projection.md b/docs/src/Query-Projection.md index b7413e569..43a09b7e2 100644 --- a/docs/src/Query-Projection.md +++ b/docs/src/Query-Projection.md @@ -4,7 +4,7 @@ Query projection supports a subset of regular mapping [configuration](Query-Proj To project a query, use: -```C# +```cs // Using an EF Core DbContext: var orderDtos = await context .Orders @@ -14,7 +14,7 @@ var orderDtos = await context `.Project()` uses the default mapper - the one used behind the scenes by the [static](Static-vs-Instance-Mappers) `Mapper` API. To project a query using an instance-scoped mapper, use: -```C# +```cs var orderDtos = await context .Orders .ProjectUsing(mapper).To() @@ -27,7 +27,7 @@ The [plan](Using-Execution-Plans) for a query projection can be viewed and cache For example: -```C# +```cs // Cache the plan to project a Person to a PersonDto; Mapper.GetPlanForProjecting(context.People).To(); ``` \ No newline at end of file diff --git a/docs/src/Static-vs-Instance-Mappers.md b/docs/src/Static-vs-Instance-Mappers.md index e1234d206..e11a4b833 100644 --- a/docs/src/Static-vs-Instance-Mappers.md +++ b/docs/src/Static-vs-Instance-Mappers.md @@ -4,7 +4,7 @@ AgileMapper provides the same API in both instance and static scope, so you can Use the static API via static methods on the `Mapper` class, for example: -```C# +```cs // Configuration - done once at start-up: Mapper.WhenMapping .From() @@ -18,7 +18,7 @@ var orderDto = Mapper.Map(order).ToANew(); To re-run static Mapper configuration - for example in testing scenarios - use: -```C# +```cs // Clears configuration and cached objects: Mapper.ResetDefaultInstance(); ``` @@ -29,7 +29,7 @@ Using the static API enables mapping in less flexible scenarios where you aren't Use the instance API via instance methods on an [`IMapper`](/agileobjects/AgileMapper/blob/master/AgileMapper/IMapper.cs) object, for example: -```C# +```cs // Configuration - done once at start-up: var mapper = Mapper.CreateNew(); mapper.WhenMapping @@ -44,7 +44,7 @@ var orderDto = mapper.Map(order).ToANew(); Using the instance API enables injection of a mapper via the `IMapper` interface, which emphasises object composition, declares the mapper as a dependency, and means you can swap in a mock mapper during testing if required. It also enables use of mappers with different configurations in different scenarios, for example, setting this up via a StructureMap registry: -```C# +```cs public class OrderMapperRegistry : Registry { public OrderMapperRegistry() diff --git a/docs/src/To-String-Formatting.md b/docs/src/To-String-Formatting.md index 991956a5d..835ad8073 100644 --- a/docs/src/To-String-Formatting.md +++ b/docs/src/To-String-Formatting.md @@ -1,6 +1,6 @@ Custom formatting strings can be configured for given source types: -```C# +```cs // Map DateTimes to string as ' ' Mapper.WhenMapping .StringsFrom(_ => _.UseFormat("y")); diff --git a/docs/src/Type-Conversion.md b/docs/src/Type-Conversion.md index fa322c91c..686eacf61 100644 --- a/docs/src/Type-Conversion.md +++ b/docs/src/Type-Conversion.md @@ -13,7 +13,7 @@ Value conversion is performed according to the following: - Enum values are parsed using a nested ternary operation with one branch per potential source enum value, e.g. -```C# +```cs target.EnumValue = source.Enum == SourceStatus.Complete ? TargetStatus.Complete : source.Enum == SourceStatus.InProgress diff --git a/docs/src/Using-Execution-Plans.md b/docs/src/Using-Execution-Plans.md index 3f932919f..7db20a50e 100644 --- a/docs/src/Using-Execution-Plans.md +++ b/docs/src/Using-Execution-Plans.md @@ -4,7 +4,7 @@ Mappings are performed by creating an [expression tree](https://msdn.microsoft.c To cache an execution plan, use: -```C# +```cs // Cache the plan to map a PersonViewModel to a new instance of a Person: Mapper.GetPlanFor().ToANew(); @@ -40,13 +40,13 @@ Viewing an execution plan can help you: To view a plan, assign the result of the call to an explicitly-typed string variable and view it in the debugger: -```C# +```cs string plan = Mapper.GetPlanFor().ToANew(); ``` To view all the plans cached in a mapper, use: -```C# +```cs Mapper.GetPlansFor.ToANew(); Mapper.GetPlansFor.To(); diff --git a/docs/src/Validating-Mappings.md b/docs/src/Validating-Mappings.md index 4f22cd2c1..28e850dea 100644 --- a/docs/src/Validating-Mappings.md +++ b/docs/src/Validating-Mappings.md @@ -10,7 +10,7 @@ Mapping plan validation is intended to be used during development to make sure n To validate that a mapping plan created on-the-fly is complete, use: -```C# +```cs mapper .Map(customerDto).Over(customer, cfg => cfg .ThrowNowIfMappingPlanIsIncomplete()); @@ -27,7 +27,7 @@ mapper To validate all cached mapping plans, use: -```C# +```cs // Cache the mapping plans you want to use later: mapper.GetPlansFor().To(); mapper.GetPlanFor().ToANew(); @@ -42,7 +42,7 @@ mapper.ThrowNowIfAnyMappingPlanIsIncomplete(); To configure a mapper to validate mapping plans by default, use: -```C# +```cs Mapper.WhenMapping.ThrowIfAnyMappingPlanIsIncomplete(); // All throw if the plan is incomplete: diff --git a/docs/src/index.md b/docs/src/index.md index 1fd19b65f..bd2583691 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -16,7 +16,7 @@ Mapping functions are created and cached the first time two types are mapped - n Create an object from another using: -```C# +```cs var customer = Mapper.Map(customerViewModel).ToANew(); // Or: var customer = customerViewModel.Map().ToANew(); @@ -26,7 +26,7 @@ var customer = customerViewModel.Map().ToANew(); [Project](Query-Projection) entities to another Type using: -```C# +```cs var customerVm = await dbContext .Customers .Project().To() @@ -37,7 +37,7 @@ var customerVm = await dbContext Deep-clone an object using: -```C# +```cs var clonedCustomer = Mapper.DeepClone(customerToBeCloned); // Or: var clonedCustomer = customerToBeCloned.DeepClone(); @@ -47,7 +47,7 @@ var clonedCustomer = customerToBeCloned.DeepClone(); [Update](Performing-Updates) an object's members with values from another using: -```C# +```cs Mapper.Map(customerSaveRequest).Over(customer); // Or: customerSaveRequest.Map().Over(customer); @@ -57,7 +57,7 @@ customerSaveRequest.Map().Over(customer); [Merge](Performing-Merges) an object's unpopulated members with values from another using: -```C# +```cs Mapper.Map(customerDto).OnTo(customer); // Or: customerDto.Map().OnTo(customer); @@ -67,7 +67,7 @@ customerDto.Map().OnTo(customer); View an [execution plan](Using-Execution-Plans) to see how two object types will be mapped; this also caches the plan, so you can use it to choose when to incur that cost. Use: -```C# +```cs // For object creation: string mappingPlan = Mapper.GetPlanFor().ToANew(); // For updates: diff --git a/mkdocs.yml b/mkdocs.yml index 1b7c3316d..2c479c1f5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,6 +4,8 @@ site_description: 'AgileMapper: A zero-configuration, highly-configurable object site_author: Steve Wilkes docs_dir: 'docs/src' site_dir: 'docs/site' +extra_css: + - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.13.1/styles/vs2015.min.css nav: - Home: index.md - Member matching: Member-Matching.md From ac0b80e43258c91d1054975f93793b8fe231b12a Mon Sep 17 00:00:00 2001 From: Steve Wilkes Date: Tue, 27 Nov 2018 15:21:03 +0000 Subject: [PATCH 2/2] Organising docs Adding custom styles --- docs/src/Collections.md | 6 +- docs/src/Configuration.md | 14 --- docs/src/Configuring-Object-Identifiers.md | 24 ----- docs/src/Derived-Types.md | 4 +- docs/src/Dictionary-Mapping.md | 10 +- docs/src/Dynamic-Mapping.md | 10 +- docs/src/Entity-Mapping.md | 2 +- docs/src/Enum-Mapping.md | 6 +- docs/src/Mapping-Extension-Methods.md | 2 +- docs/src/Member-Matching.md | 4 +- docs/src/Meta-Members.md | 2 +- docs/src/Object-Construction.md | 10 +- docs/src/Object-Flattening.md | 6 +- docs/src/Object-Unflattening.md | 8 +- docs/src/Performing-Merges.md | 2 +- docs/src/Performing-Updates.md | 2 +- docs/src/Static-vs-Instance-Mappers.md | 2 +- docs/src/Type-Conversion.md | 4 +- docs/src/Validating-Mappings.md | 8 +- .../{ => configuration}/Assembly-Scanning.md | 0 .../Classes.md} | 6 +- .../{ => configuration}/Cloning-Mappers.md | 0 .../Constructor-Arguments.md} | 6 +- .../Dependency-Injection.md | 4 +- .../Dictionary-Mapping.md} | 2 +- .../Dynamic-Mapping.md} | 2 +- .../Exception-Handling.md} | 2 +- .../Ignoring-Target-Members.md | 6 +- .../Inline.md} | 4 +- .../Mapping-Callbacks.md} | 0 .../Member-Name-Patterns.md} | 4 +- .../Member-Values.md} | 8 +- docs/src/{ => configuration}/Null-Results.md | 2 +- .../Object-Construction.md} | 2 +- docs/src/configuration/Object-Identifiers.md | 23 +++++ .../Pairing-Derived-Types.md | 6 +- .../To-String-Formatting.md | 0 docs/src/configuration/index.md | 14 +++ docs/src/css/styles.css | 54 +++++++++++ docs/src/index.md | 14 +-- .../Configuration.md} | 22 ++--- .../Derived-Types.md} | 2 +- .../Entity-Framework.md | 6 +- .../{ => query-projection}/Join-Entities.md | 0 .../Recursive-Relationships.md} | 4 +- .../index.md} | 6 +- mkdocs.yml | 96 ++++++++++--------- 47 files changed, 239 insertions(+), 182 deletions(-) delete mode 100644 docs/src/Configuration.md delete mode 100644 docs/src/Configuring-Object-Identifiers.md rename docs/src/{ => configuration}/Assembly-Scanning.md (100%) rename docs/src/{Configuration-Classes.md => configuration/Classes.md} (95%) rename docs/src/{ => configuration}/Cloning-Mappers.md (100%) rename docs/src/{Configuring-Constructor-Arguments.md => configuration/Constructor-Arguments.md} (80%) rename docs/src/{ => configuration}/Dependency-Injection.md (92%) rename docs/src/{Dictionary-Mapping-Configuration.md => configuration/Dictionary-Mapping.md} (95%) rename docs/src/{Dynamic-Mapping-Configuration.md => configuration/Dynamic-Mapping.md} (96%) rename docs/src/{Configuring-Exception-Handling.md => configuration/Exception-Handling.md} (82%) rename docs/src/{ => configuration}/Ignoring-Target-Members.md (90%) rename docs/src/{Inline-Configuration.md => configuration/Inline.md} (93%) rename docs/src/{Configuring-Mapping-Callbacks.md => configuration/Mapping-Callbacks.md} (100%) rename docs/src/{Configuring-Member-Name-Patterns.md => configuration/Member-Name-Patterns.md} (86%) rename docs/src/{Configuring-Member-Values.md => configuration/Member-Values.md} (94%) rename docs/src/{ => configuration}/Null-Results.md (82%) rename docs/src/{Configuring-Object-Construction.md => configuration/Object-Construction.md} (91%) create mode 100644 docs/src/configuration/Object-Identifiers.md rename docs/src/{ => configuration}/Pairing-Derived-Types.md (79%) rename docs/src/{ => configuration}/To-String-Formatting.md (100%) create mode 100644 docs/src/configuration/index.md create mode 100644 docs/src/css/styles.css rename docs/src/{Query-Projection-Configuration.md => query-projection/Configuration.md} (62%) rename docs/src/{Projecting-to-Derived-Types.md => query-projection/Derived-Types.md} (76%) rename docs/src/{ => query-projection}/Entity-Framework.md (96%) rename docs/src/{ => query-projection}/Join-Entities.md (100%) rename docs/src/{Projecting-Recursive-Relationships.md => query-projection/Recursive-Relationships.md} (84%) rename docs/src/{Query-Projection.md => query-projection/index.md} (64%) diff --git a/docs/src/Collections.md b/docs/src/Collections.md index 3e4aacf9b..774b0291a 100644 --- a/docs/src/Collections.md +++ b/docs/src/Collections.md @@ -12,12 +12,12 @@ The following collection types are supported by default: - `Collection` - `HashSet` - `ISet` -- [`Dictionary`](Dictionary-Mapping) -- [`IDictionary`](Dictionary-Mapping) +- [`Dictionary`](/Dictionary-Mapping) +- [`IDictionary`](/Dictionary-Mapping) Generic `List` instances are created for interface-type members except `ISet`, which uses a `HashSet`. If a member is already populated with a non-readonly collection (e.g. an array), the existing object will be reused. -[Updates](Performing-Updates) and [merges](Performing-Merges) of collections of identifiable objects (i.e. Entities) are performed in an id-aware manner. +[Updates](/Performing-Updates) and [merges](/Performing-Merges) of collections of identifiable objects (i.e. Entities) are performed in an id-aware manner. ## Null Source Collections diff --git a/docs/src/Configuration.md b/docs/src/Configuration.md deleted file mode 100644 index 1ef45757b..000000000 --- a/docs/src/Configuration.md +++ /dev/null @@ -1,14 +0,0 @@ -Many aspects of mapping can be configured, but no up-front type registration is required - a mapping function is created and cached the first time two types are mapped. - -Various configuration options are available: - -- [Static](Static-vs-Instance-Mappers) configuration (`Mapper.WhenMapping`) configures a default, instance-scoped mapper behind the scenes. This configures the mapper used when you call `Mapper.Map(source)` - -- [Instance](Static-vs-Instance-Mappers) configuration (`mapper.WhenMapping`) configures that particular instance - -- [Inline](Inline-configuration) configuration combines the configuration of the mapper performing the mapping with the inline configuration you supply - -- [Class](Configuration-Classes) configuration splits configuration up into dedicated configuration classes. - -The same API is available in all four contexts. - diff --git a/docs/src/Configuring-Object-Identifiers.md b/docs/src/Configuring-Object-Identifiers.md deleted file mode 100644 index 2216f2f9f..000000000 --- a/docs/src/Configuring-Object-Identifiers.md +++ /dev/null @@ -1,24 +0,0 @@ -Objects are identified during collection [updates](Performing-Updates) and [merges](Performing-Merges) using members with the following names: - -* `Id` -* `Id` -* `Identifier` -* `Identifier` - -You can configure an object to be uniquely identified with a different member using: - -```cs -Mapper.WhenMapping - .InstancesOf() // Apply to NamedCustomer mappings - .IdentifyUsing(c => c.Name); // Identify using NamedCustomer.Name -``` - -Or, configured [inline](Inline-Configuration): - -```cs -Mapper - .Map(customerDtos).ToANew(cfg => cfg - .WhenMapping - .InstancesOf() - .IdentifyUsing(c => c.Name)); // Identify using NamedCustomer.Name -``` \ No newline at end of file diff --git a/docs/src/Derived-Types.md b/docs/src/Derived-Types.md index abdb76266..89de45189 100644 --- a/docs/src/Derived-Types.md +++ b/docs/src/Derived-Types.md @@ -1,4 +1,4 @@ -For most cases, derived types are supported without configuration. +For many cases, derived type mapping is supported without configuration. For example, with the following classes: @@ -50,4 +50,4 @@ var resultAnimals = Mapper.Map(sourceAnimals).ToANew(); // resultAnimals[1] is of type DogDto ``` -In the second example above, the `Dog` -> `DogDto` and `Cat` -> `CatDto` types are paired by convention based on the names of the original `Animal` -> `AnimalDto` pairing. You can configure [type pairs](Pairing-Derived-Types) which don't have a consistent naming convention, and [in which assemblies](Assembly-Scanning) to look for derived types. \ No newline at end of file +In the second example above, the `Dog` -> `DogDto` and `Cat` -> `CatDto` types are paired by convention based on the names of the original `Animal` -> `AnimalDto` pairing. You can configure [type pairs](/configuration/Pairing-Derived-Types) which don't have a consistent naming convention, and [in which assemblies](/configuration/Assembly-Scanning) to look for derived types. \ No newline at end of file diff --git a/docs/src/Dictionary-Mapping.md b/docs/src/Dictionary-Mapping.md index 4cb33a025..e59cb5011 100644 --- a/docs/src/Dictionary-Mapping.md +++ b/docs/src/Dictionary-Mapping.md @@ -1,9 +1,9 @@ AgileMapper has extensive support for mapping to and from Dictionaries. Out of the box: * Only dictionaries with string keys are supported -* Dictionary keys must match target member names exactly, ignoring case ([configurable](Dictionary-Mapping-Configuration#configuring-keys)) -* Parent and child member names are matched to dictionary keys separated with a dot ([configurable](Dictionary-Mapping-Configuration#configuring-separators)), or flattened - with no separator -* Enumerable elements are matched to dictionary keys by their index inside square brackets ([configurable](Dictionary-Mapping-Configuration#configuring-element-indexes)) +* Dictionary keys must match target member names exactly, ignoring case ([configurable](/configuration/Dictionary-Mapping#configuring-keys)) +* Parent and child member names are matched to dictionary keys separated with a dot ([configurable](/configuration/Dictionary-Mapping#configuring-separators)), or flattened - with no separator +* Enumerable elements are matched to dictionary keys by their index inside square brackets ([configurable](/configuration/Dictionary-Mapping#configuring-element-indexes)) * Dictionaries can contain all or a mixture of value type values, collections and complex types - anything with a matching key is used * Target members with no matching key in the dictionary are ignored @@ -49,7 +49,7 @@ The created `contactDetails` will have the following property values: * "07890 654321" and * "01234 987654" * `Addresses` set to a new, 1-element `List
` containing an `Address`: - * With `HouseNumber` set to '123' ([parsed](Type-Conversion) from the string) + * With `HouseNumber` set to '123' ([parsed](/Type-Conversion) from the string) * With `StreetName` set to "Dictionary Street" Note that the `StreetName` key had no separator, but the mapping works anyway. @@ -91,4 +91,4 @@ The created `Dictionary` will have the following keys and values: ## Configuration -Dictionary mapping is [highly configurable](Dictionary-Mapping-Configuration). \ No newline at end of file +Dictionary mapping is [highly configurable](/configuration/Dictionary-Mapping). \ No newline at end of file diff --git a/docs/src/Dynamic-Mapping.md b/docs/src/Dynamic-Mapping.md index 08df84fdf..c0cb2d412 100644 --- a/docs/src/Dynamic-Mapping.md +++ b/docs/src/Dynamic-Mapping.md @@ -1,10 +1,10 @@ -AgileMapper's [dictionary mapping](Dictionary-Mapping) also applies to [ExpandoObject](https://docs.microsoft.com/en-us/dotnet/api/system.dynamic.expandoobject?view=netframework-4.7.1)s, which are mapped using their `IDictionary` interface. +AgileMapper's [dictionary mapping](/Dictionary-Mapping) also applies to [ExpandoObject](https://docs.microsoft.com/en-us/dotnet/api/system.dynamic.expandoobject?view=netframework-4.7.1)s, which are mapped using their `IDictionary` interface. Out of the box: -* Member names must match target member names exactly, ignoring case ([configurable](Dynamic-Mapping-Configuration#configuring-member-names)) -* Parent and child member names are matched to ExpandoObject member names separated with an underscore ([configurable](Dynamic-Mapping-Configuration#configuring-separators)), or flattened - with no separator -* Enumerable elements are matched to ExpandoObject member names by their index separated by underscores ([configurable](Dynamic-Mapping-Configuration#configuring-element-indexes)) +* Member names must match target member names exactly, ignoring case ([configurable](/configuration/Dynamic-Mapping#configuring-member-names)) +* Parent and child member names are matched to ExpandoObject member names separated with an underscore ([configurable](/configuration/Dynamic-Mapping#configuring-separators)), or flattened - with no separator +* Enumerable elements are matched to ExpandoObject member names by their index separated by underscores ([configurable](/configuration/Dynamic-Mapping#configuring-element-indexes)) * ExpandoObjects can contain all or a mixture of value type values, collections and complex types - anything with a matching member name is used * Target members with no matching member in the ExpandoObject are ignored @@ -89,4 +89,4 @@ The created `ExpandoObject` (in both cases) will have the following member names ## Configuration -Dynamic mapping is [highly configurable](Dynamic-Mapping-Configuration). \ No newline at end of file +Dynamic mapping is [highly configurable](/configuration/Dynamic-Mapping). \ No newline at end of file diff --git a/docs/src/Entity-Mapping.md b/docs/src/Entity-Mapping.md index 6c7602f0a..f99be9e09 100644 --- a/docs/src/Entity-Mapping.md +++ b/docs/src/Entity-Mapping.md @@ -4,7 +4,7 @@ Mapping to entities - an object with a member decorated with a [`KeyAttribute`]( Members decorated with a `KeyAttribute` are not mapped, unless the mapping is a deep clone. Entity key values are usually generated by a data store, and some ORMs will throw an exception if a key value is updated in code. -If you need to map to a `KeyAttribute` member, you can override this behaviour by configuring a [custom data source](Configuring-Member-Values). +If you need to map to a `KeyAttribute` member, you can override this behaviour by configuring a [custom data source](/configuration/Member-Values). ### Optional Related Entity Keys diff --git a/docs/src/Enum-Mapping.md b/docs/src/Enum-Mapping.md index 4fce7868b..2874538bb 100644 --- a/docs/src/Enum-Mapping.md +++ b/docs/src/Enum-Mapping.md @@ -9,7 +9,7 @@ Flags enums are mapped automatically from numeric, string, enum and character so ### Enum Mapping Mismatches -[Mapping plans](Using-Execution-Plans) warn you of enum mapping mismatches when mapping from one enum type to another. For example, a mapping between the following enums: +[Mapping plans](/Using-Execution-Plans) warn you of enum mapping mismatches when mapping from one enum type to another. For example, a mapping between the following enums: ```cs // Source enum: @@ -25,7 +25,7 @@ enum PaymentTypeUk { Cash, Card, Cheque } // - PaymentTypeUs.Check matches no PaymentTypeUk ``` -`PaymentTypeUk.Cheque` also mismatches, but the mapping is going from `PaymentTypeUs` -> `PaymentTypeUk`, and it only matters that all *source* values can be mapped to target values. This mismatch would cause an exception if you use [mapping validation](Validating-Mappings). +`PaymentTypeUk.Cheque` also mismatches, but the mapping is going from `PaymentTypeUs` -> `PaymentTypeUk`, and it only matters that all *source* values can be mapped to target values. This mismatch would cause an exception if you use [mapping validation](/Validating-Mappings). ## Configuring Enum Pairs @@ -38,7 +38,7 @@ Mapper.WhenMapping ...which removes the enum mapping mismatch warning from the mapping plan, and stops the validation exception. -Enum pairing can also be configured [inline](Inline-Configuration): +Enum pairing can also be configured [inline](/configuration/Inline): ```cs Mapper.Map(usTransaction).ToANew(cfg => cfg diff --git a/docs/src/Mapping-Extension-Methods.md b/docs/src/Mapping-Extension-Methods.md index 6cea0e21d..f134e1d42 100644 --- a/docs/src/Mapping-Extension-Methods.md +++ b/docs/src/Mapping-Extension-Methods.md @@ -22,7 +22,7 @@ customerDto.Map().OnTo(customer); ### Using an Instance-Scoped Mapper -Mappings performed via these extension methods use the default mapper - the same one you map with via the [static Mapper API](Static-vs-Instance-Mappers). To use an instance mapper with an extension method, use: +Mappings performed via these extension methods use the default mapper - the same one you map with via the [static Mapper API](/Static-vs-Instance-Mappers). To use an instance mapper with an extension method, use: ```cs // Deep-clone a Customer using diff --git a/docs/src/Member-Matching.md b/docs/src/Member-Matching.md index e6cf938a8..1af7d2d3a 100644 --- a/docs/src/Member-Matching.md +++ b/docs/src/Member-Matching.md @@ -1,7 +1,7 @@ By default: * Writable fields and properties, single-parameter methods prefixed with 'Set', constructor parameters and non-null, readonly complex type or enumerable members (except arrays) are targeted -* Target members are matched to [compatibly-typed](Type-Conversion) source members by name +* Target members are matched to [compatibly-typed](/Type-Conversion) source members by name * Source members prefixed with 'Get' are matched without the prefix - [`GetHashCode`](https://msdn.microsoft.com/en-us/library/system.object.gethashcode%28v=vs.100%29.aspx) and [`GetType`](https://msdn.microsoft.com/en-us/library/system.object.gettype(v=vs.100).aspx) are ignored * Members named `Id`, `Id`, `Identifier` or `Identifier` are matched * Target members with no compatible source member are ignored. @@ -37,7 +37,7 @@ public class Address When mapping `CustomerViewModel` to `Customer`: - `Customer.Name` is populated using `CustomerViewModel.Name` - - The `Customer.CustomerId` Guid is populated using the [parsed](Type-Conversion) `CustomerViewModel.Id` string + - The `Customer.CustomerId` Guid is populated using the [parsed](/Type-Conversion) `CustomerViewModel.Id` string - `Customer.HomeAddress` is populated with a new `Address` instance if one does not already exist - `Customer.HomeAddress.Line1` is populated using `CustomerViewModel.HomeAddressLine1` - `Customer.WorkAddress` is get-only, so is ignored if it's null diff --git a/docs/src/Meta-Members.md b/docs/src/Meta-Members.md index c0e9d72e7..ca882219d 100644 --- a/docs/src/Meta-Members.md +++ b/docs/src/Meta-Members.md @@ -25,7 +25,7 @@ class AccountDto - `FirstDeliveryAddressHasPostcode` - whether the first element in the source `DeliveryAddresses` collection has a non-default `Postcode` property value -Meta members are also supported in [query projections](Query-Projection). +Meta members are also supported in [query projections](/query-projection). ## Types of Meta Member diff --git a/docs/src/Object-Construction.md b/docs/src/Object-Construction.md index f6c5f53b4..f43cd5146 100644 --- a/docs/src/Object-Construction.md +++ b/docs/src/Object-Construction.md @@ -1,4 +1,4 @@ -AgileMapper constructs objects using [configured factories](Configuring-Object-Construction), factory methods and constructors, in that order. +AgileMapper constructs objects using [configured factories](/configuration/Object-Construction), factory methods and constructors, in that order. ### Factory Methods @@ -6,22 +6,22 @@ A factory method will be used if: - It's a public, static method returning an instance of the Type - Its name starts with 'Create' or 'Get' -- All its parameters have [matching source values](Member-Matching) +- All its parameters have [matching source values](/Member-Matching) ### Constructors A constructor will be used if: - It's public -- All its parameters have [matching source values](Member-Matching) +- All its parameters have [matching source values](/Member-Matching) ### Selection Rules -- [Configured constructions](Configuring-Object-Construction) are preferred +- [Configured constructions](/configuration/Object-Construction) are preferred - The factory method or constructor with the most parameters is preferred - If a factory method has the same number of parameters as a constructor, the factory method is preferred - If a factory method or constructor complex type argument would be passed as null, the next available factory method or constructor is used - If there are no available factory methods or constructors with all-matched parameters - and no public, parameterless constructor - the member for which the object would be created is ignored - To avoid infinite loops, if an object has a complex type constructor parameter of its own Type (a 'copy constructor'), it will be ignored. -If required, both [constructor parameters](Configuring-Constructor-Arguments) and [object construction](Configuring-Object-Construction) can be configured. \ No newline at end of file +If required, both [constructor parameters](/configuration/Constructor-Arguments) and [object construction](/configuration/Object-Construction) can be configured. \ No newline at end of file diff --git a/docs/src/Object-Flattening.md b/docs/src/Object-Flattening.md index 5a01aee50..50240ef19 100644 --- a/docs/src/Object-Flattening.md +++ b/docs/src/Object-Flattening.md @@ -1,8 +1,8 @@ -AgileMapper matches flattened member names [as you'd expect](Member-Matching), but it also has a dedicated `.Flatten()` API which flattens objects in various ways. It is accessible: +AgileMapper matches flattened member names [as you'd expect](/Member-Matching), but it also has a dedicated `.Flatten()` API which flattens objects in various ways. It is accessible: -- Via the [static API](Static-vs-Instance-Mappers), using `Mapper.Flatten(myObject)` +- Via the [static API](/Static-vs-Instance-Mappers), using `Mapper.Flatten(myObject)` - Via the instance API, using `myInstanceMapper.Flatten(myObject)` -- Via an [extension method](Mapping-Extension-Methods), using `myObject.Flatten()` +- Via an [extension method](/Mapping-Extension-Methods), using `myObject.Flatten()` Flattening produces an object including all the source object's string or value-type members. For example: diff --git a/docs/src/Object-Unflattening.md b/docs/src/Object-Unflattening.md index fd71633ca..18a035e2a 100644 --- a/docs/src/Object-Unflattening.md +++ b/docs/src/Object-Unflattening.md @@ -1,10 +1,10 @@ -AgileMapper matches nested members to source members with flattened names [as you'd expect](Member-Matching), but it also has a dedicated `.Unflatten()` API which unflattens objects in various ways. It is accessible: +AgileMapper matches nested members to source members with flattened names [as you'd expect](/Member-Matching), but it also has a dedicated `.Unflatten()` API which unflattens objects in various ways. It is accessible: -- Via the [static API](Static-vs-Instance-Mappers), using `Mapper.Unflatten(myObject)` +- Via the [static API](/Static-vs-Instance-Mappers), using `Mapper.Unflatten(myObject)` - Via the instance API, using `myInstanceMapper.Unflatten(myObject)` -- Via an [extension method](Mapping-Extension-Methods), using `myObject.Unflatten()` +- Via an [extension method](/Mapping-Extension-Methods), using `myObject.Unflatten()` -Unflattening produces an object populated using the source's [flattened](Object-Flattening) members. +Unflattening produces an object populated using the source's [flattened](/Object-Flattening) members. For example, this Dictionary: diff --git a/docs/src/Performing-Merges.md b/docs/src/Performing-Merges.md index 5cfb37973..6f0742a99 100644 --- a/docs/src/Performing-Merges.md +++ b/docs/src/Performing-Merges.md @@ -4,7 +4,7 @@ Update an object's unpopulated members with values from another using: Mapper.Map(customerViewModel).OnTo(customer); ``` -When merging collections, objects are matched by id ([configurable](Configuring-Object-Identifiers) if necessary). For example: +When merging collections, objects are matched by id ([configurable](/configuration/Object-Identifiers) if necessary). For example: ```cs var source = new Collection diff --git a/docs/src/Performing-Updates.md b/docs/src/Performing-Updates.md index 9f6be6d65..3996eb321 100644 --- a/docs/src/Performing-Updates.md +++ b/docs/src/Performing-Updates.md @@ -4,7 +4,7 @@ Update an object's members with values from another using: Mapper.Map(customerViewModel).Over(customer); ``` -When updating a collection, objects are matched by id ([configurable](Configuring-Object-Identifiers) if necessary). For example: +When updating a collection, objects are matched by id ([configurable](/configuration/Object-Identifiers) if necessary). For example: ```cs var source = new[] diff --git a/docs/src/Static-vs-Instance-Mappers.md b/docs/src/Static-vs-Instance-Mappers.md index e11a4b833..0662926fb 100644 --- a/docs/src/Static-vs-Instance-Mappers.md +++ b/docs/src/Static-vs-Instance-Mappers.md @@ -27,7 +27,7 @@ Using the static API enables mapping in less flexible scenarios where you aren't ### Instance API -Use the instance API via instance methods on an [`IMapper`](/agileobjects/AgileMapper/blob/master/AgileMapper/IMapper.cs) object, for example: +Use the instance API via instance methods on an [`IMapper`](https://github.com/agileobjects/AgileMapper/blob/master/AgileMapper/IMapper.cs) object, for example: ```cs // Configuration - done once at start-up: diff --git a/docs/src/Type-Conversion.md b/docs/src/Type-Conversion.md index 686eacf61..c75618ced 100644 --- a/docs/src/Type-Conversion.md +++ b/docs/src/Type-Conversion.md @@ -2,7 +2,7 @@ Value conversion is performed according to the following: - Value types, nullable types and strings are all parsed and converted out of the box using the `TryParse` methods from the BCL. -- `DateTime`s (and nullable `DateTime`s) are converted to strings using `value.ToString(CultureInfo.CurrentCulture.DateTimeFormat)`. Custom formatting strings [can be configured](To-String-Formatting) for to-string conversions. +- `DateTime`s (and nullable `DateTime`s) are converted to strings using `value.ToString(CultureInfo.CurrentCulture.DateTimeFormat)`. Custom formatting strings [can be configured](/configuration/To-String-Formatting) for to-string conversions. - Implicit or explicit to-String operators are used to convert values to strings where they are available. @@ -23,6 +23,6 @@ target.EnumValue = source.Enum == SourceStatus.Complete : default(TargetStatus) ``` -        ...any configured [enum pairs](Enum-Mapping#configuring-enum-pairs) are used as the first values in the tree. +        ...any configured [enum pairs](/Enum-Mapping#configuring-enum-pairs) are used as the first values in the tree. - Numerics are mapped to booleans (and vice-versa) with 1 mapping to true, and not-1 mapping to false. \ No newline at end of file diff --git a/docs/src/Validating-Mappings.md b/docs/src/Validating-Mappings.md index 28e850dea..3bddf68ae 100644 --- a/docs/src/Validating-Mappings.md +++ b/docs/src/Validating-Mappings.md @@ -1,8 +1,8 @@ -A mapper's [execution plans](Using-Execution-Plans) can be validated to ensure that: +A mapper's [execution plans](/Using-Execution-Plans) can be validated to ensure that: -- All target members have [matching](Member-Matching) source values -- All target complex types can either be [constructed](Object-Construction), or have mappable target members -- All members of any source [enums](Enum-Mapping) being mapped to target enums have matching members in the target enum type +- All target members have [matching](/Member-Matching) source values +- All target complex types can either be [constructed](/Object-Construction), or have mappable target members +- All members of any source [enums](/Enum-Mapping) being mapped to target enums have matching members in the target enum type Mapping plan validation is intended to be used during development to make sure nothing is missed - you should remove it in production code. diff --git a/docs/src/Assembly-Scanning.md b/docs/src/configuration/Assembly-Scanning.md similarity index 100% rename from docs/src/Assembly-Scanning.md rename to docs/src/configuration/Assembly-Scanning.md diff --git a/docs/src/Configuration-Classes.md b/docs/src/configuration/Classes.md similarity index 95% rename from docs/src/Configuration-Classes.md rename to docs/src/configuration/Classes.md index c9bad61b4..282b0495e 100644 --- a/docs/src/Configuration-Classes.md +++ b/docs/src/configuration/Classes.md @@ -1,4 +1,4 @@ -Multiple, dedicated configuration classes can be created by deriving from the abstract `MapperConfiguration` base class. This enables configuration to be split up and placed nearer where mapping is performed (although [inline](Inline-Configuration) is nearer). +Multiple, dedicated configuration classes can be created by deriving from the abstract `MapperConfiguration` base class. This enables configuration to be split up and placed nearer where mapping is performed (although [inline](/configuration/Inline) is nearer). `MapperConfiguration` provides the same configuration API, and exposes services you inject. @@ -26,7 +26,7 @@ public class ProductMappingConfiguration : MapperConfiguration } ``` -In this example the default mapper is configured - the one used via the [static](Static-vs-Instance-Mappers) Mapper API. +In this example the default mapper is configured - the one used via the [static](/Static-vs-Instance-Mappers) Mapper API. ### Applying Configurations @@ -98,7 +98,7 @@ Chains of `ApplyAfter` attributes will be followed, with all configurations auto ### Accessing Services -[Configured Service Providers](Dependency-Injection) are available to `MapperConfiguration` classes. For example: +[Configured Service Providers](/configuration/Dependency-Injection) are available to `MapperConfiguration` classes. For example: ```cs // Get a Dependency Injection container: diff --git a/docs/src/Cloning-Mappers.md b/docs/src/configuration/Cloning-Mappers.md similarity index 100% rename from docs/src/Cloning-Mappers.md rename to docs/src/configuration/Cloning-Mappers.md diff --git a/docs/src/Configuring-Constructor-Arguments.md b/docs/src/configuration/Constructor-Arguments.md similarity index 80% rename from docs/src/Configuring-Constructor-Arguments.md rename to docs/src/configuration/Constructor-Arguments.md index 36b586d9b..d6d6ed094 100644 --- a/docs/src/Configuring-Constructor-Arguments.md +++ b/docs/src/configuration/Constructor-Arguments.md @@ -1,4 +1,4 @@ -By default, types are created using the 'greediest' public constructor - the one with the most parameters that have [matching](Member-Matching) source members. If there are no available constructors whose parameters can all be matched - and no parameterless constructor - the member for which the type would be created is ignored. +By default, types are created using the 'greediest' public constructor - the one with the most parameters that have [matching](/Member-Matching) source members. If there are no available constructors whose parameters can all be matched - and no parameterless constructor - the member for which the type would be created is ignored. Constructor arguments can be configured by type or name, and constant values or expressions can be specified. @@ -45,6 +45,6 @@ Mapper .ToCtor("customerName")); // To Customer's 'customerName' param ``` -In these examples the `string` `CustomerNum` is parsed and [converted](Type-Conversion) to the `Guid` `customerId` out of the box. +In these examples the `string` `CustomerNum` is parsed and [converted](/Type-Conversion) to the `Guid` `customerId` out of the box. -If configuring constructor parameters is awkward (perhaps because there's a lot of them), you can also [configure an object factory](Configuring-Object-Creation) for a particular object type. \ No newline at end of file +If configuring constructor parameters is awkward (perhaps because there's a lot of them), you can also [configure an object factory](/configuration/Object-Construction) for a particular object type. \ No newline at end of file diff --git a/docs/src/Dependency-Injection.md b/docs/src/configuration/Dependency-Injection.md similarity index 92% rename from docs/src/Dependency-Injection.md rename to docs/src/configuration/Dependency-Injection.md index 2bebee3bd..6c1b823ba 100644 --- a/docs/src/Dependency-Injection.md +++ b/docs/src/configuration/Dependency-Injection.md @@ -58,11 +58,11 @@ Mapper.Before.MappingBegins .Call(ctx => ctx.GetService("PostLogger").Log("Mapping complete")); ``` -To retrieve the originally-configured provider, use `ctx.GetServiceProvider()`. Service providers and services are available in configured [member values](Configuring-Member-Values), [Exception handlers](Configuring-Exception-Handling), [mapping callbacks](Configuring-Mapping-Callbacks) and custom [object factories](Configuring-Object-Construction). +To retrieve the originally-configured provider, use `ctx.GetServiceProvider()`. Service providers and services are available in configured [member values](/configuration/Member-Values), [Exception handlers](/configuration/Exception-Handling), [mapping callbacks](/configuration/Mapping-Callbacks) and custom [object factories](/configuration/Object-Construction). #### During Configuration -To access services in a [MapperConfiguration](Configuration-Classes) instance, use: +To access services in a [MapperConfiguration](/configuration/Classes) instance, use: ```cs public class MyMappingConfiguration : MapperConfiguration diff --git a/docs/src/Dictionary-Mapping-Configuration.md b/docs/src/configuration/Dictionary-Mapping.md similarity index 95% rename from docs/src/Dictionary-Mapping-Configuration.md rename to docs/src/configuration/Dictionary-Mapping.md index 0bfb89736..908b45949 100644 --- a/docs/src/Dictionary-Mapping-Configuration.md +++ b/docs/src/configuration/Dictionary-Mapping.md @@ -136,4 +136,4 @@ Mapper.WhenMapping .Ignore(cd => cd.PhoneNumbers); ``` -Dictionary mapping configuration also supports custom and conditional [object creation](Configuring-Object-Creation), [mapping callbacks](Configuring-Mapping-Callbacks), [target member values](Configuring-Member-Values), etc. \ No newline at end of file +Dictionary mapping configuration also supports custom and conditional [object creation](/configuration/Object-Construction), [mapping callbacks](/configuration/Mapping-Callbacks), [target member values](/configuration/Member-Values), etc. \ No newline at end of file diff --git a/docs/src/Dynamic-Mapping-Configuration.md b/docs/src/configuration/Dynamic-Mapping.md similarity index 96% rename from docs/src/Dynamic-Mapping-Configuration.md rename to docs/src/configuration/Dynamic-Mapping.md index 048eb6146..b896e2e31 100644 --- a/docs/src/Dynamic-Mapping-Configuration.md +++ b/docs/src/configuration/Dynamic-Mapping.md @@ -130,4 +130,4 @@ Mapper.WhenMapping .Ignore(cd => cd.PhoneNumbers); ``` -Dynamic mapping configuration also supports custom and conditional [object creation](Configuring-Object-Creation), [mapping callbacks](Configuring-Mapping-Callbacks), [target member values](Configuring-Member-Values), etc. \ No newline at end of file +Dynamic mapping configuration also supports custom and conditional [object creation](/configuration/Object-Construction), [mapping callbacks](/configuration/Mapping-Callbacks), [target member values](/configuration/Member-Values), etc. \ No newline at end of file diff --git a/docs/src/Configuring-Exception-Handling.md b/docs/src/configuration/Exception-Handling.md similarity index 82% rename from docs/src/Configuring-Exception-Handling.md rename to docs/src/configuration/Exception-Handling.md index d3915e297..34f058137 100644 --- a/docs/src/Configuring-Exception-Handling.md +++ b/docs/src/configuration/Exception-Handling.md @@ -1,4 +1,4 @@ -By default, an `Exception` thrown during a mapping is wrapped in a [`MappingException`](/agileobjects/AgileMapper/blob/master/AgileMapper/MappingException.cs) and rethrown. To configure a mapper to swallow exceptions and return null instead, use: +By default, an `Exception` thrown during a mapping is wrapped in a [`MappingException`](https://github.com/agileobjects/AgileMapper/blob/master/AgileMapper/MappingException.cs) and rethrown. To configure a mapper to swallow exceptions and return null instead, use: ```cs Mapper.WhenMapping diff --git a/docs/src/Ignoring-Target-Members.md b/docs/src/configuration/Ignoring-Target-Members.md similarity index 90% rename from docs/src/Ignoring-Target-Members.md rename to docs/src/configuration/Ignoring-Target-Members.md index 4c26c7574..fab073dd2 100644 --- a/docs/src/Ignoring-Target-Members.md +++ b/docs/src/configuration/Ignoring-Target-Members.md @@ -1,4 +1,4 @@ -Target members which have no [matching](Member-Matching), [compatible](Type-Conversion) source member are ignored by default, but you can also tell a mapper to ignore members which would usually be mapped. For example: +Target members which have no [matching](/Member-Matching), [compatible](/Type-Conversion) source member are ignored by default, but you can also tell a mapper to ignore members which would usually be mapped. For example: ```cs public class OrderDto @@ -22,7 +22,7 @@ Mapper.WhenMapping .Ignore(o => o.Id); // Ignore the Order.Id property ``` -Multiple fields can be ignored with a single configuration, and ignores can be made conditional. Here's an [inline configuration](Inline-Configuration) example: +Multiple fields can be ignored with a single configuration, and ignores can be made conditional. Here's an [inline configuration](/configuration/Inline) example: ```cs // Source, target and mapping types are implicit from the mapping: @@ -116,4 +116,4 @@ Mapper.WhenMapping m.IsPropertyMatching(p => p.IsAssembly)); // Ignore ``` -Again, all ignores can alternatively be configured [inline](Inline-Configuration). \ No newline at end of file +Again, all ignores can alternatively be configured [inline](/configuration/Inline). \ No newline at end of file diff --git a/docs/src/Inline-Configuration.md b/docs/src/configuration/Inline.md similarity index 93% rename from docs/src/Inline-Configuration.md rename to docs/src/configuration/Inline.md index e53f341a1..4fff16c02 100644 --- a/docs/src/Inline-Configuration.md +++ b/docs/src/configuration/Inline.md @@ -6,7 +6,7 @@ var dto = mapper .Map((p, d) => p.Spec).To(d => d.Specification)); ``` -...which also works in [query projections](Query-Projection), for example: +This also works in [query projections](/query-projection), for example: ```cs var dto = await context @@ -46,7 +46,7 @@ var dto = mapper .Map((p, d) => p.Price).To(d => d.Cost)); ``` -Inline configuration can be supplied via the [static](Static-vs-Instance-Mappers) or [instance](Static-vs-Instance-Mappers) APIs. +Inline configuration can be supplied via the [static](/Static-vs-Instance-Mappers) or [instance](/Static-vs-Instance-Mappers) APIs. ### Invalid Configuration diff --git a/docs/src/Configuring-Mapping-Callbacks.md b/docs/src/configuration/Mapping-Callbacks.md similarity index 100% rename from docs/src/Configuring-Mapping-Callbacks.md rename to docs/src/configuration/Mapping-Callbacks.md diff --git a/docs/src/Configuring-Member-Name-Patterns.md b/docs/src/configuration/Member-Name-Patterns.md similarity index 86% rename from docs/src/Configuring-Member-Name-Patterns.md rename to docs/src/configuration/Member-Name-Patterns.md index 1b13ac3e9..00b158ea8 100644 --- a/docs/src/Configuring-Member-Name-Patterns.md +++ b/docs/src/configuration/Member-Name-Patterns.md @@ -1,4 +1,4 @@ -If a naming convention prevents normal [member matching](Member-Matching), you can configure naming patterns to use to match names up. For example: +If a naming convention prevents normal [member matching](/Member-Matching), you can configure naming patterns to use to match names up. For example: ```cs public class ProductDto @@ -36,7 +36,7 @@ Mapper.WhenMapping Configured regex patterns must start with `^` and end with `$`, contain the capturing group `(.+)` to provide the part of a name to use for matching, and have a prefix and / or suffix. -Naming patterns can also be configured [inline](Inline-Configuration) +Naming patterns can also be configured [inline](/configuration/Inline) ```cs var anonSource = new { _PriceValue = default(double) }; diff --git a/docs/src/Configuring-Member-Values.md b/docs/src/configuration/Member-Values.md similarity index 94% rename from docs/src/Configuring-Member-Values.md rename to docs/src/configuration/Member-Values.md index 1ff49e742..68974452f 100644 --- a/docs/src/Configuring-Member-Values.md +++ b/docs/src/configuration/Member-Values.md @@ -16,7 +16,7 @@ Mapper.WhenMapping ``` -**A source expression** (in this example, supplied [inline](Inline-Configuration)): +**A source expression** (in this example, supplied [inline](/configuration/Inline)): ```cs // Source, target and mapping types are implicit from the mapping: @@ -40,7 +40,7 @@ Mapper.WhenMapping .Map("Company ABC", p => p.CompanyName); ``` -**A value from an [injected service](Dependency-Injection)**: +**A value from an [injected service](/configuration/Dependency-Injection)**: ```cs // Retrieve an IDateTimeProvider instance from a configured @@ -52,7 +52,7 @@ Mapper.WhenMapping .To(o => o.DateCreated); // o is the Order ``` -**The result of a function call** ([inline](Inline-Configuration)): +**The result of a function call** ([inline](/configuration/Inline)): ```cs Func companyNameFactory = @@ -77,7 +77,7 @@ Mapper.WhenMapping .To(p => p.CompanyName); // p is the Product ``` -And in an [inline](Inline-Configuration) example: +And in an [inline](/configuration/Inline) example: ```cs Mapper.Map(productDto).ToANew(cfg => cfg diff --git a/docs/src/Null-Results.md b/docs/src/configuration/Null-Results.md similarity index 82% rename from docs/src/Null-Results.md rename to docs/src/configuration/Null-Results.md index 1d2abcdc7..7687d4555 100644 --- a/docs/src/Null-Results.md +++ b/docs/src/configuration/Null-Results.md @@ -1,4 +1,4 @@ -If a target complex type member has no [matching source member](Member-Matching), no matched [constructor arguments](Object-Construction), and none of its child members have matching source members, it will be mapped to null. +If a target complex type member has no [matching source member](/Member-Matching), no matched [constructor arguments](/Object-Construction), and none of its child members have matching source members, it will be mapped to null. For example: diff --git a/docs/src/Configuring-Object-Construction.md b/docs/src/configuration/Object-Construction.md similarity index 91% rename from docs/src/Configuring-Object-Construction.md rename to docs/src/configuration/Object-Construction.md index 1566ff5d6..1856806da 100644 --- a/docs/src/Configuring-Object-Construction.md +++ b/docs/src/configuration/Object-Construction.md @@ -21,7 +21,7 @@ Mapper.WhenMapping }); ``` -Configure a conditional custom factory using ([inline](Inline-Configuration) example): +Configure a conditional custom factory using ([inline](/configuration/Inline) example): ```cs Mapper.Map(customerViewModels).ToANew(cfg => cfg diff --git a/docs/src/configuration/Object-Identifiers.md b/docs/src/configuration/Object-Identifiers.md new file mode 100644 index 000000000..d49cfeb67 --- /dev/null +++ b/docs/src/configuration/Object-Identifiers.md @@ -0,0 +1,23 @@ +Objects are identified during collection [updates](/Performing-Updates) and [merges](/Performing-Merges) using members with the following names: + +* `Id` +* `Id` +* `Identifier` +* `Identifier` + +You can configure an object to be uniquely identified with a different member using: + +```cs +Mapper.WhenMapping + .InstancesOf() // Apply to NamedCustomer mappings + .IdentifyUsing(c => c.Name); // Identify using NamedCustomer.Name +``` + +Or, configured [inline](/configuration/Inline): + +```cs +Mapper.Map(customerDtos).ToANew(cfg => cfg + .WhenMapping + .InstancesOf() + .IdentifyUsing(c => c.Name)); // Identify using NamedCustomer.Name +``` \ No newline at end of file diff --git a/docs/src/Pairing-Derived-Types.md b/docs/src/configuration/Pairing-Derived-Types.md similarity index 79% rename from docs/src/Pairing-Derived-Types.md rename to docs/src/configuration/Pairing-Derived-Types.md index d464f581a..7d598d1dd 100644 --- a/docs/src/Pairing-Derived-Types.md +++ b/docs/src/configuration/Pairing-Derived-Types.md @@ -1,4 +1,4 @@ -Derived type pairing matches particular derived sources types to particular derived target types. Most of the time [this is done automatically](Derived-Types), but if your derived types aren't consistently-named, or you want to make derived type mapping conditional, you can configure it. +Derived type pairing matches particular derived sources types to particular derived target types. Most of the time [this is done automatically](/Derived-Types), but if your derived types aren't consistently-named, or you want to make derived type mapping conditional, you can configure it. For example: @@ -31,7 +31,7 @@ var animals = Mapper.Map(animalViewModels).ToANew>(); // animals[1] is of type Dog ``` -...and can be applied conditionally ([inline](Inline-Configuration) example): +...and can be applied conditionally ([inline](/configuration/Inline) example): ```cs Mapper @@ -43,4 +43,4 @@ Mapper .MapTo()); // Create an instance of Dog ``` -Conditional derived type mappings can also be configured [for Dictionaries](Dictionary-Mapping#conditional-derived-types). \ No newline at end of file +Conditional derived type mappings can also be configured [for Dictionaries](/configuration/Dictionary-Mapping#conditional-derived-types). \ No newline at end of file diff --git a/docs/src/To-String-Formatting.md b/docs/src/configuration/To-String-Formatting.md similarity index 100% rename from docs/src/To-String-Formatting.md rename to docs/src/configuration/To-String-Formatting.md diff --git a/docs/src/configuration/index.md b/docs/src/configuration/index.md new file mode 100644 index 000000000..8a1c495ef --- /dev/null +++ b/docs/src/configuration/index.md @@ -0,0 +1,14 @@ +Many aspects of mapping can be configured, but no up-front type registration is required - a mapping function is created and cached the first time two types are mapped. + +Various configuration options are available: + +- [Static](/Static-vs-Instance-Mappers) configuration (`Mapper.WhenMapping`) configures a default, instance-scoped mapper behind the scenes. This configures the mapper used when you call `Mapper.Map(source)` + +- [Instance](/Static-vs-Instance-Mappers) configuration (`mapper.WhenMapping`) configures that particular instance + +- [Inline](/configuration/Inline) configuration combines the configuration of the mapper performing the mapping with the inline configuration you supply + +- [Class](/configuration/Classes) configuration splits configuration up into dedicated configuration classes. + +The same API is available in all four contexts. + diff --git a/docs/src/css/styles.css b/docs/src/css/styles.css new file mode 100644 index 000000000..d6f1e0a5e --- /dev/null +++ b/docs/src/css/styles.css @@ -0,0 +1,54 @@ +body { + font: 400 11pt 'Segoe UI', Calibri, Arial, sans-serif !important; +} + +h1, h2, h3, h4, input[type=submit] { + font-family: 'Segoe UI Light', Calibri, Arial, sans-serif !important; + margin: 0 0 .5em; +} + +h1 { + font-size: 2.5em; +} + +h2 { + font-size: 2em; +} + +h3 { + font-size: 1.6em; +} + +h4 { + font-size: 1.2em; + margin-left: .7em; +} + +p code, li code { + border: none; + padding: 2px 0; + font-size: 11pt; + color: black; +} + +pre code { + font-size: 11pt; +} + +span.caption-text { + color: #dcdcdc; + background: #1e1e1e; +} + +p a code { + text-decoration: underline; +} + +.wy-menu-vertical li.current a { + color: #1e1e1e; +} + +li.current { + border-top: 1px solid #010101; + border-bottom: 1px solid #010101; +} diff --git a/docs/src/index.md b/docs/src/index.md index bd2583691..e96190619 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,10 +1,10 @@ ## Overview -AgileMapper is a zero-configuration, [highly-configurable](Configuration) object-object mapper with [viewable execution plans](Using-Execution-Plans), targetting [.NET Standard 1.0+](https://docs.microsoft.com/en-us/dotnet/articles/standard/library) and .NET 3.5+. It performs [query projections](Query-Projection), object creation, deep clones, id-aware [updates](Performing-Updates) and [merges](Performing-Merges), and can be used via [extension methods](Mapping-Extension-Methods), or a [static or instance](Static-vs-Instance-Mappers) API. +AgileMapper is a zero-configuration, [highly-configurable](/configuration) object-object mapper with [viewable execution plans](/Using-Execution-Plans), targetting [.NET Standard 1.0+](https://docs.microsoft.com/en-us/dotnet/articles/standard/library) and .NET 3.5+. It performs [query projections](/query-projection), object creation, deep clones, id-aware [updates](/Performing-Updates) and [merges](/Performing-Merges), and can be used via [extension methods](/Mapping-Extension-Methods), or a [static or instance](/Static-vs-Instance-Mappers) API. -Mapping functions are created and cached the first time two types are mapped - no up-front configuration is necessary. You can [cache up-front](Using-Execution-Plans) if you prefer, though. +Mapping functions are created and cached the first time two types are mapped - no up-front configuration is necessary. You can [cache up-front](/Using-Execution-Plans) if you prefer, though. -[Available via NuGet](https://www.nuget.org/packages/AgileObjects.AgileMapper) and licensed with the [MIT licence](/agileobjects/AgileMapper/blob/master/LICENCE.md), you can install it via the [package manager console](https://docs.nuget.org/consume/package-manager-console): +[Available via NuGet](https://www.nuget.org/packages/AgileObjects.AgileMapper) and licensed with the [MIT licence](https://github.com/agileobjects/AgileMapper/blob/master/LICENCE.md), you can install it via the [package manager console](https://docs.nuget.org/consume/package-manager-console): PM> Install-Package AgileObjects.AgileMapper @@ -24,7 +24,7 @@ var customer = customerViewModel.Map().ToANew(); ### Query Projection -[Project](Query-Projection) entities to another Type using: +[Project](/query-projection) entities to another Type using: ```cs var customerVm = await dbContext @@ -45,7 +45,7 @@ var clonedCustomer = customerToBeCloned.DeepClone(); ### Updating -[Update](Performing-Updates) an object's members with values from another using: +[Update](/Performing-Updates) an object's members with values from another using: ```cs Mapper.Map(customerSaveRequest).Over(customer); @@ -55,7 +55,7 @@ customerSaveRequest.Map().Over(customer); ### Merging -[Merge](Performing-Merges) an object's unpopulated members with values from another using: +[Merge](/Performing-Merges) an object's unpopulated members with values from another using: ```cs Mapper.Map(customerDto).OnTo(customer); @@ -65,7 +65,7 @@ customerDto.Map().OnTo(customer); ## View a Mapping Execution Plan -View an [execution plan](Using-Execution-Plans) to see how two object types will be mapped; this also caches the plan, so you can use it to choose when to incur that cost. Use: +View an [execution plan](/Using-Execution-Plans) to see how two object types will be mapped; this also caches the plan, so you can use it to choose when to incur that cost. Use: ```cs // For object creation: diff --git a/docs/src/Query-Projection-Configuration.md b/docs/src/query-projection/Configuration.md similarity index 62% rename from docs/src/Query-Projection-Configuration.md rename to docs/src/query-projection/Configuration.md index 429eb5494..c44858844 100644 --- a/docs/src/Query-Projection-Configuration.md +++ b/docs/src/query-projection/Configuration.md @@ -1,4 +1,4 @@ -[Query projection](Query-Projection) supports a subset of regular mapping [configuration](Configuration). Anything [applicable](#limitations) configured using a `Mapper.WhenMapping` API - [static](Static-vs-Instance-Mappers) or instance - will also be applied to query projections. +[Query projection](/query-projection) supports a subset of regular mapping [configuration](/configuration). Anything [applicable](#limitations) configured using a `Mapper.WhenMapping` API - [static](/Static-vs-Instance-Mappers) or instance - will also be applied to query projections. ### Static API @@ -20,7 +20,7 @@ var productDtos = await context .ToArrayAsync(); ``` -In this case, the `Product.Spec` -> `ProductDto.Specification` custom [member value](Configuring-Member-Values) will be used in the projection because both the configuration and projection are performed using the default mapper. +In this case, the `Product.Spec` -> `ProductDto.Specification` custom [member value](/configuration/Member-Values) will be used in the projection because both the configuration and projection are performed using the default mapper. ### Instance API @@ -54,22 +54,22 @@ var productDtos = await context Because projections are performed by [IQueryProvider](https://docs.microsoft.com/en-us/dotnet/api/system.linq.iqueryprovider)s, only the following configuration options are applied: -- Custom [member values](Configuring-Member-Values), as above +- Custom [member values](/configuration/Member-Values), as above -- Custom [constructor arguments](Configuring-Constructor-Arguments) +- Custom [constructor arguments](/configuration/Constructor-Arguments) -- Custom [naming patterns](Configuring-Member-Name-Patterns) +- Custom [naming patterns](/configuration/Member-Name-Patterns) -- To-String [formatting](To-String-Formatting) +- To-String [formatting](/configuration/To-String-Formatting) -- Enum [pairing](Enum-Mapping#configuring-enum-pairs) +- Enum [pairing](/configuration/Enum-Mapping#configuring-enum-pairs) -- [Ignored](Ignoring-Target-Members) members +- [Ignored](/configuration/Ignoring-Target-Members) members -- Object [factories](Configuring-Object-Construction) +- Object [factories](/configuration/Object-Construction) -- Null [mapping results](Null-Results) +- Null [mapping results](/configuration/Null-Results) -Most notably, [callbacks](Configuring-Mapping-Callbacks), [object tracking](Mapped-Object-Tracking) and [derived type pairing](Pairing-Derived-Types) are not supported - although you can [project to derived types](Projecting-to-Derived-Types) conditionally. +Most notably, [callbacks](/configuration/Mapping-Callbacks), [object tracking](/configuration/Mapped-Object-Tracking) and [derived type pairing](/configuration/Pairing-Derived-Types) are not supported - although you can [project to derived types](/query-projection/Derived-Types) conditionally. In every case, it is up to you to configure values your IQueryProvider can support - configured values which will definitely be unsupported - like function invocations - are automatically filtered out of query projections. \ No newline at end of file diff --git a/docs/src/Projecting-to-Derived-Types.md b/docs/src/query-projection/Derived-Types.md similarity index 76% rename from docs/src/Projecting-to-Derived-Types.md rename to docs/src/query-projection/Derived-Types.md index 790a8aef4..3b7e3253f 100644 --- a/docs/src/Projecting-to-Derived-Types.md +++ b/docs/src/query-projection/Derived-Types.md @@ -1,4 +1,4 @@ -If your [`IQueryProvider`](https://docs.microsoft.com/en-us/dotnet/api/system.linq.iqueryprovider) [supports](Entity-Framework#derived-types) casting projected instances to a base Type, you can project to derived Types via configured conditions. For example: +If your [`IQueryProvider`](https://docs.microsoft.com/en-us/dotnet/api/system.linq.iqueryprovider) [supports](/query-projection/Entity-Framework#derived-types) casting projected instances to a base Type, you can project to derived Types via configured conditions. For example: ```cs // Using an EF Core DbContext: diff --git a/docs/src/Entity-Framework.md b/docs/src/query-projection/Entity-Framework.md similarity index 96% rename from docs/src/Entity-Framework.md rename to docs/src/query-projection/Entity-Framework.md index 09b219bc6..5bf90ca9c 100644 --- a/docs/src/Entity-Framework.md +++ b/docs/src/query-projection/Entity-Framework.md @@ -1,4 +1,4 @@ -AgileMapper contains version-specific support for Entity Framework 5, [Entity Framework 6](https://docs.microsoft.com/en-us/ef/ef6), and [Entity Framework Core](https://docs.microsoft.com/en-us/ef/core), extending each version's ability to support [query projection](Query-Projection). +AgileMapper contains version-specific support for Entity Framework 5, [Entity Framework 6](https://docs.microsoft.com/en-us/ef/ef6), and [Entity Framework Core](https://docs.microsoft.com/en-us/ef/core), extending each version's ability to support [query projection](/query-projection). ### Type Conversion @@ -34,8 +34,8 @@ The following conversions are supported, along with the same projections from an | Recursion ** |
  • - [x]
| | | | Collection Members *** |
  • - [x]
|
  • - [x]
| | -\* EF5 and EF6 do not support casting a projected Type to its base Type, so do not support projecting to [conditional derived types](Projecting-to-Derived-Types). +\* EF5 and EF6 do not support casting a projected Type to its base Type, so do not support projecting to [conditional derived types](/query-projection/Derived-Types). -\** EF5 and EF6 do not support creating instances of a projected Type with [differing numbers](https://stackoverflow.com/questions/39139402/the-type-appears-in-two-structurally-incompatible-initializations-within-a-singl) of member initialisations in the same query, so do not support projecting [recursive relationships](Projecting-Recursive-Relationships). +\** EF5 and EF6 do not support creating instances of a projected Type with [differing numbers](https://stackoverflow.com/questions/39139402/the-type-appears-in-two-structurally-incompatible-initializations-within-a-singl) of member initialisations in the same query, so do not support projecting [recursive relationships](/query-projection/Recursive-Relationships). \*** EF5 can only project to `IEnumerable{T}` members, not `ICollection{T}`, `List{T}`, `T[]`, etc. \ No newline at end of file diff --git a/docs/src/Join-Entities.md b/docs/src/query-projection/Join-Entities.md similarity index 100% rename from docs/src/Join-Entities.md rename to docs/src/query-projection/Join-Entities.md diff --git a/docs/src/Projecting-Recursive-Relationships.md b/docs/src/query-projection/Recursive-Relationships.md similarity index 84% rename from docs/src/Projecting-Recursive-Relationships.md rename to docs/src/query-projection/Recursive-Relationships.md index 17d284320..4de783dd9 100644 --- a/docs/src/Projecting-Recursive-Relationships.md +++ b/docs/src/query-projection/Recursive-Relationships.md @@ -1,4 +1,4 @@ -If your [`IQueryProvider`](https://docs.microsoft.com/en-us/dotnet/api/system.linq.iqueryprovider) [supports](Entity-Framework#recursion) it, you can project recursive relationships to a specified depth. For example, with these classes: +If your [`IQueryProvider`](https://docs.microsoft.com/en-us/dotnet/api/system.linq.iqueryprovider) [supports](/query-projection/Entity-Framework#recursion) it, you can project recursive relationships to a specified depth. For example, with these classes: ```cs // Entity: @@ -97,4 +97,4 @@ var stringsDto = await context ...and so on. -Note that it is not possible to use [object tracking](Mapped-Object-Tracking) in query projections, so [identity integrity](Mapped-Object-Tracking#identity-integrity) is not maintained. \ No newline at end of file +Note that it is not possible to use [object tracking](/configuration/Mapped-Object-Tracking) in query projections, so [identity integrity](/configuration/Mapped-Object-Tracking#identity-integrity) is not maintained. \ No newline at end of file diff --git a/docs/src/Query-Projection.md b/docs/src/query-projection/index.md similarity index 64% rename from docs/src/Query-Projection.md rename to docs/src/query-projection/index.md index 43a09b7e2..1774c2dd5 100644 --- a/docs/src/Query-Projection.md +++ b/docs/src/query-projection/index.md @@ -1,6 +1,6 @@ AgileMapper can project an `IQueryable{T}` to any other type supported by the [`IQueryProvider`](https://docs.microsoft.com/en-us/dotnet/api/system.linq.iqueryprovider), which can increase performance by only selecting the required data from an underlying data store, and decrease lines of code by directly materializing a DTO or view model, instead of materializing then mapping entities. -Query projection supports a subset of regular mapping [configuration](Query-Projection-Configuration), and can be configured [inline](Inline-Configuration). It also supports projection of recursive relationships to a specified depth. +Query projection supports a subset of regular mapping [configuration](/query-projection/Configuration), and can be configured [inline](/configuration/Inline). It also supports projection of recursive relationships to a specified depth. To project a query, use: @@ -12,7 +12,7 @@ var orderDtos = await context .ToListAsync(); ``` -`.Project()` uses the default mapper - the one used behind the scenes by the [static](Static-vs-Instance-Mappers) `Mapper` API. To project a query using an instance-scoped mapper, use: +`.Project()` uses the default mapper - the one used behind the scenes by the [static](/Static-vs-Instance-Mappers) `Mapper` API. To project a query using an instance-scoped mapper, use: ```cs var orderDtos = await context @@ -23,7 +23,7 @@ var orderDtos = await context ### Viewing Projection Plans -The [plan](Using-Execution-Plans) for a query projection can be viewed and cached just like those for regular mappings, but because they're cached against the IQueryProvider's Type, an instance of the queryable being projected is required. +The [plan](/Using-Execution-Plans) for a query projection can be viewed and cached just like those for regular mappings, but because they're cached against the IQueryProvider's Type, an instance of the queryable being projected is required. For example: diff --git a/mkdocs.yml b/mkdocs.yml index 2c479c1f5..aa3ad4542 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,58 +1,62 @@ site_name: AgileMapper -repo_url: https://github.com/agileobjects/AgileMapper site_description: 'AgileMapper: A zero-configuration, highly-configurable object-object mapper with viewable execution plans. Projects queries, transforms, deep clones, updates and merges via extension methods, or a static or instance API. Targets .NET Standard 1.0+ and .NET 3.5+' site_author: Steve Wilkes +repo_url: https://github.com/agileobjects/AgileMapper + docs_dir: 'docs/src' site_dir: 'docs/site' + extra_css: - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.13.1/styles/vs2015.min.css + - css/styles.css + nav: - - Home: index.md - - Member matching: Member-Matching.md - - Object construction: Object-Construction.md - - Type conversion: Type-Conversion.md - - Collections: Collections.md - - Entity mapping: Entity-Mapping.md - - Dictionary mapping: Dictionary-Mapping.md - - Dynamic mapping: Dynamic-Mapping.md - - Meta members: Meta-Members.md - - Enum mapping: Enum-Mapping.md + - General Use: + - Member matching: Member-Matching.md + - Object construction: Object-Construction.md + - Type conversion: Type-Conversion.md + - Collections: Collections.md + - Entity mapping: Entity-Mapping.md + - Dictionary mapping: Dictionary-Mapping.md + - Dynamic mapping: Dynamic-Mapping.md + - Meta members: Meta-Members.md + - Enum mapping: Enum-Mapping.md + - Object updating: Performing-Updates.md + - Object merging: Performing-Merges.md + - Object flattening: Object-Flattening.md + - Object unflattening: Object-Unflattening.md + - Using execution plans: Using-Execution-Plans.md + - Derived types: Derived-Types.md + - Object tracking: Mapped-Object-Tracking.md + - Static vs Instance API: Static-vs-Instance-Mappers.md + - Mapping extension methods: Mapping-Extension-Methods.md + - Mapping validation: Validating-Mappings.md - Query Projection: - - Overview: Query-Projection.md - - Configuration: Query-Projection-Configuration.md - - Derived Types: Projecting-to-Derived-Types.md - - Recursion: Projecting-Recursive-Relationships.md - - Join entities: Join-Entities.md - - Entity Framework: Entity-Framework.md - - Object updating: Performing-Updates.md - - Object merging: Performing-Merges.md - - Object flattening: Object-Flattening.md - - Object unflattening: Object-Unflattening.md - - Using execution plans: Using-Execution-Plans.md - - Derived types: Derived-Types.md - - Object tracking: Mapped-Object-Tracking.md - - Static vs Instance API: Static-vs-Instance-Mappers.md - - Mapping extension methods: Mapping-Extension-Methods.md - - Mapping validation: Validating-Mappings.md + - Overview: query-projection/index.md + - Configuration: query-projection/Configuration.md + - Derived Types: query-projection/Derived-Types.md + - Recursion: query-projection/Recursive-Relationships.md + - Join entities: query-projection/Join-Entities.md + - Entity Framework: query-projection/Entity-Framework.md - Configuration: - - Overview: Configuration.md - - Configuring inline: Inline-Configuration.md - - Configuration classes: Configuration-Classes.md - - Dependency injection: Dependency-Injection.md - - Member values: Configuring-Member-Values.md - - Constructor arguments: Configuring-Constructor-Arguments.md - - Member name patterns: Configuring-Member-Name-Patterns.md - - To-string formatting: To-String-Formatting.md + - Overview: configuration/index.md + - Configuring inline: configuration/Inline.md + - Configuration classes: configuration/Classes.md + - Dependency injection: configuration/Dependency-Injection.md + - Member values: configuration/Member-Values.md + - Constructor arguments: configuration/Constructor-Arguments.md + - Member name patterns: configuration/Member-Name-Patterns.md + - To-string formatting: configuration/To-String-Formatting.md - Enum pairing: Enum-Mapping/#configuring-enum-pairs - - Dictionaries: Dictionary-Mapping-Configuration.md - - Dynamics: Dynamic-Mapping-Configuration.md - - Ignoring members: Ignoring-Target-Members.md - - Object identifiers: Configuring-Object-Identifiers.md - - Object construction: Configuring-Object-Construction.md - - Null results: Null-Results.md - - Derived type pairing: Pairing-Derived-Types.md - - Cloning Mappers: Cloning-Mappers.md - - Assembly scanning: Assembly-Scanning.md - - Exception handling: Configuring-Exception-Handling.md - - Mapping callbacks: Configuring-Mapping-Callbacks.md + - Dictionaries: configuration/Dictionary-Mapping.md + - Dynamics: configuration/Dynamic-Mapping.md + - Ignoring members: configuration/Ignoring-Target-Members.md + - Object identifiers: configuration/Object-Identifiers.md + - Object construction: configuration/Object-Construction.md + - Null results: configuration/Null-Results.md + - Derived type pairing: configuration/Pairing-Derived-Types.md + - Cloning Mappers: configuration/Cloning-Mappers.md + - Assembly scanning: configuration/Assembly-Scanning.md + - Exception handling: configuration/Exception-Handling.md + - Mapping callbacks: configuration/Mapping-Callbacks.md theme: readthedocs \ No newline at end of file