Skip to content

07 Migration Guide

Jump to bottom
David Sheiles edited this page Nov 27, 2025 · 2 revisions

Migration Guide: V2.x to V3.0

This guide helps developers upgrade from Meta Momentum V2.x to V3.0 (Umbraco 14+).

Overview

V3.0 introduces breaking changes:

  • Configuration moved from appsettings.json to Data Type settings
  • Removed services.AddMetaMomentum() from Startup
  • Replaced HTML Partial with Tag Helpers
  • Removed FacebookAppId (no longer used by Facebook)

Prerequisites

  • Umbraco 14.0 or higher
  • .NET 8 or higher
  • Meta Momentum V2.x currently installed

Migration Steps

Step 1: Update NuGet Package

Update the Meta Momentum package to V3.x: Update-Package MetaMomentum

Step 2: Migrate Configuration

Old Configuration (V2.x)

appsettings.json:

{ "MetaMomentum": { 
    "SiteName": "My Company", 
    "TwitterName": "@mycompany", 
    "FacebookId": "123456789" // Removed in V3 
    } 
}

Startup.cs or Program.cs:

public void ConfigureServices(IServiceCollection services) { 
    services.AddMetaMomentum(); // Remove in V3 
}

New Configuration (V3.0)

  1. Open the Umbraco backoffice

  2. Go to Settings → Data Types

  3. Open your Meta Momentum Data Type

  4. Scroll to Advanced Settings

  5. Enter values:

    • OG Site Name: Copy from old SiteName setting
    • Twitter Name: Copy from old TwitterName setting
    • FacebookId: Remove (no longer used by Facebook)

  6. Remove the MetaMomentum section from appsettings.json

  7. Remove services.AddMetaMomentum() from Startup.cs or Program.cs

Step 3: Update View Implementation

Old Implementation (V2.x)

@Html.Partial("MetaMomentum/RenderMetaTags", Model.Value("metaMomentum"))

New Implementation (V3.0)

Add to _ViewImports.cshtml:

@addTagHelper *, MetaMomentum 
@using MetaMomentum.Models

Replace the partial with Tag Helper:

<meta-momentum meta-values="@(Model.Value<MetaValues>("metaMomentum"))"></meta-momentum>

Step 4: Test the Migration

  1. Build your solution

  2. Run the site and open a content page

  3. View page source and verify meta tags are present:

  • <title> tag
  • <meta name="description"> tag
  • <meta property="og:*"> tags
  • <meta name="twitter:*"> tags
  1. Test with social debuggers:

Data Compatibility

✅ Good News: Existing content data is fully compatible with V3.0.

  • No database migration required
  • Existing meta values continue to work
  • Content editors don't need to re-enter data

Breaking Changes Summary

V2.x V3.0 Action Required
appsettings.json config Data Type settings Move values to Data Type
services.AddMetaMomentum() Not needed Remove from Startup
@Html.Partial("MetaMomentum/RenderMetaTags") <meta-momentum> Tag Helper Update views
FacebookId setting Removed Delete from config

Troubleshooting Migration

Tags Not Rendering

Symptom: No meta tags appear in page source

Solutions:

  1. Verify @addTagHelper *, MetaMomentum is in _ViewImports.cshtml
  2. Check the property alias matches: Model.Value<MetaValues>("metaMomentum")
  3. Rebuild the solution
  4. Clear Umbraco cache (Settings → Published Status → Reload)

Build Errors

Error: The type or namespace name 'MetaValues' could not be found

Solution: Add to _ViewImports.cshtml: @using MetaMomentum.Models

Missing Configuration Values

Symptom: Social tags missing site name or Twitter handle

Solution:

  1. Open Data Type settings in backoffice
  2. Scroll to Advanced Settings
  3. Enter OG Site Name and Twitter Name
  4. Save the Data Type

Facebook AppId Warnings

Question: Should I remove FacebookAppId?

Answer: Yes. Facebook deprecated this requirement. You can safely remove it from your configuration. The tag will no longer be rendered in V3.0.

Reference: Yoast - Facebook App ID Warnings

Rollback Plan

If you need to rollback to V2.x:

  1. Downgrade package: Update-Package MetaMomentum -Version 2.2.0
  2. Restore configuration:
  • Add back MetaMomentum section to appsettings.json
  • Add back services.AddMetaMomentum() to Startup
  1. Revert views:
  • Replace Tag Helpers with @Html.Partial("MetaMomentum/RenderMetaTags")
  1. Rebuild and test

Next Steps After Migration

Need Help?

If you encounter issues during migration:

  1. Check the Troubleshooting Guide
  2. Review GitHub Issues
  3. Open a new issue with:
  • Your Umbraco version
  • Meta Momentum versions (from → to)
  • Error messages or unexpected behavior
    • Steps to reproduce

Clone this wiki locally