xtd - Reference Guide  0.1.0
Modern c++17/20 framework to create console, GUI and unit test applications on Windows, macOS, Linux, iOS and android.
Public Member Functions | List of all members
xtd::diagnostics::process_start_info Class Referencefinal

#include <process_start_info.h>

Definition

Specifies a set of values that are used when you start a process.

Namespace
xtd::diagnostics
Library
xtd.core
Remarks
xtd::diagnostics::process_start_info is used together with the xtd::diagnostics::process component. When you start a process using the xtd::diagnostics::process class, you have access to process information in addition to that available when attaching to a running process.
You can use the xtd::diagnostics::process_start_info class for better control over the process you start. You must at least set the xtd::diagnostics::process_start_info::file_name property, either manually or using the constructor. The file name is any application or document. Here a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the Folder Options dialog box, which is available through the operating system. The Advanced button leads to a dialog box that shows whether there is an open action associated with a specific registered file type.
In addition, you can set other properties that define actions to take with that file. You can specify a value specific to the type of the xtd::diagnostics::process_start_info::file_name property for the xtd::diagnostics::process_start_info::verb property. For example, you can specify "print" for a document type. Additionally, you can specify xtd::diagnostics::process_start_info::arguments property values to be command-line arguments to pass to the file's open procedure. For example, if you specify a text editor application in the xtd::diagnostics::process_start_info::file_name property, you can use the xtd::diagnostics::process_start_info::arguments property to specify a text file to be opened by the editor.
Standard input is usually the keyboard, and standard output and standard error are usually the monitor screen. However, you can use the xtd::diagnostics::process_start_info::redirect_standard_input, xtd::diagnostics::process_start_info::redirect_standard_output, and xtd::diagnostics::process_start_info::redirect_standard_error properties to cause the process to get input from or return output to a file or other device. If you use the xtd::diagnostics::process::standard_input, xtd::diagnostics::process::standard_output, or xtd::diagnostics::process::standard_error properties on the xtd::diagnostics::process component, you must first set the corresponding value on the xtd::diagnostics::process_start_info property. Otherwise, the system throws an exception when you read or write to the stream.
Set xtd::diagnostics::process_start_info::use_shell_execute to specify whether to start the process by using the operating system shell.
You can change the value of any process_start_info property up to the time that the process starts. After you start the process, changing these values has no effect.

Public Member Functions

 process_start_info ()=default
 Initializes a new instance of the xtd::diagnostics::process_start_info class without specifying a file name with which to start the process. More...
 
 process_start_info (const xtd::ustring &file_name)
 Initializes a new instance of the xtd::diagnostics::process_start_info class and specifies a file name such as an application or document with which to start the process. More...
 
 process_start_info (const xtd::ustring &file_name, const xtd::ustring &arguments)
 Initializes a new instance of the xtd::diagnostics::process_start_info class, specifies an application file name with which to start the process, and specifies a set of command-line arguments_ to pass to the application. More...
 
const xtd::ustringarguments () const
 Gets the set of command-line arguments to use when starting the application. More...
 
process_start_infoarguments (const xtd::ustring &value)
 Sets the set of command-line arguments to use when starting the application. More...
 
bool create_no_window () const
 Gets a value indicating whether to start the process in a new window. More...
 
process_start_infocreate_no_window (bool value)
 Sets a value indicating whether to start the process in a new window. More...
 
const xtd::ustringdomain () const
 Gets a value that identifies the domain to use when starting the process. More...
 
process_start_infodomain (const xtd::ustring &value)
 Sets a value that identifies the domain to use when starting the process. More...
 
const std::map< xtd::ustring, xtd::ustring > & environment () const
 Gets the environment variables that apply to this process and its child processes. More...
 
std::map< xtd::ustring, xtd::ustring > & environment ()
 Gets the environment variables that apply to this process and its child processes. More...
 
const std::map< xtd::ustring, xtd::ustring > & environment_variables () const
 Gets search paths for files, directories for temporary files, application-specific options, and other similar information. More...
 
std::map< xtd::ustring, xtd::ustring > & environment_variables ()
 Gets search paths for files, directories for temporary files, application-specific options, and other similar information. More...
 
bool error_dialog () const
 Gets a value indicating whether an error dialog box is displayed to the user if the process cannot be started. More...
 
process_start_infoerror_dialog (bool value)
 Sets a value indicating whether an error dialog box is displayed to the user if the process cannot be started. More...
 
intptr_t error_dialog_parent_handle () const
 Gets the window handle to use when an error dialog box is shown for a process that cannot be started. More...
 
process_start_infoerror_dialog_parent_handle (intptr_t value)
 Sets the window handle to use when an error dialog box is shown for a process that cannot be started. More...
 
const xtd::ustringfile_name () const
 Gets the application or document to start. More...
 
process_start_infofile_name (const xtd::ustring &value)
 Sets the application or document to start. More...
 
process_start_infofile_name (const std::filesystem::path &value)
 Sets the application or document to start. More...
 
bool load_user_profile () const
 Gets a value that indicates whether the Windows user profile is to be loaded from the registry. More...
 
process_start_infoload_user_profile (bool value)
 Sets a value that indicates whether the Windows user profile is to be loaded from the registry. More...
 
const xtd::security::secure_stringpassword () const
 Gets a secure string that contains the user password to use when starting the process. More...
 
process_start_infopassword (const xtd::security::secure_string &value)
 Sets a secure string that contains the user password to use when starting the process. More...
 
xtd::ustring password_in_clear_text () const
 Gets the user password in clear text to use when starting the process. More...
 
process_start_infopassword_in_clear_text (const xtd::ustring &value)
 Sets the user password in clear text to use when starting the process. More...
 
bool redirect_standard_error () const
 Gets a value that indicates whether the error output of an application is written to the xtd::diagnostics::process::standard_error stream. More...
 
process_start_inforedirect_standard_error (bool value)
 Sets a value that indicates whether the error output of an application is written to the xtd::diagnostics::process::standard_error stream. More...
 
bool redirect_standard_input () const
 Gets a value indicating whether the input for an application is read from the Process.StandardInput stream. More...
 
process_start_inforedirect_standard_input (bool value)
 Sts a value indicating whether the input for an application is read from the Process.StandardInput stream. More...
 
bool redirect_standard_output () const
 Gets a value that indicates whether the textual output of an application is written to the xtd::diagnostics::process::standard_output stream. More...
 
process_start_inforedirect_standard_output (bool value)
 Sets a value that indicates whether the textual output of an application is written to the xtd::diagnostics::process::standard_output stream. More...
 
bool use_shell_execute () const
 Gets a value indicating whether to use the operating system shell to start the process. More...
 
process_start_infouse_shell_execute (bool value)
 Sets a value indicating whether to use the operating system shell to start the process. More...
 
const xtd::ustringuser_name () const
 Gets the user name to be used when starting the process. More...
 
process_start_infouser_name (const xtd::ustring &value)
 Sets the user name to be used when starting the process. More...
 
xtd::ustring verb () const
 Gets the verb to use when opening the application or document specified by the FileName property. More...
 
process_start_infoverb (const xtd::ustring &value)
 Sts the verb to use when opening the application or document specified by the FileName property. More...
 
std::vector< xtd::ustringverbs () const
 Gets the set of verbs associated with the type of file specified by the xtd::diagnostics::process_start_info::file_name property. More...
 
xtd::diagnostics::process_window_style window_style () const
 Gets the window state to use when the process is started. More...
 
process_start_infowindow_style (xtd::diagnostics::process_window_style value)
 Sets the window state to use when the process is started. More...
 
const xtd::ustringworking_directory () const
 When the xtd::diagnostics::process_start_info::use_shell_execute property is false, gets or sets the working directory for the process to be started. When xtd::diagnostics::process_start_info::use_shell_execute is true, gets or sets the directory that contains the process to be started. More...
 
process_start_infoworking_directory (const xtd::ustring &value)
 When the xtd::diagnostics::process_start_info::use_shell_execute property is false, gets or sets the working directory for the process to be started. When xtd::diagnostics::process_start_info::use_shell_execute is true, gets or sets the directory that contains the process to be started. More...
 
- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object. More...
 
virtual bool equals (const object &obj) const noexcept
 Determines whether the specified object is equal to the current object. More...
 
virtual size_t get_hash_code () const noexcept
 Serves as a hash function for a particular type. More...
 
template<typename object_t >
std::unique_ptr< object_t > memberwise_clone () const
 Gets the type of the current instance. More...
 
