Skip to content

v5.0.0 Migration Guide

Jump to bottom
Bryan Soltis edited this page Nov 4, 2025 · 1 revision

Azure Naming Tool v5.0.0 Migration Guide

Overview

Version 5.0.0 of the Azure Naming Tool introduces significant enhancements including a modern redesigned UI, SQLite database storage option, and Azure resource name validation capabilities. This guide will help you successfully migrate from previous versions to v5.0.0.

⚠️ Important: Always backup your current configuration before upgrading to ensure you can restore your settings if needed.

Migration Steps

Step 1: Backup Your Current Configuration

Before upgrading, it's critical to backup your existing configuration to prevent any data loss.

Option A: Using the Admin Page (Recommended)

  1. Navigate to the Admin page in your current Azure Naming Tool installation
  2. Go to the Configuration tab
  3. Under Backup/Restore Configuration, click Export Configuration (JSON)
  4. Save the downloaded JSON file to a safe location
  5. Note: This backup includes all component configurations but excludes admin settings (passwords, API keys)

Option B: Manual File System Backup

If using the file-based storage (default in v4.x):

  1. Navigate to your installation directory
  2. Copy the entire repository folder to a backup location
  3. Copy the settings folder to preserve admin settings
  4. Store these backups in a safe location outside your installation directory

Backup Checklist:

  • ✅ Configuration JSON exported from Admin page
  • ✅ repository folder backed up (if applicable)
  • ✅ settings folder backed up (if applicable)
  • ✅ Custom logo files backed up (if customized)
  • ✅ Documentation of admin password and API keys

Step 2: Backup Code Modifications/Customizations

If you have made any customizations to the Azure Naming Tool code:

  1. Document all code changes:

    • Note any modified files in the src directory
    • Document custom components or services added
    • Save copies of modified CSS/styling files

  2. Export customizations:

    • Custom logo: Located in wwwroot/images/ (if modified)
    • Custom CSS: Check wwwroot/css/ for any custom files
    • Modified resource types or components
    • Custom home content from Admin page

  3. Create a customization document:

    • List all custom changes made
    • Note file paths and specific modifications
    • Document any custom API integrations or webhooks

Step 3: Review Installation Process for Your Environment

Review the installation documentation for your specific deployment environment to ensure you understand the requirements for v5.0.0:

Supported Environments:

System Requirements:

  • .NET 8.0 Runtime (ASP.NET Core)
  • Minimum 512MB RAM (1GB recommended)
  • Persistent storage for database (file system or SQLite)

New in v5.0.0:

  • Modern UI with improved performance
  • SQLite database option for better scalability
  • Azure validation integration (requires Azure authentication)
  • Enhanced API capabilities

Step 4: Deploy Using Your Desired Installation Process

Choose your deployment method and follow the installation guide:

Azure App Service Deployment

  1. Download the latest v5.0.0 release from GitHub Releases

  2. Extract the files to a local directory

  3. Deploy to Azure App Service using one of these methods:

    • Visual Studio: Right-click project → Publish
    • Azure CLI: az webapp deploy --resource-group <rg-name> --name <app-name> --src-path <zip-file>
    • GitHub Actions: Use provided workflow file
    • Azure Portal: Deploy from zip file

  4. Configure App Settings:

    • Ensure .NET 8 runtime is selected
    • Set ASPNETCORE_ENVIRONMENT if needed
    • Configure any custom environment variables

Docker Deployment

# Pull the latest v5.0.0 image
docker pull ghcr.io/mspnp/azurenamingtool:latest

# Run with persistent storage
docker run -d \
  -p 80:80 \
  -v $(pwd)/repository:/app/repository \
  -v $(pwd)/settings:/app/settings \
  --name azurenamingtool \
  ghcr.io/mspnp/azurenamingtool:latest

Stand-alone Deployment

  1. Ensure .NET 8.0 Runtime is installed
  2. Extract the release files
  3. Run the application: 
    dotnet AzureNamingTool.dll
  4. Access the application at http://localhost:5000

💡 Note: After deployment, the site may need to be restarted for all changes to take effect. You can restart from the Azure Portal (for App Service) or by restarting the container/application.

Step 5: Restore Your Configuration (JSON)

After successfully deploying v5.0.0, restore your configuration:

  1. Access the Admin page:

    • Navigate to your new v5.0.0 installation
    • Log in with the default password (or your existing password if preserved)

  2. Navigate to Configuration tab:

    • Click on Admin in the navigation
    • Select the Configuration tab
    • Scroll to Backup/Restore Configuration

  3. Import your configuration:

    • Under Restore Configuration from JSON, click Choose File
    • Select your previously exported JSON backup file
    • Click Restore Configuration from JSON Backup
    • Confirm the restoration when prompted

  4. Verify the restoration:

    • Navigate to the Configuration page
    • Verify all components are loaded correctly
    • Check Reference page to ensure resource types display properly
    • Test name generation on the Generate page

⚠️ Important: After restoring configuration, restart the application to ensure all settings are properly loaded:

  • Azure App Service: Restart from Azure Portal
  • Docker: docker restart azurenamingtool
  • Stand-alone: Stop and restart the application

Step 6: Upgrading Your Installation to SQLite (Optional)

v5.0.0 introduces SQLite database support for improved performance and reliability. This is optional but recommended for production environments.

⚠️ Warning: Migrating to SQLite is a one-way operation. Ensure you have a complete backup before proceeding.

Prerequisites

  1. Complete Steps 1-5 (Deploy v5.0.0 and restore configuration)
  2. Create a backup of your current configuration (even if already on v5.0.0)
  3. Ensure the application is running on file-based storage (default)

