Skip to content

Quick Start

Jump to bottom
Calvindd2f edited this page Jan 14, 2026 · 1 revision

Quick Start

Relevant source files

The following files were used as context for generating this wiki page:

This guide provides step-by-step instructions to install and run OfficeScrubC2R for the first time. This page focuses on getting you operational quickly with minimal configuration. For detailed system requirements, see System Requirements. For comprehensive usage scenarios, see User Guide.

Prerequisites

Before installing OfficeScrubC2R, ensure your system meets these basic requirements:

Requirement Minimum Recommended
Operating System Windows 7 SP1 Windows 10/11
PowerShell 5.1 7.0+
.NET Framework 4.5 4.8
Privileges Administrator Administrator
Architecture x86 or x64 x64

For detailed requirements and compatibility information, see System Requirements.

Sources: docs/memory-bank/product.md:58-64

Installation

PowerShell Gallery Installation (Recommended)

The fastest way to install OfficeScrubC2R is from PowerShell Gallery:

# Install for all users (requires administrator privileges)
Install-Module -Name OfficeScrubC2R -Scope AllUsers

# Or install for current user only
Install-Module -Name OfficeScrubC2R -Scope CurrentUser

# Import the module
Import-Module OfficeScrubC2R

Manual Installation from Repository

If you prefer to install from source or PowerShell Gallery is not accessible:

# Clone or download the repository
git clone https://github.com/Calvindd2f/OfficeScrubC2R.git
cd OfficeScrubC2R

# Import the module from the repository root
Import-Module .\OfficeScrubC2R.psd1 -Force

For detailed installation instructions including offline installation and troubleshooting, see Installation.

Sources: README.md:17-19, OfficeScrubC2R.psm1:1-8

Quick Start Workflow

flowchart TD
    Start["Start: Administrator PowerShell"] --> Install["Install-Module OfficeScrubC2R"]
    Install --> Import["Import-Module OfficeScrubC2R"]
    Import --> LoadNative["Import-OfficeScrubNative"]
    LoadNative --> CreateOrch["New-OfficeScrubOrchestrator"]
    CreateOrch --> Decision{"What do you want to do?"}
    
    Decision -->|"Detect Office"| TestPath["Test-OfficeC2RPath"]
    Decision -->|"Check Product"| TestScope["Test-OfficeProductScope"]
    Decision -->|"Access Helpers"| GetHelpers["Get-OfficeScrubHelpers"]
    
    TestPath --> UseOrch["Use $orchestrator methods"]
    TestScope --> UseOrch
    GetHelpers --> UseHelpers["Use $helpers.RegistryHelper<br/>$helpers.FileHelper<br/>etc."]
    
    UseOrch --> Complete["Complete"]
    UseHelpers --> Complete
    
    style Start fill:#f9f9f9
    style Install fill:#f9f9f9
    style CreateOrch fill:#f9f9f9
    style Complete fill:#f9f9f9
Loading

Sources: README.md:17-35, OfficeScrubC2R.psm1:10-98

First Usage Examples

Example 1: Load Module and Create Orchestrator

The OfficeScrubOrchestrator is the central coordinator that wires up all helper classes. Create an instance as your first step:

# Import the module
Import-Module OfficeScrubC2R

# Load the native DLL (happens automatically when needed, but can be done explicitly)
Import-OfficeScrubNative

# Create the orchestrator with automatic bitness detection
$orchestrator = New-OfficeScrubOrchestrator

# Or explicitly specify 64-bit mode
$orchestrator = New-OfficeScrubOrchestrator -Is64Bit $true

The orchestrator automatically detects your system architecture using [Environment]::Is64BitOperatingSystem and configures the native library accordingly.

Sources: OfficeScrubC2R.psm1:37-46, README.md:21-22

Example 2: Detect Click-to-Run Installations

Use Test-OfficeC2RPath to determine if a path contains an Office Click-to-Run installation:

# Test common Office installation paths
$paths = @(
    "C:\Program Files\Microsoft Office",
    "C:\Program Files (x86)\Microsoft Office",
    "C:\Program Files\Microsoft Office 16"
)

foreach ($path in $paths) {
    $isC2R = Test-OfficeC2RPath -Path $path -Orchestrator $orchestrator
    Write-Host "$path : $isC2R"
}

This cmdlet delegates to the native OfficeScrubOrchestrator.IsC2RPath() method, which validates paths against Click-to-Run installation patterns.

Sources: OfficeScrubC2R.psm1:48-60, README.md:24-25

Example 3: Validate Product Codes

Use Test-OfficeProductScope to check whether a product GUID is in scope for cleanup operations:

# Test a specific Office product code
$productCode = '{9AC08E99-230B-47E8-9721-4577B7F124EA}'
$inScope = Test-OfficeProductScope -ProductCode $productCode -Orchestrator $orchestrator

if ($inScope) {
    Write-Host "Product $productCode is an Office Click-to-Run product in scope for cleanup"
} else {
    Write-Host "Product $productCode is not in scope"
}

This delegates to OfficeScrubOrchestrator.IsInScope(), which validates GUIDs against known Office product patterns.

Sources: OfficeScrubC2R.psm1:62-74, README.md:27-28

Example 4: Access Helper Classes

Use Get-OfficeScrubHelpers to retrieve the specialized helper class instances for direct operations:

# Get all helper classes
$helpers = Get-OfficeScrubHelpers -Orchestrator $orchestrator

# Access individual helpers
$helpers.RegistryHelper    # Registry operations with WOW64 support
$helpers.FileHelper        # File system operations with reboot scheduling
$helpers.ProcessHelper     # Process management with parallel execution
$helpers.ShellHelper       # Shell integration cleanup
$helpers.WindowsInstallerHelper  # MSI metadata cleanup
$helpers.TypeLibHelper     # COM type library operations
$helpers.LicenseHelper     # Office license and SPP operations
$helpers.ServiceHelper     # Windows service management

Each helper class encapsulates operations for a specific Windows subsystem. For detailed documentation of helper methods, see Helper Classes.

Sources: OfficeScrubC2R.psm1:76-96, README.md:30-33

Module Commands Reference

graph TB
    Module["OfficeScrubC2R Module"] --> ImportNative["Import-OfficeScrubNative"]
    Module --> NewOrch["New-OfficeScrubOrchestrator"]
    Module --> TestPath["Test-OfficeC2RPath"]
    Module --> TestScope["Test-OfficeProductScope"]
    Module --> GetHelpers["Get-OfficeScrubHelpers"]
    
    ImportNative --> DLL["Loads OfficeScrubNative.dll<br/>from module directory"]
    NewOrch --> Orch["Returns OfficeScrubOrchestrator<br/>instance with helper classes"]
    TestPath --> PathMethod["Calls orchestrator.IsC2RPath()"]
    TestScope --> ScopeMethod["Calls orchestrator.IsInScope()"]
    GetHelpers --> HelpersObj["Returns PSCustomObject with<br/>8 helper class properties"]
    
    Orch --> Registry["Registry"]
    Orch --> Files["Files"]
    Orch --> Processes["Processes"]
    Orch --> Shell["Shell"]
    Orch --> WinInstaller["WindowsInstaller"]
    Orch --> TypeLib["TypeLib"]
    Orch --> License["License"]
    Orch --> Services["Services"]
    
    style Module fill:#f9f9f9
    style Orch fill:#f9f9f9
Loading
Command Purpose Returns
Import-OfficeScrubNative Loads OfficeScrubNative.dll from module directory Assembly object
New-OfficeScrubOrchestrator Creates orchestrator with all helper classes initialized OfficeScrubOrchestrator instance
Test-OfficeC2RPath Validates if a path matches Click-to-Run patterns Boolean
Test-OfficeProductScope Checks if a product GUID is in scope for cleanup Boolean
Get-OfficeScrubHelpers Returns helper class instances for direct operations PSCustomObject with 8 properties

Sources: OfficeScrubC2R.psm1:10-98, README.md:37-45

Verification

After installation, verify the module loaded correctly:

# Check module is imported
Get-Module OfficeScrubC2R

# Verify exported commands
Get-Command -Module OfficeScrubC2R

# Test native DLL loading
$assembly = Import-OfficeScrubNative
$assembly.Location
$assembly.GetTypes() | Where-Object { $_.Name -eq 'OfficeScrubOrchestrator' }

# Create and test orchestrator
$orch = New-OfficeScrubOrchestrator
$orch.GetType().FullName  # Should output: OfficeScrubNative.OfficeScrubOrchestrator

Expected output for Get-Command -Module OfficeScrubC2R:

CommandType     Name                           Version    Source
-----------     ----                           -------    ------
Function        Get-OfficeScrubHelpers         1.0.0      OfficeScrubC2R
Function        Import-OfficeScrubNative       1.0.0      OfficeScrubC2R
Function        New-OfficeScrubOrchestrator    1.0.0      OfficeScrubC2R
Function        Test-OfficeC2RPath             1.0.0      OfficeScrubC2R
Function        Test-OfficeProductScope        1.0.0      OfficeScrubC2R

Sources: OfficeScrubC2R.psm1:10-35, OfficeScrubC2R.psm1:98

Module Loading Architecture

graph TB
    PSGallery["PowerShell Gallery<br/>or Manual Import"] --> Manifest["OfficeScrubC2R.psd1<br/>Module Manifest"]
    Manifest --> MainModule["OfficeScrubC2R.psm1<br/>Main Module"]
    
    MainModule --> ModuleVars["Script Variables<br/>$script:ModuleRoot<br/>$script:NativeAssemblyPath<br/>$script:NativeAssembly"]
    
    MainModule --> ImportFunc["Import-OfficeScrubNative"]
    ImportFunc --> CheckPath{"DLL Exists at<br/>$NativeAssemblyPath?"}
    CheckPath -->|No| Error["Throw Error:<br/>DLL Not Found"]
    CheckPath -->|Yes| CheckLoaded{"Already Loaded<br/>in AppDomain?"}
    
    CheckLoaded -->|Yes| Return1["Return Existing<br/>Assembly"]
    CheckLoaded -->|No| LoadDLL["Assembly.LoadFrom()<br/>OfficeScrubNative.dll"]
    LoadDLL --> SetVar["Set $script:NativeAssembly"]
    SetVar --> Return2["Return Assembly"]
    
    Return1 --> Available["Native Types Available"]
    Return2 --> Available
    
    Available --> NewOrch["New-OfficeScrubOrchestrator<br/>Creates Instance"]
    NewOrch --> OrchestratorObj["OfficeScrubOrchestrator<br/>with 8 Helper Classes"]
    
    style Manifest fill:#f9f9f9
    style MainModule fill:#f9f9f9
    style OrchestratorObj fill:#f9f9f9
Loading

The module uses a lazy-loading pattern for the native assembly. The DLL is loaded into the AppDomain only when first accessed, and subsequent calls return the cached assembly reference.

Sources: OfficeScrubC2R.psm1:1-35, OfficeScrubC2R.psm1:37-46

Common First-Time Issues

Issue Cause Solution
"Native assembly not found" DLL missing from module directory Re-install module or ensure OfficeScrubNative.dll is present
"Access denied" Not running as administrator Launch PowerShell with administrative privileges
Module not found Module not in PSModulePath Use -Force with Import-Module or specify full path to .psd1
Cannot load assembly Zone identifier block Unblock files: Get-ChildItem -Recurse | Unblock-File
Wrong PowerShell version Running PowerShell 2.0-4.0 Upgrade to PowerShell 5.1 or 7+

For comprehensive troubleshooting, see Troubleshooting.

Sources: OfficeScrubC2R.psm1:19-21, docs/memory-bank/product.md:58-64

Next Steps

After completing this quick start:

  1. Review System Requirements: See System Requirements for detailed compatibility information
  2. Understand the Architecture: See Architecture to learn how the hybrid PowerShell/C# design works
  3. Learn the Execution Pipeline: See Three-Stage Execution Pipeline for cleanup workflow details
  4. Explore Helper Classes: See Helper Classes for detailed API documentation
  5. Review Usage Examples: See Use Cases and Examples for real-world scenarios

For immediate Office cleanup operations, refer to Operational Modes and Command-Line Parameters.

Sources: README.md:1-71, docs/memory-bank/product.md:1-72

Clone this wiki locally