virtual xtd::ustring to_string () const noexcept
 Returns a std::string that represents the current object. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from xtd::object
static bool equals (const object &object_a, const object &object_b) noexcept
 Determines whether the specified object instances are considered equal. More...
 
static bool reference_equals (const object &object_a, const object &object_b) noexcept
 Determines whether the specified object instances are the same instance. More...
 

Constructor & Destructor Documentation

◆ process_start_info() [1/3]

xtd::diagnostics::process_start_info::process_start_info ( )
default

Initializes a new instance of the xtd::diagnostics::process_start_info class without specifying a file name with which to start the process.

Remarks
You must set at least the xtd::diagnostics::process_start_info::file_name property before you start the process. The file name is any application or document. In this case, a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the Folder Options dialog box, which is available through the operating system. The Advanced button leads to a dialog box that shows whether there is an open action associated with a specific registered file type.
Optionally, you can also set other properties before you start the process. The xtd::diagnostics::process_start_info::verb property supplies actions to take, such as "print", with the file indicated in the xtd::diagnostics::process_start_info::file_name property. The xtd::diagnostics::process_start_info::arguments property supplies a way to pass command-line arguments_ to the file when the system opens it.

◆ process_start_info() [2/3]

xtd::diagnostics::process_start_info::process_start_info ( const xtd::ustring file_name)
explicit

Initializes a new instance of the xtd::diagnostics::process_start_info class and specifies a file name such as an application or document with which to start the process.

Parameters
file_name_An application or document with which to start a process.
Remarks
The file name is any application or document. In this case, a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the Folder Options dialog box, which is available through the operating system. The Advanced button leads to a dialog box that shows whether there is an open action associated with a specific registered file type.
You can change the xtd::diagnostics::process_start_info::file_name property after you call this constructor, up to the time that the process starts. After you start the process, changing these values has no effect.

◆ process_start_info() [3/3]

xtd::diagnostics::process_start_info::process_start_info ( const xtd::ustring file_name,
const xtd::ustring arguments 
)

Initializes a new instance of the xtd::diagnostics::process_start_info class, specifies an application file name with which to start the process, and specifies a set of command-line arguments_ to pass to the application.

Parameters
file_nameAn application with which to start a process.
argumentsCommand-line arguments to pass to the application when the process starts.
Remarks
The file name is any application or document. In this case, a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the Folder Options dialog box, which is available through the operating system. The Advanced button leads to a dialog box that shows whether there is an open action associated with a specific registered file type.
You can change the xtd::diagnostics::process_start_info::file_name or xtd::diagnostics::process_start_info::arguments properties after you call this constructor, up to the time that the process starts. After you start the process, changing these values has no effect.

Member Function Documentation

◆ arguments() [1/2]

const xtd::ustring& xtd::diagnostics::process_start_info::arguments ( ) const

Gets the set of command-line arguments to use when starting the application.

Returns
File type–specific arguments that the system can associate with the application specified in the xtd::diagnostics::process_start_info::file_name property. The default is an empty string ("").

◆ arguments() [2/2]

process_start_info& xtd::diagnostics::process_start_info::arguments ( const xtd::ustring value)

Sets the set of command-line arguments to use when starting the application.

Parameters
valueFile type–specific arguments that the system can associate with the application specified in the xtd::diagnostics::process_start_info::file_name property. The default is an empty string ("").
Returns
The current instance of process_start_info.

◆ create_no_window() [1/2]

bool xtd::diagnostics::process_start_info::create_no_window ( ) const

Gets a value indicating whether to start the process in a new window.

Returns
true if the process should be started without creating a new window to contain it; otherwise, false. The default is false.
Remarks
If the xtd::diagnostics::process_start_info::use_shell_execute property is true or the xtd::diagnostics::process_start_info::user_name and xtd::diagnostics::process_start_info::password properties are not empty, the xtd::diagnostics::process_start_info::create_no_window property value is ignored and a new window is created.

◆ create_no_window() [2/2]

process_start_info& xtd::diagnostics::process_start_info::create_no_window ( bool  value)

Sets a value indicating whether to start the process in a new window.

Parameters
valuetrue if the process should be started without creating a new window to contain it; otherwise, false. The default is false.
Returns
The current instance of process_start_info.
Remarks
If the xtd::diagnostics::process_start_info::use_shell_execute property is true or the xtd::diagnostics::process_start_info::user_name and xtd::diagnostics::process_start_info::password properties are not empty, the xtd::diagnostics::process_start_info::create_no_window property value is ignored and a new window is created.

◆ domain() [1/2]

const xtd::ustring& xtd::diagnostics::process_start_info::domain ( ) const

Gets a value that identifies the domain to use when starting the process.

Returns
The Active Directory Domain to use when starting the process. The xtd::diagnostics::process_start_info::domain property is primarily of interest to users within enterprise environments that use Active Directory.

◆ domain() [2/2]

process_start_info& xtd::diagnostics::process_start_info::domain ( const xtd::ustring value)

Sets a value that identifies the domain to use when starting the process.

Parameters
valueThe Active Directory Domain to use when starting the process. The xtd::diagnostics::process_start_info::domain property is primarily of interest to users within enterprise environments that use Active Directory.
Returns
The current instance of process_start_info.

◆ environment() [1/2]

const std::map<xtd::ustring, xtd::ustring>& xtd::diagnostics::process_start_info::environment ( ) const

Gets the environment variables that apply to this process and its child processes.

Returns
std::map<xtd::ustring, xtd::ustring> A generic dictionary containing the environment variables that apply to this process and its child processes.
Remarks
The environment variables contain search paths for files, directories for temporary files, application-specific options, and other similar information. Although you cannot directly set the xtd::diagnostics::process_start_info::environment property, you can modify the generic dictionary returned by the property. For example, the following code adds a TempPath environment variable:
my_process.start_info().environment().insert({"TempPath", "C:\\Temp"}); 
. You must set the xtd::diagnostics::process_start_info::use_shell_execute property to false to start the process after changing the xtd::diagnostics::process_start_info::environment property. If xtd::diagnostics::process_start_info:use_shell_execute is true, an xtd::invalid_operation_exception is thrown when the xtd::diagnostics::process::start method is called.
An applications, using the xtd::diagnostics::process_start_info::environment property is the same as using the xtd::diagnostics::process_start_info::environment_variables property.

◆ environment() [2/2]

std::map<xtd::ustring, xtd::ustring>& xtd::diagnostics::process_start_info::environment ( )

Gets the environment variables that apply to this process and its child processes.

Returns
std::map<xtd::ustring, xtd::ustring> A generic dictionary containing the environment variables that apply to this process and its child processes.
Remarks
The environment variables contain search paths for files, directories for temporary files, application-specific options, and other similar information. Although you cannot directly set the xtd::diagnostics::process_start_info::environment property, you can modify the generic dictionary returned by the property. For example, the following code adds a TempPath environment variable:
my_process.start_info().environment().insert({"TempPath", "C:\\Temp"}); 
. You must set the xtd::diagnostics::process_start_info::use_shell_execute property to false to start the process after changing the xtd::diagnostics::process_start_info::environment property. If xtd::diagnostics::process_start_info:use_shell_execute is true, an xtd::invalid_operation_exception is thrown when the xtd::diagnostics::process::start method is called.
An applications, using the xtd::diagnostics::process_start_info::environment property is the same as using the xtd::diagnostics::process_start_info::environment_variables property.

◆ environment_variables() [1/2]

const std::map<xtd::ustring, xtd::ustring>& xtd::diagnostics::process_start_info::environment_variables ( ) const

Gets search paths for files, directories for temporary files, application-specific options, and other similar information.

Returns
std::map<xtd::ustring, xtd::ustring> A string dictionary that provides environment variables that apply to this process and child processes. The default is empty.
Remarks
Although you cannot set the xtd::diagnostics::process_start_info::environment_variables property, you can modify the generic disctionary returned by the property. For example, the following code adds a TempPath environment variable:
my_process.startInfo().environment_variables().insert({"TempPath", "C:\\Temp"}); 
. You must set the xtd::diagnostics::process_start_info::use_shell_execute property to false to start the process after changing the xtd::diagnostics::process_start_info::environment_variables property. If xtd::diagnostics::process_start_info::use_shell_execute is true, an xtd::invalid_operation_exception is thrown when the xtd::diagnostics::process::start method is called.

◆ environment_variables() [2/2]

std::map<xtd::ustring, xtd::ustring>& xtd::diagnostics::process_start_info::environment_variables ( )

Gets search paths for files, directories for temporary files, application-specific options, and other similar information.

