PSRP Core

https://psrpcore.readthedocs.io/en/latest/
Admin
PSRP Core is a sans-IO Python library implementing the PowerShell Remoting Protocol (PSRP) for...
Tokens:28,775
Snippets:322
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### start()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Marks the pipeline as started.

```APIDOC
## start()

### Description
Marks the pipeline as started.
```

--------------------------------

### get_version()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sends a request to get the version of the hosting application.

```APIDOC
## get_version()

### Description
Sends the `psrpcore.types.HostMethodIdentifier.GetVersion` host call that requests the version of the hosting application. This corresponds to the PSHost.Version Property.

### Returns
- **call id** (int) - The call id for the request.
```

--------------------------------

### Define a basic enum

Source: https://psrpcore.readthedocs.io/en/latest/types.html

Example implementation of System.IO.FileMode using PSEnumBase.

```python
import psrpcore.types as pstype

@pstype.PSType(type_names=["System.IO.FileMode"])
class IOFileMode(pstype.PSEnumBase):
    Append = 6
    Create = 2
    CreateNew = 1
    Open = 3
    OpenOrCreate = 4
    Truncate = 5
```

--------------------------------

### Define a flag-based enum

Source: https://psrpcore.readthedocs.io/en/latest/types.html

Example implementation of System.IO.FileShare using PSFlagBase to support multiple values.

```python
import psrpcore.types as pstype

@pstype.PSType(type_names=["System.IO.FileShare"])
class IOFileShare(pstype.PSFlagBase):
    Delete = 4
    Inheritable = 16
    none = 0
    Read = 1
    ReadWrite = 3
    Write = 2
```

--------------------------------

### get_name()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sends a request to get the human-friendly host name.

```APIDOC
## get_name()

### Description
Sends the `psrpcore.types.HostMethodIdentifier.GetName` host call that requests the human friendly host name identifier. This corresponds to the PSHost.Name Property.

### Returns
- **call id** (int) - The call id for the request.
```

--------------------------------

### ClientGetCommandMetadata

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

A class representing a Get Command Metadata pipeline initiated from the client.

```APIDOC
## ClientGetCommandMetadata

### Description
A Get Command Metadata pipeline to be used from the client.

### Parameters
- **runspace_pool** (ClientRunspacePool) - Required - The Runspace Pool the pipeline is a member of.
- **name** (str | List[str]) - Required - List of command names to get the metadata for. Uses `*` as a wildcard.
- **command_type** (CommandTypes) - Required - The type of commands to filter by.
- **namespace** (List[str] | None) - Optional - Wildcard patterns describing the command namespace to filter by.
- **arguments** (List[Any] | None) - Optional - Extra arguments passed to the higher-layer above PSRP.
- **pipeline_id** (UUID | None) - Optional - Manually set the Pipeline ID, used when reconnecting to an existing Pipeline.
```

--------------------------------

### get_instance_id()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sends a request to get the identifier of the hosting application.

```APIDOC
## get_instance_id()

### Description
Sends the `psrpcore.types.HostMethodIdentifier.GetInstanceId` host call that requests the identifier of the hosting application. This corresponds to the PSHost.InstanceId Property.

### Returns
- **call id** (int) - The call id for the request.
```

--------------------------------

### get_max_physical_window_size()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sends a request to get the largest possible window size.

```APIDOC
## get_max_physical_window_size()

### Description
Sends the `psrpcore.types.HostMethodIdentifier.GetMaxPhysicalWindowSize` host call to get largest possible window size that can be set. This corresponds to the PSHostRawUserInterface.MaxPhysicalWindowSize Property.

### Returns
- **call id** (int) - The call id for the request.
```

--------------------------------

### ClientPowerShell

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

The main pipeline class used by the client to start and configure a PowerShell pipeline on the server.

```APIDOC
## ClientPowerShell

### Description
A PowerShell pipeline to be used from the client. This is the main pipeline class used by the client to start a pipeline on the server.

### Methods
- **add_argument(value)**: Adds a positional argument to the last command in the pipeline.
- **add_command(cmdlet, use_local_scope)**: Adds a command to the current statement.
- **add_parameter(name, value)**: Adds a parameter to the last command.
- **add_parameters(**parameters)**: Adds multiple parameters to the last command.
- **add_script(script, use_local_scope)**: Adds a script block to the current statement.
- **add_statement()**: Adds a statement to the pipeline to separate commands.
```

--------------------------------

### Serialize PowerShell object to CLIXML

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.types.html

Example of how to serialize a value for use with PowerShell's PSSerialize class.

```powershell
[System.Management.Automation.PSSerialize]::Serialize($value)
```

--------------------------------

### Initiate and Respond to a Host Call

Source: https://psrpcore.readthedocs.io/en/latest/_sources/scenarios.md.txt

Demonstrates the workflow of a server requesting a line write and read, and the client responding to those calls.

