How SymbolSource integrates with NuGet and MyGet

There has been some confusion around how symbolsource.org shares user names, repository names, keys and permissions with nuget.org and myget.org. Today's post will hopefully clear that up.

Pure SymbolSource

None of you will probably remember or know that, but SymbolSource launched a few months before NuGet or even OpenWrap. In the beginning symbol and source uploads where done through a web form taking a regular ZIP file. Third-party uploads were rare so most of the time we just created those ZIP files ourselves and uploaded them to the Default repository. If there are any of you still refusing to jump on the package manager bandwagon, you can have us store symbols in that repository even today, e.g. for binaries published by some old-school method like a POZFWS (Plain Old Zip File on a Web Site). Maybe we'll even enable our old upload form again?

It's an absolutely useless fact by now, but having had all those binaries online, we even thought about creating some means of ditribution for them, including a Visual Studio plugin. Sounds familiar? Enough to say that when we discovered OpenWrap and NuGet, all prototype work on that feature was thrown away and instead we set out to integrate with the at the time newly published package managers.

So what does our data and permission model look like?

First of all we have the notion of instances, or companies. Most of the time you'll be using the Public instance, but we also host separate instances for MyGet and for our clients as a SaaS offering. An instance comes with its own users and repositories.

I already mentioned the Default repository, but we also host separate repositories for NuGet and OpenWrap. It's a matter of avoiding name-conflicts and having everything neatly organized. These repositories are open for read access, but pushing packages requires additional permissions - and more on that later. If you have an account on symbolsource.org you can also create private repositories, which will be prefixed with your user name to make them unique. In that case you have total control over read and write access - you can grant those rights using our website to any other user of SymbolSource (or to the public user, which makes them available without authentication).

In a separate instance, a company admin user is allowed to create any number repositories with arbitrary names. Did you know that since a week or so, you can have a company account created automatically by simply filling out a form?

You might also like the fact that in SymbolSource you can assign permissions on each level: company, repository or project (which is the equivalent of a package in NuGet), and that they are inherited accordingly.

Integration with NuGet

That was probably enough boring history and theory already, so I'll skip to how integration with nuget.org works today.

When you publish symbol packages to our NuGet endpoint, which is http://nuget.gw.symbolsource.org/Public/NuGet, you are pushing to the Public instance and NuGet repository. You could also push to your own repository with an URL like this: http://nuget.gw.symbolsource.org/Public/Private.TripleEmcoder.Secret, but be sure to create it on the website first.

Whereas a private repository is under your control, the NuGet repository is configured to verify permissions on each upload with nuget.org - using the API key supplied by the user on the nuget.exe command-line. You are only allowed push if nuget.org confirms that the API key belongs to an account listed as one of the package owners.

An interesting feature is that you don't even need to create an account on symbolsource.org to push NuGet symbol packages - we'll create one for you automatically, but since we can't figure out your user name from the upload alone, and we won't ask nuget.org to provide one for privacy reasons, this new account will have a generated name. At any time you are welcome to create a real account and associate your API key - we'll move all your previous uploads under the new account automatically. Registering gives you the additional benefits of reviewing upload reports for possible symbol issues and managing package versions.

After uploading a symbol package with NuGet and logging into SymbolSource you might notice that your package ownership is mirrored on the Authorization page. This allows you to browse upload reports for those projects, and also manage individual versions, by going to the NuGet repository and hiding or deleting them. Hiding is similar to nuget.org's unlisting - it removes a version from public display, but still allows symbols to be downloaded with Visual Studio.

Integration with MyGet

Because myget.org is quite a different beast than nuget.org, we also have a different integration model for it. To support multiple MyGet repositories, and a separate user base, SymbolSource hosts a MyGet company that is managed by myget.org using our Web Service APIs. Each MyGet user and repository automatically gets its counterpart on SymbolSource, so you don't need to do anything, apart from checking out MyGet Feed Details to discover what your push URL for symbol packages is and how to configure Visual Studio to download PDBs from your repositories. Your account's API key will enable you to push to both MyGet and SymbolSource, just as with NuGet.

You can also share MyGet symbol repositories with others - just add other people under MyGet Feed Security and our sync process will take care of the rest.

If you'd like to benefit from our website's features at the same time, just edit your MyGet Profile to set up and password and after a moment you'll be able to log into SymbolSource MyGet instance

Quick command cheatsheet

With all those different endpoint being pushed to, it is very useful to store your API key. Here's a quick cheatsheet of the commands needed for that:

  • Storing your nuget.org key, which also enables pushing to symbolsource.org:

    nuget.exe setapikey <nuget-key>

  • Storing your myget.org key:

    nuget.exe setapikey <myget-key> -Source https://www.myget.org/F/<feed-name>

  • Storing your myget.org key for symbolsource.org (this one you need to do explicitly):

    nuget.exe setapikey <myget-key> -Source https://nuget.gw.symbolsource.org/MyGet/<feed-name>

And while we're at it, it's also worth mentioning all the push commands:

  • Pushing a package to nuget.org (a symbol package will be detected and pushed to symbolsource.org automatically):

    nuget.exe push <package-file>

  • Pushing a symbol package to symbolsource.org explicitly (if you want to test it first):

    nuget.exe push <package-file> -Source https://nuget.gw.symbolsource.org/Public/NuGet

  • Pushing a package to myget.org:

    nuget.exe push <package-file> -Source https://www.myget.org/F/`

  • Pushing a symbol package to symbolsource.org:

    nuget.exe push <package-file> -Source https://nuget.gw.symbolsource.org/MyGet/<feed-name>

Unfortunately at the moment nuget.exe requires you to be very specific about the URLs, and the SymbolSource endpoint is only hardcoded in for nuget.org. It would be great if it could do symbol package autodetection and pushing also in case of myget.org feeds. If you find this a nice idea, have a look at this discussion and vote on this issue. Ideally that would also enable you to set up pairs of internal NuGet.Server and SymbolSource.Server.Basic repositories.

Other integration possibilites

As you can see our data model is quite flexible, and the fact that all the endpoints (website, NuGet, OpenWrap) are build around our Web Service APIs gives us a lot of possibilities. For example, we've always liked the idea of commercial third-party library and component vendors enabling source access using our platform instead of downloadable ZIP files. Our APIs allow adjusting symbol and source access in real-time from any e-commerce platform controlling sales and licencing.

As always we're eager to receive your comments and feedback!

Posted by Marcin Mikołajczak (TripleEmcoder) on Wednesday, August 22, 2012

blog comments powered by Disqus