ASP.NET-Routing

Eine Route ist ein URL-Muster, das einem Handler zugeordnet wird. Der Handler kann eine physische Datei sein, z. B. eine ASPX-Datei in einer Web Forms-Anwendung. Ein Handler kann auch eine Klasse sein, die die Anforderung verarbeitet, z. B. ein Controller in einer MVC-Anwendung. Zum Definieren einer Route muss eine Instanz der Route-Klasse erstellt werden, indem das URL-Muster, der Handler und optional ein Name für die Route angegeben werden.

Die Route wird der Anwendung durch Hinzufügen des Route-Objekts zur statischen Routes-Eigenschaft der RouteTable-Klasse hinzugefügt. Die Routes-Eigenschaft ist ein RouteCollection-Objekt, von dem alle Routen für die Anwendung gespeichert werden.

In der Regel muss kein Code geschrieben werden, um Routen in einer MVC-Anwendung hinzuzufügen. Visual Studio-Projektvorlagen für MVC umfassen vorkonfigurierte URL-Routen. Diese werden in der MvcApplication-Klasse definiert, die wiederum in der Datei "Global.asax" definiert wird.

Ein URL-Muster kann literale Werte und variable Platzhalter (werden als URL-Parameter bezeichnet) enthalten. Die Literale und Platzhalter befinden sich in Segmenten der URL, die durch das Schrägstrichzeichen (/) begrenzt werden.

Wenn eine Anforderung gestellt wird, wird die URL in Segmenten und Platzhaltern analysiert, und die Variablenwerte werden für den Anforderungshandler bereitgestellt. Dieser Prozess ist mit der Methode zur Analyse von Daten in Abfragezeichenfolgen und zur Weitergabe der Daten an den Anforderungshandler vergleichbar. In beiden Fällen werden Variableninformationen in die URL eingeschlossen und in der Form von Schlüssel-/Wert-Paaren an den Handler übergeben. Für Abfragezeichenfolgen sind sowohl die Schlüssel als auch die Werte in der URL enthalten. Für Routen sind die Schlüssel die im URL-Muster definierten Platzhalternamen, und nur die Werte sind in der URL enthalten.

In einem URL-Muster definieren Sie Platzhalter durch Einschließen in geschweifte Klammern ({ und }). Sie können mehrere Platzhalter in einem Segment definieren, wobei diese jedoch durch einen Literalwert getrennt werden müssen. Zum Beispiel ist {language}-{country}/{action} ein gültiges Routenmuster. {language}{country}/{action} ist jedoch kein gültiges Muster, da sich weder zwischen den Platzhaltern weder ein Literalwert noch ein Trennzeichen befindet. Daher kann das Routing nicht ermitteln, wo der Wert für den language-Platzhalter vom Wert für den country-Platzhalter getrennt werden soll.

Die folgende Tabelle zeigt gültige Routenmuster und Beispiele für URL-Anforderungen, die mit diesen Mustern übereinstimmen.

Typische URL-Muster in MVC-Anwendungen

{controller}.mvc/{action}/{id}

In einer Web Forms-Anwendung erstellen Sie Routen mit der MapPageRoute(String, String, String)-Methode der RouteCollection-Klasse. Von der MapPageRoute-Methode wird ein Route-Objekt erstellt, das anschließend dem RouteCollection-Objekt hinzugefügt wird. Sie geben Eigenschaften für das Route-Objekt in Parametern an, die Sie an die MapPageRoute-Methode übergeben.

Normalerweise fügen Sie Routen in einer Methode hinzu, die aus dem Handler für das Application_Start-Ereignis in der Datei Global.asax aufgerufen wird. Durch diese Vorgehensweise ist gewährleistet, dass die Routen beim Start der Anwendung verfügbar sind. Außerdem können Sie dadurch die Methode direkt aufrufen, wenn Sie den Komponententest für die Anwendung durchführen. Wenn Sie eine Methode beim Komponententest der Anwendung direkt aufrufen möchten, muss die Methode, mit der die Routen registriert werden, statisch sein (Shared in Visual Basic) und einen RouteCollection-Parameter enthalten.

Das folgende Beispiel zeigt Code aus einer Datei Global.asax, die ein Route-Objekt hinzufügt, das zwei URL-Parameter mit der Bezeichnung action und categoryName definiert. URLs, die das angegebene Muster besitzen, werden an die physische Seite mit dem Namen "Categories.aspx" weitergeleitet.

protected void Application_Start(object sender, EventArgs e)
{
    RegisterRoutes(RouteTable.Routes);
}

public static void RegisterRoutes(RouteCollection routes)
{
    routes.MapPageRoute("",
        "Category/{action}/{categoryName}",
        "~/categoriespage.aspx");
}

