I have recently been assigned to built a DotNetNuke web service to permit a windows application (or any sort of net client for instance) the flexibility to control DotNetNuke person accounts (create, change roles, delete, retrieve e mail address, and so forth.).
Since I had a tough time locating an accurate code sample or documentation that really applies to DotNetNuke 7.3 and accessing it without having being earlier logged in to DotNetNuke, it absolutely was difficult to constructed anything at all. I ultimately found out how to do it properly so I hard I would put my attempts to some use and write a blog publish explaining how you can get it done step by stage.
That said, let's begin by the fundamentals and just create a publicly available web services that permits anybody to ping the net service and acquire a pong again. For that we are going to use the new DotNetNuke 7 Providers Framework which makes it fairly simple should you know how to utilize it.
In order to create a net support that will work within DotNetNuke 7, you will need to fireplace up Visual Studio and create a class Library project (c# or VB but all illustrations listed here will be in c#).
That done, we will then reference some needed DotNetNuke 7 required libraries (making use of the Add Reference dialog box), here's the list:
DotNetNuke.dll
DotNetNuke.Web.dll
System.Net.Http.dll
System.Net.Http.Formatting.dll
System.Web.Http.dll
Then we also need to reference the System.Web class from the .NET tab of the same dialog box.
Finally, we neet to set the output path of the project to the DotNetNuke bin directory and we are ready to code.
Here is the code, the explanations follow:
using System.Net;
using System.Net.Http;
using System.Web.Http;
using DotNetNuke.Web.Api;
namespace MyService
{
public class PingController : DnnApiController
{
[AllowAnonymous]
[HttpGet]
public HttpResponseMessage PublicPing()
{
return Request.CreateResponse(HttpStatusCode.OK, "Pong!");
}
}
public class RouteMapper : IServiceRouteMapper
{
public void RegisterRoutes(IMapRoute mapRouteManager)
{
mapRouteManager.MapHttpRoute("MyService", "default", "{controller}/{action}", new[]{"MyService"});
}
}
}
- We merely start with some using statements for our needs as demonstrated previously mentioned
- We develop a namespace for our service and no matter what name we use listed here will be part of the url. I utilized MyService just for this instance but use any name which makes perception for your services.
- Now we create a public class for our controller. You'll be able to create numerous controllers if you want to and the controller is just a bunch of related actions that make feeling to group with each other. In my genuine project I have a PingController for testing functions, a UsersController for almost any steps that relate to user accounts and so forth. Just utilize a identify that makes feeling because it will even present up in the url. Two things for being careful right here:
- The identify of one's controller should end using the term Controller but only what will come just before it will show inside the url, so for PingController, only Ping will show in the url route.
- It should inherit DnnApiController so it'll use the DotNetNuke Providers Framework.
- Then we create the actual motion, inside our case, PublicPing. It's just a straightforward technique which return an HttpResponseMessage and may have a handful of characteristics. By default the brand new providers framework will respond only to host consumers and you also must explicitly enable other access rights if necessary, in this case the [AllowAnonymous] helps make this technique (or action if you prefer) obtainable to anyone with out credentials. The next attribute, [HttpGet] can make this action reply to HTTP GET verb, which can be usually used when requesting some date in the web server.
- Finally in that action, you insert whatever code you action needs to do, in this case just return the string "Pong!", just remember that you should return an HttpResponseMessage rather than a string or int or other item.
Ok so our controller and motion is done, now we just need to map that to an actual URL and that exactly what the final portion of the earlier code does. In essence this code tells DotNetNuke to map a specific url pattern for the techniques outlined in your course. You can use that code as is simply replacing MyService by no matter what your support title is.
Testing:
That is all there is certainly to it, your services is prepared! To test it, first compile it, then just navigate to http://yourdomain/DesktopModules/MyService/API/Ping/PublicPing and you should see "Pong!" inside your browser like a response.
Passing parameters
Ok, so the basic code above is working but it doesn't do anything useful. Lets add something more useful by creating an action that will give us the email address for a specific user id.
Again, here's the code and the explanations will follow (place the code inside the same namespace as the previous one):
public class UsersController : DnnApiController
{
[RequireHost]
[HttpGet]
public HttpResponseMessage GetEmail(int userid)
{
DotNetNuke.Entities.Users.UserInfo ui;
ui = DotNetNuke.Entities.Users.UserController.GetUserById(PortalSettings.PortalId, userid);
return Request.CreateResponse(HttpStatusCode.OK, ui.Email);
}
}
Initial we build a UsersController course which will hold all actions related to person accounts, it isn't completely required, you'll be able to have numerous steps within the same controller, nonetheless because this motion is not in any respect connected to our PingController, let'a create a new one more descriptive.
We then create a GetEmail motion (method) which will accept a userid parameter. The [RequireHost] parameter listed here will make it accessible only to host customers, we are going to see afterwards other authentication options.
The code inside the approach alone is fairly significantly self explanatory. The only interesting factor to notice listed here is the fact that because our course inherits DnnApiController, we already have a PortalSettings item obtainable. That is the big benefit of producing use of the DotNetNuke Solutions Framework. You'll have a ModuleInfo object to represent your module (if there is 1 using the identical identify as your support, which can be not essential such on this scenario), a PortalSettings object that signifies the portal at the domain title utilized to accessibility the support (portal alias) and at last a UserInfo item symbolizing the person that accessed the web services.
Testing:
If we now navigate to http://yourdomain/MyService/API/Users/GetEmail?userid=2 you need to receive the email tackle back again from the server unless of course obviously that userid does not exist, ensure that you check having a userid that truly exists for that portal. Should you exactly where not formerly linked having a host account, you then will probably be requested for qualifications.
Limiting access to particular roles
Alright, that actually works however, you need to give host qualifications to anyone needing to make use of your webservice. To avoid which you can change [RequireHost] by [DnnAuthorize(StaticRoles="Administrators")] which can limit access to administrators. Much better however, you nevertheless must provide them with an admin account. So the easy method to give only constrained entry would be to create a brand new role in DotNetNuke only for your internet services and substitute Administrators by that specific function title within the authentication parameter.
Utilizing HttpPost : (reply to a comment down bellow)
To answer Massod comment bellow, it's nearly exactly the same thing however, you have to develop an object to contain the posted information.
Let's make a easy ping that makes use of Submit, very first we need to create an object which will contain the posted info this sort of as:
public class FormMessage
{
public string Message { get; set; }
}
Then we create the service method something like this:
public class PingController : DnnApiController
{
[AllowAnonymous]
[HttpPost]
public HttpResponseMessage PostPing(FormMessage formMessage)
{
return Request.CreateResponse(HttpStatusCode.OK, "Pong from POST: message was '" + formMessage.Message + "'.");
}
}
note that normally, a post would only return ok and no message, I am just doing this so we can test here.
Now since this is a POST verb, we can't test it by only using url parameters, we need to make an html file with a form to test it out. It would be someting like this:
http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
<title>Untitled Pagetitle>
head>
<body>
<form action="http://dnndev/DesktopModules/MyService/API/Ping/PostPing" method="POST">
<label for="message">Message: label><input type="text" name="Message"/>
<input type="submit" value="Submit"/>
form>
body>
html>
The crucial thing to not right here is you can not just develop your Publish technique taking a string even when this can be only what you require, you do must create an object which will get your parameters.
Also never overlook that this is only for tests, you usually do not need to make this publicly accessible, you'd probably usually use yet another parameter than [AllowAnonymous] such as [DnnModuleAuthorize(AccessLevel = SecurityAccessLevel.View)] and [ValidateAntiForgeryToken] unless you truly want that for being public.