Erweiterungsmethoden (C#-Programmierhandbuch)Extension Methods (C# Programming Guide)

Mit Erweiterungsmethoden können Sie vorhandenen Typen Methoden hinzufügen, ohne einen neuen abgeleiteten Typ zu erstellen und ohne den ursprünglichen Typ neu kompilieren oder auf andere Weise bearbeiten zu müssen.Extension methods enable you to "add" methods to existing types without creating a new derived type, recompiling, or otherwise modifying the original type. Erweiterungsmethoden sind statische Methoden, die Sie jedoch wie Instanzmethoden für den erweiterten Typ aufrufen können.Extension methods are static methods, but they're called as if they were instance methods on the extended type. Für in C#, F# und Visual Basic geschriebenen Clientcode gibt es keinen sichtbaren Unterschied zwischen dem Aufrufen einer Erweiterungsmethode und den in einem Typ definierten Methoden.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.

Die häufigsten Erweiterungsmethoden sind die LINQ-Standardabfrageoperatoren, die vorhandenen System.Collections.IEnumerable- und System.Collections.Generic.IEnumerable<T>-Typen Funktionalität hinzufügen.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. Um die Standardabfrageoperatoren zu verwenden, müssen Sie sie zuerst mit einer using System.Linq-Direktive einbinden.To use the standard query operators, first bring them into scope with a using System.Linq directive. Jeder Typ, der IEnumerable<T> implementiert, scheint Instanzmethoden zu haben, wie z. B. GroupBy, OrderBy, Average.Then any type that implements IEnumerable<T> appears to have instance methods such as GroupBy, OrderBy, Average, and so on. Sie können diese zusätzlichen Methoden in der IntelliSense-Anweisungsvervollständigung sehen, wenn Sie nach einer Instanz eines IEnumerable<T>-Typs, z.B. List<T> oder Array, "dot" eingeben.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-BeispielOrderBy Example

Das folgende Beispiel zeigt, wie Sie die Standardabfrageoperator-Methode OrderBy für ein Ganzzahlarray aufrufen können.The following example shows how to call the standard query operator OrderBy method on an array of integers. Der Ausdruck in Klammern ist ein Lambda-Ausdruck.The expression in parentheses is a lambda expression. Viele Standardabfrageoperatoren verwenden Lambda-Ausdrücke als Parameter, dies ist jedoch keine Voraussetzung für Erweiterungsmethoden.Many standard query operators take lambda expressions as parameters, but this isn't a requirement for extension methods. Weitere Informationen finden Sie unter Lambdaausdrücke.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

Erweiterungsmethoden werden als statische Methoden definiert, jedoch mithilfe einer Instanzmethodensyntax aufgerufen.Extension methods are defined as static methods but are called by using instance method syntax. Ihr erster Parameter gibt an, für welchen Typ die Methode aufgerufen wird.Their first parameter specifies which type the method operates on. Dem Parameter wird der this-Modifizierer vorangestellt.The parameter is preceded by the this modifier. Erweiterungsmethoden befinden sich nur dann im Bereich, wenn Sie den Namespace explizit mit einer using-Direktive in Ihren Quellcode importieren.Extension methods are only in scope when you explicitly import the namespace into your source code with a using directive.

Im folgenden Beispiel wird eine für die System.String-Klasse definierte Erweiterungsmethode veranschaulicht.The following example shows an extension method defined for the System.String class. Die Definition erfolgt in einer nicht geschachtelten, nicht generischen statischen Klasse: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;
        }
    }
}

Die WordCount-Erweiterungsmethode kann mit dieser using-Direktive eingebunden werden:The WordCount extension method can be brought into scope with this using directive:

using ExtensionMethods;

Sie kann darüber hinaus mit dieser Syntax von einer Anwendung aufgerufen werden:And it can be called from an application by using this syntax:

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

