ALM Rangers

Implementieren einer statischen Codeanalyse mit StyleCop

Hamid Shahid

Wie oft ist Ihnen schon unverständlicher Code begegnet? Meistens beruht die Unlesbarkeit auf inkonsistenter Formatierung, ungültigen Kommentare und dem Mangel an Benennungskonventionen. Derartige Inkonsistenzen werden oft als Kleinigkeiten abgetan, aber bei der allgemeinen Verwaltungsfreundlichkeit von Code können sie einen großen Unterschied machen.

StyleCop ist ein ausgezeichnetes Tool für die Verwaltung von Stil und Format im Quellcode. Wie die Visual Studio-Codeanalyse führt StyleCop ebenfalls statische Codeanalysen aus. Allerdings durchsucht das Tool – im Gegensatz zur Visual Studio-Codeanalyse – Quellcodedateien und nicht verwalteten Code. Außerdem überprüft StyleCop nur auf stilbezogene Inkonsistenzen. Es führt weder eine Codeoptimierung noch Leistungsüberprüfungen durch.

In diesem Artikel stelle ich StyleCop vor, zeige Ihnen, wie es funktioniert, und erläutere, welche Faktoren Sie berücksichtigen sollten, wenn Sie StyleCop in Ihrem Projekt verwenden. Außerdem zeige ich, wie Sie die Ausführung von StyleCop in Ihren Visual Studio Team Foundation Server (TFS)-Build integrieren.

Grundlagen zu StyleCop

StyleCop (stylecop.codeplex.com) ist ein Open-Source-Tool, das statische Codeanalysen für C#-Quelldateien ausführt. Es ist in Visual Studio integriert und wird im Kontextmenü angezeigt, damit Sie auf Wunsch die aktuelle Datei oder ausgewählte Dateien bzw. Projekte überprüfen können. Abbildung 1 zeigt, welche StyleCop-Optionen im Kontextmenü für ein Visual Studio-Projekt verfügbar sind.

Abbildung 1: StyleCop-Optionen im Kontextmenü

Wenn Sie die Option „Run StyleCop“ oder „Run StyleCop (Rescan All)“ auswählen, analysiert StyleCop alle C#-Dateien und überprüft sie auf festgelegte StyleCop-Regeln. Bei Verstößen wird eine Warnmeldung im Fehlerlistenfenster angezeigt. 

Einstellungsdatei für StyleCop Hier speichert StyleCop alle Konfigurationsoptionen. Diese Datei enthält Daten wie ausgewählte Regeln, Wortschatzdaten (zum Beispiel benutzerdefinierte Wörter und Akronyme) und Angaben dazu, ob die Einstellungsdatei mit einer möglicherweise vorhandenen Einstellungsdatei in einem übergeordneten Verzeichnis zusammengeführt werden soll.

StyleCop sucht rekursiv nach der Einstellungsdatei in dem der Quelldatei übergeordneten Verzeichnis. Daher empfiehlt es sich, nur eine Version der Datei „Settings.StyleCop“ zu speichern. Indem Sie eine einzige Datei verwalten und sie im Stamm des Teamprojekts speichern, wird sichergestellt, dass im gesamten Teamprojekt derselbe Satz von Regeln verwendet wird.

Benutzerdefinierte Wörterbuchdatei StyleCop lässt nicht nur zu, dass der Einstellungsdatei Wörter und Akronyme hinzugefügt werden, sondern verwendet zusätzlich auch die Datei „CustomDictionary.xml“, die dasselbe Format besitzt wie das Wörterbuch für die Visual Studio-Codeanalyse. So können Sie für beide Komponenten dieselbe Wörterbuchdatei verwenden. Abbildung 2 zeigt das Format der Wörterbuchdatei an.

Abbildung 2: Benutzerdefinierte Wörterbuchdatei