Returns
std::map<xtd::ustring, xtd::ustring> A string dictionary that provides environment variables that apply to this process and child processes. The default is empty.
Remarks
Although you cannot set the xtd::diagnostics::process_start_info::environment_variables property, you can modify the generic disctionary returned by the property. For example, the following code adds a TempPath environment variable:
my_process.startInfo().environment_variables().insert({"TempPath", "C:\\Temp"}); 
. You must set the xtd::diagnostics::process_start_info::use_shell_execute property to false to start the process after changing the xtd::diagnostics::process_start_info::environment_variables property. If xtd::diagnostics::process_start_info::use_shell_execute is true, an xtd::invalid_operation_exception is thrown when the xtd::diagnostics::process::start method is called.

◆ error_dialog() [1/2]

bool xtd::diagnostics::process_start_info::error_dialog ( ) const

Gets a value indicating whether an error dialog box is displayed to the user if the process cannot be started.

Returns
true if an error dialog box should be displayed on the screen if the process cannot be started; otherwise, false. The default is false.
Note
xtd::diagnostics::process_start_info::use_shell_execute must be true if you want to set xtd::diagnostics::process_start_info::error_dialog to true.

◆ error_dialog() [2/2]

process_start_info& xtd::diagnostics::process_start_info::error_dialog ( bool  value)

Sets a value indicating whether an error dialog box is displayed to the user if the process cannot be started.

Parameters
valuetrue if an error dialog box should be displayed on the screen if the process cannot be started; otherwise, false. The default is false.
Returns
The current instance of process_start_info.
Note
xtd::diagnostics::process_start_info::use_shell_execute must be true if you want to set xtd::diagnostics::process_start_info::error_dialog to true.

◆ error_dialog_parent_handle() [1/2]

intptr_t xtd::diagnostics::process_start_info::error_dialog_parent_handle ( ) const

Gets the window handle to use when an error dialog box is shown for a process that cannot be started.

Returns
A pointer to the handle of the error dialog box that results from a process start failure.
Remarks
If xtd::diagnostics::process_start_info::error_dialog is true, the xtd::diagnostics::process_start_info::error_dialog_parent_handle property specifies the parent window for the dialog box that is shown. It is useful to specify a parent to keep the dialog box in front of the application.

◆ error_dialog_parent_handle() [2/2]

process_start_info& xtd::diagnostics::process_start_info::error_dialog_parent_handle ( intptr_t  value)

Sets the window handle to use when an error dialog box is shown for a process that cannot be started.

Parameters
valueA pointer to the handle of the error dialog box that results from a process start failure.
Returns
The current instance of process_start_info.
Remarks
If xtd::diagnostics::process_start_info::error_dialog is true, the xtd::diagnostics::process_start_info::error_dialog_parent_handle property specifies the parent window for the dialog box that is shown. It is useful to specify a parent to keep the dialog box in front of the application.

◆ file_name() [1/3]

const xtd::ustring& xtd::diagnostics::process_start_info::file_name ( ) const

Gets the application or document to start.

Returns
The name of the application to start, or the name of a document of a file type that is associated with an application and that has a default open action available to it. The default is an empty string ("").
Remarks
You must set at least the xtd::diagnostics::process_start_info::file_name property before you start the process. The file name is any application or document. A document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the Folder Options dialog box, which is available through the operating system. The Advanced button leads to a dialog box that shows whether there is an open action associated with a specific registered file type.
The set of file types available to you depends in part on the value of the xtd::diagnostics::process_start_info::use_shell_execute property. If xtd::diagnostics::process_start_info::use_shell_execute is true, you can start any document and perform operations on the file, such as printing, with the xtd::diagnostics::process component. When xtd::diagnostics::process_start_info::use_shell_execute is false, you can start only executables with the xtd::diagnostics::process component.

◆ file_name() [2/3]

process_start_info& xtd::diagnostics::process_start_info::file_name ( const xtd::ustring value)

Sets the application or document to start.

Parameters
valuestring The name of the application to start, or the name of a document of a file type that is associated with an application and that has a default open action available to it. The default is an empty string ("").
Returns
The current instance of process_start_info.
Remarks
You must set at least the xtd::diagnostics::process_start_info::file_name property before you start the process. The file name is any application or document. A document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the Folder Options dialog box, which is available through the operating system. The Advanced button leads to a dialog box that shows whether there is an open action associated with a specific registered file type.
The set of file types available to you depends in part on the value of the xtd::diagnostics::process_start_info::use_shell_execute property. If xtd::diagnostics::process_start_info::use_shell_execute is true, you can start any document and perform operations on the file, such as printing, with the xtd::diagnostics::process component. When xtd::diagnostics::process_start_info::use_shell_execute is false, you can start only executables with the xtd::diagnostics::process component.

◆ file_name() [3/3]

process_start_info& xtd::diagnostics::process_start_info::file_name ( const std::filesystem::path &  value)

Sets the application or document to start.

Parameters
valuestring The name of the application to start, or the name of a document of a file type that is associated with an application and that has a default open action available to it. The default is an empty string ("").
Returns
The current instance of process_start_info.
Remarks
You must set at least the xtd::diagnostics::process_start_info::file_name property before you start the process. The file name is any application or document. A document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the Folder Options dialog box, which is available through the operating system. The Advanced button leads to a dialog box that shows whether there is an open action associated with a specific registered file type.
The set of file types available to you depends in part on the value of the xtd::diagnostics::process_start_info::use_shell_execute property. If xtd::diagnostics::process_start_info::use_shell_execute is true, you can start any document and perform operations on the file, such as printing, with the xtd::diagnostics::process component. When xtd::diagnostics::process_start_info::use_shell_execute is false, you can start only executables with the xtd::diagnostics::process component.

◆ load_user_profile() [1/2]

bool xtd::diagnostics::process_start_info::load_user_profile ( ) const

Gets a value that indicates whether the Windows user profile is to be loaded from the registry.

Returns
true if the Windows user profile should be loaded; otherwise, false. The default is false.
Remarks
This property is referenced if the process is being started by using the user name, password, and domain.
If the value is true, the user's profile in the HKEY_USERS registry key is loaded. Loading the profile can be time-consuming. Therefore, it is best to use this value only if you must access the information in the HKEY_CURRENT_USER registry key.

◆ load_user_profile() [2/2]

process_start_info& xtd::diagnostics::process_start_info::load_user_profile ( bool  value)

Sets a value that indicates whether the Windows user profile is to be loaded from the registry.

Parameters
valuetrue if the Windows user profile should be loaded; otherwise, false. The default is false.
Returns
The current instance of process_start_info.
Remarks
This property is referenced if the process is being started by using the user name, password, and domain.
If the value is true, the user's profile in the HKEY_USERS registry key is loaded. Loading the profile can be time-consuming. Therefore, it is best to use this value only if you must access the information in the HKEY_CURRENT_USER registry key.

◆ password() [1/2]

const xtd::security::secure_string& xtd::diagnostics::process_start_info::password ( ) const

Gets a secure string that contains the user password to use when starting the process.

Returns
The user password to use when starting the process.
Important
The xtd::diagnostics::process_start_info::working_directory property must be set if xtd::diagnostics::process_start_info::user_name and xtd::diagnostics::process_start_info::password are provided. If the property is not set, the default working directory is SYSTEMROOT%.
Note
Setting the xtd::diagnostics::process_start_info::domain, xtd::diagnostics::process_start_info::user_name, and the xtd::diagnostics::process_start_info::password properties in a xtd::diagnostics::process_start_info object is the recommended practice for starting a process with user credentials.
Remarks
A xtd::security::secure_string object is like a xtd::ustring object in that it has a text value. However, the value of a xtd::security::secure_string object is automatically encrypted, it can be modified until your application marks it as read-only, and it can be deleted from computer memory by either your application.
Note
If you provide a value for the xtd::diagnostics::process_start_info::password property, the xtd::diagnostics::process_start_info::use_shell_execute property must be false, o an xtd::invalid_operation_exception will be thrown when the xtd::diagnostics::process::start(process_start_info) method is called.

◆ password() [2/2]

process_start_info& xtd::diagnostics::process_start_info::password ( const xtd::security::secure_string value)

Sets a secure string that contains the user password to use when starting the process.

