@uipath/skills 1.195.0

package/skills/uipath-rpa/references/legacy/xaml-basics-and-rules.md

@@ -0,0 +1,457 @@
+# XAML Basics and Rules (Legacy)
+
+Core concepts for legacy UiPath workflow XAML files and rules for generating and editing XAML content. Legacy projects use .NET Framework 4.6.1 (WF4) and primarily VB.NET expressions.
+
+For the full XAML internals guide with detailed templates, see [activity-docs/_XAML-GUIDE.md](./activity-docs/_XAML-GUIDE.md).
+
+---
+
+## XAML File Anatomy
+
+Every legacy UiPath XAML workflow is a WF4 Activity serialized as XAML:
+
+```xml
+<Activity
+  mc:Ignorable="sap sap2010"
+  x:Class="WorkflowName"
+  mva:VisualBasic.Settings="{x:Null}"
+  xmlns="http://schemas.microsoft.com/netfx/2009/xaml/activities"
+  xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+  xmlns:mva="clr-namespace:Microsoft.VisualBasic.Activities;assembly=System.Activities"
+  xmlns:sap="http://schemas.microsoft.com/netfx/2009/xaml/activities/presentation"
+  xmlns:sap2010="http://schemas.microsoft.com/netfx/2010/xaml/activities/presentation"
+  xmlns:scg="clr-namespace:System.Collections.Generic;assembly=mscorlib"
+  xmlns:sco="clr-namespace:System.Collections.ObjectModel;assembly=mscorlib"
+  xmlns:ui="http://schemas.uipath.com/workflow/activities"
+  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
+
+  <!-- BASELINE NAMESPACE IMPORTS (21 — include ALL of these in every new VB.NET XAML) -->
+  <TextExpression.NamespacesForImplementation>
+    <sco:Collection x:TypeArguments="x:String">
+      <x:String>System.Activities</x:String>
+      <x:String>System.Activities.Statements</x:String>
+      <x:String>System.Activities.Expressions</x:String>
+      <x:String>System.Activities.Validation</x:String>
+      <x:String>System.Activities.XamlIntegration</x:String>
+      <x:String>Microsoft.VisualBasic</x:String>
+      <x:String>Microsoft.VisualBasic.Activities</x:String>
+      <x:String>System</x:String>
+      <x:String>System.Collections</x:String>
+      <x:String>System.Collections.Generic</x:String>
+      <x:String>System.Data</x:String>
+      <x:String>System.Diagnostics</x:String>
+      <x:String>System.Drawing</x:String>
+      <x:String>System.IO</x:String>
+      <x:String>System.Linq</x:String>
+      <x:String>System.Net.Mail</x:String>
+      <x:String>System.Xml</x:String>
+      <x:String>System.Xml.Linq</x:String>
+      <x:String>UiPath.Core</x:String>
+      <x:String>UiPath.Core.Activities</x:String>
+      <x:String>System.Windows.Markup</x:String>
+      <!-- Add package-specific namespaces below when using additional packages -->
+    </sco:Collection>
+  </TextExpression.NamespacesForImplementation>
+
+  <!-- BASELINE ASSEMBLY REFERENCES (16 — include ALL of these in every new VB.NET XAML) -->
+  <TextExpression.ReferencesForImplementation>
+    <sco:Collection x:TypeArguments="AssemblyReference">
+      <AssemblyReference>System.Activities</AssemblyReference>
+      <AssemblyReference>Microsoft.VisualBasic</AssemblyReference>
+      <AssemblyReference>mscorlib</AssemblyReference>
+      <AssemblyReference>System.Data</AssemblyReference>
+      <AssemblyReference>System.Data.DataSetExtensions</AssemblyReference>
+      <AssemblyReference>System</AssemblyReference>
+      <AssemblyReference>System.Drawing</AssemblyReference>
+      <AssemblyReference>System.Core</AssemblyReference>
+      <AssemblyReference>System.Xml</AssemblyReference>
+      <AssemblyReference>System.Xml.Linq</AssemblyReference>
+      <AssemblyReference>PresentationFramework</AssemblyReference>
+      <AssemblyReference>WindowsBase</AssemblyReference>
+      <AssemblyReference>PresentationCore</AssemblyReference>
+      <AssemblyReference>System.Xaml</AssemblyReference>
+      <AssemblyReference>UiPath.System.Activities</AssemblyReference>
+      <AssemblyReference>UiPath.UiAutomation.Activities</AssemblyReference>
+      <!-- Add package-specific assembly references below when using additional packages -->
+    </sco:Collection>
+  </TextExpression.ReferencesForImplementation>
+
+  <!-- x:Members (arguments) -->
+  <x:Members>
+    <x:Property Name="in_InputName" Type="InArgument(x:String)" />
+    <x:Property Name="out_Result" Type="OutArgument(x:String)" />
+  </x:Members>
+
+  <!-- Main workflow body -->
+  <Sequence DisplayName="Main Sequence" sap2010:WorkflowViewState.IdRef="Sequence_1">
+    <Sequence.Variables>
+      <Variable x:TypeArguments="x:String" Name="tempVar" Default="hello" />
+    </Sequence.Variables>
+    <!-- Activities go here -->
+  </Sequence>
+
+  <!-- ViewState (designer metadata - DO NOT EDIT) -->
+  <sap2010:WorkflowViewState.ViewStateManager>
+    <!-- ... -->
+  </sap2010:WorkflowViewState.ViewStateManager>
+</Activity>
+```
+
+### Key Differences from Modern XAML
+
+| Aspect | Legacy | Modern |
+|--------|--------|--------|
+| Root marker | `mva:VisualBasic.Settings="{x:Null}"` | No `mva:` marker; may have expression editor attribute |
+| Assembly xmlns | `assembly=mscorlib` | `assembly=System.Private.CoreLib` |
+| Expression types | `mva:VisualBasicValue` / `mva:VisualBasicReference` | Brackets `[expr]` or `CSharpValue` |
+| VB namespace | `xmlns:mva="clr-namespace:Microsoft.VisualBasic.Activities;assembly=System.Activities"` | Same or inferred |
+| Framework | .NET Framework 4.6.1 | .NET 6+ |
+
+---
+
+## VB.NET vs C# Expression Detection
+
+| Marker | VB.NET (Primary) | C# (Rare in Legacy) |
+|--------|-------------------|---------------------|
+| **Root attribute** | `mva:VisualBasic.Settings="{x:Null}"` | `sap2010:ExpressionActivityEditor.ExpressionActivityEditor="C#"` |
+| **Expression type** | `mva:VisualBasicValue<T>` / `mva:VisualBasicReference<T>` | `mca:CSharpValue<T>` / `mca:CSharpReference<T>` |
+| **Namespace xmlns** | `xmlns:mva="clr-namespace:Microsoft.VisualBasic.Activities;assembly=System.Activities"` | `xmlns:mca="clr-namespace:Microsoft.CSharp.Activities;assembly=System.Activities"` |
+| **project.json** | `"expressionLanguage": "VisualBasic"` | `"expressionLanguage": "CSharp"` |
+
+**Always check `project.json` `expressionLanguage` field before writing any expressions.**
+
+---
+
+## VB.NET Expression Syntax (Primary)
+
+VB.NET expressions use bracket notation `[expression]` inline in attributes:
+
+```xml
+<!-- Simple variable reference -->
+<ui:LogMessage Message="[myVariable]" />
+
+<!-- String concatenation -->
+<ui:LogMessage Message="[&quot;Hello &quot; + userName]" />
+
+<!-- Typed expression in InArgument -->
+<Assign.Value>
+  <InArgument x:TypeArguments="x:Int32">[counter + 1]</InArgument>
+</Assign.Value>
+
+<!-- Boolean condition -->
+<If Condition="[age >= 18]">
+
+<!-- FlowDecision with explicit VisualBasicValue -->
+<FlowDecision.Condition>
+  <mva:VisualBasicValue x:TypeArguments="x:Boolean" ExpressionText="counter &lt; 10" />
+</FlowDecision.Condition>
+```
+
+**XML escaping required inside expressions:** `<` → `&lt;`, `>` → `&gt;`, `"` → `&quot;`, `&` → `&amp;`
+
+**Throw.Exception quote escaping gotcha:** Fully-qualified class names + complex string expressions with multiple `&quot;` in `Throw.Exception` can cause compiler errors. Use short-form class names (`BusinessRuleException` not `UiPath.Core.Activities.BusinessRuleException`) and for complex messages, assign to a variable first then throw with the variable. See [common-pitfalls.md](./common-pitfalls.md#vbnet-quote-escaping-in-throwexception-critical-for-xaml-generation) for the full pattern.
+
+For comprehensive VB.NET expression patterns (strings, dates, collections, DataTables), see [activity-docs/_PATTERNS.md](./activity-docs/_PATTERNS.md).
+
+---
+
+## C# Expression Syntax (Secondary)
+
+C# expressions use `<mca:CSharpValue>` / `<mca:CSharpReference>` wrappers:
+
+```xml
+<!-- String value -->
+<ui:LogMessage.Message>
+  <InArgument x:TypeArguments="x:Object">
+    <mca:CSharpValue x:TypeArguments="x:Object">"Hello " + userName</mca:CSharpValue>
+  </InArgument>
+</ui:LogMessage.Message>
+
+<!-- Assign with CSharpReference (lvalue) and CSharpValue (rvalue) -->
+<Assign DisplayName="Set Name">
+  <Assign.To>
+    <OutArgument x:TypeArguments="x:String">
+      <mca:CSharpReference x:TypeArguments="x:String">fullName</mca:CSharpReference>
+    </OutArgument>
+  </Assign.To>
+  <Assign.Value>
+    <InArgument x:TypeArguments="x:String">
+      <mca:CSharpValue x:TypeArguments="x:String">firstName + " " + lastName</mca:CSharpValue>
+    </InArgument>
+  </Assign.Value>
+</Assign>
+```
+
+**Do NOT use `[bracket]` notation in C# projects** — brackets create `VisualBasicValue` nodes, causing validation failures for C#-only syntax.
+
+---
+
+## Workflow Types
+
+### Sequence
+Linear, top-to-bottom execution. **Most common** for legacy workflows.
+```xml
+<Sequence DisplayName="My Sequence" sap2010:WorkflowViewState.IdRef="Sequence_1">
+  <Sequence.Variables>
+    <Variable x:TypeArguments="x:String" Name="result" />
+  </Sequence.Variables>
+  <!-- Activities execute top to bottom -->
+</Sequence>
+```
+
+### Flowchart
+Visual branching with FlowStep, FlowDecision, and FlowSwitch nodes.
+```xml
+<Flowchart DisplayName="My Flowchart" sap2010:WorkflowViewState.IdRef="Flowchart_1">
+  <Flowchart.StartNode>
+    <x:Reference>__ReferenceID0</x:Reference>
+  </Flowchart.StartNode>
+  <FlowStep x:Name="__ReferenceID0">
+    <!-- Activity + FlowStep.Next -->
+  </FlowStep>
+  <FlowDecision x:Name="__ReferenceID1">
+    <FlowDecision.Condition>
+      <mva:VisualBasicValue x:TypeArguments="x:Boolean" ExpressionText="condition" />
+    </FlowDecision.Condition>
+    <FlowDecision.True>
+      <x:Reference>__ReferenceID0</x:Reference>
+    </FlowDecision.True>
+  </FlowDecision>
+</Flowchart>
+```
+
+### State Machine
+State-based workflow with transitions. Used in REFramework pattern.
+```xml
+<StateMachine InitialState="{x:Reference __ReferenceID_Init}" DisplayName="Process">
+  <State x:Name="__ReferenceID_Init" DisplayName="Init">
+    <State.Entry>
+      <Sequence><!-- Init activities --></Sequence>
+    </State.Entry>
+    <State.Transitions>
+      <Transition DisplayName="Success">
+        <Transition.Condition>[initSuccess]</Transition.Condition>
+        <Transition.To>
+          <x:Reference>__ReferenceID_Process</x:Reference>
+        </Transition.To>
+      </Transition>
+    </State.Transitions>
+  </State>
+  <State x:Name="__ReferenceID_End" DisplayName="End" IsFinal="True" />
+</StateMachine>
+```
+
+For complete workflow type templates with ViewState, see [activity-docs/_XAML-GUIDE.md](./activity-docs/_XAML-GUIDE.md).
+
+---
+
+## Arguments (In/Out/InOut)
+
+Arguments are declared in `<x:Members>` and define the workflow's public interface:
+
+```xml
+<x:Members>
+  <x:Property Name="in_CustomerName" Type="InArgument(x:String)" />
+  <x:Property Name="out_ProcessedCount" Type="OutArgument(x:Int32)" />
+  <x:Property Name="io_DataTable" Type="InOutArgument(sd:DataTable)" />
+</x:Members>
+```
+
+### Common Type Mappings
+
+| XAML Type | .NET Type | Notes |
+|-----------|-----------|-------|
+| `x:String` | System.String | |
+| `x:Int32` | System.Int32 | |
+| `x:Int64` | System.Int64 | |
+| `x:Boolean` | System.Boolean | |
+| `x:Double` | System.Double | |
+| `x:Object` | System.Object | |
+| `x:Decimal` | System.Decimal | |
+| `sd:DataTable` | System.Data.DataTable | Requires `xmlns:sd="clr-namespace:System.Data;assembly=System.Data"` |
+| `s:DateTime` | System.DateTime | **Cannot** use `x:DateTime` — it's not in the XAML schema |
+| `ss:SecureString` | System.Security.SecureString | Requires `xmlns:ss="clr-namespace:System.Security;assembly=mscorlib"` (NOT `xmlns:s` — SecureString is in `System.Security`, not `System`) |
+| `scg:Dictionary(x:String, x:Object)` | Dictionary\<String, Object\> | |
+| `scg:List(x:String)` | List\<String\> | |
+
+**IMPORTANT:** The `x:` schema only supports: String, Int32, Int64, Double, Boolean, Byte, Single, Decimal, Char, Object, TimeSpan. Any other CLR type must use the appropriate namespace prefix (e.g., `s:DateTime`, `sd:DataTable`).
+
+---
+
+## Variables
+
+Variables are scoped to their containing activity:
+
+```xml
+<Sequence.Variables>
+  <Variable x:TypeArguments="x:String" Name="filePath" />
+  <Variable x:TypeArguments="x:Int32" Name="counter" Default="0" />
+  <Variable x:TypeArguments="x:Boolean" Name="isValid" Default="True" />
+  <Variable x:TypeArguments="sd:DataTable" Name="dtResults" />
+</Sequence.Variables>
+```
+
+Variables declared in an outer container are accessible in nested containers but not across invoked workflows (use Arguments for that).
+
+---
+
+## XAML Safety Rules
+
+### ViewState Rules (Editing vs Generating)
+
+ViewState controls how activities appear in the designer. The rules differ for editing vs generating:
+
+**Editing existing workflows:**
+- Do NOT modify the global `<sap2010:WorkflowViewState.ViewStateManager>` section
+- Do NOT modify existing ViewState on nodes you're not changing
+- When **adding new nodes** to an existing Flowchart/StateMachine, **DO generate ViewState** (ShapeLocation, ShapeSize, ConnectorLocation) for the new nodes — read existing node positions first to avoid overlap
+
+**Generating new workflows:**
+- **Sequence workflows:** ViewState is optional — Studio auto-manages `IsExpanded`
+- **Flowchart workflows:** ViewState is **MANDATORY** — generate ShapeLocation, ShapeSize, ConnectorLocation for every FlowStep and FlowDecision, plus the Flowchart container's start node position
+- **StateMachine workflows:** ViewState is **MANDATORY** — generate ShapeLocation, ShapeSize for every State, plus StateContainerWidth/Height on the container
+
+**Without ViewState on Flowchart/StateMachine nodes, Studio stacks everything at (0,0) — producing an unusable jumbled pile.**
+
+See the Flowchart and StateMachine ViewState Layout Guides in [activity-docs/_XAML-GUIDE.md](./activity-docs/_XAML-GUIDE.md) for coordinate systems, standard sizes, layout algorithms, and complete examples.
+
+### Preserve xmlns Declarations
+Never remove existing `xmlns` attributes from the root `<Activity>` element. Only add new ones as needed.
+
+### Respect Expression Language
+Always check `project.json` `expressionLanguage` before writing expressions. Mixing VB.NET and C# expression syntax causes build failures.
+
+### Preserve Existing Structure
+When editing XAML:
+- Do not reformat or re-indent the entire file
+- Only modify the specific section you need to change
+- Use the `Edit` tool for targeted replacements (match exact `old_string`, replace with `new_string`)
+
+### Validate After Every Change
+Run `uip rpa-legacy validate` after every XAML modification. Do not batch multiple edits without validation.
+
+### Unique Identifiers
+- Every `x:Name` must be unique within the file
+- Every `sap2010:WorkflowViewState.IdRef` must be unique
+- `x:Reference` must match an existing `x:Name`
+
+---
+
+## Property Binding: Attributes vs Child Elements
+
+### Attribute Syntax (Inline)
+```xml
+<ui:LogMessage Message="[myVar]" Level="Info" />
+```
+
+### Child Element Syntax (Property Element)
+```xml
+<Assign DisplayName="Set Result">
+  <Assign.To>
+    <OutArgument x:TypeArguments="x:String">[resultVar]</OutArgument>
+  </Assign.To>
+  <Assign.Value>
+    <InArgument x:TypeArguments="x:String">["processed"]</InArgument>
+  </Assign.Value>
+</Assign>
+```
+
+**Simple values** (strings, enums, booleans, VB expressions) work as attributes. **Output properties** and **complex objects** typically require child element syntax.
+
+---
+
+## Managing References When Adding Packages (CRITICAL)
+
+**Every package you use in a XAML file MUST have its assembly references and namespace imports added to that file.** Missing a single assembly reference causes all expressions using types from that assembly to fail validation.
+
+This replicates what Studio does automatically when you drag an activity onto the canvas or add an import via the Imports panel. When generating XAML programmatically, you must do this manually.
+
+### UiPath Activity Packages
+
+When you add a UiPath activity package to `dependencies` in project.json and use its activities in a XAML file:
+
+1. Add `xmlns` declaration to root `<Activity>` — use `XmlnsDeclaration` from `find-activities` output
+2. Add `<AssemblyReference>` — use `AssemblyName` from `find-activities` output
+3. Add `<x:String>` namespace imports — use the activity's `Namespace` from `find-activities` output
+
+```xml
+<!-- Example: after adding UiPath.Excel.Activities to dependencies -->
+<!-- 1. xmlns on root Activity: -->
+xmlns:ueab="clr-namespace:UiPath.Excel.Activities.Business;assembly=UiPath.Excel.Activities"
+
+<!-- 2. Assembly reference: -->
+<AssemblyReference>UiPath.Excel.Activities</AssemblyReference>
+
+<!-- 3. Namespace imports: -->
+<x:String>UiPath.Excel</x:String>
+<x:String>UiPath.Excel.Activities.Business</x:String>
+```
+
+### Arbitrary .NET Packages
+
+When you add a NuGet package (e.g., `CsvHelper`, `HtmlAgilityPack`) and use its classes in expressions or InvokeCode:
+
+1. Add `<AssemblyReference>` with the package's assembly name
+2. Add `<x:String>` namespace import for the namespace you use
+3. If using in xmlns attributes, add `xmlns` declaration too
+
+```xml
+<!-- Example: after adding HtmlAgilityPack to dependencies -->
+<AssemblyReference>HtmlAgilityPack</AssemblyReference>
+<x:String>HtmlAgilityPack</x:String>
+```
+
+### C# Projects — Additional Baseline References
+
+C# legacy projects need these **in addition** to the 16 VB.NET baseline refs:
+
+```xml
+<AssemblyReference>Microsoft.CSharp</AssemblyReference>
+<AssemblyReference>System.Runtime.Serialization</AssemblyReference>
+<AssemblyReference>System.ServiceModel</AssemblyReference>
+<AssemblyReference>System.ServiceModel.Activities</AssemblyReference>
+```
+
+And this additional namespace import:
+```xml
+<x:String>System.Text</x:String>
+```
+
+---
+
+## xmlns Prefix Deconfliction
+
+`find-activities` may suggest the **same xmlns prefix** for activities from different CLR namespaces (e.g., both `LogMessage` and `ReadCsvFile` return `uca`). Using the same prefix for two different namespace URIs breaks the XAML.
+
+**Before writing XAML:**
+1. Collect all `XmlnsDeclaration` values from all activities you plan to use
+2. Check for prefix collisions (same prefix, different `clr-namespace` URI)
+3. Rename conflicting prefixes with descriptive abbreviations
+
+**Example conflict:**
+```xml
+<!-- Both returned "uca" but point to different namespaces — CONFLICT -->
+xmlns:uca="clr-namespace:UiPath.Core.Activities;assembly=UiPath.System.Activities"
+xmlns:uca="clr-namespace:UiPath.CSV.Activities;assembly=UiPath.Excel.Activities"
+
+<!-- Fix: rename one prefix -->
+xmlns:uca="clr-namespace:UiPath.Core.Activities;assembly=UiPath.System.Activities"
+xmlns:ucsvact="clr-namespace:UiPath.CSV.Activities;assembly=UiPath.Excel.Activities"
+```
+
+**Tip:** The `ui` schema prefix (`xmlns:ui="http://schemas.uipath.com/workflow/activities"`) covers most `UiPath.Core.Activities` — prefer it over CLR-based prefixes for core activities like LogMessage, InvokeCode, etc.
+
+---
+
+## XAML Generation Gotchas
+
+1. **Every `x:Name` must be unique** — FlowSteps use `__ReferenceID0`, `__ReferenceID1`, etc.
+2. **`x:Reference` must match an `x:Name`** — broken references crash the designer
+3. **Bracket expressions `[expr]` are VB.NET only** — C# must use `<mca:CSharpValue>` elements
+4. **XML escaping required**: `<` → `&lt;`, `>` → `&gt;`, `"` → `&quot;`, `&` → `&amp;`
+5. **Assembly references must include all dependencies** — missing refs cause compilation errors
+6. **`expressionLanguage` must match XAML expression style** — VB project with C# expressions crashes
+7. **Never add trailing `<x:Reference>` for Flowchart child nodes** — FlowStep/FlowDecision/FlowSwitch nodes defined inline as direct children of `<Flowchart>` must NOT be re-listed with `<x:Reference>` at the end. Only use `<x:Reference>` inside property elements (`Flowchart.StartNode`, `FlowStep.Next`, `FlowDecision.True/False`, etc.) to create cross-references
+8. **State Machine needs exactly one `IsFinal="True"` state** for proper termination
+9. **Legacy uses `assembly=mscorlib`** — not `assembly=System.Private.CoreLib` (which is .NET 6+)
+10. **Scope activities require `ActivityAction<T>` body** — `ExcelApplicationScope`, `ExcelProcessScopeX`, `ExcelApplicationCard`, `WordApplicationScope`, etc. do NOT accept direct children. They require a `.Body` property with `ActivityAction<T>` and `DelegateInArgument`. See [common-pitfalls.md](./common-pitfalls.md#scope-activities-require-activityaction-body-critical-for-xaml-generation) for the complete template.

package/skills/uipath-rpa/references/powershell-interop-guide.md

@@ -0,0 +1,68 @@
+# Invoking PowerShell from RPA Workflows
+
+## Default: Use a Coded Workflow Instead
+
+When the impulse is "drop into PowerShell," reach for a coded workflow (`[Workflow]` in a `.cs` file) first. A coded workflow runs in-process, surfaces real exceptions, and lives in one file with the rest of the project.
+
+Reach for PowerShell only when:
+
+1. The script needs Windows-admin cmdlets (`Get-ADUser`, `Mount-*`, etc.) awkward to call from .NET.
+2. The project already has `.ps1` scripts you must edit (don't rewrite for its own sake).
+3. Logic is genuinely PS-shaped (modules, pipeline-style data flow).
+
+For SharePoint REST, HTTP uploads, JSON parsing, file mangling — write a coded workflow. See [coded-vs-xaml-guide.md](coded-vs-xaml-guide.md).
+
+## When You Need PowerShell — Use the `InvokePowerShell` Activity
+
+`UiPath.Core.Activities.InvokePowerShell<T>` (`UiPath.System.Activities`) is the supported path. **Do not shell out via `Invoke Process` + `powershell.exe`** — that path requires manual quote escaping, exit-code parsing, and a status-file dance. `InvokePowerShell` handles parameter binding and output collection directly, and exceptions propagate as activity faults.
+
+### Properties
+
+| Property | Type | Notes |
+|----------|------|-------|
+| `CommandText` | `InArgument<string>` | Required. Script body or single command. |
+| `IsScript` | `InArgument<bool>` | `true` → multi-line script. `false` → single cmdlet invocation. |
+| `Parameters` | typed collection | Named bindings passed in. Verify the element type via `uip rpa activities get-default-xaml --activity-class-name "UiPath.Core.Activities.InvokePowerShell\`1"`. |
+| `Input` | `InArgument<IEnumerable>` | Pipeline input (`$input` inside the script). |
+| `Output` | `OutArgument<IEnumerable<T>>` | Collected results. `T` is the activity's generic type argument (e.g. `PSObject`, `string`). |
+| `PowerShellProcess` | enum | `WindowsPowerShell32` / `WindowsPowerShell64` / `PowerShellCore`. Pin the runtime explicitly. |
+| `ContinueOnError` | `InArgument<bool>` | Default `false`. PS exceptions propagate as activity faults. |
+
+### Minimal Pattern
+
+```xml
+<ui:InvokePowerShell x:TypeArguments="x:String"
+    CommandText="[scriptBody]"
+    IsScript="True"
+    PowerShellProcess="WindowsPowerShell64"
+    Output="[psOutput]" />
+```
+
+For typed parameter bindings, use the `Parameters` collection instead of building a command line — no string concatenation, no quote escaping. Look up the element type with `activities get-default-xaml` before authoring.
+
+### Choosing `PowerShellProcess`
+
+| Value | Runtime | When to use |
+|-------|---------|-------------|
+| `WindowsPowerShell64` | Windows PowerShell 5.1, 64-bit | Default for Windows robots; broadest cmdlet compatibility. |
+| `WindowsPowerShell32` | Windows PowerShell 5.1, 32-bit | Legacy 32-bit modules only. |
+| `PowerShellCore` | PowerShell 7+ | Cross-platform. Requires `pwsh` installed on the robot. Needed for 7+-only features (`Invoke-WebRequest -InFile`, `ConvertFrom-Json -AsHashtable`, ternary, null-conditional, `&&`/`\|\|`). |
+
+Always set `PowerShellProcess` explicitly so a robot upgrade does not silently change the runtime.
+
+## Last-Resort `Invoke Process`
+
+Some scenarios force a direct shellout — a vendor script with exact-CLI requirements, or an interactive session. In that case:
+
+1. **Pin the executable.** `FileName="powershell.exe"` for 5.1, `FileName="pwsh.exe"` for 7+. Do not rely on PATH.
+2. **Escape quotes in every value** embedded in `Arguments`. A single `"` or `'` in a path silently shifts every later positional arg.
+   - VB: `value.Replace("""", """""")`
+   - C#: `value.Replace("\"", "\"\"")`
+3. **Status by file, not stdout.** `Invoke Process` returns the exit code only. Wrap the script body in `try { … } catch { Out-File -FilePath $statusFile -InputObject ("ERROR: " + $_.Exception.Message); exit 1 }` so failures are never silent. Read the file after, then delete it.
+
+## Anti-Patterns
+
+1. **Defaulting to PowerShell when a coded workflow would do.** See § Default.
+2. **Using `Invoke Process` when `InvokePowerShell` works.** Skipping the typed activity for no reason triples the gotcha surface.
+3. **Driving UI from PowerShell.** Use UiPath UIAutomation activities — [ui-automation-guide.md](ui-automation-guide.md) MUST be read IN FULL first.
+4. **Omitting `PowerShellProcess`.** A robot upgrade can silently land your script on a different runtime.

package/skills/uipath-rpa/references/project-structure-guide.md

@@ -0,0 +1,125 @@
+# Designing Project Structure
+
+When creating a project, **proactively design the right file structure** based on the task complexity. Do not put everything into a single root workflow file. Use your best judgment to split the project into multiple files following good software engineering practices.
+
+For the coded vs XAML decision, see [coded-vs-xaml-guide.md](coded-vs-xaml-guide.md). For new projects, the default is XAML — examples below lead with XAML and note where the coded equivalent differs.
+
+## Guidelines
+
+- **Single simple task** (e.g. "read a CSV and log it") — one workflow file (`Main.xaml` for XAML projects, `Main.cs` for coded) is fine
+- **Multi-step process** (e.g. "read invoices, validate, post to system") — split into multiple workflow files, each handling one step. The root workflow invokes each step
+- **Shared data structures** — extract into a Coded Source File (e.g. `Models.cs`, `InvoiceData.cs`). XAML cannot define types, so a Coded Source File is the right home even in an otherwise XAML project
+- **Repeated logic** — in XAML projects, extract into a reusable XAML workflow. In coded or hybrid projects, extract into a helper Coded Source File (e.g. `ValidationHelpers.cs`)
+- **Test project** — one test case per scenario. Coded test projects optionally use `partial class CodedWorkflow : IBeforeAfterRun` in `CodedWorkflowHooks.cs` for shared setup. XAML test projects use Test Activities for shared setup
+- **Complex domain logic** — isolate business rules so they can be unit-tested and reused (Coded Source File for typed logic, or a separate workflow for activity-driven logic)
+
+## Example — Invoice Processing Project (XAML)
+
+```
+InvoiceProcessor/
+├── project.json
+├── Main.xaml                  # Root workflow: sequences each step via Invoke Workflow File
+├── ReadInvoices.xaml          # Step 1: reads invoices from Excel
+├── ValidateInvoices.xaml      # Step 2: validates data
+├── PostToERP.xaml             # Step 3: posts to external system
+└── InvoiceData.cs             # Coded source file: typed data model used across XAML steps
+```
+
+`Main.xaml` invokes each step via `Invoke Workflow File`, passing arguments In/Out. `InvoiceData.cs` is included even in this otherwise-XAML project because XAML cannot define types — typed DTOs eliminate `DataTable` column-name guessing.
+
+### Coded equivalent
+
+```
+InvoiceProcessor/
+├── project.json
+├── Main.cs                    # Root workflow: calls each step via workflows.StepName()
+├── ReadInvoices.cs            # Step 1
+├── ValidateInvoices.cs        # Step 2
+├── PostToERP.cs               # Step 3
+├── InvoiceData.cs             # Coded source file: data model
+└── ValidationHelpers.cs       # Coded source file: validation utilities
+```
+
+`Main.cs` uses strongly-typed workflow invocation:
+
+```csharp
+[Workflow]
+public void Execute(string inputFolder)
+{
+    var readResult = workflows.ReadInvoices(folderPath: inputFolder);
+    Log($"Read {readResult.count} invoices");
+
+    var validateResult = workflows.ValidateInvoices(invoices: readResult.invoiceList);
+    Log($"Valid: {validateResult.validCount}, Invalid: {validateResult.invalidCount}");
+
+    var postResult = workflows.PostToERP(validInvoices: validateResult.validInvoices);
+    Log($"Posted {postResult.successCount} invoices to ERP");
+}
+```
+
+## Example — Test Project
+
+```
+InvoiceTests/
+├── project.json
+├── CodedWorkflowHooks.cs      # Coded test projects only: partial class CodedWorkflow with Before/After hooks
+├── TestLoginFlow.cs           # Test case: login scenario (hooks apply automatically via partial class merge)
+├── TestInvoiceCreation.cs     # Test case: create invoice scenario
+├── TestInvoiceValidation.cs   # Test case: validation rules
+└── TestData.cs                # Source file: shared test constants/fixtures
+```
+
+XAML test projects use `.xaml` test cases instead of `.cs` and Test Activities for shared setup; the rest of the layout is the same.
+
+## Example — Hybrid Project (XAML Root + Coded Logic)
+
+```
+OrderProcessing/
+├── project.json
+├── Main.xaml                  # XAML root workflow: sequences steps, handles retries
+├── ScrapeOrderPortal.xaml     # XAML: UI automation with visual selector builder
+├── SendConfirmationEmail.xaml # XAML: Mail activities (straightforward)
+├── ProcessOrder.cs            # Coded workflow: 12 validation rules + LINQ transforms
+├── OrderModels.cs             # Coded source file: Order, LineItem, ValidationResult DTOs
+├── TransformHelpers.cs        # Coded source file: date parsing, currency conversion
+└── TestProcessOrder.cs        # Coded test case: unit tests for ProcessOrder logic
+```
+
+### Why hybrid here
+
+- **ScrapeOrderPortal.xaml** — UI automation benefits from XAML's visual selector builder and recording tools
+- **ProcessOrder.cs** — Order validation has 12 business rules with nested conditions; coded C# is clearer and testable
+- **OrderModels.cs** — Typed DTOs used by both XAML (via typed arguments) and coded workflows, eliminating DataTable column-name guessing
+- **SendConfirmationEmail.xaml** — Simple Mail activity, no logic — XAML is the simpler choice
+- **Main.xaml** — Orchestration is linear (scrape → process → email); XAML Sequence is readable
+
+### Data flow
+
+1. `Main.xaml` invokes `ScrapeOrderPortal.xaml` → returns `DataTable` via Out argument
+2. `Main.xaml` invokes `ProcessOrder.cs` via Invoke Workflow File → passes raw data, returns validated `Order` objects
+3. `Main.xaml` invokes `SendConfirmationEmail.xaml` → passes validated order data
+
+## Project Structure Decision Tree
+
+**First — coded or XAML?** For new projects, default to XAML unless the user explicitly said "coded" or named a coded-specific trigger (custom data models, complex algorithms, unit tests on business logic). See [coded-vs-xaml-guide.md](coded-vs-xaml-guide.md). The root workflow is `Main.xaml` for XAML projects and `Main.cs` for coded projects — substitute accordingly below.
+
+**Is it a single, simple task?**
+- ✅ Yes → Single root workflow
+
+**Is it a multi-step process?**
+- ✅ Yes → A root workflow that invokes each step + separate workflow files for each step
+
+**Does it involve repeated data structures?**
+- ✅ Yes → Extract to Coded Source File (e.g. `Models.cs`, `InvoiceData.cs`). Required even in XAML projects — XAML cannot define types
+
+**Is there shared logic across workflows?**
+- ✅ Yes → Extract to a reusable XAML workflow (XAML projects) or a helper Coded Source File (coded or hybrid projects)
+
+**Is it a test project?**
+- ✅ Yes → One test case file per scenario. Coded test projects optionally use `CodedWorkflowHooks.cs` (partial class CodedWorkflow) for shared setup/teardown
+
+**Does it have complex business rules?**
+- ✅ Yes → Isolate in Coded Source Files for reusability and testability (extract from XAML via `Invoke Workflow File` if needed)
+
+**Does it need both UI automation AND complex non-UI logic?**
+- ✅ Yes → Hybrid: XAML for UI automation + orchestration, Coded for business logic + data models. See [coded-vs-xaml-guide.md](coded-vs-xaml-guide.md)