I'm trying to get started with the Umbraco API and seem to have fallen at the first hurdle. All the example articles and forum posts talk about adding a reference to the Umbraco dll's, which is fine, but they don't mention how the code knows which Umbraco instance you're dealing with (I've got several sites installed locally).
For this, presumably a database connection string is required - other people have posted similar queries and the response is to copy the appSetting containing the database connection string from your Umbraco web.config. I tried this but then hit upon other problems as I was trying to run my custom logic within a web page under my Umbraco site, and I think there may have been some problem around the URL rewriting, and I could feel the yak hair starting to accumulate around my ankles.
My question is fairly straightforward. I want to write a simple app to get going with the Umbraco API. This might be a desktop or console app to start with, so what's the minimum I need to configure (references, connection strings etc) before I can start executing calls to the API?
When workign with the Umbraco API in say a .NET usercontrol this is normally placed in the umbraco site that will be running it, so I don't fully understand your question in regards to instance's etc...
Can you please give us an example of what you are trying to do so I can
understand more.
Thanks for your response. In my particular example, I want to develop a custom content migration script. So initially, I'd be looking to programmatically create document types, then content nodes, then user groups and users, and so on. In this case, it wouldn't be necessary to run this process via the Umbraco admin interface, a simple console app or perhaps desktop app that could be used by developers would be fine.
I have seen some examples of people trying to achieve similar things but like I said, most seem to say "just add references to these dll's to your project", but obviously there's more to it than that. When I was talking about instances, I'm set up with about 4 different Umbraco websites on my local IIS, and 4 corresponding databases on my local SQL Server, so if I simply create a new console app and add the necessary Umbraco dll's, it's still going to need to know which 'site' I'm wanting to interact with, so how do I configure that?
I've seen the "umbImport" package, which looks great, but I'm trying to test drive the API for myself outside the context of the Umbraco web application. I wouldn't have thought this was a particularly uncommon scenario?
Appreciate any thoughts on the best way to go with this.
Umbraco is the site (as far as IIS is concerned).. The main content node is id -1.. you can start using the API to build the content from that point.. you can then (via the API).. check the top level content nodes for a domain alias.. this would let you know what "site" you are on.
Sorry, I think you've mis-understood. I'm not using a single Umbraco installation to run multiple sites, I have multiple Umbraco installations running on a single PC. In IIS, there are multiple sites. On my database server, I have multiple DB instances, one for each of these sites. Some are projects I've carried out in the past and are older versions of Umbraco. The latest one I installed is Umbraco 4.5 to check out what the latest features are in the newest release.
So, let's say I create a new console application and add references to the cms.dll, the businesslogic.dll and umbraco.dll to my project. Then I follow one of the examples in the API documentation, let's say to obtain a reference to the root content node (using the ID -1). In my experience the code falls over with null reference exceptions, and I'm not surprised because nowhere in my project have I configured a database connection. So what steps do I take next?
One I've got to the bottom of this I'll be creating a blog post about it because this really seems to be "Umbraco API 101" to me, and I'm surprised there isn't already an article out there which describes how to accomplish this.
One thing to note with current version of umbraco you cannot use api in a console/windows form application as you need httpcontext (core dlls are dependant on httpcontext) you would have to make use of webservices or umbraco base which is rest based api into umbraco there is wiki doc on base also take a look at source code of client tools which has custom webservices to do stuff with umbraco api http://clienttools4umbraco.codeplex.com/
the API depends on httpcontext, i.e. it must run as a part of a site and not a console application.
If you need a console application you can use the umbraco web services instead of the api. If the web services does not support xyz function you can create additional web services, which uses the api. I.e. these web services must be added to the umbraco instance you wish to work with.
Another option for importing content is using the CMSimport package by Richard Soeteman http://our.umbraco.org/projects/developer-tools/cmsimport. My guess is that his package will save you a lot of time. However, it is not console based.
In the past it was impossible to use the API directly from a console app, as you had to have a httpContext to work with. I'm not sure if this has changed in Umbraco v4.5 as there ARE unit tests in place now. However, I suspect it is still not fully possible.
Working with the API is pretty easy through user controls, eventhandler, etc. Have a look at my debugging blog post for a nice and fairly easy setup.
Edit: wow, fast replies over here.. what they said! ;-)
Thanks for all of your replies. I was making the incorrect assumption that the API's could be used from any type of application, so thanks for clearing that up for me. It seems like an odd decision to make the API dependent upon the HttpContext, but there you go.
So I've taken a look at the web services and successfully used the "umbraco/webservices/api/documentService.asmx" to create a new content node from a standalone desktop application, which is progress! As others have observed on these forums, the managed API libraries seem to have considerably more functionality than the web services. For instance, I'd want to create my document types programmatically before even moving onto content nodes, but I can't find any way of doing this via the web services, so it looks like I'm better off creating a new user control (or my own webservice) which uses the API directly.
I'll take a look at some of the links you've suggested and give this approach a shot.
Thanks again for your help. Out of interest, if anyone has any links to documentation on the webservices, I think it would be helpful to make these links known in replies to this thread. For instance, what's the difference between the ones in the api folder and the ones in the parent 'webservices' folder?
Beginner's API question
Hi,
I'm trying to get started with the Umbraco API and seem to have fallen at the first hurdle. All the example articles and forum posts talk about adding a reference to the Umbraco dll's, which is fine, but they don't mention how the code knows which Umbraco instance you're dealing with (I've got several sites installed locally).
For this, presumably a database connection string is required - other people have posted similar queries and the response is to copy the appSetting containing the database connection string from your Umbraco web.config. I tried this but then hit upon other problems as I was trying to run my custom logic within a web page under my Umbraco site, and I think there may have been some problem around the URL rewriting, and I could feel the yak hair starting to accumulate around my ankles.
My question is fairly straightforward. I want to write a simple app to get going with the Umbraco API. This might be a desktop or console app to start with, so what's the minimum I need to configure (references, connection strings etc) before I can start executing calls to the API?
Thanks in advance,
Matt
Hello Matt and welcome to Umbraco.
When workign with the Umbraco API in say a .NET usercontrol this is normally placed in the umbraco site that will be running it, so I don't fully understand your question in regards to instance's etc...
Can you please give us an example of what you are trying to do so I can understand more.
Thanks,
Warren
Hi Warren,
Thanks for your response. In my particular example, I want to develop a custom content migration script. So initially, I'd be looking to programmatically create document types, then content nodes, then user groups and users, and so on. In this case, it wouldn't be necessary to run this process via the Umbraco admin interface, a simple console app or perhaps desktop app that could be used by developers would be fine.
I have seen some examples of people trying to achieve similar things but like I said, most seem to say "just add references to these dll's to your project", but obviously there's more to it than that. When I was talking about instances, I'm set up with about 4 different Umbraco websites on my local IIS, and 4 corresponding databases on my local SQL Server, so if I simply create a new console app and add the necessary Umbraco dll's, it's still going to need to know which 'site' I'm wanting to interact with, so how do I configure that?
I've seen the "umbImport" package, which looks great, but I'm trying to test drive the API for myself outside the context of the Umbraco web application. I wouldn't have thought this was a particularly uncommon scenario?
Appreciate any thoughts on the best way to go with this.
Matt
Content is content is content...
Umbraco is the site (as far as IIS is concerned).. The main content node is id -1.. you can start using the API to build the content from that point.. you can then (via the API).. check the top level content nodes for a domain alias.. this would let you know what "site" you are on.
You can figure out the rest from there.
Hi Daniel,
Sorry, I think you've mis-understood. I'm not using a single Umbraco installation to run multiple sites, I have multiple Umbraco installations running on a single PC. In IIS, there are multiple sites. On my database server, I have multiple DB instances, one for each of these sites. Some are projects I've carried out in the past and are older versions of Umbraco. The latest one I installed is Umbraco 4.5 to check out what the latest features are in the newest release.
So, let's say I create a new console application and add references to the cms.dll, the businesslogic.dll and umbraco.dll to my project. Then I follow one of the examples in the API documentation, let's say to obtain a reference to the root content node (using the ID -1). In my experience the code falls over with null reference exceptions, and I'm not surprised because nowhere in my project have I configured a database connection. So what steps do I take next?
One I've got to the bottom of this I'll be creating a blog post about it because this really seems to be "Umbraco API 101" to me, and I'm surprised there isn't already an article out there which describes how to accomplish this.
Thanks,
Matt
Matt,
One thing to note with current version of umbraco you cannot use api in a console/windows form application as you need httpcontext (core dlls are dependant on httpcontext) you would have to make use of webservices or umbraco base which is rest based api into umbraco there is wiki doc on base also take a look at source code of client tools which has custom webservices to do stuff with umbraco api http://clienttools4umbraco.codeplex.com/
Regards
Isamil
Hi Matt,
If working from a windows app, I'd be more inclined to use the web services exposed from Umbraco than connecting directly with the Umbraco dlls.
It might aslo be worth looking through the source of the client tools package on codeplex to see how they are doing it
http://clienttools4umbraco.codeplex.com/
Matt
Hi Matt,
the API depends on httpcontext, i.e. it must run as a part of a site and not a console application.
If you need a console application you can use the umbraco web services instead of the api. If the web services does not support xyz function you can create additional web services, which uses the api. I.e. these web services must be added to the umbraco instance you wish to work with.
Another option for importing content is using the CMSimport package by Richard Soeteman http://our.umbraco.org/projects/developer-tools/cmsimport. My guess is that his package will save you a lot of time. However, it is not console based.
Hope this helps,
Harald
In the past it was impossible to use the API directly from a console app, as you had to have a httpContext to work with. I'm not sure if this has changed in Umbraco v4.5 as there ARE unit tests in place now. However, I suspect it is still not fully possible.
Working with the API is pretty easy through user controls, eventhandler, etc. Have a look at my debugging blog post for a nice and fairly easy setup.
Edit: wow, fast replies over here.. what they said! ;-)
Hi all,
Thanks for all of your replies. I was making the incorrect assumption that the API's could be used from any type of application, so thanks for clearing that up for me. It seems like an odd decision to make the API dependent upon the HttpContext, but there you go.
So I've taken a look at the web services and successfully used the "umbraco/webservices/api/documentService.asmx" to create a new content node from a standalone desktop application, which is progress! As others have observed on these forums, the managed API libraries seem to have considerably more functionality than the web services. For instance, I'd want to create my document types programmatically before even moving onto content nodes, but I can't find any way of doing this via the web services, so it looks like I'm better off creating a new user control (or my own webservice) which uses the API directly.
I'll take a look at some of the links you've suggested and give this approach a shot.
Thanks again for your help. Out of interest, if anyone has any links to documentation on the webservices, I think it would be helpful to make these links known in replies to this thread. For instance, what's the difference between the ones in the api folder and the ones in the parent 'webservices' folder?
Matt
is working on a reply...