C# is the preferred .NET language for MDriven developers who need to add code outside the model, such as an integration, cryptographic algorithm, background job, or a specialized extension.
Use C# in MDriven
Most of MDriven is written in C#. You can use another .NET language for extensions, but use C# when you need the most direct fit with MDriven code, generated code, and .NET libraries.
Start with the model and OCL for domain behavior. Use C# when the required behavior cannot be expressed appropriately in the model, for example when you must call an external API, use a .NET library, or implement an algorithm that depends on functionality not available through OCL.
| Need | Preferred approach | Example |
|---|---|---|
| Domain rule, navigation, validation, or calculated value | Model and OCL | Derive an order total from its order lines. |
| User-facing data selection and presentation structure | ViewModel and its model logic | Define the data and actions needed by an order-entry screen. |
| External .NET capability or specialized algorithm | C# through CodeDress or a server-side extension | Call an external service, process an uploaded image, or use advanced cryptography. |
| Programmatic request to a Turnkey REST endpoint | C# HTTP client code | Post values to a Turnkey REST command. See Documentation:Use c-sharp code to post to TurnkeyRest. |
Keep model logic in the model
OCL expresses what the application does alongside the classes, attributes, associations, and methods that it affects. This keeps the intent and implementation together.
For example, if Order.Total is determined by its order lines, model it as a derived attribute and implement the calculation in OCL. Do not move it to C# only because C# can perform the calculation.
Use C# for the boundary cases. For example, a model method named GenerateKey may need an advanced cryptographic implementation. The method remains part of the model, while its implementation can be supplied by C#.
Choose an implementation path
CodeDress
Use CodeDress when you need to add C# to an MDriven solution while working with generated code. CodeDress gives you a place to implement selected model behavior in C#.
A common workflow is:
- Define the class member in MDriven Designer.
- Generate the code.
- Build the generated CodeDress project after adding your C# implementation.
- Upload the built result to the Turnkey server through the Cloud view.
- Test the method or derivation from the application.
When you change a method signature in the model, update the corresponding C# implementation before building. A call that no longer supplies a required parameter is invalid.
You can also implement a derived attribute in C#. Generated code provides a partial implementation point for that derivation. For example, a derived display value can combine an object's name with information reached through an association.
Derived values are evaluated when needed and invalidated when accessed model data changes. Therefore, use a derivation for a value that is calculated from model state rather than recalculating it repeatedly in user-interface code.
Server-side late-bound assembly
Use a late-bound assembly when a Turnkey server-side model method must call your own compiled .NET code. This is suitable for external web API calls that return data to the current model, advanced cryptography, and other .NET-only logic.
For example, you can define RuntimeKey.GenerateKey in the model, leave its model implementation blank, and route its execution to a C# assembly. The assembly checks the owning class and method name, reads supplied parameters, and returns the result.
Follow the required assembly name, interface implementation, tagged value, and deployment procedure in Documentation:Calling your own c - sharp .net things from Turnkey–server side. That page also explains how to access method parameters, properties, and associations from the supplied MDriven object.
Important: For an Eco.ExternalLateBound=True method used with CodeDress, leave the method body empty. If the body contains code, that code runs instead of the external late-bound implementation. The generated stub may still need return statements or similar code so that the project compiles.
REST client code
Use C# when an external process must post values to Turnkey REST. The request must supply a multipart boundary both in the content and in the Content-Type header; otherwise, the Turnkey server does not parse the posted values.
See Documentation:Use c-sharp code to post to TurnkeyRest for the request pattern and example code.
Design C# work for operation and maintenance
Keep each operation small
Split long-running or complex work into focused operations. For example, instead of resizing every uploaded image during the user's save operation, trigger a server-side job that processes one image or a manageable batch at a time.
Small operations are easier to debug, reduce the amount of data held in memory at once, and avoid making the user interface wait for unrelated processing. Model additional state when needed so that each operation has the information required to continue its work.
Match framework versions
Build C# code against MDriven framework versions that are compatible with the MDriven version used to compile the model and with the deployed Turnkey version. Major framework changes can alter interfaces and break code compiled against a substantially different version.
After updating NuGet packages or framework dependencies, generate, build, upload, and test the complete path again.
Keep the contract explicit
Treat the model method as the contract between the model and C#:
- Give the method a clear name, such as
SendAssetorGenerateKey. - Define parameters and return values in the model before implementing the C# code.
- Read parameters by their modeled names in the implementation.
- Return a value compatible with the modeled method result.
- Keep side effects clear. A method intended as a query can still have side effects, so do not rely on the name alone to communicate behavior.
C# and presentation
C# is not the first choice for ordinary text formatting. Configure display formatting on the ViewModel column with tagged values instead. For example, use the relevant formatting tagged value to display a number with a required number of decimals. See Documentation:Text formatting.
Learn C#
If you are new to C#, learn the language fundamentals before implementing MDriven extensions. Focus on classes, methods, types, assemblies, references, and asynchronous or background work. The C# implementation should remain a focused extension of a model-driven application, not a replacement for the model.