<Dictionary>
  <Words>
    <Unrecognized>
      <Word/>
    </Unrecognized>
    <Recognized>
      <Word/>
    </Recognized>
    <Deprecated>
      <Term PreferredAlternate=""/>
    </Deprecated>
    <Compound>
      <Term CompoundAlternate=""/>
    </Compound>
    <DiscreteExceptions>
      <Term />
    </DiscreteExceptions>
  </Words>
  <Acronyms>
    <CastingException>
      <Acronym />
    </CastingException>
  </Acronyms>
</Dictionary>

Nachdem ich den Zweck und die Grundlagen von StyleCop erläutert habe, erfahren Sie nun, wie Sie StyleCop fest in die Arbeitsweise Ihres Entwicklungsteams integrieren.

StyleCop-Regeln Diese Prüfung führt StyleCop für eine Codedatei aus. Es gibt eine Reihe von Standardregeln, aber Sie können auf Wunsch auch benutzerdefinierte Regeln schreiben. Im StyleCop-Wiki wird detailliert beschrieben, wie Sie Ihre eigenen StyleCop-Regeln verfassen (siehe bit.ly/12P665L).

Bei Verwendung von StyleCop müssen Sie als Erstes entscheiden, welche StyleCop-Regeln eingesetzt werden sollen. Ich rate dringend zur Verwendung aller StyleCop-Regeln. Oftmals haben Entwicklungsteams jedoch ihre eigenen Codierungsstandards, und Sie stoßen möglicherweise auf erheblichen Widerstand, wenn es um die Anwendung bestimmter StyleCop-Regeln geht. Sie müssen die langfristigen Vorteile von konsistent gestaltetem, verwaltungsfreundlichem Code und eventuelle Widrigkeiten gegeneinander abwägen. Wenn Sie sich erst einmal an die Verwendung von StyleCop gewöhnt haben, geht dies wie viele andere bewährte Verfahren auch in Fleisch und Blut über. Auf jeden Fall ist es unerlässlich, dass Sie sich auf die StyleCop-Regeln einigen, die Ihr Team in allen Bereichen verwenden wird.

Alle StyleCop-Regeln zählen zu einer der folgenden sieben Kategorien:

1. Dokumentationsregeln: Diese Regeln überprüfen die Eignung von Dokumentationselementen in den Quelldateien.
2. Layoutregeln: Diese Regeln überprüfen das Layout und den Zeilenabstand in den Quelldateien.
3. Wartbarkeitsregeln: Diese Regeln überprüfen die Quelldateien auf Wartbarkeitsaspekte, wie unerwünschte Klammern oder das Vorhandensein mehrerer Klassen in einer Datei.
4. Benennungsregeln: Diese Regeln überprüfen die Ersetzbarkeit von Methoden- und Variablennamen.
5. Reihenfolgeregeln: Diese Regeln überprüfen, ob der Codeinhalt in der richtigen Reihenfolge gespeichert ist.
6. Lesbarkeitsregeln: Diese Regeln überprüfen, ob der Code ordnungsgemäß formatiert wurde und lesbar ist.
7. Abstandsregeln: Diese Regeln überprüfen, ob der Abstand im Codeinhalt gültig und zutreffend ist.

Weitere Informationen zu den StyleCop-Kategorien und den entsprechenden Regeln finden Sie in der StyleCop-Regeldokumentation unter bit.ly/191GgiQ.

Hinzufügen von StyleCop zu Team Build

Es ist gut und schön, dass Sie StyleCop-Regeln ausgewählt und in einer Einstellungsdatei gespeichert haben. Aber um sicherzustellen, dass StyleCop für sämtlichen Quellcode einheitlich ausgeführt wird, müssen Sie StyleCop als Teil des Buildprozesses ausführen.

Dies lässt sich auf zwei Arten einrichten:

1. Integrieren Sie StyleCop in die MSBuild-Datei des C#-Projekts, damit es beim Kompilieren des Projekts ausgeführt wird. Die genaue Vorgehensweise wird in der StyleCop-Dokumentation beschrieben (bit.ly/13ZX2xL).
2. Fügen Sie StyleCop in der kontinuierlichen Integration von Team Build hinzu, damit das Tool bei jedem Eincheckvorgang ausgeführt wird.

