Visual Basic 2012 Voorbeelden
   

visual basic 2012 broncode voorbeelden

Blijf op de hoogte van de recente aanpassingen op vbvoorbeelden!

Microsoft Visual Studio 2012Microsoft Developers Network - Visual BasicMicrosoft .NET Framework

33.1. Documenteren met Sandcastle

Print Email Deel op Twitter Deel op Facebook

Dit artikel is gepubliceerd op maandag 15 oktober 2012 op vbvoorbeelden, bezoek de website voor een recente versie van dit artikel of andere artikels.

Sandcastle is de codenaam/produktnaam die verwijst naar een verzameling van tools, door Microsoft samengesteld, om zowel referentie documentatie voor .NET managed libraries, als conceptuele documentatie, te compileren/genereren.

Op zich kan Sandcastle enkel HTML documentatie genereren, maar door Sandcastle te koppelen aan help compilers, kan men ook CHM (via Microsoft Help 1.x compiler) of HxS (via Microsoft Help 2.x compiler) documentatie bekomen.

Het genereren van referentie documentatie gebeurde vroeger vaak aan de hand van nDoc.  Het nDoc project is echter wegens gebrek aan community support stop gezet.
Een overzicht van enkel alternatieven voor Sandcastle zijn te vinden via onderstaande link :

33.1.1. Referentie Documentatie voor Managed Libraries

Deze referentie documentatie is voor programmeur bruikbaar voor het opzoeken van informatie over een bepaalde API (Application Programming Interface of dus code bibliotheek).
Dit is zoals MSDN (Microsoft Developer Network), waar je bijvoorbeeld op zoek kunt gaan naar informatie hoe en waarom bepaalde datatypes of methods uit de klassenbibliohteek van het .NET Framework te gebruiken.
Ook Microsoft gebruikt Sandcastle voor het genereren (bijvoorbeeld op MSDN) van documentation over Visual Studio en het .NET Framework.

33.1.2. Conceptuele Documentatie met Sandcastle

Met conceptual documentation wordt hier bedoeld non-API reference documentation, als verklarende woordenlijst (glossary), veelgestelde vragen (FAQ), procedurale informatie of gebruiksaanwijzingen ( walkthrough/task/tutorial/how-to), probleemoplossing (troubleshooting) of overige documentatie.

33.1.3. Sandcastle CodePlex Release

De recentste versie - op moment van schrijven - van Sandcastle is te vinden op CodePlex en wordt gereleased onder de Microsoft Public License (Ms-PL).
Oudere community technology preview versies (CTP versies) waren ook te vinden in de Visual Studio 2005 en 2008 SDKs (Software Developer Kits).

33.1.4. Werking van Sandcastle

Sandcastle is niet één programma, maar een verzameling van tools/programmas en XSL transformaties die samen worden gebruikt.  Hoe deze tools worden gebruikt is sterk afhankelijk van het gewenste resultaat en de nodige aan te brengen configuraties.
Zo kan men bijvoorbeeld kiezen welke informatie en in welke stijl/vorm deze wordt gepresenteerd.

Drie executables zijn voorzien in Sandcastle, MRefBuilder, BuildAssembler en XslTransform.
MRefBuilder gebruikt reflectie om informatie in XML vorm over managed assemblies te bekomen.  Informatie als identifiers, visibility, return en parameter types, inheritance details, ... .
MRefBuilder wordt in de toekomst mogelijks hernoemt naar MReflector, en eventueel wordt er dan nog iets als UReflector toegevoegd voor reflectie over unmanaged assemblies.
XlsTransform is, zoals zijn naam duidelijk maakt, bruikbaar voor het omzetten van XML informatie in één vorm naar een andere vorm (of HTML vorm).
BuildAssembler zal de uit MRefBuilder bekomen reflectie informatie en de user defined referentie documentatie (XML documentation comments) via XslTransform omzetten naar documentatie.

Deze tools kunnen via de command prompt gebruikt worden, waar men aan de hand van configuratie bestanden en parameters de nodige instellingen aanbrengt.  Omdat dit een vrij complex build scenario is wordt vaak gebruik gemaakt van MSBuild, commandline batch scripts, of Windows PowerShell scripts om deze builds te automatiseren.
Ook third-party tools met een GUI (Graphical User Interface) zijn bruikbaar om op een visuele manier de nodige configuratie aan te brengen.  Deze tools zijn opgesteld door de community, populaire zijn Sandcastle Help File Builder (SHFB) en DocProject.

33.1.5. Output van Sandcastle

Drie verschillende presentatie stijlen voor de output zijn voorzien : Sandcastle Prototype, Sandcastle Visual Studio 2005 (zoals de huidige documentatie voor Visual Studio en het .NET Framework op MSDN) en Sandcastle Hana (hybride tussen de vorige twee).
Deze stijlen verschillen in welke informatie ze op een pagina plaatsen en hoe deze informatie wordt gepresenteerd.
De documentatie kan in HTML vorm, of mits koppeling aan de nodige help compilers ook in CHM of HxS vorm opgeleverd worden.

Help 1.x (CHM) wordt vaak gebruikt in context-sensitive help scenarios, waar men bijvoorbeeld aan de hand van de Help of HelpProvider klassen, aan controls (zoals tekstvakken en knoppen) help informatie koppelt die men dan bijvoorbeeld via de F1 sneltoets kan bereiken.
De HTML Help Workshop bevat de Microsoft Help 1.x compiler en een grafische user interterface voor het samenstellen van standalone compiled help (CHM files).
Deze bestanden kunnen aan de hand van de HTML Help Component, een viewer applicatie die op elk Windows besturingssysteem aanwezig is, bekeken worden.

De Visual Studio 2005 en 2008 SDKs voorzien in de Microsoft Help 2.x compiler.  Deze is bijvoorbeeld nodig wanneer je documentatie zou willen koppelen aan de Document Explorer van Visual Studio, een HxS bestand kan immers aan de Visual Studio help collectie worden toegevoegd.

H2Viewer is een viewer applicatie voor HxS help files.

Dit artikel is gepubliceerd op maandag 15 oktober 2012 op vbvoorbeelden, bezoek de website voor een recente versie van dit artikel of andere artikels.