Parameters
valueThe user password to use when starting the process.
Returns
The current instance of process_start_info.
Important
The xtd::diagnostics::process_start_info::working_directory property must be set if xtd::diagnostics::process_start_info::user_name and xtd::diagnostics::process_start_info::password are provided. If the property is not set, the default working directory is SYSTEMROOT%.
Note
Setting the xtd::diagnostics::process_start_info::domain, xtd::diagnostics::process_start_info::user_name, and the xtd::diagnostics::process_start_info::password properties in a xtd::diagnostics::process_start_info object is the recommended practice for starting a process with user credentials.
Remarks
A xtd::security::secure_string object is like a xtd::ustring object in that it has a text value. However, the value of a xtd::security::secure_string object is automatically encrypted, it can be modified until your application marks it as read-only, and it can be deleted from computer memory by either your application.
Note
If you provide a value for the xtd::diagnostics::process_start_info::password property, the xtd::diagnostics::process_start_info::use_shell_execute property must be false, o an xtd::invalid_operation_exception will be thrown when the xtd::diagnostics::process::start(process_start_info) method is called.

◆ password_in_clear_text() [1/2]

xtd::ustring xtd::diagnostics::process_start_info::password_in_clear_text ( ) const

Gets the user password in clear text to use when starting the process.

Returns
The user password in clear text.

◆ password_in_clear_text() [2/2]

process_start_info& xtd::diagnostics::process_start_info::password_in_clear_text ( const xtd::ustring value)

Sets the user password in clear text to use when starting the process.

Parameters
valuestring The user password in clear text.
Returns
The current instance of process_start_info.

◆ redirect_standard_error() [1/2]

bool xtd::diagnostics::process_start_info::redirect_standard_error ( ) const

Gets a value that indicates whether the error output of an application is written to the xtd::diagnostics::process::standard_error stream.

Returns
true if error output should be written to xtd::diagnostics::process::standard_error; otherwise, false. The default is false.
Examples
The following example uses the net use command together with a user supplied argument to map a network resource. It then reads the standard error stream of the net command and writes it to console.
xtd::diagnostics::process_start_info my_process_start_info("net ", "use " + args[0]);
my_process_start_info.use_shell_execute(false);
my_process_start_info.redirect_standard_error(true);
my_process.start_info(my_process_start_info);
my_process.start();
xtd::io::stream_reader my_stream_reader(my_process.standard_error());
// Read the standard error of net.exe and write it on to console.
xtd::console::write_line(my_stream_reader.read_line());
}
Remarks
When a xtd::diagnostics::process writes text to its standard error stream, that text is normally displayed on the console. By redirecting the xtd::diagnostics::process::standard_error stream, you can manipulate or suppress the error output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file.
Note
To use xtd::diagnostics::process::standard_error, you must set xtd::diagnostics::process_start_info::use_shell_execute to false, and you must set xtd::diagnostics::process_start_info::redirect_standard_error to true. Otherwise, reading from the xtd::diagnostics::process::standard_error stream throws an exception.
Remarks
The redirected xtd::diagnostics::process::standard_error stream can be read synchronously or asynchronously. Methods such as xtd::io::stream_reader::read, xtd::io::stream_reader::read_line, and xtd::io::stream_reader::read_to_end perform synchronous read operations on the error output stream of the process. These synchronous read operations do not complete until the associated xtd::diagnostics::process writes to its xtd::diagnostics::process::standard_error stream, or closes the stream.
In contrast, xtd::diagnostics::process::begin_error_read_line starts asynchronous read operations on the xtd::diagnostics::process::standard_error stream. This method enables a designated event handler for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler.
Synchronous read operations introduce a dependency between the caller reading from the xtd::diagnostics::process::standard_error stream and the child process writing to that stream. These dependencies can result in deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits on the read operation until the child writes to the stream or closes the stream. When the child process writes enough data to fill its redirected stream, it is dependent on the parent. The child process waits on the next write operation until the parent reads from the full stream or closes the stream. The deadlock condition results when the caller and child process wait on each other to complete an operation, and neither can proceed. You can avoid deadlocks by evaluating dependencies between the caller and child process.
The last two examples in this section use the xtd::diagnostics:process::start method to launch an executable named Write500Lines.exe. The following example contains its source code.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
int main() {
for (int ctr = 0; ctr < 500; ctr++)
console::write_line("Line {} of 500 written: {:P2}", ctr + 1, (ctr + 1)/500.0);
console::error << "\nSuccessfully wrote 500 lines.\n";
}
// The example displays the following output:
// The last 40 characters in the output stream are:
// ': 99.80%
// Line 500 of 500 written: 100.00%
// '
//
// Successfully wrote 500 lines.
The following example shows how to read from a redirected error stream and wait for the child process to exit. It avoids a deadlock condition by calling stream_reader(p.standard_error()).read_to_end() before p.wait_for_exit. A deadlock condition can result if the parent process calls p.wait_for_exit before stream_reader(p.standard_error()).read_to_end() and the child process writes enough text to fill the redirected stream. The parent process would wait indefinitely for the child process to exit. The child process would wait indefinitely for the parent to read from the full xtd::diagnostics::process::standard_error stream.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
int main() {
auto p = process();
p.start_info().use_shell_execute(false);
p.start_info().redirect_standard_error(true);
p.start_info().file_name("write_500_lines");
p.start();
// To avoid deadlocks, always read the output stream first and then wait.
string output = stream_reader(p.standard_error()).read_to_end();
p.wait_for_exit();
console::write_line("\nError stream: {}", output);
}
// The end of the output produced by the example includes the following:
// Error stream: Successfully wrote 500 lines.
There is a similar issue when you read all text from both the standard output and standard error streams. The following example performs a read operation on both streams. It avoids the deadlock condition by performing asynchronous read operations on the xtd::diagnostics::process::standard_error stream. A deadlock condition results if the parent process calls stream_reader(p.standard_output()).read_to_end() followed by stream_reader(p.standard_error()).read_to_end() and the child process writes enough text to fill its error stream. The parent process would wait indefinitely for the child process to close its xtd::diagnostics::process::standard_output stream. The child process would wait indefinitely for the parent to read from the full xtd::diagnostics::process::standard_error stream.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
int main() {
auto p = process();
p.start_info().use_shell_execute(false);
p.start_info().redirect_standard_output(true);
string e_out;
p.start_info().redirect_standard_error(true);
p.error_data_recaived += [&](object& sender, const data_received_event_args& e) {
e_out += e.data();
};
p.start_info().file_name("write_500_lines");
p.start();
// To avoid deadlocks, always read the output stream first and then wait.
p.begin_error_read_line();
string output = stream_reader(p.standard_error()).read_to_end();
p.wait_for_exit();
console::write_line("\nError stream: {}", output);
}
// The example displays the following output:
// The last 40 characters in the output stream are:
// ': 99.80%
// Line 500 of 500 written: 100.00%
// '
//
// Error stream: Successfully wrote 500 lines.
You can use asynchronous read operations to avoid these dependencies and their deadlock potential. Alternately, you can avoid the deadlock condition by creating two threads and reading the output of each stream on a separate thread.
Note
You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a xtd::diagnostics::process is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow xtd::diagnostics::process::begin_error_read_line with a call to xtd::ioo::stream_reader::read_line on the xtd::diagnostics::process::standard_error stream, or vice versa. However, you can read two different streams in different modes. For example, you can call xtd::diagnostics::process::begin_output_read_line and then call xtd::io::sstream_reader::read_line for the xtd::diagnostics::process::standard_error stream.

◆ redirect_standard_error() [2/2]

process_start_info& xtd::diagnostics::process_start_info::redirect_standard_error ( bool  value)

Sets a value that indicates whether the error output of an application is written to the xtd::diagnostics::process::standard_error stream.

