Update ObjectSecurity.xml (#3444)

* Update ObjectSecurity.xml

When you call the method SetAccessRuleProtection with both parameters on true, you may create a non-canonical DACL.
I just made the most important changes. if you want to provide more details and e.g. code to "repair" the ACE order, I think this should go to a separate topic.
I have a colleague who provided sample code.

* Update xml/System.Security.AccessControl/ObjectSecurity.xml

Co-Authored-By: Carlos Sanchez Lopez <[email protected]>

* Update xml/System.Security.AccessControl/ObjectSecurity.xml

Co-authored-by: Jeremy Barton <[email protected]>
Co-authored-by: Carlos Sanchez Lopez <[email protected]>

Author: 3 people

xml/System.Security.AccessControl/ObjectSecurity.xml

@@ -1345,7 +1345,16 @@
         <param name="preserveInheritance">
           <see langword="true" /> to preserve inherited access rules; <see langword="false" /> to remove inherited access rules. This parameter is ignored if <paramref name="isProtected" /> is <see langword="false" />.</param>
         <summary>Sets or removes protection of the access rules associated with this <see cref="T:System.Security.AccessControl.ObjectSecurity" /> object. Protected access rules cannot be modified by parent objects through inheritance.</summary>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[  
+  
+## Remarks
+When you call the method with `isProtected=true` and `preserveInheritance=true`, you need to walk the new ACL of the object and check for DENY type ACEs.
+For a canonically sorted DACL, the DENY ACEs must appear in the front of the DACL.
+For more information on the canonical ordering of ACLs, see [Order of ACEs in a DACL](https://docs.microsoft.com/en-us/windows/win32/secauthz/order-of-aces-in-a-dacl).
+ 
+        ]]></format>
+      </remarks>
         <exception cref="T:System.InvalidOperationException">This method attempts to remove inherited rules from a non-canonical Discretionary Access Control List (DACL).</exception>
       </Docs>
     </Member>