jprdonnelly/dotnet
1
0
Fork 0
mirror of https://github.com/microsoft/dotnet.git synced 2025-12-25 01:02:53 -05:00
Code Issues Projects Releases Wiki Activity

Compat documents for .NET 4.8 for Workflow runtime and designer. (#966)

Browse Source 
* Compat documents for .NET 4.8 for Workflow runtime and designer.

* Addressed review comments
This commit is contained in:
Jim Carley
2019-02-27 10:22:25 -08:00
committed by Ron Petrusha
parent 7009963985
commit 769df738ab
4 changed files with 231 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
Documentation/compatibility/workflow-designer-accessibility-4-8.md Normal file
View File

@@ -0,0 +1,56 @@
## Accessibility improvements in Windows Workflow Foundation (WF) workflow designer
### Scope
Minor
### Version Introduced
4.8
### Source Analyzer Status
NotPlanned
### Change Description
The Windows Workflow Foundation (WF) workflow designer is improving how it works with accessibility technologies. These improvements include the following changes:
- Users using Narrator will see improvements in FlowSwitch case labels.
- Users who choose High Contrast themes will see many improvements in the visibility of the Workflow Designer and its controls, like better contrast ratios between elements and more noticeable selection boxes used for focus elements.
- Users using Narrator will see improvements in button descriptions.
- [x] Quirked
- [ ] Build-time break
### Recommended Action
If you have an application with a re-hosted workflow designer, your application can benefit from these changes by performing either of these actions:
- Recompile your application to target the .NET Framework 4.8 or later. These accessibility changes are enabled by default.
- If your application targets the .NET Framework 4.7.2 or earlier but is running on the .NET Framework 4.8 or later, you can opt out of these legacy accessibility behaviors by adding the following [AppContext switch](~/docs/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element.md) to the `<runtime>` section of the app.config file and set it to `false`, as the following example shows.
```xml
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<startup>
<supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7"/>
</startup>
<runtime>
<!-- AppContextSwitchOverrides value attribute is in the form of 'key1=true|false;key2=true|false -->
<AppContextSwitchOverrides value="Switch.UseLegacyAccessibilityFeatures.3=false" />
</runtime>
</configuration>
```
Applications that target the .NET Framework 4.8 and want to preserve the legacy accessibility behavior can opt in to the use of legacy accessibility features by explicitly setting this AppContext switch to `true`.
### Affected APIs
* Not detectable via API analysis
### Category
Windows Workflow Foundation (WF)
<!--
### Original Bug
Bug link goes here
https://devdiv.visualstudio.com/DevDiv/_workitems/edit/604810
https://devdiv.visualstudio.com/DevDiv/_workitems/edit/613975
https://devdiv.visualstudio.com/DevDiv/_workitems/edit/682170
-->

54
Documentation/compatibility/workflow-xaml-checksums-for-symbols-changed-from-sha1-to-sha256.md Normal file
View File

@@ -0,0 +1,54 @@
## Workflow XAML checksums for symbols changed from SHA1 to SHA256
### Scope
Minor
### Version Introduced
4.8
### Source Analyzer Status
NotPlanned
### Change Description
To support debugging with Visual Studio,
the Workflow runtime generates a checksum for a workflow XAML file using a hashing algorithm.
In the .NET Framework 4.6.2 and earlier versions, workflow checksum hashing used the MD5
algorithm, which caused issues on FIPS-enabled systems. Starting with the .NET Framework 4.7,
the default algorithm was changed to SHA1. Starting with the .NET Framework 4.8, the default
algorithm was changed to SHA256.
- [x] Quirked
- [ ] Build-time break
### Recommended Action
If your code is unable to load workflow instances or to find appropriate symbols
due to a checksum failure, try setting
the `AppContext` switch "Switch.System.Activities.UseSHA1HashForDebuggerSymbols" to true.
In code:
```csharp
System.AppContext.SetSwitch("Switch.System.Activities.UseSHA1HashForDebuggerSymbols", true);
```
Or in configuration:
```xml
<configuration>
<runtime>
<AppContextSwitchOverrides value="Switch.System.Activities.UseSHA1HashForDebuggerSymbols=true" />
</runtime>
</configuration>
```
### Affected APIs
* Not detectable via API analysis
### Category
Windows Workflow Foundation (WF)
<!--
### Original Bug
Bug link goes here
https://devdiv.visualstudio.com/DevDiv/_workitems/edit/537692
-->

63
Documentation/compatibility/workflow-xoml-definition-and-sqltrackingservice-caches-changed-from-md5-to-sha256.md Normal file
View File

@@ -0,0 +1,63 @@
## Workflow XOML definition and SqlTrackingService cache keys changed from MD5 to SHA256
### Scope
Minor
### Version Introduced
4.8
### Source Analyzer Status
NotPlanned
### Change Description
The Workflow Runtime in keeps a cache of workflow definitions defined in XOML.
The SqlTrackingService also keeps a cache that is keyed by strings.
These caches are keyed by values that include checksum hash value.
In the .NET Framework 4.7.2 and earlier versions, this checksum hashing used the MD5
algorithm, which caused issues on FIPS-enabled systems. Starting with the .NET Framework 4.8,
the algorithm used is SHA256.
There shouldn't be an compatability issue with this change because the values are recalculated
each time the Workflow Runtime and SqlTrackingService is started. However, we have provided quirks to allow
customers to revert back to usage of the legacy hashing algorithm, if necessary.
- [x] Quirked
- [ ] Build-time break // Causes a break if attempted to recompile
### Recommended Action
If this change presents a problem when executing workflows, try setting one or both of
the `AppContext` switches:
- "Switch.System.Workflow.Runtime.UseLegacyHashForWorkflowDefinitionDispenserCacheKey" to true.
- "Switch.System.Workflow.Runtime.UseLegacyHashForSqlTrackingCacheKey" to true.
In code:
```csharp
System.AppContext.SetSwitch("Switch.System.Workflow.Runtime.UseLegacyHashForWorkflowDefinitionDispenserCacheKey", true);
System.AppContext.SetSwitch("Switch.System.Workflow.Runtime.UseLegacyHashForSqlTrackingCacheKey", true);
```
Or in the configuration file (this needs to be in the config file for the application that is creating the <xref:System.Workflow.Runtime.WorkflowRuntime> object):
```xml
<configuration>
<runtime>
<AppContextSwitchOverrides value="Switch.System.Workflow.Runtime.UseLegacyHashForWorkflowDefinitionDispenserCacheKey=true" />
<AppContextSwitchOverrides value="Switch.System.Workflow.Runtime.UseLegacyHashForSqlTrackingCacheKeytrue" />
</runtime>
</configuration>
```
### Affected APIs
* Not detectable via API analysis
### Category
Windows Workflow Foundation (WF)
<!--
### Original Bug
Bug link goes here
https://devdiv.visualstudio.com/DevDiv/_workitems/edit/532505
-->

58
Documentation/compatibility/workflow-xoml-file-checksums-changed-from-md5-to-sha256.md Normal file
View File

@@ -0,0 +1,58 @@
## Workflow XOML file checksums changed from MD5 to SHA256
### Scope
Minor
### Version Introduced
4.8
### Source Analyzer Status
NotPlanned
### Change Description
To support debugging XOML-based workflows with Visual Studio,
when workflow projects containing XOML files build, a checksum of the contents of the XOML file is included in the code
generated as a <xref:System.Workflow.ComponentModel.Compiler.WorkflowMarkupSourceAttribute.MD5Digest?displayProperty=nameWithType> value.
In the .NET Framework 4.7.2 and earlier versions, this checksum hashing used the MD5
algorithm, which caused issues on FIPS-enabled systems. Starting with the .NET Framework 4.8,
the algorithm used is SHA256. To be compatibile with the WorkflowMarkupSourceAttribute.MD5Digest,
only the first 16 bytes of the generated checksum are used.
This may cause problems during debugging. You may need to re-build your project.
- [x] Quirked
- [ ] Build-time break // Causes a break if attempted to recompile
### Recommended Action
If re-building your project does not solve the problem, try setting
the `AppContext` switch "Switch.System.Workflow.ComponentModel.UseLegacyHashForXomlFileChecksum" to true.
In code:
```csharp
System.AppContext.SetSwitch("Switch.System.Workflow.ComponentModel.UseLegacyHashForXomlFileChecksum", true);
```
Or in a configuration file (this needs to be in MSBuild.exe.config for the MSBuild.exe that you are using):
```xml
<configuration>
<runtime>
<AppContextSwitchOverrides value="Switch.System.Workflow.ComponentModel.UseLegacyHashForXomlFileChecksum=true" />
</runtime>
</configuration>
```
### Affected APIs
* Not detectable via API analysis
### Category
Windows Workflow Foundation (WF)
<!--
### Original Bug
Bug link goes here
https://devdiv.visualstudio.com/DevDiv/_workitems/edit/531054
-->