Build and deploy .net framework / .net core to IIS with Gitlab and some awesome templates

In this blog I'll explain the way we do our builds with gitlab. It took some time to get to this, so I'm happy to share it with you. At first we set the ground-rules:

1. You use GitLab
2. You have GitLab runners on windows machines on powershell (core)
3. Make use of merge requests to merge code changes to the default branch
4. Create release tags in the form of semver '1.0.0'
5. The default branch always gets deployed to your development IIS server
6. After creating a release in GitLab, a production build is generated
7. Manual trigger starts the deployment to your production IIS server
8. There is a solution file in the root of the project
9. There is only 1 deployable webproject in your solution
10. The dotnet-* templates reside in a shared repository

Challenges we faced we're especially with the msdeploy command which behaves really funky under powershell (I dare you to do a duckduckgo search on this and see what you'll find). I really like the way everything is parameterized, so the core just works, but if you need a bit more, you just adjust where needed without breaking all the defaults in the build an deploy pipelines. This makes maintaining them a lot easier when environments change and forces you to use a standardized way of work. 

I also like the validation of the release tag numbering using the .pre step validate_tag job. It only runs when a tag is set and it's not in the form of a semver. You can never build a production packages without a proper number.

The .gitlab.yml is the ci file for your end project, it sets urls and can customize some configuration. The dotnet-framework.v1.gitlab-ci.yml and dotnet-core.v1.gitlab-ci.yml files are the base templates you can inherit in the .gitlab-ci.yml. 

Below are all the gists needed to get you going or just to get inspired. If you have any feedback, I'm happy to learn about your experiences. Comment on the gist or this blog!

Happy deploying,

Luuk

	# This file shows how to setup the template for your projects
	include:
	- project: 'templates'
	file: 'gitlab-templates/dotnet-framework.v1.gitlab-ci.yml'
	variables:
	ENABLE_UNITTESTS: 'true'
	DEFAULT_IIS_SITENAME: "my-awesome-deployment.nl" # For dev deploys this gets prefixed with 'development.', for prod it gets prefixed with 'www.'
	DEFAULT_DEVELOPMENT_URL: "https://my-awesome-deployment.devserver.nl/"
	DEFAULT_PRODUCTION_URL: "https://www.my-awesome-deployment.nl/"
	# If you want to do some additional things during the default steps,
	# for example build node stuff, you can do that in the 'before_script'
	build_debug:
	cache:
	key: npm-cache
	paths:
	- '$env:CI_PROJECT_DIR\\.npm\\'
	before_script:
	- 'npm ci --cache $env:CI_PROJECT_DIR\\.npm --prefer-offline'
	- 'npx lerna bootstrap -- --cache $env:CI_PROJECT_DIR\\.npm --prefer-offline'
	- 'npx lerna run test'
	- 'npx lerna run build'
	# Or you can overrule the variables for the seperate steps
	deploy_production:
	variables:
	IIS_SERVER: 'overruled-prodserver.nl'

view raw .gitlab-ci.yml hosted with ❤ by GitHub

	include:
	- project: 'templates' # refer to the base template of dotnet-framework.v1.gitlab-ci.yml
	file: 'gitlab-templates/dotnet-framework.v1.gitlab-ci.yml'
	build_debug:
	stage: build
	script:
	- 'dotnet restore'
	- 'dotnet build --nologo --no-restore --verbosity quiet /p:DeployOnBuild=true /p:WebPublishMethod=Package /p:PackageAsSingleFile=true /p:PackageLocation="$CI_PROJECT_DIR\$PACKAGE_TO_DEPLOY" /p:Configuration=Debug /p:EnvironmentName=Staging'
	# INSTALL https://www.nuget.org/packages/JUnitXml.TestLogger/ into the test projects
	test:
	script:
	- 'dotnet restore'
	- 'dotnet test --no-restore --test-adapter-path:. --logger:"junit;LogFilePath=..\..\artifacts\{assembly}-test-result.xml;MethodFormat=Class;FailureBodyFormat=Verbose"'
	build_release:
	stage: build
	script:
	- 'dotnet restore'
	- 'dotnet build --nologo --no-restore --verbosity quiet /p:DeployOnBuild=true /p:WebPublishMethod=Package /p:PackageAsSingleFile=true /p:PackageLocation="$CI_PROJECT_DIR\$PACKAGE_TO_DEPLOY" /p:Configuration=Release /p:EnvironmentName=Production'

