扩展方法（C# 编程指南）Extension Methods (C# Programming Guide)

扩展方法使你能够向现有类型“添加”方法，而无需创建新的派生类型、重新编译或以其他方式修改原始类型。Extension methods enable you to "add" methods to existing types without creating a new derived type, recompiling, or otherwise modifying the original type. 扩展方法是一种静态方法，但可以像扩展类型上的实例方法一样进行调用。Extension methods are static methods, but they're called as if they were instance methods on the extended type. 对于用 C#、F# 和 Visual Basic 编写的客户端代码，调用扩展方法与调用在类型中定义的方法没有明显区别。For client code written in C#, F# and Visual Basic, there's no apparent difference between calling an extension method and the methods defined in a type.

最常见的扩展方法是 LINQ 标准查询运算符，它将查询功能添加到现有的 System.Collections.IEnumerable 和 System.Collections.Generic.IEnumerable<T> 类型。The most common extension methods are the LINQ standard query operators that add query functionality to the existing System.Collections.IEnumerable and System.Collections.Generic.IEnumerable<T> types. 若要使用标准查询运算符，请先使用 using System.Linq 指令将它们置于范围中。To use the standard query operators, first bring them into scope with a using System.Linq directive. 然后，任何实现了 IEnumerable<T> 的类型看起来都具有 GroupBy、OrderBy、Average 等实例方法。Then any type that implements IEnumerable<T> appears to have instance methods such as GroupBy, OrderBy, Average, and so on. 在 IEnumerable<T> 类型的实例（如 List<T> 或 Array）后键入“dot”时，可以在 IntelliSense 语句完成中看到这些附加方法。You can see these additional methods in IntelliSense statement completion when you type "dot" after an instance of an IEnumerable<T> type such as List<T> or Array.

OrderBy 示例OrderBy Example

下面的示例演示如何对一个整数数组调用标准查询运算符 OrderBy 方法。The following example shows how to call the standard query operator OrderBy method on an array of integers. 括号里面的表达式是一个 lambda 表达式。The expression in parentheses is a lambda expression. 很多标准查询运算符采用 Lambda 表达式作为参数，但这不是扩展方法的必要条件。Many standard query operators take lambda expressions as parameters, but this isn't a requirement for extension methods. 有关详细信息，请参阅 Lambda 表达式。For more information, see Lambda Expressions.

class ExtensionMethods2
{

    static void Main()
    {
        int[] ints = { 10, 45, 15, 39, 21, 26 };
        var result = ints.OrderBy(g => g);
        foreach (var i in result)
        {
            System.Console.Write(i + " ");
        }
    }
}
//Output: 10 15 21 26 39 45

扩展方法被定义为静态方法，但它们是通过实例方法语法进行调用的。Extension methods are defined as static methods but are called by using instance method syntax. 它们的第一个参数指定方法操作的类型。Their first parameter specifies which type the method operates on. 参数前面是此修饰符。The parameter is preceded by the this modifier. 仅当你使用 using 指令将命名空间显式导入到源代码中之后，扩展方法才位于范围中。Extension methods are only in scope when you explicitly import the namespace into your source code with a using directive.

下面的示例演示为 System.String 类定义的一个扩展方法。The following example shows an extension method defined for the System.String class. 它是在非嵌套的、非泛型静态类内部定义的：It's defined inside a non-nested, non-generic static class:

namespace ExtensionMethods
{
    public static class MyExtensions
    {
        public static int WordCount(this String str)
        {
            return str.Split(new char[] { ' ', '.', '?' },
                             StringSplitOptions.RemoveEmptyEntries).Length;
        }
    }
}

可使用此 WordCount 指令将 using 扩展方法置于范围中：The WordCount extension method can be brought into scope with this using directive:

using ExtensionMethods;

而且，可以使用以下语法从应用程序中调用该扩展方法：And it can be called from an application by using this syntax:

string s = "Hello Extension Methods";
int i = s.WordCount();

在代码中，可以使用实例方法语法调用该扩展方法。You invoke the extension method in your code with instance method syntax. 编译器生成的中间语言 (IL) 会将代码转换为对静态方法的调用。The intermediate language (IL) generated by the compiler translates your code into a call on the static method. 并未真正违反封装原则。The principle of encapsulation is not really being violated. 扩展方法无法访问它们所扩展的类型中的专用变量。Extension methods cannot access private variables in the type they are extending.