Ich erläutere im Weiteren, wie Sie StyleCop innerhalb der kontinuierlichen Integration von Team Build ausführen. Wenn Sie abgegrenzte Builds verwenden, wird durch Ausführen von StyleCop sichergestellt, dass keine Codedateien mit Regelverstößen eingecheckt werden. Wenn Sie StyleCop in abgegrenzten Builds nicht verwenden, werden Sie beim Einchecken von Code im Falle eines fehlerhaften Builds weiterhin aufgefordert, die Regelverstöße zu beheben.

Damit StyleCop in Team Build ausgeführt wird, muss der Prozess von einer Aktivität im Buildworkflow aufgerufen werden. Ich verwende die StyleCop-Aktivität aus einem Open-Source-Projekt mit dem Namen Community TFS Build Extensions (tfsbuildextensions.codeplex.com). Community TFS Build Extensions ist ein Satz von Bibliotheken mit einer Reihe von wiederverwendbaren Workflowaktivitäten. Sie können diese Aktivitäten einfach per Drag & Drop in Ihrer Team Build-Prozessvorlage ablegen.

Änderungen am Buildcontroller Bevor Sie Team Build für Ihre Bedürfnisse anpassen, müssen Sie als Erstes den Pfad für die benutzerdefinierten Assemblys Ihres Buildcontrollers festlegen. Das ist der Speicherort, von dem die Build-Agents Assemblys für benutzerdefinierte Aktivitäten laden, die sie im Buildworkflow antreffen.

Erstellen Sie einen neuen Ordner an einem entsprechenden Speicherplatz im Teamprojekt, um benutzerdefinierte Assemblys hinzuzufügen. Ich habe den neuen Ordner „Custom Assemblies“ genannt und ihn direkt unterhalb von „BuildProcessTemplate“ unter dem Stammordner für das Teamprojekt erstellt. Checken Sie nun die folgenden Assemblys ein:

• StyleCop.dll
• StyleCop.CSharp.dll
• StyleCop.CSharp.Rules.dll
• TFSBuildExtensions.Activities.dll
• TFSBuildExtensions.Activities.StyleCop.dll

Der nächste Schritt besteht in der Konfigurierung des Buildcontrollers für die Verwendung dieser Assemblys. Gehen Sie hierzu folgendermaßen vor:

1. Klicken Sie in Team Explorer auf den Link für den Build. Klicken Sie auf „Aktionen“, und wählen Sie „Buildcontroller verwalten“ aus.
2. Wählen Sie im angezeigten Dialogfeld Ihren Buildcontroller aus, und klicken Sie auf die Schaltfläche „Eigenschaften“.
3. Legen Sie im Dialogfeld „Eigenschaften von Buildcontroller“ für die Eigenschaft „Versionskontrollpfad zu benutzerdefinierten Assemblys“ den Ordner „Custom Assemblies“ fest, den wir vorhin im Teamprojekt erstellt haben (siehe Abbildung 3).

Abbildung 3: Eigenschaften von Buildcontroller

Klicken Sie auf „OK“, um das Eigenschaftendialogfeld zu schließen. Nun ist der Buildcontroller so konfiguriert, dass er Ihre benutzerdefinierten Aktivitäten lädt. Im nächsten Schritt passen Sie die Vorlage des Builds an.

Überlegungen zu StyleCop

Im Folgenden finden Sie einige wichtige Aspekte:

• Im Gegensatz zur Visual Studio-Codeanalyse bietet StyleCop keine Unterstützung für Visual Basic .NET und kann nur für Quelldateien verwendet werden, die in C# geschrieben wurden.
• Als dieser Artikel entstand, war StyleCop noch nicht für Visual Studio 2013 verfügbar.
• Der gehostete Buildcontroller wird in der Cloud von Visual Studio Team Foundation Service gehostet. Die Vorgehensweise zum Konfigurieren dieses Buildcontrollers ist mit der für einen lokalen Buildserver identisch.
• Für diesen Artikel wurde Team Foundation Server (TFS) 2012 verwendet. Die Schritte für TFS 2010 und TFS 2013 sind identisch. Stellen Sie sicher, dass Sie die richtige Version von TFS Build Extensions verwenden.

