How to Connect to an SMS Provider in Configuration Manager by Using Managed Code

Article
01/05/2024

To connect to an SMS Provider, use WqlConnectionManager.Connect. After it's connected, WqlConnectionManager.Connect has methods to query, create, delete, and otherwise use Configuration Manager Windows Management Instrumentation (WMI) objects.

Note

WqlConnectionManager.Connect is a WMI-specific derivation of ConnectionManagerBase.

If you're connecting to a local SMS Provider, you don't supply user credentials. If you're connecting to a remote SMS Provider, you don't need to supply user credentials if the current user/computer context has permissions on the remote SMS Provider.

If you don't have access privileges on the remote SMS Provider, or if you want to use a different user account, then you must supply user credentials for a user account that has access privileges.

WQLConnectionManager.Connection requires a SmsNamedValuesDictionary object. This can be used to store cached information such as the computer name.

It's pre-populated with many values that can be used in your application.

Value	Description.
ProviderLocation	The provider location. For example, \\<ComputerName>\ROOT\sms:SMS_ProviderLocation.SiteCode="XXX".
ProviderMachineName	The provider computer. For example, \\ComputerName.
Connection	The connection path. For example, \\ComputerName\root\sms\site_XXX.
ConnectedSiteCode	The site code for the Configuration Manager site that the connection is connected to. For example, XXX.
ServerName	The computer name, for example, COMPUTERNAME.
SiteName	The Configuration Manager site code. For example, Central Site.
ConnectedServerVersion	The version for the connected server. For example, 4.00.5830.0000
BuildNumber	The Configuration Manager installation build number. For example, 5830.

Note

The SmsNamedValuesDictionary object is not the context qualifier information passed to the provider. For more information, see How to Add a Configuration Manager Context Qualifier by Using Managed Code.

To connect to the SMS Provider

Create a SmsNamedValuesDictionaryObject.
Create an instance of the WqlConnectionManager class and call the [Connect] method passing the server name, and if the server name is remote, the user name and password.
Use the WqlConnectionManager object to connect to the provider.

Example

The following example method connects to the SMS Provider on a local or remote computer. If servername is remote, the method uses the supplied user name and password to connect to the remote computer. If you want to use the current user context, for the remote connection, change the code so that it doesn't pass the user name and password. If the connection is successful, a WqlConnectionManager object is returned.

For information about calling the sample code, see Calling Configuration Manager Code Snippets.

public WqlConnectionManager Connect(string serverName, string userName, string userPassword)  
{  
    try  
    {  
        SmsNamedValuesDictionary namedValues = new SmsNamedValuesDictionary();  
        WqlConnectionManager connection = new WqlConnectionManager(namedValues);  

        if (System.Net.Dns.GetHostName().ToUpper() == serverName.ToUpper())  
        {  
            // Connect to local computer.  
            connection.Connect(serverName);  
        }  
        else  
        {  
            // Connect to remote computer.  
            connection.Connect(serverName, userName, userPassword);  
        }  

        return connection;  
    }  
    catch (SmsException e)  
    {  
        Console.WriteLine("Failed to Connect. Error: " + e.Message);  
        return null;  
    }  
    catch (UnauthorizedAccessException e)  
    {  
        Console.WriteLine("Failed to authenticate. Error:" + e.Message);  
        return null;  
    }  
}

Compiling the Code

Namespaces

System

System.Collections.Generic

System.ComponentModel

Microsoft.ConfigurationManagement.ManagementProvider

Microsoft.ConfigurationManagement.ManagementProvider.WqlQueryEngine

Microsoft.ManagementConsole

Assembly

microsoft.configurationmanagement.managementprovider

adminui.wqlqueryengine

Microsoft.ManagementConsole

Robust Programming

The Configuration Manager exceptions that can be raised are SmsConnectionException and SmsQueryException. These can be caught together with SmsException.

.NET Framework Security

UnauthorizedAccessException is raised when the wrong credentials are passed to WqlConnectionManager.Connect.