```python
import psrpcore
import sys

client_pool = psrpcore.ClientRunspacePool()
client_host = psrpcore.ClientHostResponder(client_pool)

server_pool = psrpcore.ServerRunspacePool()
server_host = psrpcore.ServerHostRequestor(server_pool)

# Opened the pool ...

# Request the client host to write a line and read the response.
server_host.write_line("Please enter your name:")
call_id = server_host.read_line()

# Send the request to the client and process the data
client_pool.receive_data(server_pool.data_to_send())

# Get the first call - a client should check .method_identifier to see what to invoke
write_call = client_pool.next_event()
sys.stdout.write(write_call.method_parameters[0])

# Process the read call
read_call = client_pool.next_event()
client_host.read_line(read_call.ci, "Jordan")

# Send response back to the server to process
server_pool.receive_data(client_pool.data_to_send())
read_resp = server_pool.next_event()
assert read_resp.result == "Jordan"
```

--------------------------------

### Implement PSCustomObject in Python

Source: https://psrpcore.readthedocs.io/en/latest/types.html

Demonstrates two approaches for creating PSCustomObject instances: using the library's PSCustomObject class or a standard Python class.

```python
from psrpcore.types import PSCustomObject

# Using PSObjectObject({'key': 'value'})
ps_custom_object = PSCustomObject(
    PropertyName='name',
    AnotherProperty=1,
)

# Using a plain Python class
class MyPSCustomObject:

    def __init__(self, PropertyName, AnotherProperty):
        self.PropertyName = PropertyName
        self.AnotherProperty = AnotherProperty

ps_custom_object = MyPSCustomObject('name', 1)
```

--------------------------------

### Create a PSCustomObject

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.types.html

Demonstrates creating a PSCustomObject with extended properties, replicating PowerShell syntax.

```powershell
$obj = [PSCustomObject]@{
    Property = 'value'
}
```

```python
>>> obj = PSCustomObject(Property='value')
>>> print(obj.Property)
abc
```

--------------------------------

### get_foreground_color()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sends a request to get the foreground color of the host.

```APIDOC
## get_foreground_color()

### Description
Sends the `psrpcore.types.HostMethodIdentifier.GetForegroundColor` host call to request the foreground color of the host. This corresponds to the PSHostRawUserInterface.ForegroundColor Property.

### Returns
- **call id** (int) - The call id for the request.
```

--------------------------------

### get_cursor_size()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sends a request to get the size of the cursor as a percentage.

```APIDOC
## get_cursor_size()

### Description
Sends the `psrpcore.types.HostMethodIdentifier.GetCursorSize` host call to get the size of the cursor as a percentage. This corresponds to the PSHostRawUserInterface.CursorSize Property.

### Returns
- **call id** (int) - The call id for the request.
```

--------------------------------

### notify_begin_application()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Notifies the host that the engine is about to execute a legacy command line application.

```APIDOC
## notify_begin_application()

### Description
Sends the `psrpcore.types.HostMethodIdentifier.NotifyBeginApplication` host call to notify the host that it is about to execute a legacy command line application. This corresponds to the PSHost.NotifyBeginApplication Method.
```

--------------------------------

### prompt()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Prompts the user with a number of fields to supply values.

```APIDOC
## prompt(caption, message, descriptions)

### Description
Sends the `psrpcore.types.HostMethodIdentifier.Prompt` host call to prompt the user with a number of fields for which to supply values. This corresponds to the PSHostUserInterface.Prompt Method.

### Parameters
- **caption** (str) - The caption or title for the prompt.
- **message** (str) - The message describing the set of fields.
- **descriptions** (List[FieldDescription]) - A list of fields to display.

### Returns
- **call_id** (int) - The call id for the request.
```

--------------------------------

### prompt_for_choice

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Responds to HostMethodIdentifier.PromptForChoice with the selected choice index.

```APIDOC
## prompt_for_choice(ci: int, choice: int) -> None

### Description
Responds to `psrpcore.types.HostMethodIdentifier.PromptForChoice` with the choice that was slected.

### Parameters
- **ci** (int) - The call id the response is for.
- **choice** (int) - The choice that was selected. This is a 0 based index of selected choice from the host call.
```

--------------------------------

### get_cursor_position()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sends a request to get the position of the cursor on the screen buffer.

```APIDOC
## get_cursor_position()

### Description
Sends the `psrpcore.types.HostMethodIdentifier.GetCursorPosition` host call to get the position of the cursor on the screen buffer. This corresponds to the PSHostRawUserInterface.CursorPosition Property.

### Returns
- **call id** (int) - The call id for the request.
```

--------------------------------

### prompt_for_credential

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Responds to HostMethodIdentifier.PromptForCredential with the entered credential.

```APIDOC
## prompt_for_credential(ci: int, credential: PSCredential) -> None

### Description
Responds to `psrpcore.types.HostMethodIdentifier.PromptForCredential1` or `psrpcore.types.HostMethodIdentifier.PromptForCredential2` with the credential that was entered.

### Parameters
- **ci** (int) - The call id the response is for.
- **credential** (PSCredential) - The credential that was entered.
```

