BoxPacker3D/VISUAL_STUDIO_INSTALLER_GUIDE.md

# Visual Studio Installer Projects - Návod

## 1. Inštalácia rozšírenia pre VS 2017

### Krok 1: Otvorte VS 2017
1. Spustite Visual Studio 2017
2. Prejdite na **Tools → Extensions and Updates...**
3. V ľavom paneli vyberte **Online**
4. Do vyhľadávacieho poľa napíšte: `Microsoft Visual Studio Installer Projects`
5. Nájdite oficiálne rozšírenie od Microsoft
6. Kliknite **Download**
7. Po stiahnutí **zatvorte VS 2017** - inštalácia sa spustí automaticky
8. Postupujte podľa VSIX Installer krokov
9. Reštartujte VS 2017

**Alternatíva - Priame stiahnutie:**
- Navštívte: https://marketplace.visualstudio.com/items?itemName=VisualStudioClient.MicrosoftVisualStudio2017InstallerProjects
- Stiahnite `.vsix` súbor a spustite ho

---

## 2. Vytvorenie Setup projektu

### Krok 1: Pridajte Setup projekt do solution
1. Otvorte `BoxPacker3D.sln` vo VS 2017
2. V **Solution Explorer** kliknite pravým na solution (nie projekt)
3. **Add → New Project...**
4. V ľavom paneli: **Other Project Types → Visual Studio Installer**
5. Vyberte šablónu: **Setup Project**
6. Meno: `BoxPacker3D.Setup`
7. Kliknite **OK**

### Krok 2: Nastavte základné vlastnosti
1. V **Solution Explorer** kliknite pravým na `BoxPacker3D.Setup`
2. Vyberte **Properties**
3. Nastavte:
   - **Author**: Vaše meno alebo firma
   - **Description**: `3D Box Packer - Aplikácia pre 3D balenie kusov`
   - **Manufacturer**: Vaše meno/firma
   - **ManufacturerUrl**: Vaša web stránka (voliteľné)
   - **ProductName**: `3D Box Packer`
   - **Title**: `3D Box Packer Installer`
   - **Version**: `1.0.0`

---

## 3. Pridanie súborov do inštalátora

### Metóda A: Project Output (Odporúčané)

1. V **Solution Explorer** otvorte `BoxPacker3D.Setup`
2. Vidíte **File System Editor** s tromi priečinkami:
   - Application Folder
   - User's Desktop
   - User's Programs Menu

3. **Kliknite pravým na "Application Folder"** → **Add → Project Output...**
4. V dialógu:
   - **Project**: Vyberte `BoxPacker3D`
   - **Configuration**: Vyberte `Release .NET 9.0`
   - Zaškrtnite: **Primary output** (obsahuje EXE a všetky DLLs)
   - Kliknite **OK**

5. **Pridajte konfiguračné súbory**:
   - Kliknite pravým na **Application Folder** → **Add → File...**
   - Navigujte do priečinka projektu
   - Vyberte: `appsettings.json` a `items.db`
   - Kliknite **OK**

### Metóda B: Publish Output (Alternatíva)

Ak metóda A nefunguje správne:

1. Najprv publikujte projekt:
   ```
   dotnet publish -c Release -r win-x64 --self-contained false
   ```

