@khester/create-dynamics-app 1.0.8 → 1.1.0

package/templates/dynamics-365-starter/deployment/QUICKSTART-WINDOWS.md

@@ -0,0 +1,372 @@
+# Quick Start Guide - Windows Developers
+
+🖥️ **Platform-specific setup for Windows developers using PowerShell**
+
+## Prerequisites
+
+### Required Software
+
+- **Windows 10/11** or **Windows Server 2019+**
+- **PowerShell 5.1** or **PowerShell 7+** (recommended)
+- **Node.js 18+** and **npm**
+- **Git for Windows**
+
+### PowerShell Modules
+
+```powershell
+# Install required modules (run as Administrator)
+Install-Module -Name Microsoft.PowerApps.Administration.PowerShell -Force
+Install-Module -Name Microsoft.PowerApps.PowerShell -AllowClobber -Force
+
+# Verify installation
+Get-Module -Name Microsoft.PowerApps* -ListAvailable
+```
+
+### Development Tools
+
+```powershell
+# Install Node.js (if not already installed)
+choco install nodejs
+
+# Install Git (if not already installed)
+choco install git
+
+# Verify installations
+node --version
+npm --version
+git --version
+```
+
+## Project Setup
+
+### 1. Clone and Setup Project
+
+```powershell
+# Clone the project
+git clone https://github.com/your-org/your-dynamics-project.git
+cd your-dynamics-project
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build:prod
+```
+
+### 2. Configure Environment
+
+```powershell
+# Copy environment template
+Copy-Item "config\environments\template.json" "config\environments\dev.json"
+
+# Edit configuration (use your preferred editor)
+notepad "config\environments\dev.json"
+```
+
+### 3. Validate Setup
+
+```powershell
+# Run validation script
+.\deployment\scripts\validate-setup.ps1
+
+# Test connection to D365
+.\deployment\scripts\test-connection.ps1 -Environment dev
+```
+
+## Daily Deployment Workflow
+
+### Development Deployment
+
+```powershell
+# Quick development deployment
+.\deployment\scripts\deploy.ps1 -Environment dev
+
+# With verbose output
+.\deployment\scripts\deploy.ps1 -Environment dev -Verbose
+
+# Dry run (test without changes)
+.\deployment\scripts\deploy.ps1 -Environment dev -DryRun
+```
+
+### Production Deployment
+
+```powershell
+# Production deployment with backup
+.\deployment\scripts\deploy.ps1 -Environment prod
+
+# Force deployment (skip some validations)
+.\deployment\scripts\deploy.ps1 -Environment prod -Force
+
+# Skip backup (faster deployment)
+.\deployment\scripts\deploy.ps1 -Environment prod -SkipBackup
+```
+
+### Entity Generation
+
+```powershell
+# Generate new entity
+npm run generate:entity -- --entity "salesorder" --display-name "Sales Order"
+
+# Generate multiple entities
+npm run generate:entity -- --entity "product" --display-name "Product"
+npm run generate:entity -- --entity "pricing" --display-name "Pricing Rule"
+```
+
+## Common Commands Reference
+
+### Build Commands
+
+```powershell
+npm run build:dev       # Development build (unminified)
+npm run build:prod      # Production build (optimized)
+npm run build:d365      # Dynamics 365 optimized build
+npm run clean           # Clean build artifacts
+```
+
+### Quality Checks
+
+```powershell
+npm run lint            # Check code style
+npm run lint:fix        # Fix code style issues
+npm run typecheck       # TypeScript validation
+npm run quality         # Run all quality checks
+npm run test            # Run unit tests
+```
+
+### Metadata Operations
+
+```powershell
+npm run metadata:pull -- --environment dev --entities "account,contact"
+npm run metadata:generate
+npm run metadata:validate -- --environment dev
+npm run metadata:sync -- --environment dev --all
+```
+
+### Deployment Operations
+
+```powershell
+# Deploy to specific environment
+.\deployment\scripts\deploy.ps1 -Environment <env>
+
+# Rollback deployment
+.\deployment\scripts\rollback.ps1 -Environment <env> -BackupFile "backup-file.zip"
+
+# Health check
+.\deployment\scripts\health-check.ps1 -Environment <env>
+
+# Monitor deployment
+.\deployment\scripts\monitor.ps1 -Environment <env>
+```
+
+## PowerShell Configuration
+
+### Execution Policy
+
+```powershell
+# Check current execution policy
+Get-ExecutionPolicy
+
+# Set execution policy (if needed)
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+### PowerShell Profile Setup
+
+```powershell
+# Create profile if it doesn't exist
+if (!(Test-Path $PROFILE)) {
+    New-Item -Type File -Path $PROFILE -Force
+}
+
+# Add helpful aliases
+Add-Content $PROFILE @"
+# Dynamics 365 Development Aliases
+Set-Alias d365deploy '.\deployment\scripts\deploy.ps1'
+Set-Alias d365health '.\deployment\scripts\health-check.ps1'
+Set-Alias d365rollback '.\deployment\scripts\rollback.ps1'
+
+# Quick navigation
+function Set-D365Project { Set-Location 'C:\Code\YourProject' }
+Set-Alias d365cd Set-D365Project
+"@
+
+# Reload profile
+. $PROFILE
+```
+
+## Windows-Specific Tips
+
+### File Path Handling
+
+```powershell
+# Use backslashes for Windows paths
+.\deployment\scripts\deploy.ps1
+
+# Or use forward slashes (PowerShell accepts both)
+./deployment/scripts/deploy.ps1
+```
+
+### Environment Variables
+
+```powershell
+# Set environment variables for session
+$env:D365_ENVIRONMENT = "dev"
+$env:D365_CLIENT_ID = "your-client-id"
+
+# Set permanently (requires restart)
+[Environment]::SetEnvironmentVariable("D365_ENVIRONMENT", "dev", "User")
+```
+
+### Windows Terminal Configuration
+
+```json
+// Add to Windows Terminal settings.json
+{
+  "name": "D365 PowerShell",
+  "commandline": "pwsh.exe",
+  "startingDirectory": "C:\\Code\\YourProject",
+  "icon": "ms-appx:///ProfileIcons/{574e775e-4f2a-5b96-ac1e-a2962a402336}.png"
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### PowerShell Modules Not Loading
+
+```powershell
+# Check module path
+$env:PSModulePath -split ';'
+
+# Manually import modules
+Import-Module Microsoft.PowerApps.Administration.PowerShell -Force
+Import-Module Microsoft.PowerApps.PowerShell -Force
+```
+
+#### Authentication Issues
+
+```powershell
+# Clear cached credentials
+Clear-AzContext -Force
+
+# Test authentication
+.\deployment\scripts\test-auth.ps1 -Environment dev
+```
+
+#### Build Failures
+
+```powershell
+# Clear npm cache
+npm cache clean --force
+
+# Remove node_modules and reinstall
+Remove-Item -Recurse -Force node_modules
+npm install
+```
+
+#### File Permission Issues
+
+```powershell
+# Run as Administrator if needed
+Start-Process powershell -Verb runAs
+
+# Check file permissions
+Get-Acl .\deployment\scripts\deploy.ps1
+```
+
+### Performance Optimization
+
+```powershell
+# Increase PowerShell memory limit
+$MaximumVariableCount = 32768
+$MaximumFunctionCount = 8192
+
+# Enable PowerShell parallel execution
+.\deployment\scripts\deploy.ps1 -Environment dev -Parallel
+```
+
+## VS Code Integration
+
+### Recommended Extensions
+
+- **PowerShell** - Microsoft PowerShell support
+- **TypeScript** - Enhanced TypeScript support
+- **Dynamics 365** - D365 development tools
+- **REST Client** - Test D365 APIs
+
+### Launch Configuration
+
+```json
+// .vscode/launch.json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Deploy to Dev",
+      "type": "PowerShell",
+      "request": "launch",
+      "script": "${workspaceFolder}/deployment/scripts/deploy.ps1",
+      "args": ["-Environment", "dev", "-Verbose"],
+      "cwd": "${workspaceFolder}"
+    }
+  ]
+}
+```
+
+### Tasks Configuration
+
+```json
+// .vscode/tasks.json
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Deploy to Dev",
+      "type": "shell",
+      "command": ".\\deployment\\scripts\\deploy.ps1",
+      "args": ["-Environment", "dev"],
+      "group": "build",
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "focus": false,
+        "panel": "shared"
+      }
+    }
+  ]
+}
+```
+
+## Team Collaboration
+
+### Shared Scripts Location
+
+All PowerShell scripts are in `deployment/scripts/` and work identically across all Windows
+machines.
+
+### Configuration Sharing
+
+- Environment configs in `config/environments/` are shared across team
+- Personal settings go in `.env.local` (not committed to git)
+
+### Log Files
+
+- Deployment logs: `deployment/logs/`
+- Build logs: `build/logs/`
+- Share log files when troubleshooting with team
+
+## Next Steps
+
+1. ✅ **Complete environment setup** using this guide
+2. ✅ **Run first deployment** to development environment
+3. ✅ **Generate your first entity** using the entity generator
+4. ✅ **Deploy to test environment** when ready
+5. ✅ **Set up CI/CD pipeline** for automated deployments
+
+For Mac team members, refer to `QUICKSTART-MAC.md` for their platform-specific setup.
+
+---
+
+💡 **Tip**: Bookmark this guide and refer to the **Common Commands Reference** section for daily
+workflows!