共用方式為

.NET Core 3.0 的中斷性變更

  • 發行項

如果您即將移轉至 .NET Core、ASP.NET Core 或 EF Core 3.0 版，本文列出的中斷性變更可能影響您的應用程式。

ASP.NET Core

已移除淘汰的 Antiforgery、CORS、診斷、MVC 和路由 API

已移除 ASP.NET Core 2.2 中淘汰的成員和相容性參數。

導入的版本

3.0

變更原因

隨著時間改善 API 介面。

以 .NET Core 2.2 為目標時，請遵循淘汰組建訊息中的指引，改為採用新的 API。

類別

ASP.NET Core

受影響的 API

下列類型和成員在 ASP.NET Core 2.1 和 2.2 中標示為已淘汰：

類型

  • 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

建構函式

  • 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)

屬性

  • 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

方法

已移除「Pubternal」API

為了更妥善維護 ASP.NET Core 的公用 API 介面，*.Internal 命名空間 (稱為 "pubternal" API) 中大部分的類型已成為真正的內部類型。 系統絕不會支援這些命名空間中的成員成為對外公開的 API。 API 可能會在次要版本中斷，而且此情況會經常發生。 相依於這些 API 的程式碼會在更新至 ASP.NET Core 3.0 時中斷。

如需詳細資訊，請參閱 dotnet/aspnetcore#4932 和 dotnet/aspnetcore#11312。

導入的版本

3.0

舊的行為

受影響的 API 會以 public 存取修飾詞標示，並存在於 *.Internal 命名空間中。

新的行為

受影響的 API 會以 internal 存取修飾詞標示，而且無法再由該元件外部的程式碼使用。

變更原因

這些 "pubternal" API 的指導方針是：

  • 可能會變更而不另行通知。
  • 不受 .NET 原則限制，避免中斷性變更。

讓 API 維持 public (即使是在 *.Internal 命名空間) 會讓客戶感到混亂。

停止使用這些 "pubternal" API。 如果您對於替代 API 有任何問題，請在 dotnet/aspnetcore 存放庫中提出問題。

例如，請考量 ASP.NET Core 2.2 專案中的下列 HTTP 要求緩衝程式碼。 EnableRewind 擴充方法存在於 Microsoft.AspNetCore.Http.Internal 命名空間中。

HttpContext.Request.EnableRewind();

在 ASP.NET Core 3.0 專案中，將 EnableRewind 呼叫取代為 EnableBuffering 擴充方法的呼叫。 要求緩衝功能的運作方式與過去一樣。 EnableBuffering 會呼叫現在的 internal API。

HttpContext.Request.EnableBuffering();

類別

ASP.NET Core

受影響的 API

位於 Microsoft.AspNetCore.* 和 Microsoft.Extensions.* 命名空間且名稱空間名稱中有 Internal 區段的所有 API。 例如：

  • 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

驗證：Google+ 淘汰和取代

Google 從 2019 年 1 月 28 日開始，關閉應用程式的 Google+ 登入。

變更描述

ASP.NET 4.x 和 ASP.NET Core 已使用 Google+ 登入 API 在 Web 應用程式中驗證 Google 帳戶使用者。 受影響的 NuGet 套件為適用於 ASP.NET Core 的 Microsoft.AspNetCore.Authentication.Google，以及具有 ASP.NET Web Forms 和 MVC 的 Microsoft.Owin 所適用的 Microsoft.Owin.Security.Google。

Google 的替代 API 使用不同的資料來源和格式。 以下提供已納入結構變更考量的風險降低和解決方案。 應用程式應確認資料本身是否仍符合其需求。 例如，名稱、電子郵件地址、設定檔連結和設定檔相片所提供的值可能會和之前略為不同。

導入的版本

所有版本。 這是 ASP.NET Core 外部的變更。

具有 ASP.NET Web Form 和 MVC 的 Owin

針對 Microsoft.Owin 3.1.0 和更新版本，此處概述暫時性風險降低功能。 應用程式應該使用風險降低來完成測試，以確認資料格式是否發生變更。 有計劃配合修正發行 Microsoft.Owin 4.0.1。 使用任何舊版的應用程式應更新為 4.0.1 版。

ASP.NET Core 1.x

具有 ASP.NET Web Form 和 MVC 的 Owin 風險降低，可以調整為 ASP.NET Core 1.x。 未規劃 NuGet 套件修補程式，因為 1.x 已達到生命週期結束狀態。

ASP.NET Core 2.x

若為 Microsoft.AspNetCore.Authentication.Google 2.x 版，請使用下列程式碼取代 Startup.ConfigureServices 中 AddGoogle 的現有呼叫：

.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");
});

2 月 2.1 和 2.2 修補程式已納入上述重新設定作為新的預設值。 ASP.NET Core 2.0 未規劃修補檔，因為已經達到生命週期結束階段。

ASP.NET Core 3.0

針對 ASP.NET Core 2.x 提供的風險降低功能也可用於 ASP.NET Core 3.0。 在未來的 3.0 預覽版中，可能會移除 Microsoft.AspNetCore.Authentication.Google 套件。 系統會改為將使用者導向至 Microsoft.AspNetCore.Authentication.OpenIdConnect。 下列程式碼示範如何在 Startup.ConfigureServices 中將 AddGoogle 取代為 AddOpenIdConnect。 此取代可以搭配 ASP.NET Core 2.0 和更新版本使用，並可視需要針對 ASP.NET Core 1.x 進行調整。

.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();

類別

ASP.NET Core

受影響的 API

Microsoft.AspNetCore.Authentication.Google

驗證：已移除 HttpContext.Authentication 屬性

已移除 HttpContext 被取代的 Authentication 屬性。

變更描述

在 dotnet/aspnetcore#6504 中，已移除 HttpContext 中被取代的 Authentication 屬性。 自 2.0 後，Authentication 屬性已被取代。 已發行移轉指南，將使用這個已被取代屬性的程式碼移轉至新的取代 API。 其餘與舊版 ASP.NET Core 1.x 驗證堆疊相關的未使用類別/API 均已移除，確認符合 dotnet/aspnetcore@d7a7c65 的內容。

若要了解相關討論，請參閱 dotnet/aspnetcore#6533。

導入的版本

3.0

變更原因

ASP.NET Core 1.0 API 已由 Microsoft.AspNetCore.Authentication.AuthenticationHttpContextExtensions 中的擴充方法取代。

請參閱移轉指南。

類別

ASP.NET Core

受影響的 API

驗證：已取代 Newtonsoft.Json 型別

在 ASP.NET Core 3.0 中，驗證 API 中使用的 Newtonsoft.Json 類型已取代為 System.Text.Json 類型。 除了下列情況外，驗證套件的基本用法依然不受影響：

  • 衍生自 OAuth 提供者的類別，例如來自 aspnet-contrib 的類別。
  • 進階宣告操作實作。

如需詳細資訊，請參閱 dotnet/aspnetcore#7105。 若要了解相關討論，請參閱 dotnet/aspnetcore#7289。

導入的版本

3.0

對於衍生的 OAuth 實作，最常見的變更是在 CreateTicketAsync 覆寫中將 JObject.Parse 取代為 JsonDocument.Parse，如此處所示。 JsonDocument 會實作 IDisposable。

下列清單列出已知變更項目：

類別

ASP.NET Core

受影響的 API

驗證：OAuthHandler ExchangeCodeAsync 簽章已變更

在 ASP.NET Core 3.0 中，OAuthHandler.ExchangeCodeAsync 的簽章變更自：

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

變更為：

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

導入的版本

3.0

舊的行為

code 和 redirectUri 字串是以個別引數的形式傳遞。

新的行為

Code 和 RedirectUri 是 OAuthCodeExchangeContext 上的屬性，可透過 OAuthCodeExchangeContext 建構函式設定。 新的 OAuthCodeExchangeContext 型別是唯一傳遞至 OAuthHandler.ExchangeCodeAsync 的引數。

變更原因

這項變更允許以非中斷方式提供其他參數。 不需要建立新的 ExchangeCodeAsync 多載。

使用適當的 code 和 redirectUri 值建構 OAuthCodeExchangeContext。 必須提供 AuthenticationProperties 執行個體。 這個單一的 OAuthCodeExchangeContext 執行個體可以傳遞至 OAuthHandler.ExchangeCodeAsync，而不是多個引數。

類別

ASP.NET Core

受影響的 API

OAuthHandler<TOptions>.ExchangeCodeAsync(String, String)

授權：AddAuthorization 多載已移至不同的組件

用來放置在 Microsoft.AspNetCore.Authorization 的核心 AddAuthorization 方法已重新命名為 AddAuthorizationCore。 舊的 AddAuthorization 方法仍然存在，但會改為位於 Microsoft.AspNetCore.Authorization.Policy 組件中。 使用這兩種方法的應用程式應該不會有任何影響。 請注意，Microsoft.AspNetCore.Authorization.Policy 現在隨附於共用架構中，而不是獨立套件，如共用架構：從 Microsoft.AspNetCore.App 移除的組件中所述。

導入的版本

3.0

舊的行為

AddAuthorization 方法已存在於 Microsoft.AspNetCore.Authorization 中。

新的行為

AddAuthorization 方法存在於 Microsoft.AspNetCore.Authorization.Policy 中。 AddAuthorizationCore 是舊方法的新名稱。

變更原因

AddAuthorization 是較佳的方法名稱，可用於新增授權所需的所有通用服務。

請新增參考至 Microsoft.AspNetCore.Authorization.Policy 或改用 AddAuthorizationCore。

類別

ASP.NET Core

受影響的 API

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

授權：已從 AuthorizationFilterContext.Filters 移除 IAllowAnonymous

自 ASP.NET Core 3.0 起，MVC 不會針對控制器和動作方法上探索到的 [AllowAnonymous] 屬性新增 AllowAnonymousFilters。 這項變更是為了處理本機環境中 AuthorizeAttribute 的衍生項目，但屬於 IAsyncAuthorizationFilter 和 IAuthorizationFilter 實作的中斷性變更。 這類實作包裝在 [TypeFilter] 屬性中，是一種熱門且受支援的方式，可以在需要設定和相依性插入時實行強型別的屬性型授權。

導入的版本

3.0

舊的行為

IAllowAnonymous 出現在 AuthorizationFilterContext.Filters 集合中。 測試介面是否存在，是在個別控制器方法中覆寫或停用篩選的有效方法。

新的行為

IAllowAnonymous 不再出現在 AuthorizationFilterContext.Filters 集合中。 IAsyncAuthorizationFilter 相依於舊行為的實作通常會產生「HTTP 401 未授權」或「HTTP 403 禁止回應」間歇性錯誤。

變更原因

ASP.NET Core 3.0 中導入了新的端點路由策略。

在端點中繼資料中搜尋 IAllowAnonymous。 例如：

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

在本 HasAllowAnonymous 方法檢視這項技術的範例。

類別

ASP.NET Core

受影響的 API

無

授權：IAuthorizationPolicyProvider 實作需要新的方法

在 ASP.NET Core 3.0 中，已將新的 GetFallbackPolicyAsync 方法新增至 IAuthorizationPolicyProvider。 未指定任何原則時，授權中介軟體會使用此後援原則。

如需詳細資訊，請參閱 dotnet/aspnetcore#9759。

導入的版本

3.0

舊的行為

IAuthorizationPolicyProvider 的實作不需要 GetFallbackPolicyAsync 方法。

新的行為

IAuthorizationPolicyProvider 的實作需要 GetFallbackPolicyAsync 方法。

變更原因

未指定任何原則時，需要新的方法才能使用新的 AuthorizationMiddleware。

將 GetFallbackPolicyAsync 方法新增至 IAuthorizationPolicyProvider 的實作。

類別

ASP.NET Core

受影響的 API

Microsoft.AspNetCore.Authorization.IAuthorizationPolicyProvider

快取：已移除 CompactOnMemoryPressure 屬性

ASP.NET Core 3.0 版本已移除淘汰的 MemoryCacheOptions API。

變更描述