view raw dotnet-core.v1.gitlab-ci.yml hosted with ❤ by GitHub

	# This is de default build script for .net solutions
	# To implement this, override the variables with [OVERRIDE THIS VARIABLE]
	# Or overrule parts of the script that dont fit your needs
	# See https://docs.gitlab.com/ee/ci/yaml/includes.html
	# The deployment phase expects a MSDEPLOY package as a zip file in artifacts\website.zip
	# To overrule the file location update the PACKAGE_TO_DEPLOY variable.
	include:
	- template: "Workflows/MergeRequest-Pipelines.gitlab-ci.yml"
	stages:
	- build
	- test
	- deploy
	variables:
	ENABLE_UNITTESTS: 'false'
	DEFAULT_IIS_SITENAME: "[OVERRIDE THIS VARIABLE]"
	DEFAULT_DEVELOPMENT_URL: "[OVERRIDE THIS VARIABLE]"
	DEFAULT_PRODUCTION_URL: "[OVERRIDE THIS VARIABLE]"
	PACKAGE_TO_DEPLOY: 'artifacts\website.zip'
	NUGET_PATH: 'C:\tools\build\nuget.exe'
	MSBUILD_PATH: 'C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\MSBuild\Current\Bin\MSBuild.exe'
	MSDEPLOY_PATH: 'C:\Program Files\IIS\Microsoft Web Deploy V3\msdeploy.exe'
	validate_tag:
	stage: .pre
	script:
	- echo Release tags should follow semver numbering
	- echo For example "1.0.3"
	- exit 1
	tags:
	- windows
	rules:
	- if: $CI_COMMIT_TAG && $CI_COMMIT_TAG !~ /^[0-9]+[.][0-9]+[.][0-9]+$/
	build_debug:
	stage: build
	script:
	- '& "$env:NUGET_PATH" restore -Verbosity quiet'
	- '& "$env:MSBUILD_PATH" /p:DeployOnBuild=true /p:DeployTarget=Package /p:PackageLocation="$env:CI_PROJECT_DIR\$env:PACKAGE_TO_DEPLOY" /p:Configuration=Debug -consoleloggerparameters:"ErrorsOnly;Summary" -verbosity:quiet -m'
	artifacts:
	expire_in: 5 days
	paths:
	- '$env:PACKAGE_TO_DEPLOY'
	tags:
	- windows
	rules:
	- if: $CI_COMMIT_TAG
	when: never
	- if: $CI_MERGE_REQUEST_IID
	- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
	# INSTALL https://www.nuget.org/packages/JUnitXml.TestLogger/ into the test projects
	test:
	stage: test
	script:
	- '& "$env:NUGET_PATH" restore -Verbosity quiet'
	- '& "$env:MSBUILD_PATH" /p:DeployOnBuild=true /p:DeployTarget=Package /p:PackageLocation="$env:CI_PROJECT_DIR\$env:PACKAGE_TO_DEPLOY" /p:Configuration=Debug -consoleloggerparameters:"ErrorsOnly;Summary" -verbosity:quiet -m'
	- 'dotnet test tests\**\bin\**\*.Tests.dll --test-adapter-path:. --logger:"junit;LogFilePath=.\artifacts\{assembly}-test-result.xml;MethodFormat=Class;FailureBodyFormat=Verbose"'
	artifacts:
	when: always # save test results even when the task fails
	expire_in: 1 week
	paths:
	- artifacts/*test-result.xml
	reports:
	junit:
	- artifacts/*test-result.xml
	tags:
	- windows
	rules:
	- if: $ENABLE_UNITTESTS == 'false'
	when: never
	- if: $CI_COMMIT_TAG
	when: never
	- if: $CI_MERGE_REQUEST_IID
	- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
	deploy_development:
	environment:
	name: development
	url: $DEFAULT_DEVELOPMENT_URL
	stage: deploy
	variables:
	IIS_SERVER: 'devserver.nl'
	IIS_SITENAME: development.$DEFAULT_IIS_SITENAME
	IIS_WEBDEPLOY_USERNAME: $DEVSERVER_WEBDEPLOY_USERNAME # SET BY CI/CD Protected variables
	IIS_WEBDEPLOY_PASSWORD: $DEVSERVER_WEBDEPLOY_PASSWORD # SET BY CI/CD Protected variables
	script:
	- |
	$arguments = [string[]]@(
	"-verb:sync",
	"-source:package='$PACKAGE_TO_DEPLOY'",
	"-dest:auto,computerName='https://${IIS_SERVER}:8172/msdeploy.axd?site=$IIS_SITENAME',userName='$IIS_WEBDEPLOY_USERNAME',password='$IIS_WEBDEPLOY_PASSWORD',authtype='Basic'",
	"-setParam:name='IIS Web Application Name',value='$IIS_SITENAME'",
	"-allowUntrusted",
	"-skip:Directory='App_Data'",
	"-skip:skipaction='Delete',objectname='dirPath',absolutepath='\\media'")
	- Start-Process "$env:MSDEPLOY_PATH" -ArgumentList $arguments -NoNewWindow -Wait
	tags:
	- windows
	rules:
	- if: $CI_COMMIT_TAG
	when: never
	- if: $CI_MERGE_REQUEST_IID
	when: manual
	allow_failure: true
	- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
	dependencies:
	- build_debug
	build_release:
	stage: build
	script:
	- '& "$env:NUGET_PATH" restore -Verbosity quiet'
	- '& "$env:MSBUILD_PATH" /p:DeployOnBuild=true /p:DeployTarget=Package /p:PackageLocation="$env:CI_PROJECT_DIR\$env:PACKAGE_TO_DEPLOY" /p:Configuration=Release -consoleloggerparameters:"ErrorsOnly;Summary" -verbosity:quiet -m'
	artifacts:
	paths:
	- '$PACKAGE_TO_DEPLOY'
	tags:
	- windows
	rules:
	- if: $CI_COMMIT_TAG
	deploy_production:
	environment:
	name: production
	url: $DEFAULT_PRODUCTION_URL
	stage: deploy
	variables:
	IIS_SERVER: 'prodserver.nl'
	IIS_SITENAME: www.$DEFAULT_IIS_SITENAME
	IIS_WEBDEPLOY_USERNAME: $PRODSERVER_WEBDEPLOY_USERNAME # SET BY CI/CD Protected variables
	IIS_WEBDEPLOY_PASSWORD: $PRODSERVER_WEBDEPLOY_PASSWORD # SET BY CI/CD Protected variables
	script:
	- |
	$arguments = [string[]]@(
	"-verb:sync",
	"-source:package='$PACKAGE_TO_DEPLOY'",
	"-dest:auto,computerName='https://${IIS_SERVER}:8172/msdeploy.axd?site=$IIS_SITENAME',userName='$IIS_WEBDEPLOY_USERNAME',password='$IIS_WEBDEPLOY_PASSWORD',authtype='Basic'",
	"-setParam:name='IIS Web Application Name',value='$IIS_SITENAME'",
	"-allowUntrusted",
	"-skip:Directory='App_Data'",
	"-skip:skipaction='Delete',objectname='dirPath',absolutepath='\\media'")
	- Start-Process "$env:MSDEPLOY_PATH" -ArgumentList $arguments -NoNewWindow -Wait
	tags:
	- windows
	rules:
	- if: $CI_COMMIT_TAG
	when: manual
	dependencies:
	- build_release

view raw dotnet-framework.v1.gitlab-ci.yml hosted with ❤ by GitHub

Umbraco modelsbuilder line endings

Everytime the modelsbuilder detects a change in LiveAppData moe, the generated file will be touched.

Git uses auto line-endings, meaning CRLF on windows, while the umbraco models builder uses LF (https://github.com/modelsbuilder/ModelsBuilder.Original/blob/v4/dev/src/Our.ModelsBuilder/Building/CodeWriterBase.cs#L65) This is seen as a change, but when running git add this change is corrected by git and then dropped.

This is very annoying, but easy to fix with a .gitattributes file. As a base I've used the one in the UmbracoCms repository, and extended it with the path to the models builder output:

	*.doc diff=astextplain
	*.DOC diff=astextplain
	*.docx diff=astextplain
	*.DOCX diff=astextplain
	*.dot diff=astextplain
	*.DOT diff=astextplain
	*.pdf diff=astextplain
	*.PDF diff=astextplain
	*.rtf diff=astextplain
	*.RTF diff=astextplain
	*.jpg binary
	*.png binary
	*.gif binary
	*.cs text=auto diff=csharp
	*.vb text=auto
	*.c text=auto
	*.cpp text=auto
	*.cxx text=auto
	*.h text=auto
	*.hxx text=auto
	*.py text=auto
	*.rb text=auto
	*.java text=auto
	*.html text=auto
	*.htm text=auto
	*.css text=auto
	*.scss text=auto
	*.sass text=auto
	*.less text=auto
	*.js text=auto
	*.lisp text=auto
	*.clj text=auto
	*.sql text=auto
	*.php text=auto
	*.lua text=auto
	*.m text=auto
	*.asm text=auto
	*.erl text=auto
	*.fs text=auto
	*.fsx text=auto
	*.hs text=auto
	*.json text=auto
	*.xml text=auto
	*.ts text=auto
	*.tsx text=auto
	*.csproj text=auto merge=union
	*.vbproj text=auto merge=union
	*.fsproj text=auto merge=union
	*.dbproj text=auto merge=union
	*.sln text=auto eol=crlf merge=union
	# Models builder uses LF as line-endings
	# https://github.com/modelsbuilder/ModelsBuilder.Original/blob/v4/dev/src/Our.ModelsBuilder/Building/CodeWriterBase.cs#L65
	/src/Your.Umbraco.Website.Website/Path/To/Generated/Models/*.cs text eol=lf
	*.gitattributes text=auto

view raw .gitattibutes hosted with ❤ by GitHub

Remove format on paste in SXA Experience Editor

The experience editor uses the contenteditable feature. To remove formatting on paste you cannot use the Telerik RTE feature, because that one isn't used.

To solve, I've created a new Editing Theme in the medialibrary\Base Themes:

Upload the editor.js file containing:

window.$xa(document).ready(function () {
    $('[contenteditable]').on('paste', function(e) {
     e.preventDefault();
     var text = '';
     if (e.clipboardData || e.originalEvent.clipboardData) {
       text = (e.originalEvent || e).clipboardData.getData('text/plain');
     } else if (window.clipboardData) {
       text = window.clipboardData.getData('Text');
     }
     if (document.queryCommandSupported('insertText')) {
       document.execCommand('insertText', false, text);
     } else {
       document.execCommand('paste', false, text);
     }
 });
});

Then add My Editing Theme to the Editing Theme of your site:

Now you can do paste from word without keeping the content. Happy content editors, happy developers!

Cheers, Luuk

Kendo UI Invalid template message

Just in case you'll get:

Invalid template:'<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:dcmitype="http://purl.org/dc/dcmitype/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><dc:creator>${creator}</dc:creator><cp:lastModifiedBy>${lastModifiedBy}</cp:lastModifiedBy><dcterms:created xsi:type="dcterms:W3CDTF">${created}</dcterms:created><dcterms:modified xsi:type="dcterms:W3CDTF">${modified}</dcterms:modified></cp:coreProperties>' Generated code:'var $kendoOutput, $kendoHtmlEncode = kendo.htmlEncode;with(data){$kendoOutput='<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\r\n<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:dcmitype="http://purl.org/dc/dcmitype/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><dc:creator>'+($kendoHtmlEncode(creator))+'</dc:creator><cp:lastModifiedBy>'+($kendoHtmlEncode(lastModifiedBy))+'</cp:lastModifiedBy><dcterms:created xsi:type="dcterms:W3CDTF">'+($kendoHtmlEncode(created))+'</dcterms:created><dcterms:modified xsi:type="dcterms:W3CDTF">'+($kendoHtmlEncode(modified))+'</dcterms:modified></cp:coreProperties>';}return $kendoOutput;' 

With firefox I got the message 'Content Security Policy: The page’s settings blocked the loading of a resource at eval (“script-src”).'

So in your Content Security Policy policy add 'unsave-eval' to the script-src.

Cheers,
L

Extend Sitecore SXA metadata with hreflang and better favicon support (pt. 2 - hreflang)

When you're creating a multi lingual site, you probably want to tell the search engines to tell where to find the content in a different language. The way to do this is using hreflang.

Using the hreflang from the MetadataExtended this is really easy peasy!

You'll only have to add the hreflang rendering to the metadata partial design (like with the FaviconExtension in the previous post) manually, the rest is in the config.

The idea is that you don't use the language cookie, but always use the language from the url. To do so we need to enable the custom link manager and add a pipeline to remove the language cookie:

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <linkManager defaultProvider="sitecore">
      <providers>
        <add name="ExtendedLinkProvider" 
             type="SXA.Feature.MetadataExtended.Providers.ExtendedLinkProvider, SXA.Feature.MetadataExtended" 
             cacheExpiration="5" 
             addAspxExtension="false" 
             alwaysIncludeServerUrl="false" 
             lowercaseUrls="true" 
             encodeNames="true" 
             languageEmbedding="always" 
             languageLocation="filePath" 
             shortenUrls="false" 
             useDisplayName="true">
        </add>
      </providers>
      <patch:attribute name="defaultProvider">switchableLinkProvider</patch:attribute>
    </linkManager>
    <pipelines>
      <httpRequestProcessed>
        <processor type="SXA.Feature.MetadataExtended.Pipelines.HttpRequestProcessed.LanguageCookieRemover, SXA.Feature.MetadataExtended" resolve="true" />
      </httpRequestProcessed>
    </pipelines>
  </sitecore>
</configuration>

Then enable the ExtendedLinkProvider in your SXA site, and disable language cookie support. Browse to /sitecore/content/{tenant}/{site}/Settings/Site Grouping/{site} and update the Link Provider Name. You'll also need to set the disableLanguageCookie to true:

The ExtendedLinkProvider does a bit of magic, it adds the language to the url for all languages, except for 'en'. You can always modify this behavior, but I like it this way.

To get the right localized url which uses the displayname instead of the item name (see LinkManager config above 'useDisplayName'), you'll have to do something weird, I would expect that it works when you use the language switcher it will pick up the displayname in that language. Too bad it doesn't do that, you'll need to get the language item. But the language item itself doesn't add the language in front of the url, so wrapping it around a LanguageSwitcher does the magic:

var language = Language.Parse(languageCode);

// We have to get the language item for the right display-name
var languageItem = item.Database.GetItem(item.ID, language);

// And use the Language switcher to get the right language in the url
using (new LanguageSwitcher(language))
{
    return LinkManager.GetItemUrl(languageItem); 

    // NOTE: The actual code has an option to return the full server url

    // which is needed for hreflang
}

With this, you'll get the hreflang:

If you have any questions or issues, please hit me a message below or file a ticket on:
https://github.com/luuksommers/sitecore-sxa-metadataextended

[dutch]Computer ze![/dutch]

Luuk

Extend Sitecore SXA metadata with hreflang and better favicon support

Sitecore SXA only supports a simple favicon OOTB. Because we have a full blown mobile supported website, we want to support all the native font formats as generated by https://realfavicongenerator.net/. For this I've created MetadataExtended feature for SXA.

To use it add the _FaviconExtended template to the Settings template that has been generated for your website:

After adding this template, you'll get a lot more options in the favicon section of your settings:

Here you can upload all the files that are generated by https://realfavicongenerator.net/.

Please note that the site.webmanifest and browserconfig.xml contain a link to an icon. There files are not automatically generated in the initial version, so update them with the right media path.

Now all we need to do is add the right rendering to the medatdata partial design (/sitecore/content/{tenant}/{site}/Presentation/Partial Designs/Metadata). You can do this by adding the rendering to the /sitecore/content/{tenant}/{site}/Presentation/Available Renderings and add it using the experience editor, or directly using the Presentation Details. And voila on the favicon checker, all is green!

On the next post I'll explain the hreflang extension.

All code is available on https://github.com/luuksommers/sitecore-sxa-metadataextended

Happy faviconning,

Luuk

Patching Sitecore web.config on Azure using VSTS WebApp deploy

With Sitecore, it's a best practice to not copy the web.config to your project, but use transformations. This is a really nice idea, but when deploying Sitecore using the ARM templates to Azure and apply your solution on top of it, you cannot edit the web.config. With the solution below I want to show how to apply config transformations on Azure using the VSTS Web App Service Deploy task. The method is kinda easy once you know how to do it.

First, add the code from configtransfrom to your App_Data\tools folder, the binaries and postdeployment command are stored here. Secondly add a web.azure.config to the project, with the build action set to Content. Lastly, update the release definition and add the postdeployment task to the Web App Service Deploy.

The line in the postdeploy.cmd that does the magic is:

"%WEBROOT_PATH%\App_Data\tools\configtransform\SlowCheetah.Xdt.exe" "%WEBROOT_PATH%\web.config" "%WEBROOT_PATH%\web.azure.config" "%WEBROOT_PATH%\web.config"

To see all other available environment variables run 'set' from the kudu console.

Offcourse the source is available on Github: https://github.com/luuksommers/sitecore-azure-configtransform

Happy transforming!
Luuk