NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Process.GetProcessesByName (String)

Creates an array of Process components that are associated with process resources on the local computer. These process resources share the specified process name.

[Visual Basic]
Overloads Public Shared Function GetProcessesByName( _
   ByVal processName As String _
) As Process ()
[C#]
public static Process[] GetProcessesByName(
   string processName
);
[C++]
public: static Process* GetProcessesByName(
   String* processName
) [];
[JScript]
public static function GetProcessesByName(
   processName : String
) : Process[];

Parameters

processName
The friendly name of the process.

Return Value

An array of type Process that represents the process resources running the specified application or file.

Remarks

Use this method to create an array of new Process components and associate them with process resources that are all running the same executable file on the local computer. The process resources must already exist on the computer, because GetProcessesByName does not create backend resources, but rather associates them with application-generated Process components. A processName can be specified for an executable not currently running on the local computer, so the array can be empty when it returns from the method call.

The process name is a friendly name for the process, without the .exe extension or the path, such as "Outlook". GetProcessesByName is helpful for getting and manipulating all processes associated with the same executable file. For example, you can pass in an executable name as the processName parameter, in order to shut down all running instances of that executable.

While a process Id is unique to a single process resource on the system, multiple processes on the local computer can be running the application specified by the processName parameter. Therefore, GetProcessById returns one process at most, but GetProcessesByName returns an array containing all associated processes. You can query each of these processes in turn for their Id if you need to manipulate the process using standard API calls. You cannot access process resources through the process name alone, but once you have retrieved an array of Process components that have been associated with the process resources, you can start, terminate, and otherwise manipulate the backend resources.

Because the GetProcessesByName method is static (in Visual Basic Shared), you do not need to create an instance of the Process component before you call the method. You can call the method on the Process class itself.

If you do not specify a processName, an empty string ("") is assumed.

Example [Visual Basic]

The following example gets all processes on the local computer that are running the application specified by the procName parameter (in this example, "notepad"), and trying to close each one down in turn by calling CloseMainWindow. CloseMainWindow is a request to close down, so the procedure forces a close using Kill if the call to CloseMainWindow returns false.

This example assumes that the procName passed in refers to an application that has a graphical interface, and hence a message loop. CloseMainWindow requires the associated process to have a message loop in order to send a window close message to the process.

[Visual Basic]

Private Sub StopProcesses(ByVal procName As String)
    'Declare a new process component.
    Dim myproc As System.Diagnostics.Process

    'Get all instances of Notepad that are open, attempt to close them.
    For Each myproc In Process.GetProcessesByName(processName)
        If Not myproc.CloseMainWindow Then
'If closing is not successful, then force termination.
myproc.Kill
        End If
    Next
End Sub

See Also

Process Class | Process Members | System.Diagnostics Namespace | Process.GetProcessesByName Overload List | ProcessName | GetProcessById | GetProcesses | GetCurrentProcess