這項變更是 aspnet/Caching#221 的後續動作。 如需了解相關討論，請參閱 dotnet/extensions#1062。

導入的版本

3.0

舊的行為

MemoryCacheOptions.CompactOnMemoryPressure 屬性可供使用。

新的行為

已移除 MemoryCacheOptions.CompactOnMemoryPressure 屬性。

變更原因

自動壓縮快取會導致問題。 若要避免非預期的行為，只在必要時才壓縮快取。

若要壓縮快取，請視需要向下轉型至 MemoryCache 並呼叫 Compact。

類別

ASP.NET Core

受影響的 API

MemoryCacheOptions.CompactOnMemoryPressure

快取：Microsoft.Extensions.Caching.SqlServer 使用新的 SqlClient 套件

Microsoft.Extensions.Caching.SqlServer 套件會使用新的 Microsoft.Data.SqlClient 套件，而不是 System.Data.SqlClient 套件。 這項變更可能會導致少數行為性中斷性變更。 如需詳細資訊，請參閱新的 Microsoft.Data.SqlClient 簡介。

導入的版本

3.0

舊的行為

Microsoft.Extensions.Caching.SqlServer 套件使用 System.Data.SqlClient 套件。

新的行為

Microsoft.Extensions.Caching.SqlServer 現在是使用 Microsoft.Data.SqlClient 套件。

變更原因

Microsoft.Data.SqlClient 是依據 System.Data.SqlClient 建置的新套件。 從現在開始，所有新功能的工作都在這裡執行。

除非客戶使用 Microsoft.Extensions.Caching.SqlServer 套件所傳回的型別，並將其轉換成 System.Data.SqlClient 型別，否則客戶不需要擔心這項中斷性變更。 例如，如果有人將 DbConnection 轉換成舊的 SqlConnection 型別，則必須將轉換變更為新的 Microsoft.Data.SqlClient.SqlConnection 型別。

類別

ASP.NET Core

受影響的 API

無

快取：ResponseCaching「pubternal」類型已變更為內部類型

在 ASP.NET Core 3.0 中，ResponseCaching 中的「pubternal」類型已變更為 internal。

此外，IResponseCachingPolicyProvider 和 IResponseCachingKeyProvider 的預設實作不會再新增至服務作為 AddResponseCaching 方法的一部分。

變更描述

在 ASP.NET Core 中，「pubternal」類型會宣告為 public，但會放置在尾碼為 .Internal 的命名空間中。 雖然這些型別是公用的，但沒有支援原則，而且可能會發生中斷性變更。 可惜的是，這些型別經常會被意外使用，導致這些專案出現中斷性變更，並限制維護架構的能力。

導入的版本

3.0

舊的行為

這些型別是公開可見的，但不受支援。

新的行為

這些型別現在為 internal。

變更原因

internal 範圍更能反映不支援的原則。

複製應用程式或程式庫所使用的型別。

類別

ASP.NET Core

受影響的 API

資料保護：DataProtection.Blobs 使用新的 Azure 儲存體 API

Azure.Extensions.AspNetCore.DataProtection.Blobs 取決於 Azure 儲存體程式庫。 這些程式庫已重新命名其組件、套件和命名空間。 從 ASP.NET Core 3.0 開始，Azure.Extensions.AspNetCore.DataProtection.Blobs 會使用加上 Azure.Storage. 前置詞的新 API 和套件。

若要了解 Azure 儲存體 API 相關問題，請使用 https://github.com/Azure/azure-storage-net。 如需了解有關此問題的討論，請參閱 dotnet/aspnetcore#19570。

導入的版本

3.0

舊的行為

此套件之前是參考 WindowsAzure.Storage NuGet 套件。 此套件現在參考 Microsoft.Azure.Storage.Blob NuGet 套件。

新的行為

此套件現在參考 Azure.Storage.Blob NuGet 套件。

變更原因

這項變更可讓 Azure.Extensions.AspNetCore.DataProtection.Blobs 移轉至建議的 Azure 儲存體套件。

如果您仍然需要搭配 ASP.NET Core 3.0 使用舊版 Azure 儲存體 API，請將直接相依性新增至套件 WindowsAzure.Storage 或 Microsoft.Azure.Storage。 此套件可以與新的 Azure.Storage API 一起安裝。

在許多情況下，升級只會牽涉到 using 陳述式變更為使用新的命名空間：

- 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;

類別

ASP.NET Core

受影響的 API

無

裝載：已從 Windows 裝載套件組合中移除 AspNetCoreModule V1

從 ASP.NET Core 3.0 開始，Windows 裝載套件組合不包含 AspNetCoreModule (ANCM) V1。

ANCM V2 與 ANCM OutOfProcess 回溯相容，建議搭配 ASP.NET Core 3.0 應用程式使用。

若要了解相關討論，請參閱 dotnet/aspnetcore#7095。

導入的版本

3.0

舊的行為

ANCM V1 包含在 Windows 裝載套件組合中。

新的行為

ANCM V1 未包含在 Windows 裝載套件組合中。

變更原因

ANCM V2 與 ANCM OutOfProcess 回溯相容，建議搭配 ASP.NET Core 3.0 應用程式使用。

搭配 ASP.NET Core 3.0 應用程式使用 ANCM V2。

如果需要 ANCM V1，可以使用 ASP.NET Core 2.1 或 2.2 Windows 裝載套件組合來安裝。

這項變更會中斷符合下列條件的 ASP.NET Core 3.0 應用程式：

  • 明確選擇使用 ANCM V1 搭配 <AspNetCoreModuleName>AspNetCoreModule</AspNetCoreModuleName>。
  • 取得自訂 web.config 檔案，其中含有 <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />。

類別

ASP.NET Core

受影響的 API

無

裝載：一般主機會限制啟動建構函式插入

泛型主機唯一支援 Startup 類別建構函式插入的型別為 IHostEnvironment、IWebHostEnvironment 和 IConfiguration。 使用 WebHost 的應用程式不會受到影響。

變更描述

在 ASP.NET Core 3.0 之前，建構函式插入可用於 Startup 類別建構函式中的任意類型。 在 ASP.NET Core 3.0 中，Web 堆疊已按平台重新設定為泛型主機程式庫。 您可以在範本的 Program.cs 檔案中看到變更：

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 使用一個相依性插入 (DI) 容器來建置應用程式。 WebHost 使用兩個容器：一個用於主機，另一個用於應用程式。 因此，Startup 建構函式不再支援自訂服務插入。 只能插入 IHostEnvironment、IWebHostEnvironment 和 IConfiguration。 這項變更可防止 DI 問題，例如重複建立單一資料庫服務問題。

導入的版本

3.0

變更原因

這項變更是將 Web 堆疊重新按平台設定為泛型主機程式庫的結果。

將服務插入 Startup.Configure 方法簽章。 例如：

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

類別

ASP.NET Core

受影響的 API

無

裝載：IIS 跨處理序應用程式啟用 HTTPS 重新導向

ASP.NET Core 模組 (ANCM) 13.0.19218.0 版可透過 IIS 跨處理序裝載，為 ASP.NET Core 3.0 和 2.2 應用程式啟用現有的 HTTPS 重新導向功能。

若要了解相關討論，請參閱 dotnet/AspNetCore#15243。

導入的版本

3.0

舊的行為

ASP.NET Core 2.1 專案範本首先導入了 HTTPS 中介軟體方法的支援，例如 UseHttpsRedirection 和 UseHsts。 啟用 HTTPS 重新導向需要新增設定，因為開發中的應用程式不會使用預設連接埠 443。 只有在要求已經使用 HTTPS 時，HTTP 嚴格傳輸安全性 (HSTS) 才會作用。 依預設，系統會略過 Localhost。

新的行為

在 ASP.NET Core 3.0 中，IIS HTTPS 案例已增強。 透過增強功能，應用程式可以探索伺服器的 HTTPS 連接埠，並依預設使 UseHttpsRedirection 運作。 同處理序元件使用 IServerAddresses 功能完成連接埠探索，此功能只會影響 ASP.NET Core 3.0 應用程式，因為同處理序程式庫是透過架構進行版本設定的。 跨處理序元件已變更為自動新增 ASPNETCORE_HTTPS_PORT 環境變數。 這項變更會影響 ASP.NET Core 2.2 和 3.0 應用程式，因為跨處理序元件為全域共用。 ASP.NET Core 2.1 應用程式不會受到影響，因為它們預設為使用舊版的 ANCM。

上述行為已於 ASP.NET Core 3.0.1 和 3.1.0 預覽版 3 中修改，以反轉 ASP.NET Core 2.x 中的行為變更。 這些變更只會影響 IIS 跨處理序應用程式。

如上所述，安裝 ASP.NET Core 3.0.0，會產生同時在 ASP.NET Core 2.x 應用程式中啟用 UseHttpsRedirection 中介軟體的副作用。 ANCM 已在 ASP.NET Core 3.0.1 和 3.1.0 預覽版 3 中變更，這樣一來，兩者的安裝就不會對 ASP.NET Core 2.x 應用程式造成此影響。 ANCM 在 ASP.NET Core 3.0.0 中植入的 ASPNETCORE_HTTPS_PORT 環境變數已在 ASP.NET Core 3.0.1 和 3.1.0 預覽版 3 中變更為 ASPNETCORE_ANCM_HTTPS_PORT。 UseHttpsRedirection 也在這些版本中更新，以了解新變數和舊變數。 ASP.NET Core 2.x 將不會更新。 因此，這會還原為預設停用的先前行為。

變更原因

已改善 ASP.NET Core 3.0 功能。

如果您希望所有用戶端都使用 HTTPS，則不需要採取任何動作。 若要允許某些用戶端使用 HTTP，請採取下列其中一項步驟：

  • 從專案的 Startup.Configure方法中移除對 UseHttpsRedirection 和 UseHsts 的呼叫，然後重新部署應用程式。

  • 在 web.config 檔案中，將 ASPNETCORE_HTTPS_PORT 環境變數設定為空字串。 這項變更可以在伺服器上直接發生，而不需重新部署應用程式。 例如：

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

UseHttpsRedirection 仍然可以：

  • 在 ASP.NET Core 2.x 中手動啟動，方法為將 ASPNETCORE_HTTPS_PORT 環境變數設為適當的連接埠號碼 (在大部分的實際執行案例中為 443)。
  • 在 ASP.NET Core 3.x 中停用，方法為使用空字串值來定義 ASPNETCORE_ANCM_HTTPS_PORT。 這個值設定的方式與上述 ASPNETCORE_HTTPS_PORT 範例相同。

執行 ASP.NET Core 3.0.0 應用程式的機器應先安裝 ASP.NET Core 3.0.1 執行階段，再安裝 ASP.NET Core 3.1.0 預覽版 3 ANCM。 這麼做可確保 ASP.NET Core 3.0 應用程式的 UseHttpsRedirection 繼續如預期運作。

在 Azure App Service 中，ANCM 會根據執行階段的全域本質，以個別排程進行部署。 在部署 ASP.NET Core 3.0.1 和 3.1.0 之後，ANCM 會連同這些變更部署至 Azure。

類別

ASP.NET Core

受影響的 API

HttpsPolicyBuilderExtensions.UseHttpsRedirection(IApplicationBuilder)

裝載：IHostingEnvironment 和 IApplicationLifetime 型別已淘汰並取代

引進新的型別來取代現有的 IHostingEnvironment 和 IApplicationLifetime 型別。

導入的版本

3.0

舊的行為

Microsoft.Extensions.Hosting 和Microsoft.AspNetCore.Hosting 之間有兩種不同的 IHostingEnvironment 和 IApplicationLifetime 型別。

新的行為

舊型別已標示為淘汰，並以新型別取代。

變更原因

在 ASP.NET Core 2.1 中導入 Microsoft.Extensions.Hosting 時，部分類型 (例如 IHostingEnvironment 和 IApplicationLifetime) 是從 Microsoft.AspNetCore.Hosting 複製的。 某些 ASP.NET Core 3.0 變更會導致應用程式同時包含 Microsoft.Extensions.Hosting 和 Microsoft.AspNetCore.Hosting 命名空間。 參考這兩個命名空間時，只要使用這些重複的型別就會造成「不明確的參考」編譯器錯誤。

