xDscWebService: SQL Backend Setup + Windows Server 2025 Compatibility

[mmeade-visory]

Problem description

I've spent considerable time getting the SQL backend working with xDscWebService and wanted to document what I found since the existing documentation has several gaps and some outright incorrect guidance. Hopefully this saves someone else the same pain.

Environment

-- xPSDesiredStateConfiguration: 9.2.1
-- SQL Server: Named instance configured on port 1433
-- IIS App Pool Identity: LocalSystem
-- OS Tested: Windows Server 2019, 2022, 2025

Windows Server 2025 Compatibility
The SQL backend does not work on Windows Server 2025 as of this writing.
On Windows Server 2019 and 2022 the SQL backend functions correctly — the DSC service creates the required tables (RegistrationData, StatusReport, Devices) on first use and client registration succeeds.
On Windows Server 2025 the SQL code path is never reached at all:

-- The endpoint responds HTTP 200 (IIS and the service are running)
-- No sessions appear in sys.dm_exec_sessions when the endpoint is hit
-- No errors appear in the SQL error log
-- No ASP.NET errors appear in the Application event log
-- Tables are never created even with correct connection string and permissions

Pre-creating the database and tables manually does not resolve the issue — the problem is that the service DLL on Windows Server 2025 does not attempt a SQL connection at all. This is likely a regression in Microsoft.Powershell.DesiredStateConfiguration.Service.dll on that OS version. All documentation and known-working configurations are based on Windows Server 2019.

Recommendation: Deploy the pull server on Windows Server 2022 for SQL backend support. WS2022 was confirmed working and has a longer support lifecycle than WS2019.

Verbose logs

The symptom was essentially silence:

No sessions appearing in sys.dm_exec_sessions
No errors in the SQL error log
No ASP.NET errors in the Application event log
The endpoint returned HTTP 200 normally
The SQL code path simply was never reached

It never created the table in the DSC database...  

When registering a new client:

Registration of the Dsc Agent with the server https://dscpull.visory.net:8080/PSDSCPullServer.svc failed. The underlying error is: Failed to register Dsc Agent with AgentId 42F782B1-197B-11F1-9CEF-005056A7F3B2 with the server 
https://dscpull.visory.net:8080/PSDSCPullServer.svc/Nodes(AgentId='42F782B1-197B-11F1-9CEF-005056A7F3B2'). .
    + CategoryInfo          : InvalidResult: (root/Microsoft/...gurationManager:String) [], CimException
    + FullyQualifiedErrorId : RegisterDscAgentCommandFailed,Microsoft.PowerShell.DesiredStateConfiguration.Commands.RegisterDscAgentCommand
    + PSComputerName        : localhost


and this address returned:
https://dscpull.visory.net:8080/PSDSCPullServer.svc/Nodes(AgentId='42F782B1-197B-11F1-9CEF-005056A7F3B2')

<m:error xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
<m:code>Client protocol version is invalid. Request header should contain ProtocolVersion {0}.</m:code>
<m:message xml:lang="en-US">Client protocol version is invalid. Request header should contain ProtocolVersion 2.0.</m:message>
<m:innererror>
<m:message>Client protocol version is invalid. Request header should contain ProtocolVersion 2.0.</m:message>
<m:type>System.ArgumentException</m:type>
<m:stacktrace/>
</m:innererror>
</m:error>

DSC configuration

