From 59172ad8cc5eec4759b09977c3d9713f8fbe9830 Mon Sep 17 00:00:00 2001 From: elokerio Date: Thu, 26 Aug 2021 14:30:54 +0300 Subject: [PATCH 1/5] revisions capability doc --- .../model-builder-revisions-capabilities.md | 106 ++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 Odata-docs/webapi/model-builder-revisions-capabilities.md 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..edf77182 --- /dev/null +++ b/Odata-docs/webapi/model-builder-revisions-capabilities.md @@ -0,0 +1,106 @@ +--- +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 on 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 +``` +Then Add the following using to your project class. +```csharp +using Microsoft.OData.ModelBuilder.Vocabularies +``` +## Examples + +Find below some sample usages... + +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 made 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 deprecated revisions to the entity set. use the code below: +```csharp +var builder = new ODataConventionModelBuilder(); +var customerConfiguration = builder.EntitySet("Customers").HasRevisions("Deprecated", "v1.1.0", RevisionKind.Deprecated, new DateTime(2021,8,8), new DateTime(2022, 12,12)"); +``` +The following is a short description of the HasRevisions() method's parameters: + +Deprecated is a description of why the entity set or any other model element is being deprecated. + +v.1.1.0 is the model version the deprecation was made + +RevisionKind.Deprecated is the kind of revision being done. There are 3 kinds of revisions that can be made to a model element. + +```csharp +enum RevisionKind +{ + //when a model element is added + Added, + + //when a model element is modified + Modified, + + //when a model elemeny is deprecated + Deprecated +} +``` + + From 910981b4ae43c3b805c2fdcd99c99324ba30503a Mon Sep 17 00:00:00 2001 From: elokerio Date: Thu, 26 Aug 2021 14:33:59 +0300 Subject: [PATCH 2/5] update rev doc --- .../model-builder-revisions-capabilities.md | 111 ++++++++++++++---- 1 file changed, 90 insertions(+), 21 deletions(-) diff --git a/Odata-docs/webapi/model-builder-revisions-capabilities.md b/Odata-docs/webapi/model-builder-revisions-capabilities.md index edf77182..91778ec7 100644 --- a/Odata-docs/webapi/model-builder-revisions-capabilities.md +++ b/Odata-docs/webapi/model-builder-revisions-capabilities.md @@ -19,10 +19,6 @@ You can install or update the NuGet package for OData Migration Extensions v1.0. ```PowerShell PM> Install-Package Microsoft.OData.ModelBuilder ``` -Then Add the following using to your project class. -```csharp -using Microsoft.OData.ModelBuilder.Vocabularies -``` ## Examples Find below some sample usages... @@ -76,31 +72,104 @@ enum RevisionKind ``` -To add deprecated revisions to the entity set. use the code below: +To add revisions to an entity set for example. use the code below: ```csharp var builder = new ODataConventionModelBuilder(); -var customerConfiguration = builder.EntitySet("Customers").HasRevisions("Deprecated", "v1.1.0", RevisionKind.Deprecated, new DateTime(2021,8,8), new DateTime(2022, 12,12)"); +var customerConfiguration = builder.EntitySet("Customers").HasRevisions(a => a.HasVersion("v1.2").HasKind(RevisionKind.Added).HasDescription("Added a new entity set")); ``` -The following is a short description of the HasRevisions() method's parameters: - -Deprecated is a description of why the entity set or any other model element is being deprecated. -v.1.1.0 is the model version the deprecation was made - -RevisionKind.Deprecated is the kind of revision being done. There are 3 kinds of revisions that can be made to a model element. +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. +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 -enum RevisionKind -{ - //when a model element is added - Added, - //when a model element is modified - Modified, +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))); - //when a model elemeny is deprecated - Deprecated -} ``` +$metadata + +```xml + + + + + + + + + + + + + + + + + + + + + Org.OData.Core.V1.RevisionKind/Deprecated + + + + + + + + + + + + + + + + + +``` + + + From ed894fbfff93c556bc5a3d941bdbc6e045e61a98 Mon Sep 17 00:00:00 2001 From: elokerio Date: Mon, 30 Aug 2021 07:22:21 +0300 Subject: [PATCH 3/5] proofread changes --- Odata-docs/webapi/model-builder-revisions-capabilities.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Odata-docs/webapi/model-builder-revisions-capabilities.md b/Odata-docs/webapi/model-builder-revisions-capabilities.md index 91778ec7..b26a80c3 100644 --- a/Odata-docs/webapi/model-builder-revisions-capabilities.md +++ b/Odata-docs/webapi/model-builder-revisions-capabilities.md @@ -55,7 +55,7 @@ Revisions can be added to all model elements. So far, the OData Model Builder su 1. Enum Members 1. Properties -There are three kinds of revisions that can be made to any of the model elements above: +There are three kinds of revisions that can be added to any of the model elements above: ```csharp enum RevisionKind @@ -73,6 +73,7 @@ enum RevisionKind 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")); @@ -117,7 +118,8 @@ $metadata 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. +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 From afbea727167ffd0d0633b6e98dbc8a1f7533e8c4 Mon Sep 17 00:00:00 2001 From: elokerio Date: Mon, 30 Aug 2021 08:48:49 +0300 Subject: [PATCH 4/5] update toc --- Odata-docs/TOC.yml | 2 ++ 1 file changed, 2 insertions(+) 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 From c216b9e3644807c795d27ed0fdb6dc105036657e Mon Sep 17 00:00:00 2001 From: elokerio Date: Mon, 30 Aug 2021 15:18:54 +0300 Subject: [PATCH 5/5] fixed based on review comments --- Odata-docs/webapi/model-builder-revisions-capabilities.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/Odata-docs/webapi/model-builder-revisions-capabilities.md b/Odata-docs/webapi/model-builder-revisions-capabilities.md index b26a80c3..d9c9a439 100644 --- a/Odata-docs/webapi/model-builder-revisions-capabilities.md +++ b/Odata-docs/webapi/model-builder-revisions-capabilities.md @@ -12,7 +12,7 @@ ms.date: 7/22/2021 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 on the [Nuget gallery](https://www.nuget.org/packages/Microsoft.OData.ModelBuilder) +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): @@ -21,8 +21,6 @@ PM> Install-Package Microsoft.OData.ModelBuilder ``` ## Examples -Find below some sample usages... - Unless otherwise specified, examples will be based on the model below. ```csharp @@ -72,7 +70,7 @@ enum RevisionKind ``` -To add revisions to an entity set for example. use the code below: +To add revisions to an entity set for example, use the code below: ```csharp var builder = new ODataConventionModelBuilder();