以新導入的型別取代任何出現的舊型別，如下所示：

淘汰的型別 (警告)：

新型別：

新的 IHostEnvironment IsDevelopment 和 IsProduction 擴充方法位於 Microsoft.Extensions.Hosting 命名空間中。 該命名空間可能需要新增至您的專案。

類別

ASP.NET Core

受影響的 API

裝載：已從 WebHostBuilder 相依性中移除 ObjectPoolProvider

為了提高 ASP.NET Core 的隨用隨付效率，ObjectPoolProvider 已從主要相依性集合中移除。 現在會自行新增依賴 ObjectPoolProvider 的特定元件。

若要了解相關討論，請參閱 dotnet/aspnetcore#5944。

導入的版本

3.0

舊的行為

WebHostBuilder 預設會在 DI 容器中提供 ObjectPoolProvider。

新的行為

依預設，WebHostBuilder 不再於 DI 容器中提供 ObjectPoolProvider。

變更原因

這項變更可提高 ASP.NET Core 的隨用隨付效率。

如果您的元件需要 ObjectPoolProvider，則必須透過 IServiceCollection 新增至相依性。

類別

ASP.NET Core

受影響的 API

無

HTTP：已移除 DefaultHttpContext 擴充性

為了改善 ASP.NET Core 3.0 效能，已移除 DefaultHttpContext 的擴充性。 類別現在是 sealed。 如需詳細資訊，請參閱 dotnet/aspnetcore#6504。

如果您的單元測試使用 Mock<DefaultHttpContext>，請改用 Mock<HttpContext> 或 new DefaultHttpContext()。

若要了解相關討論，請參閱 dotnet/aspnetcore#6534。

導入的版本

3.0

舊的行為

類別可以衍生自 DefaultHttpContext。

新的行為

類別不能衍生自 DefaultHttpContext。

變更原因

一開始會提供擴充性以允許 HttpContext 共用，但這會造成不必要的複雜性，且阻礙了其他最佳化。

如果您在單元測試中使用 Mock<DefaultHttpContext>，請改為使用 Mock<HttpContext>。

類別

ASP.NET Core

受影響的 API

Microsoft.AspNetCore.Http.DefaultHttpContext

HTTP：HeaderNames 常數已變更為靜態唯讀

從 ASP.NET Core 3.0 預覽版 5 開始，Microsoft.Net.Http.Headers.HeaderNames 中的欄位已從 const 變更為 static readonly。

若要了解相關討論，請參閱 dotnet/aspnetcore#9514。

導入的版本

3.0

舊的行為

這些欄位曾經是 const。

新的行為

這些欄位現在是 static readonly。

變更原因

變更：

  • 防止值跨組件界限內嵌，允許視需要更正值。
  • 啟用更快速的參考相等檢查。

重新編譯 3.0。 以下列方式使用這些欄位的原始程式碼將無法再這麼做：

  • 作為屬性引數
  • 作為 switch 陳述式中的 case
  • 定義另一個 const 時

為了因應中斷性變更，請切換使用自我定義的標頭名稱常數或字串常值。

類別

ASP.NET Core

受影響的 API

Microsoft.Net.Http.Headers.HeaderNames

HTTP：回應本文基礎結構變更

支援 HTTP 回應本文的基礎結構已變更。 如果您直接使用 HttpResponse，就不需要進行任何程式碼變更。 如果您要包裝或取代 HttpResponse.Body，抑或是或存取 HttpContext.Features，請繼續閱讀。

導入的版本

3.0

舊的行為

有三個 API 與 HTTP 回應本文相關聯：

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

新的行為

如果您取代 HttpResponse.Body，這會使用 StreamResponseBodyFeature 來提供所有預期 API 的預設實作，將整個 IHttpResponseBodyFeature 取代為指定資料流周圍的包裝函式。 設定回原始資料流會還原這項變更。

變更原因

動機是將回應本文 API 結合成單一新功能介面。

在您先前使用 IHttpResponseFeature.Body、IHttpSendFileFeature 或 IHttpBufferingFeature 的位置使用 IHttpResponseBodyFeature。

類別

ASP.NET Core

受影響的 API

SameSite 是 Cookie 的選項，可協助減輕某些跨網站偽造要求 (CSRF) 攻擊。 一開始導入此選項時，各種 ASP.NET Core API 上使用的預設值並不一致。 不一致導致結果混淆。 自 ASP.NET Core 3.0 起，這些預設值的一致性已提高。 您必須根據每個元件選擇是否加入這項功能。

導入的版本

3.0

舊的行為

類似的 ASP.NET Core API 使用不同的預設 SameSiteMode 值。 在 HttpResponse.Cookies.Append(String, String) 和 HttpResponse.Cookies.Append(String, String, CookieOptions) 中看到不一致的範例，分別預設為 SameSiteMode.None 和 SameSiteMode.Lax。

新的行為

所有受影響的 API 預設為 SameSiteMode.None。

變更原因

預設值已變更，使 SameSite 成為選擇加入的功能。

發出 Cookie 的每個元件都必須決定 SameSite 是否適合其案例。 檢閱您受影響的 API 使用方式，並視需要重新設定 SameSite。

類別

ASP.NET Core

受影響的 API

HTTP：在所有伺服器中停用同步 IO

從 ASP.NET Core 3.0 開始，依預設會停用同步伺服器作業。

變更描述

AllowSynchronousIO 是每個伺服器中的選項，可啟用或停用同步 IO API，例如 HttpRequest.Body.Read、HttpResponse.Body.Write 和 Stream.Flush。 這些 API 長久以來都是執行緒耗盡和應用程式停止回應的來源。 從 ASP.NET Core 3.0 預覽版 3 開始，這些同步作業預設為停用。

受影響的伺服器：

  • Kestrel
  • HttpSys
  • IIS 同處理序
  • TestServer

預期發生類似下方的錯誤：

  • 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.

每部伺服器都有一個 AllowSynchronousIO 選項可控制此行為，而且所有伺服器的預設值現在是 false。

行為也可以根據每個要求進行複寫，以作為暫時性風險降低措施。 例如：

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

如果您在 Dispose 中使用 TextWriter 或另一個串流呼叫同步 API 時發生問題，請改為呼叫新的 DisposeAsync API。

若要了解相關討論，請參閱 dotnet/aspnetcore#7644。

導入的版本

3.0

舊的行為

根據預設，可以使用 HttpRequest.Body.Read、HttpResponse.Body.Write 和 Stream.Flush。

新的行為

預設不允許這些同步 API：

預期發生類似下方的錯誤：

  • 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.

變更原因

這些同步 API 長久以來都是執行緒耗盡和應用程式停止回應的來源。 從 ASP.NET Core 3.0 預覽版 3 開始，同步作業預設為停用。

使用方法的非同步版本。 行為也可以根據每個要求進行複寫，以作為暫時性風險降低措施。

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

類別

ASP.NET Core

受影響的 API

身分識別：已移除 AddDefaultUI 方法多載

從 ASP.NET Core 3.0 開始，IdentityBuilderUIExtensions.AddDefaultUI(IdentityBuilder,UIFramework) 方法多載已不存在。

導入的版本

3.0

變更原因

這項變更是採用靜態 Web 資產功能的結果。

呼叫 IdentityBuilderUIExtensions.AddDefaultUI(IdentityBuilder)，而不是採用兩個引數的多載。 如果您使用 Bootstrap 3，也請將下列這一行新增至專案檔中的 <PropertyGroup> 元素：

<IdentityUIFrameworkVersion>Bootstrap3</IdentityUIFrameworkVersion>

類別

ASP.NET Core

受影響的 API

IdentityBuilderUIExtensions.AddDefaultUI(IdentityBuilder,UIFramework)

身分識別：預設啟動程序版本的 UI 已變更

從 ASP.NET Core 3.0 開始，身分識別 UI 預設為使用第 4 版的 Bootstrap。

導入的版本

3.0

舊的行為

services.AddDefaultIdentity<IdentityUser>().AddDefaultUI(); 方法呼叫之前與 services.AddDefaultIdentity<IdentityUser>().AddDefaultUI(UIFramework.Bootstrap3); 相同

新的行為

services.AddDefaultIdentity<IdentityUser>().AddDefaultUI(); 方法呼叫現在與 services.AddDefaultIdentity<IdentityUser>().AddDefaultUI(UIFramework.Bootstrap4); 相同

變更原因

Bootstrap 4 是在 ASP.NET Core 3.0 時間範圍內發行的。

如果您使用預設的身分識別 UI 並在 Startup.ConfigureServices 中新增它，就會受到此變更的影響，如下列範例所示：

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

執行下列其中一項動作：

  • 移轉您的應用程式以使用 Bootstrap 4，並使用其移轉指南。

  • 更新 Startup.ConfigureServices 以強制使用 Bootstrap 3。 例如：

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

類別

ASP.NET Core

受影響的 API

無

身分識別：SignInAsync 擲回未驗證身分識別的例外狀況

根據預設，SignInAsync 會擲回主體/身分識別的例外狀況，其中 IsAuthenticated 為 false。

導入的版本

3.0

舊的行為

SignInAsync 接受任何主體/身分識別，包括 IsAuthenticated 是 false 的身分識別。

新的行為

根據預設，SignInAsync 會擲回主體/身分識別的例外狀況，其中 IsAuthenticated 為 false。 有新的旗標可隱藏此行為，但預設行為已變更。

變更原因

舊行為有問題，因為根據預設，這些主體會遭到 [Authorize] / RequireAuthenticatedUser() 拒絕。

在 ASP.NET Core 3.0 預覽版 6 中，依預設 AuthenticationOptions 上會有一個 RequireAuthenticatedSignIn 旗標為 true。 將此旗標設定為 false 以還原舊行為。

類別

ASP.NET Core

受影響的 API

無

身分識別：SignInManager 建構函式接受新的參數

從 ASP.NET Core 3.0 開始，新的 IUserConfirmation<TUser> 參數已新增至 SignInManager 建構函式。 如需詳細資訊，請參閱 dotnet/aspnetcore#8356。

導入的版本

3.0

變更原因

變更的動機是為了在身分識別中替新電子郵件/確認流程新增支援。

如果手動建構 SignInManager，請提供 IUserConfirmation 的實作，或從相依性插入擷取一個實作來提供。

類別

ASP.NET Core

受影響的 API

SignInManager<TUser>

身分識別：UI 使用靜態 Web 資產功能

ASP.NET Core 3.0 導入了靜態 Web 資產功能，身分識別 UI 已加以採用。

變更描述

由於身分識別 UI 採用靜態 Web 資產功能：

  • 在專案中中使用 IdentityUIFrameworkVersion 屬性以完成架構選擇。
  • Bootstrap 4 是身分識別 UI 的預設 UI 架構。 Bootstrap 3 已結束生命週期，您應該考慮移轉至支援的版本。

導入的版本

3.0

舊的行為

身分識別 UI 的預設 UI 架構之前是 Bootstrap 3。 UI 架構可以使用 Startup.ConfigureServices 中的 AddDefaultUI 方法呼叫參數來設定。

新的行為

身分識別 UI 的預設 UI 架構是 Bootstrap 4。 UI 架構必須在專案檔中設定，而不是在 AddDefaultUI 方法呼叫中設定。

變更原因

採用靜態 Web 資產功能時，UI 架構設定必須移至 MSBuild。 內嵌架構的決定是一種建置階段決策，而不是執行階段決策。

檢閱您的網站 UI，以確保新的 Bootstrap 4 元件相容。 如有必要，請使用 IdentityUIFrameworkVersion MSBuild 屬性以還原為 Bootstrap 3。 將屬性新增至專案檔中的 <PropertyGroup> 元素：

<IdentityUIFrameworkVersion>Bootstrap3</IdentityUIFrameworkVersion>

類別

ASP.NET Core

受影響的 API

