EclipseRMM green eclipse symbolEclipseRMM

FIELD NOTES / POWERSHELL ADMINISTRATION

How to Restart a Service Remotely with PowerShell (Safely, with -WhatIf and Verification)

To restart a service remotely with PowerShell, run Restart-Service inside Invoke-Command: Invoke-Command -ComputerName PC01 -ScriptBlock { Restart-Service -Name Spooler -PassThru }. In PowerShell 6.0 and later, Restart-Service no longer has a -ComputerName parameter, so Microsoft's documentation says to use Invoke-Command to target a remote system. This guide adds the steps that make a remote restart safe: confirm the exact service name, check what depends on it, preview with -WhatIf, restart, and then verify that the service is really running again.

What Restart-Service actually does

Microsoft describes Restart-Service as sending "a stop message and then a start message to the Windows Service Controller for a specified service". Two details from the reference matter on remote computers:

The cmdlet can control services only when the current user has permission to do so. If a restart fails, permissions are the first thing to check.

Step 1: confirm the service name and current state

Service names and display names differ. Restart-Service accepts either, through -Name or -DisplayName, and both accept wildcards. On a remote computer a wildcard can match more services than you expect, so read first and restart by exact name:

Invoke-Command -ComputerName PC01 -ScriptBlock {
    Get-Service -DisplayName '*print*'
} | Select-Object PSComputerName, Status, Name, DisplayName

Results from Invoke-Command carry a PSComputerName property, so each line shows which computer it came from. Our guide on how to check service status with PowerShell covers reading the start mode, account and last exit code before you decide a restart is needed.

Step 2: check dependent services

Some services have other services that depend on them. Stopping the parent affects them too, so look before you restart:

Invoke-Command -ComputerName PC01 -ScriptBlock {
    Get-Service -Name LanmanServer -DependentServices
} | Select-Object PSComputerName, Status, Name

Restart-Service and Stop-Service both have a -Force switch, and the documentation describes it differently for each. For Stop-Service, it "forces the cmdlet to stop a service even if that service has dependent services". For Restart-Service, it "forces the command to run without asking for user confirmation". In either case, -Force skips a safety pause. Use it only after you have read the dependent list and know the effect on the people using that computer.

Step 3: preview the restart with -WhatIf

Restart-Service supports the common -WhatIf parameter, which "shows what would happen if the cmdlet runs. The cmdlet is not run." Microsoft's own example of piping several services into Restart-Service adds: "In practice, you would use the WhatIf parameter to determine the effect of the command before you run it." That advice matters most when the name comes from a filter:

Invoke-Command -ComputerName PC01 -ScriptBlock {
    Get-Service -Name 'net*' |
        Where-Object { $_.Status -eq 'Stopped' } |
        Restart-Service -WhatIf
}

The output lists each service the command would act on. If the list contains anything unexpected, change the filter and preview again. Nothing has been restarted at this point.

Step 4: restart the service remotely with PowerShell

When the preview looks right, remove -WhatIf and add -PassThru so the command returns the service's state:

Invoke-Command -ComputerName PC01 -ScriptBlock {
    Restart-Service -Name Spooler -PassThru
} | Select-Object PSComputerName, Name, Status

To pass the service name from your own session, use the $Using: scope modifier. Without it, Microsoft notes, "all variables are assumed to be defined in the remote session":

$service = 'Spooler'
Invoke-Command -ComputerName PC01 -ScriptBlock {
    Restart-Service -Name $Using:service -PassThru
}

Windows PowerShell 5.1 and PowerShell 7

In Windows PowerShell 5.1, Restart-Service also has no -ComputerName parameter; that parameter exists on Get-Service in 5.1, but not on Restart-Service. Microsoft's notes on differences from Windows PowerShell confirm that -ComputerName was removed from the *-Service cmdlets "to encourage the consistent use of PSRP", and recommend Invoke-Command instead. The Invoke-Command pattern above works in both versions.

Step 5: verify the service is running again

A restart request is not the same as a healthy service. Some services take a while to start, and a service can start and then stop again. Wait for the state you expect, with a time limit, and report the result:

Invoke-Command -ComputerName PC01 -ScriptBlock {
    $svc = Get-Service -Name Spooler
    Restart-Service -InputObject $svc
    try {
        $svc.WaitForStatus('Running', [TimeSpan]::FromSeconds(30))
        'Running'
    } catch {
        "Did not reach Running within 30 seconds: $($svc.Status)"
    }
}

WaitForStatus is a .NET method on the service object. According to its reference, it "waits for the service to reach the specified status or for the specified time-out to expire", and it throws a TimeoutException when the time-out expires, which is why it sits inside try. If the service does not reach Running, read its exit code with Get-CimInstance -ClassName Win32_Service, as shown in the service status guide, before trying again.

Restart a service on many computers

Invoke-Command accepts a list of computers and, by default, opens up to 32 connections at once (the -ThrottleLimit default). This version previews first, restarts only when you set $apply, and reports computers that did not answer:

$computers = 'PC01', 'PC02', 'PC03'
$service   = 'Spooler'
$apply     = $false   # set to $true after reviewing the preview

$results = Invoke-Command -ComputerName $computers -ErrorAction SilentlyContinue -ScriptBlock {
    $svc = Get-Service -Name $Using:service -ErrorAction Stop
    if ($Using:apply) {
        Restart-Service -InputObject $svc
        try { $svc.WaitForStatus('Running', [TimeSpan]::FromSeconds(30)) } catch { }
        $svc.Refresh()
    } else {
        Restart-Service -InputObject $svc -WhatIf
    }
    [pscustomobject]@{ Name = $svc.Name; Status = $svc.Status; Applied = $Using:apply }
}

$results | Select-Object PSComputerName, Name, Status, Applied | Sort-Object PSComputerName
$computers | Where-Object { $_ -notin $results.PSComputerName }   # no answer: check by hand

Run it with $apply = $false, read the preview, then run it again with $apply = $true. Restart a single computer first when the service matters to users, and keep the read-check-change-read habit from our list of safe first PowerShell commands.

Remoting requirements

Invoke-Command -ComputerName uses PowerShell remoting over WinRM. Microsoft's about_Remote_Requirements says to connect with an account that is a member of the Administrators or Remote Management Users group on the remote computer, and that the permissions to run commands are set by the session configuration. If WinRM is not open on your workstations, our guide to PowerShell remote management without RDP compares the alternatives.

Restarting services through an RMM agent

An agent-based RMM delivers the command to a service already installed on each computer, so it does not depend on WinRM being enabled. With EclipseRMM's PowerShell RMM, you run authorized PowerShell such as the verification script above on enrolled Windows devices and review the output, errors and completion status in the portal. Points from the product pages that apply to service changes:

FAQ

Why does Restart-Service -ComputerName not work?

Because Restart-Service has no -ComputerName parameter in current documentation, in either PowerShell 7 or Windows PowerShell 5.1. Use Invoke-Command -ComputerName with Restart-Service in the script block.

Does Restart-Service start a stopped service?

Yes. Microsoft's reference says that if a service was already stopped, it is started without notifying you of an error. Check the status first if you need to know whether it had stopped.

How do I know the restart worked?

Add -PassThru to see the returned state, or wait for Running with WaitForStatus and a time-out, then read the status again. Don't rely on the absence of an error.

Is -Force safe to use?

Only once you know what it skips. Check dependent services with Get-Service -DependentServices and preview with -WhatIf first.