rundll32 printui.dll,PrintUIEntry to map network printers

Have you ever used rundll32 printui.dll,PrintUIEntry to map a network printer on a computer? This command can map a printer for every user and can also be used to remove that same mapping. When you think about it, this behavior is a little odd.

I say that because mapping printers is a user profile based action. If you want a printer to show up for everyone, you have to install it on the computer directly. But somehow this command gets around that.

I was writing a DSC component that used this command and I ran into an issue trying to verify a printer was mapped. CIM_Printer and Win32_Printer could not find the printer when ran in the context of DSC. I suspect that the system account can't see the printer. Once a user is logged in, the connection to that printer is established. I had to find another way to identify these mapped printers.

My first thought was to fire up the Sysinternals procmon.exe tool. Even after filtering it down to just rundll32 related activity, nothing jumped out to me. So I started searching the registry. It didn't take long and I found what I was looking for.

"HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Print\Connections"

That registry location contains the list of printer connections that should be mapped for each user. Those printers are kept separate from the locally installed printers on the system. I started checking this location and everything started working for me.

If you came here trying to map a printer in this way, here are the commands that I used

$path = "\\server\printer name"

# Map a printer
rundll32 printui.dll,PrintUIEntry /ga /n$path 

# remove the printer
rundll32 printui.dll,PrintUIEntry /gd /n$path

# list printer connections
rundll32 printui.dll,PrintUIEntry /ge

LocalConfigurationManager{ DebugMode = $true }

One issue that I ran into when writing my custom DSC resources is that the local resource manager would cache the modules I was working on. It took me a while to realize that was going on. That is when I discovered DebugMode for the local resource manager.

If you enable debug mode, then it will reload the module every time. This is off by default for performance reasons. You have to use a DSC configuration to configure this, but it is done in a slightly different way than normal DSC configurations. Technet has all the details on how to configure the local resource manager. That is where I pulled this sample code from.

If all you want to do is enable debug mode, here is the quick script to do that:

Configuration ExampleConfig
{
    Node "localhost"
    {
        LocalConfigurationManager
        {
            DebugMode = $true
        }
    }
}

# The following line invokes the configuration and creates a file called localhost.meta.mof at the specified path
ExampleConfig -OutputPath "c:\users\public\dsc"

# Notice the use of Set-DSCLocalConfigurationManager
Set-DscLocalConfigurationManager -Path "c:\users\public\dsc"

If you are not using WMF5 CTP Release, then you have to fall back on killing the process hosting DSC. Here is a quick script to do that:

# find the Process that is hosting the DSC engine
$dscProcessID = Get-WmiObject msft_providers | 
  Where-Object {$_.provider -like 'dsccore'} | 
  Select-Object -ExpandProperty HostProcessIdentifier 

# Kill it
Get-Process -Id $dscProcessID | Stop-Process

KevMar_TcpPrinter v1.0.2

I just pushed an update to my TcpPrinter resource that can now handle basic driver installations. You can optionally provide a path to the inf files needed for the installation. The resource will try and use those if the driver does not exist.

There will be some limitations to this approach but I felt it was important to provide this option. For now, make sure the files are on the target system. You may have to use another resource to copy those files to the target.

Another change in this release is that Ensure="Absent" will try and remove the port and driver if they are not in use anymore. Should help to keep the system a little cleaner. I did add the requirement that the DriverInf property should be defined for it to remove a driver. This assumes that you installed the driver with this resource and can easily add it again. I also wanted to avoid removing any of the built in drivers.

Changes in v1.0.2
  Added DriverInf property
    Allows you to provide the location to the driver's inf file to be used during printer installation
  Modified Ensure="Absent"
    Will remove the printer port if the removed printer was the last one using it
    Will remove the driver only if the DriverInf is defined and the removed printer was the last one using it

https://github.com/kmarquette/Powershell

DSC Resource: KevMar_MapPrinter

Last week I put together a resource for adding TCP printers with Desired State Configuration. After I finished that one, I knew I needed to create another one that loads printers from a print server. They hand in hand even if they have different use cases. I can see using TcpPrinter for a print server and MapPrinter for a terminal server.

This one turned out to be much simpler to put together. I may end up doing a more detailed write up in the future just to show how easy it can be to create a DSC resource. Take a look at how simple the config looks for MapPrinter.

 
MapPrinter NetworkPrinter
       {
            Path = '\\server\EpsonPrinter'            
       }

It does not get much simpler than that. And removing a printer mapped this way is just as easy.

MapPrinter NetworkPrinter
       {
            Path   =  '\\server\EpsonPrinter'            
            Ensure = "Absent"
       }

This will map this printer for every user on the system. There is no way to target just a user with the method that I used. To correctly remove a printer mapped this way, it is best to use the DSC resource to do so. If you have to remove it by hand, here is the command that does the magic.

$path = "\\server\EpsonPrinter"
rundll32 printui.dll,PrintUIEntry /gd /n$path

It feels like the printer is slow to show up the first time this is ran. Restarting the spooler speeds up the process. I don't think the spooler immediately sees the changes.

The KevMar_MapPrinter was added to my other module that I have up on https://github.com/kmarquette/Powershell

DSC Resources: KevMar_TcpPrinter, KevMar_WindowsUpdate

I put together a set of Desired State Configuration Resources into a module. I was looking for a good project and I did not see any other resources that managed printers or Windows Updates yet.

KevMar_TcpPrinter

This is a printer management resource that will also create printer ports as needed. Most of the settings are optional as long as you specify the name, driver, and ip address of the printer.

At the moment, the driver already needs to be installed on the target node. Driver management is one of the next things for me to look at after I do some more testing.

KevMar_WindowsUpdates