IdentityBuilderUIExtensions.AddDefaultUI(IdentityBuilder, UIFramework)

Kestrel：已移除連線配接器

將「pubternal」API 移動至 public 的過程中，已從 Kestrel 中移除 IConnectionAdapter 的概念。 連線配接器會取代為連線中介軟體 (類似 ASP.NET Core 管線中的 HTTP 中介軟體，但適用於較低層級的連線)。 HTTPS 和連線記錄已從連接配接器移至連線中介軟體。 這些擴充方法應該會繼續順暢地運作，但實作詳細資料已變更。

如需詳細資訊，請參閱 dotnet/aspnetcore#11412。 若要了解相關討論，請參閱 dotnet/aspnetcore#11475。

導入的版本

3.0

舊的行為

Kestrel 擴充性元件是使用 IConnectionAdapter 建立的。

新的行為

Kestrel 擴充性元件會建立為中介軟體。

變更原因

這項變更旨在提供更具彈性的擴充性結構。

轉換 IConnectionAdapter 的任何實作以使用新的中介軟體模式，如此處所示。

類別

ASP.NET Core

受影響的 API

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

Kestrel：已移除空的 HTTPS 組件

已移除組件 Microsoft.AspNetCore.Server.Kestrel.Https。

導入的版本

3.0

變更原因

在 ASP.NET Core 2.1 中，Microsoft.AspNetCore.Server.Kestrel.Https 的內容已移至 Microsoft.AspNetCore.Server.Kestrel.Core。 這項變更是以非中斷的方式使用 [TypeForwardedTo] 屬性來完成。

  • 參考 Microsoft.AspNetCore.Server.Kestrel.Https 2.0 的程式庫應將所有 ASP.NET Core 相依性更新為 2.1 或更新版本。 否則，可能會在載入 ASP.NET Core 3.0 應用程式時中斷。
  • 以 ASP.NET Core 2.1 和更新版本為目標的應用程式和程式庫應移除 Microsoft.AspNetCore.Server.Kestrel.Https NuGet 套件的任何直接參考。

類別

ASP.NET Core

受影響的 API

無

Kestrel：要求尾端標頭已移至新集合

在舊版中，Kestrel 會在要求本文讀取至結尾時，將 HTTP/1.1 區塊化尾端標頭新增至要求標頭集合。 此行為會造成對標頭和尾端之間模棱兩可的疑慮。 決定將尾端移至新的集合。

HTTP/2 要求尾端先前在 ASP.NET Core 2.2 中無法使用，但現在也可以在 ASP.NET Core 3.0 的這個新集合中取得了。

已新增新的要求擴充方法來存取這些尾端。

讀取整個要求本文之後，即可使用 HTTP/1.1 尾端。

從用戶端收到 HTTP/2 尾端後，即可使用。 在伺服器至少緩衝處理整個要求本文之前，用戶端不會傳送尾端。 您可能需要讀取要求本文，以釋放緩衝區空間。 如果您將要求本文讀到結尾，則一定可以取得尾端。 尾端會標示本文的結尾。

導入的版本

3.0

舊的行為

要求尾端標頭會新增至 HttpRequest.Headers 集合。

新的行為

要求尾端標頭 不存在於 HttpRequest.Headers 集合中。 在 HttpRequest 中使用下列擴充方法來存取：

  • GetDeclaredTrailers() - 取得要求 "Trailer" 標頭，其中列出在本文之後預期有哪些尾端。
  • SupportsTrailers() - 指出要求是否支援接收尾端標頭。
  • CheckTrailersAvailable() - 判斷要求是否支援尾端，以及是否可供讀取。
  • GetTrailer(string trailerName) - 從回應取得所要求的尾端標頭。

變更原因

尾端是 gRPC 等案例中的重要功能。 將尾端合併至要求標頭，會對使用者造成混淆。

在 HttpRequest 中使用尾端相關擴充方法來存取尾端。

類別

ASP.NET Core

受影響的 API

HttpRequest.Headers

Kestrel：已移除並公開傳輸抽象概念

在離開「pubternal」API 的過程中，Kestrel 傳輸層 API 會公開為 Microsoft.AspNetCore.Connections.Abstractions 程式庫中的公用介面。

導入的版本

3.0

舊的行為

  • 您可以在 Microsoft.AspNetCore.Server.Kestrel.Transport.Abstractions 程式庫中取得傳輸相關的抽象概念。
  • ListenOptions.NoDelay 屬性可供使用。

新的行為

  • Microsoft.AspNetCore.Connections.Abstractions 程式庫中引進了 IConnectionListener 介面，可以公開 ...Transport.Abstractions 程式庫中最常使用的功能。
  • NoDelay 現在可在傳輸選項中使用 (LibuvTransportOptions 和 SocketTransportOptions)。
  • SchedulingMode 無法再使用。

變更原因

ASP.NET Core 3.0 已從「pubternal」API 中移除。

類別

ASP.NET Core

受影響的 API

無

當地語系化：ResourceManagerWithCultureStringLocalizer 和 WithCulture 標示為已淘汰

ResourceManagerWithCultureStringLocalizer 類別和 WithCulture 介面成員通常是造成當地語系化使用者覺得混淆不清的來源，特別是在建立自己的 IStringLocalizer 實作時。 這些項目可讓使用者覺得 IStringLocalizer 執行個體是「根據語言，根據資源」而定。 事實上，執行個體應該只能是「根據資源」而定。 搜尋的語言取決於執行時間的 CultureInfo.CurrentUICulture。 為了消除混淆的來源，這些 API 在 ASP.NET Core 3.0 中標示為已淘汰。 API 將在未來的發行版本中移除。

如需內容，請參閱 dotnet/aspnetcore#3324。 若要了解相關討論，請參閱 dotnet/aspnetcore#7756。

導入的版本

3.0

舊的行為

方法之前未標示為 Obsolete。

新的行為

方法現在標示 Obsolete。

變更原因

API 代表不建議的使用案例。 當地語系化的設計有混淆不清的情況。

建議改用 ResourceManagerStringLocalizer。 讓文化特性由 CurrentCulture 設定。 如果沒有這個選項，請建立並使用 ResourceManagerWithCultureStringLocalizer 的複本。

類別

ASP.NET Core

受影響的 API

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

記錄：DebugLogger 類別已設為 internal

在 ASP.NET Core 3.0 之前，DebugLogger 的存取修飾詞是 public。 在 ASP.NET Core 3.0 中，存取修飾詞已變更為 internal。

導入的版本

3.0

變更原因

正在進行下列變更：

  • 強制執行與其他記錄器實作保持一致性，例如 ConsoleLogger。
  • 減少 API 介面。

使用 AddDebug ILoggingBuilder 擴充方法來啟用偵錯記錄。 就算需要手動註冊服務，DebugLoggerProvider 也依然是 public。

類別

ASP.NET Core

受影響的 API

Microsoft.Extensions.Logging.Debug.DebugLogger

MVC：從控制器動作名稱修剪的非同步尾碼

在定址 dotnet/aspnetcore#4849 的過程中，ASP.NET Core MVC 依預設會修剪動作名稱的尾碼 Async。 從 ASP.NET Core 3.0 開始，這項變更會影響路由和連結產生。

導入的版本

3.0

舊的行為

請考量下列 ASP.NET Core MVC 控制器：

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

動作可透過 Product/ListAsync 路由傳送。 產生連結需要指定 Async 尾碼。 例如：

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

新的行為

在 ASP.NET Core 3.0 中，此動作可透過 Product/List 路由傳送。 連結產生程式碼應該省略 Async 尾碼。 例如：

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

這項變更不會影響使用 [ActionName] 屬性指定的名稱。 在 Startup.ConfigureServices 中將 MvcOptions.SuppressAsyncSuffixInActionNames 設定為 false，即可停用新的行為：

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

變更原因

依照慣例，非同步 .NET 方法會以 Async 作為尾碼。 不過，當方法定義 MVC 動作時，不建議使用 Async 尾碼。

如果應用程式相依的 MVC 動作保留了名稱的 Async 尾碼，請選擇下列其中一個風險降低措施：

  • 使用 [ActionName] 屬性來保留原始名稱。
  • 在 Startup.ConfigureServices 中將 MvcOptions.SuppressAsyncSuffixInActionNames 設定為 false，以完全停用重新命名：
services.AddMvc(options =>
{
   options.SuppressAsyncSuffixInActionNames = false;
});

類別

ASP.NET Core

受影響的 API

無

MVC：JsonResult 已移至 Microsoft.AspNetCore.Mvc.Core

JsonResult 已移至 Microsoft.AspNetCore.Mvc.Core 組件。 此型別是用來在 Microsoft.AspNetCore.Mvc.Formatters.Json 中定義。 組件層級 [TypeForwardedTo] 屬性已新增至 Microsoft.AspNetCore.Mvc.Formatters.Json，以解決大部分使用者的這個問題。 使用協力廠商程式庫的應用程式可能會遇到問題。

導入的版本

3.0 預覽版 6

舊的行為

使用 2.2 型程式庫的應用程式已成功建置。

新的行為

使用 2.2 型程式庫的應用程式編譯失敗。 系統會提供含有下列文字變化的錯誤訊息：

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'

如需這類問題的範例，請參閱 dotnet/aspnetcore#7220。

變更原因

ASP.NET Core 組合的平台層級變更，如 aspnet/Announcements#325 所述。

針對 Microsoft.AspNetCore.Mvc.Formatters.Json 2.2 版編譯的程式庫可能需要重新編譯，才能解決所有取用這的這個問題。 如果受到影響，請連絡程式庫建立者。 要求在以 ASP.NET Core 3.0 為目標的條件下重新編譯程式庫。

類別

ASP.NET Core

受影響的 API

Microsoft.AspNetCore.Mvc.JsonResult

MVC：先行編譯工具已被取代

在 ASP.NET Core 1.1 中導入了 Microsoft.AspNetCore.Mvc.Razor.ViewCompilation (MVC 先行編譯工具) 套件，以新增 Razor 檔案 (.cshtml 檔案) 發佈階段編譯的支援。 在 ASP.NET Core 2.1 中導入了 Razor SDK，以擴充先行編譯工具的功能。 Razor SDK 新增了 Razor 檔案建置和發佈階段編譯的支援。 SDK 會在建置階段驗證 .cshtml 檔案的正確性，同時改善應用程式啟動時間。 Razor SDK 預設為開啟，不需要手勢即可開始使用。

在 ASP.NET Core 3.0 中，已移除 ASP.NET Core 1.1 版 MVC 先行編譯工具。 舊版套件會繼續在修補程式版本中收到重要的錯誤和安全性修正程式。

導入的版本

3.0

舊的行為

Microsoft.AspNetCore.Mvc.Razor.ViewCompilation 套件是用來預先編譯 MVC Razor 檢視。

新的行為

Razor SDK 原本就支援這項功能。 不再更新 Microsoft.AspNetCore.Mvc.Razor.ViewCompilation 套件。

變更原因

Razor SDK 提供更多功能，並在建置階段驗證 .cshtml 檔案的正確性。 SDK 也會改善應用程式啟動時間。

若是 ASP.NET Core 2.1 或更新版本的使用者，請更新為使用 Razor SDK 中先行編譯的原生支援。 如果錯誤或遺漏功能導致無法移轉至 Razor SDK，請在 dotnet/aspnetcore 提出問題。

類別

ASP.NET Core

受影響的 API

無

MVC：「pubternal」類型已變更為內部類型

在 ASP.NET Core 3.0 中，MVC 中的所有「pubternal」類型都已視情況更新為支援命名空間中的 public 或 internal。

變更描述

在 ASP.NET Core 中，「pubternal」類型會宣告為 public，但位於以 .Internal 爲尾碼的命名空間中。 雖然這些型別是 public，但沒有支援原則，而且可能會發生中斷性變更。 可惜的是，這些型別經常會被意外使用，導致這些專案出現中斷性變更，並限制維護架構的能力。

導入的版本

3.0

舊的行為

MVC 中的某些型別是 public，但在 .Internal 命名空間中。 這些型別沒有支援原則，而且可能會發生中斷性變更。