--------------------------------

### get_current_ui_culture()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sends a request to get the current UI culture of the host.

```APIDOC
## get_current_ui_culture()

### Description
Sends the `psrpcore.types.HostMethodIdentifier.GetCurrentUICulture` host call that requests the current UI culture of the host. This corresponds to the PSHost.CurrentUICulture Property.

### Returns
- **call id** (int) - The call id for the request.
```

--------------------------------

### Accessing .NET object properties in Python

Source: https://psrpcore.readthedocs.io/en/latest/types.html

Demonstrates the three primary ways to access properties on a .NET-aware object in Python.

```python
# Using the dot notation
obj.PropertyName

# Using an index lookup
obj['PropertyName']

# Accesing it through the PSObject metdata
obj.PSObject.adapted_properties  # List of adapted properties, filter by name
obj.PSObject.extended_properties  # List of extended properties, filter by name
```

--------------------------------

### write_progress(source_id: int, activity_id: int, activity: str, status_description: str, current_operation: str | None, parent_activity_id: int, percent_complete: int, record_type: ProgressRecordType, seconds_remaining: int)

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sends a WriteProgress host call to display a progress record on the host.

```APIDOC
## write_progress(...)

### Description
Writes a progress record to be displayed on the host.

### Parameters
- **source_id** (int) - Required - Unique identifier of the source of the record.
- **activity_id** (int) - Required - The Id of the activity to which this record corresponds.
- **activity** (str) - Required - The description of the activity.
- **status_description** (str) - Required - Current status of the operation.
- **current_operation** (str | None) - Optional - Current operation being performed.
- **parent_activity_id** (int) - Optional - The Id of the parent activity.
- **percent_complete** (int) - Optional - Percentage of work completed.
- **record_type** (ProgressRecordType) - Optional - The type of record represented.
- **seconds_remaining** (int) - Optional - Estimate of time remaining.
```

--------------------------------

### Opening a Runspace Pool

Source: https://psrpcore.readthedocs.io/en/latest/_sources/scenarios.md.txt

Initializes client and server runspace pools and performs the handshake by exchanging data until the state is established.

```python
import psrpcore

client_pool = psrpcore.ClientRunspacePool()
server_pool = psrpcore.ServerRunspacePool()

# Start opening the client which generates data to exchange
client_pool.open()

# Continue to send and receive data until the state has changed.
while runspace_pool.state == psrpcore.types.RunspacePoolState.Opening:
    client_outgoing = client_pool.data_to_send()

    # Have the server process all incoming messages - no more events
    server_pool.receive_data(client_outgoing)
    while True:
        event = server_pool.next_event()
        if event is None:
            break

    server_outgoing = server_pool.data_to_send()

    # Process server response and fail if the eventual state was broken.
    client_pool.receive_data(server_outgoing)
    while True:
        event = runspace_pool.next_event()
        if event is None:
            break

        elif isinstance(event, psrpcore.RunspacePoolStateEvent):
            if event.state == psrpcore.types.RunspacePoolState.Broken:
                raise Exception(f"Open failed {event.reason}")
```

--------------------------------

### get_max_window_size()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sends a request to get the largest possible window size that can fit in the current buffer.

```APIDOC
## get_max_window_size()

### Description
Sends the `psrpcore.types.HostMethodIdentifier.GetMaxWindowSize` host call to get largest possible window size that can fit in the current buffer. This corresponds to the PSHostRawUserInterface.MaxWindowSize Property.

### Returns
- **call id** (int) - The call id for the request.
```

--------------------------------

### Execute a PowerShell Pipeline with psrpcore

Source: https://psrpcore.readthedocs.io/en/latest/_sources/scenarios.md.txt

Demonstrates the lifecycle of a PowerShell pipeline, including initialization, data exchange, and cleanup between client and server runspace pools.

```python
import psrpcore

client_pool = psrpcore.ClientRunspacePool()
server_pool = psrpcore.ServerRunspacePool()

# Opened the pool ...

# Create the client PowerShell pipeline
c_ps = psrpcore.ClientPowerShell(client_pool)
c_ps.add_script("echo 'hi'")
c_ps.start()

# Create the server pipeline - the pipeline id is exchanged in a transport specific message.
pipeline_id = "from transport specific message"
s_ps = psrpcore.ServerPipeline(server_pool, pipeline_id)

# Send pipeline details to server and process the data
server_pool.receive_data(client_pool.data_to_send())
create_pipe = server_pool.next_event()

# Pipeline details are stored either on the event or the pipeline object
create_pipe.pipeline is s_ps.metadata
s_ps.start()

# Data is exchanged between the client and server until it has stopped running.
while c_ps.state == psrpcore.types.PSInvocationState.Running:
    # The server can choose whether to send that initial state or not (not mandatory)
    # client_pool.receive_data(server_pool.data_to_send())
    # client_pool.next_event()

    # Server runs requested command(s) and sends output as necessary
    s_ps.write_output("data")
    s_ps.write_verbose("verbose record")
    s_ps.write_error(net_exception, ...)

    # Once the pipeline is done the server marks it as complete the pipeline
    s_ps.complete()

    # Client processes any result from the server
    client_pool.receive_data(server_pool.data_to_send())
    while True:
        event = client_pool.next_event()
        if event is None:
            break

        elif isinstance(event, psrpcore.PipelineStateEvent):
            if event.state == psrpcore.types.PSInvocationState.Failed:
                raise Exception(f"Pipe failed {event.reason}")

        # Handle output data accordingly

# Once the pipeline is done both the client and server need to close it
# Sending the close signal is a transport specific message and not done in PSRP
c_ps.close()
s_ps.close()
```

