We’ve just shipped the first betas of RemObjects SDK and Data Abstract 9.0, the next major new release of our remoting and multi-tier frameworks.
One of the big new features coming in RemObjects SDK 9, and the one I want to talk about today, is support for what we call “Code First” Servers.
What is “Code First”?
In the past, if you created a new RemObjects SDK server, you started with a RODL file, and would edit that in Service Builder to define all the services and the types that the services worked with. Behind the scenes, RO would then generate code and stub classes for your service implementation for you.
While this mode of creating servers will of course continue to be supported, “Code First” mode does away with RODL files completely — at least on the server — and lets you define everything purely in code.
You simply define your service classes and attach a couple of attributes to make them available remotely, and RemObjects SDK will take care of the rest and make sure they become callable. Similarly, any auxiliary types you define – enums, structs, etc. – you can simply define (and update) in code.
At runtime, RemObjects SDK will generate a RODL representation of your services based on the types it finds in your app and make that available to download for clients. So to the outside, a Code-First looks identical to a traditional RODL-driven server, and for the use on the client, you can still import the (now auto-generated) RODL from your IDE or the codegen tool to generate client Interface stubs.
In the current beta, Code-First servers are supported on .NET, but we plan to make the same functionality available in (newer versions of) Delphi, as well.
Let’s take a look at how this works in practice.
Converting an Existing Server
Since most of you will be starting out with existing RO servers already, let’s have a look at what is involved with converting one to the new model. Mind you, you don’t have to convert your servers to Code-First in order to use RO9. This is not a breaking change, just a new option. Still, I expect many of you will want to move to the new model, because it makes development so much easier going forward. I already converted two of my own projects.
There are really just four steps involved in making the switch, all of them simple, and two of them automated:
- Adjust your existing Service implementations
- Convert our auxiliary types, such as structs and enums
- Remove your RODL file and the auto-regenerating _Intf, _Invk and _Events files generated from it
- Add one statement of code to configure your server for Code-First
Adjusting Your Existing Services
While RO auto-generates service stubs for you from RODL, once you add code to those files, we consider them “yours”, and the RO toolchain won’t touch them. In the past, that was one of the annoyances when adding new methods to a service, as you had to edit both the RODL and the implementation.
For that same reason, we won’t auto-convert your service implementations for you, but making the switch is easy. For each of your services, you just do three things:
- Remove the
InvokerClassandActivatorClassParameters from theServiceattribute. This is the main step, and it tells the RO infrastructure that this service is now using Code-First. - Remove the service interfac from the ancestor list.
- To each of the methods you want to expose publicly, add the
ServiceMethodattribute.
In essence, you’d go from something like
@RemObjects.SDK.Server.ClassFactories.StandardClassFactory<br></br>
@RemObjects.SDK.Server.Service(Name = “LoginService”, InvokerClass = LoginService_Invoker.Type, ActivatorClass = LoginService_Activator.Type)<br></br>
public class LoginService : ILoginService {```
to just
@StandardClassFactory
@Service(Name = “LoginService”)
public class LoginService {```
(That example is Silver/Swift, but the same idea applies to Oxygene, C# or even VB.)
Optionally you can also remove the StandardClassFactory attribute, as it is the default. (If you switched to a different class factory, you would want to leave the attribute there, and you can also safely leave StandardClassFactory there if you prefer.)
In future betas, the name parameter on the Service attribute will become optional too, requiring it only if you want to expose the service under a different name than the class itself.
Note that you don’t necessarily need to convert all services to be Code-First in one go. You can start by converting some of your services and deleting them manually from the RODL, and leaving others RODL-based. Of course in that case you will want to delay the next two steps until you’re ready to switch the last service over.
At runtime, RemObjects SDK will take care of merging what’s in your RODL and what’s defined “Code-First” and make sure it all works together.
Converting Auxiliary Types
Next, let’s look at all the additional types you may have defined in the RODL to help your services. Enums, Structs, Exceptions or Arrays (although Arrays defined in RODL don’t really reflect in generated code).
In code, these all lie in the _Intf file that you normally don’t touch, because it gets updated from the RODL when that changes. Since the RODL is going away, this auto-updating won’t happen anymore, so you are, in a way, “taking ownership” of these classes now.
You could just keep the _Intf file around, but there’s a ton of extra crud in there that you no longer need, and that would make it hard to maintain/update in the future. So really, it makes sense to clean that up, and we have automated that for you with a small IDE wizard that takes care of this and the next step. We’ll get to that in a second.
Remove the RODL and Auto-Generated Code
Once we’ve take care of the auxiliary types, the RODL file and the three source files generated from it (but not the services!) can simply be removed from the server project and deleted.
Bye bye RODL, it was nice to have known you.
The “Convert to Code-First” Wizard
To automate the above two steps, we’ve added a small helper wizard to the IDE. In the first beta, this Wizard is in Fire only, but for the next beta we’ll be adding it to Visual Studio (and eventually Delphi) as well.
In Fire, you can always right-click the RODL file in your server project to see additional tasks specific to RODL files.
If your RODL contains services that don’t have stubs generated yet, you will want to invoke the “Generate Service Implementation(s)” item first to have those generated. In fact, the conversion wizard is grayed out until you do, because otherwise you would lose those definitions.
Normally, that won’t be the case, and all your services will already be implemented. In that case, the last menu option called “Convert to Code-First” becomes active. Simply invoke that to get things going:
- It will generate a new code file in your projects’s language, named after the RODL file, but with a “_RodlTypes” suffix. This file will contain all the types you need – in essence, it will be the same as the previous _Intf file, but without all there extra crud.
- It will remove the RODL file, as well as _Intf, _Invk and _Events files from the project, and move them to the Trash (where you can still restore them from, if needed. Although needless to say you should have a backup of your project, or better yet have it in version control before doing the conversion).
Once done, you can rename the _RodlTypes file to anything you like, or even move the types in it around into different source files (for example into the same file as their related service) as you see fit for the structure of your projects.
These are now “your” types. If you need to make changes to them for new versions of our server, you simply change them in code.
Configure Code-First
As a last step, there’s two lines of code you want to add to your server. This step probably will go away in subsequent betas and before release and use sensible defaults, but for now it is necessary.
Add these lines among the startup code of your server:
if !RemObjects.SDK.Server.Configuration.IsLoaded {<br></br>
RemObjects.SDK.Server.Configuration.Load(“MyProject” , “MyProject.Server” )<br></br>
}```
The first string passed is the “name” of your server, as exposed externally (in the RODL that clients will download); the second string is the namespace that RO’s Code-First engine will use for the helper types it generates under the hood at runtime.
### Press “Run”
And with that, your server is converted and ready to run. When you launch and go to http://localhost:8099/bin, you will still see the familiar RODL representation of your server, only now it is driven by the code in your project, not the other way around.
## Creating new Services
As you can imagine, creating new services (or a whole new server) will be super easy with the new model, as well. We don’t have Code-First-based templates in the first beta drop, but we’ll be adding them really soon.
To add a new service to your existing server, simply add a new class, attach the `Service` attribute, and mark the methods you want published with `ServiceMethod`. Done. If you need new structs or enums, simply define them in code.
To create a brand new server, just add one or more services to the project in the same way, and configure/start up an instance of your existing `NetworkServer` class (the API for which we’ll be making even simpler later in the RO9 beta). And of course we’ll have templates to help you do this, soon.
## Summary
We’ve only scratched the surface of Code-First services in this article, but I hope it gave you a good introduction and will help you get started with the feature.
Let us know what you think, how it’s working out for you, and what you would like to see improved!