configuration xDscWebServiceRegistration
{
    param
    (
        [string[]]$NodeName = 'localhost',
        [ValidateNotNullOrEmpty()]
        [string] $certificateThumbPrint,
        [Parameter(HelpMessage='This should be a string with enough entropy (randomness) to protect the registration of clients to the pull server.  We will use new GUID by default.')]
        [ValidateNotNullOrEmpty()]
        [string] $RegistrationKey   # A guid that clients use to initiate conversation with pull server
    )

    Import-DSCResource -ModuleName PSDesiredStateConfiguration
    Import-DSCResource -ModuleName xPSDesiredStateConfiguration
    Import-DscResource -ModuleName NetworkingDsc

    Node $NodeName
    {
        WindowsFeature DSCServiceFeature
        {
            Ensure                       = "Present"
            Name                         = "DSC-Service"
        }

	    Firewall HTTPTCPCommunication
        {
            Name                         = 'HTTPTcpCommunication'
            DisplayName                  = 'HTTP TCP communication'
            Action                       = 'Allow'
            Direction                    = 'Inbound'
            Protocol                     = 'TCP'
            Profile                      = 'Any'
            Enabled                      = 'True'
            LocalPort			         = @('8080','9080')
        }

        xDSCWebService PSDSCPullServer
        {
            Ensure                       = "Present"
            EndpointName                 = "PSDSCPullServer"
            Port                         = 8080
            PhysicalPath                 = "E:\inetpub\PSDSCPullServer"
            CertificateThumbPrint        = "<cert thumb>"
            ModulePath                   = "E:\DscService\Modules"
            ConfigurationPath            = "E:\DscService\Configuration"
            State                        = "Started"            
            RegistrationKeyPath          = "E:\DscService"
            AcceptSelfSignedCertificates = $true
            UseSecurityBestPractices     = $true
            SqlProvider                  = $true
            SqlConnectionString          = 'Provider=SQLOLEDB.1;Data Source=<sql server name>;Initial Catalog=master;User ID=<sqlsvcacc>;Password=<sqlpw>;TrustServerCertificate=Yes;'
            DependsOn                    = "[WindowsFeature]DSCServiceFeature"
        }

        File RegistrationKeyFile
        {
            Ensure                       = 'Present'
            Type                         = 'File'
            DestinationPath              = "E:\DscService\RegistrationKeys.txt"
            Contents                     = $RegistrationKey
            Force                        = $true
            MatchSource                  = $true
        }
    }
}

$xDscWebServiceRegistrationSplat = @{
    certificateThumbprint = '<cert thumb>'
    RegistrationKey = '<key>'
    OutputPath = 'C:\sys\dsc'
}

xDscWebServiceRegistration @xDscWebServiceRegistrationSplat

Start-DscConfiguration -Path C:\sys\dsc -Wait -Verbose -Force

Suggested solution

Don't use Server 2025 for your SQL backed DSC pull server, Server 2022 and 2019 seems to work fine.

Operating system the target node is running

OsName               : Microsoft Windows Server 2025 Standard
OsOperatingSystemSKU : StandardServerEdition
OsArchitecture       : 64-bit
WindowsVersion       : 2009
WindowsBuildLabEx    : 26100.1.amd64fre.ge_release.240331-1435
OsLanguage           : en-US
OsMuiLanguages       : {en-US}

PowerShell version and build the target node is running

Name                           Value                                                                                                                                                                                                                             
----                           -----                                                                                                                                                                                                                             
PSVersion                      5.1.26100.32370                                                                                                                                                                                                                   
PSEdition                      Desktop                                                                                                                                                                                                                           
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}                                                                                                                                                                                                           
BuildVersion                   10.0.26100.32370                                                                                                                                                                                                                  
CLRVersion                     4.0.30319.42000                                                                                                                                                                                                                   
WSManStackVersion              3.0                                                                                                                                                                                                                               
PSRemotingProtocolVersion      2.3                                                                                                                                                                                                                               
SerializationVersion           1.1.0.1

xPSDesiredStateConfiguration version

Name                         Version Path                                                                                                           
----                         ------- ----                                                                                                           
xPSDesiredStateConfiguration 9.2.1   C:\Program Files\WindowsPowerShell\Modules\xPSDesiredStateConfiguration\9.2.1\xPSDesiredStateConfiguration.psd1

[mmeade-visory]

Forgot to add that downgrading the xPSDesiredStateModule made no difference. Tied several versions:

9.2.1 - fail
9.2.0 - fail
9.1.0 - fail
8.2.0 - fail

[dan-hughes]

Checkout CommonTasks composite resources. It may help with some of the issues you are seeing.

[mmeade-visory]

Checkout CommonTasks composite resources. It may help with some of the issues you are seeing.

Dan, thanks for the tip, interesting, I'll test in a lab but for now I've rebuilt this environment in Windows 2022. I'll see if I can get to this in a few weeks as this issue has put my project behind the 8 ball. Once I get caught up, I'll be happy to spin up a test to see if I can duplicate it with your special sauce.

[dan-hughes]

I've managed to reproduce this.
It's not a DSC module issue, there is an issue with the Microsoft.Powershell.DesiredStateConfiguration.Service.dll in Server 2025. Looking at the code in the DLL's and comparing to the DLL in Server 2022 there is a new bit of code in the constructor which is exiting the constructor before the DB can be created.