--------------------------------

### ClientHostResponder

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Helper class used to respond to runspace and pipeline host calls.

```APIDOC
## ClientHostResponder

### Description
Helper class that can be used to respond to runspace and pipeline host calls. Each method is named after the corresponding host method identifier.

### Methods

#### get_background_color(ci: int, color: ConsoleColor)
Responds to `psrpcore.types.HostMethodIdentifier.GetBackgroundColor` with the background color of the host.

#### get_buffer_contents(ci: int, cells: List[List[BufferCell]])
Responds to `psrpcore.types.HostMethodIdentifier.GetBufferContents` with contents of the buffer that was requested.

#### get_buffer_size(ci: int, width: int, height: int)
Responds to `psrpcore.types.HostMethodIdentifier.GetBufferSize` with the size of the buffer of the host.
```

--------------------------------

### ClientRunspacePool Constructor

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Initializes a new ClientRunspacePool instance to represent a remote Runspace Pool.

```APIDOC
## ClientRunspacePool(application_arguments, apartment_state, host, thread_options, min_runspaces, max_runspaces, runspace_pool_id)

### Description
Initializes a non-blocking connection object that handles PSRP packets for a remote Runspace Pool.

### Parameters
- **application_arguments** (Dict[str, Any] | None) - Optional - Arguments sent to the server.
- **apartment_state** (ApartmentState) - Optional - The apartment state of the execution thread.
- **host** (HostInfo | None) - Optional - Describes the client hosting application.
- **thread_options** (PSThreadOptions) - Optional - Determines thread creation behavior.
- **min_runspaces** (int) - Optional - Minimum number of Runspaces.
- **max_runspaces** (int) - Optional - Maximum number of Runspaces.
- **runspace_pool_id** (UUID | None) - Optional - ID used for reconnecting to an existing pool.
```

--------------------------------

### Deserialize CLIXML string in PowerShell

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.types.html

Example of how to deserialize a CLIXML string produced by psrpcore back into a PowerShell object.

```powershell
[System.Management.Automation.PSSerialize]::Deserialize($value)
```

--------------------------------

### ServerRunspacePool.host_call()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Requests a host call on the client and generates a corresponding host call message.

```APIDOC
## host_call(method, parameters=None, pipeline_id=None)

### Description
Request a host call on the client. Will generate a `psrpcore.types.RunspacePoolHostCall` message to be sent to the client.

### Parameters
- **method** (HostMethodIdentifier) - Required - The host method that is requested to be run.
- **parameters** (List | None) - Optional - Parameters to invoke the call with.
- **pipeline_id** (UUID | None) - Optional - The pipeline identifier if the host call is for a specific pipeline.

### Returns
- **int** - The call identifier for this host call.
```

--------------------------------

### prompt

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Responds to HostMethodIdentifier.Prompt with the values for the entered field.

```APIDOC
## prompt(ci: int, choices: Dict[str, Any]) -> None

### Description
Responds to `psrpcore.types.HostMethodIdentifier.Prompt` with the values for field that was entered.

### Parameters
- **ci** (int) - The call id the response is for.
- **choices** (Dict[str, Any]) - The response with the key being the name of the field and the value is the value entered for that field.
```

--------------------------------

### prompt_for_credential

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sends a request to prompt the user for a credential. Corresponds to PSHostUserInterface.PromptForCredential.

```APIDOC
## prompt_for_credential(caption, message, username, target_name, allowed_credential_types, options)

### Description
Sends a host call to prompt the user for a credential. The server should wait for the host response before continuing.

### Parameters
- **caption** (str) - Optional - The caption or title for the prompt.
- **message** (str) - Optional - The message describing the credential required.
- **username** (str | None) - Optional - The username the credential is for.
- **target_name** (str | None) - Optional - The domain part of the username.
- **allowed_credential_types** (PSCredentialTypes | None) - Optional - The types of credential requested.
- **options** (PSCredentialUIOptions | None) - Optional - Options to control UI behavior.

### Returns
- **int** - The call id for the request.
```

--------------------------------

