A referenced package lets you use classes from an external package in your model without changing that package; use it when the package is maintained separately and you want to link your own classes to its classes.
What a referenced package does
A package is a container for a section of a model. When you add a package as a reference, its classes are part of the model definition available to you, but they are read-only in the current model.
You can:
- Use classes in the referenced package as association targets.
- Create associations between classes in your model and classes in the referenced package, subject to the read-only association-end rule.
- Use the referenced package together with the compiled assembly or project that implements its runtime logic.
You cannot:
- Change classes, properties, or other definition details in the referenced package.
- Generate the referenced package together with the rest of your model.
- Add a new association that makes a read-only class point to a class in your model.
Create associations to referenced classes
You may draw associations to and from classes in a referenced package as long as the association end that would be changed is not embedded in the read-only package.
In practical terms, your model can point to a referenced class, but a referenced class cannot be changed to point to something new in your model.
Example
Assume that an external package contains a class named Day and your model contains an Account class. You can create a unidirectional association from Account to Day. The association is owned by the editable part of your model.
This is the same integration pattern used by the Calendar package, where model classes can link to the package's Day class.
If you attempt to change a property or an association end that belongs to the referenced package, MDriven prevents the change because that definition is read-only.
Add a referenced package
Use the referenced-package editor when you want to use an external package as a dependency rather than copy it into your model.
- Open the option Edit referenced packages.
- Select Add.
- Locate and select the
.ecopkgfile that you want to reference. - Confirm that the package is selected for use in the model.
- Add a normal .NET reference to the assembly or project that supplies the referenced package's runtime implementation.
A referenced package is not code generated with your model. It commonly has its own compiled assembly or project, especially when it contains code-implemented operations, code-derived attributes, or other runtime logic.
Make a referenced package available at runtime
Select the package in the EcoSpace designer by using the package-selection control, then ensure every package your model uses is selected.
Selected UML packages are made available at runtime through a package-type reference in the generated EcoSpace designer code. If you cannot use the designer, you can add an equivalent protected member to the EcoSpace class yourself. Add one member for each referenced package, using the referenced package's generated package type and a unique member name.
protected MDrivenPackage1.MDrivenPackage1Package IncludeEcoPackage_MDrivenPackage1_MDrivenPackage1Package;
Generate code and build the solution before generating the schema. The schema is derived from the runtime model, and the runtime model is derived from the generated code.
Adopt a referenced package when you need to change it
Adopting creates a copy of the referenced package that your model owns. Use this when the package must be changed as part of your model rather than kept as an external dependency.
- Open Import/Export.
- Choose the command to adopt the referenced package.
- Confirm the adoption.
- Edit the resulting package in your model as needed.
After adoption, you can change the package, and it is handled as part of your model rather than as a read-only reference.
Important: adoption breaks the update relationship with the original source. Later updates to the original package are not applied to your adopted copy. Keep the package referenced when you need to retain the external package as a separately maintained dependency; adopt it only when local changes are required.
Choose reference or adoption
| Need | Use a referenced package | Adopt the package |
|---|---|---|
| Keep an external package read-only and use its classes | Yes | No |
| Create an association from your own class to a class in the package | Yes, when the editable association end is in your model | Yes |
| Change the package's classes or properties | No | Yes |
| Receive later changes by continuing to use the original external package | Yes | No; the adopted copy does not update from the original |
| Generate the package as part of your model | No | Yes |
For the broader distinction between importing an editable package and referencing an external package, see Documentation:Segmenting definition and logic.