Getting setup

• Start with an unmodified version 10 codebase and your upgraded database.
• Make sure the site runs
• We're going to take the old skin that is split between the /App_Templates and /App_Themes folder of the old site and consolidate them into one new /Skin folder.
• Open the old /App_Themes folder side by side with the new version 10 site /Skins folder so that you can easily copy files from old to new.

Creating the new Skin

• Duplicate the /Skins/Default folder found in the new site. Rename the folder to match your old skin name. For example "Skin_1". This will be your new skin name. For more information on how to make this a friendly name see here: Friendly Skin Names
• On the old site, navigate into the skin folder (App_Themes/{Skin_X}).
• On the new site, navigate into your new skin folder (/Skins/{NewSkinName}).

The App_Themes folder

CSS

• Before you begin

  • We're going to copy over CSS files from the old skin into the new skin. We recommend placing your CSS files in the /Skins/{NewSkinName}/Css folder.
  • If you have a _bootstrap.css file in your old skin that is unmodified we recommend that you do not bring this file over. The new skin has a new version of the Bootstrap css file. If you have modifications to this file you'll probably want to merge these changes into the new Bootstrap file, or put your changes in another place such as the style.css file to make future upgrades easier.
  • If you have a base.css file in your old skin that is unmodified we recommend that you do not bring over this file either. If you do have modifications to this file we recommend that you move those modifications into the new style.css file rather than overwriting the new base.css file. There are new styles in the base.css file that you are going to need.

• Move over your style.css file and any other custom CSS files you may have from /App_Themes/{Skin_X} to the /Skins/{NewSkinName}/Css folder.

• Make note of the CSS files that you do bring over so that we can reference those CSS files when you convert your template.
• Merge any modifications that you would like to keep from the old /App_Themes/{Skin_X}/_bootstrap.css into the new /Skins/{NewSkinName}/Css/bootstrap.css file or, if you would like to make future upgrades easier, move those changes to the /Skins/{NewSkinName}/Css/style.css file.
• Merge any modifications that you would like to keep from the old /App_Themes/{Skin_X}/base.css into the new /Skins/{NewSkinName}/Css/base.css file or, if you would like to make future upgrades easier, move those changes to the /Skins/{NewSkinName}/Css/style.css file.

• Links to images and local fonts in your css will now need to change because we've moved your Css into the Css folder.

  This:

  background-image: url(images/mybackground.gif);

  Becomes This

  background-image: url(../images/mybackground.gif);

Images

• Copy the images found in your /App_Themes/{Skin_X}/images folder into /Skins/{NewSkinName}/Images

Fonts

• If you've got glyphicons in the /App_Themes/{Skin_X}/fonts folder of your old skin there is no need to bring those over. They are already in version 10 and are most likely newer.
• If you have any additional custom fonts we recommend you move these over to the new /Skins/{NewSkinName}/Fonts folder

The App_Templates folder

Controls

• Controls such as the custom search control shipped with the bootstrap skin are no longer in MVC so there's no reason to bring over any custom controls.

JavaScript

• If you have an old bootstrap.js or bootstrap.min.js file in your skin folder you can probably leave that behind. Bootstrap is now included in version 10.
• If you have any javascripts in your /App_Templates/{Skin_X} folder or subfolders you can put those in the /Skins/{NewSkinName}/Scripts folder.
• Make note of the javascript files that you do bring over so that we can reference those javascript files when you convert your template.

SkinInfo

• Now lets navigate to the /App_Templates/{Skin_X}/SkinInfo folder of the old site. This is where we store information about your custom skin. This info is used in the admin console skin manager. You won't have this folder if you are upgrading from a version earlier than 9.4.2.0.
• Copy the preview image over into the new /Skins/{SkinName}/SkinInfo folder if you have one.
• Copy the skininfo.xml file over into the new /Skins/{SkinName}/SkinInfo folder if you have one.
• Open up your skinfo.xml file in a text editor and make sure you like the display name shown in the <DisplayName> node. Change this value to a friendly name for your skin if it is not already. You can also update the description and other nodes you find in there to whatever feels right.

Topics

• Move any file based topics that you use over from /App_Templates/{Skin_X}/Topics to /Skins/{NewSkinName}/Topics

XmlPackages

