xtd::diagnostics::process_start_info Class Reference

Inheritance diagram for xtd::diagnostics::process_start_info:

Definition

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

class core_export_ process_start_info final : public xtd::object

Inheritance

xtd::object → xtd::diagnostics::process_start_info

Header

#include <xtd/diagnostics/process_start_info>

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.

Examples

process_form.cpp, process_with_standard_output_redirection.cpp, and test_forms.cpp.

Public Constructors
	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.
	process_start_info (const xtd::string &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.
	process_start_info (const xtd::string &file_name, const xtd::string &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.

Public Properties
const xtd::string &	arguments () const noexcept
	Gets the set of command-line arguments to use when starting the application.
process_start_info &	arguments (const xtd::string &value) noexcept
	Sets the set of command-line arguments to use when starting the application.
bool	create_no_window () const noexcept
	Gets a value indicating whether to start the process in a new window.
process_start_info &	create_no_window (bool value) noexcept
	Sets a value indicating whether to start the process in a new window.
const xtd::string &	domain () const noexcept
	Gets a value that identifies the domain to use when starting the process.
process_start_info &	domain (const xtd::string &value) noexcept
	Sets a value that identifies the domain to use when starting the process.
const std::map< xtd::string, xtd::string > &	environment () const noexcept
	Gets the environment variables that apply to this process and its child processes.
std::map< xtd::string, xtd::string > &	environment () noexcept
	Gets the environment variables that apply to this process and its child processes.
const std::map< xtd::string, xtd::string > &	environment_variables () const noexcept
	Gets search paths for files, directories for temporary files, application-specific options, and other similar information.
std::map< xtd::string, xtd::string > &	environment_variables () noexcept
	Gets search paths for files, directories for temporary files, application-specific options, and other similar information.
bool	error_dialog () const noexcept
	Gets a value indicating whether an error dialog box is displayed to the user if the process cannot be started.
process_start_info &	error_dialog (bool value) noexcept
	Sets a value indicating whether an error dialog box is displayed to the user if the process cannot be started.
intptr	error_dialog_parent_handle () const noexcept
	Gets the window handle to use when an error dialog box is shown for a process that cannot be started.
process_start_info &	error_dialog_parent_handle (intptr value) noexcept
	Sets the window handle to use when an error dialog box is shown for a process that cannot be started.
const xtd::string &	file_name () const noexcept
	Gets the application or document to start.
process_start_info &	file_name (const xtd::string &value) noexcept
	Sets the application or document to start.
bool	load_user_profile () const noexcept
	Gets a value that indicates whether the Windows user profile is to be loaded from the registry.
process_start_info &	load_user_profile (bool value) noexcept
	Sets a value that indicates whether the Windows user profile is to be loaded from the registry.
const xtd::security::secure_string &	password () const noexcept
	Gets a secure string that contains the user password to use when starting the process.
process_start_info &	password (const xtd::security::secure_string &value) noexcept
	Sets a secure string that contains the user password to use when starting the process.
xtd::string	password_in_clear_text () const noexcept
	Gets the user password in clear text to use when starting the process.
process_start_info &	password_in_clear_text (const xtd::string &value) noexcept
	Sets the user password in clear text to use when starting the process.
bool	redirect_standard_error () const noexcept
	Gets a value that indicates whether the error output of an application is written to the xtd::diagnostics::process::standard_error stream.
process_start_info &	redirect_standard_error (bool value) noexcept
	Sets a value that indicates whether the error output of an application is written to the xtd::diagnostics::process::standard_error stream.
bool	redirect_standard_input () const noexcept
	Gets a value indicating whether the input for an application is read from the Process.StandardInput stream.
process_start_info &	redirect_standard_input (bool value) noexcept
	Sts a value indicating whether the input for an application is read from the Process.StandardInput stream.
bool	redirect_standard_output () const noexcept
	Gets a value that indicates whether the textual output of an application is written to the xtd::diagnostics::process::standard_output stream.
process_start_info &	redirect_standard_output (bool value) noexcept
	Sets a value that indicates whether the textual output of an application is written to the xtd::diagnostics::process::standard_output stream.
const xtd::string &	user_name () const noexcept
	Gets the user name to be used when starting the process.
process_start_info &	user_name (const xtd::string &value) noexcept
	Sets the user name to be used when starting the process.
bool	use_shell_execute () const noexcept
	Gets a value indicating whether to use the operating system shell to start the process.
process_start_info &	use_shell_execute (bool value) noexcept
	Sets a value indicating whether to use the operating system shell to start the process.
xtd::string	verb () const noexcept
	Gets the verb to use when opening the application or document specified by the FileName property.
process_start_info &	verb (const xtd::string &value) noexcept
	Sts the verb to use when opening the application or document specified by the FileName property.
xtd::collections::generic::list< xtd::string >	verbs () const
	Gets the set of verbs associated with the type of file specified by the xtd::diagnostics::process_start_info::file_name property.
xtd::diagnostics::process_window_style	window_style () const noexcept
	Gets the window state to use when the process is started.
process_start_info &	window_style (xtd::diagnostics::process_window_style value) noexcept
	Sets the window state to use when the process is started.
const xtd::string &	working_directory () const noexcept
	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.
process_start_info &	working_directory (const xtd::string &value) noexcept
	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.

Additional Inherited Members
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object.
virtual bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.
virtual xtd::size	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<class object_t >
xtd::uptr< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
virtual xtd::string	to_string () const noexcept
	Returns a xtd::string that represents the current object.
Static Public Member Functions inherited from xtd::object
template<class object_a_t , class object_b_t >
static bool	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are considered equal.
template<class object_a_t , class object_b_t >
static bool	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are the same instance.

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::string &  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::string &	file_name,
		const xtd::string &	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_name	An application with which to start a process.
arguments	Command-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::string & xtd::diagnostics::process_start_info::arguments ( ) const

noexcept

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 ("").

Examples

test_forms.cpp.

arguments() [2/2]

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

noexcept

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

Parameters

value

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 ("").

Returns

The current instance of process_start_info.

create_no_window() [1/2]

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

noexcept

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 )

noexcept

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

Parameters

value

true 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::string & xtd::diagnostics::process_start_info::domain ( ) const

noexcept

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::string &  value )