Wenn Sie die MVC-Konvention zur Implementierung von Controllern durch Erstellen von Klassen übernehmen, die von der ControllerBase-Klasse abgeleitet werden, und ihnen Namen zuweisen, die mit "Controller" enden, müssen in einer MVC-Anwendung keine Routen manuell hinzugefügt werden. Von den vorkonfigurierten Routen werden die Aktionsmethoden aufgerufen, die Sie in den Controllerklassen implementieren.

Wenn Sie benutzerdefinierte Routen in einer MVC-Anwendung hinzufügen möchten, wird die MapRoute(RouteCollection, String, String)-Methode anstelle der MapPageRoute(String, String, String)-Methode verwendet.

Im folgenden Beispiel wird der Code gezeigt, durch den in der Datei "Global.asax" standardmäßige MVC-Routen erstellt werden, gemäß der Definition in der Visual Studio-Projektvorlage für MVC-Anwendungen.

public class MvcApplication : System.Web.HttpApplication
{
    public static void RegisterRoutes(RouteCollection routes)
    {
        routes.IgnoreRoute("{resource}.axd/{*pathInfo}");

        routes.MapRoute(
            "Default",                                              // Route name
            "{controller}/{action}/{id}",                           // URL with parameters
            new { controller = "Home", action = "Index", id = "" }  // Parameter defaults
        );

    }

    protected void Application_Start()
    {
        RegisterRoutes(RouteTable.Routes);
    }
}

Wenn Sie eine Route definieren, können Sie einen Standardwert für einen Parameter zuweisen. Der Standardwert wird verwendet, wenn ein Wert für diesen Parameter nicht in der URL enthalten ist. Sie legen Standardwerte für eine Route fest, indem Sie der Defaults-Eigenschaft der Route-Klasse ein Wörterbuchobjekt zuweisen. Im folgenden Beispiel wird gezeigt, wie eine Route, die Standardwerte besitzt, mit der MapPageRoute(String, String, String, Boolean, RouteValueDictionary)-Methode hinzugefügt wird.

void Application_Start(object sender, EventArgs e) 
{
    RegisterRoutes(RouteTable.Routes);
}

public static void RegisterRoutes(RouteCollection routes)
{
    routes.MapPageRoute("",
        "Category/{action}/{categoryName}",
        "~/categoriespage.aspx",
        true,
        new RouteValueDictionary 
            {{"categoryName", "food"}, {"action", "show"}});
}

Wenn ASP.NET-Routing eine URL-Anforderung behandelt, führt die im Beispiel dargestellte Routendefinition (mit den Standardwerten food für categoryName und show für action) zu den in der folgenden Tabelle aufgeführten Ergebnissen.

Für MVC-Anwendungen ermöglichen Überladungen der RouteCollectionExtensions.MapRoute-Methode, zum Beispiel MapRoute(RouteCollection, String, String, Object, Object) die Angabe von Standardwerten.

Manchmal müssen Sie URL-Anforderungen behandeln, die eine variable Anzahl an URL-Segmenten enthalten. Beim Definieren einer Route können Sie angeben, dass, wenn eine URL mehr Segmente enthält als das Muster, die zusätzlichen Segmente als Teil des letzten Segments betrachtet werden. Um zusätzliche Segmente auf diese Weise zu behandeln, markieren Sie den letzten Parameter mit einem Sternchen (*). Dies wird als Catch-All-Parameter (Sammelparameter) bezeichnet. Eine Route mit einem Catch-All-Parameter stimmt auch mit URLs überein, die keine Werte für den letzten Parameter enthalten. Im folgenden Beispiel ist ein Routenmuster dargestellt, das mit einer unbekannten Anzahl an Segmenten übereinstimmt.

query/{queryname}/{*queryvalues}

Wenn ASP.NET-Routing eine URL-Anforderung behandelt, führt die im Beispiel dargestellte Routendefinition zu den in der folgenden Tabelle aufgeführten Ergebnissen.

Neben dem Abgleichen einer URL-Anforderung mit einer Routendefinition anhand der Anzahl der Parameter in der URL können Sie angeben, dass Werte in den Parametern bestimmte Einschränkungen erfüllen. Wenn eine URL Werte enthält, die außerhalb der Einschränkungen für eine Route liegen, wird die Route nicht zum Behandeln der Anforderung verwendet. Sie können Einschränkungen hinzufügen, damit die URL-Parameter auf jeden Fall Werte enthalten, die in Ihrer Anwendung funktionieren.

