Documentation

ans-bar-bm · May 5, 2024 · de21afd · de21afd
1 parent d02eb35
commit de21afd
Show file tree

Hide file tree

Showing 5 changed files with 100 additions and 35 deletions.
diff --git a/.assets/AL-Go_settings.png b/.assets/AL-Go_settings.png
diff --git a/.assets/CommandLine.md b/.assets/CommandLine.md
@@ -0,0 +1,18 @@
+# Command Line
+
+The LinterCop can be referenced as a code analyser on executing the Business Central AL Compiler from the command line.
+
+## AL Compiler
+
+Download the `BusinessCentral.LinterCop.AL-14.0.983287.dll` from the [releases](https://github.com/StefanMaron/BusinessCentral.LinterCop/releases) and place it into your AL Language extension folder. For Example `%userprofile%\.vscode\extensions\ms-dynamics-smb.al-14.0.983287\bin\`
+
+Run the AL Compiler `. %userprofile%\.vscode\extensions\ms-dynamics-smb.al-14.0.983287\bin\alc.exe /project:"<PathToYourAlProject>" /packagecachepath:"<PathToYour.alpackages>" /analyzer:"userprofile%\.vscode\extensions\ms-dynamics-smb.al-14.0.983287\bin\usinessCentral.LinterCop.AL-14.0.983287.dll"`
+
+**Note:** It's important to match the specific AL version of the LinterCop.dll with the exact same version of the AL Compiler.
+
+
+## BcContainerHelper
+
+For manual compile you can use the `Compile-AppInBcContainer` command and pass the path or url to the `BusinessCentral.LinterCop.dll` in via the parameter `-CustomCodeCops`. For example `-CustomCodeCops "https://github.com/StefanMaron/BusinessCentral.LinterCop/releases/latest/download/BusinessCentral.LinterCop.dll"`.
+
+If passing the `BusinessCentral.LinterCop.dll` as path instead of a url, be aware that the file needs to be placed in a folder shared with the container. Further note that you should have BcContainerHelper version 6.0.16 (or newer) installed.
diff --git a/.assets/DevOps.md b/.assets/DevOps.md
@@ -0,0 +1,42 @@
+# DevOps
+
+Integrating additional Code Cops, like the LinterCop, in your DevOps workflow will improve the maintainability and transparency of the AL code.
+
+Automate tedious manual checks during pull requestlike checking for coding conventions and identifying possible run-time errors.
+
+
+## AL-Go for GitHub
+
+[AL-Go! for GitHub](https://github.com/microsoft/AL-Go) is a plug-and-play DevOps solution for Business Central app development on GitHub.
+
+Built-in support for custom Code Cops is available out-of-the-box, allowing for easy configuration of the LinterCop.
+
+![AL-Go settings](/.assets/AL-Go_settings.png)  
+https://github.com/microsoft/AL-Go/blob/main/Scenarios/settings.md#advanced-settings
+
+In the [settings.json](https://github.com/microsoft/AL-Go/blob/main/Scenarios/settings.md)  you can specify the url to dll file of the LinterCop, where you also need to enable downloading the latest VSIX.
+
+```json
+{
+  "vsixFile": "latest",
+  "customCodeCops": [
+    "https://github.com/StefanMaron/BusinessCentral.LinterCop/releases/latest/download/BusinessCentral.LinterCop.dll"
+  ]
+}
+```
+
+## BcContainerHelper
+
+If you are using `Run-ALPipeline` in your build pipelines you can also pass the path or url to the `BusinessCentral.LinterCop.dll` in via the parameter `-CustomCodeCops`.
+
+```PowerShell
+-CustomCodeCops "https://github.com/StefanMaron/BusinessCentral.LinterCop/releases/latest/download/BusinessCentral.LinterCop.dll"
+```
+
+If passing the `BusinessCentral.LinterCop.dll` as path instead of a url, be aware that the file needs to be placed in a folder shared with the container. Further note that you should have BcContainerHelper version 6.0.16 (or newer) installed.
+
+To have the correct compiler dependecies you should also load the latest compiler from the marketplace. Add `-vsixFile (Get-LatestAlLanguageExtensionUrl)` to do so.
+
+## Azure DevOps
+
+You can let your build pipelines download the latest version of the `BusinessCentral.LinterCop.dll` via the GitHub API. You can find an example for this in the [DownloadFile.ps1](https://github.com/StefanMaron/vsc-lintercop/blob/master/DownloadFile.ps1) script used by the BusinessCentral.LinterCop VS Code helper extension for automatic updates.
diff --git a/.assets/VSCode.md b/.assets/VSCode.md
@@ -0,0 +1,20 @@
+# Visual Studio Code
+
+Get the [BusinessCentral.LinterCop](https://marketplace.visualstudio.com/items?itemName=StefanMaron.businesscentral-lintercop) VS Code extension from the Visual Studio Code Marketplace.
+
+**Tip:** It's also possible to manually add `"${analyzerfolder}BusinessCentral.LinterCop.dll"` to the `"al.codeAnalyzers"` setting in either user, workspace or folder settings.
+
+# Example
+
+An example `settings.json` where the LinterCop is configured.
+
+```json
+  "al.codeAnalyzers": [
+    "${CodeCop}",
+    "${UICop}",
+    "${PerTenantExtensionCop}",
+    "${analyzerfolder}BusinessCentral.LinterCop.dll",
+  ],
+```
+
+**Tip:** Be aware that folder settings overwrite workspace and workspace overwrite user settings. If you have codecops defined in folder settings, the codecops defined in the user settings won't be applied.
diff --git a/README.md b/README.md
@@ -12,30 +12,35 @@ If you are not happy with some rules or only feel like you need one rule of this
 
 The Linter is not finished yet (and probably never will be :D ) If you have any rule on mind that would be nice to be covered, **please start a new [discussion](https://github.com/StefanMaron/BusinessCentral.LinterCop/discussions)!** then we can maybe sharpen the rule a bit if necessary. This way we can build value for all of us. If you want to write the rule yourself you can of course also submit a pull request ;)
 
-## How to use
+## Setup
+The LinterCop is compatible with various approaches and solutions for the AL Language extension for Microsoft Dynamics 365 Business Central.
 
-### Manual Compile
+- [Command Line](/.assets/CommandLine.md)
+    - [BcContainerHelper](/.assets/CommandLine.md#BcContainerHelper)
+- [Visual Studio Code](/.assets/VSCode.md)
+- [DevOps](/.assets/DevOps.md)
+    - [AL-Go! for GitHub](/.assets/DevOps.md#AL-Go!-for-GitHub)  
+    - [BcContainerHelper](/.assets/DevOps.md#BcContainerHelper)
+    - [Azure DevOps](/.assets/DevOps.md#Azure-DevOps)
 
-1. Download the `BusinessCentral.LinterCop.dll` and place it into your AL Extension folder. For Example `%userprofile%\.vscode\extensions\ms-dynamics-smb.al-7.4.502459\bin\`
-2. Run the AL Compiler `. %userprofile%\.vscode\extensions\ms-dynamics-smb.al-7.4.502459\bin\alc.exe /project:"<PathToYourAlProject>" /packagecachepath:"<PathToYour.alpackages>" /analyzer:"userprofile%\.vscode\extensions\ms-dynamics-smb.al-7.4.502459\bin\BusinessCentral.LinterCop.dll"`
-
-### In VS Code
+## Configuration
 
-1. Get the [BusinessCentral.LinterCop](https://marketplace.visualstudio.com/items?itemName=StefanMaron.businesscentral-lintercop) VSCode helper extension from the Visual Studio Marketplace
-2. Add `"${analyzerfolder}BusinessCentral.LinterCop.dll"` to the `"al.codeAnalyzers"` setting in either user, workspace or folder settings
-3. Be aware that folder settings overwrite workspace and workspace overwrite user settings. If you have codecops defined in folder settings, the codecops defined in the user settings won't be applied.
+Some rules can be configured by adding a file named `LinterCop.json` in the root of your project.
+**Important:** The file will only be read on startup of the linter, meaning if you make any changes you need to reload VS Code once.
 
-### BcContainerHelper
+For an example and the default values see: [LinterCop.json](LinterCop.json)
 
-For manual compile you can use the `Compile-AppInBcContainer` command and pass the path to the `BusinessCentral.LinterCop.dll` in via the parameter `-CustomCodeCops`.
+If you want to use the `LinterCop.json` file in a pipeline, using BcContainerHelper, you need to copy the file to `C:\build\vsix\extension\bin\win32\LinterCop.json` inside the container before calling `Compile-AppInBcContainer`. See [this issue](https://github.com/StefanMaron/BusinessCentral.LinterCop/issues/263) for details on how to accomplish that.
 
-If you are using `Run-ALPipeline` in your build pipelines you can also pass in the `BusinessCentral.LinterCop.dll` in via the parameter `-CustomCodeCops`. To have the correct compiler dependecies you should also load the latest compiler from the marketplace. Add `-vsixFile (Get-LatestAlLanguageExtensionUrl)` to do so.
+## Can I disable certain rules?
 
-Be aware though, the `BusinessCentral.LinterCop.dll` needs to be placed in a folder shared with the container.
+Since the linter integrates with the AL compiler directly, you can use the custom rule sets like you are used to from the other code cops.
+https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-rule-set-syntax-for-code-analysis-tools
 
-Further note that you should have BcContainerHelper version 2.0.16 (or newer) installed.
+Of course you can also use pragmas for disabling a rule just for a certain place in code.
+https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/directives/devenv-directive-pragma-warning
 
-**Tip:** You also can let your build pipelines download the latest version of the `BusinessCentral.LinterCop.dll` via the GitHub API. You can find an example for this in the [DownloadFile.ps1](https://github.com/StefanMaron/vsc-lintercop/blob/master/DownloadFile.ps1) script used by the BusinessCentral.LinterCop VSCode helper extension for automatic updates.
+For an example and the default values see: [LinterCop.ruleset.json](LinterCop.ruleset.json)
 
 ## Rules
 
@@ -98,23 +103,3 @@ Further note that you should have BcContainerHelper version 2.0.16 (or newer) in
 |[LC0055](https://github.com/StefanMaron/BusinessCentral.LinterCop/wiki/LC0055)|The suffix `Tok` is meant to be used when the value of the label matches the name.|Info|
 |[LC0056](https://github.com/StefanMaron/BusinessCentral.LinterCop/wiki/LC0056)|Empty Enum values should not have a specified `Caption` property.|Info|
 |[LC0057](https://github.com/StefanMaron/BusinessCentral.LinterCop/wiki/LC0057)|Enum values must have non-empty a `Caption` to be selectable in the client|Info|
-
-## Configuration
-
-Some rules can be configured by adding a file named `LinterCop.json` in the root of your project.
-**Important:** The file will only be read on startup of the linter, meaning if you make any changes you need to reload VS Code once.
-
-For an example and the default values see: [LinterCop.json](LinterCop.json)
-
-If you want to use the `LinterCop.json` file in a pipeline, using BcContainerHelper, you need to copy the file to `C:\build\vsix\extension\bin\win32\LinterCop.json` inside the container before calling `Compile-AppInBcContainer`. See [this issue](https://github.com/StefanMaron/BusinessCentral.LinterCop/issues/263) for details on how to accomplish that.
-
-## Can I disable certain rules?
-
-Since the linter integrates with the AL compiler directly, you can use the custom rule sets like you are used to from the other code cops.
-https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-rule-set-syntax-for-code-analysis-tools
-
-Of course you can also use pragmas for disabling a rule just for a certain place in code.
-https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/directives/devenv-directive-pragma-warning
-
-For an example and the default values see: [LinterCop.ruleset.json](LinterCop.ruleset.json)
-