noexcept

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

Parameters

value

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.

Returns

The current instance of process_start_info.

environment() [1/2]

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

noexcept

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

Returns

std::map<xtd::string, xtd::string> 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::string, xtd::string > & xtd::diagnostics::process_start_info::environment ( )

noexcept

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

Returns

std::map<xtd::string, xtd::string> 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::string, xtd::string > & xtd::diagnostics::process_start_info::environment_variables ( ) const

noexcept

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

Returns

std::map<xtd::string, xtd::string> 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 dictionary 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::string, xtd::string > & xtd::diagnostics::process_start_info::environment_variables ( )

noexcept

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

Returns

std::map<xtd::string, xtd::string> 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 dictionary 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

noexcept

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 )

noexcept

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

Parameters

value

true 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 xtd::diagnostics::process_start_info::error_dialog_parent_handle ( ) const

noexcept

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  value )

noexcept

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

Parameters

value

A 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/2]

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

noexcept

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.

Examples

test_forms.cpp.

file_name() [2/2]

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

noexcept

Sets the application or document to start.

Parameters

value

string 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

noexcept

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 )

noexcept

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

Parameters

value

true 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

noexcept

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%\system32.

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::string 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 )

noexcept

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

Parameters

value

The 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%\system32.

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::string 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::string xtd::diagnostics::process_start_info::password_in_clear_text ( ) const

noexcept

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::string &  value )

noexcept

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

Parameters

value

string 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

noexcept

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.