Einschränkungen werden mit regulären Ausdrücken oder mit Objekten definiert, die die IRouteConstraint-Schnittstelle implementieren. Wenn Sie der Routes-Auflistung die Routendefinition hinzufügen, fügen Sie Einschränkungen hinzu, indem Sie ein RouteValueDictionary-Objekt erstellen, das den Überprüfungstest enthält. Der Schlüssel im Wörterbuch identifiziert den Parameter, für den die Einschränkung gilt. Bei dem Wert im Wörterbuch kann es sich um eine Zeichenfolge handeln, die einen regulären Ausdruck darstellt, oder um ein Objekt, das die IRouteConstraint-Schnittstelle implementiert.

Wenn Sie eine Zeichenfolge angeben, behandelt das Routing die Zeichenfolge als regulären Ausdruck und prüft, ob der Parameterwert gültig ist, indem es die IsMatch-Methode der Regex-Klasse aufruft. Der reguläre Ausdruck wird immer so behandelt, dass nicht zwischen Groß- und Kleinschreibung unterschieden wird. Weitere Informationen hierzu finden Sie unter Reguläre Ausdrücke von .NET Framework.

Wenn Sie ein IRouteConstraint-Objekt bereitstellen, prüft ASP.NET-Routing, ob der Parameterwert gültig ist, indem es die Match-Methode des IRouteConstraint-Objekts aufruft. Die Match-Methode gibt einen booleschen Wert zurück, der angibt, ob der Parameterwert gültig ist.

Im folgenden Beispiel wird gezeigt, wie mithilfe der MapPageRoute-Methode eine Route erstellt wird, für die Einschränkungen gelten, durch die bestimmt werden, welche Werte in den locale-Parameter und den year-Parameter eingeschlossen werden können. (In einer MVC-Anwendung wird die MapRoute-Methode verwendet.)

public static void RegisterRoutes(RouteCollection routes)
{
    routes.MapPageRoute("",
        "Category/{action}/{categoryName}",
        "~/categoriespage.aspx",
        true,
        new RouteValueDictionary 
            {{"categoryName", "food"}, {"action", "show"}},
        new RouteValueDictionary 
            {{"locale", "[a-z]{2}-[a-z]{2}"},{"year", @"\d{4}"}}
       );
}

Wenn das Routing eine URL-Anforderung behandelt, erstellt die im vorherigen Beispiel dargestellte Routendefinition die in der folgenden Tabelle aufgeführten Ergebnisse.

Unter einigen Umständen behandelt ASP.NET-Routing keine Anforderung, auch wenn sie für die Website aktiviert ist. In diesem Abschnitt werden einige Szenarien beschrieben, in denen die Anforderung nicht vom Routing behandelt wird.

Eine physische Datei wird gefunden, die mit dem URL-Muster übereinstimmt

Routing wird explizit für ein URL-Muster deaktiviert.

public static void RegisterRoutes(RouteCollection routes)
{
  routes.Ignore("{resource}.axd/{*pathInfo}");
}

Wenn das Routing URL-Anforderungen behandelt, versucht es, die URL der Anforderung mit einer Route abzugleichen. Der Abgleich einer URL-Anforderung mit einer Route hängt von allen folgenden Bedingungen ab:

• Den Routenmustern, die Sie definiert haben, oder den Standardroutenmustern (sofern vorhanden), die in Ihrem Projekttyp enthalten sind.

• Der Reihenfolge, in der Sie sie der Routes-Auflistung hinzugefügt haben.

• Allen Standardwerten, die Sie für eine Route angegeben haben.

• Allen Einschränkungen, die Sie für eine Route angegeben haben.

• Ob Sie Routing definiert haben, um Anforderungen zu behandeln, die mit einer physischen Datei übereinstimmen.

Um zu vermeiden, dass der falsche Handler eine Anforderung behandelt, müssen Sie alle diese Bedingungen beim Definieren von Routen berücksichtigen. Die Reihenfolge, in der Route-Objekte in der Routes-Auflistung angezeigt werden, ist wichtig. Der Routenabgleich beginnt mit der ersten Route in der Auflistung und geht bis zur letzten Route. Wird eine Übereinstimmung gefunden, werden keine Routen mehr ausgewertet. Im Allgemeinen beginnen Sie beim Hinzufügen von Routen zur Routes-Eigenschaft mit den detailliertesten Routendefinitionen.

Angenommen, Sie fügen Routen mit den folgenden Mustern hinzu:

• Route 1 wird auf {controller}/{action}/{id} festgelegt.

• Route 2 wird auf products/show/{id} festgelegt.

Route 2 behandelt niemals eine Anforderung, da die Route 1 zuerst ausgewertet wird, und es liegen stets Übereinstimmungen mit Anforderungen vor, die auch für Route 2 gültig sind. Eine Anforderung für http://server/application/products/show/bikes scheint stärker Route 2 zu entsprechen, doch sie wird von Route 1 mit den folgenden Werten behandelt:

• controller hat den Wert products.

• action hat den Wert show.

• id hat den Wert bikes.