有关详细信息，请参阅如何实现和调用自定义扩展方法。For more information, see How to implement and call a custom extension method.

通常，你更多时候是调用扩展方法而不是实现你自己的扩展方法。In general, you'll probably be calling extension methods far more often than implementing your own. 由于扩展方法是使用实例方法语法调用的，因此不需要任何特殊知识即可从客户端代码中使用它们。Because extension methods are called by using instance method syntax, no special knowledge is required to use them from client code. 若要为特定类型启用扩展方法，只需为在其中定义这些方法的命名空间添加 using 指令。To enable extension methods for a particular type, just add a using directive for the namespace in which the methods are defined. 例如，若要使用标准查询运算符，请将此 using 指令添加到代码中：For example, to use the standard query operators, add this using directive to your code:

using System.Linq;

（你可能还必须添加对 System.Core.dll 的引用。）你将注意到，标准查询运算符现在作为可供大多数 IEnumerable<T> 类型使用的附加方法显示在 IntelliSense 中。(You may also have to add a reference to System.Core.dll.) You'll notice that the standard query operators now appear in IntelliSense as additional methods available for most IEnumerable<T> types.

在编译时绑定扩展方法Binding Extension Methods at Compile Time

可以使用扩展方法来扩展类或接口，但不能重写扩展方法。You can use extension methods to extend a class or interface, but not to override them. 与接口或类方法具有相同名称和签名的扩展方法永远不会被调用。An extension method with the same name and signature as an interface or class method will never be called. 编译时，扩展方法的优先级总是比类型本身中定义的实例方法低。At compile time, extension methods always have lower priority than instance methods defined in the type itself. 换句话说，如果某个类型具有一个名为 Process(int i) 的方法，而你有一个具有相同签名的扩展方法，则编译器总是绑定到该实例方法。In other words, if a type has a method named Process(int i), and you have an extension method with the same signature, the compiler will always bind to the instance method. 当编译器遇到方法调用时，它首先在该类型的实例方法中寻找匹配的方法。When the compiler encounters a method invocation, it first looks for a match in the type's instance methods. 如果未找到任何匹配方法，编译器将搜索为该类型定义的任何扩展方法，并且绑定到它找到的第一个扩展方法。If no match is found, it will search for any extension methods that are defined for the type, and bind to the first extension method that it finds. 下面的示例演示编译器如何确定要绑定到哪个扩展方法或实例方法。The following example demonstrates how the compiler determines which extension method or instance method to bind to.

示例Example

下面的示例演示 C# 编译器在确定是将方法调用绑定到类型上的实例方法还是绑定到扩展方法时所遵循的规则。The following example demonstrates the rules that the C# compiler follows in determining whether to bind a method call to an instance method on the type, or to an extension method. 静态类 Extensions 包含为任何实现了 IMyInterface 的类型定义的扩展方法。The static class Extensions contains extension methods defined for any type that implements IMyInterface. 类 A、B 和 C 都实现了该接口。Classes A, B, and C all implement the interface.

MethodB 扩展方法永远不会被调用，因为它的名称和签名与这些类已经实现的方法完全匹配。The MethodB extension method is never called because its name and signature exactly match methods already implemented by the classes.

如果编译器找不到具有匹配签名的实例方法，它会绑定到匹配的扩展方法（如果存在这样的方法）。When the compiler can't find an instance method with a matching signature, it will bind to a matching extension method if one exists.

// Define an interface named IMyInterface.
namespace DefineIMyInterface
{
    using System;

    public interface IMyInterface
    {
        // Any class that implements IMyInterface must define a method
        // that matches the following signature.
        void MethodB();
    }
}

// Define extension methods for IMyInterface.
namespace Extensions
{
    using System;
    using DefineIMyInterface;

    // The following extension methods can be accessed by instances of any
    // class that implements IMyInterface.
    public static class Extension
    {
        public static void MethodA(this IMyInterface myInterface, int i)
        {
            Console.WriteLine
                ("Extension.MethodA(this IMyInterface myInterface, int i)");
        }

        public static void MethodA(this IMyInterface myInterface, string s)
        {
            Console.WriteLine
                ("Extension.MethodA(this IMyInterface myInterface, string s)");
        }

        // This method is never called in ExtensionMethodsDemo1, because each
        // of the three classes A, B, and C implements a method named MethodB
        // that has a matching signature.
        public static void MethodB(this IMyInterface myInterface)
        {
            Console.WriteLine
                ("Extension.MethodB(this IMyInterface myInterface)");
        }
    }
}

