Arbeiten mit dem Anwendungsmodell in ASP.NET Core

Von Steve Smith

ASP.NET Core MVC definiert ein Anwendungsmodell, in dem die Komponenten einer MVC-App dargestellt werden. Lesen und bearbeiten Sie dieses Modell, um das Verhalten von MVC-Elementen zu ändern. MVC folgt standardmäßig bestimmten Konventionen, um zu ermitteln, welche Klassen als Controller betrachtet werden, welche Methoden in diesen Klassen Aktionen darstellen und wie sich Parameter und das Routing verhalten. Passen Sie dieses Verhalten an die Anforderungen Ihrer App an, indem Sie Ihre eigenen Konventionen schaffen und sie global oder in Form von Attributen anwenden.

Modelle und Anbieter (IApplicationModelProvider)

Das ASP.NET Core-MVC-Anwendungsmodell enthält sowohl abstrakte Schnittstellen als auch konkrete Implementierungsklassen, die eine MVC-Anwendung beschreiben. Dieses Modell resultiert aus der MVC-Ermittlung von Controllern, Aktionen, Aktionsparametern, Routen und Filtern der App gemäß den Standardkonventionen. Wenn Sie mit dem Anwendungsmodell arbeiten, können Sie Ihre App so ändern, dass sie Konventionen entspricht, die von den Konventionen des MVC-Standardverhaltens abweichen. Die Parameter, Namen, Routen und Filter werden alle als Konfigurationsdaten für Aktionen und Controller verwendet.

Das ASP.NET Core-MVC-Anwendungsmodell weist folgende Struktur auf:

• ApplicationModel
  • Controller (ControllerModel)
    • Aktionen (ActionModel)
      • Parameter (ParameterModel)

Jede Modellebenen kann auf eine allgemeine Properties-Sammlung zugreifen. Zudem ist auf niedrigeren Ebenen der Zugriff auf Eigenschaftswerte sowie die Überschreibung von Eigenschaftswerten möglich, die auf höheren Ebenen in der Hierarchie festgelegt wurden. Die Eigenschaften werden bei der Erstellung der Aktionen in der Datei ActionDescriptor.Properties permanent gespeichert. Wenn eine Anforderung dann verarbeitet wird, kann über ActionContext.ActionDescriptor auf sämtliche Eigenschaften zugegriffen werden, die über eine Konvention hinzugefügt oder geändert wurden. Die Verwendung von Eigenschaften ist eine gute Möglichkeit zum Konfigurieren von Filtern, Modellbindungen und anderen Modellaspekten für einzelne Aktionen.

ASP.NET Core MVC lädt das Anwendungsmodell über ein durch die Schnittstelle IApplicationModelProvider definiertes Anbietermuster. Dieser Abschnitt enthält einige interne Implementierungsdetails zur Funktionsweise dieses Anbieters. Die Verwendung des Anbietermusters ist ein komplexeres Thema und in erster Linie für die Frameworkverwendung relevant. Die meisten Apps sollten Konventionen verwenden, nicht das Anbietermuster.

Implementierungen der Schnittstelle IApplicationModelProvider umschließen sich gegenseitig. Dabei wird bei den einzelnen Implementierungen die Methode OnProvidersExecuting in aufsteigender Reihenfolge basierend auf der zugehörigen Eigenschaft Order aufgerufen. Anschließend wird die Methode OnProvidersExecuted in umgekehrter Reihenfolge aufgerufen. Das Framework definiert verschiedene Anbieter:

Erst (Order=-1000):

• DefaultApplicationModelProvider

Then (Order=-990):

• AuthorizationApplicationModelProvider
• CorsApplicationModelProvider

Das Konzept DefaultApplicationModelProvider etabliert viele der von ASP.NET Core MVC verwendeten Standardverhaltensweisen. Zu den Zuständigkeiten des Konzepts zählen die folgenden:

• Hinzufügen globaler Filter zum Kontext
• Hinzufügen von Controllern zum Kontext
• Hinzufügen öffentlicher Controllermethoden in Form von Aktionen
• Hinzufügen von Aktionsmethodenparametern zum Kontext
• Anwenden einer Route und anderer Attribute