Parameters
valuetrue if error output should be written to xtd::diagnostics::process::standard_error; otherwise, false. The default is false.
Returns
The current instance of process_start_info.
Examples
The following example uses the net use command together with a user supplied argument to map a network resource. It then reads the standard error stream of the net command and writes it to console.
xtd::diagnostics::process_start_info my_process_start_info("net ", "use " + args[0]);
my_process_start_info.use_shell_execute(false);
my_process_start_info.redirect_standard_error(true);
my_process.start_info(my_process_start_info);
my_process.start();
xtd::io::stream_reader my_stream_reader(my_process.standard_error());
// Read the standard error of net.exe and write it on to console.
xtd::console::write_line(my_stream_reader.read_line());
}
Remarks
When a xtd::diagnostics::process writes text to its standard error stream, that text is normally displayed on the console. By redirecting the xtd::diagnostics::process::standard_error stream, you can manipulate or suppress the error output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file.
Note
To use xtd::diagnostics::process::standard_error, you must set xtd::diagnostics::process_start_info::use_shell_execute to false, and you must set xtd::diagnostics::process_start_info::redirect_standard_error to true. Otherwise, reading from the xtd::diagnostics::process::standard_error stream throws an exception.
Remarks
The redirected xtd::diagnostics::process::standard_error stream can be read synchronously or asynchronously. Methods such as xtd::io::stream_reader::read, xtd::io::stream_reader::read_line, and xtd::io::stream_reader::read_to_end perform synchronous read operations on the error output stream of the process. These synchronous read operations do not complete until the associated xtd::diagnostics::process writes to its xtd::diagnostics::process::standard_error stream, or closes the stream.
In contrast, xtd::diagnostics::process::begin_error_read_line starts asynchronous read operations on the xtd::diagnostics::process::standard_error stream. This method enables a designated event handler for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler.
Synchronous read operations introduce a dependency between the caller reading from the xtd::diagnostics::process::standard_error stream and the child process writing to that stream. These dependencies can result in deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits on the read operation until the child writes to the stream or closes the stream. When the child process writes enough data to fill its redirected stream, it is dependent on the parent. The child process waits on the next write operation until the parent reads from the full stream or closes the stream. The deadlock condition results when the caller and child process wait on each other to complete an operation, and neither can proceed. You can avoid deadlocks by evaluating dependencies between the caller and child process.
The last two examples in this section use the xtd::diagnostics:process::start method to launch an executable named Write500Lines.exe. The following example contains its source code.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
int main() {
for (int ctr = 0; ctr < 500; ctr++)
console::write_line("Line {} of 500 written: {:P2}", ctr + 1, (ctr + 1)/500.0);
console::error << "\nSuccessfully wrote 500 lines.\n";
}
// The example displays the following output:
// The last 40 characters in the output stream are:
// ': 99.80%
// Line 500 of 500 written: 100.00%
// '
//
// Successfully wrote 500 lines.
The following example shows how to read from a redirected error stream and wait for the child process to exit. It avoids a deadlock condition by calling stream_reader(p.standard_error()).read_to_end() before p.wait_for_exit. A deadlock condition can result if the parent process calls p.wait_for_exit before stream_reader(p.standard_error()).read_to_end() and the child process writes enough text to fill the redirected stream. The parent process would wait indefinitely for the child process to exit. The child process would wait indefinitely for the parent to read from the full xtd::diagnostics::process::standard_error stream.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
int main() {
auto p = process();
p.start_info().use_shell_execute(false);
p.start_info().redirect_standard_error(true);
p.start_info().file_name("write_500_lines");
p.start();
// To avoid deadlocks, always read the output stream first and then wait.
string output = stream_reader(p.standard_error()).read_to_end();
p.wait_for_exit();
console::write_line("\nError stream: {}", output);
}
// The end of the output produced by the example includes the following:
// Error stream: Successfully wrote 500 lines.
There is a similar issue when you read all text from both the standard output and standard error streams. The following example performs a read operation on both streams. It avoids the deadlock condition by performing asynchronous read operations on the xtd::diagnostics::process::standard_error stream. A deadlock condition results if the parent process calls stream_reader(p.standard_output()).read_to_end() followed by stream_reader(p.standard_error()).read_to_end() and the child process writes enough text to fill its error stream. The parent process would wait indefinitely for the child process to close its xtd::diagnostics::process::standard_output stream. The child process would wait indefinitely for the parent to read from the full xtd::diagnostics::process::standard_error stream.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
int main() {
auto p = process();
p.start_info().use_shell_execute(false);
p.start_info().redirect_standard_output(true);
string e_out;
p.start_info().redirect_standard_error(true);
p.error_data_recaived += [&](object& sender, const data_received_event_args& e) {
e_out += e.data();
};
p.start_info().file_name("write_500_lines");
p.start();
// To avoid deadlocks, always read the output stream first and then wait.
p.begin_error_read_line();
string output = stream_reader(p.standard_error()).read_to_end();
p.wait_for_exit();
console::write_line("\nError stream: {}", output);
}
// The example displays the following output:
// The last 40 characters in the output stream are:
// ': 99.80%
// Line 500 of 500 written: 100.00%
// '
//
// Error stream: Successfully wrote 500 lines.
You can use asynchronous read operations to avoid these dependencies and their deadlock potential. Alternately, you can avoid the deadlock condition by creating two threads and reading the output of each stream on a separate thread.
Note
You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a xtd::diagnostics::process is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow xtd::diagnostics::process::begin_error_read_line with a call to xtd::ioo::stream_reader::read_line on the xtd::diagnostics::process::standard_error stream, or vice versa. However, you can read two different streams in different modes. For example, you can call xtd::diagnostics::process::begin_output_read_line and then call xtd::io::sstream_reader::read_line for the xtd::diagnostics::process::standard_error stream.

◆ redirect_standard_input() [1/2]

bool xtd::diagnostics::process_start_info::redirect_standard_input ( ) const

Gets a value indicating whether the input for an application is read from the Process.StandardInput stream.

Returns
true if input should be read from Process.StandardInput; otherwise, false. The default is false.
Examples
The following example illustrates how to redirect the xtd::diagnostics::process::standard_input stream of a process. The example starts the sort command with redirected input. It then prompts the user for text, and passes that to the sort process by means of the redirected xtd::diagnostics::process::standard_input stream. The sort results are displayed to the user on the console.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
int main() {
console::write_line("Ready to sort one or more text lines...");
// Start the sort process with redirected input.
// Use the sort command to sort the input text.
using_(process my_process) {
my_process.start_info().file_name("sort");
my_process.start_info().use_shell_execute(false);
my_process.start_info().redirect_standard_input(true);
my_process.start();
stream_writer my_stream_writer(my_process.standard_input());
// Prompt the user for input text lines to sort.
// Write each line to the StandardInput stream of
// the sort command.
string input_text;
int num_lines = 0;
do {
console::write_line("Enter a line of text (or press the Enter key to stop):");
input_text = console::read_line();
if (input_text.size() > 0) {
num_lines++;
my_stream_writer.write_line(input_text);
}
} while (input_text.size() > 0);
// Write a report header to the console.
if (num_lines > 0) {
console::write_line(" {} sorted text line(s) ", num_lines);
console::write_line("------------------------");
} else {
console::write_line(" No input was sorted");
}
// End the input stream to the sort command.
// When the stream closes, the sort command
// writes the sorted text lines to the
// console.
my_stream_writer.close();
// Wait for the sort process to write the sorted text lines.
my_process.wait_for_exit();
}
}
Remarks
A xtd::diagnostics::process can read input text from its standard input stream, typically the keyboard. By redirecting the xtd::diagnostics::process::standard_input stream, you can programmatically specify the input. For example, instead of using keyboard input, you can provide text from the contents of a designated file or output from another application.
Note
To use xtd::diagnostics::process::standard_input, you must set xtd::diagnostics::process_start_info::use_shell_execute to false, and you must set xtd::diagnostics::process_start_info::redirect_standard_input to true. Otherwise, writing to the xtd::diagnostics::process::standard_input stream throws an exception.

◆ redirect_standard_input() [2/2]

process_start_info& xtd::diagnostics::process_start_info::redirect_standard_input ( bool  value)

Sts a value indicating whether the input for an application is read from the Process.StandardInput stream.

Parameters
valuetrue if input should be read from Process.StandardInput; otherwise, false. The default is false.
Returns
The current instance of process_start_info.
Examples
The following example illustrates how to redirect the xtd::diagnostics::process::standard_input stream of a process. The example starts the sort command with redirected input. It then prompts the user for text, and passes that to the sort process by means of the redirected xtd::diagnostics::process::standard_input stream. The sort results are displayed to the user on the console.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
int main() {
console::write_line("Ready to sort one or more text lines...");
// Start the sort process with redirected input.
// Use the sort command to sort the input text.
using_(process my_process) {
my_process.start_info().file_name("sort");
my_process.start_info().use_shell_execute(false);
my_process.start_info().redirect_standard_input(true);
my_process.start();
stream_writer my_stream_writer(my_process.standard_input());
// Prompt the user for input text lines to sort.
// Write each line to the StandardInput stream of
// the sort command.
string input_text;
int num_lines = 0;
do {
console::write_line("Enter a line of text (or press the Enter key to stop):");
input_text = console::read_line();
if (input_text.size() > 0) {
num_lines++;
my_stream_writer.write_line(input_text);
}
} while (input_text.size() > 0);
// Write a report header to the console.
if (num_lines > 0) {
console::write_line(" {} sorted text line(s) ", num_lines);
console::write_line("------------------------");
} else {
console::write_line(" No input was sorted");
}
// End the input stream to the sort command.
// When the stream closes, the sort command
// writes the sorted text lines to the
// console.
my_stream_writer.close();
// Wait for the sort process to write the sorted text lines.
my_process.wait_for_exit();
}
}
Remarks
A xtd::diagnostics::process can read input text from its standard input stream, typically the keyboard. By redirecting the xtd::diagnostics::process::standard_input stream, you can programmatically specify the input. For example, instead of using keyboard input, you can provide text from the contents of a designated file or output from another application.
Note
To use xtd::diagnostics::process::standard_input, you must set xtd::diagnostics::process_start_info::use_shell_execute to false, and you must set xtd::diagnostics::process_start_info::redirect_standard_input to true. Otherwise, writing to the xtd::diagnostics::process::standard_input stream throws an exception.