Wenn ein Parameter in der Anforderung fehlt, werden Standardwerte verwendet. Deshalb können sie dazu führen, dass eine Route mit einer Anforderung übereinstimmt, die Sie nicht erwartet haben. Angenommen, Sie fügen Routen mit den folgenden Mustern hinzu:

• Route 1: {report}/{year}/{month}, mit Standardwerten für year und month.

• Route 2: {report}/{year}, mit einem Standardwert für year.

Route 2 behandelt nie eine Anforderung. Route 1 könnte für einen monatlichen Bericht vorgesehen sein und Route 2 für einen Jahresbericht. Die Standardwerte in Route 1 bedeuten jedoch, dass sie mit jeder Anforderung übereinstimmt, die auch für Route 2 möglich wäre.

Sie können Mehrdeutigkeit in den Mustern vermeiden, indem Sie Konstanten aufnehmen, z. B. annual/{report}/{year} und monthly/{report}/{year}/{month}.

Wenn eine URL mit keinem Route-Objekt übereinstimmt, das in der RouteTable-Auflistung definiert ist, verarbeitet ASP.NET-Routing die Anforderung nicht. Stattdessen wird die Verarbeitung an eine ASP.NET-Seite, einen Webdienst oder einen anderen ASP.NET-Endpunkt übergeben.

Wenn Sie Links zu Seiten auf der Website erstellen möchten, können Sie mit den URL-Mustern programmgesteuert URLs erstellen, die den Routen entsprechen. Wenn Sie die Muster ändern, werden automatisch URLs generiert, die den neuen Mustern entsprechen. Informationen zum Generieren von URLs in Code oder Markup finden Sie unter Gewusst wie: Erstellen von URLs aus Routen.

Im Handler für eine weitergeleitete Seitenanforderung können Sie auf die Werte zugreifen, die in den URL-Platzhaltern mit Code oder Markup übergeben werden. Weitere Informationen finden Sie unter Gewusst wie: Zugreifen auf URL-Parameter auf einer weitergeleiteten Seite.

Für MVC-Anwendungen behandelt das MVC-Framework automatisch die Werte, die in URL-Platzhaltern übergeben werden. Weitere Informationen finden Sie unter Übergeben von Daten in einer ASP.NET-MVC-Anwendung.

Autorisierungsregeln können nur für die Routen-URL oder sowohl für die Routen-URL als auch die physische URL, der sie zugeordnet ist, übernommen werden. In Autorisierungsregeln kann z. B. angegeben werden, dass alle Benutzer auf URLs zugreifen können, die mit Category beginnen, jedoch nur Administratoren auf die Seite "Categories.aspx" zugreifen dürfen. Wenn das Muster der Routen-URL contoso.com/Categoriespage.aspx der physischen URL contoso.com/Category/{controller}/{action} zugeordnet wird und Autorisierungsregeln nur auf die Routen-URL angewendet werden, dürfen alle Benutzer auf "Categoriespage.aspx" zugreifen, wenn die Datei mit einer Routen-URL angefordert wird. Allerdings besitzen nur Administratoren Zugriff auf die Datei, wenn sie mithilfe einer physischen URL angefordert wird.

Standardmäßig werden Autorisierungsregeln sowohl auf die Routen-URL als auch auf die physische URL angewendet. Weitere Informationen finden Sie in den Ausführungen zur PageRouteHandler.CheckPhysicalUrlAccess-Eigenschaft.

In der folgenden Tabelle sind die wichtigsten Serverklassen für ASP.NET-Routing aufgeführt.

ASP.NET-Routing unterscheidet sich vom Überschreiben von URLs. Das Überschreiben von URLs verarbeitet eingehende Anforderungen, indem die URL geändert wird, bevor die Anforderung an die Webseite gesendet wird. Zum Beispiel könnte eine Anwendung, die das Überschreiben von URLs verwendet, eine URL von /Products/Widgets/ in /Products.aspx?id=4 ändern. Ebenso gibt es beim Überschreiben von URLs in der Regel keine API zum Erstellen von URLs, die auf Ihren Mustern basieren. Wenn Sie beim Überschreiben von URLs ein URL-Muster ändern, müssen Sie alle Links, die die ursprüngliche URL enthalten, manuell aktualisieren.

Mit ASP.NET-Routing wird die URL nicht geändert, wenn eine eingehende Anforderung verarbeitet wird, da das Routing Werte aus der URL extrahieren kann. Wenn Sie eine URL erstellen müssen, übergeben Sie Parameterwerte in eine Methode, die die URL für Sie generiert. Um das URL-Muster zu ändern, ändern Sie es an einem Speicherort. Alle Links, die Sie in der Anwendung erstellen und die auf diesem Muster basieren, verwenden automatisch das neue Muster.

Aufgaben

Referenz

Konzepte

Weitere Ressourcen