Einige integrierte Verhaltensweisen werden vom DefaultApplicationModelProvider implementiert. Dieser Anbieter ist zuständig für die Erstellung des Controllermodells (ControllerModel), das wiederum auf die Instanzen ActionModel, PropertyModel und ParameterModel verweist. Die DefaultApplicationModelProvider-Klasse stellt ein Detail zur Implementierung des internen Frameworks dar, das sich möglicherweise noch ändert.

AuthorizationApplicationModelProvider ist für die Anwendung des Verhaltens zuständig, das den Attributen AuthorizeFilter und AllowAnonymousFilter zugeordnet ist. Weitere Informationen finden Sie unter Einfache Autorisierung in ASP.NET Core.

CorsApplicationModelProvider implementiert Verhalten, das IEnableCorsAttribute und IDisableCorsAttribute zugeordnet ist. Weitere Informationen finden Sie unter Aktivieren ursprungsübergreifender Anforderungen (Cross-Origin Requests, CORS) in ASP.NET Core.

Informationen zu den in diesem Abschnitt beschriebenen internen Anbietern des Frameworks sind nicht über den .NET API-Browser verfügbar. Die Anbieter können jedoch in der ASP.NET Core-Referenzquelle (GitHub-Repository „dotnet/aspnetcore“) überprüft werden. Verwenden Sie die GitHub-Suche, um die Anbieter anhand des Namens zu suchen, und wählen Sie die Version der Quelle über die Dropdownliste Branches/Tags wechseln aus.

Konventionen

Das Anwendungsmodell definiert Konventionsabstraktionen, die eine einfachere Möglichkeit zur Anpassung des Verhaltens der Modelle bieten, wodurch auf eine Überschreibung des gesamten Modells oder Anbieters verzichtet werden kann. Diese Abstraktionen werden als Methode für eine Änderung des Verhaltens einer App empfohlen. Konventionen ermöglichen das Schreiben von Code, der Anpassungen dynamisch anwendet. Während Filter eine Möglichkeit zum Ändern des Frameworkverhaltens bieten, können Sie mithilfe von Anpassungen steuern, wie die einzelnen Komponenten der App zusammenarbeiten.

Folgende Konventionen sind verfügbar:

• IApplicationModelConvention
• IControllerModelConvention
• IActionModelConvention
• IParameterModelConvention

Konventionen werden angewendet, indem sie MVC-Optionen hinzugefügt oder indem Attribute implementiert und auf Controller, Aktionen oder Aktionsparameter angewendet werden (ähnlich wie Filter). Im Gegensatz zu Filtern werden Konventionen nur ausgeführt, wenn die App gestartet wird (also nicht als Teil jeder Anforderung).

Ändern des Anwendungsmodells (ApplicationModel)

Die folgende Konvention wird verwendet, um dem Anwendungsmodell eine Eigenschaft hinzuzufügen:

using Microsoft.AspNetCore.Mvc.ApplicationModels;

namespace AppModelSample.Conventions
{
    public class ApplicationDescription : IApplicationModelConvention
    {
        private readonly string _description;

        public ApplicationDescription(string description)
        {
            _description = description;
        }

        public void Apply(ApplicationModel application)
        {
            application.Properties["description"] = _description;
        }
    }
}

Konventionen von Anwendungsmodellen werden als Optionen angewendet, wenn MVC in Startup.ConfigureServices hinzugefügt wird:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc(options =>
    {
        options.Conventions.Add(new ApplicationDescription("My Application Description"));
        options.Conventions.Add(new NamespaceRoutingConvention());
    });
}

Auf Eigenschaften kann innerhalb von Controlleraktionen über die ActionDescriptor.Properties-Auflistung zugegriffen werden:

public class AppModelController : Controller
{
    public string Description()
    {
        return "Description: " + ControllerContext.ActionDescriptor.Properties["description"];
    }
}

Ändern der ControllerModel-Beschreibung

Das Controllermodell kann auch benutzerdefinierte Eigenschaften enthalten. Benutzerdefinierte Eigenschaften setzen vorhandene Eigenschaften mit dem gleichen Namen, die im Anwendungsmodell angegeben sind, außer Kraft. Das folgende Konventionsattribut fügt eine Beschreibung auf Controllerebene hinzu:

using System;
using Microsoft.AspNetCore.Mvc.ApplicationModels;

namespace AppModelSample.Conventions
{
    public class ControllerDescriptionAttribute : Attribute, IControllerModelConvention
    {
        private readonly string _description;

        public ControllerDescriptionAttribute(string description)
        {
            _description = description;
        }

        public void Apply(ControllerModel controllerModel)
        {
            controllerModel.Properties["description"] = _description;
        }
    }
}

Diese Konvention wird als Attribut für einen Controller angewendet:

[ControllerDescription("Controller Description")]
public class DescriptionAttributesController : Controller
{
    public string Index()
    {
        return "Description: " + ControllerContext.ActionDescriptor.Properties["description"];
    }

Ändern der ActionModel-Beschreibung

Auf einzelne Aktionen kann eine separate Attributkonvention angewendet werden, mit der das bereits auf Anwendungs- oder Controllerebene angewendete Verhalten außer Kraft gesetzt wird:

using System;
using Microsoft.AspNetCore.Mvc.ApplicationModels;

namespace AppModelSample.Conventions
{
    public class ActionDescriptionAttribute : Attribute, IActionModelConvention
    {
        private readonly string _description;

        public ActionDescriptionAttribute(string description)
        {
            _description = description;
        }

        public void Apply(ActionModel actionModel)
        {
            actionModel.Properties["description"] = _description;
        }
    }
}

Die Anwendung dieser Konvention auf eine Aktion innerhalb des Controllers veranschaulicht, wie die Konvention auf Controllerebene außer Kraft gesetzt wird:

[ControllerDescription("Controller Description")]
public class DescriptionAttributesController : Controller
{
    public string Index()
    {
        return "Description: " + ControllerContext.ActionDescriptor.Properties["description"];
    }

    [ActionDescription("Action Description")]
    public string UseActionDescriptionAttribute()
    {
        return "Description: " + ControllerContext.ActionDescriptor.Properties["description"];
    }
}

Ändern des Parametermodells (ParameterModel)

Die folgende Konvention kann auf Aktionsparameter zur Änderung ihrer BindingInfo angewendet werden. Für die folgende Konvention muss der Parameter ein Routenparameter sein. Andere potenzielle Bindungsquellen (z. B. Abfragezeichenfolgenwerte) werden ignoriert:

using System;
using Microsoft.AspNetCore.Mvc.ApplicationModels;
using Microsoft.AspNetCore.Mvc.ModelBinding;

namespace AppModelSample.Conventions
{
    public class MustBeInRouteParameterModelConvention : Attribute, IParameterModelConvention
    {
        public void Apply(ParameterModel model)
        {
            if (model.BindingInfo == null)
            {
                model.BindingInfo = new BindingInfo();
            }
            model.BindingInfo.BindingSource = BindingSource.Path;
        }
    }
}

Das Attribut kann möglicherweise auf sämtliche Aktionsparameter angewendet werden:

public class ParameterModelController : Controller
{
    // Will bind:  /ParameterModel/GetById/123
    // WON'T bind: /ParameterModel/GetById?id=123
    public string GetById([MustBeInRouteParameterModelConvention]int id)
    {
        return $"Bound to id: {id}";
    }
}

Um die Konvention auf alle Aktionsparameter anzuwenden, fügen Sie MustBeInRouteParameterModelConvention zu MvcOptions in Startup.ConfigureServices hinzu:

options.Conventions.Add(new MustBeInRouteParameterModelConvention());

Ändern des ActionModel-Namens

Folgende Konvention ändert das ActionModel, um den Namen der Aktion zu aktualisieren, auf die sie angewendet wird. Der neue Name wird als Parameter für das Attribut bereitgestellt. Dieser neue Name wird beim Routing verwendet und beeinflusst die Route, die zum Erreichen dieser Aktionsmethode verwendet wird:

using System;
using Microsoft.AspNetCore.Mvc.ApplicationModels;

namespace AppModelSample.Conventions
{
    public class CustomActionNameAttribute : Attribute, IActionModelConvention
    {
        private readonly string _actionName;

        public CustomActionNameAttribute(string actionName)
        {
            _actionName = actionName;
        }