2. V Setup projekte:
   - Kliknite pravým na **Application Folder** → **Add → File...**
   - Navigujte do: `bin\Release\net9.0-windows\win-x64\publish\`
   - Vyberte **všetky súbory** (`.exe`, `.dll`, `.json`, `.db`)
   - Kliknite **OK**

---

## 4. Vytvorenie Desktop ikony (voliteľné)

1. V **File System Editor** kliknite pravým na **User's Desktop**
2. **Add → File...**
3. V dialógu vyberte **Application Folder** (nie súbor!)
4. V zozname nájdite **Primary output from BoxPacker3D**
5. Kliknite **OK**
6. Ikona sa vytvorí automaticky

Alebo:
1. Kliknite pravým na **User's Desktop** → **Create New Shortcut**
2. V dialógu vyberte **Application Folder**
3. Vyberte **Primary output from BoxPacker3D**
4. Kliknite **OK**
5. Premenujte shortcut na "3D Box Packer"

---

## 5. Start Menu položka

1. V **File System Editor** kliknite pravým na **User's Programs Menu**
2. **Add → Folder**
3. Premenujte priečinok na `3D Box Packer`
4. Kliknite pravým na tento priečinok → **Create New Shortcut**
5. V dialógu vyberte **Application Folder**
6. Vyberte **Primary output from BoxPacker3D**
7. Kliknite **OK**
8. Premenujte shortcut na "3D Box Packer"

---

## 6. Nastavenie .NET 9 prerequisite

### Varient 1: Launch Conditions (Upozornenie)

1. V **Solution Explorer** kliknite pravým na `BoxPacker3D.Setup`
2. **View → Launch Conditions**
3. Kliknite pravým na **Requirements on Target Machine** → **Add Launch Condition**
4. Vlastnosti:
   - **Condition**: `NETFRAMEWORK90FULL="#1"`
   - **Message**: `Táto aplikácia vyžaduje .NET 9. Stiahnite z https://dotnet.microsoft.com/download/dotnet/9.0`

### Variant 2: Bootstrapper (Automatická inštalácia)

1. Kliknite pravým na `BoxPacker3D.Setup` → **Properties**
2. Nájdite sekciu **Prerequisites...**
3. V dialógu:
   - Zaškrtnite **Create setup program to install prerequisite components**
   - V zozname hľadajte `.NET Desktop Runtime 9.0` (ak nie je, musíte použiť custom bootstrapper)
   - Vyberte umiestnenie: **Download prerequisites from the component vendor's web site**
4. Kliknite **OK**

**Poznámka:** Ak .NET 9 nie je v zozname prerequisite (starší VS 2017), použite Launch Condition a užívateľ si musí nainštalovať .NET 9 manuálne.

---

## 7. Build inštalátora

### Jednoduchý build:

1. V **Solution Explorer** kliknite pravým na `BoxPacker3D.Setup`
2. Vyberte **Build**
3. Počkajte na dokončenie
4. MSI súbor nájdete v: `BoxPacker3D.Setup\Release\BoxPacker3D.Setup.msi`

### Batch script pre automatizáciu:

Vytvorte `build-installer-vstudio.bat`:

```batch
@echo off
echo ================================================
echo Building BoxPacker3D with VS Installer Projects
echo ================================================

echo.
echo [1/3] Building Release configuration...
msbuild BoxPacker3D.sln /p:Configuration=Release /p:Platform="Any CPU" /v:minimal

if errorlevel 1 (
    echo ERROR: Project build failed!
    pause
    exit /b 1
)

echo.
echo [2/3] Building Setup project...
msbuild BoxPacker3D.Setup\BoxPacker3D.Setup.vdproj /p:Configuration=Release /v:minimal

if errorlevel 1 (
    echo ERROR: Setup build failed!
    pause
    exit /b 1
)

echo.
echo [3/3] Installer created successfully!
echo Location: BoxPacker3D.Setup\Release\BoxPacker3D.Setup.msi
echo.

explorer /select,"BoxPacker3D.Setup\Release\BoxPacker3D.Setup.msi"
pause
```

---

## 8. Vlastnosti MSI inštalátora

### Upgrade Behavior (Automatický upgrade)

1. V **Solution Explorer** kliknite pravým na `BoxPacker3D.Setup`
2. **Properties**
3. Nastavte:
   - **RemovePreviousVersions**: `True` (umožní upgrade cez nainštalovanie novej verzie)
   - **DetectNewerInstalledVersion**: `True` (zabráni inštalácii staršej verzie)

### Product Code a Upgrade Code

- **ProductCode**: Automaticky sa vygeneruje nový pri každom zmene verzie
- **UpgradeCode**: **NIKDY nemeňte!** Toto ID identifikuje vašu aplikáciu naprieč verziami

---