block_scope_(xtd::diagnostics::process my_process) {
  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;
 
auto main() -> int {
  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 xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
 
auto main() -> int {
  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 xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
 
auto main() -> int {
  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_received += [&](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::io::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.

Examples

test_forms.cpp.

redirect_standard_error() [2/2]

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

noexcept

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

Parameters

value

true 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.

block_scope_(xtd::diagnostics::process my_process) {
  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;
 
auto main() -> int {
  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 xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
 
auto main() -> int {
  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 xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
 
auto main() -> int {
  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_received += [&](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::io::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

noexcept

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 xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
 
auto main() -> int {
  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.
  block_scope_(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 )

noexcept

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

Parameters

value

true 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 xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
 
auto main() -> int {
  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.
  block_scope_(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

noexcept

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.

Examples

The following example runs the ipconfig.exe command and redirects its standard output to the example's console window.

#include <xtd/xtd>
 
using namespace xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
 
auto main() -> int {
  block_scope_(process process) {
    process.start_info().file_name("ipconfig");
    process.start_info().use_shell_execute(false);
    process.start_info().redirect_standard_output(true);
    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.
    console::write_line(output);
 
    process.wait_for_exit();
  }
 
  console::write_line("\n\nPress any key to exit.");
  console::read_line();
}

Remarks

When a xtd::diagnostics::process writes text to its standard stream, that text is normally displayed on the console. By redirecting the xtd::diagnostics::process::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::process::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::process::standard_output stream throws an exception.

Remarks

The redirected xtd::diagnostics::process::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::process::xtd::diagnostics::process::standard_output stream, or closes the stream.

In contrast, xtd::diagnostics::process::begin_output_read_line starts asynchronous read operations on the xtd::diagnostics::process::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::process::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;
 
auto main() -> int {
  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 xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
 
auto main() -> int {
  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 xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
 
auto main() -> int {
  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_received += [&](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_output_read_line with a call to xtd::io::stream_reader::read_line on the xtd::diagnostics::process::standard_output 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::stream_reader::read_line for the xtd::diagnostics::process::standard_error stream.

Examples

test_forms.cpp.

redirect_standard_output() [2/2]

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

noexcept

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

Parameters

value

true 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.

Examples

The following example runs the ipconfig.exe command and redirects its standard output to the example's console window.

#include <xtd/xtd>
 
using namespace xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
 
auto main() -> int {
  block_scope_(process process) {
    process.start_info().file_name("ipconfig");
    process.start_info().use_shell_execute(false);
    process.start_info().redirect_standard_output(true);
    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.
    console::write_line(output);
 
    process.wait_for_exit();
  }
 
  console::write_line("\n\nPress any key to exit.");
  console::read_line();
}

Remarks

When a xtd::diagnostics::process writes text to its standard stream, that text is normally displayed on the console. By redirecting the xtd::diagnostics::process::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::process::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::process::standard_output stream throws an exception.

Remarks

The redirected xtd::diagnostics::process::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::process::xtd::diagnostics::process::standard_output stream, or closes the stream.

In contrast, xtd::diagnostics::process::begin_output_read_line starts asynchronous read operations on the xtd::diagnostics::process::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::process::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;
 
auto main() -> int {
  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 xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
 
auto main() -> int {
  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 xtd;
using namespace xtd::diagnostics;
using namespace xtd::io;
 
auto main() -> int {
  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_received += [&](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_output_read_line with a call to xtd::io::stream_reader::read_line on the xtd::diagnostics::process::standard_output 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::stream_reader::read_line for the xtd::diagnostics::process::standard_error stream.

user_name() [1/2]

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

noexcept

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%\system32.

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::string &  value )

noexcept

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

Parameters

value

The 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%\system32.

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.

use_shell_execute() [1/2]

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

noexcept

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_execute 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.

Examples

process_form.cpp, process_with_standard_output_redirection.cpp, and test_forms.cpp.

use_shell_execute() [2/2]

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

noexcept

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

Parameters

value

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.

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_execute 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.

verb() [1/2]

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

noexcept

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::string &  value )

noexcept

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

Parameters

value

The 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()

xtd::collections::generic::list< xtd::string > 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

noexcept

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_exception

The 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 )

noexcept

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

Parameters

value

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.

Returns

The current instance of process_start_info.

Exceptions

xtd::invalid_enum_argument_exception

The window style is not one of the xtd::diagnostics::process_window_style enumeration members.

working_directory() [1/2]

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

noexcept

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%\system32.

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.

Examples

process_form.cpp.

working_directory() [2/2]

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

noexcept

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

value

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 ("").

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%\system32.

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:

• xtd.core/include/xtd/diagnostics/process_start_info.hpp