        public void Apply(ActionModel actionModel)
        {
            // this name will be used by routing
            actionModel.ActionName = _actionName;
        }
    }
}

Dieses Attribut wird auf eine Aktionsmethode im HomeController angewendet:

// Route: /Home/MyCoolAction
[CustomActionName("MyCoolAction")]
public string SomeName()
{
    return ControllerContext.ActionDescriptor.ActionName;
}

Obwohl der Methodenname SomeName lautet, überschreibt das Attribut die MVC-Konvention für die Verwendung des Methodennamens und ersetzt den Aktionsnamen durch MyCoolAction. Daher lautet die Route zum Erreichen dieser Aktion /Home/MyCoolAction.

Benutzerdefinierte Routingkonvention

Verwenden Sie IApplicationModelConvention, um die Funktionsweise des Routings anzupassen. Die folgende Konvention bezieht beispielsweise Namespaces von Controllern in ihre Routen ein und ersetzt . im Namespace durch / in der Route:

using Microsoft.AspNetCore.Mvc.ApplicationModels;
using System.Linq;

namespace AppModelSample.Conventions
{
    public class NamespaceRoutingConvention : IApplicationModelConvention
    {
        public void Apply(ApplicationModel application)
        {
            foreach (var controller in application.Controllers)
            {
                var hasAttributeRouteModels = controller.Selectors
                    .Any(selector => selector.AttributeRouteModel != null);

                if (!hasAttributeRouteModels
                    && controller.ControllerName.Contains("Namespace")) // affect one controller in this sample
                {
                    // Replace the . in the namespace with a / to create the attribute route
                    // Ex: MySite.Admin namespace will correspond to MySite/Admin attribute route
                    // Then attach [controller], [action] and optional {id?} token.
                    // [Controller] and [action] is replaced with the controller and action
                    // name to generate the final template
                    controller.Selectors[0].AttributeRouteModel = new AttributeRouteModel()
                    {
                        Template = controller.ControllerType.Namespace.Replace('.', '/') + "/[controller]/[action]/{id?}"
                    };
                }
            }

            // You can continue to put attribute route templates for the controller actions depending on the way you want them to behave
        }
    }
}

Die Konvention wird als Option in Startup.ConfigureServices hinzugefügt:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc(options =>
    {
        options.Conventions.Add(new ApplicationDescription("My Application Description"));
        options.Conventions.Add(new NamespaceRoutingConvention());
    });
}

services.Configure<MvcOptions>(c => c.Conventions.Add({CONVENTION}));

Im folgenden Beispiel wird eine Konvention auf Routen angewendet, die kein Attributrouting verwenden, bei dem der Name des Controllers Namespace enthält:

using Microsoft.AspNetCore.Mvc;

namespace AppModelSample.Controllers
{
    public class NamespaceRoutingController : Controller
    {
        // using NamespaceRoutingConvention
        // route: /AppModelSample/Controllers/NamespaceRouting/Index
        public string Index()
        {
            return "This demonstrates namespace routing.";
        }
    }
}

services.AddMvc().AddWebApiConventions();

Dokumentieren einer App mithilfe von ApiExplorer

Das Anwendungsmodell macht auf jeder Ebene, auf der die Struktur der App durchlaufen werden kann, eine Eigenschaft vom Typ ApiExplorerModel verfügbar. Dies ermöglicht das Generieren von Hilfeseiten für Ihre Web-APIs mithilfe von Tools wie Swagger. Die Eigenschaft ApiExplorer macht eine Eigenschaft vom Typ IsVisible verfügbar, die festgelegt werden kann, um anzugeben, welche Teile des Modells der App verfügbar gemacht werden sollen. Konfigurieren Sie diese Einstellung mithilfe einer Konvention:

using Microsoft.AspNetCore.Mvc.ApplicationModels;

namespace AppModelSample.Conventions
{
    public class EnableApiExplorerApplicationConvention : IApplicationModelConvention
    {
        public void Apply(ApplicationModel application)
        {
            application.ApiExplorer.IsVisible = true;
        }
    }
}

Mithilfe dieses Ansatzes (und ggf. zusätzlicher Konventionen) wird die API-Sichtbarkeit auf einer beliebigen Ebene innerhalb einer App aktiviert oder deaktiviert.