Cesivi PowerShell Troubleshooting Guide¶

This guide helps you diagnose and resolve common issues with Cesivi PowerShell cmdlets.

Table of Contents¶

Module Issues
Connection Issues
Cmdlet Errors
Performance Issues
Debugging Tips

Module Issues¶

Module Not Found¶

Symptom:

Import-Module : The specified module 'Cesivi.PowerShell' was not loaded because no valid module file was found

Diagnosis:

# Check if DLL exists
Test-Path .\Cesivi.PowerShell\bin\Debug\net10.0\Cesivi.PowerShell.dll

Solutions:

Build the module:

cd C:\Source\_AI\Cesivi
dotnet build Cesivi.PowerShell

Import using full path:

$modulePath = "C:\Source\_AI\Cesivi\Cesivi.PowerShell\bin\Debug\net10.0\Cesivi.PowerShell.dll"
Import-Module $modulePath -Force

Check build errors:

dotnet build Cesivi.PowerShell --verbosity quiet
# Look for errors in output

Module Already Loaded (Different Version)¶

Symptom:

WARNING: The names of some imported commands conflict with existing commands

Solution:

# Remove old module
Remove-Module Cesivi.PowerShell -ErrorAction SilentlyContinue

# Import new version
Import-Module .\Cesivi.PowerShell\bin\Debug\net10.0\Cesivi.PowerShell.dll -Force

Cmdlets Not Found After Import¶

Symptom:

Get-CSSite : The term 'Get-CSSite' is not recognized as the name of a cmdlet

Diagnosis:

# Check if module loaded
Get-Module Cesivi.PowerShell

# List available cmdlets
Get-Command -Module Cesivi.PowerShell

Solutions:

Verify module loaded correctly:

$module = Get-Module Cesivi.PowerShell
if ($module) {
    Write-Host "Module loaded: $($module.Path)"
    Write-Host "Exported commands: $($module.ExportedCommands.Count)"
} else {
    Write-Host "Module not loaded"
}

Check PowerShell version:

$PSVersionTable.PSVersion
# Should be 7.0 or higher

Reimport with verbose:

Import-Module .\Cesivi.PowerShell\bin\Debug\net10.0\Cesivi.PowerShell.dll -Verbose

Wrong .NET Version¶

Symptom:

Could not load file or assembly 'System.Management.Automation'

Solution:

# Check .NET version
dotnet --version
# Should be 10.0 or higher

# Rebuild for correct target
dotnet build Cesivi.PowerShell --framework net10.0

Connection Issues¶

Cannot Connect to Server¶

Symptom:

Get-CSSite : Unable to connect to Cesivi Server at http://localhost:5000
Connection refused

Diagnosis:

# Test server connectivity
Test-NetConnection localhost -Port 5000

# Or using curl
curl http://localhost:5000/_api/site

Solutions:

Start Cesivi Server:

# In a separate terminal
cd C:\Source\_AI\Cesivi\Cesivi.Server
dotnet run

Check server is running:

# Check process
Get-Process | Where-Object { $_.Name -like "*Cesivi*" }

# Check listening ports
netstat -ano | findstr :5000

Use correct server URL:

# If server runs on different port
Get-CSSite -All -ServerUrl "http://localhost:5001"

# Or set environment variable
$env:CESIVI_SERVER_URL = "http://localhost:5001"

Timeout Errors¶

Symptom:

The operation has timed out

Diagnosis:

# Measure request time
Measure-Command {
    Get-CSSite -All -ServerUrl "http://localhost:5000"
}

Solutions:

Check server performance:

# Check server CPU/memory usage
Get-Process | Where-Object { $_.Name -like "*Cesivi*" } |
    Format-Table Name, CPU, WorkingSet64

Increase timeout (if supported):

# Future enhancement - timeout parameter
# Get-CSSite -All -Timeout 60

Check network:

# Ping server
Test-Connection localhost

# Check firewall
Get-NetFirewallRule | Where-Object { $_.DisplayName -like "*5000*" }

SSL/HTTPS Errors¶

Symptom:

The SSL connection could not be established

Solution:

# For development, use HTTP instead of HTTPS
$env:CESIVI_SERVER_URL = "http://localhost:5000"

# Or bypass SSL validation (DEVELOPMENT ONLY)
# Not currently supported - feature for future enhancement

Cmdlet Errors¶

Parameter Validation Errors¶

Symptom:

Cannot validate argument on parameter 'Url'. The argument is null or empty.

Solution:

# Ensure required parameters provided
New-CSSite -Url "/sites/example" -Title "Example" -OwnerLogin "admin"

# Check parameter requirements
Get-Help New-CSSite -Parameter Url

Object Not Found¶

Symptom:

Get-CSSite : Site not found: /sites/nonexistent

Diagnosis:

# List all sites
Get-CSSite -All | Format-Table Url, Title

# Check if site exists
$exists = Get-CSSite -All | Where-Object { $_.Url -eq "/sites/example" }
if ($exists) {
    Write-Host "Site exists"
} else {
    Write-Host "Site not found"
}

Solution:

# Create site if doesn't exist
if (-not (Get-CSSite -All | Where-Object { $_.Url -eq "/sites/example" })) {
    New-CSSite -Url "/sites/example" -Title "Example" -OwnerLogin "admin"
}

Already Exists Error¶

Symptom:

New-CSSite : Site already exists: /sites/example

Solution:

# Check if site exists first
$site = Get-CSSite -All | Where-Object { $_.Url -eq "/sites/example" }

if ($site) {
    Write-Host "Site already exists, updating..."
    Set-CSSite -Identity "/sites/example" -Title "Updated Title"
} else {
    Write-Host "Creating new site..."
    New-CSSite -Url "/sites/example" -Title "Example" -OwnerLogin "admin"
}

Permission Denied¶

Symptom:

Access denied. You do not have permission to perform this action.

Solution:

# Check authentication
# Future enhancement - authentication support

# For now, Cesivi Server runs in development mode
# No authentication required

Invalid URL Format¶

Symptom:

The URL '/sites/example' is not valid

Solution:

# Use relative URLs, not absolute
# Good:
New-CSSite -Url "/sites/example" -Title "Example" -OwnerLogin "admin"

# Bad:
New-CSSite -Url "http://localhost:5000/sites/example" -Title "Example" -OwnerLogin "admin"

# Validate URL format
$url = "/sites/example"
if ($url -match '^/') {
    Write-Host "URL format valid"
} else {
    Write-Host "URL should start with /"
}

Performance Issues¶

Slow Cmdlet Execution¶

Symptom: Cmdlets take several seconds to complete.

Diagnosis:

# Measure cmdlet performance
Measure-Command { Get-CSSite -All }

# Compare with direct API call
Measure-Command {
    Invoke-RestMethod -Uri "http://localhost:5000/_api/sites" -Method Get
}

Solutions:

Check server performance:

# Monitor server during cmdlet execution
Get-Process | Where-Object { $_.Name -like "*Cesivi*" } |
    Select-Object Name, CPU, WorkingSet64, Threads

Use filtering on server side (future enhancement):

# Instead of:
Get-CSSite -All | Where-Object { $_.Title -like "*Team*" }

# Use server-side filtering (when implemented):
# Get-CSSite -Filter "Title like 'Team'"

Cache results:

# Cache site list for repeated queries
$script:siteCache = Get-CSSite -All
$script:siteCacheTime = Get-Date

function Get-CachedSites {
    $cacheAge = (Get-Date) - $script:siteCacheTime
    if ($cacheAge.TotalMinutes -gt 5) {
        Write-Host "Refreshing cache..."
        $script:siteCache = Get-CSSite -All
        $script:siteCacheTime = Get-Date
    }
    return $script:siteCache
}

# Use cached data
$sites = Get-CachedSites

High Memory Usage¶

Symptom: PowerShell process uses excessive memory.

Solution:

# Process large result sets in batches
$sites = Get-CSSite -All

foreach ($site in $sites) {
    # Process one site at a time
    # Heavy processing here

    # Clear variables
    Remove-Variable site -ErrorAction SilentlyContinue
    [System.GC]::Collect()
}

Debugging Tips¶

Enable Verbose Output¶

# Use -Verbose with cmdlets (when implemented)
Get-CSSite -All -Verbose

# Or set global preference
$VerbosePreference = "Continue"
Get-CSSite -All
$VerbosePreference = "SilentlyContinue"

Capture Errors¶

# Capture errors for analysis
$ErrorActionPreference = "Continue"

try {
    Get-CSSite -Identity "/sites/example"
}
catch {
    Write-Host "Error occurred:"
    Write-Host "Message: $($_.Exception.Message)"
    Write-Host "Type: $($_.Exception.GetType().FullName)"
    Write-Host "Stack trace: $($_.Exception.StackTrace)"
}

Test REST API Directly¶

# Bypass cmdlets, test API directly
$serverUrl = "http://localhost:5000"

# Get sites
$response = Invoke-RestMethod -Uri "$serverUrl/_api/sites" -Method Get
$response

# Get specific site
$response = Invoke-RestMethod -Uri "$serverUrl/_api/site" -Method Get
$response

Check Cmdlet Parameters¶

# View all parameters
Get-Help Get-CSSite -Parameter *

# View cmdlet source (if available)
$cmd = Get-Command Get-CSSite
$cmd.ImplementingType.Assembly.Location

Trace HTTP Requests¶

# Use Fiddler or similar tool to capture HTTP traffic
# Configure proxy:
$env:HTTP_PROXY = "http://localhost:8888"
$env:HTTPS_PROXY = "http://localhost:8888"

# Run cmdlet
Get-CSSite -All

# Check captured requests in Fiddler

Compare with SharePoint¶

# If you have SharePoint available, compare behavior

# SharePoint
Add-PSSnapin Microsoft.SharePoint.PowerShell
$spSite = Get-SPSite http://sharepoint.local/sites/team
$spSite | Get-Member

# Cesivi
Import-Module Cesivi.PowerShell
$csSite = Get-CSSite -Identity "/sites/team"
$csSite | Get-Member

# Compare properties
Compare-Object ($spSite | Get-Member -MemberType Property).Name `
               ($csSite | Get-Member -MemberType Property).Name

Common Error Messages¶

"Assembly not loaded"¶

Full error:

Could not load file or assembly 'System.Management.Automation, Version=7.0.0.0'

Solution: Ensure you're using PowerShell 7+, not Windows PowerShell 5.1:

# Check version
$PSVersionTable.PSVersion

# Download PowerShell 7+ from:
# https://github.com/PowerShell/PowerShell/releases

"Method not found"¶

Full error:

Method 'ProcessRecord' in type 'GetCSSiteCmdlet' does not have an implementation

Solution: Rebuild the module:

dotnet clean Cesivi.PowerShell
dotnet build Cesivi.PowerShell

"Type not found"¶

Full error:

Unable to find type [Cesivi.Models.SharePoint.SPSite]

Solution: Ensure all dependencies are built:

dotnet build  # Build entire solution
Import-Module .\Cesivi.PowerShell\bin\Debug\net10.0\Cesivi.PowerShell.dll -Force

Getting Help¶

Built-in Help¶

# Get cmdlet help
Get-Help Get-CSSite
Get-Help Get-CSSite -Full
Get-Help Get-CSSite -Examples
Get-Help Get-CSSite -Parameter Identity

# List all cmdlets
Get-Command -Module Cesivi.PowerShell

# Get about topics
Get-Help about_Cesivi_PowerShell
Get-Help about_CS_Site_Cmdlets

Log Files¶

Check Cesivi Server logs for errors:

# Server log location (adjust path as needed)
Get-Content C:\Source\_AI\Cesivi\Cesivi.Server\logs\cesivi-*.log -Tail 50

Reporting Issues¶

When reporting issues, include:

PowerShell version:
```
$PSVersionTable
```

Module version:

Get-Module Cesivi.PowerShell | Format-List Name, Version, Path

Server version:

Invoke-RestMethod -Uri "http://localhost:5000/_api/version"

Error details:
```
$Error[0] | Format-List * -Force
```

Reproduction steps:

# Minimal script that reproduces the issue
Import-Module Cesivi.PowerShell
Get-CSSite -Identity "/sites/example"  # Fails here

Cesivi PowerShell Troubleshooting Guide¶

Table of Contents¶

Module Issues¶

Module Not Found¶

Module Already Loaded (Different Version)¶

Cmdlets Not Found After Import¶

Wrong .NET Version¶

Connection Issues¶

Cannot Connect to Server¶

Timeout Errors¶

SSL/HTTPS Errors¶

Cmdlet Errors¶

Parameter Validation Errors¶

Object Not Found¶

Already Exists Error¶

Permission Denied¶

Invalid URL Format¶

Performance Issues¶

Slow Cmdlet Execution¶

High Memory Usage¶

Debugging Tips¶

Enable Verbose Output¶

Capture Errors¶

Test REST API Directly¶

Check Cmdlet Parameters¶

Trace HTTP Requests¶

Compare with SharePoint¶

Common Error Messages¶

"Assembly not loaded"¶

"Method not found"¶

"Type not found"¶

Getting Help¶

Built-in Help¶

Log Files¶

Reporting Issues¶

See Also¶