The Windows Updates module is a composite module that wraps together several registry resources. Each of those properties maps to one or more registry keys that relates to automatic updates

I have all the code up on https://github.com/kmarquette/Powershell with some example configurations.

Why can't things just work?

I love to learn new things. I tend to dive in and just run with it. I just put together a new DSC resource for managing printers. Everything felt very solid as I was testing and things were just working. Running the Get,Set,and Test TargetResource commands by hand felt solid. Then I created my first config and pushed it with a Start-DscConfiguration. I ran into one small little issue that turned into a major road block.

How hard can it be to add a printer?

Under the hood, I was just using WMI to add printers and printer ports. I could easily update and delete existing printers. I could also create new printer ports without issue. My major road block was that my code to create a new printer would only fail when ran with Start-DscConfiguration. One little feature that is kind of critical to the whole project.

Win32_Printer.Put()

I was creating a new Win32_Printer object and using the .Put() command to save it. The error message I got was very nondescript. I used a try/catch block to report back the inner message of the exception. Access Denied is all it said.

I tried creating WMI objects different ways but I was not making any progress. I validated all the properties and tested setting more/less of them at once. I took a closer look at the .Put() command and found it had a putOptions overload. I had to track down how to create the right object because it didn't accept the raw int values. I discovered that there was a .psbase.put() command that I was not using before. Trial and error.

VBScript 

I also discovered that Powershell and VBScript use different wrappers for WMI objects. For some reason VBScript uses a .put_() command (yes, that underscore is intentional) to commit changes. I was able to use an existing VBScript in the Windows folder so I didn't have to write my own. It worked well enough with manual testing, but it also failed to work correctly when ran as a DscResource. I had hope that the different wrappers would somehow make a difference. But I was mistaken.

CIM_Printer

I would have loved to have used New-Printer but I am working with Windows 7. But that gave me an idea to look at the CIM instances. Again, a different wrapper. While the CIM_Printer class is easy to pull data out with, I don't think it was ever intended to be used for adding printers. I tried to create a new object but did not have much luck. As I explored the object, all the properties look to be read only. When trying to create a new one, it complains about the key fields missing. Yet when I tried to work that out, I didn't make any progress.

rundll32.exe

I figured there had to be some way to add a printer from the command line without using WMI. I tracked down a rundll32 command that I used in the past for other things (Rundll32 printui.dll,PrintUIEntry). I had a good feeling that it would have worked. I didn't like the required parameters as much. Mostly because it wanted more details around the driver than I was using. Something I could change, but it didn't feel as clean as I wanted this part to be. But it did give me another idea.

pInvoke

I started to look at system calls and found the AddPrinter that I was looking for. I required exactly what I wanted it to require. It was almost too good to be true. I was then looking at my next challenge. How do I pInvoke from Powershell? I found a little snip of code where they used C# to do the pInvoke from Powershell. That looked like as good of an approach as any.

C# and Powershell

I had my C# code fleshed out and needed to get it running in Powershell. I want to avoid having an external assembly so I had to figure out how to do it more inline. The Add-Type command turned out to be exactly what I was looking for. After importing my C# code, I was off an running.

It just works

I was able to drop it into my DSC resource with minimal adjustment and it worked perfectly. That last piece fell into place and my DSC resource was working wonderfully. This project started out as one of the most basic resources that I could think of and it ended up taking me on journey across many different technologies before I was done.

The end result is a TCPPrinter DSC resource that I have added to my KevMar modules.

Writing DSC Resources in C#

I wanted to mention this real quick so that I could find it later. The Powershell blog just mentioned that you can write DSC resources in C#.

http://blogs.msdn.com/b/powershell/archive/2014/05/29/wish-i-can-author-dsc-resource-in-c.aspx

Using Desired State Configuration to Set Local Passwords

DSC as a User resource that allows you to create and configure local accounts. While you can set the local account password this way, you have to store the password in plain text to do so. So if you decide to set the administrator password this way, the mof file on the machine will contain that password in plain text. This is a perfect example of just because you can do something, it does not mean that you should.

This turned out to be more complicated than I expected. I was able to find a post by Aman Dhally that dug into the details and this was the result.

$ConfigData = @{
    AllNodes = @( 
             @{ NodeName = "*"; PSDscAllowPlainTextPassword=$true }
             @{ NodeName = "localhost"; }
    );
}


Configuration LocalPasswordConfig
{
    $secpassword = ConvertTo-SecureString "Password1" -AsPlainText -Force
    $mycreds = New-Object System.Management.Automation.PSCredential("Administrator",$secpassword)

    Node $AllNodes.NodeName
    {
        User LocalAccount{
            UserName = "Administrator"
            Password = $mycreds
        }
    }
}

If you don't want to have your password in plain text in your config files, you can pass in a credential object. But the .mof file will still have the plain text password.

Configuration LocalPasswordConfig
{
    param([PsCredential]$mycreds)

    Node $AllNodes.NodeName
    {
        User LocalAccount{
            UserName = "Administrator"
            Password = $mycreds
        }
    }
}

$cred = Get-Credential
LocalPasswordConfig -mycreds $cred –ConfigurationData $ConfigData 

It may be possible to use a certificate to solve the pain text issue, but I am still trying to get my head wrapped around it. I see what looks like a good example here. See the example script at the bottom of that page.

Change Local Account Password

I wrote a CmdLet the other day to change the local account password. It was a good exercise in working with Powershell, but all the meat of the command boiled down to 2 lines of code.

$admin = [adsi]("WinNT://$ComputerName/$AccountName, user")
$admin.psbase.invoke("SetPassword", $Password)

While I was looking for that command, I remembered this other ways to do the same thing.

net user $account $password