Sie rufen die Erweiterungsmethode im Code mit Instanzmethodensyntax auf.You invoke the extension method in your code with instance method syntax. Die vom Compiler erstellte Intermediate Language (IL) übersetzt Ihren Code in einen Aufruf der statischen Methode.The intermediate language (IL) generated by the compiler translates your code into a call on the static method. Es wird nicht wirklich gegen das Prinzip der Kapselung verstoßen.The principle of encapsulation is not really being violated. Erweiterungsmethoden können nicht auf private Variablen im Typ zugreifen, den sie erweitern.Extension methods cannot access private variables in the type they are extending.

Weitere Informationen finden Sie unter Vorgehensweise: Implementieren und Aufrufen einer benutzerdefinierten Erweiterungsmethode.For more information, see How to implement and call a custom extension method.

Im Allgemeinen rufen Sie vermutlich sehr viel häufiger Erweiterungsmethoden auf, als eigene Methoden zu implementieren.In general, you'll probably be calling extension methods far more often than implementing your own. Da Erweiterungsmethoden mit der Instanzmethodensyntax aufgerufen werden, sind für ihren Einsatz aus dem Clientcode keine besonderen Kenntnisse erforderlich.Because extension methods are called by using instance method syntax, no special knowledge is required to use them from client code. Um Erweiterungsmethoden für einen bestimmten Typ zu aktivieren, fügen Sie eine using-Direktive für den Namespace, in dem die Methoden definiert werden, hinzu.To enable extension methods for a particular type, just add a using directive for the namespace in which the methods are defined. Um beispielsweise die Standardabfrageoperatoren zu verwenden, fügen Sie diese using-Direktive dem Code hinzu:For example, to use the standard query operators, add this using directive to your code:

using System.Linq;