新的行為

所有這類型別都會更新為支援命名空間中的 public，或標示為 internal 。

變更原因

這些「pubternal」類型經常會被意外使用，導致這些專案出現中斷性變更，並限制維護結構的能力。

如果您使用的型別已確實變成 public，而且已移至新的支援命名空間，請更新您的參考以符合新的命名空間。

如果您使用已標示為 internal 的型別，則必須尋找替代項目。 先前的「pubternal」類型從未支援供公用使用。 如果這些命名空間中有特定型別對您的應用程式很重要，請在 dotnet/aspnetcore 提出問題。 可能會考慮讓所要求的型別成為 public。

類別

ASP.NET Core

受影響的 API

這項變更包含下列命名空間中的型別：

  • 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 相容性填充碼

從 ASP.NET Core 3.0 開始，不再提供 Microsoft.AspNetCore.Mvc.WebApiCompatShim 套件。

變更描述

Microsoft.AspNetCore.Mvc.WebApiCompatShim (WebApiCompatShim) 套件與使用 ASP.NET 4.x Web API 2 的 ASP.NET Core 部分相容，可以簡化將現有 Web API 實作移轉至 ASP.NET Core 的作業。 不過，使用 WebApiCompatShim 的應用程式並不會獲益於最近 ASP.NET Core 版本所提供的 API 相關功能。 這類功能包括改善的 Open API 規格產生、標準化錯誤處理，以及用戶端程式碼產生。 為了在 3.0 中提升 API 工作成效，已移除 WebApiCompatShim。 使用 WebApiCompatShim 的現有應用程式應該移轉至較新的 [ApiController] 模型。

導入的版本

3.0

變更原因

Web API 相容性填充碼是移轉工具。 會限制使用者存取 ASP.NET Core 中新增的功能。

移除此填充碼的使用，並直接移轉至 ASP.NET Core 本身的類似功能。

類別

ASP.NET Core

受影響的 API

Microsoft.AspNetCore.Mvc.WebApiCompatShim

Razor：已移除 RazorTemplateEngine API

RazorTemplateEngineAPI 已移除，並以 Microsoft.AspNetCore.Razor.Language.RazorProjectEngine 取代。

若要查看討論內容，請參閱 GitHub 問題 dotnet/aspnetcore#25215 (英文)。

導入的版本

3.0

舊的行為

您可以建立範本引擎，並用來剖析和產生 Razor 檔案的程式碼。

新的行為

RazorProjectEngine 可以建立並提供與 RazorTemplateEngine 相同的資訊型別，來剖析和產生 Razor 檔案的程式碼。 RazorProjectEngine 也提供額外的設定層級。

變更原因

RazorTemplateEngine 過於緊密地結合至現有的實作。 這種緊密結合會導致嘗試正確設定 Razor 剖析/產生管線時發生更多問題。

使用 RazorProjectEngine 取代 RazorTemplateEngine。 請思考一下下列範例。

建立及設定 RazorProjectEngine
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
        });
產生 Razor 檔案的程式碼
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();

類別

ASP.NET Core

受影響的 API

  • RazorTemplateEngine
  • RazorTemplateEngineOptions

Razor：執行階段編譯已移至套件

Razor 檢視和 Razor Pages 的執行階段編譯支援已移至不同的套件。

導入的版本

3.0

舊的行為

執行階段編譯可供使用，而不需要額外的套件。

新的行為

此功能已移至 Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation 套件。

先前已在 Microsoft.AspNetCore.Mvc.Razor.RazorViewEngineOptions 中提供下列 API 來支援執行階段編譯。 API 現在可透過 Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation.MvcRazorRuntimeCompilationOptions 取得。

  • RazorViewEngineOptions.FileProviders 現在為 MvcRazorRuntimeCompilationOptions.FileProviders
  • RazorViewEngineOptions.AdditionalCompilationReferences 現在為 MvcRazorRuntimeCompilationOptions.AdditionalReferencePaths

此外，Microsoft.AspNetCore.Mvc.Razor.RazorViewEngineOptions.AllowRecompilingViewsOnFileChange 已移除。 根據預設，參考 Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation 套件會啟用檔案變更的重新編譯。

變更原因

需要這項變更，才能移除 Roslyn 上的 ASP.NET Core 共用架構相依性。

需要執行階段編譯或重新編譯 Razor 檔案的應用程式應該採取下列步驟：

  1. 將參考新增至 Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation 套件。

  2. 更新專案的 Startup.ConfigureServices 方法以包括對 AddRazorRuntimeCompilation 的呼叫。 例如：

    services.AddMvc()
    .AddRazorRuntimeCompilation();

類別

ASP.NET Core

受影響的 API

Microsoft.AspNetCore.Mvc.Razor.RazorViewEngineOptions

工作階段狀態：已移除淘汰的 API

用來設定工作階段 Cookie 的淘汰 API 已移除。 如需詳細資訊，請參閱 aspnet/Announcements#257。

導入的版本

3.0

變更原因

這項變更會強制執行 API 之間的一致性，以設定使用 Cookie 的功能。

將已移除 API 的使用移轉至其較新的取代項目。 請考慮 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;
    });
}

類別

ASP.NET Core

受影響的 API

共用架構：從 Microsoft.AspNetCore.App 移除的組件

從 ASP.NET Core 3.0 開始，ASP.NET Core 共用架構 (Microsoft.AspNetCore.App) 只包含 Microsoft 完全開發、支援及可服務的第一方組件。

變更描述

請將變更視為重新定義 ASP.NET Core「平台」的界限。共用架構將可由任何人透過 GitHub 利用原始碼重新建置，並讓應用程式繼續享有 .NETCore 共用架構的現有優點。 其中部分優點包括較小的部署大小、集中式修補，以及更快的啟動時間。

在變更過程中，會在 Microsoft.AspNetCore.App 中引進一些值得注意的中斷性變更。

導入的版本

3.0

舊的行為

專案透過專案檔中的 <PackageReference> 元素參考 Microsoft.AspNetCore.App。

此外，Microsoft.AspNetCore.App 包含下列子元件：

  • Json.NET (Newtonsoft.Json)
  • Entity Framework Core (前綴 Microsoft.EntityFrameworkCore. 的組件)
  • Roslyn (Microsoft.CodeAnalysis)

新的行為

Microsoft.AspNetCore.App 的參考不再需要專案檔中的 <PackageReference> 元素。 .NET Core SDK 支援名為 <FrameworkReference> 的新元素，此元素將汰用 <PackageReference>。

如需詳細資訊，請參閱 dotnet/aspnetcore#3612。

Entity Framework Core 會以 NuGet 套件出貨。 這項變更將使隨附模型與 .NET 上的所有其他資料存取程式庫保持一致。 讓 Entity Framework Core 能夠以最簡單的方式繼續創新，同時支援各種 .NET 平台。 將 Entity Framework Core 移出共用架構不會影響其身為 Microsoft 開發、支援及可服務程式庫的狀態。 .NET Core 支援原則會繼續將其納入支援範圍。

Json.NET 和 Entity Framework Core 會繼續使用 ASP.NET Core。 不過，不會將它們納入共用架構之中。

如需詳細資訊，請參閱 JSON 於 .NET Core 3.0 中的未來。 另請參閱已從共用架構中移除的二進位檔完整清單。

變更原因

這項變更可簡化 Microsoft.AspNetCore.App 的取用，並減少 NuGet 套件與共享架構之間的重複。

如需此變更動機的詳細資訊，請參閱此部落格文章。

從 ASP.NET Core 3.0 開始，專案不再需要以 NuGet 套件形式取用 Microsoft.AspNetCore.App 中的組件。 為了簡化 ASP.NET Core 共用架構的定位和使用，ASP.NET Core 1.0 以來隨附的許多 NuGet 套件都不再產生。 透過使用 <FrameworkReference> 至 Microsoft.AspNetCore.App，這些套件提供的 API 仍可供應用程式利用。 常見的 API 範例包括 Kestrel、MVC 和 Razor。