## 9. Pokročilé nastavenia

### Custom Actions (Voliteľné)

Ak potrebujete spustiť akcie počas inštalácie:

1. Kliknite pravým na `BoxPacker3D.Setup` → **View → Custom Actions**
2. Môžete pridať:
   - **Install**: Spustí sa pri inštalácii
   - **Commit**: Po úspešnej inštalácii
   - **Rollback**: Ak inštalácia zlyhá
   - **Uninstall**: Pri odinštalácii

### Registry Keys (Voliteľné)

1. **View → Registry**
2. Navigujte do `HKEY_LOCAL_MACHINE\Software`
3. Kliknite pravým → **New → Key**
4. Vytvorte štruktúru napr. `YourCompany\BoxPacker3D`
5. Pridajte hodnoty (napr. install path)

### File Associations (Voliteľné)

1. **View → File Types**
2. Pridajte vlastné prípony (.box, .pack, atď.)
3. Asociujte s vašou aplikáciou

---

## 10. Testovanie

### Pred vydaním:

1. **Nainštalujte MSI** na čistom PC alebo VM
2. Overte že:
   - ✅ Aplikácia sa spustí
   - ✅ Všetky súbory sú prítomné
   - ✅ items.db sa vytvorí/skopíruje
   - ✅ appsettings.json funguje
   - ✅ Desktop ikona funguje (ak je)
   - ✅ Start Menu položka funguje
   - ✅ Uninstaller funguje správne

3. **Test upgrade:**
   - Zmeňte verziu v Setup properties (napr. 1.0.0 → 1.0.1)
   - Rebuild
   - Nainštalujte cez starú verziu
   - Overte že upgrade prebehol bez chýb

---

## 11. Distribúcia

MSI súbor je pripravený na distribúciu:
- Môžete ho nahrať na web
- Poslať emailom
- Distribuovať na USB
- Nie je potrebný žiadny iný súbor

**Veľkosť inštalátora:**
- Framework-dependent (vyžaduje .NET 9): ~5-10 MB
- Self-contained (zahrnutý .NET runtime): ~60-80 MB

---

## 12. Riešenie problémov

### "The project could not be opened"
- **Príčina:** Rozšírenie nie je nainštalované
- **Riešenie:** Nainštalujte "Microsoft Visual Studio Installer Projects"

### "Unable to update dependencies"
- **Príčina:** Konflikt verzií
- **Riešenie:** Použite **Project Output** namiesto manuálneho pridávania súborov

### MSI zlyhá pri inštalácii
- Skontrolujte Windows Event Log (Application)
- Zapnite MSI logging: `msiexec /i BoxPacker3D.Setup.msi /l*v install.log`

### items.db sa neprenesie
- V Properties súboru `items.db` overte:
  - **Build Action**: None alebo Content
  - **Copy to Output Directory**: Copy if newer
- Pridajte manuálne do Application Folder v Setup projekte

---

## Porovnanie: VS Installer vs Inno Setup

| Feature | VS Installer Projects | Inno Setup |
|---------|----------------------|------------|
| **Výstup** | MSI | EXE |
| **GUI** | ✅ Visual Studio | ❌ Text editor |
| **Verzovanie** | ⚠️ Binárny .vdproj | ✅ Text .iss |
| **Cena** | ✅ Zadarmo | ✅ Zadarmo |
| **Jednoduchosť** | ✅ Drag & drop | ⚠️ Scripting |
| **Flexibilita** | ⚠️ Obmedzená | ✅ Vysoká |
| **Windows štandard** | ✅ MSI natívny | ⚠️ EXE custom |
| **CI/CD** | ⚠️ Potrebuje VS | ✅ Command-line |

---

## Ďalšie kroky

1. Nainštalujte rozšírenie
2. Vytvorte Setup projekt
3. Pridajte súbory pomocou Project Output
4. Nastavte vlastnosti
5. Build a test
6. Distribuujte MSI

**Tip:** Ak plánujete často updatovať, zachovajte `UpgradeCode` konštantný a len zvyšujte verziu!