From f0fd3f95f90d0ba283bb28d49830eef102f173ee Mon Sep 17 00:00:00 2001 From: John Shkolnik Date: Tue, 16 Jul 2019 09:22:06 -0400 Subject: [PATCH 1/3] "together" was misspelled. --- src/aggregator-cli/Instances/InstallInstanceCommand.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/aggregator-cli/Instances/InstallInstanceCommand.cs b/src/aggregator-cli/Instances/InstallInstanceCommand.cs index c1e223ab..5e4327f3 100644 --- a/src/aggregator-cli/Instances/InstallInstanceCommand.cs +++ b/src/aggregator-cli/Instances/InstallInstanceCommand.cs @@ -26,7 +26,7 @@ class InstallInstanceCommand : CommandBase [Option("sourceUrl", SetName="url", Required = false, HelpText = "URL of Aggregator Runtime.")] public string SourceUrl { get; set; } - /* next two should go toghether, no way to express this via CommandLine library */ + /* next two should go together, no way to express this via CommandLine library */ [Option('k', "hostingPlanSku", SetName = "plan", Required = false, Default = "Y1", HelpText = "Azure AppPlan SKU hosting the Aggregator instances .")] public string HostingPlanSku { get; set; } From 6547894570a16d4ed9c70098bb626968ebd91e21 Mon Sep 17 00:00:00 2001 From: John Shkolnik Date: Tue, 16 Jul 2019 10:17:13 -0400 Subject: [PATCH 2/3] Fast sweep through example grammar and clarity. --- doc/command-examples.md | 82 ++++++++++++++++++++++------------------- 1 file changed, 44 insertions(+), 38 deletions(-) diff --git a/doc/command-examples.md b/doc/command-examples.md index 64252d12..23991685 100644 --- a/doc/command-examples.md +++ b/doc/command-examples.md @@ -1,48 +1,52 @@ # Sample Aggregator CLI usage -In the following you will find many sample usage of Aggregator CLI commands. Run `aggregator-cli` or `dotnet aggregator-cli.dll` followed by the command and any option. -All commands accept the `--verbose` option to print additional messages, useful in troubleshooting. +All commands accept the `--verbose` option to print additional messages for troubleshooting. ### Logon -This is a required step, credentials are cached locally and expire after 2 hours. -``` +You are required to log into both Azure and ADO. The credentials are cached locally and expire after 2 hours. _(Replace the below asterisks `*` with valid values.)_ +```Batchfile logon.azure --subscription ************ --client ************ --password *********** --tenant ************ -logon.ado --url https://dev.azure.com/youraccount --mode PAT --token ***************************************q +logon.ado --url https://dev.azure.com/youraccount --mode PAT --token *************************************** ``` -Clearly you have to use valid values instead of asterisks (`*`). ### Create an Azure Function Application -You need an Azure Function Application plus the Aggregator runtime to execute the Rules. -These commands will do everything for you. -``` +You need an Azure Function Application plus the Aggregator runtime to execute rules. Both are created by a single call to `install.instance`. + +Create a new instance -- and a new resource group -- in the West Europe region. +```Batchfile install.instance --verbose --name my1 --location westeurope +``` + +Create a new instance -- and a new resource group named myRG1 -- in the West Europe region. +```Batchfile install.instance --name my3 --resourceGroup myRG1 --location westeurope --requiredVersion latest ``` -Remember that the Instance name must be unique in Azure (CLI automatically append `aggregator` suffix to minimize the chance of a clash). -You can specify the version of Aggregator Runtime using the `requiredVersion` option. -Look in https://github.com/tfsaggregator/aggregator-cli/releases for valid version numbers. + +- The Aggregator instance name must be unique in Azure (CLI automatically appends `aggregator` suffix to minimize the chance of a clash). +- You can specify the version of Aggregator Runtime using the `requiredVersion` option. Look in [our releases](https://github.com/tfsaggregator/aggregator-cli/releases) for valid version numbers. +- You can use the [Azure CLI](https://github.com/Azure/azure-cli) to get a list of regions: `az account list-locations -o table` ### Search Aggregator instances That is Azure Functions previously created via the CLI. -This command searches in the entire Azure subscription defined at logon. -``` +Search the entire Azure subscription (previously connected to via logon.azure): +```Batchfile list.instances ``` -To scope search in an Azure Resource Group use -``` +Scope search to a particular resource group: +```Batchfile list.instances --resourceGroup myRG1 ``` ### Add Azure Functions (i.e. Aggregator Rules) to an existing Azure Function Application (i.e. an Aggregator Instance) Creates two rules -``` +```Batchfile add.rule --verbose --instance my1 --name test1 --file test\test1.rule add.rule --verbose --instance my1 --name test2 --file test\test2.rule list.rules --verbose --instance my1 @@ -50,29 +54,28 @@ list.rules --verbose --instance my1 `list.rules` shows which Rules (i.e. Azure Function) are deployed in an Instance (i.e. Azure Function Application). Creates an Aggregator Rule in specified App and Resource Group -``` +```Batchfile add.rule --verbose --instance my3 --resourceGroup myRG1 --name test3 --file test\test3.rule ``` -### Adds two Service Hook to Azure DevOps, each invoking a different rule +### Adds two service hooks to Azure DevOps, each invoking a different rule This is the last step: gluing Azure DevOps to the Rule hosted in Azure Functions -``` +```Batchfile map.rule --verbose --project SampleProject --event workitem.created --instance my1 --rule test1 map.rule --verbose --project SampleProject --event workitem.updated --instance my1 --rule test2 map.rule --verbose --project SampleProject --event workitem.created --instance my3 --resourceGroup myRG1 --rule test3 ``` -Currently only these events are supported:
+The same rule can be triggered by multiple events from different Azure DevOps projects. Currently only these events are supported:
`workitem.created`
`workitem.updated`
`workitem.deleted`
`workitem.restored`
`workitem.commented`
-The same rule can be triggered by multiple Events from different Azure DevOps Projects. List the mappings with various filter options. -``` +```Batchfile list.mappings --verbose --instance my1 list.mappings --verbose --project SampleProject list.mappings --instance my1 --project SampleProject @@ -80,8 +83,8 @@ list.mappings --instance my1 --project SampleProject ### Disable and enable rules -Disabling a broken rule leaves any Mappings in place. -``` +Disabling a broken rule leaves any mappings in place. +```Batchfile configure.rule --verbose --instance my1 --name test1 --disable configure.rule --verbose --instance my1 --name test1 --enable ``` @@ -90,7 +93,7 @@ configure.rule --verbose --instance my1 --name test1 --enable ### Update the code and runtime of a rule This command updates the code and potentially the Aggregator runtime -``` +```Batchfile update.rule --verbose --instance my1 --name test1 --file test1.rule --requiredVersion 0.4.0 update.rule --verbose --instance my3 --resourceGroup myRG1 --name test3 --file test\test3.rule ``` @@ -100,7 +103,7 @@ You can fix the Aggregator runtime using the `requiredVersion` option. ### Updates the Azure DevOps credential stored in Azure Function The Azure Function configuration saves the credential to connect back to Azure DevOps. -``` +```Batchfile configure.instance --name my1 --location westeurope --authentication configure.instance --name my3 --resourceGroup myRG1 --location westeurope --authentication ``` @@ -110,7 +113,7 @@ Note that a Personal Access Token (PAT) has a limited duration and must be perio ### Remove a Service Hook from Azure DevOps Run these command, Azure DevOps stops sending the notification to the Rule. -``` +```Batchfile unmap.rule --verbose --event workitem.created --instance my1 --rule test1 unmap.rule --verbose --event workitem.updated --project SampleProject --instance my1 --rule test2 unmap.rule --verbose --project SampleProject --event workitem.created --instance my3 --resourceGroup myRG1 --rule test3 @@ -119,22 +122,25 @@ The first example removes all subscriptions sending `workitem.created` notificat Note the options to filter for a specific Azure DevOps project. -### Deletes an Azure Function -It also removes all Service Hooks referring to the Rule. - -``` +### Delete Azure Function (Rule) +Delete rule and remove all service hooks referring to it. +```Batchfile remove.rule --verbose --instance my1 --name test1 -remove.rule --verbose --instance my3 --resourceGroup myRG1 --name test3 ``` -The `dont-remove-mappings` delete the Azure Function Application leaving the Service Hooks in place +Delete rule from a specific resource group and remove all service hooks referring to it. +```Batchfile +remove.rule --verbose --instance my3 --resourceGroup myRG1 --name test3 ``` + +Delete rule but leave the service hooks in place. +```Batchfile uninstall.instance --name my1 --location westeurope --dont-remove-mappings ``` ### Delete the Azure Function Application and any Service Hooks referring to it -Deletes the Instance and all the Rules in it. +Delete entire Aggregator instance and all its rules. ``` uninstall.instance --verbose --name my3 --resourceGroup myRG1 --location westeurope ``` @@ -142,7 +148,7 @@ uninstall.instance --verbose --name my3 --resourceGroup myRG1 --location westeur ### Stream It connects for 30 minutes to the Azure Application and prints the logging messages. -``` +```Batchfile stream.logs --instance my7 --resourceGroup test-aggregator7 --verbose ``` You can stop the program using `Ctrl+C` keystroke or closing the command window. @@ -150,12 +156,12 @@ You can stop the program using `Ctrl+C` keystroke or closing the command window. ### Trigger rules by faking the Azure DevOps event Runs a rule code locally, no change is sent to Azure DevOps -``` +```Batchfile invoke.rule --dryrun --project SampleProject --event workitem.created --workItemId 14 --local --source test\test2.rule ``` Runs existing rule in Azure, no change is sent to Azure DevOps thanks to the `dryrun` option -``` +```Batchfile invoke.rule --instance my7 --resourceGroup test-aggregator7 --name r1 --event workitem.created --account giuliovaad --project WorkItemTracking --workItemId 14 --verbose --dryrun ``` If you want to see the log messages, run a `stream.logs` command in another window. From 9295eeb7b80d48cc511fc1d345e605fb02505f83 Mon Sep 17 00:00:00 2001 From: John Shkolnik Date: Tue, 16 Jul 2019 17:08:42 -0400 Subject: [PATCH 3/3] Amend comment to re-use existing group. --- doc/command-examples.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/command-examples.md b/doc/command-examples.md index 23991685..37df396e 100644 --- a/doc/command-examples.md +++ b/doc/command-examples.md @@ -20,7 +20,7 @@ Create a new instance -- and a new resource group -- in the West Europe region. install.instance --verbose --name my1 --location westeurope ``` -Create a new instance -- and a new resource group named myRG1 -- in the West Europe region. +Create a new instance -- and a new resource group named myRG1 or re-use existing -- in the West Europe region. ```Batchfile install.instance --name my3 --resourceGroup myRG1 --location westeurope --requiredVersion latest ``` @@ -45,7 +45,7 @@ list.instances --resourceGroup myRG1 ### Add Azure Functions (i.e. Aggregator Rules) to an existing Azure Function Application (i.e. an Aggregator Instance) -Creates two rules +Creates two rules where the file parameter is a local file relative to the working directory. ```Batchfile add.rule --verbose --instance my1 --name test1 --file test\test1.rule add.rule --verbose --instance my1 --name test2 --file test\test2.rule