开源地址

Github：https://github.com/AgileObjects/AgileMapper (opens new window)

AgileMapper 是一个用于 .NET 的开源对象映射库，它提供了一种简单、灵活、强大的方式来处理对象映射。本文将为你介绍 AgileMapper 的使用方法，并提供详细的示例。

安装

你可以通过 NuGet 包管理器来安装 AgileMapper，也可以手动下载并添加到你的项目中。

在 NuGet 包管理器控制台中运行以下命令来安装 AgileMapper：

Install-Package AgileObjects.AgileMapper

基本用法

在开始使用 AgileMapper 之前，你需要引用 AgileObjects.AgileMapper 命名空间。

下面是一个简单的示例，用于将一个 Person 对象映射到一个 PersonViewModel 对象：

using AgileObjects.AgileMapper;

var person = new Person
{
    FirstName = "John",
    LastName = "Doe",
    Age = 30
};

var viewModel = Mapper.Map(person).ToANew<PersonViewModel>();

这里，我们使用 Mapper 类的 Map 方法来指定源对象 person，并使用 ToANew 泛型方法来指定目标对象的类型 PersonViewModel。最终，viewModel 对象将会包含源对象 person 中的所有属性。

配置映射

在某些情况下，你可能需要显式地配置对象映射。例如，当源类型和目标类型的属性名称不匹配时，你需要告诉 AgileMapper 如何映射它们。

下面是一个示例，展示了如何使用 Mapper.WhenMapping 方法来配置映射：

using AgileObjects.AgileMapper;

var person = new Person
{
    FirstName = "John",
    LastName = "Doe",
    Age = 30
};

var viewModel = Mapper
    .WhenMapping
    .From<Person>()
    .To<PersonViewModel>()
    .Map(dest => dest.FullName)
    .To(src => $"{src.FirstName} {src.LastName}")
    .Map(dest => dest.YearsOld)
    .To(src => src.Age)
    .Map(dest => dest.IsAdult)
    .To(src => src.Age >= 18)
    .Map(dest => dest.AgeGroup)
    .To(ctx => ctx.Source.Age < 18 ? "Underage" : "Adult")
    .Map(dest => dest.DateOfBirth)
    .To(src => DateTime.Now.AddYears(-src.Age))
    .Map(dest => dest.Address)
    .To(src => $"{src.AddressLine1}, {src.City}, {src.State} {src.ZipCode}")
    .Map(dest => dest.Country)
    .To(ctx => ctx.Source.Country.ToUpper())
    .ToANew<PersonViewModel>();

在这个示例中，我们首先使用 WhenMapping 方法来指定源类型和目标类型。接着，我们使用 Map 方法来配置属性映射。

在这个示例中，我们将 FullName 属性映射到源类型的 FirstName 和 LastName 属性的组合字符串。我们还将 YearsOld 属性映射到源类型的 Age 属性，IsAdult 属性映射到 Age 属性是否大于等于 18，AgeGroup 属性映射到年龄是否小于 18，DateOfBirth 属性映射到当前时间减去 Age 年后的日期，Address 属性映射到地址的格式化字符串，Country 属性映射到源类型的 Country 属性的大写形式。

自定义映射

在某些情况下，你可能需要自定义对象的映射方式。例如，当源类型和目标类型之间存在复杂的转换逻辑时，你需要自定义映射方法。

下面是一个示例，展示了如何使用 Mapper.WhenMapping 方法来自定义映射方法：

using AgileObjects.AgileMapper;

public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public DateTime DateOfBirth { get; set; }
}

public class PersonViewModel
{
    public string FullName { get; set; }
    public int Age { get; set; }
}

var person = new Person
{
    FirstName = "John",
    LastName = "Doe",
    DateOfBirth = new DateTime(1990, 1, 1)
};

var viewModel = Mapper
    .WhenMapping
    .From<Person>()
    .To<PersonViewModel>()
    .Map(ctx => ctx.Source.FirstName + " " + ctx.Source.LastName)
    .To(dest => dest.FullName)
    .Map(ctx => DateTime.Now.Year - ctx.Source.DateOfBirth.Year)
    .To(dest => dest.Age)
    .ToANew<PersonViewModel>();

在这个示例中，我们首先使用 WhenMapping 方法来指定源类型和目标类型。接着，我们使用 Map 方法来自定义映射方法。

在这个示例中，我们将 FullName 属性映射到源类型的 FirstName 和 LastName 属性的组合字符串。我们还将 Age 属性映射到当前年份减去 DateOfBirth 属性的年份后的结果。

忽略属性

在某些情况下，你可能需要忽略对象的某些属性。例如，当你不希望将某些敏感数据映射到目标对象时，你需要忽略这些属性。

