Skip to content

Developer Guide

Jump to bottom Edit New page
Boaz Brickner edited this page Oct 24, 2015 · 33 revisions

Here are the guidelines for developing Pcap.Net.
If you want to use Pcap.Net in your own application, see the User Guide.

Checklist

The following items are needed before you can develop Pcap.Net:

Compiling the code

  • Make sure you have the checklist.
  • Download the code (by clicking the "Download ZIP" button or by cloning the repository).
  • Build PcapDotNet.sln by going over the following steps:
    • Download WinPcap Developer's Pack (of the correct WinPcap version) and put it in the Source Code 3rdParty folder (so you'll have ...\PcapDotNet\3rdParty\WpdPack... folders).
    • Open the PcapDotNet.sln and build it.
  • Run all the unit tests of PcapDotNet.sln
  • Problems:
    • If compilation fails - try to find the problem in the Q&A group or create a new thread.
    • If tests fail - try to find the problem in the Q&A group page or create a new thread.

Coding Conventions

  • Warning Level: 4.
  • The Resharper configuration file in the solution should be used.
  • Code Analysis should run smoothly and the following rules exceptions are allowed:
    • CA1004 (Design): Generic methods should provide type parameter
    • CA1021 (Design): Avoid out parameters
    • CA1027 (Design): Mark enums with FlagsAttribute
    • CA1028 (Design): Enum storage should be Int32
    • CA1045 (Design): Do not pass types by reference
    • CA1056 (Design): URI properties should not be strings
    • CA1501 (Maintainability): Avoid excessive inheritance
    • CA1710 (Naming): Identifiers should have correct suffix
    • CA2000 (Reliability): Dispose objects before losing scope (perhaps this rule should be enabled after it is fixed in Visual Studio 2010).
    • CA2004 (Reliability): Remove calls to GC.KeepAlive
  • Special cases to suppress Code Analysis warnings (case by case):
    • CA1025 (Design): Replace repetitive arguments with params array. Can be suppressed when it makes sense to have more than 3 parameters of the same type but not unlimited number of parameters.
    • CA2227 (Usage): Collection properties should be read only - Can be suppressed only if the Collection is a ReadOnlyCollection<T>.
  • For C++ CLI projects, the following rules exceptions are also allowed:
    • CA2151 (Security): Fields with critical types should be security critical.

