將移轉至 .NET Framework 4.5.x 的重定目標變更

發行項
03/09/2024

本文列出 .NET Framework 4.5、4.5.1 和 4.5.2 中介紹的應用程式相容性問題。

.NET Framework 4.5

ASP.NET

MachineKey.Encode 和 MachineKey.Decode 方法現在已淘汰

詳細資料

這些方法現在已經過時。編譯呼叫這些方法的程式碼會產生編譯器警告。

建議

建議的替代方式為 Protect(Byte[], String[]) 和 Unprotect(Byte[], String[])。或者，您也可以隱藏建置警告，或使用舊版編譯器以避免出現警告。這些 API 仍受到支援。

名稱	值
範圍	Minor
版本	4.5
類型	正在重定目標

受影響的 API

使用 AntiXSSEncoder 時，多行 ASP.NET TextBox 間距已變更

詳細資料

在 .NET Framework 4.0 中，如果使用 System.Web.Security.AntiXss.AntiXssEncoder，則會在回傳時，於多行文字方塊的行間插入額外幾行。在 .NET Framework 4.5 中，不會包含這些額外的分行符號，但前提是 Web 應用程式是以 .NET Framework 4.5 為目標

建議

請注意，重定目標為 .NET Framework 4.5 的 4.0 版 Web 應用程式可能已改善多行文字方塊，不再插入額外的分行符號。如果不想這麼做，在 .NET Framework 4.5 上執行的應用程式可藉由將目標設為 .NET Framework 4.0 來保留舊版行為。

名稱	值
範圍	Minor
版本	4.5
類型	正在重定目標

WebUtility.HtmlEncode 和 WebUtility.HtmlDecode 正確地反覆存取 BMP

詳細資料

若是目標為 .NET Framework 4.5 的應用程式，當 Basic Multilingual Plane (BMP) 以外的字元傳遞至 HtmlDecode(String) 方法時，會正確地來回轉譯。

建議

這項變更應該不會影響目前的應用程式，但若要還原原始行為，請將 <httpRuntime> 元素的 targetFramework 屬性設為 "4.5" 以外的字串。您也可以設定 unicodeEncodingConformance 組態項目的 unicodeDecodingConformance 和 <webUtility> 屬性，以與目標 .NET Framework 版本不相關的方式控制這個行為。

名稱	值
範圍	Edge
版本	4.5
類型	正在重定目標

受影響的 API

ClickOnce

透過 ClickOnce 發行的應用程式，這些應用程式使用可能會在 Windows 2003 上失敗的 SHA-256 程式碼簽署憑證

詳細資料

這個可執行檔使用 SHA256 簽署。之前，不論程式碼簽署憑證為 SHA-1 或 SHA-256，都會使用 SHA1 簽署。這適用於：

使用 Visual Studio 2012 (含) 以後版本建置的所有應用程式。
使用 Visual Studio 2010 (含) 以前版本，在具有 .NET Framework 4.5 的系統上建置應用程式。此外，如果有 .NET Framework 4.5 (含) 以後版本，也會針對 SHA-256 憑證使用 SHA-256 來簽署 ClickOnce 資訊清單，而不論編譯的 .NET Framework 版本為何。

建議

對簽署 ClickOnce 可執行檔所做的變更只會影響 Windows Server 2003 系統；這些變更需要安裝 KB 938397。對使用 SHA-256 簽署資訊清單所做的變更還會引進 .NET Framework 4.5 (含) 以後版本的執行階段相依性，即使應用程式是以 .NET Framework 4.0 (含) 以前版本為目標亦然。

名稱	值
範圍	Edge
版本	4.5
類型	正在重定目標

核心