◆ redirect_standard_output() [1/2]

bool xtd::diagnostics::process_start_info::redirect_standard_output ( ) const

Gets a value that indicates whether the textual output of an application is written to the xtd::diagnostics::process::standard_output stream.

Returns
bool true if output should be written to xtd::diagnostics::process::standard_output; otherwise, false. The default is false.
Examplles
The following example runs the ipconfig.exe command and redirects its standard output to the example's console window.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
int main() {
using_(process process) {
process.start_info().file_name("ipconfig");
process.start_info().use_shell_execute(false);
process.start();
// Synchronously read the standard output of the spawned process.
stream_reader reader(process.standard_output());
string output = reader.read_to_end();
// Write the redirected output to this application's window.
process.wait_for_exit();
}
console::write_line("\n\nPress any key to exit.");
}
Remarks
When a xtd::diagnostics::processs writes text to its standard stream, that text is normally displayed on the console. By redirecting the xtd::diagnostics::processs::standard_output stream, you can manipulate or suppress the output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file.
Note
To use xtd::diagnostics::processs::standard_output, you must set xtd::diagnostics::process_start_info::use_shell_execute to false, and you must set xtd::diagnostics::process_start_info::redirect_standard_output to true. Otherwise, reading from the xtd::diagnostics::processs::standard_output stream throws an exception.
Remarks
The redirected xtd::diagnostics::processs::standard_output stream can be read synchronously or asynchronously. Methods such as xtd::io::stream_reader::read, xtd::io::stream_reader::read_line, and xtd::io::stream_reader::read_to_end perform synchronous read operations on the output stream of the process. These synchronous read operations do not complete until the associated Process writes to its xtd::diagnostics::processs::xtd::diagnostics::processs::standard_output stream, or closes the stream.
In contrast, xtd::diagnostics::processs::begin_output_read_line starts asynchronous read operations on the xtd::diagnostics::processs::standard_output stream. This method enables a designated event handler for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler.
Synchronous read operations introduce a dependency between the caller reading from the xtd::diagnostics::processs::standard_output stream and the child process writing to that stream. These dependencies can result in deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits on the read operation until the child writes to the stream or closes the stream. When the child process writes enough data to fill its redirected stream, it is dependent on the parent. The child process waits on the next write operation until the parent reads from the full stream or closes the stream. The deadlock condition results when the caller and child process wait on each other to complete an operation, and neither can proceed. You can avoid deadlocks by evaluating dependencies between the caller and child process.
The last two examples in this section use the xtd::diagnostics:process::start method to launch an executable named Write500Lines.exe. The following example contains its source code.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
int main() {
for (int ctr = 0; ctr < 500; ctr++)
console::write_line("Line {} of 500 written: {:P2}", ctr + 1, (ctr + 1)/500.0);
console::error << "\nSuccessfully wrote 500 lines.\n";
}
// The example displays the following output:
// The last 40 characters in the output stream are:
// ': 99.80%
// Line 500 of 500 written: 100.00%
// '
//
// Successfully wrote 500 lines.
The following example shows how to read from a redirected error stream and wait for the child process to exit. It avoids a deadlock condition by calling stream_reader(p.standard_error()).read_to_end() before p.wait_for_exit. A deadlock condition can result if the parent process calls p.wait_for_exit before stream_reader(p.standard_error()).read_to_end() and the child process writes enough text to fill the redirected stream. The parent process would wait indefinitely for the child process to exit. The child process would wait indefinitely for the parent to read from the full xtd::diagnostics::process::standard_error stream.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
int main() {
auto p = process();
p.start_info().use_shell_execute(false);
p.start_info().redirect_standard_error(true);
p.start_info().file_name("write_500_lines");
p.start();
// To avoid deadlocks, always read the output stream first and then wait.
string output = stream_reader(p.standard_error()).read_to_end();
p.wait_for_exit();
console::write_line("\nError stream: {}", output);
}
// The end of the output produced by the example includes the following:
// Error stream: Successfully wrote 500 lines.
There is a similar issue when you read all text from both the standard output and standard error streams. The following example performs a read operation on both streams. It avoids the deadlock condition by performing asynchronous read operations on the xtd::diagnostics::process::standard_error stream. A deadlock condition results if the parent process calls stream_reader(p.standard_output()).read_to_end() followed by stream_reader(p.standard_error()).read_to_end() and the child process writes enough text to fill its error stream. The parent process would wait indefinitely for the child process to close its xtd::diagnostics::process::standard_output stream. The child process would wait indefinitely for the parent to read from the full xtd::diagnostics::process::standard_error stream.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
int main() {
auto p = process();
p.start_info().use_shell_execute(false);
p.start_info().redirect_standard_output(true);
string e_out;
p.start_info().redirect_standard_error(true);
p.error_data_recaived += [&](object& sender, const data_received_event_args& e) {
e_out += e.data();
};
p.start_info().file_name("write_500_lines");
p.start();
// To avoid deadlocks, always read the output stream first and then wait.
p.begin_error_read_line();
string output = stream_reader(p.standard_error()).read_to_end();
p.wait_for_exit();
console::write_line("\nError stream: {}", output);
}
// The example displays the following output:
// The last 40 characters in the output stream are:
// ': 99.80%
// Line 500 of 500 written: 100.00%
// '
//
// Error stream: Successfully wrote 500 lines.
You can use asynchronous read operations to avoid these dependencies and their deadlock potential. Alternately, you can avoid the deadlock condition by creating two threads and reading the output of each stream on a separate thread.
Note
You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a xtd::diagnostics::processs is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow xtd::diagnostics::processs::begin_output_read_line with a call to xtd::io::stream_reader::read_line on the xtd::diagnostics::processs::standard_output stream, or vice versa. However, you can read two different streams in different modes. For example, you can call xtd::diagnostics::processs::begin_output_read_line and then call xtd::io::stream_reader::read_line for the xtd::diagnostics::processs::standard_error stream.

◆ redirect_standard_output() [2/2]

process_start_info& xtd::diagnostics::process_start_info::redirect_standard_output ( bool  value)

Sets a value that indicates whether the textual output of an application is written to the xtd::diagnostics::process::standard_output stream.