Benutzerdefinierte Buildvorlagen

TFS erstellt für jedes neue Teamprojekt mehrere standardmäßige Buildvorlagen. Diese Buildvorlagen werden in einem Ordner namens „ProcessBuildTemplates“ erstellt, der sich im Stamm des Teamprojekts befindet. Als Erstes passen Sie eine Kopie der Vorlage „DefaultTemplate.11.1.xaml“ an, indem Sie die StyleCop-Aktivität hinzufügen. Ich habe eine Kopie von „DefaultTemplate.11.1.xaml“ erstellt und sie „CustomTemplate.xaml“ genannt.

Zur Anpassung des Buildworkflows müssen Sie die benutzerdefinierten Aktivitäten in Ihrer Entwicklungsumgebung hinzufügen. Erstellen Sie zu diesem Zweck ein neues Workflowaktivität-Bibliotheksprojekt in Visual Studio. Vergewissern Sie sich, dass im Dialogfeld „Neues Projekt hinzufügen“ Microsoft .NET Framework 4.5 als Zielplattform ausgewählt ist. Als Nächstes müssen Sie im neu erstellten Projekt einen Link zur Datei „CustomTem­plate.xaml“ hinzufügen. Klicken Sie zu diesem Zweck mit der rechten Maustaste auf das Projekt, wählen Sie „Vorhandenes Element hinzufügen“ aus, und navigieren Sie zur Datei „CustomTemplate.xml“. Klicken Sie auf die Schaltfläche „Als Link hinzufügen“.

Der letzte Schritt zum Einrichten Ihrer Entwicklungsumgebung besteht darin, die StyleCop-Aktivität im Fenster „Toolbox“ hinzuzufügen, um Drag-&-Drop-Vorgänge zuzulassen. Klicken Sie dazu mit der rechten Maustaste im Fenster „Toolbox“ auf den Bereich unterhalb der Aktivitäten, und wählen Sie die Option „Registerkarte hinzufügen“ aus. Nennen Sie die neue Registerkarte „TFS Build Extensions“. Klicken Sie mit der rechten Maustaste auf den Namen der Registerkarte, und wählen Sie „Elemente auswählen“ aus. Wechseln Sie zur Assembly „TfsBuildExtensions.Activities.Stylecop.dll“, und klicken Sie auf „OK“. Nun können Sie die Datei „CustomTemplate.xaml“ öffnen und die StyleCop-Aktivität hineinziehen.

Anpassen der Buildvorlage Es empfiehlt sich, StyleCop früh im Buildprozess auszuführen. Auf diese Weise schlägt der Build im Falle von Regelverstößen frühzeitig fehl. Da StyleCop für die Überprüfung Quelldateien benötigt, kann das Tool frühestens im Anschluss an die Sequenz „Arbeitsbereich initialisieren“ innerhalb der Sequenz „Ausführung mit Agent“ ausgeführt werden (siehe Abbildung 4).

Abbildung 4: Speicherort zum Ablegen der StyleCop-Aktivität

Nachdem Sie ermittelt haben, an welcher Stelle im Buildworkflow Sie die StyleCop-Aktivität am besten hinzufügen, wird als Nächstes eine Sequenzaktivität hinzugefügt. Benennen Sie die Sequenzaktivität in „Run StyleCop“ um. Die abschließende Auflistung meiner Sequenz „Run StyleCop“ ist in Abbildung 5 dargestellt.

Abbildung 5: Sequenz „Run StyleCop“

Exemplarische Vorgehensweise für den Code In Abbildung 6 werden die in der Sequenz „Run StyleCop“ definierten Variablen im Detail gezeigt, einschließlich Typ und Zweck.