// Define three classes that implement IMyInterface, and then use them to test
// the extension methods.
namespace ExtensionMethodsDemo1
{
    using System;
    using Extensions;
    using DefineIMyInterface;

    class A : IMyInterface
    {
        public void MethodB() { Console.WriteLine("A.MethodB()"); }
    }

    class B : IMyInterface
    {
        public void MethodB() { Console.WriteLine("B.MethodB()"); }
        public void MethodA(int i) { Console.WriteLine("B.MethodA(int i)"); }
    }

    class C : IMyInterface
    {
        public void MethodB() { Console.WriteLine("C.MethodB()"); }
        public void MethodA(object obj)
        {
            Console.WriteLine("C.MethodA(object obj)");
        }
    }

    class ExtMethodDemo
    {
        static void Main(string[] args)
        {
            // Declare an instance of class A, class B, and class C.
            A a = new A();
            B b = new B();
            C c = new C();

            // For a, b, and c, call the following methods:
            //      -- MethodA with an int argument
            //      -- MethodA with a string argument
            //      -- MethodB with no argument.

            // A contains no MethodA, so each call to MethodA resolves to
            // the extension method that has a matching signature.
            a.MethodA(1);           // Extension.MethodA(IMyInterface, int)
            a.MethodA("hello");     // Extension.MethodA(IMyInterface, string)

            // A has a method that matches the signature of the following call
            // to MethodB.
            a.MethodB();            // A.MethodB()

            // B has methods that match the signatures of the following
            // method calls.
            b.MethodA(1);           // B.MethodA(int)
            b.MethodB();            // B.MethodB()

            // B has no matching method for the following call, but
            // class Extension does.
            b.MethodA("hello");     // Extension.MethodA(IMyInterface, string)

            // C contains an instance method that matches each of the following
            // method calls.
            c.MethodA(1);           // C.MethodA(object)
            c.MethodA("hello");     // C.MethodA(object)
            c.MethodB();            // C.MethodB()
        }
    }
}
/* Output:
    Extension.MethodA(this IMyInterface myInterface, int i)
    Extension.MethodA(this IMyInterface myInterface, string s)
    A.MethodB()
    B.MethodA(int i)
    B.MethodB()
    Extension.MethodA(this IMyInterface myInterface, string s)
    C.MethodA(object obj)
    C.MethodA(object obj)
    C.MethodB()
 */

常见使用模式Common Usage Patterns

集合功能Collection Functionality

过去，创建”集合类”通常是为了使给定类型实现 System.Collections.Generic.IEnumerable<T> 接口，并实现对该类型集合的功能。In the past, it was common to create "Collection Classes" that implemented the System.Collections.Generic.IEnumerable<T> interface for a given type and contained functionality that acted on collections of that type. 创建这种类型的集合对象没有任何问题，但也可以通过对 System.Collections.Generic.IEnumerable<T> 使用扩展来实现相同的功能。While there's nothing wrong with creating this type of collection object, the same functionality can be achieved by using an extension on the System.Collections.Generic.IEnumerable<T>. 扩展的优势是允许从任何集合（如 System.Array 或实现该类型 System.Collections.Generic.IEnumerable<T> 的 System.Collections.Generic.List<T>）调用功能。Extensions have the advantage of allowing the functionality to be called from any collection such as an System.Array or System.Collections.Generic.List<T> that implements System.Collections.Generic.IEnumerable<T> on that type. 可以在本文前面的内容中找到使用 Int32 的数组的示例。An example of this using an Array of Int32 can be found earlier in this article.

特定于层的功能Layer-Specific Functionality

使用洋葱架构或其他分层应用程序设计时，通常具有一组域实体或数据传输对象，可用于跨应用程序边界进行通信。When using an Onion Architecture or other layered application design, it's common to have a set of Domain Entities or Data Transfer Objects that can be used to communicate across application boundaries. 这些对象通常不包含任何功能，或者只包含适用于应用程序的所有层的最少功能。These objects generally contain no functionality, or only minimal functionality that applies to all layers of the application. 使用扩展方法可以添加特定于每个应用程序层的功能，而无需使用其他层中不需要的方法来向下加载对象。Extension methods can be used to add functionality that is specific to each application layer without loading the object down with methods not needed or wanted in other layers.

public class DomainEntity
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

static class DomainEntityExtensions
{
    static string FullName(this DomainEntity value)
        => $"{value.FirstName} {value.LastName}";
}

