Breaking Changes in .NET Core 3.0

  • Artikel

Wenn Sie von Version 3.0 von .NET Core, ASP.NET Core oder EF Core migrieren, können sich die in diesem Artikel aufgeführten Breaking Changes auf Ihre App auswirken.

ASP.NET Core

Veraltete Antifälschungs-, CORS-, Diagnose-, MVC- und Routing-APIs wurden entfernt.

Veraltete Member und Kompatibilitätsschalter in ASP.NET Core 2.2 wurden entfernt.

Eingeführt in Version

3.0

Grund für die Änderung

Fortlaufende Verbesserung der API-Schnittstelle.

Wenn Sie .NET Core 2.2 als Ziel verwenden, befolgen Sie die Anweisungen in den Meldungen zum veralteten Build, um stattdessen die neuen APIs zu verwenden.

Kategorie

ASP.NET Core

Betroffene APIs

Die folgenden Typen und Member wurden für ASP.NET Core 2.1 und 2.2 als veraltet markiert:

Typen

  • Microsoft.AspNetCore.Diagnostics.Views.WelcomePage
  • Microsoft.AspNetCore.DiagnosticsViewPage.Views.AttributeValue
  • Microsoft.AspNetCore.DiagnosticsViewPage.Views.BaseView
  • Microsoft.AspNetCore.DiagnosticsViewPage.Views.HelperResult
  • Microsoft.AspNetCore.Mvc.Formatters.Xml.ProblemDetails21Wrapper
  • Microsoft.AspNetCore.Mvc.Formatters.Xml.ValidationProblemDetails21Wrapper
  • Microsoft.AspNetCore.Mvc.Razor.Compilation.ViewsFeatureProvider
  • Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageArgumentBinder
  • Microsoft.AspNetCore.Routing.IRouteValuesAddressMetadata
  • Microsoft.AspNetCore.Routing.RouteValuesAddressMetadata