Abbildung 6: Die in der Sequenz „Run StyleCop“ definierten Variablen

Variablenname	Typ	Beschreibung
SourceCodeFiles	IEnumerable<Zeichenfolge>	Speichert die Namen aller Dateien, die von StyleCop überprüft werden sollen.
IsSuccess	Boolesch	Speichert die Angabe, ob die StyleCop-Aktivität Regelverstöße gefunden hat.
ViolationCount	Int32	Speichert die Anzahl von StyleCop-Regelverstößen.

Der Workflow enthält auch den Parameter „StyleCopSettingsFile“ vom Typ Zeichenfolge, der den Pfad der StyleCop-Einstellungsdatei speichert.

Die erste Aktivität in der Sequenz „Run StyleCop“ ist die Aktivität „FindMatchingFiles“. Die Aktivität befindet sich in der Assembly „Microsoft.TeamFoundation.Build.Workflow.dll“ und gibt die Liste aller Dateien zurück, die dem angegebenen Dateimuster entsprechen. Abbildung 7 beschreibt, wie die Eigenschaften für diese Aktivität festgelegt werden.

Abbildung 7: Eigenschaften der FindMatchingFiles-Aktivität

Name der Eigenschaft	Wert
DisplayName	FindMatchingFiles
IsSuccess	String.Format(“{0}\**\*.cs”, BuildDirectory)
Result	SourceCodeFiles

Das Muster der erfolgreichen Suche aller C#-Dateien (*.cs) im Buildverzeichnis wird an die Aktivität übergeben. Die Aktivität gibt das Ergebnis dann in der SourceCodeFiles-Auflistung zurück.

Die nächste Aktivität in der Sequenz ist „ConvertWorkspaceItem“. Sie befindet sich in der Assembly „Microsoft.TeamFounda­tion.Build.Workflow.Activities.dll“. Die Aktivität konvertiert den Serverpfad der angegebenen StyleCop-Einstellungsdatei, die als Parameter übergeben wird, in einen lokalen Pfad auf dem Buildserver. Die Eigenschaften dieser Aktivität werden in Abbildung 8 dargestellt.

Abbildung 8: Eigenschaften von „Get Local Settings File“

Name der Eigenschaft	Wert
Direction	ServerToLocal
DisplayName	Get Local Settings File
Input	StyleCopSettingsFile
Result	StyleCopSettingsFileLocalPath
Workspace	Workspace

Die Namen der Quelldateien wurden abgerufen, und der Speicherplatz der StyleCop-Einstellungen ist nun eingerichtet. Die nächste Aktivität in der Sequenz „Run StyleCop“ ist die StyleCop-Aktivität. Abbildung 9 stellt dar, wie die Eigenschaften der StyleCop-Aktivität festgelegt werden.

Abbildung 9: Eigenschaften von „Execute StyleCop“

Name der Eigenschaft	Wert
DisplayName	Execute StyleCop
LogExceptionStack	True
SettingsFile	StyleCopSettingsFile
ShowOutput	True
SourceFiles	SourceCodeFiles.ToArray()
Result	StyleCopSettingsFileLocalPath
Succeeded	IsSuccess
TreatWarningsAsErrors	True

Die Aktivität verwendet die in ein Array konvertierte SourceCodeFiles-Auflistung als Eingabe und gibt das Ergebnis sowie die Anzahl von Regelverstößen jeweils in den Variablen „IsSuccess“ und „ViolationCount“ zurück. Sie erhält den Anzeigenamen „Execute StyleCop“ und ist so definiert, dass sie Warnungen als Fehler behandelt. Sie lässt den Build fehlschlagen, falls Fehler auftreten.

Die letzte Aktivität in der Sequenz „Run StyleCop“ ist die Aktivität zum Schreiben der Buildmeldung. Sie zeigt das Ergebnis und die Anzahl von Regelverstößen an. Abbildung 10 stellt dar, wie die Eigenschaften für diese Aktivität festgelegt werden.