Migration Process

  1. Access Admin page:

    • Navigate to Admin → Configuration tab
    • Scroll to Storage Migration section

  2. Review migration information:

    • Current storage provider is shown (should be "FileSystem")
    • Read the migration warnings and requirements carefully

  3. Create pre-migration backup:

    • Click Create Pre-Migration Backup
    • Download and save the backup file
    • Verify the backup file is complete

  4. Initiate migration:

    • Click Migrate to SQLite
    • You will see two confirmation prompts:
      • First confirmation: Acknowledge the migration process
      • Second confirmation: Type CONFIRM to proceed
    • Click Confirm on both prompts

  5. Monitor migration progress:

    • The migration process will:
      • Export current configuration to JSON
      • Initialize SQLite database
      • Import all data to SQLite
      • Update storage provider setting
    • This may take several minutes depending on data size

  6. Restart the application:

    • Critical: The application MUST be restarted after migration
    • Azure App Service: Go to Azure Portal → Your App Service → Click Restart
    • Docker: Run docker restart azurenamingtool
    • Stand-alone: Stop the application and restart it

  7. Verify migration:

    • After restart, log back into the Admin page
    • Check Configuration tab → Storage Migration section
    • Verify "Current Storage Provider" shows SQLite
    • Navigate to Configuration page and verify all components loaded
    • Test name generation to ensure functionality

Post-Migration Cleanup (Optional)

After successful migration and verification:

  1. The original file-based storage remains in the repository folder
  2. You can archive this folder for backup purposes
  3. Do not delete until you've verified SQLite is working correctly for at least a few days

Rollback Procedure

If you need to rollback from SQLite to file-based storage:

  1. Stop the application
  2. Restore your pre-migration backup files to the repository folder
  3. Delete or rename the azurenamingtool.db file
  4. Update appsettings.json to set storage provider back to "FileSystem"
  5. Restart the application

What's New in v5.0.0

Modern UI Redesign

  • New Dashboard: Two-column hero layout with logo and custom content
  • Configuration Overview: Stats grid showing all enabled component counts
  • Improved Navigation: Streamlined modern tab interface
  • Better Mobile Support: Responsive design improvements

SQLite Database Support

  • Enhanced Performance: Faster data access and queries
  • Better Scalability: Handles larger configurations more efficiently
  • Improved Reliability: Transactional support and data integrity
  • Easy Migration: Built-in migration tool from file-based storage

Azure Resource Name Validation

  • Real-time Validation: Check if resource names already exist in Azure
  • Conflict Detection: Prevent naming conflicts before deployment
  • Multi-subscription Support: Validate across multiple Azure subscriptions
  • Configurable: Enable/disable per your requirements

Enhanced API Capabilities

  • Bulk Operations: Process multiple naming requests in a single call
  • Improved Error Handling: Better error messages and validation
  • Extended Filtering: More options for querying configurations
  • Performance Improvements: Faster response times

Other Improvements

  • Fixed Component Name Matching: Resolved issues with ResourceOrg, ResourceProjAppSvc, and ResourceFunction
  • Custom Home Content: Now loads correctly in Admin page editor
  • Improved Logging: Enhanced admin logs for troubleshooting
  • Better Error Messages: More helpful error descriptions

Troubleshooting

Common Issues

Configuration Not Restored

Symptom: After importing JSON, components don't appear

Solution:

  1. Verify the JSON file is valid and not corrupted
  2. Check Admin Logs for any error messages
  3. Restart the application after restoring
  4. Try importing individual components using the Component Import feature

SQLite Migration Failed

Symptom: Migration process stops or shows errors

Solution:

  1. Ensure you have a valid backup before retrying
  2. Check available disk space (SQLite needs space to create database)
  3. Review Admin Logs for specific error messages
  4. If migration fails, the application remains on file-based storage
  5. Contact support with error logs if issue persists

Application Won't Start After Migration

Symptom: Application fails to start after SQLite migration

Solution:

  1. Check application logs for error details
  2. Verify azurenamingtool.db file was created
  3. Ensure file permissions allow read/write to database
  4. Try rollback procedure (see Step 6)
  5. Restore from pre-migration backup

Azure Validation Not Working

Symptom: Azure validation features are not available

Solution:

  1. Ensure proper Azure authentication is configured
  2. Check that Managed Identity or Service Principal has necessary permissions
  3. Verify network connectivity to Azure Resource Manager
  4. Review Admin → Azure Validation settings
  5. Check Admin Logs for authentication errors

Post-Migration Checklist

After completing the migration, verify these items:

  • ✅ All resource components appear in Configuration page
  • ✅ Custom components (if any) are present
  • ✅ Resource types display correctly on Reference page
  • ✅ Name generation works on Generate page
  • ✅ Admin settings preserved (verify password, API keys)
  • ✅ Custom logo appears (if customized)
  • ✅ Custom home content displays on dashboard (if configured)
  • ✅ Generated Names Log contains previous entries (if applicable)
  • ✅ API endpoints respond correctly (test with Swagger)
  • ✅ Azure validation configured and working (if enabled)
  • ✅ Application performance is acceptable

Getting Help

If you encounter issues during migration:

  1. Check Admin Logs: Admin page → View Admin Log
  2. Review Documentation: Azure Naming Tool Wiki
  3. Search Issues: GitHub Issues
  4. Report Bugs: Create New Issue
  5. Community Support: Join discussions on GitHub

Additional Resources

Last Updated: November 4, 2025
Version: 5.0.0

Clone this wiki locally