Policies

  • Every check-in must be commented.
  • Solution must compile without errors or warnings.
  • All unit tests must pass.
  • Code coverage should be high (90%+).
  • Everything public should be documented (you should get a warning for anything that should be documented but isn't).
  • Work items of significant changes should be created. Significant changes are ones that users can notice (and so should be able to vote for).

Building the documentation

  • Build the entire PcapDotNet solution in release.
  • Download and install Sandcastle Help File Builder 1.9.6.0 using SandcastleInstaller.exe. http://shfb.codeplex.com
  • Open Pcap.Net Sandcastle Help File Builder project file located in the doc folder in the source control.
  • Make sure the version is up-to-date. If not, update it (remember to check out the file and submit it afterwards).
  • Build using Sandcastle Help File Builder.

Releasing a new version

  • Pre-release checklist:
    • Make sure the code compiles with a few warnings as possible (in release).
    • Make sure the code coverage is high.
    • Make sure the code metrics look good.
    • Build the documentation and make sure it looks good.
    • Make sure developer's pack solution compiles with updated 3rdParty binaries.
  • Versioning:
    • Decide on the new version number.
    • PcapDotNet - change the version in all the AssemblyInfo.cs files and in the AssemblyInfo.cpp file.
    • PcapDotNet.DevelopersPack - change the version in all the AssemblyInfo.cs files.
    • Documentation - change the version in the PcapDotNet.shfbproj file (requires manual checkout).
    • Checkin the 22 files (note the new Change Set number).
  • Folders:
    • PcapDotNet.Source.<Version>.<Change Set>
    • PcapDotNet.Binaries.<Version>.<Change Set> containing two folders:
      • PcapDotNet.Binaries.<Version>.<Change Set>.x64
      • PcapDotNet.Binaries.<Version>.<Change Set>.x86
    • PcapDotNet.Documentation.<Version>.<Change Set>
    • PcapDotNet.DevelopersPack.<Version>.<Change Set> containing two folders:
      • PcapDotNet.DevelopersPack.<Version>.<Change Set>.x64 containing doc folder.
      • PcapDotNet.DevelopersPack.<Version>.<Change Set>.x86 containing doc folder.
  • Build:
    • Close any solution opened.
    • Do the following twice, once for x86 and once for x64:
      • Delete the bin folder of PcapDotNet.
      • Build PcapDotNet in release according to the Compiling the code section above.
      • Copy the 12 dll, xml and pdb files (not the Test, TestUtils, CodeAnalysisLog.xml or lastcodeanalysissucceeded files) from the ...\PcapDotNet\bin&lt;Architecture>\Release\ folder to the previously created PcapDotNet.Binaries.<Version>.<Change Set>.<Architecture> folder.
      • Note: only the Core files should be different between the two architectures.
  • Download the Change Set source code and put its contents in the previously created PcapDotNet.Source.<Version>.<Change Set> folder.
  • Create documentation and copy it to the previously created PcapDotNet.Documentation.<Version>.<Change Set> folder.
  • Create Developer's pack:
    • Update the user guide with new versions of examples.
    • Copy the files from PcapDotNet.Source.<Version>.<Change Set> folder to the Developer's Pack folders (PcapDotNet.DevelopersPack.<Version>.<Change Set>.x64, PcapDotNet.DevelopersPack.<Version>.<Change Set>.x86).
    • Copy the files from PcapDotNet.Binaries.<Version>.<Change Set>.x64 folder to PcapDotNet.DevelopersPack.<Version>.<Change Set>.x64\PcapDotNet.DevelopersPack\3rdParty\PcapDotNet folder.
    • Copy the files from PcapDotNet.Binaries.<Version>.<Change Set>.x86 folder to PcapDotNet.DevelopersPack.<Version>.<Change Set>.x86\PcapDotNet.DevelopersPack\3rdParty\PcapDotNet folder.
    • Copy the files from PcapDotNet.Documentation.<Version>.<Change Set> to both Developer's Pack doc folders (PcapDotNet.DevelopersPack.<Version>.<Change Set>.x64\doc, PcapDotNet.DevelopersPack.<Version>.<Change Set>.x86\doc).
    • Delete all of the .vspscc and .vssscc files in the different folders under PcapDotNet.DevelopersPack.<Version>.<Change Set> folder.
  • Copy the license.txt file to PcapDotNet.Documentation.<Version>.<Change Set>, PcapDotNet.Binaries.<Version>.<Change Set> and PcapDotNet.DevelopersPack.<Version>.<Change Set> folders.
  • Zip each folder (PcapDotNet.Source.<Version>.<Change Set>, PcapDotNet.Binaries.<Version>.<Change Set>, PcapDotNet.Documentation.<Version>.<Change Set>, PcapDotNet.DevelopersPack.<Version>.<Change Set>) to create 4 matching zip files.
  • Create a new release:
    • Named it Pcap.Net <Version> (<Change Set>).
    • Copy the description from a previous release and change the necessary sections (use the comments on the different Change Sets to describe the changes).
    • The files should be ordered Developer's Pack, Binaries, Documentation, Source.
    • Developer's Pack is the recommended download.
  • Update NuGet packages. For each architecture (x64 and x86) do the following:
    • Open Pcap.Net.<Architecture>.nupkg.
    • Edit Metadata: Update Version and Release notes.
    • Under lib, remove the net40 directory.
    • Add net40 directory.
    • Add the binaries from the matching PcapDotNet.Binaries.<Version>.<Change Set>.<Architecture> directory.
    • Save.
    • Go to https://www.nuget.org.
    • Upload the Package.

Bugs in other products that were found during the development of Pcap.Net and were fixed:

Windows Bugs

WinPcap Bugs

Wireshark Bugs

Add a custom footer
Add a custom sidebar

Clone this wiki locally