扩展预定义类型Extending Predefined Types

当需要创建可重用功能时，我们无需创建新对象，而是可以扩展现有类型，例如 .NET 或 CLR 类型。Rather than creating new objects when reusable functionality needs to be created, we can often extend an existing type, such as a .NET or CLR type. 例如，如果不使用扩展方法，我们可能会创建 Engine 或 Query 类，对可从代码中的多个位置调用的 SQL Server 执行查询。As an example, if we don't use extension methods, we might create an Engine or Query class to do the work of executing a query on a SQL Server that may be called from multiple places in our code. 但是，如果换做使用扩展方法扩展 System.Data.SqlClient.SqlConnection 类，就可以从与 SQL Server 连接的任何位置执行该查询。However we can instead extend the System.Data.SqlClient.SqlConnection class using extension methods to perform that query from anywhere we have a connection to a SQL Server. 一些其他示例可能是向 System.String 类添加常见功能、扩展 System.IO.File、System.IO.Stream 以及 System.Exception 对象的数据处理功能以实现特定的错误处理功能。Other examples might be to add common functionality to the System.String class, extend the data processing capabilities of the System.IO.File and System.IO.Stream objects, and System.Exception objects for specific error handling functionality. 这些用例的类型仅受想象力和判断力的限制。These types of use-cases are limited only by your imagination and good sense.

使用 struct 类型扩展预定义类型可能很困难，因为它们已通过值传递给方法。Extending predefined types can be difficult with struct types because they're passed by value to methods. 这意味着将对结构的副本进行任何结构更改。That means any changes to the struct are made to a copy of the struct. 扩展方法退出后，将不显示这些更改。Those changes aren't visible once the extension method exits. 从 C# 7.2 开始，可以将 ref 修饰符添加到扩展方法的第一个参数。Beginning with C# 7.2, you can add the ref modifier to the first argument of an extension method. 添加 ref 修饰符意味着第一个参数是通过引用传递的。Adding the ref modifier means the first argument is passed by reference. 在这种情况下，可以编写扩展方法来更改要扩展的结构的状态。This enables you to write extension methods that change the state of the struct being extended.

通用准则General Guidelines

尽管通过修改对象的代码来添加功能，或者在合理和可行的情况下派生新类型等方式仍是可取的，但扩展方法已成为在整个 .NET 生态系统中创建可重用功能的关键选项。While it's still considered preferable to add functionality by modifying an object's code or deriving a new type whenever it's reasonable and possible to do so, extension methods have become a crucial option for creating reusable functionality throughout the .NET ecosystem. 对于原始源不受控制、派生对象不合适或不可用，或者不应在功能适用范围之外公开功能的情况，扩展方法是一个不错的选择。For those occasions when the original source isn't under your control, when a derived object is inappropriate or impossible, or when the functionality shouldn't be exposed beyond its applicable scope, Extension methods are an excellent choice.

有关派生类型的详细信息，请参阅继承。For more information on derived types, see Inheritance.

在使用扩展方法来扩展你无法控制其源代码的类型时，你需要承受该类型实现中的更改会导致扩展方法失效的风险。When using an extension method to extend a type whose source code you aren't in control of, you run the risk that a change in the implementation of the type will cause your extension method to break.

如果确实为给定类型实现了扩展方法，请记住以下几点：If you do implement extension methods for a given type, remember the following points:

  • 如果扩展方法与该类型中定义的方法具有相同的签名，则扩展方法永远不会被调用。An extension method will never be called if it has the same signature as a method defined in the type.
  • 在命名空间级别将扩展方法置于范围中。Extension methods are brought into scope at the namespace level. 例如，如果你在一个名为 Extensions 的命名空间中具有多个包含扩展方法的静态类，则这些扩展方法将全部由 using Extensions; 指令置于范围中。For example, if you have multiple static classes that contain extension methods in a single namespace named Extensions, they'll all be brought into scope by the using Extensions; directive.

针对已实现的类库，不应为了避免程序集的版本号递增而使用扩展方法。For a class library that you implemented, you shouldn't use extension methods to avoid incrementing the version number of an assembly. 如果要向你拥有源代码的库中添加重要功能，请遵循适用于程序集版本控制的 .NET 准则。If you want to add significant functionality to a library for which you own the source code, follow the .NET guidelines for assembly versioning. 有关详细信息，请参阅程序集版本控制。For more information, see Assembly Versioning.

请参阅See also