From 865edd18b7706db3be9b9648926cdb40c18c30be Mon Sep 17 00:00:00 2001 From: Benjamin Moles Date: Tue, 3 Apr 2018 22:39:17 +0200 Subject: [PATCH 1/4] Fix small issue in README file (reference to number of projects in solution) --- sitecore/9.0.1 rev. 171219 XM1/VS2017/TDSSample/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sitecore/9.0.1 rev. 171219 XM1/VS2017/TDSSample/README.md b/sitecore/9.0.1 rev. 171219 XM1/VS2017/TDSSample/README.md index e0e1033..fa25640 100644 --- a/sitecore/9.0.1 rev. 171219 XM1/VS2017/TDSSample/README.md +++ b/sitecore/9.0.1 rev. 171219 XM1/VS2017/TDSSample/README.md @@ -23,7 +23,7 @@ This demo showcases how to create a VS2017 project for Sitecore with the followi 1. Open VS2017 as Administrator 1. Open the solution “C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\TDSSample\\**TDSSample.sln**” 1. Make sure the project “**docker-compose**” is set as StartUp project -1. Build the solution. The two projects in the solution should compile. +1. Build the solution. The three projects in the solution should compile. 1. Review the files "C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\TDSSample\\**Website\Dockerfile**" and "C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\TDSSample\\**Website\build.Dockerfile**" and update the `FROM` clause with the name used to build the base images. 1. Build the solution with “**Debug**” configuration ("F5"). >The first time the containers run, the base images will detect that the required assets (databases, indexes and site files) are missing in their respected VOLUMEs (pointing to the development environment) and will take some time to create them. VS will build the containers and will try to attach to the IIS's process running in website's container, however it will fail (TODO: fix this known issue). In the meantime, the file transfer from the images to the Development environment will keep progresing. Please be patient. From 7e0ff1deacf35f9774486ff0af6d655e3d14f583 Mon Sep 17 00:00:00 2001 From: Benjamin Moles Date: Wed, 4 Apr 2018 23:02:18 +0200 Subject: [PATCH 2/4] Prevent Git from adjusting line endings on Sitecore .item files --- .gitattributes | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .gitattributes diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..de072a1 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,5 @@ + + + +# Do not adjust line endings on Sitecore .item files +*.item -text From 1c7bcf0bbcab4bff7e9213c5206bb0c45c14995a Mon Sep 17 00:00:00 2001 From: Benjamin Moles Date: Sun, 8 Apr 2018 21:59:46 +0200 Subject: [PATCH 3/4] Fix typo in README file --- sitecore/9.0.1 rev. 171219 XM1/VS2017/TDSSample/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sitecore/9.0.1 rev. 171219 XM1/VS2017/TDSSample/README.md b/sitecore/9.0.1 rev. 171219 XM1/VS2017/TDSSample/README.md index fa25640..1a3321c 100644 --- a/sitecore/9.0.1 rev. 171219 XM1/VS2017/TDSSample/README.md +++ b/sitecore/9.0.1 rev. 171219 XM1/VS2017/TDSSample/README.md @@ -25,7 +25,7 @@ This demo showcases how to create a VS2017 project for Sitecore with the followi 1. Make sure the project “**docker-compose**” is set as StartUp project 1. Build the solution. The three projects in the solution should compile. 1. Review the files "C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\TDSSample\\**Website\Dockerfile**" and "C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\TDSSample\\**Website\build.Dockerfile**" and update the `FROM` clause with the name used to build the base images. -1. Build the solution with “**Debug**” configuration ("F5"). +1. Run the solution with “**Debug**” configuration ("F5"). >The first time the containers run, the base images will detect that the required assets (databases, indexes and site files) are missing in their respected VOLUMEs (pointing to the development environment) and will take some time to create them. VS will build the containers and will try to attach to the IIS's process running in website's container, however it will fail (TODO: fix this known issue). In the meantime, the file transfer from the images to the Development environment will keep progresing. Please be patient. 1. Copy the website's container’s IP from the VS' "Output" panel (make sure it is the "Docker" output) and paste the IP on a browser's address bar. Please notice that Sitecore needs some time to warm-up, therefore the initial start may take a bit (up to 1-2 min). 1. The browser will display the OOTB Sitecore’s home page. From cb458c2f9e8b94259637d729d870af33aea50464 Mon Sep 17 00:00:00 2001 From: Benjamin Moles Date: Mon, 9 Apr 2018 00:13:33 +0200 Subject: [PATCH 4/4] Improvements made to README files --- .../VS2017/SimpleSample/README.md | 20 +++--- .../VS2017/TDSSample/README.md | 67 ++++++++++++++----- 2 files changed, 60 insertions(+), 27 deletions(-) diff --git a/sitecore/9.0.1 rev. 171219 XM1/VS2017/SimpleSample/README.md b/sitecore/9.0.1 rev. 171219 XM1/VS2017/SimpleSample/README.md index 8888524..e04f89a 100644 --- a/sitecore/9.0.1 rev. 171219 XM1/VS2017/SimpleSample/README.md +++ b/sitecore/9.0.1 rev. 171219 XM1/VS2017/SimpleSample/README.md @@ -1,4 +1,6 @@ -# docker-demo for Sitecore 9.0.1 rev. 171219 XM1 +# SimpleSample Demo + +## Demo Introduction This demo showcases how to create a VS2017 project for Sitecore with the following features: @@ -16,7 +18,7 @@ This demo showcases how to create a VS2017 project for Sitecore with the followi ## Development Environment Setup -1. Clone [this repository](https://github.com/Sitecore/docker-demo) into a folder such as “c:\Docker\Sitecore\docker-demo” (next steps will asume this folder has been used): +1. Clone [this repository](https://github.com/Sitecore/docker-demo) into a folder such as “c:\Docker\Sitecore\docker-demo” (next steps will assume this folder has been used): 1. Copy "**license.xml**" into "C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\SimpleSample\\**storage\Data**“ 1. Open VS2017 as Administrator 1. Open the solution “C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\SimpleSample\\**SimpleSample.sln**” @@ -24,7 +26,7 @@ This demo showcases how to create a VS2017 project for Sitecore with the followi 1. Build the solution. The two projects in the solution should compile. 1. Review the files "C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\SimpleSample\\**Website\Dockerfile**" and "C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\SimpleSample\\**Website\build.Dockerfile**" and update the `FROM` clause with the name used to build the base images. 1. Build the solution with “**Debug**” configuration ("F5"). - >The first time the containers run, the base images will detect that the required assets (databases, indexes and site files) are missing in their respected VOLUMEs (pointing to the development environment) and will take some time to create them. VS will build the containers and will try to attach to the IIS's process running in website's container, however it will fail (TODO: fix this known issue). In the meantime, the file transfer from the images to the Development environment will keep progresing. Please be patient. + >The first time the containers run, the base images will detect that the required assets (databases, indexes and site files) are missing in their respected VOLUMEs (pointing to the development environment) and will take some time to create them. VS will build the containers and will try to attach to the IIS's process running in website's container, however it will fail (TODO: fix this known issue). In the meantime, the file transfer from the images to the Development environment will keep progressing. Please be patient. 1. Copy the website's container’s IP from the VS' "Output" panel (make sure it is the "Docker" output) and paste the IP on a browser's address bar. Please notice that Sitecore needs some time to warm-up, therefore the initial start may take a bit (up to 1-2 min). 1. The browser will display the OOTB Sitecore’s home page. 1. Any change made to the following folder will be automatically detected by sitecore @@ -32,7 +34,7 @@ This demo showcases how to create a VS2017 project for Sitecore with the followi ## Development Process -Sitecore supports multiple sites and also multiple URL for each site. It may be necessary to access the site with a specific URL (other than the IP). In these cases, it is necessary to update the development environment's host file every time the container is run (instantiated), which happens the first time VS runs the project. +Sitecore supports multiple sites and multiple URL for each site. It may be necessary to access the site with a specific URL (other than the IP). In these cases, it is necessary to update the development environment's host file every time the container is run (instantiated), which happens the first time VS runs the project. Following the initial container run, the container can remain running meanwhile changes are done to the website and published to the following folder through the standard VS publishing feature (as if the container was an IIS instance running locally). "C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\SimpleSample\\**storage\Website**“ @@ -43,7 +45,7 @@ Following the initial container run, the container can remain running meanwhile The following steps describes how to attach VS2017 to the IIS process where Sitecore is running within its container. -1. Make sure Sitecore is running by browising to its IP which can be obtained with either of the following procedures: +1. Make sure Sitecore is running by browsing to its IP which can be obtained with either of the following procedures: 1. Through VS2017 1. When VS2017 runs a docker project (it must be selected as StartUp project) the website container's IP is displayed in the "Output" panel ("Docker" output). There should be as below example: ```text @@ -58,7 +60,7 @@ The following steps describes how to attach VS2017 to the IIS process where Site ```text docker inspect --format="{{range .NetworkSettings.Networks}}{{.IPAddress}} {{end}}" ac58646e9013 ``` - * Finally the last line is the container's IP which also changes every time the container is run. + * Finally, the last line is the container's IP which also changes every time the container is run. 1. Through a console 1. Get the container's ID: ```text @@ -72,7 +74,7 @@ The following steps describes how to attach VS2017 to the IIS process where Site Notice in the table above the container named "**\*_website_1**", with image named "website:dev". This is the website container which IP is needed. 1. Make sure the container status is "Up" by checking the "STATUS" column. 1. Copy the container id value. - 4. Run the following command to the the container's IP. + 4. Run the following command to get the container's IP. ```text PS C:\> docker inspect --format="{{range .NetworkSettings.Networks}}{{.IPAddress}} {{end}}" ac58646e9013 172.22.99.92 @@ -81,7 +83,7 @@ The following steps describes how to attach VS2017 to the IIS process where Site ### Sitecore logs -Sitecore logs can be found in the follwing location: +Sitecore logs can be found in the following location: "C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\SimpleSample\\**storage\Data**“ ### Sitecore site files @@ -98,5 +100,3 @@ If the solution is switched to the "Release" configuration re-run, the container ## Known issues 1. Visual Studio fails when trying to attach just after starting debugging session. VS can attach to the running process in container afterwards, though. See section "Attaching VS2017 to Sitecore" for a workaround - - diff --git a/sitecore/9.0.1 rev. 171219 XM1/VS2017/TDSSample/README.md b/sitecore/9.0.1 rev. 171219 XM1/VS2017/TDSSample/README.md index 1a3321c..15dea64 100644 --- a/sitecore/9.0.1 rev. 171219 XM1/VS2017/TDSSample/README.md +++ b/sitecore/9.0.1 rev. 171219 XM1/VS2017/TDSSample/README.md @@ -1,4 +1,6 @@ -# docker-demo for Sitecore 9.0.1 rev. 171219 XM1 +#TDS Sample + +## Demo Introduction This demo showcases how to create a VS2017 project for Sitecore with the following features: @@ -9,43 +11,68 @@ This demo showcases how to create a VS2017 project for Sitecore with the followi 1. Website folder files, databases and Solr cores are automatically copied from the images to the Development environment (if missing) (same as databases). 1. Attach to IIS process in the container from VS2017 for debugging +# TDS Introduction + +TDS stand for [Team Development for Sitecore](https://www.teamdevelopmentforsitecore.com/). It is a suite of commercial products built and maintained by [Hedgehog](https://www.hhog.com/). + +To run this demo only one tool from the suite is necessary. Its name is [TDS Classic](https://www.teamdevelopmentforsitecore.com/TDS-Classic). + +This project shows how to do basic TDS Classic tasks with a Sitecore instance running in a container. + ## Prerequisites * Windows 10 Fall Creators Update * Docker for Windows * Visual Studio 2017 15.5 or later * Clone the [Sitecore base docker-images repository](https://github.com/Sitecore/docker-images) and build the images for the Sitecore version "9.0.1 rev. 171219 XM1 CM". +* TDS Classic needs to be installed, which requires a commercial license. It has been tested with TDS Classic version 5.7.0.13 although it may work with other versions. ## Development Environment Setup -1. Clone [this repository](https://github.com/Sitecore/docker-demo) into a folder such as “c:\Docker\Sitecore\docker-demo” (next steps will asume this folder has been used): +1. Clone [this repository](https://github.com/Sitecore/docker-demo) into a folder such as “c:\Docker\Sitecore\docker-demo” (next steps will assume this folder has been used): 1. Copy "**license.xml**" into "C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\TDSSample\\**storage\Data**“ 1. Open VS2017 as Administrator 1. Open the solution “C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\TDSSample\\**TDSSample.sln**” -1. Make sure the project “**docker-compose**” is set as StartUp project -1. Build the solution. The three projects in the solution should compile. +1. Copy the file “C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\TDSSample\src\Website\Properties\PublishProfiles\\**LocalDevContainer.pubxml.example**” as “**LocalDevContainer.pubxml**”, in the same folder. +1. From VS2017, edit the Publication settings for the project “Website”. Set the Target Location to “C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\TDSSample\\**storage\Website**” 1. Review the files "C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\TDSSample\\**Website\Dockerfile**" and "C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\TDSSample\\**Website\build.Dockerfile**" and update the `FROM` clause with the name used to build the base images. +1. Make sure the project “**docker-compose**” is set as StartUp project 1. Run the solution with “**Debug**” configuration ("F5"). - >The first time the containers run, the base images will detect that the required assets (databases, indexes and site files) are missing in their respected VOLUMEs (pointing to the development environment) and will take some time to create them. VS will build the containers and will try to attach to the IIS's process running in website's container, however it will fail (TODO: fix this known issue). In the meantime, the file transfer from the images to the Development environment will keep progresing. Please be patient. -1. Copy the website's container’s IP from the VS' "Output" panel (make sure it is the "Docker" output) and paste the IP on a browser's address bar. Please notice that Sitecore needs some time to warm-up, therefore the initial start may take a bit (up to 1-2 min). + >The first time the containers run, the base images will detect that the required assets (databases, indexes and site files) are missing in their respected VOLUMEs (pointing to the development environment) and will take some time to create them. VS will build the containers and will try to attach to the IIS's process running in website's container, however it will fail (TODO: fix this known issue). In the meantime, the file transfer from the images to the Development environment will keep progressing. Please be patient. +1. Copy the website's container’s IP from the VS' "Output" panel (make sure it is the "Docker" output) and paste the IP on a browser's address bar. Please notice that Sitecore needs some time to warm-up, therefore the initial start may take a bit (up to 5-6 min). 1. The browser will display the OOTB Sitecore’s home page. -1. Any change made to the following folder will be automatically detected by sitecore - "C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\TDSSample\\**storage\Website**“ ## Development Process -Sitecore supports multiple sites and also multiple URL for each site. It may be necessary to access the site with a specific URL (other than the IP). In these cases, it is necessary to update the development environment's host file every time the container is run (instantiated), which happens the first time VS runs the project. - -Following the initial container run, the container can remain running meanwhile changes are done to the website and published to the following folder through the standard VS publishing feature (as if the container was an IIS instance running locally). +Every time VS2017 is open, it must be run at least one to get containers run. After that initial run, the containers will remain up running meanwhile VS2017 is open, allowing us to make changes and published them to the following folder through the standard VS publishing feature (as if the container was an IIS instance running locally). "C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\TDSSample\\**storage\Website**“ +Every time the containers are run, they get a new internal IP which needs to be set in the development environment's "**host**" file to be able to access the site through a URL. For this example, we will use "**sitecore901.xm1.tds.dev.local**" + +## Deploy the TDS project + +1. With VS2017, edit the properties of the TDS project “**TDS.Website.master**”. + 1. Select tab “**Build**” + 1. Check the checkbox “Edit user specific configuration (.user file)” + 1. Set the following values in the text boxes: + 1. Sitecore Web Url: “http://sitecore901.xm1.tds.dev.local” + 1. Sitecore Deploy Folder: "C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\TDSSample\\**storage\Website**“ + 1. Check the checkbox “**Install Sitecore Connector**”. A guid should appear in the “Sitecore Access Guid” field + 1. Save the project. + 1. Click the “Test” button to confirm the connection works +1. Deploy the TDS project “**TDS.Website.master**” +1. Browse to “http://sitecore901.xm1.tds.dev.local/sitecore/shell” +1. Login with “admin” and “b” +1. With the “Content Editor” expand the item “/sitecore/content/Home” to see its children. There should be a child page deployed by the TDS project. + + ## Debugging Sitecore with VS2017 ### Attaching VS2017 to Sitecore The following steps describes how to attach VS2017 to the IIS process where Sitecore is running within its container. -1. Make sure Sitecore is running by browising to its IP which can be obtained with either of the following procedures: +1. Make sure Sitecore is running by browsing to its IP which can be obtained with either of the following procedures: 1. Through VS2017 1. When VS2017 runs a docker project (it must be selected as StartUp project) the website container's IP is displayed in the "Output" panel ("Docker" output). There should be as below example: ```text @@ -60,7 +87,7 @@ The following steps describes how to attach VS2017 to the IIS process where Site ```text docker inspect --format="{{range .NetworkSettings.Networks}}{{.IPAddress}} {{end}}" ac58646e9013 ``` - * Finally the last line is the container's IP which also changes every time the container is run. + * Finally, the last line is the container's IP which also changes every time the container is run. 1. Through a console 1. Get the container's ID: ```text @@ -74,16 +101,24 @@ The following steps describes how to attach VS2017 to the IIS process where Site Notice in the table above the container named "**\*_website_1**", with image named "website:dev". This is the website container which IP is needed. 1. Make sure the container status is "Up" by checking the "STATUS" column. 1. Copy the container id value. - 4. Run the following command to the the container's IP. + 4. Run the following command to get the container's IP. ```text PS C:\> docker inspect --format="{{range .NetworkSettings.Networks}}{{.IPAddress}} {{end}}" ac58646e9013 172.22.99.92 PS C:\> ``` +### Debugging Test + +1. Make sure the "**TDS.Website.master**" project has been configured and deployed as explained in previous section. +1. Browse to "http://sitecore901.xm1.tds.dev.local" and confirm that the Home page has a customisation that displays the container's Computer Name which is a code matching with the initial characters of the container's ID. This is a small customisation made for demo purposes. +1. With VS2017 open the file "c:\docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\TDSSample\src\Website\Processors\\**ExampleProcessor.cs**" and set an interruption point in the line 12 of the code. +1. Attach VS2017 to the IIS process running in the container as described in previous section. +1. Refresh the Home page in the browser. VS2017 should stop execution where the interruption point was set and allow the user to change execution by skipping one line, for instance. + ### Sitecore logs -Sitecore logs can be found in the follwing location: +Sitecore logs can be found in the following location: "C:\Docker\Sitecore\docker-demo\sitecore\9.0.1 rev. 171219 XM1\VS2017\TDSSample\\**storage\Data**“ ### Sitecore site files @@ -100,5 +135,3 @@ If the solution is switched to the "Release" configuration re-run, the container ## Known issues 1. Visual Studio fails when trying to attach just after starting debugging session. VS can attach to the running process in container afterwards, though. See section "Attaching VS2017 to Sitecore" for a workaround - -