(Möglicherweise müssen Sie auch einen Verweis auf System.Core.dll hinzufügen.) Wie Sie sehen, werden die Standardabfrageoperatoren in IntelliSense jetzt für die meisten IEnumerable<T>-Typen als zusätzliche Methoden angezeigt.(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.

Binden von Erweiterungsmethoden während der KompilierungBinding Extension Methods at Compile Time

Sie können Erweiterungsmethoden verwenden, um eine Klasse oder eine Schnittstelle zu erweitern, jedoch nicht, um sie zu überschreiben.You can use extension methods to extend a class or interface, but not to override them. Eine Erweiterungsmethode mit dem gleichen Namen und der gleichen Signatur wie eine Schnittstellen- oder Klassenmethode wird nie aufgerufen.An extension method with the same name and signature as an interface or class method will never be called. Bei der Kompilierung verfügen Erweiterungsmethoden immer über niedrigere Priorität als im Typ selbst definierte Instanzmethoden.At compile time, extension methods always have lower priority than instance methods defined in the type itself. Das heißt, wenn ein Typ eine Methode mit dem Namen Process(int i) hat und Sie über eine Erweiterungsmethode mit der gleichen Signatur verfügen, stellt der Compiler immer eine Bindung mit der Instanzmethode her.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. Wenn der Compiler einen Methodenaufruf erkennt, sucht er zuerst nach einer Entsprechung in den Instanzmethoden des Typs.When the compiler encounters a method invocation, it first looks for a match in the type's instance methods. Wenn keine Entsprechung gefunden wird, sucht er nach Erweiterungsmethoden, die für den Typ definiert wurden, und stellt eine Bindung mit der ersten gefundenen Erweiterungsmethode her.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. Im folgenden Beispiel wird veranschaulicht, wie der Compiler bestimmt, mit welcher Erweiterungsmethode oder Instanzmethode die Bindung erfolgen soll.The following example demonstrates how the compiler determines which extension method or instance method to bind to.

BeispielExample

Das folgende Beispiel veranschaulicht die Regeln, denen der C#-Compiler folgt, um zu bestimmen, ob ein Methodenaufruf an eine Instanzmethode für den Typ oder an eine Erweiterungsmethode gebunden werden soll.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. Die statische Klasse Extensions enthält Erweiterungsmethoden, die für jeden Typ definiert wurden, der IMyInterface implementiert.The static class Extensions contains extension methods defined for any type that implements IMyInterface. Die Klassen A, B und C implementieren alle die Schnittstelle.Classes A, B, and C all implement the interface.

Die MethodB-Erweiterungsmethode wird nie aufgerufen, da ihr Name und die Signatur genau mit Methoden übereinstimmen, die bereits von den Klassen implementiert wurden.The MethodB extension method is never called because its name and signature exactly match methods already implemented by the classes.

Wenn der Compiler keine Instanzmethode mit einer entsprechenden Signatur findet, stellt er eine Bindung mit einer entsprechenden Erweiterungsmethode her (sofern vorhanden).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()
 */

Gängige VerwendungsmusterCommon Usage Patterns

AuflistungsfunktionenCollection Functionality

In der Vergangenheit war es üblich, „Sammlungsklassen“ zu erstellen, mit denen die System.Collections.Generic.IEnumerable<T>-Schnittstelle für einen bestimmten Typ implementiert und Funktionalität für Sammlungen dieses Typs bereitgestellt wurde.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. Es ist zwar nichts Falsches daran, diese Art von Sammlungsobjekten zu erstellen, aber die gleiche Funktionalität kann durch eine Erweiterung von System.Collections.Generic.IEnumerable<T> erreicht werden.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>. Erweiterungen haben den Vorteil, dass die Funktionalität aus einer beliebigen Sammlung – z. B. System.Array oder System.Collections.Generic.List<T> – aufgerufen werden kann, die System.Collections.Generic.IEnumerable<T> für diesen Typ implementiert.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. Ein entsprechendes Beispiel mit Verwendung eines Int32-Arrays finden Sie weiter oben in diesem Artikel.An example of this using an Array of Int32 can be found earlier in this article.

Ebenenspezifische FunktionalitätLayer-Specific Functionality

Bei Verwendung einer Zwiebelarchitektur oder eines anderen geschichteten Anwendungsdesigns ist es üblich, einen Satz mit Domänenentitäten oder Datenübertragungsobjekten für die Kommunikation über Anwendungsgrenzen hinweg zu verwenden.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. Diese Objekte umfassen in der Regel keine oder nur minimale Funktionalität, die für alle Ebenen der Anwendung gilt.These objects generally contain no functionality, or only minimal functionality that applies to all layers of the application. Erweiterungsmethoden können verwendet werden, um Funktionalität hinzuzufügen, die für jede Anwendungsschicht spezifisch ist, ohne das Objekt mit Methoden zu überladen, die in anderen Ebenen nicht benötigt werden oder unerwünscht sind.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}";
}

Erweiterung von vordefinierten TypenExtending Predefined Types

Wenn wiederverwendbare Funktionalität erstellt werden muss, kann statt der Erstellung neuer Objekte häufig ein bereits vorhandener Typ erweitert werden, z. B. ein .NET- oder CLR-Typ.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. Wenn beispielsweise keine Erweiterungsmethoden verwendet werden, könnten wir eine Engine- oder Query-Klasse zum Ausführen einer Abfrage auf einer SQL Server-Instanz erstellen, die über mehrere Stellen in unserem Code aufgerufen werden kann.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. Stattdessen können wir jedoch die Klasse System.Data.SqlClient.SqlConnection mithilfe von Erweiterungsmethoden erweitern, damit diese Abfrage von jedem beliebigen Ort ausgeführt werden kann, an dem eine Verbindung mit einer SQL Server-Instanz vorhanden ist.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. Weitere Beispiele wären das Hinzufügen gemeinsamer Funktionalität zur Klasse System.String, eine Erweiterung der Datenverarbeitungsfunktionalität der Objekte System.IO.File und System.IO.Stream sowie System.Exception-Objekte für eine spezifische Fehlerbehandlungsfunktionalität.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. Der Verwendung dieser Anwendungsfälle sind praktisch keine Grenzen gesetzt.These types of use-cases are limited only by your imagination and good sense.

