ºÝºÝߣ

ºÝºÝߣShare a Scribd company logo

NuGet (Anti-)Patterns - Tales from the Trenches

?Download as PPTX, PDF?
?
Xavier Decoster
Xavier Decoster

This document contains a presentation on NuGet packaging best practices and anti-patterns. The presentation discusses 9 NuGet packaging patterns and anti-patterns: 1) Using package restore, 2) Following semantic versioning, 3) Avoiding 3-dot versioning, 4) Maintaining a smooth upgrade path, 5) Splitting package repositories by audience, 6) Not deleting packages after publishing, 7) Having a fallback repository, 8) Looking for binding redirects, and 9) Ensuring uninstall leaves no traces. The presentation was given by Xavier Decoster and provides guidance on developing high-quality NuGet packages.

1 of 17
Download to read offline
www.realdolmen.com NUGET (ANTI-)PATTERNS: TALES FROM THE TRENCHES JANUARY 16, 2013 | SLIDE 1
WHO AM I? Xavier Decoster Antwerp, Belgium Technical Consultant, RealDolmen Co-founder of MyGet.org Microsoft Extended Experts Team Author of Apress Pro NuGet http://www.xavierdecoster.com @xavierdecoster JANUARY 16, 2013 | SLIDE 2
IN THIS SESSION JANUARY 16, 2013 | SLIDE 3
IN THIS SESSION JANUARY 16, 2013 | SLIDE 4
#0 ¨C USE PACKAGE RESTORE ? A source repository is for ¡­ sources ? What¡¯s a package repository for? ? Impact of package restore ? No more duplication of same binaries ? Less merge conflicts (no binary diff) ? Maintain overview of consumed packages in single place ? Less network I/O (NuGet cache) ? Contra-argument: single point of failure ? Good remark: now deal with it! ? Disconnected from package source(s)? JANUARY 16, 2013 | SLIDE 5
#1 ¨C USE SEMANTIC VERSIONING Major Breaking changes Minor Backwards compatible API additions/changes Patch Bugfixes not affecting the API PreRelease Tag Alpha, Beta, ¡­, RC1, RC2, ¡­ Build Build stamp, metadata, ¡­ ? NuGet versioning algorithm differs from SemVer SemVer NuGet v x SemVer Versioning Scheme major.minor.patch[-prerelease][+build] v v NuGet pre-release package major.minor.patch-prerelease v v NuGet release package major.minor.patch x v Legacy Versioning Scheme major.minor.build.revision JANUARY 16, 2013 | SLIDE 6
#2 ¨C DON¡¯T USE 3-DOTS VERSIONING ? Even though NuGet supports it ? Not supported in SemVer ? Not supported in combination with pre-release tag ? Instead use 2-Dots SemVer notation ? Optionally with pre-release tag JANUARY 16, 2013 | SLIDE 7
#3 ¨C MAINTAIN A SMOOTH UPGRADE PATH ? Don¡¯t change Package ID along the way! ? Your packages will get stuck ? So will your consumers JANUARY 16, 2013 | SLIDE 8
#3 ¨C MAINTAIN A SMOOTH UPGRADE PATH MyGet.Core MyGet.Core ¡­ 1.0.1-alpha00001 1.0.1-alpha00256 MyGet.Core 1.0.1-alpha MyGet.Core 1.0.1 ? Version Precedence ? 1.0.1-alpha00001 < 1.0.1-alpha00256 < 1.0.1-alpha < 1.0.1 ? Question: Where does 1.0.1-alpha2 fit? ? Don¡¯t change Package ID along the way! JANUARY 16, 2013 | SLIDE 9
#4 ¨C SPLIT PACKAGE REPOSITORIES BY AUDIENCE MyGet.Core MyGet.Core ¡­ 1.0.1-alpha00001 1.0.1-alpha00256 MyGet.Core 1.0.1-alpha MyGet.Core 1.0.1 ? Don¡¯t pollute consumers¡¯ repository with your internal DEV builds ? MyGet.org is great at this: set up as many feeds as you want and promote packages from one to another (including nuget.org!) JANUARY 16, 2013 | SLIDE 10
#5 ¨C ONCE PUBLISHED, DON¡¯T DELETE PACKAGES ? Unlist packages instead! ? Maintains upgrade path ? Still available through package restore ? Supported by NuGet.org and MyGet.org ? Using own NuGet server or file share? ? Remove user permissions to delete! ? Deleting ? Breaks package restore! ? Forces consumers to upgrade! ¡°Attempting to force a user to do something is both an exercise in futility and a great way to guarantee that you have less users overall¡± - Rob Reynolds JANUARY 16, 2013 | SLIDE 11
#6 ¨C HAVE A FALLBACK REPOSITORY ? Backup consumed packages ? Mirror them on MyGet.org ? Download them ? Especially when using Package Restore ? From NuGet.org ? From any external feed ? Each consumer has local cache ? %LocalAppData%NuGetCache JANUARY 16, 2013 | SLIDE 12
#7 ¨C LOOK FOR BINDING REDIRECTS ? Mitigates potential risk for conflicts ? During assembly resolution <configuration> <runtime> <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"> <dependentAssembly> <assemblyIdentity name="myAssembly" publicKeyToken="32ab4ba45e0a69a1" culture="neutral" /> <bindingRedirect oldVersion="1.0.0.0" newVersion="2.0.0.0"/> </dependentAssembly> </assemblyBinding> </runtime> </configuration> ? Investigate why ? Package versions not aligned? Package upgrades & version alignment can reduce the number of binding redirects JANUARY 16, 2013 | SLIDE 13
#8 ¨C USE SAMPLE PACKAGE OR README.TXT ? Don¡¯t pollute your actual packages ? Provide a readme.txt ? If you can¡¯t automate the manual instructions ? If you want to have your consumers read some specific info ? Automatically presented to consumer during installation ? Use a sample package when appropriate ? Separate package ? Different package ID ? Convention: {packageID}.Sample ? E.g.: NUnit ? NUnit.Sample ? Sample package depends on actual package you want to ship JANUARY 16, 2013 | SLIDE 14
#8 ¨C USE SAMPLE PACKAGE OR README.TXT JANUARY 16, 2013 | SLIDE 15
#9 ¨C UNINSTALL SHOULD LEAVE NO TRACES ? Obvious, but often neglected/forgotten ? Be a good citizen ? Uninstall reverses installation + any side-effects ? Unless modifications happened ? Uninstall ? Any files copied (binaries, sources, content, scripts¡­) ? Tools package: any system modifications (PowerShell modules, registry keys, environment variables¡­) JANUARY 16, 2013 | SLIDE 16
http://www.xavierdecoster.com @xavierdecoster THANK YOU! Questions? Come get your MyGet stickers, you might get lucky! ? JANUARY 16, 2013 | SLIDE 17