Konstruktoren

  • Microsoft.AspNetCore.Cors.Infrastructure.CorsService(IOptions{CorsOptions})
  • Microsoft.AspNetCore.Routing.Tree.TreeRouteBuilder(ILoggerFactory,UrlEncoder,ObjectPool{UriBuildingContext},IInlineConstraintResolver)
  • Microsoft.AspNetCore.Mvc.Formatters.OutputFormatterCanWriteContext
  • Microsoft.AspNetCore.Mvc.ApiExplorer.DefaultApiDescriptionProvider(IOptions{MvcOptions},IInlineConstraintResolver,IModelMetadataProvider)
  • Microsoft.AspNetCore.Mvc.ApiExplorer.DefaultApiDescriptionProvider(IOptions{MvcOptions},IInlineConstraintResolver,IModelMetadataProvider,IActionResultTypeMapper)
  • Microsoft.AspNetCore.Mvc.Formatters.FormatFilter(IOptions{MvcOptions})
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.ArrayModelBinder`1(IModelBinder)
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.ByteArrayModelBinder
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.CollectionModelBinder`1(IModelBinder)
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.ComplexTypeModelBinder(IDictionary`2)
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.DictionaryModelBinder`2(IModelBinder,IModelBinder)
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.DoubleModelBinder(System.Globalization.NumberStyles)
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.FloatModelBinder(System.Globalization.NumberStyles)
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.FormCollectionModelBinder
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.FormFileModelBinder
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.HeaderModelBinder
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.KeyValuePairModelBinder`2(IModelBinder,IModelBinder)
  • Microsoft.AspNetCore.Mvc.ModelBinding.Binders.SimpleTypeModelBinder(System.Type)
  • Microsoft.AspNetCore.Mvc.ModelBinding.ModelAttributes(IEnumerable{System.Object})
  • Microsoft.AspNetCore.Mvc.ModelBinding.ModelAttributes(IEnumerable{System.Object},IEnumerable{System.Object})
  • Microsoft.AspNetCore.Mvc.ModelBinding.ModelBinderFactory(IModelMetadataProvider,IOptions{MvcOptions})
  • Microsoft.AspNetCore.Mvc.ModelBinding.ParameterBinder(IModelMetadataProvider,IModelBinderFactory,IObjectModelValidator)
  • Microsoft.AspNetCore.Mvc.Routing.KnownRouteValueConstraint()
  • Microsoft.AspNetCore.Mvc.Formatters.XmlDataContractSerializerInputFormatter
  • Microsoft.AspNetCore.Mvc.Formatters.XmlDataContractSerializerInputFormatter(System.Boolean)
  • Microsoft.AspNetCore.Mvc.Formatters.XmlDataContractSerializerInputFormatter(MvcOptions)
  • Microsoft.AspNetCore.Mvc.Formatters.XmlSerializerInputFormatter
  • Microsoft.AspNetCore.Mvc.Formatters.XmlSerializerInputFormatter(System.Boolean)
  • Microsoft.AspNetCore.Mvc.Formatters.XmlSerializerInputFormatter(MvcOptions)
  • Microsoft.AspNetCore.Mvc.TagHelpers.ImageTagHelper(IHostingEnvironment,IMemoryCache,HtmlEncoder,IUrlHelperFactory)
  • Microsoft.AspNetCore.Mvc.TagHelpers.LinkTagHelper(IHostingEnvironment,IMemoryCache,HtmlEncoder,JavaScriptEncoder,IUrlHelperFactory)
  • Microsoft.AspNetCore.Mvc.TagHelpers.ScriptTagHelper(IHostingEnvironment,IMemoryCache,HtmlEncoder,JavaScriptEncoder,IUrlHelperFactory)
  • Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.RazorPageAdapter(RazorPageBase)

Eigenschaften

  • Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.CookieDomain
  • Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.CookieName
  • Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.CookiePath
  • Microsoft.AspNetCore.Antiforgery.AntiforgeryOptions.RequireSsl
  • Microsoft.AspNetCore.Mvc.ApiBehaviorOptions.AllowInferringBindingSourceForCollectionTypesAsFromQuery
  • Microsoft.AspNetCore.Mvc.ApiBehaviorOptions.SuppressUseValidationProblemDetailsForInvalidModelStateResponses
  • Microsoft.AspNetCore.Mvc.CookieTempDataProviderOptions.CookieName
  • Microsoft.AspNetCore.Mvc.CookieTempDataProviderOptions.Domain
  • Microsoft.AspNetCore.Mvc.CookieTempDataProviderOptions.Path
  • Microsoft.AspNetCore.Mvc.DataAnnotations.MvcDataAnnotationsLocalizationOptions.AllowDataAnnotationsLocalizationForEnumDisplayAttributes
  • Microsoft.AspNetCore.Mvc.Formatters.Xml.MvcXmlOptions.AllowRfc7807CompliantProblemDetailsFormat
  • Microsoft.AspNetCore.Mvc.MvcOptions.AllowBindingHeaderValuesToNonStringModelTypes
  • Microsoft.AspNetCore.Mvc.MvcOptions.AllowCombiningAuthorizeFilters
  • Microsoft.AspNetCore.Mvc.MvcOptions.AllowShortCircuitingValidationWhenNoValidatorsArePresent
  • Microsoft.AspNetCore.Mvc.MvcOptions.AllowValidatingTopLevelNodes
  • Microsoft.AspNetCore.Mvc.MvcOptions.InputFormatterExceptionPolicy
  • Microsoft.AspNetCore.Mvc.MvcOptions.SuppressBindingUndefinedValueToEnumType
  • Microsoft.AspNetCore.Mvc.MvcViewOptions.AllowRenderingMaxLengthAttribute
  • Microsoft.AspNetCore.Mvc.MvcViewOptions.SuppressTempDataAttributePrefix
  • Microsoft.AspNetCore.Mvc.RazorPages.RazorPagesOptions.AllowAreas
  • Microsoft.AspNetCore.Mvc.RazorPages.RazorPagesOptions.AllowDefaultHandlingForOptionsRequests
  • Microsoft.AspNetCore.Mvc.RazorPages.RazorPagesOptions.AllowMappingHeadRequestsToGetHandler

Methoden

„Pubternal“-APIs entfernt

Um die öffentliche API-Oberfläche von ASP.NET Core besser zu verwalten, sind die meisten Typen in *.Internal-Namespaces (als "pubternal"-APIs bezeichnet) wirklich intern geworden. Member in diesen Namespaces sollten nie als öffentlich ausgerichtete APIs unterstützt werden. Bei den APIs konnten in Nebenversionen Fehler auftreten, was auch häufig der Fall war. Bei Code, der von diesen APIs abhängig ist, treten beim Aktualisieren auf ASP.Net Core 3.0 Fehler auf.

Weitere Informationen finden Sie unter dotnet/aspnetcore#4932 und dotnet/aspnetcore#11312.

Eingeführt in Version

3.0

Altes Verhalten

Die betroffenen APIs werden mit dem public-Zugriffsmodifizierer gekennzeichnet und sind in *.Internal-Namespaces vorhanden.

Neues Verhalten

Die betroffenen APIs sind mit dem internal-Zugriffsmodifizierer gekennzeichnet und können nicht mehr von Code außerhalb dieser Assembly verwendet werden.

Grund für die Änderung

Die Richtlinie für diese "pubternal"-APIs war:

  • Sie konnten ohne vorherige Ankündigung geändert werden.
  • Sie unterlagen nicht den .NET-Richtlinien zum Verhindern von Breaking Changes.

Die APIs public zu lassen (selbst in den *.Internal-Namespaces), war für Kunden verwirrend.

Verwenden Sie diese "pubternal"-APIs nicht mehr. Wenn Sie Fragen zu alternativen APIs haben, öffnen Sie ein Issue im dotnet/aspnetcore-Repository.

Sehen Sie sich beispielsweise den folgenden HTTP-Anforderungspuffercode in einem ASP.NET Core 2.2-Projekt an. Die EnableRewind-Erweiterungsmethode ist im Microsoft.AspNetCore.Http.Internal-Namespace vorhanden.

HttpContext.Request.EnableRewind();

Ersetzen Sie den EnableRewind-Aufruf in einem ASP.NET Core 3.0-Projekt durch einen Aufruf der EnableBuffering-Erweiterungsmethode. Das Feature für die Anforderungspufferung funktioniert wie bisher. EnableBuffering ruft die jetzige internal-API auf.

HttpContext.Request.EnableBuffering();

Kategorie

ASP.NET Core

Betroffene APIs

Alle APIs in den Microsoft.AspNetCore.*-und Microsoft.Extensions.*-Namespaces mit einem Internal-Segment im Namespacenamen. Zum Beispiel:

  • Microsoft.AspNetCore.Authentication.Internal
  • Microsoft.AspNetCore.Builder.Internal
  • Microsoft.AspNetCore.DataProtection.Cng.Internal
  • Microsoft.AspNetCore.DataProtection.Internal
  • Microsoft.AspNetCore.Hosting.Internal
  • Microsoft.AspNetCore.Http.Internal
  • Microsoft.AspNetCore.Mvc.Core.Infrastructure
  • Microsoft.AspNetCore.Mvc.Core.Internal
  • Microsoft.AspNetCore.Mvc.Cors.Internal
  • Microsoft.AspNetCore.Mvc.DataAnnotations.Internal
  • Microsoft.AspNetCore.Mvc.Formatters.Internal
  • Microsoft.AspNetCore.Mvc.Formatters.Json.Internal
  • Microsoft.AspNetCore.Mvc.Formatters.Xml.Internal
  • Microsoft.AspNetCore.Mvc.Internal
  • Microsoft.AspNetCore.Mvc.ModelBinding.Internal
  • Microsoft.AspNetCore.Mvc.Razor.Internal
  • Microsoft.AspNetCore.Mvc.RazorPages.Internal
  • Microsoft.AspNetCore.Mvc.TagHelpers.Internal
  • Microsoft.AspNetCore.Mvc.ViewFeatures.Internal
  • Microsoft.AspNetCore.Rewrite.Internal
  • Microsoft.AspNetCore.Routing.Internal
  • Microsoft.AspNetCore.Server.Kestrel.Core.Adapter.Internal
  • Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http
  • Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Infrastructure
  • Microsoft.AspNetCore.Server.Kestrel.Https.Internal

Authentifizierung: Google+ als veraltet markiert und ersetzt

Google hat ab 28. Januar 2019 damit begonnen, die Google+-Anmeldung für Apps einzustellen.

Änderungsbeschreibung

ASP.NET 4.x und ASP.NET Core verwendeten die Google+-Anmelde-APIs zum Authentifizieren von Google-Benutzerkonten in Web-Apps. Die betroffenen NuGet-Pakete sind Microsoft.AspNetCore.Authentication.Google für ASP.NET Core und Microsoft.Owin.Security.Google für Microsoft.Owin mit ASP.NET Web Forms und MVC.

Die Ersetzungs-APIs von Google nutzen eine andere Datenquelle und ein anderes Format. Mit den unten aufgeführten Entschärfungen und Lösungen wird auf diese strukturellen Änderungen reagiert. Apps sollten überprüfen, ob die Daten selbst weiterhin die Anforderungen erfüllen. Beispielsweise können Namen, E-Mail-Adressen, Profilverknüpfungen und Profilfotos etwas andere Werte als zuvor bereitstellen.

Eingeführt in Version

Alle Versionen. Diese Änderung ist extern von ASP.NET Core.

Owin mit ASP.NET Web Forms und MVC

Für Microsoft.Owin 3.1.0 und höher finden Sie hier eine vorübergehende Entschärfung. Apps sollten Tests mit der Entschärfung durchführen, um Änderungen am Datenformat zu überprüfen. Es gibt Pläne, Microsoft.Owin 4.0.1 mit einer Korrektur zu veröffentlichen. Apps, die eine frühere Version verwenden, sollten auf Version 4.0.1 aktualisiert werden.

ASP.NET Core 1.x

Die Entschärfung in Owin mit ASP.NET Web Forms und MVC kann an ASP.NET Core 1.x angepasst werden. NuGet-Paketpatches sind nicht geplant, da Version 1.x das Ende des Lebenszyklus erreicht hat.

ASP.NET Core 2.x

Ersetzen Sie für Microsoft.AspNetCore.Authentication.Google Version 2.x den vorhandenen Aufruf von AddGoogle in Startup.ConfigureServices durch folgenden Code:

.AddGoogle(o =>
{
    o.ClientId = Configuration["Authentication:Google:ClientId"];
    o.ClientSecret = Configuration["Authentication:Google:ClientSecret"];
    o.UserInformationEndpoint = "https://www.googleapis.com/oauth2/v2/userinfo";
    o.ClaimActions.Clear();
    o.ClaimActions.MapJsonKey(ClaimTypes.NameIdentifier, "id");
    o.ClaimActions.MapJsonKey(ClaimTypes.Name, "name");
    o.ClaimActions.MapJsonKey(ClaimTypes.GivenName, "given_name");
    o.ClaimActions.MapJsonKey(ClaimTypes.Surname, "family_name");
    o.ClaimActions.MapJsonKey("urn:google:profile", "link");
    o.ClaimActions.MapJsonKey(ClaimTypes.Email, "email");
});

Die Februar-Patches 2.1 und 2.2 enthalten die vorherige Neukonfiguration als neuen Standard. Es ist kein Patch für ASP.NET Core 2.0 geplant, da diese Version das Ende des Lebenszyklus erreicht hat.

ASP.NET Core 3.0

Die für ASP.NET Core 2.x angegebene Entschärfung kann auch für ASP.NET Core 3.0 verwendet werden. In den nächsten Vorschauversionen für 3.0 wird das Paket Microsoft.AspNetCore.Authentication.Google möglicherweise entfernt. Benutzer würden stattdessen an Microsoft.AspNetCore.Authentication.OpenIdConnect weitergeleitet werden. Im folgenden Code wird das Ersetzen von AddGoogle durch AddOpenIdConnect in Startup.ConfigureServices veranschaulicht. Diese Ersetzung kann mit ASP.NET Core 2.0 und höher verwendet und bei Bedarf für ASP.NET Core 1.x angepasst werden.

.AddOpenIdConnect("Google", o =>
{
    o.ClientId = Configuration["Authentication:Google:ClientId"];
    o.ClientSecret = Configuration["Authentication:Google:ClientSecret"];
    o.Authority = "https://accounts.google.com";
    o.ResponseType = OpenIdConnectResponseType.Code;
    o.CallbackPath = "/signin-google"; // Or register the default "/signin-oidc"
    o.Scope.Add("email");
});
JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear();

Kategorie

ASP.NET Core

Betroffene APIs

Microsoft.AspNetCore.Authentication.Google

Authentifizierung: HttpContext.Authentication-Eigenschaft wurde entfernt

Die veraltete Authentication-Eigenschaft in HttpContext wurde entfernt.

Beschreibung der Änderung:

Gemäß dotnet/aspnetcore#6504 wurde die veraltete Authentication-Eigenschaft für HttpContext entfernt. Die Authentication-Eigenschaft ist seit Version 2.0 veraltet. Es wurde eine Migrationsanleitung veröffentlicht, um Code, der diese veraltete Eigenschaft verwendet, zu den neuen Ersatz-APIs zu migrieren. Die verbleibenden nicht verwendeten Klassen/APIs, die sich auf den alten ASP.NET Core 1.x-Authentifizierungsstapel beziehen, wurden im Commit dotnet/aspnetcore@d7a7c65 entfernt.

Weitere Informationen finden Sie unter dotnet/aspnetcore#6533.

Eingeführt in Version

3.0

Grund für die Änderung

Die ASP.NET Core 1.0-APIs wurden durch Erweiterungsmethoden in Microsoft.AspNetCore.Authentication.AuthenticationHttpContextExtensions ersetzt.

Lesen Sie die Migrationsanleitung.

Kategorie

ASP.NET Core

Betroffene APIs

Authentifizierung: Newtonsoft.Json-Typen wurden ersetzt.

In ASP.NET Core 3.0 wurden die in Authentifizierungs-APIs verwendeten Newtonsoft.Json-Typen durch System.Text.Json-Typen ersetzt. Mit Ausnahme der folgenden Fälle ist die grundlegende Verwendung der Authentifizierungspakete nicht betroffen:

  • Von den OAuth-Anbietern abgeleitete Klassen (z. B. von aspnet-contrib )
  • Erweiterte Implementierungen von Anspruchsbearbeitungen

Weitere Informationen finden Sie unter dotnet/aspnetcore#7105. Weitere Informationen finden Sie unter dotnet/aspnetcore#7289.

Eingeführt in Version

3.0

Bei abgeleiteten OAuth-Implementierungen besteht die häufigste Änderung darin, dass JObject.Parse in der CreateTicketAsync-Überschreibung durch JsonDocument.Parse ersetzt wird, wie hier gezeigt. JsonDocument implementiert IDisposable.

In der folgenden Liste werden bekannte Änderungen erläutert:

Kategorie

ASP.NET Core

Betroffene APIs

Authentifizierung: Signatur von OAuthHandler.ExchangeCodeAsync wurde geändert

In ASP.NET Core 3.0 wurde die Signatur von OAuthHandler.ExchangeCodeAsync geändert von:

protected virtual System.Threading.Tasks.Task<Microsoft.AspNetCore.Authentication.OAuth.OAuthTokenResponse> ExchangeCodeAsync(string code, string redirectUri) { throw null; }

Nach:

protected virtual System.Threading.Tasks.Task<Microsoft.AspNetCore.Authentication.OAuth.OAuthTokenResponse> ExchangeCodeAsync(Microsoft.AspNetCore.Authentication.OAuth.OAuthCodeExchangeContext context) { throw null; }

Eingeführt in Version

3.0

Altes Verhalten

Die Zeichenfolgen code und redirectUri wurden als separate Argumente übergeben.

Neues Verhalten

Code und RedirectUri sind Eigenschaften von OAuthCodeExchangeContext, die über den OAuthCodeExchangeContext-Konstruktor festgelegt werden können. Der neue OAuthCodeExchangeContext-Typ ist das einzige Argument, das an OAuthHandler.ExchangeCodeAsync übergeben wird.

Grund für die Änderung

Diese Änderung ermöglicht die Bereitstellung zusätzlicher Parameter, ohne dass es zu Breaking Changes kommt. Es müssen keine neuen ExchangeCodeAsync-Überladungen erstellt werden.

Erstellen Sie einen OAuthCodeExchangeContext mit geeigneten Werten für code und redirectUri. Es muss eine AuthenticationProperties-Instanz bereitgestellt werden. Diese einzelne OAuthCodeExchangeContext-Instanz kann anstelle mehrerer Argumente an OAuthHandler.ExchangeCodeAsync übergeben werden.

Kategorie

ASP.NET Core

Betroffene APIs

OAuthHandler<TOptions>.ExchangeCodeAsync(String, String)

Autorisierung: AddAuthorization-Überladung wurde in andere Assembly verschoben

Die wichtigsten AddAuthorization-Methoden, die bisher in Microsoft.AspNetCore.Authorization enthalten waren, wurden in AddAuthorizationCore umbenannt. Die alten AddAuthorization-Methoden sind immer noch vorhanden, befinden sich jedoch stattdessen in der Assembly Microsoft.AspNetCore.Authorization.Policy. Dies sollte auf Apps, die beide Methoden verwenden, keine Auswirkung haben. Beachten Sie, dass Microsoft.AspNetCore.Authorization.Policy jetzt im freigegebenen Framework und nicht einem eigenständigen Paket enthalten ist, wie in Freigegebenes Framework: Assemblys aus Microsoft.AspNetCore.App entfernt beschrieben.

Eingeführt in Version

3.0

Altes Verhalten

Die AddAuthorization-Methoden waren in Microsoft.AspNetCore.Authorization enthalten.

Neues Verhalten

Die AddAuthorization-Methoden sind jetzt in Microsoft.AspNetCore.Authorization.Policy enthalten. AddAuthorizationCore ist der neue Name für die alten Methoden.

Grund für die Änderung

AddAuthorization ist ein besserer Methodenname für das Hinzufügen aller allgemeinen Dienste, die für die Autorisierung benötigt werden.

Fügen Sie entweder einen Verweis auf Microsoft.AspNetCore.Authorization.Policy hinzu, oder verwenden Sie stattdessen AddAuthorizationCore.

Kategorie

ASP.NET Core

Betroffene APIs

Microsoft.Extensions.DependencyInjection.AuthorizationServiceCollectionExtensions.AddAuthorization(IServiceCollection, Action<AuthorizationOptions>)

Autorisierung: IAllowAnonymous wurde aus AuthorizationFilterContext.Filters entfernt

Ab ASP.NET Core 3.0 fügt MVC keine AllowAnonymousFilters für [AllowAnonymous]-Attribute hinzu, die für Controller und Aktionsmethoden ermittelt wurden. Diese Änderung wird lokal für Ableitungen von AuthorizeAttributebehandelt, ist aber ein Breaking Change für IAsyncAuthorizationFilter- und IAuthorizationFilter-Implementierungen. Solche Implementierungen, die ein [TypeFilter]-Attribut als Wrapper verwenden, sind eine gängige und unterstützte Möglichkeit, um eine stark typisierte, attributbasierte Autorisierung zu erreichen, wenn sowohl Konfiguration als auch Abhängigkeitsinjektion (Dependency Injection, DI) erforderlich sind.

Eingeführt in Version

3.0

Altes Verhalten

IAllowAnonymous war in der AuthorizationFilterContext.Filters-Sammlung enthalten. Das Testen auf das Vorhandensein der Schnittstelle war ein gültiger Ansatz, um den Filter für einzelne Controllermethoden zu überschreiben oder zu deaktivieren.

Neues Verhalten

IAllowAnonymous ist nicht mehr in der AuthorizationFilterContext.Filters-Sammlung enthalten. IAsyncAuthorizationFilter-Implementierungen, die vom alten Verhalten abhängig sind, verursachen in der Regel vorübergehende HTTP 401- (Nicht autorisiert) oder HTTP 403-Antworten (Unzulässig).

Grund für die Änderung

In ASP.NET Core 3.0 wurde eine neue Endpunktroutingstrategie eingeführt.

Suchen Sie nach den Endpunktmetadaten für IAllowAnonymous. Beispiel:

var endpoint = context.HttpContext.GetEndpoint();
if (endpoint?.Metadata?.GetMetadata<IAllowAnonymous>() != null)
{
}

Ein Beispiel für diese Technik finden Sie in dieser HasAllowAnonymous-Methode.

Kategorie

ASP.NET Core

Betroffene APIs

Keine

Autorisierung: Implementierungen von IAuthorizationPolicyProvider erfordern eine neue Methode

In ASP.NET Core 3.0 wurde IAuthorizationPolicyProvider eine neue GetFallbackPolicyAsync-Methode hinzugefügt. Diese Fallbackrichtlinie wird von der Autorisierungsmiddleware verwendet, wenn keine Richtlinie angegeben wird.

Weitere Informationen finden Sie unter dotnet/aspnetcore#9759.

Eingeführt in Version

3.0

Altes Verhalten

Implementierungen von IAuthorizationPolicyProvider haben keine GetFallbackPolicyAsync-Methode erfordert.

Neues Verhalten

Implementierungen von IAuthorizationPolicyProvider erfordern eine GetFallbackPolicyAsync-Methode.

Grund für die Änderung

Es war eine neue Methode erforderlich, damit die neue AuthorizationMiddleware verwendet wird, wenn keine Richtlinie angegeben wird.

Fügen Sie Ihren Implementierungen von IAuthorizationPolicyProvider die GetFallbackPolicyAsync-Methode hinzu.

Kategorie

ASP.NET Core

Betroffene APIs

Microsoft.AspNetCore.Authorization.IAuthorizationPolicyProvider

Zwischenspeicherung: CompactOnMemoryPressure-Eigenschaft wurde entfernt

Die veralteten MemoryCacheOptions-APIs wurden im Release ASP.NET Core 3.0 entfernt.

Änderungsbeschreibung

Diese Änderung resultiert aus aspnet/Caching#221. Weitere Informationen finden Sie unter dotnet/extensions#1062.

Eingeführt in Version

3.0

Altes Verhalten

Die MemoryCacheOptions.CompactOnMemoryPressure-Eigenschaft war verfügbar.

Neues Verhalten

Die MemoryCacheOptions.CompactOnMemoryPressure-Eigenschaft wurde entfernt.

Grund für die Änderung

Die automatische Komprimierung des Caches hat Probleme verursacht. Um unerwartetes Verhalten zu vermeiden, sollte der Cache nur bei Bedarf komprimiert werden.

Um den Cache zu komprimieren, führen Sie eine Umwandlung in MemoryCache durch und rufen bei Bedarf Compact auf.

Kategorie

ASP.NET Core

Betroffene APIs

MemoryCacheOptions.CompactOnMemoryPressure

Zwischenspeicherung: Microsoft.Extensions.Caching.SqlServer verwendet neues SqlClient-Paket

Das Paket Microsoft.Extensions.Caching.SqlServer verwendet anstelle des Pakets System.Data.SqlClient das neue Paket Microsoft.Data.SqlClient. Diese Änderung kann zu geringfügigen Breaking Changes beim Verhalten führen. Weitere Informationen finden Sie unter Introducing the new Microsoft.Data.SqlClient (Vorstellung des neuen Microsoft.Data.SqlClient).

Eingeführt in Version

3.0

Altes Verhalten

Das Paket Microsoft.Extensions.Caching.SqlServer hat das Paket System.Data.SqlClient verwendet.

Neues Verhalten

Microsoft.Extensions.Caching.SqlServer verwendet jetzt das Paket Microsoft.Data.SqlClient.

Grund für die Änderung

Microsoft.Data.SqlClient ist ein neues Paket, das aus System.Data.SqlClient erstellt wurde. Es enthält ab sofort alle neuen Funktionen.

Kunden müssen sich um diesen Breaking Change nur kümmern, wenn sie die vom Paket Microsoft.Extensions.Caching.SqlServer zurückgegebenen Typen verwendet und in System.Data.SqlClient-Typen umgewandelt haben. Wenn z. B. eine DbConnection in den alten SqlConnection-Typ umgewandelt wurde, muss die Umwandlung in den neuen Microsoft.Data.SqlClient.SqlConnection-Typ geändert werden.

Kategorie

ASP.NET Core

Betroffene APIs

Keine

Zwischenspeicherung: „pubternal“-Typen wurden in ResponseCaching in „internal“-Typen geändert

In ASP.NET Core 3.0 wurden „pubternal“-Typen in ResponseCaching in internal geändert.

Außerdem werden die Standardimplementierungen von IResponseCachingPolicyProvider und IResponseCachingKeyProvider Diensten nicht mehr als Teil der AddResponseCaching-Methode hinzugefügt.

Änderungsbeschreibung

In ASP.NET Core werden „pubternal“-Typen als public deklariert, befinden sich jedoch in einem Namespace mit dem Suffix .Internal. Diese Typen sind zwar öffentlich („public“), sie verfügen jedoch nicht über eine Unterstützungsrichtlinie und können daher Breaking Changes unterliegen. Da diese Typen leider relativ häufig versehentlich verwendet werden, können an diesen Projekten Breaking Changes auftreten, und die Fähigkeit zum Verwalten des Frameworks kann eingeschränkt werden.

Eingeführt in Version

3.0

Altes Verhalten

Diese Typen waren öffentlich sichtbar, wurden jedoch nicht unterstützt.

Neues Verhalten

Diese Typen sind jetzt internal.

Grund für die Änderung

Der Geltungsbereich internal entspricht besser der nicht unterstützten Richtlinie.

Kopieren Sie Typen, die von Ihrer App oder Bibliothek verwendet werden.

Kategorie

ASP.NET Core

Betroffene APIs

Schutz von Daten: DataProtection.Blobs verwendet neue Azure Storage-APIs

Azure.Extensions.AspNetCore.DataProtection.Blobs hängt von den Azure Storage-Bibliotheken ab. Für diese Bibliotheken wurden die Assemblys, Pakete und Namespaces umbenannt. Ab ASP.NET Core 3.0 verwendet Azure.Extensions.AspNetCore.DataProtection.Blobs die neuen APIs und Pakete mit dem Präfix Azure.Storage..

Wenn Sie Fragen zu den Azure Storage-APIs haben, lesen Sie unter https://github.com/Azure/azure-storage-net nach. Dieses Problem wird unter dotnet/aspnetcore#19570 behandelt.

Eingeführt in Version

3.0

Altes Verhalten

Das Paket verwies auf das NuGet-Paket WindowsAzure.Storage. Das Pakete verweist auf das NuGet-Paket Microsoft.Azure.Storage.Blob.

Neues Verhalten

Das Pakete verweist auf das NuGet-Paket Azure.Storage.Blob.

Grund für die Änderung

Diese Änderung ermöglicht Azure.Extensions.AspNetCore.DataProtection.Blobs die Migration zu den empfohlenen Azure Storage-Paketen.

Wenn Sie weiterhin die älteren Azure Storage-APIs mit ASP.NET Core 3.0 verwenden müssen, fügen Sie eine direkte Abhängigkeit vom Paket WindowsAzure.Storage oder Microsoft Azure Storage hinzu. Dieses Paket kann parallel zu den neuen Azure.Storage-APIs installiert werden.

In vielen Fällen umfasst das Upgrade nur das Ändern der using-Anweisungen, um die neuen Namespaces zu verwenden:

- using Microsoft.WindowsAzure.Storage;
- using Microsoft.WindowsAzure.Storage.Blob;
- using Microsoft.Azure.Storage;
- using Microsoft.Azure.Storage.Blob;
+ using Azure.Storage;
+ using Azure.Storage.Blobs;

Kategorie

ASP.NET Core

Betroffene APIs

Keine

Hosting: AspNetCoreModule v1 wurde aus dem Windows-Hostingpaket entfernt

Ab ASP.NET Core 3.0 ist AspNetCoreModule v1 (ANCM) nicht mehr im Windows-Hostingpaket enthalten.

ANCM v2 ist abwärtskompatibel mit ANCM OutOfProcess und wird für die Verwendung mit ASP.NET Core 3.0-Apps empfohlen.

Weitere Informationen finden Sie unter dotnet/aspnetcore#7095.

Eingeführt in Version

3.0

Altes Verhalten

ANCM v1 war im Windows-Hostingpaket enthalten.

Neues Verhalten

ANCM v1 ist nicht mehr im Windows-Hostingpaket enthalten.

Grund für die Änderung

ANCM v2 ist abwärtskompatibel mit ANCM OutOfProcess und wird für die Verwendung mit ASP.NET Core 3.0-Apps empfohlen.

Verwenden Sie ANCM v2 mit ASP.NET Core 3.0-Apps.

Wenn ANCM v1 erforderlich ist, kann es mit dem Windows-Hostingpaket für ASP.NET Core 2.1 oder 2.2 installiert werden.

Diese Änderung stellt einen Breaking Change für ASP.NET Core 3.0-Apps dar, für die Folgendes gilt:

  • Sie verwenden ANCM v1 explizit über <AspNetCoreModuleName>AspNetCoreModule</AspNetCoreModuleName>.
  • Sie verfügen über eine benutzerdefinierte Datei web.config mit <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />.

Kategorie

ASP.NET Core

Betroffene APIs

Keine

Hosting: Generischer Host schränkt Startup-Konstruktorinjektion ein

Die einzigen Typen, die vom generischen Host für Konstruktorinjektionen der Startup-Klasse unterstützt werden, sind IHostEnvironment, IWebHostEnvironment und IConfiguration. Apps, die WebHost verwenden, sind nicht betroffen.

Änderungsbeschreibung

Vor ASP.NET Core 3.0 konnte die Konstruktorinjektion für beliebige Typen im Konstruktor der Startup-Klasse verwendet werden. In ASP.NET Core 3.0 wurde der Webstapel der Bibliothek des generischen Hosts zugeordnet. Sie können die Änderung in der Datei Program.cs der Vorlagen sehen:

ASP.NET Core 2.x:

https://github.com/dotnet/aspnetcore/blob/5cb615fcbe8559e49042e93394008077e30454c0/src/Templating/src/Microsoft.DotNet.Web.ProjectTemplates/content/EmptyWeb-CSharp/Program.cs#L20-L22

ASP.NET Core 3.0:

https://github.com/dotnet/aspnetcore/blob/b1ca2c1155da3920f0df5108b9fedbe82efaa11c/src/ProjectTemplates/Web.ProjectTemplates/content/EmptyWeb-CSharp/Program.cs#L19-L24

Host verwendet einen Container zur Abhängigkeitsinjektion, um die App zu erstellen. WebHost verwendet zwei Container: einen für den Host und einen für die App. Daher unterstützt der Startup-Konstruktor keine benutzerdefinierte Dienstinjektion mehr. Es können nur IHostEnvironment, IWebHostEnvironment und IConfiguration eingefügt werden. Diese Änderung verhindert Probleme mit Abhängigkeitsinjektionen, z. B. die doppelte Erstellung eines Singletondiensts.

Eingeführt in Version

3.0

Grund für die Änderung

Diese Änderung ist eine Folge der geänderten Zuordnung des Webstapels zur Bibliothek des generischen Hosts.

Fügen Sie Dienste in die Signatur der Startup.Configure-Methode ein. Zum Beispiel:

public void Configure(IApplicationBuilder app, IOptions<MyOptions> options)

Kategorie

ASP.NET Core

Betroffene APIs

Keine

Hosting: HTTPS-Umleitung für IIS-Out-of-Process-Apps aktiviert

In der Version 13.0.19218.0 des ASP.NET Core-Moduls (ANCM) für das Hosten über IIS-Out-of-Process wurde ein vorhandenes HTTPS-Umleitungsfeature für ASP.NET Core 3.0- und ASP.NET Core 2.2.-Apps aktiviert.

Weitere Informationen finden Sie unter dotnet/AspNetCore#15243.

Eingeführt in Version

3.0

Altes Verhalten

Bei der ASP.NET Core 2.1-Projektvorlage wurde zuerst Unterstützung für HTTPS-Middlewaremethoden wie UseHttpsRedirection und UseHsts eingeführt. Es musste eine Konfiguration hinzugefügt werden, um die HTTPS-Umleitung zu aktivieren, da Apps in der Entwicklung nicht den Standardport 443 verwenden. HTTP Strict Transport Security (HSTS) ist nur aktiv, wenn die Anforderung bereits HTTPS verwendet. Der Localhost wird standardmäßig übersprungen.

Neues Verhalten

In ASP.NET Core 3.0 wurde das IIS-HTTPS-Szenario verbessert. Dank dieser Optimierung kann eine App nun die HTTPS-Ports eines Servers ermitteln, und UseHttpsRedirection funktioniert standardmäßig. Die In-Process-Komponente hat das Ermitteln von Ports mithilfe des IServerAddresses-Features möglich gemacht. Das betrifft nur ASP.NET Core 3.0-Apps, da die In-Process-Bibliothek mit dem Framework versioniert ist. Die Out-of-Process-Komponente wurde so geändert, dass die ASPNETCORE_HTTPS_PORT-Umgebungsvariable automatisch hinzugefügt wird. Diese Änderung wirkt sich sowohl auf ASP.NET Core 2.2- als auch ASP.NET Core 3.0-Apps aus, da die Out-of-Process-Komponente global geteilt wird. ASP.NET Core 2.1-Apps sind nicht betroffen, da sie standardmäßig eine ältere ANCM-Version verwenden.

Das hier beschriebene Verhalten wurde in ASP.NET Core 3.0.1 und ASP.NET Core 3.1.0 Preview 3 so geändert, dass die Behavior Changes in ASP.NET Core 2.x umgekehrt werden. Diese Änderungen betreffen nur IIS-Out-of-Process-Apps.

Wie oben beschrieben hatte das Installieren von ASP.NET Core 3.0.0 die Begleiterscheinung, dass auch die UseHttpsRedirection-Middleware in ASP.NET Core 2.x-Apps aktiviert wurde. Deshalb wurde das ANCM in ASP.NET Core 3.0.1 und in ASP.NET Core 3.1.0 Preview 3 so geändert, dass eine Installation des Frameworks nicht mehr diese Begleiterscheinung für ASP.NET Core 2.x-Apps hat. Die ASPNETCORE_HTTPS_PORT-Umgebungsvariable, die in ASP.NET Core 3.0.0 vom ANCM aufgefüllt wurde, wurde in ASP.NET Core 3.0.1 und ASP.NET Core 3.1.0 Preview 3 in ASPNETCORE_ANCM_HTTPS_PORT geändert. UseHttpsRedirection wurde in diesen Releases ebenfalls aktualisiert, sodass die neuen und die alten Variablen verstanden werden können. ASP.NET Core 2.x wird nicht aktualisiert. Das führt dazu, dass das vorherige Verhalten (standardmäßig deaktiviert) wiederhergestellt wird.

Grund für die Änderung

Verbesserung der ASP.NET Core 3.0-Funktionen.

Es ist keine Aktion erforderlich, wenn Sie möchten, dass alle Clients HTTPS verwenden. Wenn Sie zulassen möchten, dass einige Clients HTTP verwenden, führen Sie einen der folgenden Schritte aus:

  • Entfernen Sie die Aufrufe von UseHttpsRedirection und UseHsts aus der Startup.Configure-Methode Ihres Projekts, und stellen Sie die App neu bereit.

  • Legen Sie in der Datei web.config die ASPNETCORE_HTTPS_PORT-Umgebungsvariable auf eine leere Zeichenfolge fest. Diese Änderung kann direkt auf dem Server ausgeführt werden, ohne dass die App dafür neu bereitgestellt werden muss. Beispiel:

    <aspNetCore processPath="dotnet" arguments=".\WebApplication3.dll" stdoutLogEnabled="false" stdoutLogFile="\\?\%home%\LogFiles\stdout" >
    <environmentVariables>
    <environmentVariable name="ASPNETCORE_HTTPS_PORT" value="" />
    </environmentVariables>
</aspNetCore>

Folgende Aktionen sind für UseHttpsRedirection weiterhin möglich:

  • Manuelles Aktivieren in ASP.NET Core 2.x, indem die ASPNETCORE_HTTPS_PORT-Umgebungsvariable auf die entsprechende Portnummer festgelegt wird. In den meisten Produktionsszenarios ist das 443.
  • Deaktivieren in ASP.NET Core 3.x, indem ASPNETCORE_ANCM_HTTPS_PORT mit einem leeren Zeichenfolgenwert definiert wird. Dieser Wert wird auf dieselbe Art und Weise festgelegt, wie im vorherigen ASPNETCORE_HTTPS_PORT-Beispiel.

Auf Computern, auf denen ASP.NET Core 3.0.0-Apps ausgeführt werden, sollte die ASP.NET Core 3.0.1-Runtime installiert werden, bevor das ANCM von ASP.NET Core 3.1.0 Preview 3 installiert wird. Dadurch kann sichergestellt werden, dass UseHttpsRedirection für ASP.NET Core 3.0-Apps weiterhin erwartungsgemäß ausgeführt wird.

In Azure App Service wird das ANCM aufgrund seiner globalen Natur gemäß eines von der Runtime unabhängigen Plans bereitgestellt. Das ANCM wurde in Azure nach den Bereitstellungen von ASP.NET Core 3.0.1 und ASP.NET Core 3.1.0 mit diesen Änderungen bereitgestellt.

Kategorie

ASP.NET Core

Betroffene APIs

HttpsPolicyBuilderExtensions.UseHttpsRedirection(IApplicationBuilder)

Hosting: IHostingEnvironment- und IApplicationLifetime-Typen als veraltet markiert und ersetzt

Es wurden neue Typen eingeführt, um die vorhandenen Typen IHostingEnvironment und IApplicationLifetime zu ersetzen.

Eingeführt in Version

3.0

Altes Verhalten

Es gab zwei verschiedene IHostingEnvironment- und IApplicationLifetime-Typen von Microsoft.Extensions.Hosting und Microsoft.AspNetCore.Hosting.

Neues Verhalten

Die alten Typen wurden als veraltet markiert und durch neue ersetzt.

Grund für die Änderung

Als Microsoft.Extensions.Hosting in ASP.NET Core 2.1 eingeführt wurde, wurden einige Typen wie IHostingEnvironment und IApplicationLifetime aus Microsoft.AspNetCore.Hosting kopiert. Einige Änderungen in ASP.NET Core 3.0 führen dazu, dass Apps die beiden Namespaces Microsoft.Extensions.Hosting und Microsoft.AspNetCore.Hosting enthalten. Jede Verwendung dieser doppelten Typen verursacht einen Compilerfehler aufgrund eines mehrdeutigen Verweises, wenn auf beide Namespaces verwiesen wird.

Ersetzen Sie alle Verwendungen der alten Typen wie unten gezeigt durch die neu eingeführten Typen:

Veraltete Typen (Warnung):

Neue Typen:

Die neuen Erweiterungsmethoden IHostEnvironment, IsDevelopment und IsProduction befinden sich im Microsoft.Extensions.Hosting-Namespace. Dieser Namespace muss Ihrem Projekt eventuell hinzugefügt werden.

Kategorie

ASP.NET Core

Betroffene APIs

Hosting: ObjectPoolProvider wurde aus WebHostBuilder-Abhängigkeiten entfernt

Um ASP.NET Core produktiver zu machen, wurde der ObjectPoolProvider aus dem Hauptsatz von Abhängigkeiten entfernt. Bestimmte Komponenten, die von ObjectPoolProvider abhängen, fügen sich jetzt selbst hinzu.

Weitere Informationen finden Sie unter dotnet/aspnetcore#5944.

Eingeführt in Version

3.0

Altes Verhalten

WebHostBuilder hat ObjectPoolProvider standardmäßig im Container für Abhängigkeitsinjektionen bereitgestellt.

Neues Verhalten

WebHostBuilder stellt ObjectPoolProvider nicht mehr standardmäßig im Container für Abhängigkeitsinjektionen bereit.

Grund für die Änderung

Diese Änderung wurde vorgenommen, um ASP.NET Core produktiver zu machen.

Wenn die Komponente ObjectPoolProvider erfordert, muss sie Ihren Abhängigkeiten über die IServiceCollection hinzugefügt werden.

Kategorie

ASP.NET Core

Betroffene APIs

Keine

HTTP: Erweiterbarkeit von DefaultHttpContext wurde entfernt

Im Rahmen der Leistungsverbesserungen in ASP.NET Core 3.0 wurde die Erweiterbarkeit von DefaultHttpContext aufgehoben. Die Klasse ist jetzt sealed. Weitere Informationen finden Sie unter dotnet/aspnetcore#6504.

Wenn Sie für Komponententests Mock<DefaultHttpContext> verwenden, nutzen Sie stattdessen Mock<HttpContext> oder new DefaultHttpContext().

Weitere Informationen finden Sie unter dotnet/aspnetcore#6534.

Eingeführt in Version

3.0

Altes Verhalten

Klassen konnten von DefaultHttpContext abgeleitet werden.

Neues Verhalten

Klassen können nicht mehr von DefaultHttpContext abgeleitet werden.

Grund für die Änderung

Die Erweiterbarkeit wurde anfänglich bereitgestellt, um das Pooling des HttpContext zu ermöglichen, sie führt aber zu einer unnötigen Komplexität und hat andere Optimierungen behindert.

Wenn Sie in Komponententests Mock<DefaultHttpContext> verwenden, nutzen Sie stattdessen Mock<HttpContext>.

Kategorie

ASP.NET Core

Betroffene APIs

Microsoft.AspNetCore.Http.DefaultHttpContext

HTTP: HeaderNames-Konstanten zu „static readonly“ geändert

Ab ASP.NET Core 3.0 Preview 5 wurden die Felder in Microsoft.Net.Http.Headers.HeaderNames von const in static readonly geändert.

Weitere Informationen finden Sie unter dotnet/aspnetcore#9514.

Eingeführt in Version

3.0

Altes Verhalten

Diese Felder waren const.

Neues Verhalten

Diese Felder sind nun static readonly.

Grund für die Änderung

Die Änderung hat folgende Gründe:

  • Sie verhindert, dass die Werte über Assemblygrenzen hinweg eingebettet werden, sodass bei Bedarf Korrekturen an Werten möglich sind.
  • Sie ermöglicht schnellere Überprüfungen der Verweisgleichheit.

Kompilieren Sie mit 3.0 neu. Sie müssen Quellcode ändern, der diese Felder auf folgende Weise verwendet:

  • Als unzulässiges Attributargument
  • Als einen case in einer switch-Anweisung
  • Beim Definieren einer anderen const

Um diesen Breaking Change zu umgehen, verwenden Sie selbst definierte Headernamenkonstanten oder Zeichenfolgenliterale.

Kategorie

ASP.NET Core

Betroffene APIs

Microsoft.Net.Http.Headers.HeaderNames

HTTP: Änderungen an der Infrastruktur von Antworttexten

Die Infrastruktur für HTTP-Antworttexte wurde geändert. Wenn Sie HttpResponse direkt verwenden, sollten keine Änderungen am Code erforderlich sein. Wenn Sie HttpResponse.Body umschließen oder auf HttpContext.Features zugreifen, lesen Sie weiter.

Eingeführt in Version

3.0

Altes Verhalten

Dem HTTP-Antworttext waren drei APIs zugeordnet:

  • IHttpResponseFeature.Body
  • IHttpSendFileFeature.SendFileAsync
  • IHttpBufferingFeature.DisableResponseBuffering

Neues Verhalten

Wenn Sie HttpResponse.Body ersetzen, wird das gesamte IHttpResponseBodyFeature durch einen Wrapper um den angegebenen Stream ersetzt, indem StreamResponseBodyFeature verwendet wird, um Standardimplementierungen für alle erwarteten APIs bereitzustellen. Durch das Zurücksetzen des ursprünglichen Streams wird diese Änderung zurückgesetzt.

Grund für die Änderung

Die Antworttext-APIs sollen in einer einzigen neuen Funktionsschnittstelle zusammengefasst werden.

Verwenden Sie IHttpResponseBodyFeature an den Stellen, an denen Sie zuvor IHttpResponseFeature.Body, IHttpSendFileFeature oder IHttpBufferingFeature verwendet haben.

Kategorie

ASP.NET Core

Betroffene APIs

Bei SameSite handelt es sich um eine Option für Cookies, mit der einige CSRF-Angriffe (Cross-Site Request Forgery, websiteübergreifende Anforderungsfälschung) entschärft werden können. Als diese Option erstmals eingeführt wurde, wurden inkonsistente Standardwerte für verschiedene ASP.NET Core-APIs verwendet. Diese Inkonsistenz führte zu verwirrenden Ergebnissen. Ab ASP.NET Core 3.0 sind diese Standardeinstellungen besser abgestimmt. Sie müssen dieses Feature auf Komponentenbasis aktivieren.

Eingeführt in Version

3.0

Altes Verhalten

Ähnliche ASP.NET Core-APIs verwendeten unterschiedliche SameSiteMode-Standardwerte. Ein Beispiel für die Inkonsistenz sind HttpResponse.Cookies.Append(String, String) und HttpResponse.Cookies.Append(String, String, CookieOptions), wofür die Standardwerte SameSiteMode.None bzw. SameSiteMode.Lax verwendet wurden.

Neues Verhalten

Alle betroffenen APIs verwenden standardmäßig SameSiteMode.None.

Grund für die Änderung

Der Standardwert wurde geändert, um SameSite zu einem Feature zu machen, das aktiviert werden muss.

Für jede Komponente, die Cookies ausgibt, muss entschieden werden, ob SameSite für die zugehörigen Szenarios geeignet ist. Überprüfen Sie die Nutzung der betroffenen APIs, und konfigurieren Sie SameSite nach Bedarf neu.

Kategorie

ASP.NET Core

Betroffene APIs

HTTP: Synchrones E/A auf allen Servern deaktiviert

Ab ASP.NET Core 3.0 sind synchrone Servervorgänge standardmäßig deaktiviert.

Änderungsbeschreibung

AllowSynchronousIO ist eine Option auf sämtlichen Servern, die synchrone E/A-APIs wie HttpRequest.Body.Read, HttpResponse.Body.Write und Stream.Flush aktiviert bzw. deaktiviert. Diese APIs waren schon länger Ursache für fehlende Threads und hängende Apps. Ab ASP.NET Core 3.0 Preview 3 sind diese synchronen Vorgänge standardmäßig deaktiviert.

Betroffene Server:

  • Kestrel
  • HttpSys
  • IIS In-Process
  • TestServer

Erwartbare Fehler:

  • Synchronous operations are disallowed. Call ReadAsync or set AllowSynchronousIO to true instead.
  • Synchronous operations are disallowed. Call WriteAsync or set AllowSynchronousIO to true instead.
  • Synchronous operations are disallowed. Call FlushAsync or set AllowSynchronousIO to true instead.

Jeder Server verfügt über eine AllowSynchronousIO-Option, die dieses Verhalten steuert und nun standardmäßig false ist.

Das Verhalten kann auch auf Anforderung als vorübergehende Entschärfung überschrieben werden. Beispiel:

var syncIOFeature = HttpContext.Features.Get<IHttpBodyControlFeature>();
if (syncIOFeature != null)
{
    syncIOFeature.AllowSynchronousIO = true;
}

Wenn Sie Probleme mit einem TextWriter oder einem anderen Stream haben, der eine synchrone API in Dispose aufruft, rufen Sie stattdessen die neue DisposeAsync-API auf.

Weitere Informationen finden Sie unter dotnet/aspnetcore#7644.

Eingeführt in Version

3.0

Altes Verhalten

HttpRequest.Body.Read, HttpResponse.Body.Write und Stream.Flush waren standardmäßig zulässig.

Neues Verhalten

Diese synchronen APIs sind nun standardmäßig nicht mehr zulässig:

Erwartbare Fehler:

  • Synchronous operations are disallowed. Call ReadAsync or set AllowSynchronousIO to true instead.
  • Synchronous operations are disallowed. Call WriteAsync or set AllowSynchronousIO to true instead.
  • Synchronous operations are disallowed. Call FlushAsync or set AllowSynchronousIO to true instead.

Grund für die Änderung

Diese synchronen APIs waren schon länger Ursache für fehlende Threads und hängende Apps. Ab ASP.NET Core 3.0 Preview 3 sind synchrone Vorgänge standardmäßig deaktiviert.

Verwenden Sie die asynchronen Versionen der Methoden. Das Verhalten kann auch auf Anforderung als vorübergehende Entschärfung überschrieben werden.

var syncIOFeature = HttpContext.Features.Get<IHttpBodyControlFeature>();
if (syncIOFeature != null)
{
    syncIOFeature.AllowSynchronousIO = true;
}

Kategorie

ASP.NET Core

Betroffene APIs

Identität: AddDefaultUI-Methodenüberladung wurde entfernt.

Ab ASP.NET Core 3.0 ist die Methodenüberladung IdentityBuilderUIExtensions.AddDefaultUI(IdentityBuilder,UIFramework) nicht mehr vorhanden.

Eingeführt in Version

3.0

Grund für die Änderung

Diese Änderung wurde aufgrund der Einführung der Funktion für statische Webressourcen notwendig.

Rufen Sie anstelle der Überladung IdentityBuilderUIExtensions.AddDefaultUI(IdentityBuilder) auf, die zwei Argumente akzeptiert. Wenn Sie Bootstrap 3 verwenden, fügen Sie außerdem die folgende Zeile in einem <PropertyGroup>-Element in Ihrer Projektdatei hinzu:

<IdentityUIFrameworkVersion>Bootstrap3</IdentityUIFrameworkVersion>

Kategorie

ASP.NET Core

Betroffene APIs

IdentityBuilderUIExtensions.AddDefaultUI(IdentityBuilder,UIFramework)

Identität: Bootstrap-Standardversion der Benutzeroberfläche geändert

Ab ASP.NET Core 3.0 verwendet die Identitäts-Benutzeroberfläche standardmäßig Version 4 von Bootstrap.

Eingeführt in Version

3.0

Altes Verhalten

Der services.AddDefaultIdentity<IdentityUser>().AddDefaultUI();-Methodenaufruf war mit services.AddDefaultIdentity<IdentityUser>().AddDefaultUI(UIFramework.Bootstrap3); identisch.

Neues Verhalten

Der services.AddDefaultIdentity<IdentityUser>().AddDefaultUI();-Methodenaufruf ist mit services.AddDefaultIdentity<IdentityUser>().AddDefaultUI(UIFramework.Bootstrap4); identisch.

Grund für die Änderung

Bootstrap 4 wurde im Zeitrahmen von ASP.NET Core 3.0 veröffentlicht.

Diese Änderung hat Auswirkungen auf Ihre Arbeit, wenn Sie die Standardbenutzeroberfläche für Identitäten verwenden und diese in Startup.ConfigureServices hinzugefügt haben, wie im folgenden Beispiel gezeigt:

services.AddDefaultIdentity<IdentityUser>().AddDefaultUI();

Führen Sie eine der folgenden Aktionen aus:

  • Migrieren Sie Ihre App mithilfe der Migrationsanleitung zur Verwendung von Bootstrap 4.

  • Aktualisieren Sie Startup.ConfigureServices, um die Verwendung von Bootstrap 3 zu erzwingen. Zum Beispiel:

    services.AddDefaultIdentity<IdentityUser>().AddDefaultUI(UIFramework.Bootstrap3);

Kategorie

ASP.NET Core

Betroffene APIs

Keine

Identität: SignInAsync löst eine Ausnahme für eine nicht authentifizierte Identität aus

Standardmäßig löst SignInAsync eine Ausnahme für Prinzipale/Identitäten aus, bei denen IsAuthenticatedfalse ist.

Eingeführt in Version

3.0

Altes Verhalten

SignInAsync akzeptiert alle Prinzipale/Identitäten, einschließlich Identitäten, bei denen IsAuthenticatedfalse ist.

Neues Verhalten

Standardmäßig löst SignInAsync eine Ausnahme für Prinzipale/Identitäten aus, bei denen IsAuthenticatedfalse ist. Es gibt ein neues Flag, mit dem dieses Verhalten unterdrückt werden kann, aber das Standardverhalten wurde geändert.

Grund für die Änderung

Das alte Verhalten war problematisch, da diese Prinzipale standardmäßig von [Authorize] / RequireAuthenticatedUser() abgelehnt wurden.

In ASP.NET Core 3.0 Preview 6 gibt es das Flag RequireAuthenticatedSignIn in AuthenticationOptions, das standardmäßig true ist. Legen Sie dieses Flag auf false fest, um das alte Verhalten wiederherzustellen.

Kategorie

ASP.NET Core

Betroffene APIs

Keine

Identität: SignInManager-Konstruktor akzeptiert neuen Parameter

Ab ASP.NET Core 3.0 wurde dem SignInManager-Konstruktor ein neuer IUserConfirmation<TUser>-Parameter hinzugefügt. Weitere Informationen finden Sie unter dotnet/aspnetcore#8356.

Eingeführt in Version

3.0

Grund für die Änderung

Diese Änderung war erforderlich, um Unterstützung für neue E-Mail-/Bestätigungsflows für Identitäten zu erzielen.

Wenn Sie manuell einen SignInManager erstellen, stellen Sie eine Implementierung von IUserConfirmation bereit, oder nutzen Sie dafür eine der Abhängigkeitsinjektion.

Kategorie

ASP.NET Core

Betroffene APIs

SignInManager<TUser>

Identität: Benutzeroberfläche verwendet Funktion für statische Webressourcen

In ASP.NET Core 3.0 wurde eine Funktion für statische Webressourcen eingeführt, an die die Identitäts-Benutzeroberfläche nun angepasst wurde.

Änderungsbeschreibung

Die Identitäts-Benutzeroberfläche wurde an die Funktion für statische Webressourcen angepasst:

  • Die Auswahl des Frameworks erfolgt mithilfe der IdentityUIFrameworkVersion-Eigenschaft in Ihrer Projektdatei.
  • Bootstrap 4 ist das Standardframework für die Identitäts-Benutzeroberfläche. Bootstrap 3 hat das Ende des Lebenszyklus erreicht, und Sie sollten zu einer unterstützten Version migrieren.

Eingeführt in Version

3.0

Altes Verhalten

Das Standardframework für die Identitäts-Benutzeroberfläche war bisher Bootstrap 3. Das Benutzeroberflächen-Framework kann mithilfe eines Parameters im AddDefaultUI-Methodenaufruf in Startup.ConfigureServices konfiguriert werden.

Neues Verhalten

Das Standardframework für die Identitäts-Benutzeroberfläche ist nun Bootstrap 4. Das Benutzeroberflächen-Framework muss in der Projektdatei und nicht mehr im AddDefaultUI-Methodenaufruf konfiguriert werden.

Grund für die Änderung

Durch die Einführung der Funktion für statische Webressourcen musste die Konfiguration des Benutzeroberflächen-Frameworks auf MSBuild umgestellt werden. Die Entscheidung über das einzubettende Framework wird zur Buildzeit und nicht zur Laufzeit getroffen.

Überprüfen Sie die Website-Benutzeroberfläche, um sicherzustellen, dass die neuen Bootstrap 4-Komponenten kompatibel sind. Verwenden Sie ggf. die MSBuild-Eigenschaft IdentityUIFrameworkVersion, um zu Bootstrap 3 zurückzukehren. Fügen Sie die-Eigenschaft einem <PropertyGroup>-Element in Ihrer Projektdatei hinzu:

<IdentityUIFrameworkVersion>Bootstrap3</IdentityUIFrameworkVersion>

Kategorie

ASP.NET Core

Betroffene APIs

IdentityBuilderUIExtensions.AddDefaultUI(IdentityBuilder, UIFramework)

Kestrel: Verbindungsadapter wurde entfernt

Als Teil der Umstellung von „pubternal“-APIs zu public wurde das Konzept eines IConnectionAdapter aus Kestrel entfernt. Verbindungsadapter wurden durch Verbindungsmiddleware ersetzt. Diese ähnelt der HTTP-Middleware in der ASP.NET Core-Pipeline, ist aber für Verbindungen auf niedrigerer Ebene konzipiert. Die HTTPS- und Verbindungsprotokollierung wurden von den Verbindungsadaptern zur Verbindungsmiddleware verschoben. Diese Erweiterungsmethoden sollten weiterhin nahtlos funktionieren, aber die Implementierungsdetails wurden geändert.

Weitere Informationen finden Sie unter dotnet/aspnetcore#11412. Weitere Informationen finden Sie unter dotnet/aspnetcore#11475.

Eingeführt in Version

3.0

Altes Verhalten

Kestrel-Erweiterbarkeitskomponenten wurden mit IConnectionAdapter erstellt.

Neues Verhalten

Kestrel-Erweiterbarkeitskomponenten werden als Middleware erstellt.

Grund für die Änderung

Mit dieser Änderung soll eine flexiblere Erweiterbarkeitsarchitektur bereitgestellt werden.

Stellen Sie alle Implementierungen von IConnectionAdapter wie hier gezeigt auf das neue Middlewarekonzept um.

Kategorie

ASP.NET Core

Betroffene APIs

Microsoft.AspNetCore.Server.Kestrel.Core.Adapter.Internal.IConnectionAdapter

Kestrel: Leere HTTPS-Assembly wurde entfernt

Die Assembly Microsoft.AspNetCore.Server.Kestrel.Https wurde entfernt.

Eingeführt in Version

3.0

Grund für die Änderung

In ASP.NET Core 2.1 wurde der Inhalt von Microsoft.AspNetCore.Server.Kestrel.Https nach Microsoft.AspNetCore.Server.Kestrel.Core verschoben. Diese Änderung wurde ohne Breaking Change mithilfe von [TypeForwardedTo]-Attributen durchgeführt.

  • In Bibliotheken, die auf Microsoft.AspNetCore.Server.Kestrel.Https 2.0 verweisen, sollten alle ASP.NET Core-Abhängigkeiten auf 2.1 oder höher aktualisiert werden. Andernfalls können sie beim Laden in eine ASP.NET Core 3.0-App unterbrochen werden.
  • In Apps und Bibliotheken, die auf ASP.NET Core 2.1 und höher abzielen, sollten alle direkten Verweise auf das NuGet-Paket Microsoft.AspNetCore.Server.Kestrel.Https entfernt werden.

Kategorie

ASP.NET Core

Betroffene APIs

Keine

Kestrel: Anforderungstrailer-Header wurden in neue Sammlung verschoben

In früheren Versionen fügte Kestrel aufgeteilte HTTP/1.1-Trailer-Header in die Sammlung der Anforderungsheader ein, wenn der Anforderungstext bis zum Ende gelesen wurde. Durch dieses Verhalten war keine eindeutige Trennung zwischen Headern und Trailern möglich. Es wurde entschieden, die Trailer in eine neue Sammlung zu verschieben.

HTTP/2-Anforderungstrailer waren in ASP.NET Core 2.2 nicht verfügbar. Sie sind jetzt aber in dieser neuen Sammlung in ASP.NET Core 3.0 enthalten.

Für den Zugriff auf diese Trailer wurden neue Anforderungserweiterungsmethoden hinzugefügt.

HTTP/1.1-Trailer sind verfügbar, sobald der gesamte Anforderungstext gelesen wurde.

HTTP/2-Trailer sind verfügbar, sobald sie vom Client empfangen wurden. Der Client sendet die Trailer erst, wenn der gesamte Anforderungstext mindestens vom Server gepuffert wurde. Sie müssen möglicherweise den Anforderungstext lesen, um Pufferspeicher freizugeben. Trailer sind immer verfügbar, wenn Sie den Anforderungstext bis zum Ende lesen. Die Trailer markieren das Ende des Texts.

Eingeführt in Version

3.0

Altes Verhalten

Anforderungstrailer-Header wurden der Sammlung HttpRequest.Headers hinzugefügt.

Neues Verhalten

Anforderungstrailer-Header sind nicht in der Sammlung HttpRequest.Headers enthalten. Verwenden Sie die folgenden Erweiterungsmethoden in HttpRequest, um darauf zuzugreifen:

  • GetDeclaredTrailers() ruft den Anforderungsheader „Trailer“ ab, in dem aufgelistet wird, welche Trailer nach dem Text erwartet werden.
  • SupportsTrailers() gibt an, ob die Anforderung das Empfangen von Trailer-Headern unterstützt.
  • CheckTrailersAvailable() legt fest, ob die Anforderung Trailer unterstützt und ob diese zum Lesen verfügbar sind.
  • GetTrailer(string trailerName) ruft den angeforderten Trailer-Header aus der Antwort ab.

Grund für die Änderung

Trailer stellen ein wichtiges Feature in Szenarien wie gRPC dar. Das Zusammenführen der Trailer mit den Anforderungsheadern war für Benutzer verwirrend.

Verwenden Sie die trailerbezogenen Erweiterungsmethoden in HttpRequest, um auf Trailer zuzugreifen.

Kategorie

ASP.NET Core

Betroffene APIs

HttpRequest.Headers

Kestrel: Transportabstraktionen entfernt und öffentlich gemacht

Im Rahmen der Umstellung von „pubternal“-APIs werden die Kestrel-APIs auf der Datentransportschicht als öffentliche Schnittstelle in der Microsoft.AspNetCore.Connections.Abstractions-Bibliothek verfügbar gemacht.

Eingeführt in Version

3.0

Altes Verhalten

  • Abstraktionen zum Datentransport waren in der Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions-Bibliothek verfügbar.
  • Die ListenOptions.NoDelay-Eigenschaft war verfügbar.

Neues Verhalten

  • Die IConnectionListener-Schnittstelle wurde in der Microsoft.AspNetCore.Connections.Abstractions-Bibliothek eingeführt, um die am häufigsten verwendeten Funktionen aus der ...Transport.Abstractions-Bibliothek verfügbar zu machen.
  • NoDelay ist nun in den Datentransportoptionen (LibuvTransportOptions und SocketTransportOptions) verfügbar.
  • SchedulingMode ist nicht mehr verfügbar.

Grund für die Änderung

In ASP.NET Core 3.0 werden keine „pubternal“-APIs mehr verwendet.

Kategorie

ASP.NET Core

Betroffene APIs

Keine

Lokalisierung: ResourceManagerWithCultureStringLocalizer und WithCulture wurden als veraltet markiert.

Die ResourceManagerWithCultureStringLocalizer-Klasse und der Schnittstellenmember WithCulture führten häufig zu Verwirrung bei Benutzern der Lokalisierung, insbesondere bei der Erstellung einer eigenen Implementierung von IStringLocalizer. Diese Elemente vermittelten dem Benutzer den Eindruck, dass eine IStringLocalizer-Instanz lediglich „pro Sprache, pro Ressource“ gilt. Tatsächlich sollten die Instanzen nur „pro Ressource“ gelten. Die gesuchte Sprache wird zur Ausführungszeit von der CultureInfo.CurrentUICulture festgelegt. Um dieses Problem zu beheben, wurden die APIs in ASP.NET Core 3.0 als veraltet markiert. Die APIs werden in einem der nächsten Releases entfernt.

Weitere Kontextinformationen finden Sie unter dotnet/aspnetcore#3324. Weitere Informationen finden Sie unter dotnet/aspnetcore#7756.

Eingeführt in Version

3.0

Altes Verhalten

Methoden wurden nicht als Obsolete gekennzeichnet.

Neues Verhalten

Methoden werden als Obsolete gekennzeichnet.

Grund für die Änderung

Die APIs stellten einen Anwendungsfall dar, der nicht empfohlen wird. Der Entwurf der Lokalisierung war unklar.

Es wird empfohlen, stattdessen ResourceManagerStringLocalizer zu verwenden. Lassen Sie die Kultur durch CurrentCulture festlegen. Falls dies nicht möglich ist, erstellen Sie eine Kopie von ResourceManagerWithCultureStringLocalizer, und verwenden Sie diese.

Kategorie

ASP.NET Core

Betroffene APIs

  • Microsoft.Extensions.Localization.ResourceManagerWithCultureStringLocalizer
  • Microsoft.Extensions.Localization.ResourceManagerStringLocalizer.WithCulture

Protokollierung: DebugLogger-Klasse wurde als „internal“ deklariert

Vor ASP.NET Core 3.0 war public Zugriffsmodifizierer von DebugLogger. In ASP.NET Core 3.0 wurde der Zugriffsmodifizierer in internal geändert.

Eingeführt in Version

3.0

Grund für die Änderung

Die Änderung erfolgt aus folgenden Gründen:

  • Erzwingen von Konsistenz mit anderen Protokollierungsimplementierungen, z. B. ConsoleLogger
  • Reduzieren der API-Oberfläche

Verwenden Sie die AddDebug ILoggingBuilder-Erweiterungsmethode, um die Debugprotokollierung zu aktivieren. DebugLoggerProvider ist auch weiterhin public, wenn der Dienst manuell registriert werden muss.

Kategorie

ASP.NET Core

Betroffene APIs

Microsoft.Extensions.Logging.Debug.DebugLogger

MVC: Async-Suffix aus Controlleraktionsnamen entfernt

Im Zusammenhang mit dotnet/aspnetcore#4849 entfernt ASP.NET Core MVC das Suffix Async standardmäßig aus Aktionsnamen. Ab ASP.NET Core 3.0 wirkt sich diese Änderung sowohl auf das Routing als auch auf die Linkgenerierung aus.

Eingeführt in Version

3.0

Altes Verhalten

Nehmen Sie den folgenden ASP.NET Core MVC-Controller an:

public class ProductController : Controller
{
    public async IActionResult ListAsync()
    {
        var model = await DbContext.Products.ToListAsync();
        return View(model);
    }
}

Die Aktion ist über Product/ListAsync routingfähig. Für die Linkgenerierung muss das Suffix Async angegeben werden. Beispiel:

<a asp-controller="Product" asp-action="ListAsync">List</a>

Neues Verhalten

In ASP.NET Core 3.0 ist die Aktion über Product/List routingfähig. Der Code zur Linkgenerierung sollte das Suffix Async nicht verwenden. Beispiel:

<a asp-controller="Product" asp-action="List">List</a>

Diese Änderung hat keine Auswirkungen auf Namen, die mit dem [ActionName]-Attribut angegeben werden. Sie können neue Verhalten deaktivieren, indem Sie MvcOptions.SuppressAsyncSuffixInActionNames in Startup.ConfigureServices auf false festlegen:

services.AddMvc(options =>
{
   options.SuppressAsyncSuffixInActionNames = false;
});

Grund für die Änderung

Es gibt die Konvention, asynchrone .NET-Methoden durch das Suffix Async zu kennzeichnen. Wenn eine Methode jedoch eine MVC-Aktion definiert, ist das Suffix Async nicht wünschenswert.

Wenn Ihre App von MVC-Aktionen abhängig ist, die das Suffix Async im Namen beibehalten, führen Sie eine der folgenden Maßnahmen aus:

  • Verwenden Sie das [ActionName]-Attribut, um den ursprünglichen Namen beizubehalten.
  • Deaktivieren Sie das Umbenennen vollständig, indem Sie MvcOptions.SuppressAsyncSuffixInActionNames in Startup.ConfigureServices auf false festlegen:
services.AddMvc(options =>
{
   options.SuppressAsyncSuffixInActionNames = false;
});

Kategorie

ASP.NET Core

Betroffene APIs

Keine

MVC: JsonResult wurde in Microsoft.AspNetCore.Mvc.Core verschoben

JsonResult wurde in die Microsoft.AspNetCore.Mvc.Core-Assembly verschoben. Dieser Typ wurde bisher in Microsoft.AspNetCore.Mvc.Formatters.Json definiert. Ein [TypeForwardedTo]-Attribut auf Assemblyebene wurde Microsoft.AspNetCore.Mvc.Formatters.Json hinzugefügt, um dieses Problem für die Mehrheit der Benutzer zu beheben. Bei Apps, die Bibliotheken von Drittanbietern verwenden, treten möglicherweise Probleme auf.

Eingeführt in Version

3.0 Vorschau 6

Altes Verhalten

Eine App, die eine auf Version 2.2 basierende Bibliothek verwendet, wird erfolgreich erstellt.

Neues Verhalten

Für eine App, die eine auf Version 2.2 basierende Bibliothek verwendet, schlägt die Kompilierung fehl. Eine Fehlermeldung, die ähnlich wie der folgende Text lautet, wird bereitgestellt:

The type 'JsonResult' exists in both 'Microsoft.AspNetCore.Mvc.Core, Version=3.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60' and 'Microsoft.AspNetCore.Mvc.Formatters.Json, Version=2.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'

Ein Beispiel für ein solches Problem finden Sie unter dotnet/aspnetcore#7220.

Grund für die Änderung

Änderungen auf Plattformebene an der Zusammenstellung von ASP.NET Core wie unter aspnet/Announcements#325 beschrieben.

Bibliotheken, die anhand von Version 2.2 von Microsoft.AspNetCore.Mvc.Formatters.Json kompiliert wurden, müssen möglicherweise erneut kompiliert werden, um das Problem für alle Benutzer zu beheben. Wenden Sie sich an den Autor der Bibliothek, wenn Sie davon betroffen sind. Fordern Sie eine Neukompilierung der Bibliothek mit dem Ziel ASP.NET Core 3.0 an.

Kategorie

ASP.NET Core

Betroffene APIs

Microsoft.AspNetCore.Mvc.JsonResult

MVC: Vorkompilierungstool wurde als veraltet markiert

In ASP.NET Core 1.1 wurde das Paket Microsoft.AspNetCore.Mvc.Razor.ViewCompilation (MVC-Vorkompilierungstool) eingeführt, um die Kompilierung von Razor-Dateien (CSHTML-Dateien) bei der Veröffentlichung zu unterstützen. In ASP.NET Core 2.1 wurde das Razor SDK eingeführt, um die Funktionen des Vorkompilierungstools zu erweitern. Mit dem Razor SDK wurde auch die Möglichkeit geschaffen, Razor-Dateien bei der Erstellung und Veröffentlichung zu kompilieren. Das SDK überprüft die Richtigkeit der CSHTML-Dateien zur Erstellungszeit und verbessert gleichzeitig die Startzeit der App. Das Razor SDK ist standardmäßig aktiviert und kann ohne weitere Aktion verwendet werden.

In ASP.NET Core 3.0 wurde das MVC-Vorkompilierungstool aus der Zeit von ASP.NET Core 1.1 entfernt. Frühere Paketversionen erhalten weiterhin wichtige Fehler- und Sicherheitskorrekturen, wenn Patches veröffentlicht werden.

Eingeführt in Version

3.0

Altes Verhalten

Das Paket Microsoft.AspNetCore.Mvc.Razor.ViewCompilation wurde zum Vorkompilieren von MVC-Razor-Ansichten verwendet.

Neues Verhalten

Das Razor SDK unterstützt diese Funktion nun nativ. Das Paket Microsoft.AspNetCore.Mvc.Razor.ViewCompilation wird nicht mehr aktualisiert.

Grund für die Änderung

Das Razor SDK bietet mehr Funktionen und überprüft die Richtigkeit der CSHTML-Dateien zur Erstellungszeit. Das SDK verbessert auch die Startzeit von Apps.

Benutzer von ASP.NET Core 2.1 oder höher sollten auf die native Unterstützung für die Vorkompilierung im Razor SDK wechseln. Wenn Fehler oder fehlende Features die Migration zum Razor SDK verhindern, melden Sie auf dotnet/aspnetcore ein Problem.

Kategorie

ASP.NET Core

Betroffene APIs

Keine

MVC: pubternal-Typen zu internal-Typen geändert

In ASP.NET Core 3.0 wurden alle „pubternal“-Typen in MVC je nach Anwendungsfall in public in einem unterstützten Namespace oder in internal geändert.

Änderungsbeschreibung

In ASP.NET Core werden „pubternal“-Typen als public deklariert, befinden sich jedoch in einem Namespace mit dem Suffix .Internal. Diese Typen sind zwar public, sie verfügen jedoch nicht über eine Unterstützungsrichtlinie und können daher Breaking Changes unterliegen. Da diese Typen leider relativ häufig versehentlich verwendet werden, können an diesen Projekten Breaking Changes auftreten, und die Fähigkeit zum Verwalten des Frameworks kann eingeschränkt werden.

Eingeführt in Version

3.0

Altes Verhalten

Einige Typen in MVC waren public – aber in einem .Internal-Namespace. Diese Typen verfügten nicht über eine Unterstützungsrichtlinie und konnten daher Breaking Changes unterliegen.

Neues Verhalten

Alle diese Typen wurden entweder als public in einem unterstützten Namespace oder als internal gekennzeichnet.

Grund für die Änderung

Da die „pubternal“-Typen relativ häufig versehentlich verwendet wurden, konnten an diesen Projekten Breaking Changes auftreten, und die Fähigkeit zum Verwalten des Frameworks konnte eingeschränkt werden.

Wenn Sie Typen verwenden, die tatsächlich public waren und in einen neuen, unterstützten Namespace verschoben wurden, aktualisieren Sie Ihre Verweise entsprechend den neuen Namespaces.

Wenn Sie Typen verwenden, die als internal gekennzeichnet wurden, müssen Sie eine Alternative suchen. Die zuvor als „pubternal“ deklarierten Typen waren nie für die öffentliche Verwendung vorgesehen. Wenn diese Namespaces bestimmte Typen enthalten, die für Ihre Apps wichtig sind, melden Sie ein Problem bei dotnet/aspnetcore. Es ist eventuell möglich, die angeforderten Typen public zu machen.

Kategorie

ASP.NET Core

Betroffene APIs

Diese Änderung umfasst Typen in den folgenden Namespaces:

  • Microsoft.AspNetCore.Mvc.Cors.Internal
  • Microsoft.AspNetCore.Mvc.DataAnnotations.Internal
  • Microsoft.AspNetCore.Mvc.Formatters.Internal
  • Microsoft.AspNetCore.Mvc.Formatters.Json.Internal
  • Microsoft.AspNetCore.Mvc.Formatters.Xml.Internal
  • Microsoft.AspNetCore.Mvc.Internal
  • Microsoft.AspNetCore.Mvc.ModelBinding.Internal
  • Microsoft.AspNetCore.Mvc.Razor.Internal
  • Microsoft.AspNetCore.Mvc.RazorPages.Internal
  • Microsoft.AspNetCore.Mvc.TagHelpers.Internal
  • Microsoft.AspNetCore.Mvc.ViewFeatures.Internal

MVC: Web-API-Kompatibilitätsshim wurde entfernt

Ab ASP.NET Core 3.0 ist das Paket Microsoft.AspNetCore.Mvc.WebApiCompatShim nicht mehr verfügbar.

Änderungsbeschreibung

Das Paket Microsoft.AspNetCore.Mvc.WebApiCompatShim (WebApiCompatShim) bietet partielle Kompatibilität in ASP.NET Core mit der ASP.NET 4.x-Web-API 2, um die Migration vorhandener Web-API-Implementierungen zu ASP.NET Core zu vereinfachen. Apps, die WebApiCompatShim verwenden, profitieren jedoch nicht von den API-bezogenen Features der letzten ASP.NET Core-Releases. Zu diesen Features zählen die verbesserte Generierung von Open API-Spezifikationen, die standardisierte Fehlerbehandlung und die Generierung von Clientcode. Um die API in 3.0 noch weiter zu optimieren, wurde WebApiCompatShim entfernt. Vorhandene Apps, die WebApiCompatShim verwenden, sollten zum neueren [ApiController]-Modell migriert werden.

Eingeführt in Version

3.0

Grund für die Änderung

Das Web-API-Kompatibilitätsshim war ein Migrationstool. Es beschränkt den Benutzerzugriff auf neue Funktionen, die in ASP.NET Core hinzugefügt wurden.

Entfernen Sie alle Verwendungen dieses Shims, und migrieren Sie direkt zu der entsprechenden Funktionalität in ASP.NET Core.

Kategorie

ASP.NET Core

Betroffene APIs

Microsoft.AspNetCore.Mvc.WebApiCompatShim

Razor: RazorTemplateEngine-API wurde entfernt

Die API RazorTemplateEngine wurde entfernt und durch Microsoft.AspNetCore.Razor.Language.RazorProjectEngine ersetzt.

Weitere Informationen finden Sie unter dem GitHub-Issue dotnet/aspnetcore#25215.

Eingeführt in Version

3.0

Altes Verhalten

Ein Vorlagen-Engine kann erstellt und zum Analysieren und Generieren von Code für Razor-Dateien verwendet werden.

Neues Verhalten

RazorProjectEngine kann erstellt und mit derselben Art von Informationen wie RazorTemplateEngine versorgt werden, um Code für Razor-Dateien zu analysieren und zu generieren. RazorProjectEngine stellt außerdem zusätzliche Konfigurationsebenen bereit.

Grund für die Änderung

RazorTemplateEngine war zu eng an die vorhandenen Implementierungen gekoppelt. Diese enge Kopplung führte zu weiteren Fragen beim Versuch, eine Razor-Pipeline für die Analyse/Generierung von Code ordnungsgemäß zu konfigurieren.

Verwenden Sie RazorProjectEngine anstelle von RazorTemplateEngine. Betrachten Sie die folgenden Beispiele.

Erstellen und Konfigurieren der RazorProjectEngine-API
RazorProjectEngine projectEngine =
    RazorProjectEngine.Create(RazorConfiguration.Default,
        RazorProjectFileSystem.Create(@"C:\source\repos\ConsoleApp4\ConsoleApp4"),
        builder =>
        {
            builder.ConfigureClass((document, classNode) =>
            {
                classNode.ClassName = "MyClassName";

                // Can also configure other aspects of the class here.
            });

            // More configuration can go here
        });
Generieren von Code für eine Razor-Datei
RazorProjectItem item = projectEngine.FileSystem.GetItem(
    @"C:\source\repos\ConsoleApp4\ConsoleApp4\Example.cshtml",
    FileKinds.Legacy);
RazorCodeDocument output = projectEngine.Process(item);

// Things available
RazorSyntaxTree syntaxTree = output.GetSyntaxTree();
DocumentIntermediateNode intermediateDocument =
    output.GetDocumentIntermediateNode();
RazorCSharpDocument csharpDocument = output.GetCSharpDocument();

Kategorie

ASP.NET Core

Betroffene APIs

  • RazorTemplateEngine
  • RazorTemplateEngineOptions

Razor: Laufzeitkompilierung wurde in ein Paket verschoben

Die Unterstützung für die Laufzeitkompilierung von Razor-Ansichten und Razor Pages wurde in ein separates Paket verschoben.

Eingeführt in Version

3.0

Altes Verhalten

Die Laufzeitkompilierung ist ohne zusätzliche Pakete verfügbar.

Neues Verhalten

Die Funktionalität wurde in das Paket Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation verschoben.

Die folgenden APIs waren bereits in Microsoft.AspNetCore.Mvc.Razor.RazorViewEngineOptions zur Unterstützung der Laufzeitkompilierung verfügbar. Die APIs sind jetzt über Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.MvcRazorRuntimeCompilationOptions verfügbar.

  • RazorViewEngineOptions.FileProviders ist jetzt MvcRazorRuntimeCompilationOptions.FileProviders
  • RazorViewEngineOptions.AdditionalCompilationReferences ist jetzt MvcRazorRuntimeCompilationOptions.AdditionalReferencePaths

Darüber hinaus wurde Microsoft.AspNetCore.Mvc.Razor.RazorViewEngineOptions.AllowRecompilingViewsOnFileChange entfernt. Die erneute Kompilierung von Dateiänderungen wird durch einen Verweis auf das Paket Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation standardmäßig aktiviert.

Grund für die Änderung

Diese Änderung war erforderlich, um die Abhängigkeit des freigegebenen ASP.NET Core-Frameworks von Roslyn aufzuheben.

Für Apps, die eine Laufzeitkompilierung oder eine erneute Kompilierung von Razor-Dateien erfordern, sollten die folgenden Schritte ausgeführt werden:

  1. Fügen Sie einen Verweis auf das Paket Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation hinzu.

  2. Aktualisieren Sie die Startup.ConfigureServices-Methode des Projekts so, dass diese einen Aufruf von AddRazorRuntimeCompilation enthält. Zum Beispiel:

    services.AddMvc()
    .AddRazorRuntimeCompilation();

Kategorie

ASP.NET Core

Betroffene APIs

Microsoft.AspNetCore.Mvc.Razor.RazorViewEngineOptions

Sitzungszustand: Veraltete APIs wurden entfernt

Veraltete APIs zum Konfigurieren von Sitzungscookies wurden entfernt. Weitere Informationen finden Sie unter aspnet/Announcements#257.

Eingeführt in Version

3.0

Grund für die Änderung

Diese Änderung erzwingt Konsistenz zwischen APIs zum Konfigurieren von Funktionen, die Cookies verwenden.

Migrieren Sie alle Verwendungen der entfernten APIs zu ihren neueren Ersetzungen. Betrachten Sie das folgende Beispiel in Startup.ConfigureServices:

public void ConfigureServices(ServiceCollection services)
{
    services.AddSession(options =>
    {
        // Removed obsolete APIs
        options.CookieName = "SessionCookie";
        options.CookieDomain = "contoso.com";
        options.CookiePath = "/";
        options.CookieHttpOnly = true;
        options.CookieSecure = CookieSecurePolicy.Always;

        // new API
        options.Cookie.Name = "SessionCookie";
        options.Cookie.Domain = "contoso.com";
        options.Cookie.Path = "/";
        options.Cookie.HttpOnly = true;
        options.Cookie.SecurePolicy = CookieSecurePolicy.Always;
    });
}

Kategorie

ASP.NET Core

Betroffene APIs

Freigegebenes Framework: Assemblys aus Microsoft.AspNetCore.App entfernt

Ab ASP.NET Core 3.0 enthält das freigegebene ASP.NET Core-Framework (Microsoft.AspNetCore.App) nur Erstanbieterassemblys, die vollständig von Microsoft entwickelt, unterstützt und verwaltet werden.

Änderungsbeschreibung

Stellen Sie sich die Änderung als Neudefinition der Grenzen für die ASP.NET Core-„Plattform“ vor. Das freigegebene Framework kann von allen Benutzern über GitHub aus der Quelle erstellt werden und bietet Ihren Apps auch weiterhin die bereits vorhandenen Vorteile der freigegebenen .NET Core-Frameworks. Zu den Vorteilen zählen die kleinere Bereitstellungsgröße, das zentralisierte Patchen und die schnellere Startzeit.

Im Rahmen der Änderung werden einige wichtige Breaking Changes in Microsoft.AspNetCore.App eingeführt.

Eingeführt in Version

3.0

Altes Verhalten

Projekte verwiesen über ein <PackageReference>-Element in der Projektdatei auf Microsoft.AspNetCore.App.

Außerdem enthielt Microsoft.AspNetCore.App die folgenden Unterkomponenten:

  • Json.NET (Newtonsoft.Json)
  • Entity Framework Core (Assemblys mit Präfix Microsoft.EntityFrameworkCore.)
  • Roslyn (Microsoft.CodeAnalysis)

Neues Verhalten

Für einen Verweis auf Microsoft.AspNetCore.App ist kein <PackageReference>-Element in der Projektdatei mehr erforderlich. Das .NET Core SDK unterstützt ein neues Element mit dem Namen <FrameworkReference>, das <PackageReference> ersetzt.

Weitere Informationen finden Sie unter dotnet/aspnetcore#3612.

Entity Framework Core wird als NuGet-Pakete bereitgestellt. Diese Änderung stellt eine Anpassung an das Auslieferungsmodell aller anderen Datenzugriffsbibliotheken in .NET dar. Es bietet Entity Framework Core die einfachste Möglichkeit, weiterhin Innovationen mit Unterstützung der verschiedenen .NET-Plattformen zu schaffen. Das Verschieben von Entity Framework Core aus dem freigegebenen Framework hat keine Auswirkung auf seinen Status als eine von Microsoft entwickelte, unterstützte und gewartete Bibliothek. Die .NET Core-Supportrichtlinie gilt auch weiterhin.

Json.NET und Entity Framework Core funktionieren auch In Zukunft mit ASP.NET Core. Sie sind jedoch nicht mehr im freigegebenen Framework enthalten.

Weitere Informationen finden Sie unter The future of JSON in .NET Core 3.0 (Die Zukunft von JSON in .NET Core 3.0). Sehen Sie sich auch die komplette Liste der Binärdateien an, die aus dem freigegebenen Framework entfernt wurden.

Grund für die Änderung

Diese Änderung vereinfacht die Verwendung von Microsoft.AspNetCore.App und verringert Duplizierungen zwischen NuGet-Paketen und freigegebenen Frameworks.

Weitere Informationen zu den Gründen für diese Änderung finden Sie in diesem Blogbeitrag.

Ab ASP.NET Core 3.0 ist es nicht mehr erforderlich, dass Projekte Assemblys in Microsoft.AspNetCore.App als NuGet-Pakete verwenden. Um die Ausrichtung und Verwendung des freigegebenen ASP.NET Core-Frameworks zu vereinfachen, werden viele NuGet-Pakete, die seit ASP.NET Core 1.0 eingeführt wurden, nicht mehr erstellt. Die von diesen Paketen bereitgestellten APIs sind für Apps weiterhin mithilfe eines <FrameworkReference> auf Microsoft.AspNetCore.App verfügbar. Beispiele für gängige APIs sind Kestrel, MVC und Razor.

Diese Änderung gilt nicht für alle Binärdateien, auf die über Microsoft.AspNetCore.App in ASP.NET Core 2.x verwiesen wird. Wichtige Ausnahmen sind:

  • Microsoft.Extensions-Bibliotheken, die weiterhin auf .NET Standard abzielen, sind als NuGet-Pakete verfügbar (siehe https://github.com/dotnet/extensions).
  • APIs, die vom ASP.NET Core-Team erstellt werden und die nicht Teil Microsoft.AspNetCore.App sind. Die folgenden Komponenten sind beispielsweise als NuGet-Pakete verfügbar:
  • Erweiterungen für MVC zur Unterstützung von Json.NET. Eine API wird als NuGet-Paket bereitgestellt, um die Verwendung von Json.NET und MVC zu unterstützen. Weitere Informationen finden Sie im Migrationsleitfaden zu ASP.NET Core.
  • Der SignalR-.NET-Client unterstützt weiterhin .NET Standard und wird als NuGet-Paket bereitgestellt. Er ist für die Verwendung in vielen .NET-Runtimes vorgesehen, z. B. Xamarin und UWP.

Weitere Informationen finden Sie unter Stop producing packages for shared framework assemblies in 3.0 (Beenden der Erstellung von Paketen für Assemblys in freigegebenen Frameworks in 3.0). Weitere Informationen finden Sie unter dotnet/aspnetcore#3757.

Kategorie

ASP.NET Core

Betroffene APIs

Freigegebenes Framework: Microsoft.AspNetCore.All entfernt

Ab ASP.NET Core 3.0 werden das Metapaket Microsoft.AspNetCore.All und das entsprechende freigegebene Framework Microsoft.AspNetCore.All nicht mehr erstellt. Dieses Paket ist in ASP.NET Core 2.2 verfügbar und wird auch weiterhin mit Wartungsupdates in ASP.NET Core 2.1 versorgt.

Eingeführt in Version

3.0

Altes Verhalten

Apps konnten das Metapaket Microsoft.AspNetCore.All verwenden, um das freigegebene Framework Microsoft.AspNetCore.All als Ziel in .NET Core zu verwenden.

Neues Verhalten

.NET Core 3.0 enthält das freigegebene Framework Microsoft.AspNetCore.All nicht mehr.

Grund für die Änderung

Das Metapaket Microsoft.AspNetCore.All enthielt eine große Anzahl externer Abhängigkeiten.

Stellen Sie Ihr Projekt auf die Verwendung des Frameworks Microsoft.AspNetCore.App um. Komponenten, die zuvor in Microsoft.AspNetCore.All verfügbar waren, sind weiterhin in NuGet verfügbar. Diese Komponenten werden nun mit Ihrer App bereitgestellt, anstatt in das freigegebene Framework eingefügt zu werden.

Kategorie

ASP.NET Core

Betroffene APIs

Keine

SignalR: HandshakeProtocol.SuccessHandshakeData wurde ersetzt

Das Feld HandshakeProtocol.SuccessHandshakeData wurde entfernt und durch eine Hilfsmethode ersetzt, die eine erfolgreiche Handshakeantwort für ein bestimmtes IHubProtocol generiert.

Eingeführt in Version

3.0

Altes Verhalten

HandshakeProtocol.SuccessHandshakeData war ein public static ReadOnlyMemory<byte>-Feld.

Neues Verhalten

HandshakeProtocol.SuccessHandshakeData wurde durch eine static GetSuccessfulHandshake(IHubProtocol protocol)-Methode ersetzt, die basierend auf dem angegebenen Protokoll ein ReadOnlyMemory<byte>-Element zurückgibt.

Grund für die Änderung

Der Handshakeantwort wurden zusätzliche Felder hinzugefügt, die nicht konstant sind und je nach ausgewähltem Protokoll abweichen.

Keine Dieser Typ ist nicht für die Verwendung in Benutzercode vorgesehen. Er ist public, damit er von SignalR-Server und -Client gemeinsam verwendet werden kann. Er kann auch von SignalR-Kundenclients verwendet werden, die in .NET geschrieben wurden. Benutzer von SignalR sollten von dieser Änderung nicht betroffen sein.

Kategorie

ASP.NET Core

Betroffene APIs

HandshakeProtocol.SuccessHandshakeData

SignalR: ResetSendPing- und ResetTimeout-Methoden aus HubConnection entfernt

Die Methoden ResetSendPing und ResetTimeout wurden aus der SignalR-API HubConnection entfernt. Diese Methoden waren ursprünglich nur für die interne Verwendung vorgesehen, wurden aber in ASP.NET Core 2.2 öffentlich („public“) gemacht. Diese Methoden sind ab dem Release ASP.NET Core 3.0 Preview 4 nicht mehr verfügbar. Weitere Informationen finden Sie unter dotnet/aspnetcore#8543.

Eingeführt in Version

3.0

Altes Verhalten

Die APIs waren verfügbar.

Neues Verhalten

Die APIs wurden entfernt.

Grund für die Änderung

Diese Methoden waren ursprünglich nur für die interne Verwendung vorgesehen, wurden aber in ASP.NET Core 2.2 öffentlich („public“) gemacht.

Verwenden Sie diese Methoden nicht mehr.

Kategorie

ASP.NET Core

Betroffene APIs

SignalR: HubConnectionContext-Konstruktoren wurden geändert

Die HubConnectionContext-Konstruktoren von SignalR wurden so geändert, dass sie anstelle von mehreren Parametern einen Optionstyp akzeptieren, damit auch in Zukunft Optionen hinzugefügt werden können. Durch diese Änderung werden zwei Konstruktoren durch einen einzelnen Konstruktor ersetzt, der einen Optionstyp akzeptiert.

Eingeführt in Version

3.0

Altes Verhalten

HubConnectionContext hatte zwei Konstruktoren:

public HubConnectionContext(ConnectionContext connectionContext, TimeSpan keepAliveInterval, ILoggerFactory loggerFactory);
public HubConnectionContext(ConnectionContext connectionContext, TimeSpan keepAliveInterval, ILoggerFactory loggerFactory, TimeSpan clientTimeoutInterval);

Neues Verhalten

Die beiden Konstruktoren wurden entfernt und durch einen Konstruktor ersetzt:

public HubConnectionContext(ConnectionContext connectionContext, HubConnectionContextOptions contextOptions, ILoggerFactory loggerFactory)

Grund für die Änderung

Der neue Konstruktor verwendet ein neues Optionsobjekt. Aus diesem Grund können die Features von HubConnectionContext in Zukunft erweitert werden, ohne dass weitere Konstruktoren erforderlich werden oder Breaking Changes vorgenommen werden müssen.

Verwenden Sie anstelle der folgenden Konstruktoren:

HubConnectionContext connectionContext = new HubConnectionContext(
    connectionContext,
    keepAliveInterval: TimeSpan.FromSeconds(15),
    loggerFactory,
    clientTimeoutInterval: TimeSpan.FromSeconds(15));

den folgenden Konstruktor:

HubConnectionContextOptions contextOptions = new HubConnectionContextOptions()
{
    KeepAliveInterval = TimeSpan.FromSeconds(15),
    ClientTimeoutInterval = TimeSpan.FromSeconds(15)
};
HubConnectionContext connectionContext = new HubConnectionContext(connectionContext, contextOptions, loggerFactory);

Kategorie

ASP.NET Core

Betroffene APIs

SignalR: Name des JavaScript-Clientpakets geändert

In ASP.NET Core 3.0 Preview 7 wurde der Name des SignalR-JavaScript-Clientpakets von @aspnet/signalr in @microsoft/signalr geändert. Die Namensänderung spiegelt die Tatsache wider, dass SignalR dank Azure SignalR Service für mehr als nur ASP.NET Core-Apps nützlich ist.

Um auf diese Änderung zu reagieren, ändern Sie die Verweise in Ihren package.json-Dateien, require-Anweisungen und ECMAScript-import-Anweisungen. Im Rahmen dieser Umbenennung werden keine APIs geändert.

Weitere Informationen finden Sie unter dotnet/aspnetcore#11637.

Eingeführt in Version

3.0

Altes Verhalten

Das Clientpaket hatte den Namen @aspnet/signalr.

Neues Verhalten

Das Clientpaket hat jetzt den Namen @microsoft/signalr.

Grund für die Änderung

Die Namensänderung macht deutlich, dass SignalR dank Azure SignalR Service für mehr als nur ASP.NET Core-Apps nützlich ist.

Stellen Sie auf das neue Paket @microsoft/signalr um.

Kategorie

ASP.NET Core

Betroffene APIs

Keine

SignalR: UseSignalR- und UseConnections-Methoden als veraltet markiert

Die Methoden UseConnections und UseSignalR sowie die Klassen ConnectionsRouteBuilder und HubRouteBuilder wurden in ASP.NET Core 3.0 als veraltet markiert.

Eingeführt in Version

3.0

Altes Verhalten

Das Hubrouting in SignalR wurde mithilfe von UseSignalR oder UseConnections konfiguriert.

Neues Verhalten

Das alte Verfahren zum Konfigurieren des Routings wurde als veraltet markiert und durch das Endpunktrouting ersetzt.

Grund für die Änderung

Die Middleware wurden auf das neue System mit Endpunktrouting umgestellt. Das alte Verfahren zum Hinzufügen von Middleware ist veraltet.

Ersetzen Sie UseSignalR durch UseEndpoints:

Alter Code:

app.UseSignalR(routes =>
{
    routes.MapHub<SomeHub>("/path");
});

Neuer Code:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHub<SomeHub>("/path");
});

Kategorie

ASP.NET Core

Betroffene APIs

SPAs: SpaServices und NodeServices wurden als veraltet markiert

Der Inhalt der folgenden NuGet-Pakete ist seit ASP.NET Core 2.1 nicht mehr erforderlich. Aus diesem Grund werden die folgenden Pakete als veraltet markiert:

Aus demselben Grund werden die folgenden npm-Module als veraltet markiert:

Die obigen Pakete und npm-Module werden später aus .NET 5 entfernt.

Eingeführt in Version

3.0

Altes Verhalten

Die veralteten Pakete und npm-Module waren für die Integration von ASP.NET Core mit verschiedenen SPA-Frameworks (Single-Page-Webanwendung) vorgesehen. Zu diesen Frameworks gehören Angular, React und React mit Redux.

Neues Verhalten

Im NuGet-Paket Microsoft.AspNetCore.SpaServices.Extensions steht ein neuer Integrationsmechanismus zur Verfügung. Das Paket bleibt die Basis der Angular- und React-Projektvorlagen seit ASP.NET Core 2.1.

Grund für die Änderung

ASP.NET Core unterstützt die Integration mit verschiedenen SPA-Frameworks (Single-Page-Webanwendung), einschließlich Angular, React und React mit Redux. Anfänglich wurde die Integration mit diesen Frameworks über ASP.NET Core-spezifische Komponenten erzielt, die Szenarien wie die serverseitige Vorabgenerierung und Integration mit WebPack behandelt haben. Im Laufe der Zeit haben sich die Industriestandards geändert. Alle SPA-Frameworks haben ihre eigenen Standard-Befehlszeilenschnittstellen veröffentlicht. Dazu gehören beispielsweise die Angular CLI und die create-react-app.

Als ASP.NET Core 2.1 im Mai 2018 veröffentlicht wurde, reagierte das Team auf die Änderungen bei den Standards. Es wurde eine neuere und einfachere Möglichkeit zur Integration mit den eigenen Toolketten des SPA-Frameworks bereitgestellt. Der neue Integrationsmechanismus ist im Paket Microsoft.AspNetCore.SpaServices.Extensions enthalten und bleibt die Basis der Angular- und React-Projektvorlagen seit ASP.NET Core 2.1.

Um deutlich zu machen, dass die älteren ASP.NET Core-spezifischen Komponenten irrelevant sind und nicht empfohlen werden, wurde Folgendes umgesetzt:

  • Der Integrationsmechanismus vor Version 2.1 wurde als veraltet markiert.
  • Die unterstützenden npm-Pakete wurden als veraltet markiert.

Wenn Sie diese Pakete verwenden, aktualisieren Sie Ihre Apps, um diese Funktionalität zu nutzen:

  • Im Paket Microsoft.AspNetCore.SpaServices.Extensions.
  • Bereitgestellt von den von Ihnen verwendeten SPA-Frameworks

Informationen zum Aktivieren von Features wie dem serverseitigen Vorabrendering und dem „heißen“ Neuladen von Modulen finden Sie in der Dokumentation zum zugehörigen SPA-Framework. Die Funktionen in Microsoft.AspNetCore.SpaServices.Extensions sind nicht veraltet und werden weiterhin unterstützt.

Kategorie

ASP.NET Core

Betroffene APIs

SPAs: Kein Fallback auf die Konsolenprotokollierung mehr für SpaServices und NodeServices

Microsoft.AspNetCore.SpaServices und Microsoft.AspNetCore.NodeServices zeigen nur dann Konsolenprotokolle an, wenn die Protokollierung konfiguriert wurde.

Eingeführt in Version

3.0

Altes Verhalten

Microsoft.AspNetCore.SpaServices und Microsoft.AspNetCore.NodeServices erstellten automatisch eine Konsolenprotokollierung, wenn die Protokollierung nicht konfiguriert war.

Neues Verhalten

Microsoft.AspNetCore.SpaServices und Microsoft.AspNetCore.NodeServices zeigen nur dann Konsolenprotokolle an, wenn die Protokollierung konfiguriert wurde.

Grund für die Änderung

Mit dieser Änderung soll eine Anpassung an die Implementierung der Protokollierung in anderen ASP.NET Core-Paketen umgesetzt werden.

Wenn das alte Verhalten erforderlich ist, fügen Sie zum Konfigurieren der Konsolenprotokollierung Ihrer Setup.ConfigureServices-Methode services.AddLogging(builder => builder.AddConsole()) hinzu.

Kategorie

ASP.NET Core

Betroffene APIs

Keine

Zielframework: .NET Framework-Unterstützung aufgehoben

Ab ASP.NET Core 3.0 ist .NET Framework kein unterstütztes Zielframework mehr.

Änderungsbeschreibung

.NET Framework 4.8 ist die letzte Hauptversion von .NET Framework. Neue ASP.NET Core-Apps sollten mit .NET Core erstellt werden. Ab dem Release .NET Core 3.0 können Sie sich ASP.NET Core 3.0 als Teil von .NET Core vorstellen.

Kunden, die ASP.NET Core mit .NET Framework verwenden, erhalten mit dem LTS-Release 2.1 weiterhin vollständige Unterstützung. Support und Wartung für 2.1 werden mindestens bis zum 21. August 2021 fortgesetzt. Dieses Datum liegt gemäß der .NET-Supportrichtlinie drei Jahre nach der Bekanntgabe des LTS-Release. Die Unterstützung für ASP.NET Core 2.1-Pakete auf Grundlage von .NET Framework wird unbegrenzt verlängert (ähnlich der Dienstrichtlinie für andere paketbasierte ASP.NET-Frameworks).

Weitere Informationen zum Portieren von .NET Framework zu .NET Core finden Sie unter Portieren zu .NET Core.

Microsoft.Extensions-Pakete (z. B. Protokollierung, Abhängigkeitsinjektion und Konfiguration) und Entity Framework Core sind nicht betroffen. Sie unterstützen .NET Standard auch weiterhin.

Weitere Informationen zu den Gründen für diese Änderung finden Sie im ursprünglichen Blogbeitrag.

Eingeführt in Version

3.0

Altes Verhalten

ASP.NET Core-Apps konnten unter .NET Core oder .NET Framework ausgeführt werden.

Neues Verhalten

ASP.NET Core-Apps können nur unter .NET Core ausgeführt werden.

Führen Sie eine der folgenden Aktionen aus:

  • Verwenden Sie für Ihre App auch weiterhin ASP.NET Core 2.1.
  • Migrieren Sie Ihre App und die Abhängigkeiten zu .NET Core.

Kategorie

ASP.NET Core

Betroffene APIs

Keine

Core .NET-Bibliotheken

APIs, die Versionsinformationen melden, melden nun die Produktversion und nicht die Dateiversion

Viele APIs, die in .NET Core Versionsinformationen zurückgeben, geben nun anstelle der Dateiversion die Produktversion zurück.

Änderungsbeschreibung

In .NET Core 2.2 und früheren Versionen, wird in Methoden wie Environment.Version, RuntimeInformation.FrameworkDescription und im Dialogfeld mit den Dateieigenschaften für .NET Core-Assemblys die Dateiversion angegeben. Ab .NET Core 3.0 wird die Produktversion angegeben.

In der folgenden Abbildung sind die unterschiedlichen Versionsinformationen für die System.Runtime.dll-Assembly für .NET Core 2.2 (links) und .NET Core 3.0 (rechts) zu sehen, die im Dialogfeld mit Dateieigenschaften im Windows-Explorer angezeigt werden.

Unterschiedliche Produktversionsinformationen

Eingeführt in Version

3.0

Keine Durch diese Änderung soll die Version einfacher und intuitiver zu erkennen sein.

Kategorie

Core .NET-Bibliotheken

Betroffene APIs

Benutzerdefinierte EncoderFallbackBuffer-Instanzen können kein rekursives Fallback ausführen

Benutzerdefinierte EncoderFallbackBuffer-Instanzen können kein rekursives Fallback ausführen. Die Implementierung von EncoderFallbackBuffer.GetNextChar() muss zu einer Zeichensequenz führen, die in die Zielcodierung konvertiert werden kann. Andernfalls tritt eine Ausnahme auf.

Änderungsbeschreibung

Bei einem Zeichen-zu-Byte-Transcodierungsvorgang erkennt die Runtime falsch formatierte oder nicht konvertierbare UTF-16-Sequenzen und stellt diese Zeichen für die EncoderFallbackBuffer.Fallback-Methode bereit. Die Fallback-Methode bestimmt, welche Zeichen die ursprünglichen nicht konvertierbaren Daten ersetzen, und diese Zeichen werden durch Aufrufen von EncoderFallbackBuffer.GetNextChar in einer Schleife ausgeglichen.

Die Runtime versucht dann, diese Ersetzungszeichen in die Zielcodierung zu transcodieren. Wenn dieser Vorgang erfolgreich ist, setzt die Runtime die Transcodierung an der Stelle fort, an der sie die ursprüngliche Eingabezeichenfolge verlassen hat.

In früheren Versionen können von benutzerdefinierten Implementierungen von EncoderFallbackBuffer.GetNextChar() Zeichensequenzen zurückgegeben werden, die nicht in die Zielcodierung konvertiert werden können. Wenn die ersetzten Zeichen nicht in die Zielcodierung transcodiert werden können, ruft die Runtime die EncoderFallbackBuffer.Fallback-Methode erneut mit den Ersetzungszeichen auf, wobei erwartet wird, dass die EncoderFallbackBuffer.GetNextChar()-Methode eine neue Ersetzungssequenz zurückgibt. Dieser Vorgang wird fortgesetzt, bis die Laufzeit eine wohlgeformte, konvertierbare Ersetzung erkennt oder eine maximale Anzahl von Rekursionen erreicht wird.

Ab .NET Core 3.0 müssen von benutzerdefinierten Implementierungen von EncoderFallbackBuffer.GetNextChar() Zeichensequenzen zurückgegeben werden, die in die Zielcodierung konvertiert werden können. Wenn die ersetzten Zeichen nicht in die Zielcodierung transcodiert werden können, wird eine ArgumentException ausgelöst. Die Laufzeit führt keine rekursiven Aufrufe der EncoderFallbackBuffer-Instanz mehr durch.

Dieses Verhalten gilt nur, wenn alle drei der folgenden Bedingungen erfüllt sind:

  • Die Runtime erkennt eine falsch formatierte UTF-16-Sequenz oder eine UTF-16-Sequenz, die nicht in die Zielcodierung konvertiert werden kann.
  • Ein benutzerdefinierter EncoderFallback wurde angegeben.
  • Der benutzerdefinierte EncoderFallback versucht, eine neue falsch formatierte oder nicht konvertierbare UTF-16-Sequenz zu ersetzen.

Eingeführt in Version

3.0

Die meisten Entwickler müssen keine Maßnahmen ergreifen.

Wenn eine Anwendung eine benutzerdefinierte EncoderFallback- und EncoderFallbackBuffer-Klasse verwendet, stellen Sie sicher, dass die Implementierung von EncoderFallbackBuffer.Fallback den Fallbackpuffer mit wohlgeformten UTF-16-Daten auffüllt, die direkt in die Zielcodierung konvertiert werden können, wenn die Fallback-Methode zuerst von der Runtime aufgerufen wird.

Kategorie

Core .NET-Bibliotheken

Betroffene APIs

Neues Verhalten bei Formatierung und Analyse von Gleitkommawerten

Das Verhalten bei der Analyse und Formatierung von Gleitkommawerten (durch die Typen Double und Single) ist jetzt IEEE-konform. Dadurch wird sichergestellt, dass das Verhalten von Gleitkommatypen in .NET dem Verhalten von anderen IEEE-konformen Sprachen entspricht. Beispielsweise muss double.Parse("SomeLiteral") immer mit der Ausgabe von C# für double x = SomeLiteral übereinstimmen.

Änderungsbeschreibung

In .NET Core 2.2 und früheren Versionen war die Formatierung mit Double.ToString und Single.ToString und die Analyse mit Double.Parse, Double.TryParse, Single.Parse und Single.TryParse nicht IEEE-konform. Daher kann nicht sichergestellt werden, dass ein Wert mit einer unterstützten Zeichenfolge in einem Standardformat oder in einem benutzerdefinierten Format einen Roundtrip durchführt. Bei einigen Eingaben kann bei der Analyse eines formatierten Werts ein Fehler auftreten. Bei anderen Eingaben kann es vorkommen, dass der analysierte Wert nicht dem ursprünglichen Wert entspricht.

Ab .NET Core 3.0 entsprechen Analyse- und Formatierungsvorgänge für Gleitkommawerte der Norm IEEE 754.

Die folgende Tabelle zeigt zwei Codeausschnitte und die Unterschiede in der Ausgabe zwischen .NET Core 2.2 und .NET Core 3.1.

Codeausschnitt Ausgabe in .NET Core 2.2 Ausgabe in .NET Core 3.1
Console.WriteLine((-0.0).ToString()); 0 -0
var value = -3.123456789123456789;
Console.WriteLine(value == double.Parse(value.ToString()));		 False True

Weitere Informationen finden Sie im Blogbeitrag Verbesserungen bei Analyse und Formatierung von Gleitkommawerten in .NET Core 3.0.

Eingeführt in Version

3.0

Im Abschnitt Potenzielle Auswirkungen auf vorhandenen Code im Blogbeitrag Verbesserungen der Analyse und Formatierung von Gleitkommawerten in .NET Core 3.0 werden einige Änderungen vorgeschlagen, die Sie an Ihrem Code vornehmen können, wenn Sie das vorherige Verhalten beibehalten möchten.

  • Bei einigen Formatierungsunterschieden können Sie ein Verhalten erzielen, das dem vorherigen Verhalten entspricht, indem Sie eine andere Formatzeichenfolge angeben.
  • Für Unterschiede bei der Analyse gibt es keinen Mechanismus zum Wiederherstellen des vorherigen Verhaltens.

Kategorie

Core .NET-Bibliotheken

Betroffene APIs

Gleitkomma-Analysevorgänge lösen keinen Fehler und keine OverflowException mehr aus

Die Gleitkomma-Analysemethoden lösen keine OverflowException mehr aus und geben auch nicht false zurück, wenn sie eine Zeichenfolge analysieren, deren Zahlenwert außerhalb des Bereichs des Gleitkommatyps Single oder Double liegt.

Änderungsbeschreibung

In .NET Core 2.2 und früheren Versionen lösen die Methoden Double.Parse und Single.Parse eine OverflowException für Werte aus, die außerhalb des Bereichs ihres jeweiligen Typs liegen. Die Methoden Double.TryParse und Single.TryParse geben false für die Zeichenfolgendarstellungen von numerischen Werten außerhalb des gültigen Bereichs zurück.

Ab .NET Core 3.0 schlagen die Methoden Double.Parse, Double.TryParse, Single.Parse und Single.TryParse nicht mehr fehl, wenn Sie außerhalb des gültigen Bereichs liegende numerische Zeichenfolgen analysieren. Stattdessen geben die Double-Analysemethoden Double.PositiveInfinity für Werte, die Double.MaxValue überschreiten, und Double.NegativeInfinity für Werte zurück, die kleiner als Double.MinValue sind. Analog dazu geben die Single-Analysemethoden Single.PositiveInfinity für Werte, die Single.MaxValue überschreiten, und Single.NegativeInfinity für Werte zurück, die kleiner als Single.MinValue sind.

Diese Änderung wurde vorgenommen, um die Konformität mit IEEE 754:2008 zu verbessern.

Eingeführt in Version

3.0

Diese Änderung kann sich auf zwei Arten auf den Code auswirken:

  • Der Code hängt vom Handler für die OverflowException ab, der ausgeführt wird, wenn ein Überlauf auftritt. In diesem Fall sollten Sie die catch-Anweisung entfernen und erforderlichen Code in einer If-Anweisung platzieren, die testet, ob Double.IsInfinity oder Single.IsInfinitytrue ist.

  • Ihr Code geht davon aus, dass Gleitkommawerte nicht Infinity sind. In diesem Fall sollten Sie den erforderlichen Code hinzufügen, um auf Gleitkommawerte des Typs PositiveInfinity und NegativeInfinity zu prüfen.

Kategorie

Core .NET-Bibliotheken

Betroffene APIs

InvalidAsynchronousStateException in andere Assembly verschoben

Die InvalidAsynchronousStateException-Klasse wurde verschoben.

Änderungsbeschreibung

In .NET Core 2.2 und früheren Versionen befand sich die InvalidAsynchronousStateException-Klasse in der System.ComponentModel.TypeConverter-Assembly.

Seit .NET Core 3.0 befindet sie sich in der System.ComponentModel.Primitives-Assembly.

Eingeführt in Version

3.0

Diese Änderung betrifft nur Anwendungen, welche die Reflektion zum Laden von InvalidAsynchronousStateException durch Aufrufen einer Methode wie Assembly.GetType oder eine Überladung von Activator.CreateInstance nutzen, bei der vorausgesetzt wird, dass sich der Typ in einer bestimmten Assembly befindet. Ist dies der Fall, aktualisieren Sie die im Methodenaufruf referenzierte Assembly entsprechend dem neuen Assemblyspeicherort des Typs.

Kategorie

Core .NET-Bibliotheken

Betroffene APIs

Keine.

Ersetzen von falsch formatierten UTF-8-Bytesequenzen von Unicode-Vorgaben abhängig

Wenn die Klasse UTF8Encoding während einer Byte-zu-Zeichen-Transcodierung auf eine falsch formatierte UTF-8-Bytesequenz trifft, ersetzt sie diese in der Ausgabezeichenfolge durch ein „�“-Zeichen (U+FFFD, ERSETZUNGSZEICHEN). .NET Core 3.0 unterscheidet sich von früheren Versionen von .NET Core und .NET Framework durch die Einhaltung der bewährten Unicode-Methoden für die Durchführung dieser Ersetzung während des Transcodierungsvorgangs.

Dies ist Teil einer größeren Maßnahme zur Verbesserung der UTF-8-Verarbeitung in .NET, auch bei den neuen Typen System.Text.Unicode.Utf8 und System.Text.Rune. Der Typ UTF8Encoding wurde mit einem verbesserten Verfahren für die Fehlerbehandlung versehen, sodass die Ausgabe konsistent mit den neu eingeführten Typen generiert wird.

Änderungsbeschreibung

Ab .NET Core 3.0 führt die UTF8Encoding-Klasse bei der Transcodierung von Bytes in Zeichen Zeichenersetzung basierend auf bewährten Unicode-Methoden aus. Der verwendete Ersetzungsmechanismus wird durch The Unicode Standard, Version 12.0, Abschnitt 3.9 (PDF) unter der Überschrift U+FFFD Substitution of Maximum Subparts beschrieben.

Dieses Verhalten gilt nur, wenn die Eingabebytesequenz falsch formatierte UTF-8-Daten enthält. Außerdem gilt: Wenn die UTF8Encoding-Instanz mit throwOnInvalidBytes: true erstellt wurde, löst die UTF8Encoding-Instanz bei ungültiger Eingabe weiterhin eine Ausnahme aus, anstatt eine Ersetzung mit U+FFFD auszuführen. Weitere Informationen über den Konstruktor UTF8Encoding finden Sie unter UTF8Encoding(Boolean, Boolean).

In der folgenden Tabelle wird die Auswirkung dieser Änderung mit einer ungültigen 3-Byte-Eingabe veranschaulicht:

Falsch formatierte 3-Byte-Eingabe Ausgabe vor .NET Core 3.0 Ausgabe ab .NET Core 3.0
[ ED A0 90 ] [ FFFD FFFD ] (2-Zeichen-Ausgabe) [ FFFD FFFD FFFD ] (3-Zeichen-Ausgabe)

Die 3-Zeichen-Ausgabe ist die bevorzugte Ausgabe gemäß Tabelle 3–9 der oben genannten PDF-Datei zum Unicode-Standard.

Eingeführt in Version

3.0

Auf der Seite des Entwicklers ist keine Aktion erforderlich.

Kategorie

Core .NET-Bibliotheken

Betroffene APIs

TypeDescriptionProviderAttribute in andere Assembly verschoben

Die TypeDescriptionProviderAttribute-Klasse wurde verschoben.

Änderungsbeschreibung

In .NET Core 2.2 und früheren Versionen befand sich die TypeDescriptionProviderAttribute-Klasse in der System.ComponentModel.TypeConverter-Assembly.

Seit .NET Core 3.0 befindet sie sich in der System.ObjectModel-Assembly.

Eingeführt in Version

3.0

Diese Änderung betrifft nur Anwendungen, welche die Reflektion zum Laden des TypeDescriptionProviderAttribute-Typs durch Aufrufen einer Methode wie Assembly.GetType oder eine Überladung von Activator.CreateInstance nutzen, bei der vorausgesetzt wird, dass sich der Typ in einer bestimmten Assembly befindet. Ist dies der Fall, muss die im Methodenaufruf referenzierte Assembly entsprechend dem neuen Assemblyspeicherort des Typs aktualisiert werden.

Kategorie

Windows Forms

Betroffene APIs

Keine.

ZipArchiveEntry verarbeitet keine Archive mit inkonsistenten Eintragsgrößen mehr

ZIP-Archive listen sowohl die komprimierte als auch die unkomprimierte Größe im zentralen Verzeichnis und im lokalen Header auf. Die Eintragsdaten selbst geben die Größe ebenfalls an. In .NET Core 2.2 und früheren Versionen wurden diese Werte nie auf Konsistenz geprüft. Ab .NET Core 3.0 ist dies jetzt der Fall.

Änderungsbeschreibung

In .NET Core 2.2 und früheren Versionen ist ZipArchiveEntry.Open() selbst dann erfolgreich, wenn der lokale Header nicht mit dem zentralen Header der ZIP-Datei übereinstimmt. Die Daten werden dekomprimiert, bis das Ende des komprimierten Datenstroms erreicht ist, auch wenn seine Länge die im zentralen Verzeichnis/lokalen Header angegebene unkomprimierte Dateigröße überschreitet.

Ab .NET Core 3.0 überprüft die ZipArchiveEntry.Open()-Methode, ob der lokale Header und der zentrale Header hinsichtlich der komprimierten und unkomprimierten Größen eines Eintrags übereinstimmen. Wenn dies nicht der Fall ist, löst die Methode eine InvalidDataException aus, wenn die lokalen Größen der Header- und/oder Datendeskriptorlisten des Archivs nicht mit dem zentralen Verzeichnis der ZIP-Datei übereinstimmen. Beim Lesen eines Eintrags werden dekomprimierte Daten auf die nicht komprimierte Dateigröße abgeschnitten, die im Header aufgeführt ist.

Diese Änderung wurde vorgenommen, um sicherzustellen, dass ein ZipArchiveEntry die Größe seiner Daten richtig darstellt und nur diese Menge an Daten gelesen wird.

Eingeführt in Version

3.0

Packen Sie jedes ZIP-Archiv neu, das diese Probleme aufweist.

Kategorie

Core .NET-Bibliotheken

Betroffene APIs

FieldInfo.SetValue löst eine Ausnahme für statische reine Initialisierungsfelder aus

Ab .NET Core 3.0 wird eine Ausnahme ausgelöst, wenn Sie versuchen, einen Wert in einem statischen InitOnly-Feld durch Aufrufen von System.Reflection.FieldInfo.SetValue festzulegen.

Änderungsbeschreibung

In .NET Framework und Versionen von .NET Core vor 3.0 konnten Sie den Wert eines statischen Felds, das nach der Initialisierung konstant ist (schreibgeschützt in C#), durch Aufrufen von System.Reflection.FieldInfo.SetValue festlegen. Allerdings führte das Festlegen eines solchen Felds auf diese Weise je nach Zielframework und Optimierungseinstellungen zu einem unvorhersehbaren Verhalten.

Ab . NET Core 3.0 wird beim Aufrufen von SetValue für ein statisches InitOnly-Feld eine System.FieldAccessException-Ausnahme ausgelöst.

Tipp

Ein InitOnly-Feld ist ein Feld, das nur zum Zeitpunkt seiner Deklaration oder im Konstruktor für die enthaltende Klasse festgelegt werden kann. Das heißt, dass es nach der Initialisierung konstant ist.

Eingeführt in Version

3.0

Initialisieren Sie statische InitOnly-Felder in einem statischen Konstruktor. Dies gilt sowohl für dynamische als auch für nicht dynamische Typen.

Alternativ können Sie das FieldAttributes.InitOnly-Attribut aus dem Feld entfernen und dann FieldInfo.SetValueaufrufen.

Kategorie

Core .NET-Bibliotheken

Betroffene APIs

Das Übergeben von GroupCollection an Erweiterungsmethoden, die IEnumerable<T> akzeptieren, erfordert Vermeidung von Mehrdeutigkeit

Wenn Sie eine Erweiterungsmethode aufrufen, die IEnumerable<T> für GroupCollection akzeptiert, müssen Sie den Typ mithilfe einer Umwandlung verdeutlichen.

Änderungsbeschreibung

Ab .NET Core 3.0 implementiert System.Text.RegularExpressions.GroupCollection neben anderen Typen wie IEnumerable<Group> auch IEnumerable<KeyValuePair<String,Group>>. Dies resultiert in einer Mehrdeutigkeit, wenn eine Erweiterungsmethode aufgerufen wird, die IEnumerable<T> akzeptiert. Wenn Sie eine solche Erweiterungsmethode für eine GroupCollection-Instanz aufrufen, z. B. Enumerable.Count, wird der folgende Compilerfehler angezeigt:

CS1061: „GroupCollection“ enthält keine Definition für „Count“, und es konnte keine Erweiterungsmethode „Count“ gefunden werden, die ein erstes Argument vom Typ „GroupCollection“ akzeptiert (möglicherweise fehlt eine using-Anweisung oder ein Assemblyverweis).

In vorherigen Versionen von .NET gab es keine Mehrdeutigkeit und keinen Compilerfehler.

Eingeführt in Version

3.0

Grund für die Änderung

Hierbei handelt es sich um einen unbeabsichtigten Breaking Change. Da diese Funktionsweise seit einiger Zeit besteht, ist keine Änderung geplant. Außerdem würde eine solche Änderung selbst zu einem Breaking Change führen.

Heben Sie für GroupCollection-Instanzen die Mehrdeutigkeit von Aufrufen der Erweiterungsmethoden auf, die IEnumerable<T> mit einer Umwandlung akzeptieren.

// Without a cast - causes CS1061.
match.Groups.Count(_ => true)

// With a disambiguating cast.
((IEnumerable<Group>)m.Groups).Count(_ => true);

Kategorie

Core .NET-Bibliotheken

Betroffene APIs

Dies betrifft alle Erweiterungsmethoden, die IEnumerable<T> akzeptieren. Beispiel:

Kryptografie

„BEGIN TRUSTED CERTIFICATE“-Syntax wird nicht mehr für Stammzertifikate unter Linux unterstützt

Stammzertifikate können unter Linux und anderen UNIX-ähnlichen Betriebssystemen (jedoch nicht macOS) in zwei Formen dargestellt werden: als Standard-PEM-Header BEGIN CERTIFICATE oder als OpenSSL-spezifischen PEM-Header BEGIN TRUSTED CERTIFICATE. Die letztere Syntax ermöglicht eine zusätzliche Konfiguration, die Kompatibilitätsprobleme mit der System.Security.Cryptography.X509Certificates.X509Chain-Klasse von .NET Core verursacht hat. BEGIN TRUSTED CERTIFICATE-Stammzertifikatinhalte werden ab .NET Core 3.0 nicht mehr von der Ketten-Engine geladen.

Änderungsbeschreibung

Zuvor wurden sowohl die BEGIN CERTIFICATE- als auch die BEGIN TRUSTED CERTIFICATE-Syntax verwendet, um die Vertrauensliste des Stammzertifikats auszufüllen. Wenn die BEGIN TRUSTED CERTIFICATE-Syntax verwendet wurde und zusätzliche Optionen in der Datei angegeben wurden, hat X509Chain möglicherweise gemeldet, dass die Vertrauenskette explizit nicht zulässig war (X509ChainStatusFlags.ExplicitDistrust). Wenn das Zertifikat jedoch auch mit der BEGIN CERTIFICATE-Syntax in einer zuvor geladenen Datei angegeben wurde, war die Vertrauenskette zulässig.

Ab .NET Core 3.0 werden BEGIN TRUSTED CERTIFICATE-Inhalte nicht mehr gelesen. Wenn das Zertifikat nicht auch über eine Standardsyntax BEGIN CERTIFICATE angegeben wird, meldet X509Chain, dass der Stamm nicht vertrauenswürdig ist (X509ChainStatusFlags.UntrustedRoot).

Eingeführt in Version

3.0

Die meisten Anwendungen sind von dieser Änderung nicht betroffen. Bei Anwendungen, denen aufgrund von Berechtigungsproblemen nicht beide Quellen des Stammzertifikats angezeigt werden, treten nach dem Upgrade möglicherweise unerwartete UntrustedRoot-Fehler auf.

Viele Linux-Distributionen schreiben Stammzertifikate in zwei Speicherorte: in ein Verzeichnis mit einem einzigen Zertifikat pro Datei und in eine Verkettung mit einer Datei. Bei manchen Distributionen verwendet das Verzeichnis mit einem einzigen Zertifikat pro Datei die BEGIN TRUSTED CERTIFICATE-Syntax, während die Dateiverkettung die Standardsyntax BEGIN CERTIFICATE verwendet. Stellen Sie sicher, dass alle benutzerdefinierten Stammzertifikate an mindestens einem dieser Speicherorte als BEGIN CERTIFICATE hinzugefügt werden und dass beide Speicherorte von Ihrer Anwendung gelesen werden können.

Das übliche Verzeichnis ist /etc/ssl/certs/ , und die übliche verkettete Datei ist /etc/ssl/cert.pem. Verwenden Sie den Befehl openssl version -d, um den plattformspezifischen Stamm zu ermitteln, der sich von /etc/ssl/ unterscheiden kann. Unter Ubuntu 18.04 ist das Verzeichnis beispielsweise /usr/lib/ssl/certs/ und die Datei /usr/lib/ssl/cert.pem. /usr/lib/ssl/certs/ ist jedoch eine symbolische Verknüpfung mit /etc/ssl/certs/ , und /usr/lib/ssl/cert.pem ist nicht vorhanden.

$ openssl version -d
OPENSSLDIR: "/usr/lib/ssl"
$ ls -al /usr/lib/ssl
total 12
drwxr-xr-x  3 root root 4096 Dec 12 17:10 .
drwxr-xr-x 73 root root 4096 Feb 20 15:18 ..
lrwxrwxrwx  1 root root   14 Mar 27  2018 certs -> /etc/ssl/certs
drwxr-xr-x  2 root root 4096 Dec 12 17:10 misc
lrwxrwxrwx  1 root root   20 Nov 12 16:58 openssl.cnf -> /etc/ssl/openssl.cnf
lrwxrwxrwx  1 root root   16 Mar 27  2018 private -> /etc/ssl/private

Kategorie

Kryptografie

Betroffene APIs

EnvelopedCms verwendet standardmäßig AES-256-Verschlüsselung

Der von EnvelopedCms verwendete symmetrische Standardverschlüsselungsalgorithmus hat sich von TripleDES in AES-256 geändert.

Änderungsbeschreibung

Wenn in früheren Versionen EnvelopedCms zum Verschlüsseln von Daten verwendet wird, ohne einen symmetrischen Verschlüsselungsalgorithmus über eine Konstruktorüberladung anzugeben, werden die Daten mit dem TripleDES/3DES/3DES/3DEA/DES3-EDE-Algorithmus verschlüsselt.

Ab .NET Core 3.0 (über Version 4.6.0 des NuGet-Pakets System.Security.Cryptography.Pkcs) wurde der Standardalgorithmus in AES-256 geändert, um die Algorithmen zu modernisieren und die Sicherheit von Standardoptionen zu verbessern. Wenn ein Nachrichtenempfängerzertifikat über einen öffentlichen Diffie-Hellman-Schlüssel (Nicht-EC) verfügt, kann die Verschlüsselung mit einer CryptographicException aufgrund von Einschränkungen der zugrunde liegenden Plattform fehlschlagen.

Im folgenden Beispielcode werden die Daten mit TripleDES verschlüsselt, wenn die Ausführung unter .NET Core 2.2 oder früher erfolgt. Wenn die Ausführung unter .NET Core 3.0 oder höher erfolgt, wird für die Verschlüsselung AES-256 verwendet.

EnvelopedCms cms = new EnvelopedCms(content);
cms.Encrypt(recipient);
return cms.Encode();

Eingeführt in Version

3.0

Wenn Sie von der Änderung negativ betroffen sind, können Sie die TripleDES-Verschlüsselung wiederherstellen, indem Sie den Bezeichner des Verschlüsselungsalgorithmus in einem EnvelopedCms-Konstruktor explizit angeben, der einen Parameter vom Typ AlgorithmIdentifier enthält, beispielsweise:

Oid tripleDesOid = new Oid("1.2.840.113549.3.7", null);
AlgorithmIdentifier tripleDesIdentifier = new AlgorithmIdentifier(tripleDesOid);
EnvelopedCms cms = new EnvelopedCms(content, tripleDesIdentifier);

cms.Encrypt(recipient);
return cms.Encode();

Kategorie

Kryptografie

Betroffene APIs

Die Mindestgröße für die Generierung von RSAOpenSsl-Schlüsseln wurde heraufgesetzt

Die Mindestgröße für das Erstellen neuer RSA-Schlüssel unter Linux wurde von 384 Bit auf 512 Bit heraufgesetzt.

Änderungsbeschreibung

Mit .NET Core 3.0 wurde die mindestens erforderliche Schlüsselgröße, die von der LegalKeySizes-Eigenschaft auf RSA-Instanzen von RSA.Create, RSAOpenSsl und RSACryptoServiceProvider unter Linux gemeldet wird, von 384 auf 512 erhöht.

Infolgedessen ist in . NET Core 2.2 und früheren Versionen ein Methodenaufruf wie RSA.Create(384) erfolgreich. In .NET Core 3.0 und höheren Versionen löst der Methodenaufruf RSA.Create(384) eine Ausnahme aus, die anzeigt, dass die Größe zu klein ist.

Diese Änderung wurde vorgenommen, weil für OpenSSL (Software zum Durchführen der kryptografischen Vorgänge unter Linux) der Mindestwert von Version 1.0.2 zu Version 1.1.0 erhöht wurde. .NET Core 3.0 zieht OpenSSL 1.1.x 1.0.x vor, und die mindestens gemeldete Version wurde erhöht, um dieser neuen höheren Abhängigkeitseinschränkung Rechnung zu tragen.

Eingeführt in Version

3.0

Wenn Sie eine der betroffenen APIs aufzurufen, stellen Sie sicher, dass die Größe der generierten Schlüssel nicht kleiner ist als der Anbietermindestwert.

Hinweis

384-Bit-RSA wird bereits als unsicher angesehen (ebenso wie 512-Bit-RSA). Moderne Empfehlungen (z.B. NIST Special Publication 800-57 Part 1 Revision 4) schlagen 2048-Bit als Mindestgröße für neu generierte Schlüssel vor.

Kategorie

Kryptografie

Betroffene APIs

.NET Core 3.0 zieht OpenSSL 1.1.x OpenSSL 1.0.x vor

.NET Core für Linux, das über mehrere Linux-Distributionen hinweg funktioniert, kann sowohl OpenSSL 1.0.x als auch OpenSSL 1.1.x unterstützen. .NET Core 2.1 und .NET Core 2.2 suchen zuerst nach 1.0.x und dann nach 1.1.x. .NET Core 3.0 sucht zuerst nach 1.1.x. Diese Änderung wurde vorgenommen, um Unterstützung für neue Kryptografiestandards hinzuzufügen.

Diese Änderung kann sich auf Bibliotheken oder Anwendungen auswirken, die plattformübergreifendes Interop mit den OpenSSL-spezifischen Interoptypen in .NET Core durchführen.

Änderungsbeschreibung

In .NET Core 2.2 und früheren Versionen zieht die Runtime das Laden von OpenSSL 1.0.x dem Laden von 1.1.x vor. Dies bedeutet, dass der IntPtr- und SafeHandle-Typ für Interop mit OpenSSL mit libcrypto.so.1.0.0/libcrypto.so.1.0/libcrypto.so.10 bevorzugt verwendet werden.

Ab .NET Core 3.0 bevorzugt die Runtime das Laden von OpenSSL 1.1.x gegenüber OpenSSL 1.0.x, sodass die Typen IntPtr und SafeHandle für Interop mit OpenSSL mit libcrypto.so.1.1/libcrypto.so.11/libcrypto.so.1.1.0/libcrypto.so.1.1.1 verwendet werden. Infolgedessen können Bibliotheken und Anwendungen, die direkt mit OpenSSL interagieren, beim Upgrade von .NET Core 2.1 oder .NET Core 2.2 inkompatible Zeiger mit den von .NET Core bereitgestellten Werten aufweisen.

Eingeführt in Version

3.0

Bibliotheken und Anwendungen, die direkte Vorgänge mit OpenSSL ausführen, müssen darauf achten, dass sichergestellt wird, dass sie die gleiche OpenSSL-Version wie die .NET Core-Runtime verwenden.

Alle Bibliotheken oder Anwendungen, die IntPtr- oder SafeHandle-Werte aus den kryptographischen .NET Core-Typen direkt mit OpenSSL verwenden, sollten die Version der von ihnen verwendeten Bibliothek mit der neuen SafeEvpPKeyHandle.OpenSslVersion-Eigenschaft vergleichen, um sicherzustellen, dass die Zeiger kompatibel sind.

Kategorie

Kryptografie

Betroffene APIs

CryptoStream.Dispose transformiert den abschließenden Block nur beim Schreiben

Die Methode CryptoStream.Dispose, die verwendet wird, um CryptoStream-Vorgänge abzuschließen, versucht nicht mehr, den abschließenden Block beim Lesen zu transformieren.

Änderungsbeschreibung

In früheren Versionen von .NET konnte die Methode Dispose eine Ausnahme auslösen, wenn ein Benutzer bei der Verwendung von CryptoStream im Read-Modus einen unvollständigen Lesevorgang durchführte (z. B. bei Verwendung von AES mit Auffüllung). Die Ausnahme wurde ausgelöst, da versucht wurde, den abschließenden Block zu transformieren, die Daten aber unvollständig waren.

Ab .NET Core 3.0 versucht Dispose nicht mehr, den abschließenden Block beim Lesen zu transformieren, was unvollständige Lesevorgänge ermöglicht.

Grund für die Änderung

Diese Änderung ermöglicht unvollständige Lesevorgänge aus CryptoStream, wenn ein Netzwerkvorgang abgebrochen wird, ohne dass eine Ausnahme abgefangen werden muss.

Eingeführt in Version

3.0

Die meisten Apps sollten von dieser Änderung nicht betroffen sein.

Wenn Ihre Anwendung bisher bei unvollständigen Lesevorgängen eine Ausnahme abgefangen hat, können Sie diesen catch-Block löschen. Wenn Ihre App das Transformieren des abschließenden Blocks in Hashingszenarios verwendet hat, müssen Sie möglicherweise sicherstellen, dass der gesamte Datenstrom gelesen wird, bevor er verworfen wird.

Kategorie

Kryptografie

Betroffene APIs

Entity Framework Core

Breaking Changes für Entity Framework Core

Globalisierung

Gebietsschema „C“ wird dem invarianten Gebietsschema zugeordnet

.NET Core 2.2 und frühere Versionen hängen von dem ICU-Standardverhalten ab, das das Gebietsschema „C“ zum Gebietsschema „en_US_POSIX“ zuordnet. Das Gebietsschema „en_US_POSIX“ weist ein unerwünschtes Sortierverhalten auf, da es keine Zeichenfolgenvergleiche ohne Berücksichtigung der Groß-/Kleinschreibung unterstützt. Da einige Linux-Verteilungen das Gebietsschema „C“ als Standardgebietsschema festlegen, kam es bei einigen Benutzern zu unerwartetem Verhalten.

Beschreibung der Änderung

Die Zuordnung des Gebietsschemas „C“ wurde ab .NET Core 3.0 geändert, sodass das invariante Gebietsschema anstelle von „en_US_POSIX“ verwendet wird. Die Zuordnung des Gebietsschemas „C“ zum invarianten Gebietsschema wird zur Gewährleistung der Konsistenz auch auf Windows angewendet.

Die Zuordnung von „C“ zu „en_US_POSIX“ sorgte bei Kunden für Verwirrung, da „en_US_POSIX“ keine Sortier- und Suchvorgänge für Zeichenfolgen ohne Beachtung der Groß-/Kleinschreibung unterstützt. Da das Gebietsschema „C“ in einigen Linux-Verteilungen als Standardgebietsschema verwendet wird, trat dieses unerwünschte Verhalten bei Kunden mit diesen Betriebssystemen auf.

Eingeführt in Version

3.0

Es ist keine spezifische Maßnahme erforderlich. Sie sollten lediglich über die Änderung informiert sein. Diese Änderung wirkt sich nur auf Anwendungen aus, die die Zuordnung des Gebietsschemas „C“ verwenden.

Kategorie

Globalisierung

Betroffene APIs

Diese Änderung wirkt sich auf alle Sortierungs- und Kultur-APIs aus.

MSBuild

Änderung des Manifestdateinamens der Ressource

Ab .NET Core 3.0 generiert MSBuild im Standardfall einen anderen Manifestdateinamen für Ressourcendateien.

Eingeführt in Version

3.0

Änderungsbeschreibung

Vor .NET Core 3.0 hat MSBuild im Muster <RootNamespace>.<ResourceFilePathFromProjectRoot>.resources einen Manifestdateinamen generiert, wenn für ein EmbeddedResource-Element in der Projektdatei nicht LogicalName-, ManifestResourceName- oder DependentUpon-Metadaten angegeben wurden. Wenn RootNamespace nicht in der Projektdatei definiert ist, wird standardmäßig der Projektname verwendet. Beispielsweise lautete der Name des generierten Manifests für eine Ressourcendatei mit dem Namen Form1.resx im Stammverzeichnis des Projekts MyProject.Form1.resources.

Ab .NET Core 3.0 verwendet MSBuild Typinformationen aus der Quelldatei, wenn eine Ressourcendatei mit einer Quelldatei desselben Namens (z. B. Form1.resx und Form1.cs) angeordnet wird, um den Manifestdateinamen im Muster <Namespace>.<ClassName>.resources zu generieren. Der Namespace- und Klassenname werden aus dem ersten Typ in der angeordneten Quelldatei extrahiert. Beispielsweise lautet der generierte Manifestname für eine Ressourcendatei mit dem Namen Form1.resx, die mit einer Quelldatei mit dem Namen Form1.cs angeordnet wird, MyNamespace.Form1.resources. Wichtig ist zu beachten, dass der erste Teil des Dateinamens sich von früheren Versionen von .NET Core unterscheidet (MyNamespace anstelle von MyProject).

Hinweis

Wenn LogicalName-, ManifestResourceName- oder DependentUpon-Metadaten für ein EmbeddedResource-Element in der Projektdatei angegeben sind, wirkt sich diese Änderung nicht auf diese Ressourcendatei aus.

Dieser Breaking Change wurde mit dem Hinzufügen der EmbeddedResourceUseDependentUponConvention-Eigenschaft zu .NET Core-Projekten eingeführt. Standardmäßig werden Ressourcendateien nicht explizit in einer .NET Core-Projektdatei aufgelistet, sodass Ihnen keine DependentUpon-Metadaten zur Verfügung stehen, um anzugeben, wie die generierte RESOURCES-Datei benannt werden soll. Wenn EmbeddedResourceUseDependentUponConvention dem Standard entsprechend auf true festgelegt ist, sucht MSBuild nach einer angeordneten Quelldatei und extrahiert einen Namespace- und Klassennamen aus dieser Datei. Wenn Sie EmbeddedResourceUseDependentUponConvention auf false festlegen, generiert MSBuild den Namen des Manifests gemäß dem vorherigen Verhalten, wobei RootNamespace und der relative Dateipfad kombiniert werden.

In den meisten Fällen ist keine Aktion seitens des Entwicklers erforderlich, und Ihre App sollte weiterhin funktionieren. Wenn diese Änderung jedoch Ihre App beeinträchtigt, haben Sie folgende Möglichkeiten:

  • Ändern Sie den Code so, dass er den neuen Manifestnamen erwartet.

  • Um die neue Namenskonvention zu umgehen, legen Sie in Ihrer Projektdatei EmbeddedResourceUseDependentUponConvention auf false fest.

    <PropertyGroup>
  <EmbeddedResourceUseDependentUponConvention>false</EmbeddedResourceUseDependentUponConvention>
</PropertyGroup>

Kategorie

MSBuild

Betroffene APIs

–

Netzwerk

Standardwert von HttpRequestMessage.Version wurde in 1.1 geändert

Der Standardwert der Eigenschaft System.Net.Http.HttpRequestMessage.Version wurde aus 2.0 in 1.1 geändert.

Eingeführt in Version

3.0

Änderungsbeschreibung

In .NET Core 1.0 bis 2.0 ist der Standardwert der Eigenschaft System.Net.Http.HttpRequestMessage.Version 1.1. Ab .NET Core 2.1 wurde er in 2.1 geändert.

Ab .NET Core 3.0 ist die Standardversionsnummer, die von der System.Net.Http.HttpRequestMessage.Version-Eigenschaft zurückgegeben wird, erneut 1.1.

Aktualisieren Sie Ihren Code, wenn die System.Net.Http.HttpRequestMessage.Version-Eigenschaft einen Standardwert von 2.0 zurückgeben muss.

Kategorie

Netzwerk

Betroffene APIs

WPF

Geändertes Drag-and-Drop-Verhalten in Texteditoren

.NET Core 3.0 hat eine Änderung der Erstellung von System.Windows.DataObject Text-Editor-Steuerelementen eingeführt, wenn Text auf ein anderes Steuerelement gezogen wird. Die Änderung deaktivierte autoconversion, wodurch der Vorgang die Daten beibehalten, anstatt DataFormats.Text DataFormats.UnicodeText sie in DataFormats.StringFormat.

Eingeführt in Version

.NET Core 3.0

Kategorie

Windows Presentation Foundation

Vorheriges Verhalten

Der Datentyp System.Windows.DataObject beim Ziehen von Text aus einem Text-Editor-Steuerelement war DataFormats.StringFormat.

Neues Verhalten

Der Datentyp beim System.Windows.DataObject Ziehen von Text aus einem Text-Editor-Steuerelement lautet DataFormats.Text oder DataFormats.UnicodeText.

Typ des Breaking Changes

Diese Änderung ist eine Verhaltensänderung.

Grund für die Änderung

Die Änderung war unbeabsichtigt.

Diese Änderung wurde in .NET 7 wiederhergestellt. Führen Sie ein Upgrade auf .NET 7 oder höher durch.

Betroffene APIs

Siehe auch