- added encoding to md file generation

- added ignoring rules md doc
- fixed some typos in readme, and added link to new ignore doc

Author: tcartwright

.github/workflows/generate_docs.ps1

@@ -186,7 +186,6 @@ function New-TableOfContents {
     $categories = $RuleObjects | Group-Object { $_.Category } | Sort-Object -Property Key
 
     $StringBuilder = [System.Text.StringBuilder]::new()
-    [void]$StringBuilder.AppendLine("$spaces")
     [void]$StringBuilder.AppendLine("[This document is automatically generated. All changed made to it WILL be lost]: <>$spaces")
 
     [void]$StringBuilder.AppendLine("$spaces")
@@ -209,7 +208,7 @@ function New-TableOfContents {
     $FilePath = "$ParentDirectory\docs\"
     New-Item -Path $FilePath -Force -ItemType Directory | Out-Null
 
-    $StringBuilder.ToString() | Out-File "$FilePath\table_of_contents.md" -Force
+    $StringBuilder.ToString() | Out-File "$FilePath\table_of_contents.md" -Force -Encoding ascii
 }
 
 function New-MdFromRuleObject {
@@ -223,7 +222,6 @@ function New-MdFromRuleObject {
 
     # MD EOL - When you do want to insert a <br /> break tag using Markdown, you end a line with two or more spaces, then type return.
     $spaces = " " * 2
-    [void]$StringBuilder.AppendLine("$spaces")
     [void]$StringBuilder.AppendLine("[This document is automatically generated. All changed made to it WILL be lost]: <>$spaces")
 
     [void]$StringBuilder.AppendLine("$spaces")
@@ -273,7 +271,7 @@ function New-MdFromRuleObject {
     $FilePath = "$ParentDirectory\docs\$($RuleObject.Category)\"
     New-Item -Path $FilePath -Force -ItemType Directory | Out-Null
 
-    $StringBuilder.ToString() | Out-File "$FilePath\$($RuleObject.RuleId).md" -Force
+    $StringBuilder.ToString() | Out-File "$FilePath\$($RuleObject.RuleId).md" -Force -Encoding ascii
 }
 
 function Publish-Markdown {

README.md

@@ -2,11 +2,9 @@
 
 ## Overview
 
-Just what it says on the box: A library of SQL best practices as extended [database code analysis rules](https://docs.microsoft.com/en-us/sql/ssdt/overview-of-extensibility-for-database-code-analysis-rules?view=sql-server-ver15) checked at build.
+Just what it says on the box: A library of SQL best practices as extended [database code analysis rules](https://docs.microsoft.com/en-us/sql/ssdt/overview-of-extensibility-for-database-code-analysis-rules?view=sql-server-ver15) checked at build. The rules can be installed locally as well as on the build server.
 
-For a complete list of the current rules we have implemented see [here](docs/table_of_contents.md)
-
-For example code see [here](https://github.com/microsoft/DACExtensions/tree/master/RuleSamples)
+For a complete list of the current rules we have implemented see [here](docs/table_of_contents.md). For example code see [here](https://github.com/microsoft/DACExtensions/tree/master/RuleSamples)
 
 ## Organization
 
@@ -39,10 +37,12 @@ The build should be installed to the template path
 So for Visual Studio 2017 with DAC version 150 the path might be
 > `C:\Program Files (x86)\Microsoft Visual Studio\`***`2017`***`\Enterprise\Common7\IDE\Extensions\Microsoft\SQLDB\DAC\`***`150`***`\Extensions\SqlServer.Rules`
 
+An Install.bat is provided that will copy out the rules to all of the appropriate folder destinations.
+
 **NOTES:**
 
 - You will need to copy the binaries to every permutation of Visual Studio version and dac version that you wish to use the rules for.  
-- When you have code analysis enabled and have compiled the project Visual Studio places a hard lock on the rule binaries. To updates them or remove them you will need to close Visual Studio.
+- When you have code analysis enabled and have compiled the project Visual Studio places a hard lock on the rule binaries. To update them or remove them you will need to close Visual Studio.
 
 ## Project Configuration
 
@@ -52,3 +52,4 @@ So for Visual Studio 2017 with DAC version 150 the path might be
 - You can also optionally:
   - Enable / disable rules.
   - Set certain rules as errors so they will actually throw build errors.
+  - Ignore rules in the sql files. [See](docs/ignoring_rules.md)

SqlServer.Rules.sln

@@ -53,6 +53,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "workflows", "workflows", "{
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{596B2FD7-2684-4DC5-BD46-31EE223C49E4}"
 	ProjectSection(SolutionItems) = preProject
+		docs\ignoring_rules.md = docs\ignoring_rules.md
 		docs\table_of_contents.md = docs\table_of_contents.md
 	EndProjectSection
 EndProject

docs/ignoring_rules.md

@@ -0,0 +1,54 @@
+# Ignoring Rules
+
+Certain rules can be ignored within the T-SQL of the object itself. This is useful for whenever you want a rule to continue to run, but you have valid reasons for ignoring it in certain instances. Not all rules are ignorable. Refer to the documentation to determine which ones are.
+
+In those cases you can use:
+
+- IGNORE {RuleId}: Ignores a single occurrence of a rule within the file. Must be placed on, or above the line that violated the rule.
+- GLOBAL IGNORE {RuleId}: Ignores all occurrences of that rule within the file.
+
+Ignores must be done in comment syntax using either of these formats:
+
+- -- IGNORE {RuleId}
+- /* IGNORE {RuleId} */ - This is the preferred syntax as it will not cause sql to be malformed if the line breaks are removed.
+
+## Examples
+
+For example, for us to ignore the rule [SRD0032](Design/SRD0032.md) (Avoid use of OR in where clause) we can this several ways. This is a very common rule to have to ignore.
+
+To ignore just one of the rules:
+
+```sql
+CREATE PROCEDURE dbo.Example AS 
+BEGIN
+    SELECT * 
+    FROM dbo.table1 
+    WHERE id1 = 1 OR id2 = 2 /* IGNORE SRD0032 */ 
+
+
+    SELECT * 
+    FROM dbo.table2 
+    WHERE id1 = 1 OR id2 = 2 -- this will still flag as a violation of SRD0032
+END
+```
+
+Now you could just add ignores for each occasion of this rule violation, but instead you could use a global ignore to ignore all violations of that rule within the stored procedure.
+
+```sql
+CREATE PROCEDURE dbo.Example AS 
+BEGIN
+    /* GLOBAL IGNORE SRD0032 */
+    SELECT * 
+    FROM dbo.table1 
+    WHERE id1 = 1 OR id2 = 2 
+
+
+    SELECT * 
+    FROM dbo.table2 
+    WHERE id1 = 1 OR id2 = 2 
+END
+```
+
+## Notes
+
+If you find that you do not want a rule to ever run, you can simply uncheck it from your list of rules in your project properties instead of adding global ignores everywhere.