Abbildung 10: Eigenschaften der Aktivität zum Schreiben der Buildmeldung

Name der Eigenschaft	Wert
DisplayName	Completion Message
Importance	Microsoft.TeamFoundation.Build.Client.BuildMessageImportance.Normal
Message	String.Format(„StyleCop wurde mit {0} Regelverstößen abgeschlossen“, StyleCopViolationsCount)

Nun können Sie Ihre benutzerdefinierte Buildvorlage verwenden. Speichern Sie die Datei „CustomTemplate.xaml“, und checken Sie sie ein. Um die neue Buildvorlage zu verwenden, öffnen Sie die Builddefinition, klicken Sie auf den Prozess, erweitern Sie die Buildprozessvorlage, und klicken Sie auf die Schaltfläche „Neu“. Wählen Sie im angezeigten Dialogfeld für die neue Prozessvorlage die Option „Vorhandene XAML-Datei auswählen“ aus, und navigieren Sie zur Datei „CustomTemplate.xaml“.

Legen Sie als Wert für den StyleCopSettingsFile-Parameter den Pfad zur Datei „Settings.StyleCop“ fest. Klicken Sie zum Speichern der Builddefinition auf „Speichern“. Nun können Sie Ihren Build mit StyleCop verwenden. Diese Buildvorlage verwenden Sie am besten für abgegrenzte Builds. So wird sichergestellt, dass keine eingecheckte Quelldatei gegen StyleCop-Regeln verstößt.

Nächste Schritte

Ich habe gezeigt, wie Sie mit StyleCop statische Codeanalysen in Team Build erzwingen können. Statische Codeanalysen sorgen für bessere Codierungsstandards und können in Team Build ausgeführt werden, um sicherzustellen, dass eingecheckter Code Ihre Standards erfüllt. Auf ähnliche Weise können Sie andere bewährte Vorgehensweisen in Ihrer Team Build-Bereitstellung erzwingen. Die Microsoft ALM Rangers haben im Rahmen des Projekts für Team Foundation Build-Anpassungsrichtlinien (vsarbuildguide.codeplex.com) eine Reihe nützlicher Buildvorlagen erstellt, die Sie verwenden können. Außerdem können Sie wahlweise Ihre eigenen Aktivitäten schreiben oder die im Community TFS Build Extensions-Projekt zur Verfügung gestellten Aktivitäten verwenden.

Hamid Shahid ist Microsoft ALM Ranger und unabhängiger Berater. Er entwirft und entwickelt seit über zwölf Jahren Enterprise-Software. Hamid beschäftigt sich intensiv mit der Förderung von Best Practices in Microsoft ALM-Technologien. Er kann über seinen Blog unter hamidshahid.blogspot.com erreicht werden, und auf Twitter können Sie seine Beiträge unter twitter.com/hamid_shahid verfolgen.

UNSER DANK gilt den folgenden ALM Rangers und technischen Experten für die Durchsicht dieses Artikels: Mike Fourie (unabhängiger Berater), Willy-Peter Schaub (Microsoft) und Patricia Wagner (Microsoft)
Mike Fourie ist ein unabhängiger Berater mit über 13 Jahren Erfahrung im Bereich Softwareentwicklung, der sich auf Build- und Bereitstellungsautomatisierung spezialisiert hat. Er ist MVP für Microsoft ALM und Distinguished ALM Ranger. Sie können ihn über seinen Blog unter freetodev.com erreichen und ihm auf Twitter unter twitter.com/mikefourie folgen.

Willy-Peter Schaub ist Senior Program Manager bei den Visual Studio ALM Rangers im Microsoft Canada Development Center. Seit Mitte der 80er Jahre bemüht er sich um mehr Einfachheit und Instandhaltbarkeit in der Softwareentwicklung. Sie finden seinen Blog unter blogs.msdn.com/b/willy-peter_schaub. Folgen Sie ihm auf Twitter unter twitter.com/wpschaub.