---
title: Command-line argument parsing and lookup
summary: Normalizes raw command-line arguments at startup and resolves named or positional /Name:Value / -Name:Value switches on demand.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-07-30
library: SAIF.Presentation.ConsoleApplication
reference_type: package
operation_id: OP-CA-002
trigger: Downstream code calls ParamExists, GetParamName, or GetParamValue after Initialize() has run
---

# Command-line argument parsing and lookup

Downstream applications never parse `Environment.GetCommandLineArgs` themselves; `Initialize()` normalizes the raw array once during the [console application execution lifecycle](console-application-lifecycle.md), and this operation's lookup methods let `ValidateCommandLine()` and `RunAppLogic()` query that normalized array by position or by named switch, and split a switch into its name and value at a colon.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-CA-002 |
| **Trigger** | Downstream code (typically `ValidateCommandLine()` or `RunAppLogic()`) calls `ParamExists`, `GetParamName`, or `GetParamValue`, after `Initialize()` has normalized `m_CmdLine` |
| **Inputs** | The normalized command-line argument array (`m_CmdLine`); a requested switch name (`String`) or positional index (`Integer`) |
| **Outputs** | `Boolean` existence result (`ParamExists`); the resolved switch name or value (`String`, empty string when not found) |
| **Primary components** | `clsConsoleBase.GetParamName`, `clsConsoleBase.GetParamValue`, `clsConsoleBase.ParamExists` |
| **Entry point** | `Presentation\SAIF.Presentation.ConsoleApplication\clsConsoleBase.vb` |

## Steps

1. **Prerequisite normalization (performed once, during `Initialize()`).** Each raw argument has a single leading `/` or `-` stripped, if present, and is upper-cased before storage in `m_CmdLine` ([BR-002](../business-rules.md#br-002-case-insensitive-command-line-switch-matching)). This step is part of [console application execution lifecycle](console-application-lifecycle.md) and is not repeated here; every lookup below operates on the already-normalized array.
2. **Check existence by index (`ParamExists(Integer)`).** Returns `True` only if the index falls within `0` to `m_CmdLine.Length - 1`.
3. **Check existence by name (`ParamExists(String)`).** Scans `m_CmdLine` and returns `True` as soon as any stored argument starts with the upper-cased requested name ([BR-005](../business-rules.md#br-005-command-line-parameter-names-match-by-prefix-not-exact-equality)).
   - If no stored argument matches: returns `False`.
4. **Resolve a switch's name by index (`GetParamName(Integer)`).**
   - If `ParamExists(inNumber)` is `False`: returns `""`.
   - Otherwise, if the stored argument contains a colon not immediately followed by a backslash: returns the substring before the colon ([BR-004](../business-rules.md#br-004-colon-in-a-file-path-value-is-not-treated-as-a-namevalue-separator)).
   - Otherwise: returns the whole stored argument as the name.
5. **Resolve a switch's name by name (`GetParamName(String)`).**
   - If `ParamExists(inName)` is `False`: returns `""`.
   - Otherwise, scans `m_CmdLine` for the first argument starting with the upper-cased name and applies the same colon/backslash split as step 4 ([BR-004](../business-rules.md#br-004-colon-in-a-file-path-value-is-not-treated-as-a-namevalue-separator), [BR-005](../business-rules.md#br-005-command-line-parameter-names-match-by-prefix-not-exact-equality)).
6. **Resolve a switch's value by name (`GetParamValue(String)`).**
   - If `ParamExists(inName)` is `False`: returns `""`.
   - Otherwise, finds the first matching argument and, if it contains a colon not immediately followed by a backslash, returns the substring after the colon ([BR-004](../business-rules.md#br-004-colon-in-a-file-path-value-is-not-treated-as-a-namevalue-separator), [BR-005](../business-rules.md#br-005-command-line-parameter-names-match-by-prefix-not-exact-equality)).
   - If no colon-delimited value is present (or the colon is immediately followed by a backslash): returns `""` — a value-only switch (e.g., `/DEBUG`) has no separately retrievable value.
7. **Resolve a switch's value by index (`GetParamValue(Integer)`).** Same colon/backslash split as step 6, applied to the argument at the given index ([BR-004](../business-rules.md#br-004-colon-in-a-file-path-value-is-not-treated-as-a-namevalue-separator)).

## Process flow

The following diagram visualizes the name/value resolution path shared by `GetParamName` and `GetParamValue`.

```mermaid
flowchart TD
	Start([Lookup requested: name or index]) --> Exists{ParamExists?}
	Exists -->|No| Empty([Return empty string])
	Exists -->|Yes| Find[Locate matching stored argument]
	Find --> Colon{Colon present and<br>not followed by backslash?}
	Colon -->|Yes, GetParamName| Before([Return substring before colon])
	Colon -->|Yes, GetParamValue| After([Return substring after colon])
	Colon -->|No| Whole([GetParamName: return whole argument<br>GetParamValue: return empty string])
```

## Failure and edge-case behavior

- Name and value resolution both rely on prefix matching (`StartsWith`), so a short requested name can match a longer stored argument that happens to share the same prefix, potentially resolving the wrong switch ([BR-005](../business-rules.md#br-005-command-line-parameter-names-match-by-prefix-not-exact-equality)).
- A value that itself begins with a Windows drive-letter path (`C:\...`) is preserved intact rather than split at its own colon, because the character immediately after the colon is checked for a backslash ([BR-004](../business-rules.md#br-004-colon-in-a-file-path-value-is-not-treated-as-a-namevalue-separator)).
- A switch with no colon at all (e.g., a bare `/DEBUG` flag) always yields an empty value from `GetParamValue`; callers must use `ParamExists` to detect the flag itself.
- `ParamExists(Integer)` is a bounds check only — it does not inspect the argument's content — while `ParamExists(String)` inspects content but not position.

## Related documentation

- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

## Sources

- `Presentation\SAIF.Presentation.ConsoleApplication\clsConsoleBase.vb`