• Copy any custom xmlpackages that you would like to keep from /App_Templates/{Skin_X}/XmlPackages to /Skins/{NewSkinName}/XmlPackages

App_Templates CSS

• If you have CSS in your App_Templates folder there's a good chance you do not need to bring it over to the new skin. The only one you might want to consider is receipt.css if you'd made style modifications to your receipt.
• If you do bring over CSS put it in the /Skins/{SkinName}/CSS folder like you did above.

The template

• Locate your main template.master file and copy it over to the new skin in the /Skins/{NewSkinName}/Views/Shared folder.
• Delete the /Skins/{NewSkinName}/Views/Shared/_Layout.cshtml file (You've got the one in the Default folder for reference later if you need it.)
• Rename your template.master file to _Layout.cshtml
• You can leave the following master page files behind:
  • editaddressrecurring.master
  • empty.master
  • maintenance.master
• If you have other custom template files such as a home page template you can convert them in the same way you do your main template. For more info about custom layouts click here: Custom Layouts .

Converting the template

• Open your new _Layout.cshtml file in Visual Studio or a plain text editor. We recommend Visual Studio because you'll get good syntax highlighting and intellisense to help keep you from making mistakes.
• The razor examples below are case-sensitive so make sure that you copy them carefully if you want to use them on your own site. .
• Remove the master page reference and registrations and imports at the top. They all start with <%@ and end with %>.
• Now you should have a doctype at the top of your document that looks like this:
  
  <!DOCTYPE html>
• If you don't, add a doctype.
• If your doctype does not look the same. Change it to this new Html 5 style above.

The <head> section

• Before you begin
  • The head section of the default skin is stored in a separate partial view /Skins/{SkinName}/Views/Shared/_Head.cshtml. We recommend that you do the same for your custom skin.
  • The _Head.cshtml file is also shared with the pop up windows throughout the app, so styles and other resources you place in this file are also accessible to pop up content.
• Now open up the /Skins/{SkinName}/Views/Shared/_Head.cshtml file.
• Cut the contents of the <head> section of your new _Layout.cshtml and paste into the /Skins/{SkinName}/Views/Shared/_Head.cshtml file. Feel free to overwrite all of the contents of the _Head.cshtml file or leave the existing contents there for reference. Just make sure to clean up any unused code when you're done.
• Now back in the _Layout.cshtml file replace your head section with the following code:
  
  <head>

    @Html.Partial("_Head")

  </head>
• Head back over to your _Head.cshtml file.
• Remove any comments that look like this: <%-- This is a webforms style comment that won't work in razor --%>
• If you want to keep the comments you can replace them with razor style comments: @* Razor comment *@
• Remove the <title>, <meta name="description">, and <meta name="keywords"> tags and any comments about them and replace them with this code that you can copy from the default head partial view file(Skins/Default/Views/Shared/_Head.cshtml):
  
  @Html.Action(ActionNames.Detail, ControllerNames.MetaTag, new { metaTitle = @ViewBag.MetaTitle, metaDescription = @ViewBag.MetaDescription, metaKeywords = @ViewBag.MetaKeywords })

• Replace your jquery reference and the adnsf$ alias with this code from the default layout.

  • Replace this
    
    <%-- jQuery is required in versions 9.4 and higher --%>

    <script src="jscripts/jquery.min.js" type="text/javascript"></script>

    <script type="text/javascript">

      adnsf$ = jQuery; <%-- to avoid conflicts with existing jQuery versions and other javascript frameworks, change this line to adnsf$ = jQuery.noConflict(); --%>

    </script>
  • with this:
    
    @* Bundle and minify jQuery. *@

    @AspDotNetStorefront.Optimization.AdnsfBundler.RenderScriptBundle(

      bundlePath: "~/scripts/jquery",

      filePaths: new []

      {

          "~/scripts/jquery.js",

          "~/scripts/jquery.adnsfalias.js"

      }

    )
  • jQuery is required for AspDotNetStorefront to work properly so make sure to add it if you don't already have it.

CSS references

• Remember the list of CSS files you brought over earlier? Now's the time to get out that list. You'll want to reference any CSS that your skin needs from the new layout file.
• In version 9 all css files found anywhere in your /App_Themes/{Skin_X} folder were automatically referenced from you template. This is not the case in version 10. You'll need to specifically reference any css files you want to include. You can use either the bundling technique or simple css tags or both.
• You can bundle and minify your css automatically. You do not have to, but we recommend that you do so that you can benefit from faster initial page load times. To bundle your css add the following code and reference your own css files.
  
  @* Bundle and minify CSS. *@

  @AspDotNetStorefront.Optimization.AdnsfBundler.RenderStyleBundle(

    bundlePath: Url.SkinUrl("css/bundled"),

    filePaths: new []

    {

        Url.AppRelativeSkinUrl("css/bootstrap.css"),

        Url.AppRelativeSkinUrl("css/font-awesome.css"),

        Url.AppRelativeSkinUrl("css/base.css"),

        Url.AppRelativeSkinUrl("css/style.css"),

    }

  )
• Make sure that you use unique bundlePath parameters. This is just a made up url by the way. Use any path string you want for bundlePath, but remember that if you link to external resources like images from within your CSS, you'll want to use a path that is in the same directory as your real CSS file.
• Only bundle local files. Don't try to bundle files that you are running from somewhere off of your website like a CDN.
• If you have CSS outside of your skin folder you can reference it like so:
  
  @AspDotNetStorefront.Optimization.AdnsfBundler.RenderStyleBundle(

    bundlePath: "~/bundledrootcss",

    filePaths: new []

    {

        "~/ImInTheRootFolder.css"

    }

  )
• If you do not use the CSS bundler you can reference your skin css more typically like so:
  
  <link href="~/skins/@Html.Token("SkinName")/css/mystyles.css" rel="stylesheet" type="text/css" />
• Watch out for that tricky receipt.css file. It is not supposed to be referenced from your site so don't add it to your bundle. It is referenced from your receipt automatically. If you modified your old receipt css just make sure that you bring that file over to the new skin. Otherwise use the version 10 receipt.css.
• If you have a reference to the bootstrap javascript you can safely leave that out of your _Head.cshtml file. That will get added down in the body close area.

Javascript references

• You can also bundle and minify your javascript references. You'll see that we've moved as many of these javascript references to the <body> close area as possible. You may want to do the same with yours to help speed up your pageload times. I would recommend doing this only if you know exactly how all your custom javascript works though. To include your javascript in the <head> or the close <body> area you can do this:
  
  @* Bundle and minify JavaScript. *@

  @AspDotNetStorefront.Optimization.AdnsfBundler.RenderScriptBundle(

    bundlePath: "~/scripts/bundled",

    filePaths: new[]

    {

        "~/scripts/myscript.js",

        "~/scripts/anotherscript.js",

        Url.AppRelativeSkinUrl("scripts/relativetoskin.js"),

    }

  )
• Like the CSS, don't try to bundle remote paths and make sure your bundlePath parameter is unique if you use several bundles.
• If you don't want to bundle your javascript you can do something like this:
  
  <script type="text/javascript" src="~/skins/@Html.Token("SkinName")/scripts/myscript.js"></script>

  The <body> tag

• Navigate back over to your _Layout.cshtml file if you haven't already.
• Remove references to AjaxTookKit and the if statement around it like this:
  
  <%  if(RequireScriptManager)

  { %>

  <%-- Only render for pages that require ajax --%>

  <ajaxToolkit:ToolkitScriptManager runat="server" ID="scrptMgr" CombineScripts="true" />

  <% } %>
• Remove the <form> tag that wraps around the contents of the body. Don't forget to get the closing form tag too.
• Please perform a 30 second moment of silence for Asp.Net webforms. If you will not miss webforms please proceed to the next step.
• Like the head section we compartmentalized the body open and body close areas into partial views, /Skins/{SkinName}/Views/Shared/_BodyOpen.cshtml and /Skins/{SkinName}/Views/Shared/_BodyClose.cshtml.
• Let's add the body open and body close sections to the top and bottom of your body tag like so:
  
  <body>

    @Html.Partial("_BodyOpen")

    ...

    The contents of the body. There should be lots of HTML here

    ...

    @Html.Partial("_BodyClose")

  </body>

Body open area

The body open area is mostly for javascripts that you need to run in this section of the document. It's not recommended that you put content in here.

• Open up the /Skins/{SkinName}/Views/Shared/_BodyOpen.cshtml file.
• Notice the following items:
  • The IE8 Media query support
  • The page info token
  • The preview bar for previewing different skins from the admin console
  • The "script.bodyopen" xmlpackage token
• Remove these items above from your new _Layout.cshtml file.
• If you have any other scripts that you would like to add to this section from you layout file, go right on ahead. Resources placed here will also be shared with the pop up window layout.

Body Close Area

The body close partial is for javascripts so keep that in mind as you decide what to put in here.

• Now open up the /Skins/{SkinName}/Views/Shared/_BodyClose.cshtml file.
• Notice the following:
  • The BuySafe token
  • The Bongo token (Note - Bongo have now deprecated their Extend product)
  • The Google Trusted Stores Token
  • The closing body tag javascripts (including bootstrap.js)
  • The "script.bodyclose" xmlpackage token
• Remove the items above from your _Layout.cshtml file. Feel free to move other scripts that would make sense into this file. These scripts will also be used in the pop up window layout.

String Resources references

String resources used to be referenced like this:

 

Now we do this:

 

Nice right?

Xmlpackage references

• Xmlpackages used to be referenced like this
  
  <aspdnsf:XmlPackage runat="server" PackageName="script.bodyclose" />
• We'll want to replace that syntax with this
  
  @Html.XmlPackage("script.bodyclose")
• Sometimes you'll see something like this for an old XmlPackage reference:
  
  <asp:Literal ID="litTrustedStores" runat="server" Text='<%$ Tokens: XmlPackage, skin.trustedstores.xml.config %>' />
• You'd replace that the same way as above:
  
  @Html.XmlPackage("skin.trustedstores.xml.config")
• Sometimes you'll need to pass additional parameters. Here's the old style:
  
  <aspdnsf:XmlPackage ID="XmlPackage2" runat="server" PackageName="entitymenu" RuntimeParams="entitytype=manufacturer" />

• Add your additional parameters with a new anonymous type like so:

  @Html.XmlPackage("entitymenu", new { entitytype = "manufacturer" })

   

  Topic references

  old:

  <aspdnsf:Topic runat="server" TopicName="Template.Logo" />

   

  new:

  @Html.Topic("Template.Logo")

   

  Other token references

  old:

  <asp:Literal ID="ltrPageInfo" runat="server" Text='<%$ Tokens:PageInfo %>' />

   

  new:

  @Html.Token("PageInfo")

   

Breadcrumb

• Replace the breadcrumb with this code from the default layout file:
  
  @Html.Action(

      actionName: "Detail",

      controllerName: "Breadcrumb",

      routeValues: new

      {

          PageTitle = ViewBag.PageTitle,

          PathInfo = ViewBag.PathInfo

      })

Notices area

Wherever you'd like error/validation messages to appear in your layout (usually just above the breadcrumb), add this code:

 

Main contents area

old:

 

new:

 

Search box

Replace your search box with this:

 

• Make sure you've removed all of the runat="server" tags from the template at this point.

Footer area

At the bottom of the body area, just above @Html.Partial("_BodyClose"), add this code if you're going to be using the popup minicart or the wishlist:

 

 

Aspx page links in your layout file

You will want to replace any links to aspx pages such as 'account.aspx' with the new MVC style Url.Action(). So this:

 

Becomes:

 

This will allow you to change your URLs to the modern styles when you're ready at some point in the future.

For more information about building links see Mvc Link Reference.

Links in your topics referenced from your layout

If your template file pulls in topics for blocks of HTML content, you will also want to update any links they contain as follows.

Replace links to aspx pages like so:

 

With this:

 

 

Replace any links to topics such as this:

 

With this style link:

 

Testing and resolving issues

• Now you should be able to load up the site in a browser and see what it looks like. I like to cross my fingers at this point. It seems to help.
• Common issues are
  • Missing CSS references. Make sure to reference your CSS files in their new location in the /Skins/{NewSkinName}/Css folder.
  • Missing javascript references
  • If you had a custom template for your homepage or other pages you'll need to follow instructions here(Custom Layouts ) about adding additional custom layouts. We no longer support the HomeTemplate appconfig. Razor has much more flexible ways of specifying a custom layout file.
  • Broken links to aspx pages such as account.aspx. Make sure to use the new MVC style links metioned above