Parameters
valuetrue if output should be written to xtd::diagnostics::process::standard_output; otherwise, false. The default is false.
Returns
The current instance of process_start_info.
Examplles
The following example runs the ipconfig.exe command and redirects its standard output to the example's console window.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
int main() {
using_(process process) {
process.start_info().file_name("ipconfig");
process.start_info().use_shell_execute(false);
process.start();
// Synchronously read the standard output of the spawned process.
stream_reader reader(process.standard_output());
string output = reader.read_to_end();
// Write the redirected output to this application's window.
process.wait_for_exit();
}
console::write_line("\n\nPress any key to exit.");
}
Remarks
When a xtd::diagnostics::processs writes text to its standard stream, that text is normally displayed on the console. By redirecting the xtd::diagnostics::processs::standard_output stream, you can manipulate or suppress the output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file.
Note
To use xtd::diagnostics::processs::standard_output, you must set xtd::diagnostics::process_start_info::use_shell_execute to false, and you must set xtd::diagnostics::process_start_info::redirect_standard_output to true. Otherwise, reading from the xtd::diagnostics::processs::standard_output stream throws an exception.
Remarks
The redirected xtd::diagnostics::processs::standard_output stream can be read synchronously or asynchronously. Methods such as xtd::io::stream_reader::read, xtd::io::stream_reader::read_line, and xtd::io::stream_reader::read_to_end perform synchronous read operations on the output stream of the process. These synchronous read operations do not complete until the associated Process writes to its xtd::diagnostics::processs::xtd::diagnostics::processs::standard_output stream, or closes the stream.
In contrast, xtd::diagnostics::processs::begin_output_read_line starts asynchronous read operations on the xtd::diagnostics::processs::standard_output stream. This method enables a designated event handler for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler.
Synchronous read operations introduce a dependency between the caller reading from the xtd::diagnostics::processs::standard_output stream and the child process writing to that stream. These dependencies can result in deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits on the read operation until the child writes to the stream or closes the stream. When the child process writes enough data to fill its redirected stream, it is dependent on the parent. The child process waits on the next write operation until the parent reads from the full stream or closes the stream. The deadlock condition results when the caller and child process wait on each other to complete an operation, and neither can proceed. You can avoid deadlocks by evaluating dependencies between the caller and child process.
The last two examples in this section use the xtd::diagnostics:process::start method to launch an executable named Write500Lines.exe. The following example contains its source code.
#include <xtd/xtd>
using namespace xtd;
using namespace xtd::io;
int main() {
for (int ctr = 0; ctr < 500; ctr++)
console::write_line("Line {} of 500 written: {:P2}", ctr + 1, (ctr + 1)/500.0);
console::error << "\nSuccessfully wrote 500 lines.\n";
}
// The example displays the following output:
// The last 40 characters in the output stream are:
// ': 99.80%
// Line 500 of 500 written: 100.00%
// '
//
// Successfully wrote 500 lines.
The following example shows how to read from a redirected error stream and wait for the child process to exit. It avoids a deadlock condition by calling stream_reader(p.standard_error()).read_to_end() before p.wait_for_exit. A deadlock condition can result if the parent process calls p.wait_for_exit before stream_reader(p.standard_error()).read_to_end() and the child process writes enough text to fill the redirected stream. The parent process would wait indefinitely for the child process to exit. The child process would wait indefinitely for the parent to read from the full xtd::diagnostics::process::standard_error stream.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
int main() {
auto p = process();
p.start_info().use_shell_execute(false);
p.start_info().redirect_standard_error(true);
p.start_info().file_name("write_500_lines");
p.start();
// To avoid deadlocks, always read the output stream first and then wait.
string output = stream_reader(p.standard_error()).read_to_end();
p.wait_for_exit();
console::write_line("\nError stream: {}", output);
}
// The end of the output produced by the example includes the following:
// Error stream: Successfully wrote 500 lines.
There is a similar issue when you read all text from both the standard output and standard error streams. The following example performs a read operation on both streams. It avoids the deadlock condition by performing asynchronous read operations on the xtd::diagnostics::process::standard_error stream. A deadlock condition results if the parent process calls stream_reader(p.standard_output()).read_to_end() followed by stream_reader(p.standard_error()).read_to_end() and the child process writes enough text to fill its error stream. The parent process would wait indefinitely for the child process to close its xtd::diagnostics::process::standard_output stream. The child process would wait indefinitely for the parent to read from the full xtd::diagnostics::process::standard_error stream.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
int main() {
auto p = process();
p.start_info().use_shell_execute(false);
p.start_info().redirect_standard_output(true);
string e_out;
p.start_info().redirect_standard_error(true);
p.error_data_recaived += [&](object& sender, const data_received_event_args& e) {
e_out += e.data();
};
p.start_info().file_name("write_500_lines");
p.start();
// To avoid deadlocks, always read the output stream first and then wait.
p.begin_error_read_line();
string output = stream_reader(p.standard_error()).read_to_end();
p.wait_for_exit();
console::write_line("\nError stream: {}", output);
}
// The example displays the following output:
// The last 40 characters in the output stream are:
// ': 99.80%
// Line 500 of 500 written: 100.00%
// '
//
// Error stream: Successfully wrote 500 lines.
You can use asynchronous read operations to avoid these dependencies and their deadlock potential. Alternately, you can avoid the deadlock condition by creating two threads and reading the output of each stream on a separate thread.
Note
You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a xtd::diagnostics::processs is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow xtd::diagnostics::processs::begin_output_read_line with a call to xtd::io::stream_reader::read_line on the xtd::diagnostics::processs::standard_output stream, or vice versa. However, you can read two different streams in different modes. For example, you can call xtd::diagnostics::processs::begin_output_read_line and then call xtd::io::stream_reader::read_line for the xtd::diagnostics::processs::standard_error stream.

◆ use_shell_execute() [1/2]

bool xtd::diagnostics::process_start_info::use_shell_execute ( ) const

Gets a value indicating whether to use the operating system shell to start the process.

Returns
true if the shell should be used when starting the process; false if the process should be created directly from the executable file. The default is true.
Remarks
Setting this property to false enables you to redirect input, output, and error streams.
Note
xtd::diagnostics::process_start_info::use_shell_execute must be false if the xtd::diagnostics::process_start_info::user_name property is not an empty string, or an xtd::invalid_operation_exception will be thrown when the xtd::diagnostics::process::start(process_start_info) method is called.
Remarks
When you use the operating system shell to start processes, you can start any document (which is any registered file type associated with an executable that has a default open action) and perform operations on the file, such as printing, by using the Process object. When xtd::diagnostics::process_start_info::use_shell_execute is false, you can start only executables by using the xtd::diagnostics::process object.
Note
xtd::diagnostics::process_start_info::use_shell_execute must be true if you set the xtd::diagnostics::process_start_info::error_dialog property to true.
Remarks
The xtd::diagnostics::process_start_info::working_directory property behaves differently depending on the value of the xtd::diagnostics::process_start_info::use_shell_execute property. When xtd::diagnostics::process_start_info::use_shell_execute is true, the xtd::diagnostics::process_start_info::working_directory property specifies the location of the executable. If working_directory is an empty string, it is assumed that the current directory contains the executable.
When xtd::diagnostics::process_start_info::use_shell_execute is false, the xtd::diagnostics::process_start_info::working_directory property is not used to find the executable. Instead, it is used only by the process that is started and has meaning only within the context of the new process. When xtd::diagnostics::process_start_info::use_shell_xecute is false, the xtd::diagnostics::process_start_info::file_name property can be either a fully qualified path to the executable, or a simple executable name that the system will attempt to find within folders specified by the PATH environment variable.

◆ use_shell_execute() [2/2]

process_start_info& xtd::diagnostics::process_start_info::use_shell_execute ( bool  value)

Sets a value indicating whether to use the operating system shell to start the process.

Parameters
valuetrue if the shell should be used when starting the process; false if the process should be created directly from the executable file. The default is true.
Returns
The current instance of process_start_info.
Remarks
Setting this property to false enables you to redirect input, output, and error streams.
Note
xtd::diagnostics::process_start_info::use_shell_execute must be false if the xtd::diagnostics::process_start_info::user_name property is not an empty string, or an xtd::invalid_operation_exception will be thrown when the xtd::diagnostics::process::start(process_start_info) method is called.
Remarks
When you use the operating system shell to start processes, you can start any document (which is any registered file type associated with an executable that has a default open action) and perform operations on the file, such as printing, by using the Process object. When xtd::diagnostics::process_start_info::use_shell_execute is false, you can start only executables by using the xtd::diagnostics::process object.
Note
xtd::diagnostics::process_start_info::use_shell_execute must be true if you set the xtd::diagnostics::process_start_info::error_dialog property to true.
Remarks
The xtd::diagnostics::process_start_info::working_directory property behaves differently depending on the value of the xtd::diagnostics::process_start_info::use_shell_execute property. When xtd::diagnostics::process_start_info::use_shell_execute is true, the xtd::diagnostics::process_start_info::working_directory property specifies the location of the executable. If working_directory is an empty string, it is assumed that the current directory contains the executable.
When xtd::diagnostics::process_start_info::use_shell_execute is false, the xtd::diagnostics::process_start_info::working_directory property is not used to find the executable. Instead, it is used only by the process that is started and has meaning only within the context of the new process. When xtd::diagnostics::process_start_info::use_shell_xecute is false, the xtd::diagnostics::process_start_info::file_name property can be either a fully qualified path to the executable, or a simple executable name that the system will attempt to find within folders specified by the PATH environment variable.

◆ user_name() [1/2]

const xtd::ustring& xtd::diagnostics::process_start_info::user_name ( ) const

Gets the user name to be used when starting the process.

