From b734061b13582cf581a16915a162448064ebd73e Mon Sep 17 00:00:00 2001 From: Akos Nagy Date: Fri, 4 May 2018 14:21:22 +0200 Subject: [PATCH] Submodule & readme update --- CosmosDbAdoNetProvider | 2 +- README.md | 116 +++++++---------------------------------- 2 files changed, 20 insertions(+), 98 deletions(-) diff --git a/CosmosDbAdoNetProvider b/CosmosDbAdoNetProvider index b7fa28a..a400fe9 160000 --- a/CosmosDbAdoNetProvider +++ b/CosmosDbAdoNetProvider @@ -1 +1 @@ -Subproject commit b7fa28a1d718801771b0a81d26cd23219f598cf9 +Subproject commit a400fe917dcbabb4e3b6bf59322472b30383f91b diff --git a/README.md b/README.md index 3f7a151..9ea8b81 100644 --- a/README.md +++ b/README.md @@ -1,114 +1,36 @@ -# Azure DocumentDb LinqPad Driver +# Azure CosmosDb LinqPad Driver -This is a LinqPad data context driver for Azure DocumentDb -(now rebranded as CosmosDb). +This is a LinqPad data context driver for Azure CosmosDb -You can check out my blogpost on the making of the driver: +Check out my blogposts on the making of the driver: -[http://www.dotnetfalcon.com/linqpad-documentdb-now-cosmosdb-driver/](http://www.dotnetfalcon.com/linqpad-documentdb-now-cosmosdb-driver/) +[http://dotnetfalcon.com/tag/linqpad/](http://dotnetfalcon.com/tag/linqpad/) ## Download the binaries -If you want, you can just go ahead and download the binaries from my blog or directly from these links: +If you want, you can just go ahead and download the latest binaries from my blog or directly from these links: -* [Driver package](https://dotnetfalconcontent.blob.core.windows.net/linqpad-documentdb-now-cosmosdb-driver/AzureDocumentDbDriver.lpx) -* [Static driver helper class library](https://dotnetfalconcontent.blob.core.windows.net/linqpad-documentdb-now-cosmosdb-driver/ContextLibrary.dll) +* [Driver package](https://dotnetfalconcontent.blob.core.windows.net/linqpad-cosmosdb-driver/v2-0-0-0/AzureCosmosDbDriver.lpx) +* [Static driver context backend class library](https://dotnetfalconcontent.blob.core.windows.net/linqpad-cosmosdb-driver/v2-0-0-0/CosmosDbContext.dll) -## Build and run - -You can fork or clone the repo and modify the source code if you want. -For testing, I suggest you take a look at the [official documentation](http://www.linqpad.net/Extensibility.aspx) -on how to write drivers. - -I created a DevDeploy.bat and a ReleaseDeploy.ps1, both of which are included -in the repo, they handle automatic packaging for release mode and copy -the output into the right folders for debug mode. They are added by default as build actions. If you want, you -can disable them or add your own. - -**Note**: LinqPad creates a folder for the drivers and the folder name -includes the public part of the signing key, if the driver is signed. I signed -the driver with a self-signed pfx just for fun, but I didn't upload it. -So in order to build the project, first disable signing the assembly, and then -modify the build scripts so that they copy the unsigned dlls (see the official -documentation on how). - -## Contribution - -Any ideas are welcome. Also if you discover any issues, feel free to create a ticket. -If you decide to contribute, PRs are welcome. - ## Features -### Static driver - -A static driver uses a prebuilt dll that you have to load to discover the data source and run the queries. -To help you get started, I created a class library called ContextLibrary. You can use the base classes and methods in this class library to build your static driver data context, load it into LinqPad and get querying. I included some samples on how to use it -in the StaticDriverDataContext project. - -### Dynamic driver - -I implemented a dynamic driver too, but since there's no schema or structure -wahtsorever to be discovered automatically by the driver, some sacrificies were -necessary. The most important one being the fact the everything runs on the client side. -If you create a query against a collection, the contents of the collection are downloaded and then you are essentially making Linq-to-objects queries. - -The problem comes from the fact that in order to support a schemaless structure, dynamic have to be used. But Linq and dynamic don't really mix well (expression trees cannot contain dynamic references) so I had to get creative and this is what I came up with. Go ahead and check out the source code; if you have a better idea, suggestions and PRs are welcome. - - -### Querying collections with Linq - -If you load up the driver and connect to a data source, the driver automatically discovers the collections that are available and you can run queries against them: - -![](https://dotnetfalconcontent.blob.core.windows.net/linqpad-documentdb-now-cosmosdb-driver/collections.png) - -If you use the dynamic driver, as mentioned before, you are basically running Linq-to-objects queries against the downloaded contents of the collection. If you use the static driver, then the queries you create are executed on the server-side. - -![](https://dotnetfalconcontent.blob.core.windows.net/linqpad-documentdb-now-cosmosdb-driver/collection_query.png) +For a detailed description of the currently supported features, please refer to the project [Wiki](https://github.com/conwid/AzureDocumentDbDriver/wiki). -As a bonus, if you right-click on a collection, you have all sorts of shortcuts to execute queries: +* Static datacontext driver that you can use if you have a prebuilt context using my context library +* Dynamic datacontext driver if you want to et started fast +* Querying CosmosDb document collections using LInQ with all the LinqPad integration that you like +* Running CosmosDb stored procedures +* Running CosmosDb UDFs +* Support for executing raw SQL queries in the raw SQL LinqPad window +* Support for executing raw SQL queries from the C# windows +* Support for setting the FeedOptions for the underlying queries +* Populating the SQL translation tab -![](https://dotnetfalconcontent.blob.core.windows.net/linqpad-documentdb-now-cosmosdb-driver/collection_context.png) - -### Stored procedures and user-defined functions -Both the static and the dynamic drivers support stored procedures and user defined functions (though a little differently). - -First off, they are listed in the browser window: - -![](https://dotnetfalconcontent.blob.core.windows.net/linqpad-documentdb-now-cosmosdb-driver/splist.png) - -Second, you can run an sp if you want either by typing the call manually, or right-clicking the sp name in the browser and importing the call into the editor window. The results are then displayed in a table form: - -![](https://dotnetfalconcontent.blob.core.windows.net/linqpad-documentdb-now-cosmosdb-driver/sp_run.png) - -Parameters are also supported. - -Since the results of the sp are loaded into memory, you can go ahead and use Linq-to-objects to query your data. - -![](https://dotnetfalconcontent.blob.core.windows.net/linqpad-documentdb-now-cosmosdb-driver/sp_run_filter.png) - -If you use the dynamic driver, you don't really need to do anything. If you use the static driver, you have to create a method with the name of the SP that returns IQueryable (T is your type that you are querying) and inside the method call the CreateStoredProcedure() method (you can check out the Github sample for more). -UDFs are also supported — you can run them as an SQL query (see below). - -And the nice addition: if you hover over an sp or udf, you can check out their code: - -![](https://dotnetfalconcontent.blob.core.windows.net/linqpad-documentdb-now-cosmosdb-driver/sp_hover.png) - -### SQL support - -Here's the coolest of all: if you change your language to SQL, you can run DocumentDB sql queries directly from LinqPad and see the results in the table. - -![](https://dotnetfalconcontent.blob.core.windows.net/linqpad-documentdb-now-cosmosdb-driver/sql.png) - -The syntax is almost entirely coherent with that of DocumentDb. The only difference is that you have to first specify the collection, against which you'd like to run the query (note that cross-collection queries are not supported, so this is not really a problem). - -## Roadmap -Here's a couple of features that I would like to add in the future (if you want to help, feel free to submit a PR on Github): +## Contribution -* Nicer connect dialog: It would be nice if you could just connect to your Azure subscription and then select the data source from a treeview or something. -* Populating the SQL window: DocumentDb Linq queries are compiled to data source specific queries, just like in the case of Linq-to-Entities or every other Linq-based query API. LinqPad has a tab to display the generated data source specific query from the Linq query — hooking this up would be a nice addition. -* Trying to find ways the push even more things to the server side. I'm not sure how much of this is possible, but this is part of a continuous improvement process (not that critical though — my experience is people usually only use LinqPad for fiddling, and for that convenience is a more important factor than performance). -* Maybe the ADO.NET provider could be extended to support more features, not just the ones that LinqPad currently uses. +Every idea, issue or improvement is welcome. If you want to contribute, join the discussions under the issues or read the [Wiki](https://github.com/conwid/AzureDocumentDbDriver/wiki) on how to contribute and issue a PR. ## Disclaimer and license notes