### write(value: str, foreground_color: ConsoleColor | None = None, background_color: ConsoleColor | None = None) -> None

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Writes characters to the screen buffer.

```APIDOC
## write(value, foreground_color, background_color)

### Description
Sends the Write host call that writes the characters to the screen buffer.

### Parameters
- **value** (str) - The characters to write.
- **foreground_color** (ConsoleColor | None) - The color to display the text with.
- **background_color** (ConsoleColor | None) - The color to display the background with.
```

--------------------------------

### set_window_size(width: int, height: int) -> None

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Changes the size of the view window.

```APIDOC
## set_window_size(width, height)

### Description
Sends the SetWindowSize host call to change the size of the view window size as measured by cells.

### Parameters
- **width** (int) - The number of cells in the view window width.
- **height** (int) - The number of cells in the view window height.
```

--------------------------------

### get_window_size

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Responds to HostMethodIdentifier.GetWindowSize with the size of the host window.

```APIDOC
## get_window_size(ci: int, width: int, height: int) -> None

### Description
Responds to `psrpcore.types.HostMethodIdentifier.GetWindowSize` with the size of the window of the host.

### Parameters
- **ci** (int) - The call id the response is for.
- **width** (int) - The number of cells the fit the width of the window.
- **height** (int) - The number of cells that fit the height of the window.
```

--------------------------------

### write_line(line: str | None, foreground_color: ConsoleColor | None, background_color: ConsoleColor | None)

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sends a WriteLine host call to write characters with a newline to the screen buffer.

```APIDOC
## write_line(line: str | None, foreground_color: ConsoleColor | None, background_color: ConsoleColor | None)

### Description
Writes the characters with a newline to the screen buffer.

### Parameters
- **line** (str | None) - Optional - The line to write, if not set then just a newline is written.
- **foreground_color** (ConsoleColor | None) - Optional - The color to display the line with.
- **background_color** (ConsoleColor | None) - Optional - The color to display the background with.
```

--------------------------------

### Extend objects and types with psrpcore

Source: https://psrpcore.readthedocs.io/en/latest/types.html

Demonstrates adding a note property to a specific object instance and a script property to a type definition.

```python
import psrpcore.types


# The property only applies to the object passed in
obj = psrpcore.types.PSString("testing")
psrpcore.types.add_note_property(obj, "MyProperty", "value")
obj.MyProperty == "value"


# When adding to a type, the property now applies to any new instance of that type
psrpcore.types.add_script_property(psrpcore.types.PSString, "Length", lambda o: len(o))
obj = psrpcore.types.PSString("testing")
obj.Length == 7
```

--------------------------------

### get_version

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Responds to HostMethodIdentifier.GetVersion with the version of the host.

```APIDOC
## get_version(ci: int, version: str | PSVersion) -> None

### Description
Responds to `psrpcore.types.HostMethodIdentifier.GetVersion` with the version of the host.

### Parameters
- **ci** (int) - The call id the response is for.
- **version** (str | PSVersion) - The version of the host.
```

--------------------------------

### prompt_for_choice()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Prompts the user to choose an option from a set list.

```APIDOC
## prompt_for_choice(caption, message, choices, default_choice)

### Description
Sends the `psrpcore.types.HostMethodIdentifier.PromptForChoice` host call to prompt the user to choose an option from a set list. This corresponds to the PSHostUserInterface.PromptForChoice Method.

### Parameters
- **caption** (str) - The caption or title for the prompt.
- **message** (str) - The message describing the set of choices.
- **choices** (List[ChoiceDescription]) - A list of choices.
- **default_choice** (int) - The default choice index, -1 means no default.

### Returns
- **call_id** (int) - The call id for the request.
```

--------------------------------

### ServerRunspacePool.connect()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Marks the pool as connected from a disconnected state and generates the necessary state message for the client.

```APIDOC
## connect()

### Description
Marks the pool as connected from a disconnected state. Generates the `psrpcore.types.RunspacePoolStateMsg` that can be sent to the client.
```

--------------------------------

### host_call(method: HostMethodIdentifier, parameters: List | None)

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Requests a host call on the client for the pipeline.

```APIDOC
## host_call(method: HostMethodIdentifier, parameters: List | None)

### Description
Request a host call on the client for the pipeline. Generates a PipelineHostCall message.

### Parameters
- **method** (HostMethodIdentifier) - Required - The host method to invoke.
- **parameters** (List | None) - Optional - Parameters for the host call.
```

--------------------------------

### ClientRunspacePool Methods

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Methods available on the ClientRunspacePool instance to manage the connection and pool state.