Constructor:

string dbLocFromCnstr = OleDatabaseHelper.GetDBLocFromCnstr(appSetting2);
if (!File.Exists(dbLocFromCnstr))
    OleDatabaseHelper.CreateOleDBRepository(dbLocFromCnstr);
if (!File.Exists(dbLocFromCnstr))
      return;

GetDBLocFromCnstr:

private static string GetDBLocFromCnstr(string cnstr)
{
  if (!string.IsNullOrEmpty(cnstr))
  {
    OleDbConnectionStringBuilder connectionStringBuilder = new OleDbConnectionStringBuilder();
    connectionStringBuilder.ConnectionString = cnstr;
    if (connectionStringBuilder.ContainsKey("Data Source"))
      return connectionStringBuilder["Data Source"].ToString();
  }
  return string.Empty;
}

CreateOleDBRepository:

internal static void CreateOleDBRepository(string outputPath)
{
  try
  {
    string str1 = Environment.ExpandEnvironmentVariables("%SystemRoot%\\\\SysWOW64\\\\WindowsPowerShell\\\\v1.0\\\\powershell.exe");
    string str2 = Environment.ExpandEnvironmentVariables("%SystemRoot%\\\\System32\\\\WindowsPowerShell\\\\v1.0\\\\Modules\\\\PSDesiredStateConfiguration\\\\PullServer\\\\GenerateDevicesMDB.ps1");
    using (Process process = Process.Start(new ProcessStartInfo()
    {
      FileName = str1,
      Arguments = $"-File \"{str2}\" -OutputPath \"{outputPath}\"",
      UseShellExecute = false,
      RedirectStandardOutput = true,
      RedirectStandardError = true
    }))
    {
      process.StandardOutput.ReadToEnd();
      process.StandardError.ReadToEnd();
      process.WaitForExit();
    }
  }
  catch (Exception ex)
  {
    DatabaseHelper.TraceException2Params(ex.ToString(), "Failed to create OLE DB repository.");
    throw new InvalidOperationException("Failed to create OLE DB repository. See inner exception for details.", ex);
  }
}

There is also a bunch of nonsense in the WriteRegistrationRecordToDatabase function which again will prevent this working.
If you copy Microsoft.Powershell.DesiredStateConfiguration.Service.dll from Server 2022 to the 2025 inetpub and restart the site then it works as expected.

It's a raise a support call to Microsoft fix I'm afraid.

[dan-hughes]

TBH the more I think of it this could be test code that got shipped accidently.

[mmeade-visory]

Thanks for this... This is awesome... I can't test atm, do we want to leave this open until MS gets back to you?

[dan-hughes]

I don't have access to a support agreement to raise a call to.
Usually when issues arise from the OS side we as the user to raise.

[mmeade-visory]

Understood, I'll see what I can do....

[dan-hughes]

@raandree, do you have customers using the Pull Server backed with SQL on Server 2025?

[raandree]

No yet. Did I understand you correctly that this issue only appears when having the pull server on 2025, right? Connecting 2025 nodes to a 2022 pull server works as it should?

Is

If you copy Microsoft.Powershell.DesiredStateConfiguration.Service.dll from Server 2022 to the 2025 inetpub and restart the site then it works as expected"

an acceptable workaround? Given the deprecated state of DSC I doubt that Microsoft will put the effort into this to solve it quickly.

[mmeade-visory]

I can confirm that I wasn't able to reproduce this under Server 2022....

[dan-hughes]

No yet. Did I understand you correctly that this issue only appears when having the pull server on 2025, right? Connecting 2025 nodes to a 2022 pull server works as it should?

Is

If you copy Microsoft.Powershell.DesiredStateConfiguration.Service.dll from Server 2022 to the 2025 inetpub and restart the site then it works as expected"

an acceptable workaround? Given the deprecated state of DSC I doubt that Microsoft will put the effort into this to solve it quickly.

Correct, Server 2025 Microsoft.Powershell.DesiredStateConfiguration.Service.dll has some changes in which breaks SQL DB access.
There are no other changes by the looks of it.

I get it's deprecated but this is flat out broken which in theory costs users 3 years of potential further use.