Returns
The user name to use when starting the process.
Important
The xtd::diagnostics::process_start_info::working_directory property must be set if xtd::diagnostics::process_start_info::user_name and xtd::diagnostics::process_start_info::password are provided. If the property is not set, the default working directory is SYSTEMROOT%.
Remarks
If the xtd::diagnostics::process_start_info::user_name property is not an empty string, the xtd::diagnostics::process_start_info::use_shell_execute property must be false, or an xtd::invalid_operation_exception will be thrown when the xtd::diagnostics::process::.start(xtd::diagnostics::process_start_info) method is called.

◆ user_name() [2/2]

process_start_info& xtd::diagnostics::process_start_info::user_name ( const xtd::ustring value)

Sets the user name to be used when starting the process.

Parameters
valueThe user name to use when starting the process.
Returns
The current instance of process_start_info.
Important
The xtd::diagnostics::process_start_info::working_directory property must be set if xtd::diagnostics::process_start_info::user_name and xtd::diagnostics::process_start_info::password are provided. If the property is not set, the default working directory is SYSTEMROOT%.
Remarks
If the xtd::diagnostics::process_start_info::user_name property is not an empty string, the xtd::diagnostics::process_start_info::use_shell_execute property must be false, or an xtd::invalid_operation_exception will be thrown when the xtd::diagnostics::process::.start(xtd::diagnostics::process_start_info) method is called.

◆ verb() [1/2]

xtd::ustring xtd::diagnostics::process_start_info::verb ( ) const

Gets the verb to use when opening the application or document specified by the FileName property.

Returns
The action to take with the file that the process opens. The default is an empty string (""), which signifies no action.
Remarks
Each file name extension has its own set of verbs, which can be obtained by using the Verbs property. For example, the "print" verb will print a document specified by using FileName. The default verb can be specified by using an empty string (""). Examples of verbs are "Edit", "Open", "OpenAsReadOnly", "Print", and "Printto". You should use only verbs that appear in the set of verbs returned by the xtd::diagnostics::process_start_info::verbs property.
When you use the xtd::diagnostics::process_start_info::verb property, you must include the file name extension when you set the value of the xtd::diagnostics::process_start_info::file_name property. The file name does not need to have an extension if you manually enter a value for the xtd::diagnostics::process_start_info::verb property.

◆ verb() [2/2]

process_start_info& xtd::diagnostics::process_start_info::verb ( const xtd::ustring value)

Sts the verb to use when opening the application or document specified by the FileName property.

Parameters
valueThe action to take with the file that the process opens. The default is an empty string (""), which signifies no action.
Returns
The current instance of process_start_info.
Remarks
Each file name extension has its own set of verbs, which can be obtained by using the Verbs property. For example, the "print" verb will print a document specified by using FileName. The default verb can be specified by using an empty string (""). Examples of verbs are "Edit", "Open", "OpenAsReadOnly", "Print", and "Printto". You should use only verbs that appear in the set of verbs returned by the xtd::diagnostics::process_start_info::verbs property.
When you use the xtd::diagnostics::process_start_info::verb property, you must include the file name extension when you set the value of the xtd::diagnostics::process_start_info::file_name property. The file name does not need to have an extension if you manually enter a value for the xtd::diagnostics::process_start_info::verb property.

◆ verbs()

std::vector<xtd::ustring> xtd::diagnostics::process_start_info::verbs ( ) const

Gets the set of verbs associated with the type of file specified by the xtd::diagnostics::process_start_info::file_name property.

Returns
The actions that the system can apply to the file indicated by the xtd::diagnostics::process_start_info::file_name property.
Remarks
The xtd::diagnostics::process_start_info::verbs property enables you to determine the verbs that can be used with the file specified by the xtd::diagnostics::process_start_info::file_name property. You can set the xtd::diagnostics::process_start_info::verb property to the value of any verb in the set. Examples of verbs are "Edit", "Open", "OpenAsReadOnly", "Print", and "Printto".
When you use the xtd::diagnostics::process_start_info::verbs property, you must include the file name extension when you set the value of the xtd::diagnostics::process_start_info::file_name property. The file name extension determines the set of possible verbs.

◆ window_style() [1/2]

xtd::diagnostics::process_window_style xtd::diagnostics::process_start_info::window_style ( ) const

Gets the window state to use when the process is started.

Returns
One of the enumeration values that indicates whether the process is started in a window that is maximized, minimized, normal (neither maximized nor minimized), or not visible. The default is xtd::diagnostics::process_window_style::normal.
Exceptions
xtd::invalid_enum_argument_exceptionThe window style is not one of the xtd::diagnostics::process_window_style enumeration members.

◆ window_style() [2/2]

process_start_info& xtd::diagnostics::process_start_info::window_style ( xtd::diagnostics::process_window_style  value)

Sets the window state to use when the process is started.

Parameters
valueOne of the enumeration values that indicates whether the process is started in a window that is maximized, minimized, normal (neither maximized nor minimized), or not visible. The default is xtd::diagnostics::process_window_style::normal.
Returns
The current instance of process_start_info.
Exceptions
xtd::invalid_enum_argument_exceptionThe window style is not one of the xtd::diagnostics::process_window_style enumeration members.

◆ working_directory() [1/2]

const xtd::ustring& xtd::diagnostics::process_start_info::working_directory ( ) const

When the xtd::diagnostics::process_start_info::use_shell_execute property is false, gets or sets the working directory for the process to be started. When xtd::diagnostics::process_start_info::use_shell_execute is true, gets or sets the directory that contains the process to be started.

Returns
When xtd::diagnostics::process_start_info::use_shell_execute is true, the fully qualified name of the directory that contains the process to be started. When the xtd::diagnostics::process_start_info::use_shell_execute property is false, the working directory for the process to be started. The default is an empty string ("").
Important
The xtd::diagnostics::process_start_info::working_directory property must be set if xtd::diagnostics::process_start_info::user_name and xtd::diagnostics::process_start_info::password are provided. If the property is not set, the default working directory is SYSTEMROOT%.
Remarks
If the directory is already part of the system path variable, you do not have to repeat the directory's location in this property.
The xtd::diagnostics::process_start_info::working_directory property behaves differently when xtd::diagnostics::process_start_info::use_shell_execute is true than when xtd::diagnostics::process_start_info::use_shell_execute is false. When xtd::diagnostics::process_start_info::use_shell_execute is true, the xtd::diagnostics::process_start_info::working_directory property specifies the location of the executable. If xtd::diagnostics::process_start_info::working_directory is an empty string, the current directory is understood to contain the executable.
Note
When xtd::diagnostics::process_start_info::use_shell_execute is true, the working directory of the application that starts the executable is also the working directory of the executable.
Remarks
When xtd::diagnostics::process_start_info::use_shell_execute is false, the xtd::diagnostics::process_start_info::working_directory property is not used to find the executable. Instead, its value applies to the process that is started and only has meaning within the context of the new process.

◆ working_directory() [2/2]

process_start_info& xtd::diagnostics::process_start_info::working_directory ( const xtd::ustring value)

When the xtd::diagnostics::process_start_info::use_shell_execute property is false, gets or sets the working directory for the process to be started. When xtd::diagnostics::process_start_info::use_shell_execute is true, gets or sets the directory that contains the process to be started.

Parameters
valueWhen xtd::diagnostics::process_start_info::use_shell_execute is true, the fully qualified name of the directory that contains the process to be started. When the xtd::diagnostics::process_start_info::use_shell_execute property is false, the working directory for the process to be started. The default is an empty string ("").
Returns
The current instance of process_start_info.
Important
The xtd::diagnostics::process_start_info::working_directory property must be set if xtd::diagnostics::process_start_info::user_name and xtd::diagnostics::process_start_info::password are provided. If the property is not set, the default working directory is SYSTEMROOT%.
Remarks
If the directory is already part of the system path variable, you do not have to repeat the directory's location in this property.
The xtd::diagnostics::process_start_info::working_directory property behaves differently when xtd::diagnostics::process_start_info::use_shell_execute is true than when xtd::diagnostics::process_start_info::use_shell_execute is false. When xtd::diagnostics::process_start_info::use_shell_execute is true, the xtd::diagnostics::process_start_info::working_directory property specifies the location of the executable. If xtd::diagnostics::process_start_info::working_directory is an empty string, the current directory is understood to contain the executable.
Note
When xtd::diagnostics::process_start_info::use_shell_execute is true, the working directory of the application that starts the executable is also the working directory of the executable.
Remarks
When xtd::diagnostics::process_start_info::use_shell_execute is false, the xtd::diagnostics::process_start_info::working_directory property is not used to find the executable. Instead, its value applies to the process that is started and only has meaning within the context of the new process.

The documentation for this class was generated from the following file: