Major update: Enhanced documentation, comprehensive examples, and fixed remaining issues

- Updated README.md with modern feature descriptions and comprehensive overview - Enhanced docs/USAGE.md with advanced object listing, directory management, and chunked operations - Created examples/ directory with 6 comprehensive example scripts: * 01-Basic-Operations.ps1 - Fundamental operations for beginners * 02-Advanced-Object-Listing.ps1 - Filtering, sorting, and pagination * 03-Directory-Management.ps1 - Nested directory structures and organization * 04-Chunked-Operations.ps1 - Large file handling with performance optimization * 05-Bulk-Operations.ps1 - Batch processing and automation workflows * 06-Enterprise-Automation.ps1 - Enterprise monitoring, reporting, and compliance - Added comprehensive examples/README.md with usage patterns and best practices - Fixed directory creation warnings (now clean verbose logging) - Implemented missing Get-MinIOObject cmdlet with full filtering/sorting capabilities - Added timing and performance metrics to all operations - Enhanced chunked operations with multi-layer progress tracking - Improved error handling and resource cleanup - Removed temporary test files and cleaned up repository structure - All examples use proper PowerShell output (no Write-Host usage) - Professional logging with timestamps and structured output
2026-07-26 06:48:13 +00:00 · 2025-07-10 22:33:03 -04:00
parent 2974ead76e
commit d887fd7f46
66 changed files with 2475 additions and 3428 deletions
@@ -1,16 +1,19 @@
 # PSMinIO Usage Guide

-This guide provides comprehensive examples and usage patterns for the PSMinIO PowerShell module.
+This comprehensive guide covers all aspects of using the PSMinIO PowerShell module for MinIO object storage operations.

 ## Table of Contents

 - [Installation](#installation)
- [Configuration](#configuration)
+- [Connection Management](#connection-management)
 - [Bucket Operations](#bucket-operations)
 - [Object Operations](#object-operations)
+- [Advanced Object Listing](#advanced-object-listing)
+- [Directory and Folder Management](#directory-and-folder-management)
+- [Chunked Operations](#chunked-operations)
 - [Security and Policies](#security-and-policies)
- [Statistics and Monitoring](#statistics-and-monitoring)
- [Advanced Usage](#advanced-usage)
+- [Performance and Monitoring](#performance-and-monitoring)
+- [Advanced Usage Patterns](#advanced-usage-patterns)
 - [Troubleshooting](#troubleshooting)

 ## Installation
@@ -23,29 +26,39 @@ This guide provides comprehensive examples and usage patterns for the PSMinIO Po
 ### Import the Module

 ```powershell
-# Import the module
-Import-Module .\PSMinIO.psd1
+# Import the module from the Module directory
+Import-Module .\Module\PSMinIO\PSMinIO.psd1

-# Verify the module is loaded
+# Verify the module is loaded and check available cmdlets
 Get-Module PSMinIO
+Get-Command -Module PSMinIO
 ```

-## Configuration
+## Connection Management

-### Basic Configuration
+### Establishing Connections
+
+PSMinIO uses a modern connection-based approach with the `Connect-MinIO` cmdlet:

 ```powershell
-# Set up MinIO connection
-Set-MinIOConfig -Endpoint "minio.example.com:9000" `
-                -AccessKey "your-access-key" `
-                -SecretKey "your-secret-key" `
-                -UseSSL
+# Connect to MinIO server with SSL
+$connection = Connect-MinIO -Endpoint "https://minio.example.com" -AccessKey "your-access-key" -SecretKey "your-secret-key"

-# For local development (no SSL)
-Set-MinIOConfig -Endpoint "localhost:9000" `
-                -AccessKey "minioadmin" `
-                -SecretKey "minioadmin" `
-                -NoSSL
+# Connect to local MinIO (no SSL)
+$connection = Connect-MinIO -Endpoint "http://localhost:9000" -AccessKey "minioadmin" -SecretKey "minioadmin"
+
+# Connect with custom port
+$connection = Connect-MinIO -Endpoint "https://minio.example.com:9443" -AccessKey "your-access-key" -SecretKey "your-secret-key"
+```
+
+### Connection Options
+
+```powershell
+# Skip SSL certificate validation (for self-signed certificates)
+$connection = Connect-MinIO -Endpoint "https://minio.internal.com" -AccessKey "key" -SecretKey "secret" -SkipCertificateValidation
+
+# Connection with region specification
+$connection = Connect-MinIO -Endpoint "https://s3.amazonaws.com" -AccessKey "key" -SecretKey "secret" -Region "us-west-2"
 ```

 ### Advanced Configuration
@@ -220,6 +233,158 @@ Remove-MinIOObject -BucketName "cache" `
                   -Force
 ```

+## Advanced Object Listing
+
+The `Get-MinIOObject` cmdlet provides powerful filtering, sorting, and pagination capabilities:
+
+### Basic Object Listing
+
+```powershell
+# List all objects in a bucket
+Get-MinIOObject -BucketName "my-bucket"
+
+# List objects with a specific prefix
+Get-MinIOObject -BucketName "my-bucket" -Prefix "documents/"
+
+# List objects recursively (default behavior)
+Get-MinIOObject -BucketName "my-bucket" -Prefix "logs/" -Recursive
+
+# List objects non-recursively (current level only)
+Get-MinIOObject -BucketName "my-bucket" -Prefix "logs/" -Recursive:$false
+```
+
+### Advanced Filtering
+
+```powershell
+# Get a specific object by exact name
+Get-MinIOObject -BucketName "my-bucket" -ObjectName "documents/report.pdf"
+
+# List only files (exclude directory markers)
+Get-MinIOObject -BucketName "my-bucket" -ObjectsOnly
+
+# Include object versions (for versioned buckets)
+Get-MinIOObject -BucketName "my-bucket" -IncludeVersions
+
+# Limit the number of results
+Get-MinIOObject -BucketName "my-bucket" -MaxObjects 50
+```
+
+### Sorting Options
+
+```powershell
+# Sort by name (ascending - default)
+Get-MinIOObject -BucketName "my-bucket" -SortBy "Name"
+
+# Sort by name (descending)
+Get-MinIOObject -BucketName "my-bucket" -SortBy "Name" -Descending
+
+# Sort by file size (largest first)
+Get-MinIOObject -BucketName "my-bucket" -SortBy "Size" -Descending
+
+# Sort by last modified date (newest first)
+Get-MinIOObject -BucketName "my-bucket" -SortBy "LastModified" -Descending
+
+# Sort by ETag
+Get-MinIOObject -BucketName "my-bucket" -SortBy "ETag"
+```
+
+### Complex Queries
+
+```powershell
+# Find large files in a specific directory
+Get-MinIOObject -BucketName "media" -Prefix "videos/" -SortBy "Size" -Descending -MaxObjects 10
+
+# Get recent files only
+$recentFiles = Get-MinIOObject -BucketName "logs" -SortBy "LastModified" -Descending -MaxObjects 20
+
+# Find files by pattern using PowerShell filtering
+Get-MinIOObject -BucketName "documents" | Where-Object { $_.Name -like "*.pdf" -and $_.Size -gt 1MB }
+
+# Get directory structure overview
+Get-MinIOObject -BucketName "my-bucket" | Group-Object { ($_.Name -split '/')[0] } | Format-Table Name, Count
+```
+
+## Directory and Folder Management
+
+### Creating Directory Structures
+
+```powershell
+# Create explicit folder structures
+New-MinIOFolder -BucketName "my-bucket" -FolderName "projects/web-app/src"
+New-MinIOFolder -BucketName "my-bucket" -FolderName "projects/web-app/docs"
+
+# Create multiple folder levels at once
+New-MinIOFolder -BucketName "my-bucket" -FolderName "company/departments/engineering/teams/backend"
+```
+
+### Automatic Directory Creation
+
+```powershell
+# Upload files with automatic directory creation using BucketDirectory
+New-MinIOObject -BucketName "my-bucket" -Files "report.pdf" -BucketDirectory "documents/2025/january"
+
+# Create nested directory structures automatically
+New-MinIOObject -BucketName "my-bucket" -Files "config.json" -BucketDirectory "projects/web-app/config/production"
+```
+
+### Directory-Based Operations
+
+```powershell
+# List all directories (folder markers)
+Get-MinIOObject -BucketName "my-bucket" | Where-Object { $_.IsDirectory }
+
+# List files in a specific directory
+Get-MinIOObject -BucketName "my-bucket" -Prefix "documents/2025/" -ObjectsOnly
+
+# Organize files by date-based directories
+$today = Get-Date -Format "yyyy/MM/dd"
+New-MinIOObject -BucketName "logs" -Files "app.log" -BucketDirectory "daily-logs/$today"
+```
+
+## Chunked Operations
+
+### Chunked Uploads
+
+```powershell
+# Upload large files with chunked transfer
+New-MinIOObjectChunked -BucketName "media" -Files "large-video.mp4" -ChunkSize 10MB
+
+# Upload with custom chunk size and directory
+New-MinIOObjectChunked -BucketName "backups" -Files "database-backup.sql" -ChunkSize 5MB -BucketDirectory "daily-backups/$(Get-Date -Format 'yyyy-MM-dd')"
+
+# Upload multiple large files
+New-MinIOObjectChunked -BucketName "media" -Files @("video1.mp4", "video2.mp4") -ChunkSize 10MB -BucketDirectory "videos/uploads"
+```
+
+### Chunked Downloads
+
+```powershell
+# Download large files with chunked transfer
+Get-MinIOObjectContentChunked -BucketName "media" -ObjectName "large-video.mp4" -FilePath "C:\Downloads\video.mp4" -ChunkSize 10MB
+
+# Download with progress tracking
+Get-MinIOObjectContentChunked -BucketName "backups" -ObjectName "large-backup.zip" -FilePath "C:\Restore\backup.zip" -ChunkSize 5MB
+```
+
+### Chunk Size Guidelines
+
+```powershell
+# Recommended chunk sizes based on file size:
+# Files < 10MB: Use regular upload/download
+# Files 10MB - 100MB: Use 1-5MB chunks
+# Files 100MB - 1GB: Use 5-10MB chunks
+# Files > 1GB: Use 10-50MB chunks
+
+# Example with optimal chunk size selection
+$fileSize = (Get-Item "large-file.zip").Length
+$chunkSize = if ($fileSize -lt 10MB) { 1MB }
+             elseif ($fileSize -lt 100MB) { 5MB }
+             elseif ($fileSize -lt 1GB) { 10MB }
+             else { 25MB }
+
+New-MinIOObjectChunked -BucketName "uploads" -Files "large-file.zip" -ChunkSize $chunkSize
+```
+
 ## Security and Policies

 ### Get Bucket Policies