```APIDOC
## connect()
Connects to a disconnected Runspace Pool on the peer.

## exchange_key()
Requests the session-specific key from the peer.

## get_available_runspaces()
Returns the command ID for a request to get the number of available Runspaces.

## host_response(ci, return_value, error_record)
Responds to a host call event.
- **ci** (int) - Required - The call ID to respond to.
- **return_value** (Any | None) - Optional - The return value.
- **error_record** (ErrorRecord | None) - Optional - The error record.

## open()
Opens the Runspace Pool on the peer.

## reset_runspace_state()
Resets the variable table for the Runspace Pool to default. Returns the command ID.

## set_max_runspaces(value)
Builds a request to set the maximum number of Runspaces. Returns the command ID.
- **value** (int) - Required - The new maximum number of runspaces.

## set_min_runspaces(value)
Builds a request to set the minimum number of Runspaces. Returns the command ID.
- **value** (int) - Required - The new minimum number of runspaces.
```

--------------------------------

### read_line(ci, line)

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Responds to a ReadLine request from the host with the provided line string.

```APIDOC
## read_line(ci, line)

### Description
Responds to `psrpcore.types.HostMethodIdentifier.ReadLine` with the line that was read.

### Parameters
- **ci** (int) - Required - The call id the response is for.
- **line** (str) - Required - The line that was read.
```

--------------------------------

### get_key_available

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Responds to GetKeyAvailable with input status.

```APIDOC
## get_key_available(ci, waiting)

### Description
Responds to `psrpcore.types.HostMethodIdentifier.GetKeyAvailable` with whether the host is waiting on input.

### Parameters
- **ci** (int) - Required - The call id the response is for.
- **waiting** (bool) - Required - Host is waiting on input.
```

--------------------------------

### read_key

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Responds to HostMethodIdentifier.ReadKey with the inputted key.

```APIDOC
## read_key(ci: int, character: int | str | PSChar, key_down: bool, control_key_state: ControlKeyStates, key_code: int) -> None

### Description
Responds to `psrpcore.types.HostMethodIdentifier.ReadKey` with key that was inputted onto the host.

### Parameters
- **ci** (int) - The call id the response is for.
- **character** (int | str | PSChar) - The character inputted.
- **key_down** (bool) - Whether the key is down.
- **control_key_state** (ControlKeyStates) - The state of control keys.
- **key_code** (int) - The key code.
```

--------------------------------

### prompt_for_multiple_choice

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sends a request to prompt the user to choose multiple options from a list. Corresponds to IHostUISupportsMultipleChoiceSelection.PromptForChoice.

```APIDOC
## prompt_for_multiple_choice(caption, message, choices, default_choices)

### Description
Sends a host call to prompt the user to choose multiple options from a set list. The server should wait for the host response before continuing.

### Parameters
- **caption** (str) - Required - The caption or title for the prompt.
- **message** (str) - Required - The message describing the set of choices.
- **choices** (List[ChoiceDescription]) - Required - A list of choices.
- **default_choices** (List[int] | None) - Optional - A list of default choice indices.

### Returns
- **int** - The call id for the request.
```

--------------------------------

### prompt_for_multiple_choice

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Responds to HostMethodIdentifier.PromptForChoiceMultipleSelection with the selected choices.

```APIDOC
## prompt_for_multiple_choice(ci: int, choices: int | List[int]) -> None

### Description
Responds to `psrpcore.types.HostMethodIdentifier.PromptForChoiceMultipleSelection` with the choices that were selected.

### Parameters
- **ci** (int) - The call id the response is for.
- **choices** (int | List[int]) - The choices that were selected. Each choice is a 0 based index of the selected choice from the host call.
```

--------------------------------

### complete()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Marks the server pipeline as closed and sends a completion message to the client.

```APIDOC
## complete()

### Description
Marks the pipeline as closed and generates a PipelineState message to be sent to the client.
```

--------------------------------

### set_foreground_color(color: ConsoleColor) -> None

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Changes the foreground color of the host.

```APIDOC
## set_foreground_color(color)

### Description
Sends the SetForegroundColor host call to change the foreground color of the host.

### Parameters
- **color** (ConsoleColor) - The color to set the foreground color to.
```

--------------------------------

### write_information()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Writes an information record to send to the client. Requires ProtocolVersion 2.3 (PowerShell 5.1+).

```APIDOC
## write_information(message_data, source, time_generated=None, tags=None, user=None, computer=None, process_id=None, native_thread_id=None, managed_thread_id=None)

### Description
Writes an information record to send to the client.
```

--------------------------------

### get_window_title

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Responds to HostMethodIdentifier.GetWindowTitle with the title of the host window.

```APIDOC
## get_window_title(ci: int, title: str) -> None

### Description
Responds to `psrpcore.types.HostMethodIdentifier.GetWindowTitle` with the title of the host window.

### Parameters
- **ci** (int) - The call id the response is for.
- **title** (str) - The title of the window.
```

--------------------------------

### set_background_color(color: ConsoleColor) -> None

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sends a host call to change the background color of the host, corresponding to the PSHostRawUserInterface.BackgroundColor property.

```APIDOC
## set_background_color(color: ConsoleColor) -> None

### Description
Sends the `psrpcore.types.HostMethodIdentifier.SetBackgroundColor` host call to change the background color of the host. This is a void method.

### Parameters
- **color** (ConsoleColor) - Required - The color to set the background color to.
```