這項變更不適用於 ASP.NET Core 2.x 中透過 Microsoft.AspNetCore.App 參考的所有二進位檔。 值得注意的例外狀況包括：

  • 繼續以 .NET Standard 為目標的 Microsoft.Extensions 程式庫可作為 NuGet 套件使用 (請參閱 https://github.com/dotnet/extensions)。
  • ASP.NET Core 小組所產生的 API 不屬於 Microsoft.AspNetCore.App。 例如，下列元件可作為 NuGet 套件使用：
  • 維護 Json.NET 支援的 MVC 擴充功能。 API 會以 NuGet 套件的形式提供，以支援使用 Json.NET 和 MVC。 如需詳細資訊，請參閱 ASP.NET Core 移轉指南。
  • SignalR .NET 用戶端會繼續支援 .NET Standard，並以 NuGet 套件的形式隨附。 適用於許多 .NET 執行階段，例如 Xamarin 和 UWP。

如需詳細資訊，請參閱 停止在 3.0 中產生共用架構組件的套件。 若要了解相關討論，請參閱 dotnet/aspnetcore#3757。

類別

ASP.NET Core

受影響的 API

共用架構：Microsoft.AspNetCore.All 已移除

從 ASP.NET Core 3.0 開始，不再產生 Microsoft.AspNetCore.All 中繼套件和相符的 Microsoft.AspNetCore.All 共用架構。 此套件可在 ASP.NET Core 2.2 中取得，並將繼續在 ASP.NET Core 2.1 中接收服務更新。

導入的版本

3.0

舊的行為

應用程式可以使用 Microsoft.AspNetCore.All 中繼套件，以 .NET Core 上的 Microsoft.AspNetCore.All 共用架構為目標。

新的行為

.NET Core 3.0 不包含 Microsoft.AspNetCore.All 共用架構。

變更原因

Microsoft.AspNetCore.All 中繼套件包含大量的外部相依性。

移轉您的專案以使用 Microsoft.AspNetCore.App 架構。 先前在 Microsoft.AspNetCore.All 中提供的元件仍可在 NuGet 上使用。 這些元件現在會隨著您的應用程式部署，而不是包含在共用架構中。

類別

ASP.NET Core

受影響的 API

無

SignalR：HandshakeProtocol.SuccessHandshakeData 已取代

已移除 HandshakeProtocol.SuccessHandshakeData 欄位，並以協助程式方法取代，該方法會產生特定 IHubProtocol 的成功交握回應。

導入的版本

3.0

舊的行為

HandshakeProtocol.SuccessHandshakeData 之前是 public static ReadOnlyMemory<byte> 欄位。

新的行為

HandshakeProtocol.SuccessHandshakeData 已由 static GetSuccessfulHandshake(IHubProtocol protocol) 方法取代，此方法會依據指定的通訊協定傳回 ReadOnlyMemory<byte>。

變更原因

其他欄位已新增至交握回應，這些欄位屬於非常數且會依據選取的通訊協定而改變。

無。 此型別並非為了在使用者程式碼中使用而設計。 這是 public，因此可以在 SignalR 伺服器與用戶端之間共用。 以 .NET 撰寫的客戶 SignalR 用戶端也可加以使用。 SignalR 的使用者不應受到這項變更的影響。

類別

ASP.NET Core

受影響的 API

HandshakeProtocol.SuccessHandshakeData

SignalR：HubConnection ResetSendPing 和 ResetTimeout 方法已移除

ResetSendPing和 ResetTimeout 方法已從 SignalR HubConnection API 中移除。 這些方法原本僅供內部使用，但於 ASP.NET Core 2.2 公開。 從 ASP.NET Core 3.0 預覽版 4 開始，將無法使用這些方法。 若要了解相關討論，請參閱 dotnet/aspnetcore#8543。

導入的版本

3.0

舊的行為

API 曾可供使用。

新的行為

已移除 API。

變更原因

這些方法原本僅供內部使用，但於 ASP.NET Core 2.2 公開。

請勿使用這些方法。

類別

ASP.NET Core

受影響的 API

SignalR：HubConnectionContext 建構函式已變更

SignalR 的 HubConnectionContext 建構函式已變更為接受選項型別，而不是多個參數，以在未來證明新增選項。 這項變更會將兩個建構函式取代為一個接受選項型別的建構函式。

導入的版本

3.0

舊的行為

HubConnectionContext 有兩個建構函式：

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

新的行為

已移除這兩個建構函式，並以一個建構函式取代：

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

變更原因

新的建構函式會使用新的 options 物件。 因此，未來可以擴充 HubConnectionContext 的功能，而不需要建立更多建構函式並進行中斷性變更。

不使用下列建構函式：

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

而是使用下列建構函式：

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

類別

ASP.NET Core

受影響的 API

SignalR：JavaScript 用戶端套件名稱變更

在 ASP.NET Core 3.0 預覽版 7 中，SignalR JavaScript 用戶端套件名稱從 @aspnet/signalr 變更為 @microsoft/signalr。 此名稱變更反映出 SignalR 不僅僅在 ASP.NET Core 應用程式中有用的事實，這得益於 Azure SignalR Service。

若要回應這項變更，請變更 package.json 檔案、require 陳述式和 ECMAScript import 陳述式中的參考。 在此重新命名過程中，不會有任何 API 變更。

若要了解相關討論，請參閱 dotnet/aspnetcore#11637。

導入的版本

3.0

舊的行為

用戶端套件之前名為 @aspnet/signalr。

新的行為

用戶端套件現在名為 @microsoft/signalr。

變更原因

此名稱變更說明了 SignalR 不僅僅在 ASP.NET Core 應用程式中有用而已，這得益於 Azure SignalR Service。

切換至新的套件 @microsoft/signalr。

類別

ASP.NET Core

受影響的 API

無

SignalR：UseSignalR 和 UseConnections 方法標示為已淘汰

方法 UseConnections 和 UseSignalR 以及類別 ConnectionsRouteBuilder 和 HubRouteBuilder 在 ASP.NET Core 3.0 中標示為已淘汰。

導入的版本

3.0

舊的行為

SignalR 中樞路由透過使用 UseSignalR 或 UseConnections 進行設定。

新的行為

設定路由的舊方式已經淘汰，並取代為端點路由。

變更原因

中介軟體正在移至新的端點路由系統。 新增中介軟體的舊方式已經淘汰。

將 UseSignalR 取代為 UseEndpoints：

舊程式碼：

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

新程式碼：

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

類別

ASP.NET Core

受影響的 API

SPA：SpaServices 和 NodeServices 標示為已淘汰

自 ASP.NET Core 2.1 起，已不再需要下列 NuGet 套件的內容。 因此，下列套件標示為已淘汰：

基於相同的理由，下列 npm 模組標示為已被取代：

上述套件和 npm 模組後續會在 .NET 5 中移除。

導入的版本

3.0

舊的行為

被取代的套件和 npm 模組旨在整合 ASP.NET Core 與各種單頁應用程式 (SPA) 架構。 這類架構包括 redux Angular、React 和使用 Redux 的 React。

新的行為

Microsoft.AspNetCore.SpaServices.Extensions NuGet 套件中有新的整合機制。 自 ASP.NET Core 2.1 起，套件會維持 Angular 和 React 專案範本的基礎。

變更原因

ASP.NET Core 支援與各種單頁應用程式 (SPA) 架構整合，包括 Angular、React 和使用 Redux 的 React。 一開始，與這些架構的整合透過 ASP.NET Core 特定元件來完成，這些元件可處理伺服器端預先轉譯和整合 Webpack 等案例。 業界標準已隨著時間變更。 每個 SPA 架構都會發行自己的標準命令列介面。 例如，Angular CLI 和 create-react-app。

ASP.NET Core 2.1 於 2018 年 5 月發行時，小組回應了標準的變更。 已提供較新且更簡單的方式來整合 SPA 架構本身的工具鏈。 新的整合機制存在於套件 Microsoft.AspNetCore.SpaServices.Extensions 中，並維持自 ASP.NET Core 2.1 以來的 Angular 和 React 專案範本基礎。

為了表明較舊的 ASP.NET Core 特定元件不相關且不建議使用：

  • 2.1 之前的整合機制標示為已淘汰。
  • 支援的 npm 套件標示為已被取代。

如果您使用這些套件，請更新您的應用程式以使用功能：

  • 在 Microsoft.AspNetCore.SpaServices.Extensions 套件中。
  • 由您使用的 SPA 架構所提供

若要啟用伺服器端預先呈現和熱模組重載等功能，請參閱對應 SPA 架構的文件。 Microsoft.AspNetCore.SpaServices.Extensions 中的功能尚未淘汰，而且將繼續受到支援。

類別

ASP.NET Core

受影響的 API

SPA：SpaServices 和 NodeServices 不再回復至主控台記錄器

除非已設定記錄，否則 Microsoft.AspNetCore.SpaServices 和 Microsoft.AspNetCore.NodeServices 不會顯示主控台記錄。

導入的版本

3.0

舊的行為

Microsoft.AspNetCore.SpaServices 和 Microsoft.AspNetCore.NodeServices 用於在未設定記錄時自動建立主控台記錄器。

新的行為

除非已設定記錄，否則 Microsoft.AspNetCore.SpaServices 和 Microsoft.AspNetCore.NodeServices 不會顯示主控台記錄。

變更原因

需要與其他 ASP.NET Core 套件實作記錄的方式一致。

如果需要舊的行為，而要設定主控台記錄，請將 services.AddLogging(builder => builder.AddConsole()) 新增至您的 Setup.ConfigureServices 方法。

類別

ASP.NET Core

受影響的 API

無

目標架構：.NET Framework 支援已卸除

從 ASP.NET Core 3.0 開始，.NET Framework 不再是受支援的目標架構。

變更描述

.NET Framework 4.8 是 .NET Framework 的最後一個主要版本。 新的 ASP.NET Core 應用程式應建置在 .NET Core 上。 從 .NET Core 3.0 版本開始，您可以將 ASP.NET Core 3.0 視為 .NET Core 的一部分。

使用 ASP.NET Core 搭配 .NET Framework 的客戶可以使用 2.1 LTS 版本，繼續受到完整支援。 2.1 的支援與服務會持續到至少 2021 年 8 月 21 日為止。 根據 .NET 支援原則，此日期訂為宣告 LTS 版本的三年後。 在 .NET Framework 上對 ASP.NET Core 2.1 套件的支援將無限延伸，類似於其他套件型 ASP.NET 架構的服務原則。

如需從 .NET Framework 移植到 .NET Core 的詳細資訊，請參閱移植到 .NET Core。

Microsoft.Extensions 套件 (例如記錄、相依性插入和設定) 和 Entity Framework Core 不會受到影響。 它們會繼續支援 .NET Standard。

如需此變更動機的詳細資訊，請參閱原始部落格文章。

導入的版本

3.0

舊的行為

ASP.NET Core 應用程式可執行於 .NET Core 或 .NET Framework。

新的行為

ASP.NET Core 應用程式只能在 .NET Core 上執行。

執行下列其中一項動作：

  • 將您的應用程式保留在 ASP.NET Core 2.1 上。
  • 將您的應用程式和相依性移轉至 .NET Core。

類別

ASP.NET Core

受影響的 API

無

Core .NET 程式庫

報告版本的 API 現在報告產品而不是檔案版本

許多在 .NET Core 中傳回版本的 API，現在會傳回產品版本，而不是檔案版本。

變更描述

在 .NET Core 2.2 和舊版本中，Environment.Version、RuntimeInformation.FrameworkDescription 之類的方法，以及 .NET Core 組件的檔案屬性對話方塊均反映檔案版本。 從 .NET Core 3.0 開始，會反映產品版本。

下圖說明在 .NET Core 2.2 (左側) 和 .NET Core 3.0 (右側) 中 System.Runtime.dll 組件的版本資訊差異，如 Windows 檔案總管的檔案屬性對話方塊所示。

產品版本資訊的差異

導入的版本

3.0

無。 這項變更應該讓版本偵測直覺化，而不是模糊化。

類別

Core .NET 程式庫

受影響的 API

自訂 EncoderFallbackBuffer 執行個體無法遞迴回復

自訂 EncoderFallbackBuffer 執行個體無法遞迴回復。 EncoderFallbackBuffer.GetNextChar() 的實作必須產生可以轉換成目的地編碼的字元序列。 否則，會擲回例外狀況。

變更描述

在字元到位元組轉碼作業期間，執行階段會偵測格式錯誤或無法轉換的 UTF-16 序列，並將這些字元提供給 EncoderFallbackBuffer.Fallback 方法。 Fallback 方法會決定哪些字元應該取代原始不可轉換的資料，而且這些字元會藉由在迴圈中呼叫 EncoderFallbackBuffer.GetNextChar 來清空。

執行階段接著會嘗試將這些替代字元轉碼為目標編碼。 如果此作業成功，執行階段會繼續從原始輸入字串離開的位置轉碼。

先前，EncoderFallbackBuffer.GetNextChar() 的自訂實作可以傳回無法轉換成目的地編碼的字元序列。 如果替代字元無法轉碼為目標編碼，則執行階段會使用替代字元再一次叫用 EncoderFallbackBuffer.Fallback 方法，期待 EncoderFallbackBuffer.GetNextChar() 方法傳回新的替代序列。 此程序會繼續執行，直到執行階段最終看到格式正確的可轉換替代，或直到達到最大遞迴計數為止。

從 .NET Core 3.0 開始，EncoderFallbackBuffer.GetNextChar() 的自訂實作必須傳回可以轉換成目的地編碼的字元序列。 如果替代字元無法轉碼為目標編碼，則會擲回 ArgumentException。 執行階段將不再遞迴呼叫 EncoderFallbackBuffer 執行個體。

只有在符合下列三個條件時，才會套用此行為：

  • 執行階段偵測到格式不正確的 UTF-16 序列或無法轉換成目標編碼的 UTF-16 序列。
  • 已指定自訂 EncoderFallback。
  • 自訂 EncoderFallback 嘗試取代新的格式錯誤或無法轉換的 UTF-16 序列。

導入的版本

3.0

大部分的開發人員不需要採取任何動作。

如果應用程式使用自訂 EncoderFallback 和 EncoderFallbackBuffer 類別，請確定 EncoderFallbackBuffer.Fallback 的實作會在執行階段第一次叫用 Fallback 方法時，以格式正確的 UTF-16 資料填入後援緩衝區，而這些資料可直接轉換成目標編碼。

類別

Core .NET 程式庫

受影響的 API

浮點格式化和剖析行為變更

浮點剖析和格式化行為 (依 Double 和 Single 型表) 現在符合 IEEE 規範。 這可確保 .NET 中浮點類型的行為符合其他 IEEE 相容語言的行為。 例如，double.Parse("SomeLiteral") 應該一律符合 C# 在 double x = SomeLiteral 中產生的內容。

變更描述

在 .NET Core 2.2 和舊版中，使用 Double.ToString 和 Single.ToString 進行格式化，以及使用 Double.Parse、Double.TryParse、Single.Parse 和 Single.TryParse 進行剖析，不符合 IEEE 規範。 因此，無法保證值會以任何支援標準或自訂格式字串來回往返。 在某些輸入中，剖析格式化值的嘗試可能會失敗，而在其他輸入中，剖析的值不等於原始值。

從 .NET Core 3.0 開始，浮點剖析和格式化作業均符合 IEEE 754 規範。

下表顯示兩個程式碼片段，以及 .NET Core 2.2 和 .NET Core 3.1 之間的輸出變更。

程式碼片段 .NET Core 2.2 上的輸出 .NET Core 3.1 上的輸出
Console.WriteLine((-0.0).ToString()); 0 0-
var value = -3.123456789123456789;
Console.WriteLine(value == double.Parse(value.ToString()));		 False True

如需詳細資訊，請參閱 .NET Core 3.0 中的浮點剖析和格式化改善部落格文章。

導入的版本

3.0

在 .NET Core 3.0 中的浮點剖析和格式化改善部落格文章的對現存程式碼的潛在影響一節中，建議如果您想要維持之前的行為，可以對程式碼做一些變更。

  • 對於格式化的某些差異，您可以藉由指定不同的格式字串，取得與先前行為相等的行為。
  • 對於剖析的差異，沒有任何機制可以回復為先前的行為。

類別

Core .NET 程式庫

受影響的 API

浮點剖析作業不再失敗或擲回 OverflowException

當浮點剖析方法所剖析字串的數值不屬於 Single 或 Double 浮點類型時，就不會再擲回 OverflowException 或傳回 false。

變更描述

在 .NET Core 2.2 和舊版中，Double.Parse 和 Single.Parse 方法會針對不屬於其各自類型範圍的值擲回 OverflowException。 Double.TryParse and Single.TryParse 方法會針對超出數值範圍的字串表示，傳回 false。

從 .NET Core 3.0 開始，在剖析超出範圍的數值字串時，Double.Parse、Double.TryParse、Single.Parse 和 Single.TryParse 方法不再失敗。 針對超過 Double.MaxValue 的值，Double 剖析方法會改為傳回 Double.PositiveInfinity，以及針對小於 Double.MinValue 的值，傳回 Double.NegativeInfinity。 同樣地，針對超過 Single.MaxValue 的值，Single 剖析方法會傳回 Single.PositiveInfinity，且針對小於 Single.MinValue 的值，傳回 Single.NegativeInfinity。

這項變更是為了遵守改善後的 IEEE 754:2008 規範。

導入的版本

3.0

這項變更可能會以下列兩種方式之一影響您的程式碼：

  • 您的程式碼取決於 OverflowException 的處理常式，在發生溢位時執行。 在此情況下，您應該移除 catch 陳述式並將任何必要的程式碼放置在 If 陳述式，測試 Double.IsInfinity 或 Single.IsInfinity 是否為 true。

  • 您的程式碼假設浮點值不是 Infinity。 在此情況下，您應該新增必要的程式碼，以檢查 PositiveInfinity 和 NegativeInfinity 的浮點值。

類別

Core .NET 程式庫

受影響的 API

InvalidAsynchronousStateException 移至另一個組件

InvalidAsynchronousStateException 類別已移動。

變更描述

在 .NET Core 2.2 和舊版中，InvalidAsynchronousStateException 類別位於 System.ComponentModel.TypeConverter 組件中。

從 .NET Core 3.0 開始，位於 System.ComponentModel.Primitives 組件中。

導入的版本

3.0

只有使用反映並呼叫 Assembly.GetType 之類的方法來載入 InvalidAsynchronousStateException，或假設該類型是在特定組件而多載 Activator.CreateInstance 的應用程式，才會受到這項變更的影響。 如果是這種情況，請更新方法呼叫中參考的組件，以反映該類型的新組件位置。

類別

Core .NET 程式庫

受影響的 API

無。

遵循 Unicode 指導方針，取代格式不正確的 UTF-8 位元組序列

當類別 UTF8Encoding 在位元組對字元轉碼作業期間遇到格式不正確的 UTF-8 位元組序列時，會將輸出字串中的該序列取代為 '�' (U+FFFD 替換字元) 字元。 .NET Core 3.0 不同於舊版的 .NET Core 和 .NET Framework，在轉碼作業期間會依照 Unicode 最佳做法來執行這項取代。

這是在 .NET 中改善 UTF-8 處理作業的巨大工作中的一部分，包括利用新的 System.Text.Unicode.Utf8 和 System.Text.Rune 類型。 UTF8Encoding 類型已獲得改善的錯誤處理機制，使其產生與新建立類型一致的輸出。

變更描述

從 .NET Core 3.0 開始，將位元組轉碼為字元時，UTF8Encoding 類別會依據 Unicode 最佳做法執行字元替代。 如需使用的替代機制說明，請參閱 The Unicode Standard, Version 12.0, Sec. 3.9 (PDF) 中標題為 U+FFFD Substitution of Maximal Subparts 的章節。

只有在輸入位元組序列包含格式不正確的 UTF-8 資料時，才會套用此行為。 此外，如果 UTF8Encoding 執行個體已使用 throwOnInvalidBytes: true 建構，UTF8Encoding 執行個體將會繼續擲回無效輸入，而不是執行 U+FFFD 取代。 如需 UTF8Encoding 建構函式的詳細資訊，請參閱 UTF8Encoding(Boolean, Boolean)。

下表說明此變更對 3 位元組無效輸入的影響：

格式不正確的 3 位元組輸入 .NET Core 3.0 之前的輸出 從 .NET Core 3.0 開始的輸出
[ ED A0 90 ] [ FFFD FFFD ] (2 字元輸出) [ FFFD FFFD FFFD ] (3 字元輸出)

根據前面連結的 Unicode 標準 PDF 所提供的表 3-9，3 字元輸出是慣用輸出。

導入的版本

3.0

開發人員無須採取任何動作。

類別

Core .NET 程式庫

受影響的 API

TypeDescriptionProviderAttribute 移至另一個組件

TypeDescriptionProviderAttribute 類別已移動。

變更描述

在 .NET Core 2.2 和舊版中，TypeDescriptionProviderAttribute 類別位於 System.ComponentModel.TypeConverter 組件中。

從 .NET Core 3.0 開始，會位於 System.ObjectModel 組件中。

導入的版本

3.0

只有使用反映並呼叫 Assembly.GetType 之類的方法來載入 TypeDescriptionProviderAttribute 類型，或假設該類型是在特定組件而多載 Activator.CreateInstance 的應用程式，才會受到這項變更的影響。 如果是這種情況，應更新方法呼叫中參考的組件，以反映該類型的新組件位置。

類別

Windows Forms

受影響的 API

無。

ZipArchiveEntry 不再處理項目大小不一致的封存

Zip 封存會在中央目錄和本機標頭中列出壓縮大小和未壓縮大小。 項目資料本身也會指出其大小。 在 .NET Core 2.2 和舊版中，一律不會檢查這些值的一致性。 從 .NET Core 3.0 開始，現在會檢查了。

變更描述

在 .NET Core 2.2 和舊版中，即使本機標頭與 zip 檔案的中央標頭不一致，ZipArchiveEntry.Open() 仍會成功。 即使資料長度超過中央目錄/本機標頭列出的未壓縮檔案大小，仍會解壓縮到壓縮資料串流的結尾為止。

從 .NET Core 3.0 開始，ZipArchiveEntry.Open() 方法會檢查本機標頭和中央標頭中項目的壓縮和未壓縮大小是否一致。 如果不一致，則在封存的本機標頭和/或資料描述項列出的大小與 zip 檔案的中央目錄不符時，方法會擲回 InvalidDataException。 讀取項目時，解壓縮的資料會截斷為標頭中列出的未壓縮檔案大小。

這項變更是為了確保 ZipArchiveEntry 可以正確表示其資料的大小，以及只讀取該資料量。

導入的版本

3.0

重新封裝任何出現這些問題的 zip 封存。

類別

Core .NET 程式庫

受影響的 API

FieldInfo.SetValue 擲回靜態、僅限 init 欄位的例外狀況

從 .NET Core 3.0 開始，當您嘗試藉由呼叫 InitOnly 來設定靜態 System.Reflection.FieldInfo.SetValue 欄位的值時，就會擲回例外狀況。

變更描述

在 .NET Framework 和 3.0 之前的 .NET Core 版本中，您可以藉由呼叫 System.Reflection.FieldInfo.SetValue 來設定靜態欄位的值，該值在初始化後即保持不變 (在 C# 中為唯讀)。 不過，以此方式設定這類欄位會導致無法預測以目標架構和最佳化設定為基礎的行為。

在 .NET Core 3.0 和更新版本中，當您在靜態 InitOnly 欄位上呼叫 SetValue 時，會擲回 System.FieldAccessException 例外狀況。

提示

InitOnly 欄位是只能在宣告時或在內含類別的建構函式中設定的欄位。 換句話說，它會在初始化之後保持不變。

導入的版本

3.0

在靜態建構函式中初始化靜態 InitOnly 欄位。 這同時適用於動態和非動態類型。

或者，您也可以從欄位中移除 FieldAttributes.InitOnly 屬性，然後呼叫 FieldInfo.SetValue。

類別

Core .NET 程式庫

受影響的 API

將 GroupCollection 傳遞至採用 IEnumerable<T> 的擴充方法必須消除岐義

在 GroupCollection 上呼叫採用 IEnumerable<T> 的擴充方法時，您必須使用轉換明確釐清該類型。

變更描述

從 .NET Core 3.0 開始，System.Text.RegularExpressions.GroupCollection 除了本身實作的其他類型外還會實作 IEnumerable<KeyValuePair<String,Group>>，包括 IEnumerable<Group>。 在呼叫採用 IEnumerable<T> 的擴充方法時，這會導致模棱兩可。 如果您在 GroupCollection 執行個體上呼叫這類擴充方法，例如 Enumerable.Count，則會看到下列編譯器錯誤：

CS1061：'GroupCollection' 不包含 'Count' 的定義，而且也找不到可存取的擴充方法 'Count' 來接受類型 'GroupCollection' 的第一個引數 (您是否遺漏了 using 指示詞或組件參考？)

在舊版的 .NET 中，沒有模棱兩可且沒有編譯器錯誤。

導入的版本

3.0

變更原因

這是意外的中斷性變更。 由於它像這樣已有一段時間，所以我們不打算還原它。 此外，這類變更本身會造成中斷。

針對 GroupCollection 執行個體，使用轉換釐清接受 IEnumerable<T> 的擴充方法呼叫。

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

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

類別

Core .NET 程式庫

受影響的 API

任何接受 IEnumerable<T> 的擴充方法都會受到影響。 例如：

密碼編譯

已不再對 Linux 的根憑證支援 "BEGIN TRUSTED CERTIFICATE" 語法

Linux 和其他類似 Unix 系統 (不包括 macOS) 上的根憑證，可用兩種形式呈現：標準 BEGIN CERTIFICATE PEM 標頭和 OpenSSL 專用的 BEGIN TRUSTED CERTIFICATE PEM 標頭。 後者的語法允許會導致出現 .NET Core System.Security.Cryptography.X509Certificates.X509Chain 類別相容性問題的其他設定。 從 .NET Core 3.0 開始的鏈結引擎，已不再載入 BEGIN TRUSTED CERTIFICATE 根憑證內容。

變更描述

先前使用 BEGIN CERTIFICATE 和 BEGIN TRUSTED CERTIFICATE 語法，填入根信任清單。 如果先前使用 BEGIN TRUSTED CERTIFICATE 語法，且在檔案中也指定了其他選項，則 X509Chain 可能會回報明確地不允許鏈結信任 (X509ChainStatusFlags.ExplicitDistrust)。 不過，如果在指定了該憑證的同時，先前載入的檔案中有 BEGIN CERTIFICATE 語法，則允許該鏈結信任。

從 .NET Core 3.0 開始，將不再讀取 BEGIN TRUSTED CERTIFICATE 內容。 如果憑證也不是透過標準 BEGIN CERTIFICATE 語法指定，則 X509Chain 會回報該根目錄不受信任 (X509ChainStatusFlags.UntrustedRoot)。

導入的版本

3.0

大部分的應用程式都未受到這項變更的影響，但應用程式因為權限問題而讓看不到這兩個根憑證來源，可能會導致在升級之後，出現非預期的 UntrustedRoot 錯誤。

許多 Linux 散發套件 (或散發版本) 都會將根憑證寫入兩個位置：每個檔案各一憑證的目錄，以及單一檔案的串連。 在某些散發版本上，每個檔案各一憑證的目錄，會使用 BEGIN TRUSTED CERTIFICATE 語法，而檔案串連則使用標準 BEGIN CERTIFICATE 語法。 請確定至少在其中一個位置，有任一自訂根憑證已新增為 BEGIN CERTIFICATE，而且您的應用程式可以讀取這兩個位置。

一般目錄是 /etc/ssl/certs/，而一般的串連檔案是 /etc/ssl/cert.pem。 使用命令 openssl version -d 可判斷平台專用的根目錄 (可能與 /etc/ssl/不同)。 例如，在 Ubuntu 18.04 上，目錄是 /usr/lib/ssl/certs/，而檔案是 /usr/lib/ssl/cert.pem。 不過，/usr/lib/ssl/certs/ 是 /etc/ssl/certs/ 的符號連結，而 /usr/lib/ssl/cert.pem 不存在。

$ 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

類別

密碼編譯

受影響的 API

EnvelopedCms 預設為 AES-256 加密

EnvelopedCms 所使用的預設對稱加密演算法，已從 TripleDES 變更為 AES-256。

變更描述

在舊版中，若使用 EnvelopedCms 加密資料，而不透過建構函式多載指定對稱加密演算法時，會使用 TripleDES/3DES/3DEA/DES3-EDE 演算法來加密資料。

從 .NET Core 3.0 開始 (透過 System.Security.Cryptography.Pkcs NuGet 套件的 4.6.0 版)，預設演算法已變更為 AES-256，以使用現代化的演算法，並改善預設選項的安全性。 如果郵件收件者憑證有 (非 EC) Diffie-Hellman 公開金鑰，則加密作業會因為基礎平台的限制而失敗，並出現 CryptographicException。

在下列範例程式碼中，如果執行於 .NET Core 2.2 或更早版本上，則會以 TripleDES 加密資料。 如果執行於 .NET Core 3.0 或更新版本上，則會使用 AES-256 加密。

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

導入的版本

3.0

如果受到這項變更的負面影響，您可以在包含類型 AlgorithmIdentifier 參數的 EnvelopedCms 建構函式中，明確地指定加密演算法識別碼，以還原 TripleDES 加密，例如：

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();

類別

密碼編譯

受影響的 API

RSAOpenSsl 金鑰產生的大小下限已加大

在 Linux 上產生新 RSA 金鑰的大小下限，已從 384 位元增加到 512 位元。

變更描述

從 .NET Core 3.0 開始，來自 Linux 上 RSA.Create、RSAOpenSsl 和 RSACryptoServiceProvider 之 RSA 執行個體 LegalKeySizes 屬性，所回報的合法金鑰大小下限，已從 384 加大到 512。

因此，在 .NET Core 2.2 和更舊的版中，RSA.Create(384) 之類的方法呼叫會成功。 在 .NET Core 3.0 和更新版本中，方法呼叫 RSA.Create(384) 會擲回例外狀況，指出大小太小。

這項變更是因為在 Linux 上執行密碼編譯作業的 OpenSSL，在 1.0.2 版和 1.1.0 版之間，提高了其最小值。 .NET Core 3.0 會優先選擇 OpenSSL 1.1.x 而非 1.0.x，並會提高回報的最低版本，以反映出這個新的相依性限制提高的情況。

導入的版本

3.0

如果要呼叫任一受影響的 API，請確定任何所產生的金鑰大小，都不會小於提供者的最小值。

注意

384 位元 RSA 已被視為不安全 (如 512 位元 RSA)。 針對新式的建議，例如 NIST 特殊出版物 800-57 第 1 部分修訂 4 (英文)，建議以 2048 位元作為新產生金鑰的大小下限。

類別

密碼編譯

受影響的 API

.NET Core 3.0 會優先選擇 OpenSSL 1.1.x 而非 OpenSSL 1.0.x

適用於 Linux 的 .NET Core 可跨多個 Linux 發行版本運作，並同時支援 OpenSSL 1.0.x 和 OpenSSL 1.1.x。 .NET Core 2.1 和 .NET Core 2.2 會先尋找 1.0.x，然後回復為 1.1.x；.NET Core 3.0 則會先尋找 1.1.x。 進行這項變更，是為了加入對全新密碼編譯標準的支援。

這項變更會影響在 .NET Core 中，以 OpenSSL 專用 Interop 類型，與平台進行 Interop 的程式庫或應用程式。

變更描述

在 .NET Core 2.2 和舊版中，執行階段會優先載入 OpenSSL 1.0.x，而非 1.1.x。 這表示與 OpenSSL 進行 Interop 的 IntPtr 和 SafeHandle 類型，會選擇搭配 1.0.0 / libcrypto.so.1.0 / libcrypto.so.10 使用。

從 .NET Core 3.0 開始，執行階段會優先載入 OpenSSL 1.1.x (而非 OpenSSL 1.0.x)，讓與 OpenSSL 進行 Interop 的類型 IntPtr 和 SafeHandle，會選擇搭配 libcrypto.so.1.1 / libcrypto.so.11 / libcrypto.so.1.1.0 / libcrypto.so.1.1.1 使用。 因此，從 .NET Core 2.1 或 .NET Core 2.2 升級時，直接與 OpenSSL 進行交互作業的程式庫和應用程式，可能會有與 .NET Core 公開值不相容的指標。

導入的版本

3.0

對 OpenSSL 進行直接作業的程式庫和應用程式，必須非常注意，要確保它們使用與 .NET Core 執行階段相同的 OpenSSL 版本。

直接使用 OpenSSL 的所有程式庫或應用程式，若使用的 IntPtr 或 SafeHandle 值取自 .NET Core 密碼編譯類型，則應比較使用的程式庫版本與新的 SafeEvpPKeyHandle.OpenSslVersion 屬性，以確保指標相容。

類別

密碼編譯

受影響的 API

CryptoStream.Dispose 只有在寫入時，才會轉換最終區塊

來完成 CryptoStream 作業的 CryptoStream.Dispose 方法，不會再嘗試於讀取時，轉換最終區塊。

變更描述

在舊版 .NET 中，如果使用者在模式 Read 下使用 CryptoStream 執行不完整的讀取時，Dispose 方法可能會擲回例外狀況 (例如，填補時使用 AES)。 因為嘗試轉換最終區塊，但資料不完整，因此擲回例外狀況。

在 .NET Core 3.0 和更新版本中，Dispose 已不會在讀取時嘗試轉換最終區塊 (這會導致讀取不完整)。

變更原因

這項變更會在取消網路作業時，讓從密碼編譯串流進行的讀取，變得不完整，而不需要攔截例外狀況。

導入的版本

3.0

大部分的應用程式應不會受到這項變更的影響。

如果您的應用程式先前會在讀取不完整時，攔截到例外狀況，可以刪除該 catch 區塊。 如果您的應用程式在雜湊案例中，使用了轉換最終區塊，可能需要先確定已讀取了整個串流，然後再加以處置。

類別

密碼編譯

受影響的 API

Entity Framework Core

Entity Framework Core 中斷性變更

全球化

"C" 地區設定表示不因地區設定而異

.NET Core 2.2 和舊版相依於預設的 ICU 行為，該行為會將 "C" 地區設定對應至 en_US_POSIX 地區設定。 en_US_POSIX 地區設定不支援不區分大小寫的字串比較，因此會有不需要的定序行為。 由於某些 Linux 發行版本會將 "C" 地區設定設為預設地區設定，因此使用者會遇到非預期行為。

變更描述

從 .NET Core 3.0 開始，"C" 地區設定對應已變更為使用非變異地區設定，而不是 en_US_POSIX。 為了保持一致，"C" 地區設定的非變異對應也會套用至 Windows。

將 "C" 對應至 en_US_POSIX 文化特性會造成客戶混淆，因為 en_US_POSIX 不支援不區分大小寫排序/搜尋字串作業。 由於某些 Linux 散發版使用 "C" 地區設定作為預設地區設定，造成客戶在這些作業系統上遇到這項不必要的行為。

導入的版本

3.0

對使用者來說，這項變更最明確具體。 這項變更只會影響使用 "C" 地區設定對應的應用程式。

類別

全球化

受影響的 API

所有定序和文化特性 API 都會受到這項變更的影響。

MSBuild

資源資訊清單檔名稱變更

從 .NET Core 3.0 開始，在預設案例中，MSBuild 會為資源檔產生不同的資訊清單檔名稱。

導入的版本

3.0

變更描述

在 .NET Core 3.0 之前，如果並未對專案檔中的 EmbeddedResource 項目指定 LogicalName、ManifestResourceName 或 DependentUpon 中繼資料，MSBuild 就會在模式 <RootNamespace>.<ResourceFilePathFromProjectRoot>.resources 中產生資訊清單檔名稱。 如果未在專案檔中定義 RootNamespace，則這會預設為專案名稱。 例如，對於根專案目錄中名為 Form1.resx 的資源檔產生的資訊清單名稱是 MyProject.Form1.resources。

從 .NET Core 3.0 開始，如果資源檔與相同名稱的來源檔案共置 (例如 Form1.resx 和 Form1.cs)，MSBuild 會使用來源檔案中的型別資訊，在模式 <Namespace>.<ClassName>.resources 中產生資訊清單檔名稱。 命名空間和類別名稱是從共置原始程式檔的第一個型別擷取。 例如，對於與名為 Form1.cs 的來源檔案共置而且名為 Form1.resx 的資源檔，產生的資訊清單名稱是 MyNamespace.Form1.resources。 請注意，檔案名稱的第一個部分不同於舊版 .NET Core (MyNamespace 而非 MyProject)。

注意

如果您在專案檔中的 EmbeddedResource 項目上指定 LogicalName、ManifestResourceName 或 DependentUpon 中繼資料，則這項變更不會影響該資源檔。

此中斷性變更是透過將 EmbeddedResourceUseDependentUponConvention 屬性新增至 .NET Core 專案而進行。 根據預設，資源檔不會明確列在 .NET Core 專案檔中，因此沒有 DependentUpon 中繼資料可指定如何命名產生的 .resources 檔案。 EmbeddedResourceUseDependentUponConvention 設定為 true 時，這是預設值，MSBuild 會尋找共置的來源檔案，並從該檔案擷取命名空間和類別名稱。 如果您設定 EmbeddedResourceUseDependentUponConvention 為 false，MSBuild 會根據先前的行為產生資訊清單名稱，這會合併 RootNamespace 和相對檔案路徑。

在大部分情況下，開發人員不需要採取任何動作，您的應用程式應該會繼續運作。 不過，如果這項變更中斷您的應用程式，您可以：

  • 將您的程式碼變更為預期新的資訊清單名稱。

  • 在專案檔中將 EmbeddedResourceUseDependentUponConvention 設定為 false，以退出新的命名慣例。

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

類別

MSBuild

受影響的 API

N/A

網路

HttpRequestMessage.Version 的預設值已變更為 1.1

System.Net.Http.HttpRequestMessage.Version 屬性的預設值已從 2.0 變更為 1.1。

導入的版本

3.0

變更描述

從 .NET Core 1.0 到 2.0，System.Net.Http.HttpRequestMessage.Version 屬性的預設值為 1.1。 自 .NET Core 2.1 起，該值已變更為 2.1。

自 .NET Core 3.0 起，System.Net.Http.HttpRequestMessage.Version 屬性傳回的預設版本號碼再次為 1.1。

若其 System.Net.Http.HttpRequestMessage.Version 屬性傳回預設值 2.0，請更新程式碼。

類別

網路

受影響的 API

WPF

在文字編輯器上改變拖放行為

.NET Core 3.0 引進了文本編輯器控件在將文字拖曳至另一個控件時建立 System.Windows.DataObject 的變更。 變更已停用自動轉換，導致作業將資料保留為 DataFormats.Text 或 DataFormats.UnicodeText ，而不是將它 DataFormats.StringFormat轉換成 。

導入的版本

.NET Core 3.0

類別

Windows Presentation Foundation

先前的行為

從文字編輯器控制器拖曳文字時的資料類型 System.Windows.DataObject 為 DataFormats.StringFormat。

新的行為

從文字編輯器控制器拖曳文字時的資料類型 System.Windows.DataObject 為 DataFormats.Text 或 DataFormats.UnicodeText。

中斷性變更的類型

此變更為行為變更。

變更原因

變更是無意的。

這項變更已在 .NET 7 中還原。 升級至 .NET 7 或更新版本。

受影響的 API

另請參閱