Das Erweitern vordefinierter Typen kann bei struct-Typen schwierig sein, da sie als Wert an Methoden übergeben werden.Extending predefined types can be difficult with struct types because they're passed by value to methods. Dies bedeutet, dass alle Änderungen an der Struktur an einer Kopie der Struktur vorgenommen werden.That means any changes to the struct are made to a copy of the struct. Diese Änderungen sind nicht sichtbar, nachdem die Erweiterungsmethode beendet wurde.Those changes aren't visible once the extension method exits. Ab C# 7.2 können Sie dem ersten Argument einer Erweiterungsmethode den ref-Modifizierer hinzufügen.Beginning with C# 7.2, you can add the ref modifier to the first argument of an extension method. Durch das Hinzufügen des ref-Modifizierers wird das erste Argument als Verweis übergeben.Adding the ref modifier means the first argument is passed by reference. Auf diese Weise können Sie Erweiterungsmethoden schreiben, die den Status der erweiterten Struktur ändern.This enables you to write extension methods that change the state of the struct being extended.

Allgemeine RichtlinienGeneral Guidelines

Wenngleich es weiterhin vorzuziehen ist, Funktionalität durch Änderung des Codes eines Objekts oder durch Ableitung eines neuen Typs hinzuzufügen – sofern dies sinnvoll und möglich ist –, sind Erweiterungsmethoden zu einer wichtigen Option zum Bereitstellen wiederverwendbarer Funktionalität im gesamten .NET-Ökosystem geworden.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. In Fällen, in denen die ursprüngliche Quelle nicht Ihrer Kontrolle unterliegt, ein abgeleitetes Objekt ungeeignet ist oder nicht verwendet werden kann oder die Funktionalität nicht über den anwendbaren Bereich hinaus offengelegt werden soll, stellen Erweiterungsmethoden eine ausgezeichnete Wahl dar.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.

Weitere Informationen zu abgeleiteten Typen finden Sie unter Vererbung.For more information on derived types, see Inheritance.

Wenn Sie eine Erweiterungsmethode zum Erweitern eines Typs verwenden, dessen Quellcode Sie nicht ändern können, laufen Sie Gefahr, dass eine Änderung an der Implementierung des Typs zu einer Beschädigung Ihrer Erweiterungsmethode führt.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.

Wenn Sie Erweiterungsmethoden für einen gegebenen Typ implementieren, beachten Sie die folgenden Punkte:If you do implement extension methods for a given type, remember the following points:

  • Eine Erweiterungsmethode wird nie aufgerufen, wenn sie die gleiche Signatur wie eine im Typ definierte Methode hat.An extension method will never be called if it has the same signature as a method defined in the type.
  • Erweiterungsmethoden werden auf Namespace-Ebene eingebunden.Extension methods are brought into scope at the namespace level. Wenn Sie z. B. über mehrere statische Klassen verfügen, die Erweiterungsmethoden in einem einzelnen Namespace mit dem Namen Extensions enthalten, werden sie alle mit der using Extensions;-Direktive eingebunden.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.

Für eine Klassenbibliothek, die Sie implementiert haben, sollten Sie keine Erweiterungsmethoden verwenden, um zu vermeiden, dass die Versionsnummer einer Assembly erhöht wird.For a class library that you implemented, you shouldn't use extension methods to avoid incrementing the version number of an assembly. Wenn Sie zu einer Bibliothek, deren Quellcode Sie besitzen, wichtige Funktionalität hinzufügen möchten, befolgen Sie die .NET-Richtlinien für Assemblyversionierung.If you want to add significant functionality to a library for which you own the source code, follow the .NET guidelines for assembly versioning. Weitere Informationen dazu finden Sie unter Assemblyversionen.For more information, see Assembly Versioning.

Siehe auchSee also