Foreach 迭代器變數的範圍現在會設定為在反覆項目內，因此關閉擷取語意不同 (在 C#5 中)

詳細資料

從 C# 5 (Visual Studio 2012) 開始，foreach 迭代器變數的範圍會設定為在反覆項目內。如果程式碼之前需要這些變數才不會包含在 foreach 的關閉中，這可能會導致中斷。這項變更的徵兆是傳遞至委派的迭代器變數會視為建立委派時所具有的值，而不是叫用委派時所具有的值。

建議

在理想情況下，您應該更新程式碼，以確保此新的編譯器行為。如果需要舊版語意，您可以將此迭代器變數取代成明確放在迴圈範圍外的不同變數。

名稱	值
範圍	主修
版本	4.5
類型	正在重定目標

IAsyncResult.CompletedSynchronously 屬性必須正確，產生的工作才能完成

詳細資料

呼叫 TaskFactory.FromAsync 時，CompletedSynchronously 屬性的實作必須正確，產生的工作才能完成。也就是說，只有在實作同步完成時，屬性才必須傳回 true。以往不會檢查屬性。

建議

如果 System.IAsyncResult 實作只在工作同步完成時，才針對 System.IAsyncResult.CompletedSynchronously 屬性正確地傳回 true，則不會觀察到中斷情況。使用者應檢閱其擁有的 System.IAsyncResult 實作 (如果有的話)，以確保正確評估工作是否同步完成。

名稱	值
範圍	Edge
版本	4.5
類型	正在重定目標

受影響的 API

修改清單項目時，List<T>.ForEach 可能會擲回例外狀況

詳細資料

從 .NET Framework 4.5 開始，如果呼叫集合中有任何項目遭到修改，ForEach(Action<T>) 列舉程式將會擲回 System.InvalidOperationException 例外狀況。之前，這不會擲回例外狀況，但可能會造成競爭情形。

建議

在理想情況下，您應該修正程式碼，不要在列舉其項目時修改清單，因為這絕不是安全的作業。不過，若要還原成舊版行為，應用程式可以將目標設為 .NET Framework 4.0。

名稱	值
範圍	Edge
版本	4.5
類型	正在重定目標

受影響的 API

List<T>.ForEach(Action<T>)

System.Uri 剖析遵守 RFC 3987

詳細資料

URI 剖析在 .NET Framework 4.5 中已做了幾項變更。不過請注意，這些變更只會影響以 .NET Framework 4.5 為目標的程式碼。如果某個二進位檔是以 .NET Framework 4.0 為目標，則會遵守舊版行為。 .NET Framework 4.5 中的 URI 剖析變更包括：

URI 剖析將會根據 RFC 3987 中最新的 IRI 規則來執行正規化和字元檢查。
只會在 URI 的主機部分執行 Unicode 正規化格式 C。
無效的 mailto: URI 現在會造成例外狀況。
現在會保留路徑線段結尾的後置點。
file:// URI 不會逸出 ? 字元。
不支援 Unicode 控制字元 U+0080 至 U+009F。
逗號字元 , 或 %2c 不會自動設為未逸出。

建議

如果需要舊版 .NET Framework 4.0 URI 剖析語意 (通常不需要)，藉由設定 .NET Framework 4.0 目標即可使用。您可以在組件上使用 System.Runtime.Versioning.TargetFrameworkAttribute，或透過 Visual Studio 專案系統 UI 的 [專案屬性] 頁面來完成此作業。

名稱	值
範圍	主修
版本	4.5
類型	正在重定目標

受影響的 API

System.Uri.IsWellFormedUriString 方法針對第一個區段中有冒號字元的相對 URI 會傳回 false

詳細資料

從 .NET Framework 4.5 開始，IsWellFormedUriString(String, UriKind) 會將第一個區段中具有 : 的相對 URI 視為格式不正確。這是 .NET Framework 4.0 System.Uri.IsWellFormedUriString(String, UriKind) 行為的變更，以符合 RFC3986。

建議

這項變更 (就像許多其他的 URI 變更一樣) 只會影響以 .NET Framework 4.5 (或更新版本) 為目標的應用程式。若要繼續使用舊的行為，請將應用程式設為以 .NET Framework 4.0 為目標。或者，在呼叫 System.Uri.IsWellFormedUriString(String, UriKind) 前掃描 URI，尋找 : 字元，如果您偏好舊的行為，則請移除字元以進行驗證。

名稱	值
範圍	Minor
版本	4.5
類型	正在重定目標

受影響的 API

Uri.IsWellFormedUriString(String, UriKind)

Entity Framework

Entity Framework 版本必須符合 .NET Framework 版本

詳細資料

Entity Framework (EF) 版本應該符合 .NET Framework 版本。建議針對 .NET Framework 4.5 使用 Entity Framework 5。 .NET Framework 4.5 專案中，已知 EF 4.x 有一些 System.ComponentModel.DataAnnotations 相關問題。在 .NET Framework 4.5，這些已移至不同的組件，因此決定要使用哪些註解時會有問題。

建議

針對 .NET Framework 4.5 升級至 Entity Framework 5

名稱	值
範圍	主修
版本	4.5
類型	正在重定目標

Windows Forms

EncoderParameter ctor 已淘汰

詳細資料

EncoderParameter(Encoder, Int32, Int32, Int32, Int32) 建構函式現在已淘汰，如果使用，就會產生建置警告。

建議

雖然 EncoderParameter(Encoder, Int32, Int32, Int32, Int32) 建構函式會繼續運作，但應改用下列建構函式，以避免使用 .NET Framework 4.5 工具重新編譯程式碼時出現已淘汰的建置警告：EncoderParameter(Encoder, Int32, EncoderParameterValueType, IntPtr)。

名稱	值
範圍	Minor
版本	4.5
類型	正在重定目標

受影響的 API

EncoderParameter(Encoder, Int32, Int32, Int32, Int32)

Windows Communication Foundation (WCF)

使用 BodyWriter 撰寫二進位輸出

詳細資料

如果您從類別 System.ServiceModel.Channels.BodyWriter 衍生並使用 OnWriteBodyContents(XmlDictionaryWriter writer) 的實作來撰寫二進位輸出，則當您將 .NET Framework 4.5 重定時，可能需要進行一些變更。檢查寫入狀態，如果是 WriterState.Start，請發出 Binary 包裝 XML 元素，如下列程式碼片段所示。

protected override void OnWriteBodyContents(XmlDictionaryWriter writer)
{
    bool wroteStartElement = false;
    if (writer.WriteState == WriteState.Start)
    {
        writer.WriteStartElement("Binary", string.Empty);
        wroteStartElement = true;
    }
    writer.WriteBase64(buffer, offset, count);
    if (wroteStartElement)
    {
        writer.WriteEndElement();
    }
}

此外，如果您從 System.ServiceModel.Channels.StreamBodyWriter 類別衍生並覆寫了方法 OnWriteBodyContents(XmlDictionaryWriter writer)，則可能需要進行一些變更。以 .NET Framework 4.0 為目標時，覆寫此方法時必須明確寫入 Binary 元素。當您以 .NET Framework 4.5 為目標時，不再需要這麼做，因此這樣會導致無法寫入主體。

Windows Presentation Foundation (WPF)

WPF TextBox.Text 可能與資料繫結不同步

詳細資料

在某些情況下，如果屬性在資料繫結寫入作業期間經過修改，Text 屬性會反映資料繫結屬性值先前的值。

建議

這應該不會產生負面影響。不過，您可以藉由將 KeepTextBoxDisplaySynchronizedWithTextProperty 屬性設為 false 還原舊有行為。

	值
範圍	Edge
版本	4.5
類型	正在重定目標

受影響的 API

TextBox.Text

Windows Workflow Foundation (WF)

新的 (模稜兩可的) Dispatcher.Invoke 多載可能會導致不同的行為

詳細資料

.NET Framework 4.5 將包含 Action 類型參數的多載新增至 Dispatcher.Invoke。重新編譯現有的程式碼時，編譯器可能會將呼叫解析為具有 Delegate 參數的 Dispatcher.Invoke 方法，就像呼叫具有 Action 參數的 Dispatcher.Invoke 方法。如果將具有 Delegate 參數的 Dispatcher.Invoke 多載呼叫解析成具有 Action 參數的 Dispatcher.Invoke 多載呼叫，則可能會出現下列行為的差異：

如果發生例外狀況，則不會引發 UnhandledExceptionFilter 和 UnhandledException 事件。而是由 System.Threading.Tasks.TaskScheduler.UnobservedTaskException 事件處理例外狀況。
對某些成員 (例如 Result) 的呼叫會遭到封鎖，直到作業完成為止。

建議

若要避免模稜兩可的情況 (以及例外狀況處理或封鎖行為上的可能差異)，呼叫 Dispatcher.Invoke 的程式碼可以傳遞空的 object[] 作為 Invoke 呼叫的第二個參數，以確定解析為 .NET Framework 4.0 方法多載。

名稱	值
範圍	Minor
版本	4.5
類型	正在重定目標

受影響的 API

某些工作流程拖放 API 已淘汰

詳細資料

此工作流程拖放 API 已淘汰；如果針對 4.5 重建應用程式，就會產生編譯器警告。

建議

您應該改用支援操作多個物件的新 System.Activities.Presentation.DragDropHelper API。或者，您也可以隱藏建置警告，或使用舊版編譯器以避免出現警告。這些 API 仍受到支援。

名稱	值
範圍	Minor
版本	4.5
類型	正在重定目標

受影響的 API

WorkFlow 3.0 類型已淘汰

詳細資料

Windows Workflow Foundation (WWF) 3.0 API (System.Workflow 命名空間中的 API) 現在已淘汰。

建議

您應該改用新的 WWF 4.0 API (在 System.Activities 中)。您可以在這裡找到使用新 API 的範例，並在這裡取得進一步指引。此外，由於仍然支援 WWF 3.0 API，因此可使用這些 API，並藉由隱藏建置階段警告或使用舊版編譯器來避免出現警告。

名稱	值
範圍	主修
版本	4.5
類型	正在重定目標

WorkflowDesigner.Load 不會移除符號屬性

詳細資料

如果工作流程設計工具是以 .NET Framework 4.5 為目標，並使用 Load() 方法載入重新裝載的 3.5 工作流程，則會在儲存工作流程時擲回 System.Xaml.XamlDuplicateMemberException。

建議

只有在工作流程設計工具是以 .NET Framework 4.5 為目標時才會出現此錯誤 (bug)，因此可藉由將 WorkflowDesigner.Context.Services.GetService<DesignerConfigurationService>().TargetFrameworkName 設定為 .NET Framework 4.0 來解決。

或者，使用 Load(String) 方法 (而非 Load()) 來載入工作流程，以避免此問題。

名稱	值
範圍	主修
版本	4.5
類型	正在重定目標

受影響的 API

WorkflowDesigner.Load()

XML、XSLT

XML 結構描述驗證更嚴格

詳細資料

在 .NET Framework 4.5 中，XML 結構描述驗證更為嚴格。如果您使用 xsd:anyURI 驗證 URI (例如 mailto 通訊協定)，而 URI 中有空格，則驗證會失敗。在舊版 .NET Framework 中，驗證會成功。這項變更只會影響以 .NET Framework 4.5 為目標的應用程式。

建議

如果需要較鬆散的 .NET Framework 4.0 驗證，正在驗證的應用程式可以將目標設為 .NET Framework 4.0 版。不過，將目標重定為 .NET Framework 4.5 時，應該完成程式碼檢閱，以確定無效的 URI (含空格) 不會作為 anyURI 資料類型的屬性值。

名稱	值
範圍	Minor
版本	4.5
類型	正在重定目標

.NET Framework 4.5.1

ADO.NET

DbParameter.Precision 和 DbParameter.Scale 現在是公用虛擬成員

詳細資料

Precision 和 Scale 會當做公用虛擬屬性來實作。這些屬性取代對應的明確介面實作 IDbDataParameter.Precision 和 IDbDataParameter.Scale。

建議

重建 ADO.NET 資料庫提供者時，這些差異會要求將 'override' 關鍵字套用至 Precision 和 Scale 屬性。只有在重建元件時才需要這樣做；現有的二進位檔將繼續運作。

名稱	值
範圍	Minor
版本	4.5.1
類型	正在重定目標

受影響的 API

核心

ObsoleteAttribute 會在 WinMD 案例中匯出為 ObsoleteAttribute 和 DeprecatedAttribute

詳細資料

當您建立 Windows 中繼資料庫 (.winmd 檔案) 時，System.ObsoleteAttribute 屬性會匯出為 System.ObsoleteAttribute 和 Windows.Foundation.DeprecatedAttribute。

建議

重新編譯使用 System.ObsoleteAttribute 屬性的現有來源程式碼，可能會在從 C++/CX 或 JavaScript 使用該程式碼時產生警告。我們不建議您在受控組件中同時套用 System.ObsoleteAttribute 和 Windows.Foundation.DeprecatedAttribute，這樣可能會導致建置警告。

名稱	值
範圍	Edge
版本	4.5.1
類型	正在重定目標

Entity Framework

如果使用 EntityDeploySplit 或 EntityClean 工作，以 Visual Studio 2013 建置 Entity Framework edmx 可能會失敗，並出現錯誤 MSB4062

詳細資料

MSBuild 12.0 工具 (隨附於 Visual Studio 2013) 已變更 MSBuild 檔案位置，導致舊版 Entity Framework 的目標檔案無效。結果是 EntityDeploySplit 和 EntityClean 工作會失敗，因為找不到 Microsoft.Data.Entity.Build.Tasks.dll。請注意，造成此中斷的原因是工具組 (MSBuild/VS) 變更，而不是 .NET Framework 變更。只有在升級開發人員工具時才會發生此情況，若只是升級 .NET Framework 則不會發生。

建議

Entity Framework 的目標檔案已修正，從 .NET Framework 4.6 開始，可搭配新的 MSBuild 配置使用。升級至該版 Framework 將會修正此問題。或者，您也可以使用此因應措施來直接修補目標檔案。

名稱	值
範圍	主修
版本	4.5.1
類型	正在重定目標

MSBuild

ResolveAssemblyReference 工作現在會發出警告，指出相依於錯誤的架構

詳細資料

這項工作會發出警告 MSB3270，指出某個參考或參考的任何一個相依性不符合應用程式的架構。例如，如果使用 AnyCPU 選項編譯的應用程式包含 x86 參考，則會發生此情況。這類情況會導致應用程式在執行階段失敗 (在本範例中，如果應用程式部署為 x64 處理序)。

建議

影響可分為下列兩方面：

重新編譯會產生在舊版 MSBuild 下編譯應用程式時未顯示的警告。不過，由於此警告識別執行階段失敗的可能來源，因此應該加以調查和解決。
如果將警告視為錯誤，應用程式將無法編譯。

名稱	值
範圍	Minor
版本	4.5.1
類型	正在重定目標

Windows Presentation Foundation (WPF)

不支援具有非公用 setter 之屬性的雙向資料繫結

詳細資料

嘗試將資料繫結至不含公用 setter 的屬性，是之前從未支援過的情況。從 .NET Framework 4.5.1 開始，這種情況將會擲回 System.InvalidOperationException。請注意，只有專門以 .NET Framework 4.5.1 為目標的應用程式才會擲回此新的例外狀況。如果應用程式是以 .NET Framework 4.5 為目標，則會允許此呼叫。如果應用程式未以特定 .NET Framework 版本為目標，則會將繫結視為單向。

建議

您應該更新應用程式以使用單向繫結，或以公用方式公開屬性的 setter。此外，以 .NET Framework 4.5 為目標也會使應用程式展示舊版行為。

名稱	值
範圍	Minor
版本	4.5.1
類型	正在重定目標

受影響的 API

BindingMode.TwoWay

.NET Framework 4.5.2

Visual Basic .NET

VB.NET 不再支援 System.Windows API 的部分命名空間限定性條件

詳細資料

從 .NET Framework 4.5.2 開始，VB.NET 專案無法以部分限定的命名空間來指定 System.Windows API。例如，參考 Windows.Forms.DialogResult 將會失敗。相反地，程式碼必須參考完整名稱 (DialogResult)，或匯入特定命名空間並只參考 System.Windows.Forms.DialogResult。

建議

您應該更新程式碼，以簡單名稱 (並匯入相關命名空間) 或完整名稱參考 System.Windows API。

名稱	值
範圍	Minor
版本	4.5.2
類型	正在重定目標

Windows Forms

DataObject.GetData 現在會以 UTF-8 形式來擷取資料

詳細資料

若為以 .NET Framework 4.5.1 為目標的應用程式，或者在 .NET Framework 4.5.1 或舊版上執行的應用程式，DataObject.GetData 會以 ASCII 字串形式來擷取 HTML 格式的資料。因此，非 ASCII 字元 (ASCII 碼大於 0x7F 的字元) 會以兩個隨機字元表示。

若為以 .NET Framework 4.5 或更新版本為目標並且在 .NET Framework 4.5.2 上執行的應用程式，DataObject.GetData 會以 UTF-8 形式來擷取 HTML 格式的資料，以正確地表示大於 0x7F 的字元。

建議

如果針對 HTML 格式字串的編碼問題實作了因應措施 (例如將從 [剪貼簿] 擷取的 HTML 字串傳遞至 System.Text.UTF8Encoding.GetString(Byte[], Int32, Int32) 以明確將其編碼)，並將目標從應用程式 4 版重定為 4.5 版，則應該移除該因應措施。如果因故需要舊版行為，應用程式可以將目標設為 .NET Framework 4.0 來取得該行為。

名稱	值
範圍	Edge
版本	4.5.2
類型	正在重定目標

受影響的 API

Windows Workflow Foundation (WF)

WorkflowDesigner.Load 不會移除符號屬性

詳細資料

建議

或者，使用 Load(String) 方法 (而非 Load()) 來載入工作流程，以避免此問題。

名稱	值
範圍	主修
版本	4.5
類型	正在重定目標

受影響的 API

WorkflowDesigner.Load()