--------------------------------

### Inspecting object properties with vars()

Source: https://psrpcore.readthedocs.io/en/latest/types.html

Uses the built-in vars() function to list all properties of a psrpcore object.

```python
import psrpcore

record = psrpcore.types.VerboseRecord("message")
vars(record)

# {
#     'PSObject': <psrpcore.types._base.PSObjectMeta object at 0x7fb9ed36b220>,
#     'serialize_extended_info': False,
#     'Message': 'message',
#     'InvocationInfo': None,
#     'PipelineIterationInfo': None
# }
```

--------------------------------

### read_line_as_secure_string(ci, line)

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Responds to a ReadLineAsSecureString request from the host with the provided secure string.

```APIDOC
## read_line_as_secure_string(ci, line)

### Description
Responds to `psrpcore.types.HostMethodIdentifier.ReadLineAsSecureString` with the line as a secure string that was read.

### Parameters
- **ci** (int) - Required - The call id the response is for.
- **line** (PSSecureString) - Required - The line that was read as a secure string.
```

--------------------------------

### get_instance_id

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Responds to GetInstanceId with the host unique identifier.

```APIDOC
## get_instance_id(ci, instance_id)

### Description
Responds to `psrpcore.types.HostMethodIdentifier.GetInstanceId` with a unique identifier of the host.

### Parameters
- **ci** (int) - Required - The call id the response is for.
- **instance_id** (UUID) - Required - The host identifier.
```

--------------------------------

### get_max_window_size

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Responds to GetMaxWindowSize with window dimensions.

```APIDOC
## get_max_window_size(ci, width, height)

### Description
Responds to `psrpcore.types.HostMethodIdentifier.GetMaxWindowSize` with the maximum size of the window of the host.

### Parameters
- **ci** (int) - Required - The call id the response is for.
- **width** (int) - Required - The number of cells that fit the max width.
- **height** (int) - Required - The number of cells that fit the max height.
```

--------------------------------

### set_cursor_size(size: int) -> None

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sets the cursor size as a percentage.

```APIDOC
## set_cursor_size(size)

### Description
Sends the SetCursorSize host call to set the size of the cursor as a percentage.

### Parameters
- **size** (int) - The cursor size as a percentage.
```

--------------------------------

### ServerRunspacePool.send_event()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sends a user event to the client Runspace Pool.

```APIDOC
## send_event(event_identifier, source_identifier, sender=None, source_args=None, message_data=None, time_generated=None, computer=None)

### Description
Sends an event to the client Runspace Pool. Generates a `psrpcore.types.UserEvent` message to be sent to the client.

### Parameters
- **event_identifier** (int) - Required - Unique identifier of this event.
- **source_identifier** (str) - Required - Identifier associated with the source of this event.
- **sender** (Any) - Optional - Object that generated this event.
- **source_args** (List[Any] | None) - Optional - List of arguments captured by the original event source.
- **message_data** (Any) - Optional - Additional user data associated with this event.
- **time_generated** (datetime | None) - Optional - Time and date that this event was generated.
- **computer** (str | None) - Optional - The name of the computer on which this event was generated.
```

--------------------------------

### write_verbose_line(line: str)

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sends a WriteVerboseLine host call to write a verbose message to the host.

```APIDOC
## write_verbose_line(line: str)

### Description
Writes a verbose message to the host display.

### Parameters
- **line** (str) - Required - The verbose line to write.
```

--------------------------------

### pop_runspace()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Notifies the host that a Runspace pop has been requested.

```APIDOC
## pop_runspace()

### Description
Sends the `psrpcore.types.HostMethodIdentifier.PopRunspace` host call to notify the host that a Runspace pop has been requested. This corresponds to the IHostSupportsInteractiveSession.PopRunspace Method.
```

--------------------------------

### get_window_size()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sends the GetWindowSize host call to retrieve the size of the view window in cells.

```APIDOC
## get_window_size()

### Description
Sends the `psrpcore.types.HostMethodIdentifier.GetWindowSize` host call to get the size of the view window as measured by cells. This corresponds to the PSHostRawUserInterface.WindowSize Property.

### Returns
- **call_id** (int) - The call id for the request.
```

--------------------------------

### get_key_available()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Sends a request to check if a keystroke is waiting in the input buffer.

```APIDOC
## get_key_available()

### Description
Sends the `psrpcore.types.HostMethodIdentifier.GetKeyAvailable` host call to examine if a keystroke is waiting in the input buffer. This corresponds to the PSHostRawUserInterface.KeyAvailable Property.

### Returns
- **call id** (int) - The call id for the request.
```

--------------------------------

### get_window_position

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Responds to HostMethodIdentifier.GetWindowPosition with the coordinates of the host window.

