From 6cdf8dd1af3a6b2f93ebfc830d4872db4fb1a366 Mon Sep 17 00:00:00 2001 From: Tyler Whitney Date: Fri, 6 Jul 2018 17:57:08 -0700 Subject: [PATCH] fine tuning and bring quickstart changes into tutorial --- ...vice-fabric-mesh-quickstart-dotnet-core.md | 25 +++++++---- ...-fabric-mesh-tutorial-create-dotnetcore.md | 44 ++++++++++--------- ...-tutorial-debug-service-fabric-mesh-app.md | 14 +++--- ...tutorial-deploy-service-fabric-mesh-app.md | 29 ++++++++---- 4 files changed, 68 insertions(+), 44 deletions(-) diff --git a/docs/preview-docs/service-fabric-mesh-quickstart-dotnet-core.md b/docs/preview-docs/service-fabric-mesh-quickstart-dotnet-core.md index 2b838b9..e50b02b 100644 --- a/docs/preview-docs/service-fabric-mesh-quickstart-dotnet-core.md +++ b/docs/preview-docs/service-fabric-mesh-quickstart-dotnet-core.md @@ -12,7 +12,7 @@ ms.devlang: dotNet ms.topic: conceptual ms.tgt_pltfrm: NA ms.workload: NA -ms.date: 06/12/2018 +ms.date: 07/6/2018 ms.author: twhitney ms.custom: mvc, devcenter #Customer intent: As a developer, I want to use visual studio to locally run an ASP.NET Core website on Service Fabric Mesh so that I can see it run. @@ -32,7 +32,7 @@ You'll need an Azure subscription. If you don't have one, you can easily create Open Visual Studio and select **File** > **New** > **Project...** -In the **New Project** dialog, type **mesh** into the **Search** box at the top. Select the **Service Fabric Mesh Application** template. +In the **New Project** dialog **Search** box at the top, type `mesh`. Select the **Service Fabric Mesh Application** template. (If you don't see the template, make sure that you installed the Mesh SDK and the VS tools preview as described in [set up your development environment](service-fabric-mesh-setup-developer-environment-sdk.md). In the **Name** box, type **ServiceFabricMesh1** and in the **Location** box, set the folder path of where the files for the project will be stored. @@ -42,11 +42,7 @@ Make sure that **Create directory for solution** is checked, and click **OK** to ### Create a service -After you click **OK**, the **New Service Fabric Service** dialog appears. Select the **ASP.NET Core** project type, make sure **Container OS** is set to **Windows**. - -You must set the **Service Name** to something unique because the name of the service is used as the repository name of the Docker image. If you have an existing Docker image with the same repository name, it will be overwritten by Visual Studio. Open a terminal and use the Docker command `docker images` to make sure your project name isn't already being used. - -Press **OK** to create the ASP.NET Core project. +After you click **OK**, the **New Service Fabric Service** dialog appears. Select the **ASP.NET Core** project type, make sure **Container OS** is set to **Windows** and press **OK** to create the ASP.NET Core project. ![Visual studio new Service Fabric Mesh project dialog](media/service-fabric-mesh-quickstart-dotnet-core/visual-studio-new-service-fabric-service.png) @@ -80,7 +76,20 @@ Under **Resource group**, select **\**. A dialog a ![Visual studio Service Fabric Mesh new resource group dialog](media/service-fabric-mesh-quickstart-dotnet-core/visual-studio-publish-new-resource-group-dialog.png) -Back in the **Publish Service Fabric Application** dialog, under **Azure Container Registry**, select **\**. In the **Create Container Registry** dialog, use a unique name for the **Container registry name**. For **Location**, pick **East US**. Select the **sfmeshTutorial1RG** resource group (the group you created above). Set the **SKU** to **Basic** and then press **Create** to return to the publish dialog. +Back in the **Publish Service Fabric Application** dialog, under **Azure Container Registry**, select **\**. In the **Create Container Registry** dialog, use a unique name for the **Container registry name**. Specify a **Location** (this tutorial uses **East US**). Select the **Resource group** that you created in the previous step in the drop-down, e.g. **sfmeshTutorial1RG**. Set the **SKU** to **Basic** and then press **Create** to return to the publish dialog. + +If you get an error that a resource provider has not been registered for your subscription, you can register it. First see if the resource provider is available for your subscription: + +```Powershell +Get-AzureRmResourceProvider -ListAvailable +``` + +If the container registry provider (`Microsoft.ContainerRegistry`) is available, register it from Powershell: + +```Powershell +Connect-AzureRmAccount +Register-AzureRmResourceProvider -ProviderNamespace Microsoft.ContainerRegistry +``` ![Visual studio Service Fabric Mesh new resource group dialog](media/service-fabric-mesh-quickstart-dotnet-core/visual-studio-publish-new-container-registry-dialog.png) diff --git a/docs/preview-docs/service-fabric-mesh-tutorial-create-dotnetcore.md b/docs/preview-docs/service-fabric-mesh-tutorial-create-dotnetcore.md index 9a41918..2c45ef8 100644 --- a/docs/preview-docs/service-fabric-mesh-tutorial-create-dotnetcore.md +++ b/docs/preview-docs/service-fabric-mesh-tutorial-create-dotnetcore.md @@ -12,7 +12,7 @@ ms.devlang: dotNet ms.topic: tutorial ms.tgt_pltfrm: NA ms.workload: NA -ms.date: 06/27/2018 +ms.date: 07/6/2018 ms.author: twhitney ms.custom: mvc, devcenter #Customer intent: As a developer, I want learn how to create a Service Fabric Mesh app that communicates with another service, and then publish it to Azure. @@ -22,7 +22,7 @@ ms.custom: mvc, devcenter This tutorial is part one of a series. You'll learn how to create an Azure Service Fabric app that has an ASP.NET web front end and an ASP.NET Core Web API back-end service. Then you'll debug the app on your local development cluster and publish the app to Azure. When you're finished, you'll have a simple to-do app that demonstrates a service-to-service call in a Service Fabric application running in Service Fabric Mesh. -If you don't want to manually create the to-do app, you can [download the source code](https://github.com/azure-samples/service-fabric-mesh) for the completed application (under the basicservicefabricmeshapp directory) and skip ahead to [Debug the app locally](service-fabric-mesh-tutorial-debug-service-fabric-mesh-app.md). +If you don't want to manually create the to-do app, you can [download the source code](https://github.com/azure-samples/service-fabric-mesh) for the completed application and skip ahead to [Debug the app locally](service-fabric-mesh-tutorial-debug-service-fabric-mesh-app.md). In part one of the series, you learn how to: @@ -54,23 +54,25 @@ Before you begin this tutorial: Run Visual Studio and select **File** > **New** > **Project...** -In the **New Project** dialog, type **mesh** into the **Search** box at the top. Select the **Service Fabric Mesh Application** template. (If you don't see the template, make sure that you installed the Mesh SDK and the VS tools preview as described in [set up your development environment](service-fabric-mesh-setup-developer-environment-sdk.md). +In the **New Project** dialog **Search** box at the top, type `mesh`. Select the **Service Fabric Mesh Application** template. (If you don't see the template, make sure that you installed the Mesh SDK and the VS tools preview as described in [set up your development environment](service-fabric-mesh-setup-developer-environment-sdk.md). -In the **Name** box, type **ServiceFabricMeshApp** and in the **Location** box, set the folder path to where the files for the project will be stored. +In the **Name** box, type `ServiceFabricMeshApp` and in the **Location** box, set the folder path to where you want to store the files for the project. -Make sure that **Create directory for solution** is checked, and click **OK** to create the Service Fabric Mesh project. Next you'll see the **New Service Fabric Service** dialog. +Make sure that **Create directory for solution** is checked, and click **OK** to create the Service Fabric Mesh project. ![Visual studio new Service Fabric Mesh project dialog](./media/service-fabric-mesh-tutorial-deploy-dotnetcore/visual-studio-new-project.png) +Next you'll see the **New Service Fabric Service** dialog. + ### Create the web front-end service In the **New Service Fabric Service** dialog, select the **ASP.NET Core** project type, make sure **Container OS** is set to **Windows**. -Set the **Service Name** to **WebFrontEnd**. Press **OK** to create the ASP.NET Core service. Next you'll see the **New ASP.NET Core Web Application** dialog. +Set the **Service Name** to **WebFrontEnd**. Press **OK** to create the ASP.NET Core service. ![Visual studio new Service Fabric Mesh project dialog](./media/service-fabric-mesh-tutorial-deploy-dotnetcore/visual-studio-new-service-fabric-service.png) -In the **New ASP.NET Core Web Application** dialog, select **Web Application** and then click **OK**. +Next you'll see the **New ASP.NET Core Web Application** dialog. In the **New ASP.NET Core Web Application** dialog, select **Web Application** and then click **OK**. ![Visual studio new ASP.NET core application](./media/service-fabric-mesh-tutorial-deploy-dotnetcore/visual-studio-new-aspnetcore-app.png) @@ -80,11 +82,11 @@ Now you have a Service Fabric Application. Next, create the model for to-do info For simplicity, the to-do items are stored in a list in memory. Create a class library for the to-do items and a list to hold them. In Visual Studio, which currently has the **ServiceFabricMeshApp** loaded, select **File** > **Add** > **New Project**. -In the **New Project** dialog, type **C# .net core class** into the **Search** box at the top. Select the **Class Library (.NET Core)** template. +In the **New Project** dialog **Search** box at the top, type `C# .net core class`. Select the **Class Library (.NET Core)** template. -In the **Name** box, type **Model**. Click **OK** to create the class library. +In the **Name** box, type `Model`. Click **OK** to create the class library. -In the Solution explorer, under **Model**, right-click **Class1.cs** and choose **Rename**. Rename the class **ToDoItem.cs**. A prompt will appear asking whether to rename all references to `Class1`. Click **Yes**. +In the Solution explorer, under **Model**, right-click **Class1.cs** and choose **Rename**. Rename the class **ToDoItem.cs**. If a prompt appears asking whether to rename all references, click **Yes**. Replace the contents of the empty `class ToDoItem` with: @@ -116,7 +118,7 @@ public class ToDoItem This class represents individual to-do items. -Create a list to hold the to-do items. In Visual Studio, right-click the **Model** class library, and select **Add** > **Class...** The **Add New Item** dialog will appear. Set the **Name** to **ToDoList.cs** and click **Add**. +In Visual Studio, right-click the **Model** class library, and select **Add** > **Class...** to create a list to hold the to-do items. The **Add New Item** dialog will appear. Set the **Name** to `ToDoList.cs` and click **Add**. In **ToDoList.cs**, replace the empty `class ToDoList` with: @@ -170,7 +172,7 @@ public class ToDoList } ``` -Next, create the service fabric service (a Web API project) that will track the to-do items. +Next, create the service fabric service that will track the to-do items. ## Create the back-end service @@ -182,7 +184,7 @@ Set the **Service Name** to **ToDoService**. Click **OK** to create the ASP.NET ![Visual studio new ASP.NET core application](./media/service-fabric-mesh-tutorial-deploy-dotnetcore/visual-studio-new-webapi.png) -Because the back-end service doesn't provide any UI, turn off launching the browser when the service is launched. In the **Solution Explorer**, right-click **ToDoService**, and select **Properties**. In the properties window that appears, select the **Debug** tab on the left, and uncheck **Launch browser**. Press Ctrl+S to save the change. +Because the back-end service doesn't provide any UI, turn off launching the browser when the service is launched. In the **Solution Explorer**, right-click **ToDoService**, and select **Properties**. In the properties window that appears, select the **Debug** tab on the left, and uncheck **Launch browser**. Press **Ctrl+S** to save the change. Because this service maintains the to-do information, add a reference to the Model class library. In the Solution Explorer, right-click **ToDoService** and then select **Add** > **Reference...**. The **Reference Manager** dialog will appear. @@ -195,7 +197,7 @@ ASP.Net Web API projects use the model view controller (MVC) pattern. Next creat To add the data context class, in the solution explorer right-click **ToDoService** and then **Add** > **Class**. In the **Add New Item** dialog that appears, make sure that **Class** is selected, and set the **Name** to `Datacontext.cs`, and click **Add**. -In **Datacontext.cs**, replace the contents of the empty 'class DataContext' with: +In **Datacontext.cs**, replace the contents of the empty `class DataContext` with: ```csharp public static class DataContext @@ -215,13 +217,13 @@ public static class DataContext } ``` -The minimal data context populates some sample to-do items and provides access to them. +This minimal data context populates some sample to-do items and provides access to them. ### Add a controller Also part of the MVC pattern is a controller that handles the HTTP requests and creates the HTTP response. A default controller was provided by the template when the **ToDoService** project was created. In the **Solution Explorer**, under **ToDoService**, open the **Controllers** folder to see the **ValuesController.cs** file. -Right-click **ValuesController.cs** and then **Rename**. Rename the file to `ToDoController.cs`. A prompt to rename all references will appear, click **Yes**. +Right-click **ValuesController.cs** and then **Rename**. Rename the file to `ToDoController.cs`. If a prompt appears to rename all references, click **Yes**. Open the **ToDoController.cs** file and replace the contents of `class ToDoController` with: @@ -263,7 +265,7 @@ public class ToDoController : Controller } ``` -This tutorial does not implement add, delete, and so on. The focus is on communicating with another service. +This tutorial does not implement add, delete, and so on to keep the focus on communicating with another service. ## Create the web page that displays to-do items @@ -335,7 +337,7 @@ public class IndexModel : PageModel ### Create environment variables -The URL for the back-end service is required to communicate with that service. For the purpose of this tutorial, the following code (defined above as part of the IndexModel) reads environment variables to compose the URL: +The URL for the back-end service is required to communicate with that service. For the purpose of this tutorial, the following code excerpt (which is defined above as part of the IndexModel) reads environment variables to compose the URL: ```csharp private static string backendDNSName = $"{Environment.GetEnvironmentVariable("ServiceName")}.{Environment.GetEnvironmentVariable("AppName")}"; @@ -350,12 +352,12 @@ The URL is composed of the application name, the service name, and the port. All * The service name, `ToDoService`, is found under `services:` after `name:` See (2) in the figure above. * The port, `20006`, is found under `endpoints:` after `port:` See (3) in the figure above. -With the app name, service name, and port number, environment variables can be defined that the app will use to communicate with the back-end service. In **Solution Explorer**, navigate to **WebFrontEnd** > **Service Resources** > **service.yaml** to define the variables that specify the back-end service address. +Next, environment variables representing the app name, service name, and port number will be defined in the WebFrontEnd project to enable it to call the back-end service. In **Solution Explorer**, navigate to **WebFrontEnd** > **Service Resources** > **service.yaml** to define the variables that specify the back-end service address. -In the service.yaml file, add the following variables under `environmentVariables`. +In the service.yaml file, add the following variables under `environmentVariables`. The spacing is very particular so line up using the same spacing used by the other variables under `environmentVariables:` > [!IMPORTANT] -> Spaces, not tabs, must be used to indent the variables in the service.yaml file or it won't compile. Visual Studio may insert tabs as you create new lines. Replace all tabs with spaces. You'll see errors in the Error List when you compile but the app will still run--although it won't work until you convert the tabs to spaces. To ensure that no tabs are in the service.yaml file, make whitespace visible in the Visual Studio editor with **Edit** > **Advanced** > **View White Space**. +> Spaces, not tabs, must be used to indent the variables in the service.yaml file or it won't compile. Visual Studio may insert tabs as you create the environment variables. Replace all tabs with spaces. Although you'll see errors in the **build** debug output, the app will still launch. It won't work, however, until you convert the tabs to spaces. To ensure that no tabs are in the service.yaml file, you can make whitespace visible in the Visual Studio editor with **Edit** > **Advanced** > **View White Space**. ``` xml - name: AppName diff --git a/docs/preview-docs/service-fabric-mesh-tutorial-debug-service-fabric-mesh-app.md b/docs/preview-docs/service-fabric-mesh-tutorial-debug-service-fabric-mesh-app.md index eeb491c..c01b035 100644 --- a/docs/preview-docs/service-fabric-mesh-tutorial-debug-service-fabric-mesh-app.md +++ b/docs/preview-docs/service-fabric-mesh-tutorial-debug-service-fabric-mesh-app.md @@ -12,7 +12,7 @@ ms.devlang: dotNet ms.topic: tutorial ms.tgt_pltfrm: NA ms.workload: NA -ms.date: 06/27/2018 +ms.date: 07/6/2018 ms.author: twhitney ms.custom: mvc, devcenter #Customer intent: As a developer, I want learn how to debug a Service Fabric Mesh app that communicates with another service. @@ -52,7 +52,7 @@ If you did not create the to-do sample application in [part one of this tutorial git clone https://github.com/azure-samples/service-fabric-mesh ``` -The application is under the basicservicefabricmeshapp directory. +The application is under the `basicservicefabricmeshapp` directory. ## Build and debug on your local cluster @@ -70,18 +70,18 @@ After the local deployment is finished, and Visual Studio is running your app, a **Debugging tips** -* If you get error that "No Service Fabric local cluster is running", make sure that the Service Local Custer Manager (SLCM) is running. Right-click the SLCM icon in the task bar, and click **Start Local Cluster**. Once it has started, return to Visual Studio and press **F5**. -* If you get a 404 when the app starts, it probably means that your environment variables in **service.yaml** are incorrect. Make sure that `AppName`, `ApiHostPort` and `ServiceName` are set correctly per the instructions in [Set environment variables](#set-environment-variables). -* If you get a build error in **service.yaml**, make sure that you used spaces and not tabs when you added the environment variables. +* If you get the **No Service Fabric local cluster is running** error, make sure that the Service Local Custer Manager (SLCM) is running and right-click the SLCM icon in the task bar, then click **Start Local Cluster**. Once it has started, return to Visual Studio and press **F5**. +* If you get a **404** error when the app starts, it probably means that your environment variables in **service.yaml** are incorrect. Make sure that `AppName`, `ApiHostPort` and `ServiceName` are set correctly per the instructions in [Set environment variables](#set-environment-variables). +* If you get build errors in **service.yaml**, make sure that spaces, not tabs, are used to indent the lines. ### Debug in Visual Studio When you debug a Service Fabric application in Visual Studio, you are using a local Service Fabric development cluster. To see how to-do items are retrieved from the back-end service, debug into the OnGet() method. 1. In the **WebFrontEnd** project, open **Pages** > **Index.cshtml** > **Index.cshtml.cs** and set a breakpoint in the **Get** method (line 17). -2. In the **ToDoService** project, open **TodoController.cs** and set a breakpoint in the **Get** method (line 16). +2. In the **ToDoService** project, open **TodoController.cs** and set a breakpoint in the **OnGet** method (line 15). 3. Go back to the browser and refresh the page. You hit the breakpoint in the web front end `OnGet()` method. You can inspect the `backendUrl` variable to see how the environment variables that you defined in the **service.yaml** file are combined into the URL used to contact the back-end service. 4. Step over (F10) the `client.GetAsync(backendUrl).GetAwaiter().GetResult())` call and you'll hit the controller's `Get()` breakpoint. In this method, you can see how the list of to-do items is retrieved from the in-memory list. -5. When you are done looking around, you can stop debugging your project in Visual Studio by pressing **Shift+F5**. +5. When you are done, stop debugging your project in Visual Studio by pressing **Shift+F5**. ## Next steps diff --git a/docs/preview-docs/service-fabric-mesh-tutorial-deploy-service-fabric-mesh-app.md b/docs/preview-docs/service-fabric-mesh-tutorial-deploy-service-fabric-mesh-app.md index 503f1b8..32ae63a 100644 --- a/docs/preview-docs/service-fabric-mesh-tutorial-deploy-service-fabric-mesh-app.md +++ b/docs/preview-docs/service-fabric-mesh-tutorial-deploy-service-fabric-mesh-app.md @@ -12,7 +12,7 @@ ms.devlang: dotNet ms.topic: tutorial ms.tgt_pltfrm: NA ms.workload: NA -ms.date: 06/27/2018 +ms.date: 07/6/2018 ms.author: twhitney ms.custom: mvc, devcenter #Customer intent: As a developer, I want learn how to publish a Service Fabric Mesh app to Azure. @@ -54,11 +54,11 @@ If you did not build the to-do sample application in [part two of this tutorial git clone https://github.com/azure-samples/service-fabric-mesh ``` -The application is under the basicservicefabricmeshapp directory. +The application is under the `basicservicefabricmeshapp` directory. ## Publish to Azure -To publish your Service Fabric Mesh project to Azure, right-click on **ServiceFabricMeshApp** in Visual studio and select **Publish...** +To publish your Service Fabric Mesh project to Azure, right-click on **ServiceFabricMeshApp** in Visual Studio and select **Publish...** Next, you'll see a **Publish Service Fabric Application** dialog. @@ -66,17 +66,30 @@ Next, you'll see a **Publish Service Fabric Application** dialog. Select your Azure account and subscription. Choose a **Location**. This article uses **East US**. -Under **Resource group**, select **\**. This results in a dialog where you'll create a new resource group. Choose the **East US** location and name the group **sfmeshTutorial1RG**. Press **Create** to create the resource group and return to the publish dialog. +Under **Resource group**, select **\**. A dialog appears where you will create a new resource group. This article uses the **East US** location and names the group **sfmeshTutorial1RG** (if your organization has multiple people using the same subscription, choose a unique group name). Press **Create** to create the resource group and return to the publish dialog. ![Visual studio Service Fabric Mesh new resource group dialog](./media/service-fabric-mesh-tutorial-deploy-dotnetcore/visual-studio-publish-new-resource-group-dialog.png) -Back in the **Publish Service Fabric Application** dialog, under **Azure Container Registry**, select **\**. In the **Create Container Registry** dialog, use a unique name for the **Container registry name**. For **Location**, pick **East US**. Select the **sfmeshTutorial1RG** resource group. Set the **SKU** to **Basic** and then press **Create** to return to the publish dialog. +Back in the **Publish Service Fabric Application** dialog, under **Azure Container Registry**, select **\**. In the **Create Container Registry** dialog, use a unique name for the **Container registry name**. Specify a **Location** (this tutorial uses **East US**). Select the **Resource group** that you created in the previous step in the drop-down, e.g. **sfmeshTutorial1RG**. Set the **SKU** to **Basic** and then press **Create** to return to the publish dialog. ![Visual studio Service Fabric Mesh new resource group dialog](./media/service-fabric-mesh-tutorial-deploy-dotnetcore/visual-studio-publish-new-container-registry-dialog.png) +If you get an error that a resource provider has not been registered for your subscription, you can register it. First see if the resource provider is available for your subscription: + +```Powershell +Get-AzureRmResourceProvider -ListAvailable +``` + +If the container registry provider (`Microsoft.ContainerRegistry`) is available, register it from Powershell: + +```Powershell +Connect-AzureRmAccount +Register-AzureRmResourceProvider -ProviderNamespace Microsoft.ContainerRegistry +``` + In the publish dialog, press the **Publish** button to deploy your Service Fabric application to Azure. -When you publish to Azure for the first time, it can take up to 10 or more minutes. Subsequent publishes of the same project generally take around five minutes. Obviously, these estimates will vary based on your internet connection speed and other factors. You can monitor the progress of the deployment by selecting the **Service Fabric Tools** pane in the Visual Studio **Output** window. Once the deployment has finished, the **Service Fabric Tools** output will display the app's IP address and port in the form of a URL. +When you publish to Azure for the first time, the docker image is pushed to the Azure Container Registry (ACR) which takes time depending on the size of the image. Subsequent publishes of the same project will be faster. You can monitor the progress of the deployment by selecting the **Service Fabric Tools** pane in the Visual Studio **Output** window. Once the deployment has finished, the **Service Fabric Tools** output will display the IP address and port of your application in the form of a URL. ```json Packaging Application... @@ -96,7 +109,7 @@ You can use the Azure Cloud Shell or a local installation of the Azure CLI for t If you choose to install and use the CLI locally, this tutorial requires that you're running the Azure CLI version 2.0.35 or later. Run `az --version` to find the version. To install or upgrade to the latest version of the CLI, see [Install Azure CLI 2.0][azure-cli-install]. ## Install the az mesh cli -At the cli prompt +At the CLI prompt 1) Remove any previous install of the Azure Service Fabric Mesh CLI module. @@ -138,7 +151,7 @@ az mesh code-package-log get --resource-group $rg --application-name ServiceMesh ## Clean up resources -When no longer needed, delete all of the resources you created. Since you created a new resource group to host both the ACR and Service Fabric Mesh service resources, you can safely delete this resource group. +When no longer needed, delete all of the resources you created. Since you created a new resource group to host both the ACR and Service Fabric Mesh service resources, you can safely delete this resource group which will delete all of the associated resources. ```azurecli az group delete --resource-group sfmeshTutorial1RG