SYSK 396: FxCop Rules for RESTful API

Artikel
08/24/2015

There are a few well known basic naming rules providing a consistent, understandable REST API services, e.g.

The scheme and host name are not case sensitive; however, the path and query should be treated as case sensitive.
Lowercase letters are preferred in URI paths.
Do use hyphens (-) between words to improve readability of URI
Do not use underscore (_) in URIs as this character is often virtually indistinguishable when the content is underlined.

However, quite a few WebAPIs I’ve seen do not adhere to these conventions, so I created (quick and dirty, not fully tested and not production ready) FxCop rules that check for underscores and capital letters in WebAPI implementations. Feel free to create a dll library type of project, add the files from the listings below and use it in your projects.

WebApiBaseNamingRule.cs

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

using System.Threading.Tasks;

using Microsoft.FxCop.Sdk;

using System.Threading;

using YOURCOMPANY.CodeQuality;

using System.Web.Http.Routing;

using System.Web.Http;

namespace YOURCOMPANY.CodeQuality.WebAPI

{

public abstract class WebApiBaseNamingRule : BaseIntrospectionRule

{

private static Dictionary<string, HttpRoute[]> KnownRoutes = new Dictionary<string, HttpRoute[]>();

protected static string[] KnownVerbs = Enum.GetNames(typeof(System.Web.Mvc.HttpVerbs));

public WebApiBaseNamingRule(string name, string resourceName)

: base(name, resourceName, typeof(WebApiBaseNamingRule).Assembly)

{

}

public abstract ProblemCollection Check(string checkTemplate, string routeTemplate);

public override ProblemCollection Check(Member member)

{

var routes = GetRegisteredApiRoutes(member);

if (member.DeclaringType.ConstructorName.ToString() == "WebApiConfig" &&

member.NodeType == NodeType.Method&&

(member as Method).Parameters.Count == 1 && (member as Method).Parameters[0].Type.FullName == "System.Web.Http.HttpConfiguration")

{

foreach(var r in routes)

{

// Only check literals, i.e. don't check placeholers as they will be replaced when WebAPI is actually used

string validateTemplate = RemoteRoutePlaceholders(r.RouteTemplate);

Check(validateTemplate, r.RouteTemplate);

}

else if (member.DeclaringType.IsApiController()&& member.IsPublic && !member.IsSpecialName)

{

string template = null;

if (member.HasCustomAttribute("System.Web.Http.RouteAttribute"))

{

var a = member.GetCustomAttribute("System.Web.Http.RouteAttribute");

if (a.Expressions.Count > 0)

{

Literal l = a.Expressions[0] as Literal;

if (l != null)

template = l.Value as string;

}

if (string.IsNullOrEmpty(template) && member.NodeType == NodeType.Method)

{

// Get matching template

string controllerName = RemoveSuffix(member.DeclaringType.Name.ToString(), "controller");

var requiredParamsArray = (from p in (member as Method).Parameters

where p.IsOptional == false && p.IsOut == false // note: IsIn is only set to true if parameter has [in] attribute

select "{" + p.Name + "}").ToArray();

string requiredParams = string.Join("/", requiredParamsArray);

var action = "/" + member.Name.ToString();

if (IsHttpVerb(member.Name.ToString())) // Matching logic in System.Web.Http (packages\Microsoft.AspNet.WebApi.Core.5.2.2\lib\net45\System.Web.Http.dll)

action = "";

template = "{controller}" + action +

(string.IsNullOrEmpty(requiredParams) ? "" : "/" + requiredParams);

foreach(var r in routes)

{

string rt = r.RouteTemplate;

if (rt.EndsWith(template))

template = rt.Substring(0, rt.Length - requiredParams.Length);

}

if (!string.IsNullOrEmpty(template))

{

string validateTemplate = RemoteRoutePlaceholders(template);

return Check(validateTemplate, template);

}

else

{

return base.Check(member);

}

return this.Problems;

}

private bool IsHttpVerb(string method)

{

bool result = false;

if (!string.IsNullOrEmpty(method))

{

result = (from v in KnownVerbs

where string.Compare(method, v, true) == 0

select v).Any();

}

return result;

}

private string RemoteRoutePlaceholders(string template)

{

List<char> r = new List<char>();

bool skip = false;

foreach(var c in template.ToCharArray())

{

if (c == '{')

skip = true;

if (!skip)

r.Add(c);

if (c == '}')

skip = false;

}

string result = new string(r.ToArray());

while (result.IndexOf("//") != -1)

{

result = result.Replace("//", "/");

}

return result;

}

private HttpRoute[] GetRegisteredApiRoutes(Member member)

{

List<HttpRoute> routeList = new List<HttpRoute>();

var a = member.DeclaringType.ContainingAssembly().Name;

lock (KnownRoutes)

{

if (!KnownRoutes.ContainsKey(a))

{

// NOTE: this assumes the class name wasn't changed from one generated by VS project template

// TODO: make it more versatile

var webApiCofig = (from t in member.DeclaringType.ContainingAssembly().Types

where t.ConstructorName.ToString() == "WebApiConfig"

select t).FirstOrDefault();

var registerMethod = (from m in webApiCofig.Members

where m.NodeType == NodeType.Method

let tm = m as Method

from p in tm.Parameters

where tm.Parameters.Count == 1 && tm.Parameters[0].Type.FullName == "System.Web.Http.HttpConfiguration"

select tm).FirstOrDefault();

var registeredRoutes = (from ms in registerMethod.Body.Statements

where ms.NodeType == NodeType.Block

let b = (ms as Block)

from s in b.Statements

where s.NodeType == NodeType.ExpressionStatement

let ex = s as ExpressionStatement

where ex.Expression is UnaryExpression

let uex = ex.Expression as UnaryExpression

where uex.Operand is Microsoft.FxCop.Sdk.NaryExpression&& uex.Operand.Type.FullName == "System.Web.Http.Routing.IHttpRoute"

select (uex.Operand as Microsoft.FxCop.Sdk.NaryExpression).Operands).ToArray();

foreach (var r in registeredRoutes)

{

HttpRoute route = null;

var operands = r.ToArray();

// Skip the first operand which is MethodCall

for (int i = 1; i < operands.Length; i++)

{

// TODO: add handling for constraints

switch (i)

{

//case 1:

// // Get this for debugging/tracing purposes

// name = operands[i].ToString();

// break;

case 2:

//template = operands[i].ToString();

route = new HttpRoute(operands[i].ToString());

break;

case 3:

var operandName = operands[i].Type.Members.Last().Name;

foreach (var o in (operands[i] as Construct).Operands)

{

route.Defaults.Add(operandName.ToString(), o);

//if (o.NodeType == NodeType.MemberBinding)

//{

// if ((o as MemberBinding).BoundMember.FullName == "System.Web.Http.RouteParameter.Optional")

// {

// string newTemplate = template.ReplaceOrdinal("/{" + operandName.ToString() + "}", "");

// routeList.Add(newTemplate);

// }

//}

//else if (o.NodeType == NodeType.Literal)

//{

// string newTemplate = template.ReplaceOrdinal("{" + operandName.ToString() + "}", (o as Literal).Value.ToString());

// //System.Diagnostics.Debug.WriteLine(newTemplate);

// routeList.Add(newTemplate);

//}

}

break;

case 4:

//handler = operands[i].ToString();

break;

}

routeList.Add(route);

}

KnownRoutes.Add(a, routeList.ToArray());

}

return KnownRoutes[a];

}

private string RemoveSuffix(string name, string suffix, bool caseInsensitive = true)

{

string result = name;

string s = caseInsensitive ? suffix.ToLower() : suffix;

string n = caseInsensitive ? name.ToLower() : name;

if (n.EndsWith(s))

{

result = name.Substring(0, name.Length - suffix.Length);

}

return result;

}

protected WordInfo[] Words(string template)

{

List<WordInfo> result = new List<WordInfo>();

var wordParser = new WordParser(template, WordParserOptions.SplitCompoundWords);

string word = null;

int processedIndex = 0;

while ((word = wordParser.NextWord()) != null)

{

int i = template.IndexOf(word, processedIndex);

if (i > processedIndex)

{

result.Add(new WordInfo(template.Substring(processedIndex, i - processedIndex), false));

}

result.Add(new WordInfo(word, true));

processedIndex = i + word.Length;

}

if (processedIndex < template.Length)

result.Add(new WordInfo(template.Substring(processedIndex), false));

return result.ToArray();

}

protected struct WordInfo

{

public string Text;

public bool IsWord;

public WordInfo(string text, bool isWord)

{

Text = text;

IsWord = isWord;

}

WebApiRouteShouldNotContainCapitalLetters.cs

using Microsoft.FxCop.Sdk;

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

using System.Threading.Tasks;

namespace YOURCOMPANY.CodeQuality.WebAPI

{

// Important: this implementation only checks for controller and action names, not route part registered via config.Routes.MapHttpRoute

public class WebApiRouteShouldNotContainCapitalLetters : WebApiBaseNamingRule

{

public WebApiRouteShouldNotContainCapitalLetters()

: base("WebApiRouteShouldNotContainCapitalLetters", "YOURCOMPANY.CodeQuality.Rules")

{

}

public override Microsoft.FxCop.Sdk.ProblemCollection Check(string checkTemplate, string routeTemplate)

{

bool isValid = true;

string validTemplate = string.Empty;

bool precededByWord = false;

string validWord = string.Empty;

foreach (var w in Words(checkTemplate))

{

isValid& = IsValid(w.Text, precededByWord, out validWord);

validTemplate += validWord;

precededByWord = w.IsWord;

}

if (!isValid)

{

validTemplate = routeTemplate.Replace(checkTemplate, validTemplate);

this.Problems.Add(new Problem(this.GetResolution(routeTemplate, validTemplate)));

}

return this.Problems;

}

private bool IsValid(string word, bool preceededByWord, out string validWord)

{

bool result = true;

List<char> validChars = new List<char>();

foreach (char c in word.ToCharArray())

{

if (char.IsUpper(c))

{

result = false;

if (preceededByWord)

validChars.Add('-');

validChars.Add(char.ToLower(c));

}

else

{

validChars.Add(c);

}

validWord = new string(validChars.ToArray());

return result;

}

WebApiRouteShouldNotContainUnderscores.cs

using Microsoft.FxCop.Sdk;

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

using System.Threading.Tasks;

namespace YOURCOMPANY.CodeQuality.WebAPI

{

public class WebApiRouteShouldNotContainUnderscores : WebApiBaseNamingRule

{

public WebApiRouteShouldNotContainUnderscores()

: base("WebApiRouteShouldNotContainUnderscores", "YOURCOMPANY.CodeQuality.Rules")

{

}

public override Microsoft.FxCop.Sdk.ProblemCollection Check(string checkTemplate, string routeTemplate)

{

if (checkTemplate.IndexOf('_') != -1)

{

this.Problems.Add(new Problem(this.GetResolution(routeTemplate)));

}

return this.Problems;

}

WebApiRouteShouldUseHyphenToSeparateWords.cs

using Microsoft.FxCop.Sdk;

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

using System.Threading.Tasks;

namespace YOURCOMPANY.CodeQuality.WebAPI

{

public class WebApiRouteShouldUseHyphenToSeparateWords : WebApiBaseNamingRule

{

public WebApiRouteShouldUseHyphenToSeparateWords()

: base("WebApiRouteShouldUseHyphenToSeparateWords", "YOURCOMPANY.CodeQuality.Rules")

{

}

public override Microsoft.FxCop.Sdk.ProblemCollection Check(string checkTemplate, string routeTemplate)

{

bool isValid = true;

string validTemplate = string.Empty;

var words = Words(checkTemplate);

for (int i = 0; i < words.Length; i++)

{

WordInfo w = words[i];

if (i > 0 && w.IsWord && words[i - 1].IsWord)

{

isValid = false;

validTemplate += "-";

}

validTemplate += w.Text.ToLower();

}

if (!isValid)

{

validTemplate = routeTemplate.Replace(checkTemplate, validTemplate);

this.Problems.Add(new Problem(this.GetResolution(routeTemplate, validTemplate)));

}

return this.Problems;

}

ClassFieldNamePrefixes.cs

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

using System.Threading.Tasks;

using Microsoft.FxCop.Sdk;

using System.Threading;

namespace YOURCOMPANY.CodeQuality

{

public class ClassFieldNamePrefixes : BaseIntrospectionRule

{

public ClassFieldNamePrefixes() :

base("ClassFieldNamePrefixes", "YOURCOMPANY.CodeQuality.Rules", typeof(ClassFieldNamePrefixes).Assembly)

{

}

public override ProblemCollection Check(Member member)

{

if (!(member.DeclaringType is ClassNode))

return this.Problems;

Field fld = member as Field;

if (fld == null)

return this.Problems;

if (fld.IsStatic&& !fld.Name.Name.StartsWith("s_", StringComparison.Ordinal)&&

fld.Name.Name != "__ENCList") // Ignore edit-and-continue debugging fields

{

this.Problems.Add(new Problem(this.GetNamedResolution("Static", fld.Name.Name)));

}

else if (!fld.Name.Name.StartsWith("_", StringComparison.Ordinal)&&

fld.Name.Name != "__ENCList"&& fld.Name.Name != "components")

{

this.Problems.Add(new Problem(this.GetNamedResolution("Instance", fld.Name.Name)));

}

return this.Problems;

}

ExtensionMethods \String.cs

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

using System.Threading.Tasks;

namespace YOURCOMPANY.CodeQuality

{

public static class StringExtensionMethods

{

// Replace s1 with s2 in orig (find is case-insensitive)

public static string ReplaceOrdinalIgnoreCase(this string orig, string s1, string s2)

{

string result = orig;

int i1 = orig.ToLower().IndexOf(s1.ToLower());

if (i1 != -1)

{

if (i1 == 0)

result = string.Empty;

else

result = orig.Substring(0, i1);

result += s2;

int i2 = i1 + s1.Length;

if (i2 < orig.Length)

result += orig.Substring(i2);

}

return result;

}

ExtensionMethods \TypeNode.cs

using Microsoft.FxCop.Sdk;

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

using System.Threading.Tasks;

namespace YOURCOMPANY.CodeQuality

{

public static class TypeExtensionMethods

{

public static bool IsApiController(this TypeNode t)

{

bool result = false;

{

t = t.BaseType;

if (t != null && t.Name.Name == "ApiController")

result = true;

} while (t != null && result == false);

return result;

}

Rules.xml

<?xml version="1.0" encoding="utf-8"?>

<Name>Web API route should use hyphen (-) instead of undercore (_).</Name>

Do not use underscore (_) in URIs as this character is often virtually indistinguishable when the content is underlined.

</Description>

<Resolution>Use hyphen instead of underscore in route '{0}' .</Resolution>

<MessageLevel Certainty="95">Warning</MessageLevel>

<FixCategories>Breaking</FixCategories>

<Owner>Microsoft, Corp.</Owner>

</Rule>

<Name>Lowercase letters are preferred in URI paths.</Name>

Web API route should use hyphen (-) to separate compound words instead of Pascal or Camel case naming convention.

</Description>

<Resolution>Change from {0} route to {1} .</Resolution>

<MessageLevel Certainty="95">Warning</MessageLevel>

<FixCategories>Breaking</FixCategories>

<Owner>Microsoft, Corp.</Owner>

</Rule>

<Name>Use hyphens (-) between words to improve readability of URIs</Name>

Web API route should use hyphen (-) to separate compound words

</Description>

<Resolution>Change from {0} route to {1} .</Resolution>

<MessageLevel Certainty="95">Warning</MessageLevel>

<FixCategories>Breaking</FixCategories>

<Owner>Microsoft, Corp.</Owner>

</Rule>

</Rules>

Freigeben über

SYSK 396: FxCop Rules for RESTful API

Zusätzliche Ressourcen