下面是一个示例，展示了如何使用 Mapper.WhenMapping 方法来忽略属性：

using AgileObjects.AgileMapper;

public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Password { get; set; }
}

public class PersonViewModel
{
    public string FullName { get; set; }
}

var person = new Person
{
    FirstName = "John",
    LastName = "Doe",
    Password = "password"
};

var viewModel = Mapper
    .WhenMapping
    .From<Person>()
    .To<PersonViewModel>()
    .Ignore(dest => dest.FullName)
    .Ignore(dest => dest.Password)
    .ToANew<PersonViewModel>();

在这个示例中，我们首先使用 WhenMapping 方法来指定源类型和目标类型。接着，我们使用 Ignore 方法来忽略属性。

在这个示例中，我们忽略了 PersonViewModel 类型的 FullName 和 Person 类型的 Password 属性。

映射集合

AgileMapper 也支持映射集合对象。你可以使用 Mapper.Map 方法映射单个对象，也可以使用 Mapper.Map 方法的重载版本来映射集合对象。

下面是一个示例，展示了如何使用 Mapper.Map 方法来映射集合对象：

using AgileObjects.AgileMapper;

public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

public class PersonViewModel
{
    public string FullName { get; set; }
}

var persons = new List<Person>
{
    new Person { FirstName = "John", LastName = "Doe" },
    new Person { FirstName = "Jane", LastName = "Doe" }
};

var viewModels = Mapper
    .Map(persons)
    .ToANew<List<PersonViewModel>>();

在这个示例中，我们首先创建了一个 Person 类型的列表对象 persons，其中包含两个 Person 对象。接着，我们使用 Mapper.Map 方法映射整个列表对象，最终得到一个 PersonViewModel 类型的列表对象 viewModels，其中包含映射后的对象。

处理空值

在某些情况下，你可能需要处理源对象中的空值。例如，当源对象中的某些属性为 null 时，你需要设置目标对象中相应的属性为默认值或空值。

下面是一个示例，展示了如何使用 Mapper.WhenMapping 方法来处理空值：

using AgileObjects.AgileMapper;

public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

public class PersonViewModel
{
    public string FullName { get; set; }
}

var person = new Person
{
    FirstName = "John",
    LastName = null
};

var viewModel = Mapper
    .WhenMapping
    .From<Person>()
    .To<PersonViewModel>()
    .Map(dest => dest.FullName)
    .To(src => $"{src.FirstName ?? string.Empty} {src.LastName ?? string.Empty}")
    .ToANew<PersonViewModel>();

在这个示例中，我们首先使用 WhenMapping 方法来指定源类型和目标类型。接着，我们使用 Map 方法来处理源对象中的空值。

在这个示例中，我们将 FullName 属性映射到源类型的 FirstName 和 LastName 属性的组合字符串。我们使用 ?? 运算符来检查属性是否为 null，如果是，则返回空字符串。这样，我们就可以防止空值导致的运行时错误。

处理异常

在某些情况下，映射过程可能会导致异常。例如，当源对象中的某些属性类型与目标对象中的属性类型不匹配时，映射过程可能会抛出异常。在这种情况下，你可以使用异常处理机制来捕获异常并处理它们。

下面是一个示例，展示了如何使用 Mapper.WhenMapping 方法来处理异常：

using AgileObjects.AgileMapper;

public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

public class PersonViewModel
{
    public int FullName { get; set; }
}

try
{
    var person = new Person
    {
        FirstName = "John",
        LastName = "Doe"
    };

    var viewModel = Mapper
        .WhenMapping
        .From<Person>()
        .To<PersonViewModel>()
        .Map(dest => dest.FullName)
        .To(src => $"{src.FirstName} {src.LastName}")
        .ToANew<PersonViewModel>();
}
catch (MappingException ex)
{
    // 处理异常
}

在这个示例中，我们首先使用 WhenMapping 方法来指定源类型和目标类型。接着，我们使用 Map 方法来配置属性映射。

在这个示例中，我们将 FullName 属性映射到源类型的 FirstName 和 LastName 属性的组合字符串。由于 PersonViewModel 类型的 FullName 属性是一个整数，而我们试图将字符串赋值给它，所以映射过程将会抛出异常。

在异常处理块中，我们可以使用 MappingException 类来捕获异常并处理它们。这样，我们就可以避免映射过程导致的运行时错误。

结论

AgileMapper 是一个功能强大的对象映射库，它提供了一种简单、灵活、强大的方式来处理对象映射。在本文中，我们介绍了 AgileMapper 的基本用法，包括配置映射、自定义映射、忽略属性、映射集合、处理空值和处理异常。我们希望这些示例可以帮助你更好地了解 AgileMapper 的使用方法，并能够在实际项目中使用它来简化对象映射过程。