More Related Content

NuGet (Anti-)Patterns - Tales from the Trenches

  • 1. www.realdolmen.com NUGET (ANTI-)PATTERNS: TALES FROM THE TRENCHES JANUARY 16, 2013 | SLIDE 1
  • 2. WHO AM I? Xavier Decoster Antwerp, Belgium Technical Consultant, RealDolmen Co-founder of MyGet.org Microsoft Extended Experts Team Author of Apress Pro NuGet http://www.xavierdecoster.com @xavierdecoster JANUARY 16, 2013 | SLIDE 2
  • 3. IN THIS SESSION JANUARY 16, 2013 | SLIDE 3
  • 4. IN THIS SESSION JANUARY 16, 2013 | SLIDE 4
  • 5. #0 ¨C USE PACKAGE RESTORE ? A source repository is for ¡­ sources ? What¡¯s a package repository for? ? Impact of package restore ? No more duplication of same binaries ? Less merge conflicts (no binary diff) ? Maintain overview of consumed packages in single place ? Less network I/O (NuGet cache) ? Contra-argument: single point of failure ? Good remark: now deal with it! ? Disconnected from package source(s)? JANUARY 16, 2013 | SLIDE 5
  • 6. #1 ¨C USE SEMANTIC VERSIONING Major Breaking changes Minor Backwards compatible API additions/changes Patch Bugfixes not affecting the API PreRelease Tag Alpha, Beta, ¡­, RC1, RC2, ¡­ Build Build stamp, metadata, ¡­ ? NuGet versioning algorithm differs from SemVer SemVer NuGet v x SemVer Versioning Scheme major.minor.patch[-prerelease][+build] v v NuGet pre-release package major.minor.patch-prerelease v v NuGet release package major.minor.patch x v Legacy Versioning Scheme major.minor.build.revision JANUARY 16, 2013 | SLIDE 6
  • 7. #2 ¨C DON¡¯T USE 3-DOTS VERSIONING ? Even though NuGet supports it ? Not supported in SemVer ? Not supported in combination with pre-release tag ? Instead use 2-Dots SemVer notation ? Optionally with pre-release tag JANUARY 16, 2013 | SLIDE 7
  • 8. #3 ¨C MAINTAIN A SMOOTH UPGRADE PATH ? Don¡¯t change Package ID along the way! ? Your packages will get stuck ? So will your consumers JANUARY 16, 2013 | SLIDE 8
  • 9. #3 ¨C MAINTAIN A SMOOTH UPGRADE PATH MyGet.Core MyGet.Core ¡­ 1.0.1-alpha00001 1.0.1-alpha00256 MyGet.Core 1.0.1-alpha MyGet.Core 1.0.1 ? Version Precedence ? 1.0.1-alpha00001 < 1.0.1-alpha00256 < 1.0.1-alpha < 1.0.1 ? Question: Where does 1.0.1-alpha2 fit? ? Don¡¯t change Package ID along the way! JANUARY 16, 2013 | SLIDE 9
  • 10. #4 ¨C SPLIT PACKAGE REPOSITORIES BY AUDIENCE MyGet.Core MyGet.Core ¡­ 1.0.1-alpha00001 1.0.1-alpha00256 MyGet.Core 1.0.1-alpha MyGet.Core 1.0.1 ? Don¡¯t pollute consumers¡¯ repository with your internal DEV builds ? MyGet.org is great at this: set up as many feeds as you want and promote packages from one to another (including nuget.org!) JANUARY 16, 2013 | SLIDE 10
  • 11. #5 ¨C ONCE PUBLISHED, DON¡¯T DELETE PACKAGES ? Unlist packages instead! ? Maintains upgrade path ? Still available through package restore ? Supported by NuGet.org and MyGet.org ? Using own NuGet server or file share? ? Remove user permissions to delete! ? Deleting ? Breaks package restore! ? Forces consumers to upgrade! ¡°Attempting to force a user to do something is both an exercise in futility and a great way to guarantee that you have less users overall¡± - Rob Reynolds JANUARY 16, 2013 | SLIDE 11
  • 12. #6 ¨C HAVE A FALLBACK REPOSITORY ? Backup consumed packages ? Mirror them on MyGet.org ? Download them ? Especially when using Package Restore ? From NuGet.org ? From any external feed ? Each consumer has local cache ? %LocalAppData%NuGetCache JANUARY 16, 2013 | SLIDE 12
  • 13. #7 ¨C LOOK FOR BINDING REDIRECTS ? Mitigates potential risk for conflicts ? During assembly resolution <configuration> <runtime> <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"> <dependentAssembly> <assemblyIdentity name="myAssembly" publicKeyToken="32ab4ba45e0a69a1" culture="neutral" /> <bindingRedirect oldVersion="1.0.0.0" newVersion="2.0.0.0"/> </dependentAssembly> </assemblyBinding> </runtime> </configuration> ? Investigate why ? Package versions not aligned? Package upgrades & version alignment can reduce the number of binding redirects JANUARY 16, 2013 | SLIDE 13
  • 14. #8 ¨C USE SAMPLE PACKAGE OR README.TXT ? Don¡¯t pollute your actual packages ? Provide a readme.txt ? If you can¡¯t automate the manual instructions ? If you want to have your consumers read some specific info ? Automatically presented to consumer during installation ? Use a sample package when appropriate ? Separate package ? Different package ID ? Convention: {packageID}.Sample ? E.g.: NUnit ? NUnit.Sample ? Sample package depends on actual package you want to ship JANUARY 16, 2013 | SLIDE 14
  • 15. #8 ¨C USE SAMPLE PACKAGE OR README.TXT JANUARY 16, 2013 | SLIDE 15
  • 16. #9 ¨C UNINSTALL SHOULD LEAVE NO TRACES ? Obvious, but often neglected/forgotten ? Be a good citizen ? Uninstall reverses installation + any side-effects ? Unless modifications happened ? Uninstall ? Any files copied (binaries, sources, content, scripts¡­) ? Tools package: any system modifications (PowerShell modules, registry keys, environment variables¡­) JANUARY 16, 2013 | SLIDE 16
  • 17. http://www.xavierdecoster.com @xavierdecoster THANK YOU! Questions? Come get your MyGet stickers, you might get lucky! ? JANUARY 16, 2013 | SLIDE 17

Editor's Notes

  • #6: Even ifyoudon¡¯tuseyourown package repository, youshould have a fallbackrepositorywithbackup of allused packages¡­DEMO: package restoreDisable internet connectivityand show how the cache canbeused as a fallbackExplain a fallbackrepositoryshouldbemaintainedifusingprimarilyexternalpackage sources