[API Proposal]: System.DirectoryServices.Protocols: Add new directory search control for LDAP_SERVER_DIRSYNC_EX_OID

[dankitzmann]

Background and motivation

Active Directory implemented the LDAP_SERVER_DIRSYNC_EX_OID search control in 2012. The OID is 1.2.840.113556.1.4.2090. Its behavior mirrors the regular LDAP_SERVER_DIRSYNC_OID control except it provides a mechanism to return specified directory attributes even if they have not changed.

See ref: https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-adts/a568cbbe-5082-45ca-9427-0a6793646b89

Adding a directory control and response for this extended version of the DirSync control would be helpful for various DirSync change polling applications that use the DirectoryServices.Protocols API.

API Proposal

The main, perhaps only, file that would need to be changed is:
https://github.com/dotnet/dotnet/blob/30000d883e06c122311a66894579bc12329a09d4/src/runtime/src/libraries/System.DirectoryServices.Protocols/src/System/DirectoryServices/Protocols/common/DirectoryControl.cs

One possible approach is to simply add new request and response classes.

namespace System.DirectoryServices.Protocols;

public class DirSyncExtendedRequestControl : DirectoryControl
{
    public DirSyncExtendedRequestControl() : base("1.2.840.113556.1.4.2090", null, true, true) { }
    // Other ctor signatures and members to match existing DirSyncRequestControl
}

public class DirSyncExtendedResponseControl : DirectoryControl
{
    internal DirSyncExtendedResponseControl(byte[] cookie, bool moreData,
            int resultSize, bool criticality, byte[] controlValue)
        : base("1.2.840.113556.1.4.2090", controlValue, criticality, true)
    {
        // set properties/fields as done in DirSyncResponseControl
    }
}

internal static void TransformControls(DirectoryControl[] controls)
{
   // Slight changes in this method to add a condition matching the new OID above
}

### API Usage

```csharp
byte[]? currCookie = null;
var dirSyncExt = new DirSyncExtendedControl()
{
    Cookie = currCookie,
    // etc
};
var searchReq = new SearchRequest()
{
    Filter = "(objectCategory=group)",
    // etc
};
searchReq.Controls.Add(dirSyncExt);
// Perform DirSync polling per usual

Alternative Designs

No response

Risks

The LDAP_SERVER_DIRSYNC_EX_OID is an Active Directory MS-ADTS extension, meaning any new request/response controls for it may not be usable on other LDAP platforms, though I believe that is already the case with some LDAP OIDs in DirectoryServices.Protocols. In any case, the new classes could be decorated with [SupportedOSPlatform("windows")].

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-directoryservices, @jay98014
See info in area-owners.md if you want to be subscribed.

[KalleOlaviNiemitalo]

If it is possible to send this kind of request from a Linux client to an Active Directory server on Windows, then I don't think SupportedOSPlatformAttribute should be used.

[dankitzmann]

If it is possible to send this kind of request from a Linux client to an Active Directory server on Windows, then I don't think SupportedOSPlatformAttribute should be used.

That's a good point. The QuotaControl uses this attribute but I think that is because it passes a SID (security identifier) as the query argument, which probably wouldn't make sense for a Linux client.

https://learn.microsoft.com/en-us/dotnet/api/system.directoryservices.protocols.quotacontrol?view=net-9.0-pp

Given that, I agree SupportedOSPlatformAttribute is probably inappropriate/pointless for the LDAP_SERVER_DIRSYNC_EX_OID control.

[daaaaaaave]

This would be super useful for our enterprise apps. I hope this can get accepted as it seems to just be wiring up existing LDAP capability. Nice proposal, Dan!