From a516c75d9a7a7baed7090eb762797aa7a34be0e8 Mon Sep 17 00:00:00 2001 From: Connie Yau Date: Tue, 30 May 2017 11:57:12 -0700 Subject: [PATCH] Compatibility diagnostic wording fixes (#413) * Update breaking changes based on PR feedback * Split breaking change 181 into multiple categories * Fix incorrect xrefs --- Documentation/compatibility/README.md | 6 +++--- ...ider-decryptor-provides-a-reusable-transform.md | 2 +- ...g-the-entitydeploysplit-or-entityclean-tasks.md | 6 +++--- ...rameter_scale-are-now-public-virtual-members.md | 2 +- .../ef-version-must-match-netfx-version.md | 4 ++-- ...-variable-is-now-scoped-within-the-iteration.md | 3 +-- ...twriter-does-not-render-br-element-correctly.md | 2 +- ...d-machinekey_decode-methods-are-now-obsolete.md | 2 +- ...overloads-could-result-in-different-behavior.md | 2 +- .../new-enum-values-in-wpf's-pagerangeselection.md | 2 +- ...e-and-deprecatedattribute-in-winmd-scenarios.md | 4 ++-- .../remove-ssl3-from-the-wcf-transportdefaults.md | 2 +- ...-of-dependencies-with-the-wrong-architecture.md | 2 +- ...ome-workflow-drag-and-drop-apis-are-obsolete.md | 4 ++-- .../sslstream-support-for-tls-alerts.md | 3 ++- .../system_uri-parsing-adheres-to-rfc-3987.md | 14 +++++++------- .../throttle-concurrent-requests-per-session.md | 2 +- .../workflow-3_0-types-are-obsolete.md | 2 +- ...g-code-from-imagesourceconverter_convertfrom.md | 2 +- ...ializer-serializes-fields-differently-in-4_5.md | 3 +-- 20 files changed, 34 insertions(+), 35 deletions(-) diff --git a/Documentation/compatibility/README.md b/Documentation/compatibility/README.md index 8eab802..a826ac0 100644 --- a/Documentation/compatibility/README.md +++ b/Documentation/compatibility/README.md @@ -126,7 +126,7 @@ Please help us improve the [.NET Framework Application Compatibility documents]( - [Compiler support for type forwarding when multi-targeting mscorlib](compiler-support-for-type-forwarding-when-multi-targeting-mscorlib.md) - [ConcurrentQueue<T>.TryPeek can return an erroneous null via its out parameter](concurrentqueue_trypeek-can-return-an-erroneous-null-via-its-out-parameter.md) - [Different exception handling for ObjectContext.CreateDatabase and DbProviderServices.CreateDatabase methods](different-exception-handling-for-objectcontext_createdatabase-and-dbproviderservices_createdatabase-methods.md) -- [EF version must match NetFX version](ef-version-must-match-netfx-version.md) +- [Entity Framework version must match the .NET Framework version](ef-version-must-match-netfx-version.md) - [EncoderParameter ctor is obsolete](encoderparameter-ctor-is-obsolete.md) - [EntityFramework 6.0 loads very slowly in apps launched from Visual Studio](entityframework-6_0-loads-very-slowly-in-apps-launched-from-visual-studio.md) - [Enumerable.Empty<TResult> always returns cached instance](enumerable_empty-always-returns-cached-instance.md) @@ -168,7 +168,7 @@ Please help us improve the [.NET Framework Application Compatibility documents]( - [Sharing session state with Asp.Net StateServer requires all servers in the web farm to use the same .NET Framework version](sharing-session-state-with-asp_net-stateserver-requires-all-servers-in-the-web-farm-to-use-the-same-_net-framework-version.md) - [SoapFormatter cannot deserialize Hashtable and similar ordered collection objects](soapformatter-cannot-deserialize-hashtable-and-similar-ordered-collection-objects.md) - [Some .NET APIs cause first chance (handled) EntryPointNotFoundExceptions](some-_net-apis-cause-first-chance-(handled)-entrypointnotfoundexceptions.md) -- [Some WorkFlow drag and drop APIs are obsolete](some-workflow-drag-and-drop-apis-are-obsolete.md) +- [Some WorkFlow drag-and-drop APIs are obsolete](some-workflow-drag-and-drop-apis-are-obsolete.md) - [Sql_variant data uses sql_variant collation rather than database collation](sql_variant-data-uses-sql_variant-collation-rather-than-database-collation.md) - [SqlBulkCopy uses destination column encoding for strings](sqlbulkcopy-uses-destination-column-encoding-for-strings.md) - [SqlConnection can no longer connect to SQL Server 1997 or databases using the VIA adapter](sqlconnection-can-no-longer-connect-to-sql-server-1997-or-databases-using-the-via-adapter.md) @@ -199,7 +199,7 @@ Please help us improve the [.NET Framework Application Compatibility documents]( - [XML schema validation is stricter](xml-schema-validation-is-stricter.md) - [XmlSchemaException now sets line positions properly](xmlschemaexception-now-sets-line-positions-properly.md) - [XmlSerializer fails while serializing a type that hides an accessible member with an inaccessible one](xmlserializer-fails-while-serializing-a-type-that-hides-an-accessible-member-with-an-inaccessible-one.md) -- [XmlSerializer serializes fields differently in 4.5](xmlserializer-serializes-fields-differently-in-4_5.md) +- [XmlSerializer serializes fields differently in .NET Framework 4.5](xmlserializer-serializes-fields-differently-in-4_5.md) - [XmlTextReader DTD entity expansion is limited to 10,000,000 characters](xmltextreader-dtd-entity-expansion-is-limited-to-10000000-characters.md) - [XSLT forward compat now works](xslt-forward-compat-now-works.md) - [XSLT style sheet exception message changed](xslt-style-sheet-exception-message-changed.md) diff --git a/Documentation/compatibility/aescryptoserviceprovider-decryptor-provides-a-reusable-transform.md b/Documentation/compatibility/aescryptoserviceprovider-decryptor-provides-a-reusable-transform.md index 5bf6068..6a1b87b 100644 --- a/Documentation/compatibility/aescryptoserviceprovider-decryptor-provides-a-reusable-transform.md +++ b/Documentation/compatibility/aescryptoserviceprovider-decryptor-provides-a-reusable-transform.md @@ -23,7 +23,7 @@ after a call to or produces corrupted data. -- [X] Quirked AppContext or config files. Needs to be turned on automatically for some situations. +- [X] Quirked - [ ] Build-time break ### Recommended Action diff --git a/Documentation/compatibility/building-an-entity-framework-edmx-with-visual-studio-2013-can-fail-with-error-msb4062-if-using-the-entitydeploysplit-or-entityclean-tasks.md b/Documentation/compatibility/building-an-entity-framework-edmx-with-visual-studio-2013-can-fail-with-error-msb4062-if-using-the-entitydeploysplit-or-entityclean-tasks.md index 22711f3..3552df7 100644 --- a/Documentation/compatibility/building-an-entity-framework-edmx-with-visual-studio-2013-can-fail-with-error-msb4062-if-using-the-entitydeploysplit-or-entityclean-tasks.md +++ b/Documentation/compatibility/building-an-entity-framework-edmx-with-visual-studio-2013-can-fail-with-error-msb4062-if-using-the-entitydeploysplit-or-entityclean-tasks.md @@ -13,11 +13,11 @@ Major Available ### Change Description -MSBuild 12.0 tools (included in Visual Studio 2013) changed msbuild file +MSBuild 12.0 tools (included in Visual Studio 2013) changed MSBuild file locations, causing older Entity Framework targets files to be invalid. The result is that `EntityDeploySplit` and `EntityClean` tasks fail because they are unable to find `Microsoft.Data.Entity.Build.Tasks.dll`. Note that this break is -because of a toolset (msbuild/VS) change, not because of a .NET Framework +because of a toolset (MSBuild/VS) change, not because of a .NET Framework change. It will only occur when upgrading developer tools, not when merely upgrading the .NET Framework. @@ -25,7 +25,7 @@ upgrading the .NET Framework. - [x] Build-time break ### Recommended Action -Entity Framework targets files are fixed to work with the new msbuild layout beginning in the .NET Framework 4.6. Upgrading to that version of the Framework will fix this issue. Alternatively, [this](http://stackoverflow.com/a/24249247/131944) workaround can be used to patch the targets files directly. +Entity Framework targets files are fixed to work with the new MSBuild layout beginning in the .NET Framework 4.6. Upgrading to that version of the Framework will fix this issue. Alternatively, [this](http://stackoverflow.com/a/24249247/131944) workaround can be used to patch the targets files directly. ### Affected APIs * Not detectable via API analysis diff --git a/Documentation/compatibility/dbparameter_precision-and-dbparameter_scale-are-now-public-virtual-members.md b/Documentation/compatibility/dbparameter_precision-and-dbparameter_scale-are-now-public-virtual-members.md index 35fbd8d..5f47e91 100644 --- a/Documentation/compatibility/dbparameter_precision-and-dbparameter_scale-are-now-public-virtual-members.md +++ b/Documentation/compatibility/dbparameter_precision-and-dbparameter_scale-are-now-public-virtual-members.md @@ -24,7 +24,7 @@ explicit interface implementations, When re-building an ADO.NET database provider, these differences will require the 'override' keyword to be applied to the Precision and Scale properties. This -is only needed when re-building the components; exisiting binaries will continue +is only needed when re-building the components; existing binaries will continue to work. ### Affected APIs diff --git a/Documentation/compatibility/ef-version-must-match-netfx-version.md b/Documentation/compatibility/ef-version-must-match-netfx-version.md index dc655d2..3036bce 100644 --- a/Documentation/compatibility/ef-version-must-match-netfx-version.md +++ b/Documentation/compatibility/ef-version-must-match-netfx-version.md @@ -1,4 +1,4 @@ -## EF version must match NetFX version +## Entity Framework version must match the .NET Framework version ### Scope Major @@ -22,7 +22,7 @@ which annotations to use. - [x] Build-time break ### Recommended Action -Upgrade to EF 5 for .NET 4.5 +Upgrade to Entity Framework 5 for .NET Framework 4.5 ### Affected APIs * Not detectable via API analysis diff --git a/Documentation/compatibility/foreach-iterator-variable-is-now-scoped-within-the-iteration.md b/Documentation/compatibility/foreach-iterator-variable-is-now-scoped-within-the-iteration.md index 999892b..5af7159 100644 --- a/Documentation/compatibility/foreach-iterator-variable-is-now-scoped-within-the-iteration.md +++ b/Documentation/compatibility/foreach-iterator-variable-is-now-scoped-within-the-iteration.md @@ -10,7 +10,7 @@ Major Available ### Change Description -Beginning with C# 5 (Visual Studio 2012), foreach iterator variables are scoped within the iteration. This can cause breaks if code was previously depending on the variables to not be included in the foreach's closure. The symptom of this change will be that an iterator variable passed to a delagate will be treated as the value it had at the time the delegate was created, rather than the value it had at the time the delegate was invoked. +Beginning with C# 5 (Visual Studio 2012), `foreach` iterator variables are scoped within the iteration. This can cause breaks if code was previously depending on the variables to not be included in the `foreach`'s closure. The symptom of this change is that an iterator variable passed to a delegate is treated as the value it has at the time the delegate is created, rather than the value it has at the time the delegate is invoked. - [ ] Quirked - [x] Build-time break @@ -23,7 +23,6 @@ Ideally, code should be updated to expect the new compiler behavior. If the old ### Categories Core -C# [More information](http://blogs.msdn.com/b/ericlippert/archive/2009/11/12/closing-over-the-loop-variable-considered-harmful.aspx) diff --git a/Documentation/compatibility/htmltextwriter-does-not-render-br-element-correctly.md b/Documentation/compatibility/htmltextwriter-does-not-render-br-element-correctly.md index 54021cd..c6179fb 100644 --- a/Documentation/compatibility/htmltextwriter-does-not-render-br-element-correctly.md +++ b/Documentation/compatibility/htmltextwriter-does-not-render-br-element-correctly.md @@ -25,7 +25,7 @@ with a `
` element will correctly insert only one `
` (instead of two) If an app depended on the extra `
` tag, should be called a second time. Note that this behavior change only affects apps -that are targeting the .NET Framework 4.6, so another option is to target a +that target the .NET Framework 4.6 or later, so another option is to target a previous version of the .NET Framework in order to get the old behavior. ### Affected APIs diff --git a/Documentation/compatibility/machinekey_encode-and-machinekey_decode-methods-are-now-obsolete.md b/Documentation/compatibility/machinekey_encode-and-machinekey_decode-methods-are-now-obsolete.md index 80a3e56..f87c60e 100644 --- a/Documentation/compatibility/machinekey_encode-and-machinekey_decode-methods-are-now-obsolete.md +++ b/Documentation/compatibility/machinekey_encode-and-machinekey_decode-methods-are-now-obsolete.md @@ -23,7 +23,7 @@ The recommended alternatives are and . -Alternatively, the build warnings can be suppressed or they can be avoided by +Alternatively, the build warnings can be suppressed, or they can be avoided by using an older compiler. The APIs are still supported. ### Affected APIs diff --git a/Documentation/compatibility/new-(ambiguous)-dispatcher_invoke-overloads-could-result-in-different-behavior.md b/Documentation/compatibility/new-(ambiguous)-dispatcher_invoke-overloads-could-result-in-different-behavior.md index f95fbe0..362a1b8 100644 --- a/Documentation/compatibility/new-(ambiguous)-dispatcher_invoke-overloads-could-result-in-different-behavior.md +++ b/Documentation/compatibility/new-(ambiguous)-dispatcher_invoke-overloads-could-result-in-different-behavior.md @@ -19,7 +19,7 @@ parameter. If a call to a Dispatcher.Invoke overload with a @System.Delegate parameter is resolved as a call to a Dispatcher.Invoke overload with an @System.Action parameter, the following differences in behavior may occur: -- If an exception occurs, the Filter> and events are not raised. Instead, exceptions are handled by the event. +- If an exception occurs, the and events are not raised. Instead, exceptions are handled by the event. - Calls to some members, such as , block until the operation has completed. - [ ] Quirked diff --git a/Documentation/compatibility/new-enum-values-in-wpf's-pagerangeselection.md b/Documentation/compatibility/new-enum-values-in-wpf's-pagerangeselection.md index c1d3c40..be1a727 100644 --- a/Documentation/compatibility/new-enum-values-in-wpf's-pagerangeselection.md +++ b/Documentation/compatibility/new-enum-values-in-wpf's-pagerangeselection.md @@ -13,7 +13,7 @@ Available Two new members ( and -) +) have been added to the enum. diff --git a/Documentation/compatibility/obsoleteattribute-exports-as-both-obsoleteattribute-and-deprecatedattribute-in-winmd-scenarios.md b/Documentation/compatibility/obsoleteattribute-exports-as-both-obsoleteattribute-and-deprecatedattribute-in-winmd-scenarios.md index cfdb697..e246d95 100644 --- a/Documentation/compatibility/obsoleteattribute-exports-as-both-obsoleteattribute-and-deprecatedattribute-in-winmd-scenarios.md +++ b/Documentation/compatibility/obsoleteattribute-exports-as-both-obsoleteattribute-and-deprecatedattribute-in-winmd-scenarios.md @@ -14,7 +14,7 @@ Available When you create a Windows Metadata library (.winmd file), the attribute is exported as both and -Windows.Foundation.DeprecatedAttribute. +[Windows.Foundation.DeprecatedAttribute](https://docs.microsoft.com/en-us/uwp/api/windows.foundation.metadata.deprecatedattribute). - [ ] Quirked - [x] Build-time break @@ -27,7 +27,7 @@ warnings when consuming that code from C++/CX or JavaScript. We do not recommend applying both and -Windows.Foundation.DeprecatedAttribute to code in managed assemblies; it may +[Windows.Foundation.DeprecatedAttribute](https://docs.microsoft.com/en-us/uwp/api/windows.foundation.metadata.deprecatedattribute) to code in managed assemblies; it may result in build warnings. ### Affected APIs diff --git a/Documentation/compatibility/remove-ssl3-from-the-wcf-transportdefaults.md b/Documentation/compatibility/remove-ssl3-from-the-wcf-transportdefaults.md index 1367801..c3834a7 100644 --- a/Documentation/compatibility/remove-ssl3-from-the-wcf-transportdefaults.md +++ b/Documentation/compatibility/remove-ssl3-from-the-wcf-transportdefaults.md @@ -25,7 +25,7 @@ should be able to negotiate a connection using at least TLS1.0. If Ssl3 is required, use one of the following configuration mechanisms to add Ssl3 to the list of negotiated protocols. -* +* * * [\ section of \](https://docs.microsoft.com/en-us/dotnet/articles/framework/configure-apps/file-schema/wcf/transport-of-nettcpbinding) * [\ section of \](https://docs.microsoft.com/en-us/dotnet/articles/framework/configure-apps/file-schema/wcf/sslstreamsecurity) diff --git a/Documentation/compatibility/resolveassemblyreference-task-now-warns-of-dependencies-with-the-wrong-architecture.md b/Documentation/compatibility/resolveassemblyreference-task-now-warns-of-dependencies-with-the-wrong-architecture.md index 1c8bf61..212cc9f 100644 --- a/Documentation/compatibility/resolveassemblyreference-task-now-warns-of-dependencies-with-the-wrong-architecture.md +++ b/Documentation/compatibility/resolveassemblyreference-task-now-warns-of-dependencies-with-the-wrong-architecture.md @@ -10,7 +10,7 @@ Minor Planned ### Change Description -The task emits a warning, MSB3270, which indicates that a reference or any of its dependencies does not match the app's architecture. For example, this occurs if an app that was compiled with the anycpu option includes an x86 reference. Such a scenario could result in an app failure at run time (in this case, if the app is deployed as an x64 process). +The task emits a warning, MSB3270, which indicates that a reference or any of its dependencies does not match the app's architecture. For example, this occurs if an app that was compiled with the `AnyCPU` option includes an x86 reference. Such a scenario could result in an app failure at run time (in this case, if the app is deployed as an x64 process). - [ ] Quirked - [x] Build-time break diff --git a/Documentation/compatibility/some-workflow-drag-and-drop-apis-are-obsolete.md b/Documentation/compatibility/some-workflow-drag-and-drop-apis-are-obsolete.md index 4883f5a..8ef567b 100644 --- a/Documentation/compatibility/some-workflow-drag-and-drop-apis-are-obsolete.md +++ b/Documentation/compatibility/some-workflow-drag-and-drop-apis-are-obsolete.md @@ -1,4 +1,4 @@ -## Some WorkFlow drag and drop APIs are obsolete +## Some WorkFlow drag-and-drop APIs are obsolete ### Scope Minor @@ -10,7 +10,7 @@ Minor Available ### Change Description -This WorkFlow Drag/Drop API is obsolete and will cause compiler warnings if the app is rebuilt against 4.5. +This WorkFlow drag-and-drop API is obsolete and will cause compiler warnings if the app is rebuilt against 4.5. - [ ] Quirked - [x] Build-time break diff --git a/Documentation/compatibility/sslstream-support-for-tls-alerts.md b/Documentation/compatibility/sslstream-support-for-tls-alerts.md index 5268786..b311132 100644 --- a/Documentation/compatibility/sslstream-support-for-tls-alerts.md +++ b/Documentation/compatibility/sslstream-support-for-tls-alerts.md @@ -78,7 +78,8 @@ for .NET 4.6 and above applications running on .NET 4.7 or higher framework. * `N:System.Net.Http` ### Category -Networking, Security +Networking +Security