diff --git a/Odata-docs/TOC.yml b/Odata-docs/TOC.yml index b323af5d..9fb53d04 100644 --- a/Odata-docs/TOC.yml +++ b/Odata-docs/TOC.yml @@ -66,6 +66,8 @@ items: - name: Capabilities vocabulary extensions href: /odata/webapi/model-builder-capabilities-vocabulary + - name: Revisions vocabulary annotations + href: /odata/webapi/model-builder-revisions-capabilities - name: Non-convention model builder href: /odata/webapi/model-builder-nonconvention - name: Routing diff --git a/Odata-docs/webapi/model-builder-revisions-capabilities.md b/Odata-docs/webapi/model-builder-revisions-capabilities.md new file mode 100644 index 00000000..d9c9a439 --- /dev/null +++ b/Odata-docs/webapi/model-builder-revisions-capabilities.md @@ -0,0 +1,175 @@ +--- +title: "Adding Revisions Annotations with the OData Model Builder" +description: "core capabilities vocabulary" +author: ElizabethOkerio +ms.author: elokerio +ms.date: 7/22/2021 +--- + +# Adding Revisions Annotations with the OData Model Builder + +**Applies To**:[!INCLUDE[appliesto-webapi](../includes/appliesto-webapi-v7.md)][!INCLUDE[appliesto-webapi](../includes/appliesto-webapi-v6.md)] + +The model builder now allows you to add [revisions annotations](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.xml#L77) to your model elements. Please [follow the link](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md) for more information on [core capabilities vocabulary](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md). + +It is available in the [Nuget gallery](https://www.nuget.org/packages/Microsoft.OData.ModelBuilder) + +You can install or update the NuGet package for OData Migration Extensions v1.0.0 using the [Package Manager Console](https://docs.nuget.org/docs/start-here/using-the-package-manager-console): + +```PowerShell +PM> Install-Package Microsoft.OData.ModelBuilder +``` +## Examples + +Unless otherwise specified, examples will be based on the model below. + +```csharp +public class Customer +{ + public int CustomerId { get; set; } + public string Name { get; set; } +} + +public class Address +{ + public string City {get;set;} +} + +public enum Color +{ + Red, + Green, + Blue +} +``` +Revisions can be added to all model elements. So far, the OData Model Builder supports revisions to the following model elements: + +1. EntitySets +1. Actions and Action Imports +1. Functions and Function Imports +1. Entity Types +1. Complex Types +1. Enum Types +1. Enum Members +1. Properties + +There are three kinds of revisions that can be added to any of the model elements above: + +```csharp +enum RevisionKind +{ + //when a model element is added + Added, + + //when a model element is modified + Modified, + + //when a model elemeny is deprecated + Deprecated +} +``` + + +To add revisions to an entity set for example, use the code below: + +```csharp +var builder = new ODataConventionModelBuilder(); +var customerConfiguration = builder.EntitySet("Customers").HasRevisions(a => a.HasVersion("v1.2").HasKind(RevisionKind.Added).HasDescription("Added a new entity set")); +``` + +Use this structure to add revisions to all the other supported model elements above. + +$metadata + +```xml + + + + + + + + + + + + + + + + + + + + + Org.OData.Core.V1.RevisionKind/Added + + + + + + + + + +``` +To add a revision, you must provide the following properties: +1. RevisionKind - the kind of revision you are making. Added, Modified or Deprecated. +1. Description - a description describing the revision you are making. +1. Version - the version of the model the revision was made. + +You can add also dynamic properties to provide more information for the model elements' revisions. Below is an example on how to add extra properties to a revision. + +```csharp + +var builder = new ODataConventionModelBuilder(); +var config = builder.EntitySet("Customers").HasRevisions(a => a.HasVersion("v1.2").HasKind(RevisionKind.Deprecated).HasDescription("The M").HasDynamicProperty("Date", new DateTime(2021,11,11)).HasDynamicProperty("RemovalDate", new DateTime(2022,12,12))); + +``` +$metadata + +```xml + + + + + + + + + + + + + + + + + + + + + Org.OData.Core.V1.RevisionKind/Deprecated + + + + + + + + + + + + + + + + + +``` + + + + +