```APIDOC
## get_window_position(ci: int, x: int, y: int) -> None

### Description
Responds to `psrpcore.types.HostMethodIdentifier.GetWindowPosition` the coordinates (from the top left point) of the host window.

### Parameters
- **ci** (int) - The call id the response is for.
- **x** (int) - The X (horizontal) coordinate of the host window.
- **y** (int) - The Y (vertical) coordinate of the host window.
```

--------------------------------

### ServerHostRequestor Methods

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Methods available on the ServerHostRequestor class to interact with the host.

```APIDOC
## enter_nested_prompt()

### Description
Sends the EnterNestedPrompt host call to interrupt the currently running pipeline and start a new nested input loop.

### Method
void

---

## exit_nested_prompt()

### Description
Sends the ExitNestedPrompt host call to end the currently running input loop.

### Method
void

---

## flush_input_buffer()

### Description
Sends the FlushInputBuffer host call to reset the keyboard input buffer.

### Method
void

---

## get_background_color()

### Description
Sends the GetBackgroundColor host call to request the background color of the host.

### Returns
- **call_id** (int) - The call id for the request.

---

## get_buffer_contents(left, top, right, bottom)

### Description
Sends the GetBufferContents host call to request the contents of the specified screen region.

### Parameters
- **left** (int) - The left margin of the buffer region.
- **top** (int) - The top margin of the buffer region.
- **right** (int) - The right margin of the buffer region.
- **bottom** (int) - The bottom margin of the buffer region.

### Returns
- **call_id** (int) - The call id for the request.

---

## get_buffer_size()

### Description
Sends the GetBufferSize host call to get the size of the screen buffer.

### Returns
- **call_id** (int) - The call id for the request.

---

## get_current_culture()

### Description
Sends the GetCurrentCulture host call to request the current culture of the host.

### Returns
- **call_id** (int) - The call id for the request.
```

--------------------------------

### set_buffer_size(width: int, height: int) -> None

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Changes the size of the screen buffer as measured by cells, corresponding to the PSHostRawUserInterface.BufferSize property.

```APIDOC
## set_buffer_size(width: int, height: int) -> None

### Description
Sends the `psrpcore.types.HostMethodIdentifier.SetBufferSize` host call to change the size of the screen buffer. This is a void method.

### Parameters
- **width** (int) - Required - The number of cells in the buffer width.
- **height** (int) - Required - The number of cells in the buffer height.
```

--------------------------------

### Define a custom enumeration

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.types.html

Shows how to inherit from PSEnumBase to create custom enumeration types, optionally specifying a base type.

```python
@PSType(["System.MyEnum"])
class MyEnum(PSEnumBase):
    Label = 1
    Other = 2

@PSType(["System.MyUIntEnum"])
class MyUIntEnum(PSEnumBase, base_type=PSUInt):
    Label = 1
    Other = 0xFFFFFFFF
```

--------------------------------

### get_name

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Responds to HostMethodIdentifier.GetName with a human-friendly host name identifier.

```APIDOC
## get_name(ci: int, name: str) -> None

### Description
Responds to `psrpcore.types.HostMethodIdentifier.GetName` with a human friendly host name identifier.

### Parameters
- **ci** (int) - The call id the response is for.
- **name** (str) - The host name to respond.
```

--------------------------------

### write_progress()

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Writes a progress record to send to the client.

```APIDOC
## write_progress(activity, activity_id, status_description, current_operation=None, parent_activity_id=-1, percent_complete=-1, record_type=ProgressRecordType.Processing, seconds_remaining=-1)

### Description
Writes a progress record to send to the client.
```

--------------------------------

### Accessing PowerShell Hashtable Properties and Keys

Source: https://psrpcore.readthedocs.io/en/latest/types.html

Demonstrates how PowerShell distinguishes between object properties added via Add-Member and dictionary keys, showing that dot notation favors properties while index notation favors keys.

```powershell
$hash = @{foo = 'bar'}

# PowerShell can get the key/value using the dot notation normally
$hash.foo -eq 'bar'

# Adds a property to the hashtable - only accesible using the dot notation
Add-Member -InputObject $hash -NotePropertyName my_prop -NotePropertyValue prop_value
$hash.my_prop -eq 'prop_value'
$hash['my_prop'] -ne 'prop_value'

# Adds a property with the same name as a contained key
Add-Member -InputObject $hash -NotePropertyName foo -NotePropertyValue override

# Dot notation favours the property added
$hash.foo -eq 'override'

# Index still favours the index lookup behaviour of the object
$hash['foo'] -eq 'bar'
```

--------------------------------

### get_foreground_color

Source: https://psrpcore.readthedocs.io/en/latest/psrpcore.html

Responds to GetForegroundColor with the host text color.

```APIDOC
## get_foreground_color(ci, color)

### Description
Responds to `psrpcore.types.HostMethodIdentifier.GetForegroundColor` with the foreground (text) color of the host.

### Parameters
- **ci** (int) - Required - The call id the response is for.
- **color** (ConsoleColor) - Required - The foreground color of the host.
```
Tokens:
Raw