DEV Community: UpSlide

Continuous Translation with .NET Framework

Grégoire Scano — Thu, 09 Jan 2025 19:50:03 +0000

Most popular softwares are available in multiple languages, and that is awesome: you are a native Spanish speaker, you can use Microsoft PowerPoint in Spanish, that’s it. But when it’s your turn to deliver a new innovative software, you rarely think of the translation of its user interface as a primary goal. You focus on impacting features and working code. Indeed, this is what matters the most in the initial stages of the lifecycle. If the software is natively supporting English, it takes even longer to consider supporting other languages because its use is widespread.

English Localization

As UpSlide was first available in French, its growing success quickly required English support to expand abroad. The translation was thought to be a onetime effort and needed to be carried out swiftly with a low development cost.

At that time, strings were stored in the code in two different ways: one using fields, the second using ResX resource files¹; and so, the translation was made in one of these formats without changing the architecture of the code.

For fields, the migration consisted in making their static constructors initialize strings to the relevant language on startup. It was quite straightforward, but a huge work, nonetheless.

public static class SettingsMessages
{
    public static string WindowTitle { get; private set; }

    public static void Localize(CultureInfo culture)
    {
        switch(culture)
        {
            case SupportedCultures.English:
                WindowTitle = "Settings";
                break;
            case SupportedCultures.French:
              WindowTitle = "Paramètres";
                break;
            default:
                throw new ArgumentException($"Unknown culture: {culture}");
        }
    }
}

For ResX files, it was even simpler. Thanks to its .NET native internationalization support, it is possible to have multiple ResX files with a language suffix such as Ribbon.en.resx for a localization of Ribbon.resx. The content of the English version is then stored in a satellite assembly and retrieved at runtime if the culture of the resource is set to en or any region for this language, such as en-US for instance.

public static class Resources
{
    public static void Localize(CultureInfo culture)
    {
        Ribbon.Culture = culture;
    }
}

French was kept as the default language to allow for incremental translation. The transition was thus an easy, but painstaking process of translations and reviews (our product team had professional proficiency in both languages).

The result worked wonders. It has supported the company's continuous success in expanding to other countries all over the world for about a decade. So, it could very much have been the end of the story.

German Office Called: Katastrophe…

But it was not going to be enough; English is not the only widespread professional language after all. According to a Babel article, less than 20% of the world speaks it. Some German clients even bought the solution under the assumption that the software would be available in German — this is because UpSlide also has an office in Germany. It seemed obvious to them but not us: the English translation had worked so well so far; we didn’t think it'd require further work.

Besides hindering future sales, missing a translated language could slow down product adoption in other countries as well. Indeed, although some French users can use English, they most often prefer to use the French version… The conclusion was simple: the software must be ready to be translated to other languages.

So far, only two languages were dealt with, and they were fairly similar. As a result, the methods used to add English would not necessarily be replicable, and translating to other, potentially very different, languages was unknown territory. In particular, pluralization and average word length could differ and impact both the code structure and the visual rendering. Also, it may not be spoken fluently by people in charge of string editions, namely product engineers and managers, so it was not very clear how the actual translation would take place.

Internationalization & Localization

According to Wikipedia, “Internationalization is the process of designing a software application so that it can be adapted to various languages and regions without engineering changes. Localization is the process of adapting internationalized software for a specific region or language by translating text and adding locale-specific components”.

Internationalization is complex because it has to bend a formal language to be able to display natural languages, with a common interface for all supported locales. It is also not just about the language in which an application is displayed but also involves reworking on the graphical user interface to accommodate for different writing directions, strings length, buttons’ locations, and color schemes.

GNU brilliantly solved part of the problem with gettext for textual changes. One program extracts the strings in the default language from the code itself. Another manipulates those for each language. The last one retrieves the correct string depending on the localization at runtime. In particular, gettext handles pluralization in a very smart and efficient way for any type of language, especially those for which more than two plural forms exist.

# Ukrainian has 3 plural forms:
# nplurals=3
# The plural form (the index in the msgstr array) is determined by the following expression:
# plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)

msgid "%d constructor found\n"          # Singular in English
msgid_plural "%d constructors found\n"  # Plural in English (to indicate the pluralized content to the translator - 'constructors' here)

msgstr[0] "%d конструктор знайдено\n"   # Singular nominative form for numbers ending in 1 (except 11)
msgstr[1] "%d конструктори знайдено\n"  # Plural nominative form for numbers ending in 2, 3, and 4 (except 12, 13, and 14)
msgstr[2] "%d конструкторів знайдено\n" # Plural genetive form for all other numbers

Regarding graphical user interfaces, solutions are most commonly handcrafted depending on the application. However, WinForm properties such as the size of graphical elements can be adjusted through properties defined in ResX files. It is also possible to do the same for WPF elements, even without using the designer.

Localization is challenging because it requires synchronisation between the product and developer teams. Many solutions exist to provide online localisation services supporting various input formats such as GNU gettext and ResX files. But a strong requirement, the code should not leave the company’s premises, removed almost all available solutions. Not to mention that they were also quite expensive. Weblate on the other hand combines the advantages of being free and self-hosted. The code would not have to leave the premises, and support is affordable.

Remaining Pragmatic

There are a couple of NuGet packages out there to harness the cleverness of gettext in .NET. However, integration required additional dependencies, both for compilation and runtime, and resulted in a more complex and less stable build. The approach was thus deemed unfit for our .NET Framework projects.

Besides technical challenges, the long-term target languages did not have more than two plural forms. These targeted languages were carefully identified with a high return on investment and limited expected graphical user interface modifications. To achieve the transition, all static strings had to be migrated to ResX files and plurals had to be handled by a method similar to ngettext.

Of course, this migration had a big impact. But it was still costly to add and edit strings both because the code had to be edited but also because product and developer teams needed synchronization. This is where Weblate and continuous translation brought the solution to yet another level. It allows many within the company to engage in the translation process. All in a shared and constant environment. Translations can be peer-reviewed, and developers do not have to worry too much about them either, freeing up some time and reducing friction in the whole development process. Subcontractors can also be involved to translate to languages that are not mastered within the company.

Building on the previous success of the incremental translation to English, the migration is also incremental. The technical solution is ready, and we can already start translating to other languages. This makes the company a little more resilient against new language requirements and a little more ready for future challenges.

¹ A ResX file is an XML description of resources. Some, such as strings, are directly contained verbatim, while others are a pointer to any type of files, most notably icons, images, and audio files. Those files, along with an internal representation of the XML file, are embedded in the final assembly so that those resources can be retrieved in two convenient ways at run time. First, using a resource manager that loads the assembly, locates the resource and returns it. Second, having a single file generator wrap the resource file within a generated class with properties corresponding to each resource.

How and why did we improve our API hosting?

Clément MARTINEZ — Tue, 17 Sep 2024 12:22:06 +0000

Background

UpSlide is a Microsoft 365 add-in that runs with PowerPoint, Excel and Word. At startup, the UpSlide add-in sends requests to our various endpoints to:

check the license;
perform auto-update;
retrieve global settings managed from our “Portal” website;
send usage statistics.

These endpoints are critical to ensure the add-in works correctly, which is why we need a stable and secure release process to guarantee their continuous availability.

To host these endpoints, we’ve been using Azure App Services for a long time, organized into three distinct environments:

Develop	Testing	Production
to deploy and test the code during the sprint	to run automated tests in an environment close to the production one (similar data, same performance)	to handle UpSlide add-in’s requests

Historically, each environment was materialized by an App Service deployment slot, in which we configured slot settings. These were used to fill the application settings to target the right resources (i.e., the right database, service, or warehouse) based on the environment. Slot settings were actually environment variables.

On release day, the production roll-out process involved:

Deploying a new version on the "testing" slot
Updating the “testing” slot settings
Ensuring everything was working correctly
Updating the “production” slot settings
Swapping the "testing" and "production" slots to complete the deployment

If the new version had any problems, we would restore the previous one.

This solution was functional, but there was still room for improvement.

Challenges with Azure App Services

First, there were still manual operations during the deployment process, which, in my opinion, often results in the introduction of bugs in a release process. Updating deployment slot settings (i.e., environment variables) because of a change in application settings was one of the elements that needed to be automated.

Imagine Alex, a super-happy developer at UpSlide. On release day, Alex manually updates the App Service production slot settings, as application settings were added or modified during the sprint.

He is bound to encounter situations where:

he forgets to add or edit slot settings;
a value entered in slot settings contains a typo;
thinking he's doing the right thing, he corrects a setting, but the correction is incorrect.

In the best-case scenario, these errors have a minor impact on the service. In the worst case, the service goes down.

But it's not over yet. Let's assume these slot settings changes have been carried out correctly: the new version works, but an hour later, we realize that a regression has been introduced. We expect to quickly fix the problem by returning to the previous version, just long enough to understand what's wrong. So Alex figures he can simply swap the "testing" and "production" slots again. But a new problem arises: the slot settings have changed! As these settings stick to slots during a swap operation, Alex has to urgently determine what changes have been made to revert them.

What should be a simple situation becomes a headache, and the stress and urgency can lead Alex to make other mistakes.

So far, our developers have been vigilant enough to avoid any major problems. But we didn't want to rely solely on their vigilance, so we had to prioritize improvements to the release process. We agreed on the following resolutions:

environment variable updates must not be done manually;
redeploying an older version of our endpoints must be easy and without risks.

This brought us to our new approach: Container Apps!

A new hosting solution: Container Apps

Azure Container Apps provide a serverless environment for running microservices and containerized applications. They feature the concept of 'Revisions', which encapsulate both application code and environment variables, ensuring consistent and reliable deployments.

Let’s go back to the previous situation, this time with container apps. Alex deploys the latest version of our endpoints and the set of environment variables linked to that revision. An hour later, a regression is detected. Alex just needs to reactivate the previous version and redirect traffic. In a matter of seconds, and without the risk of making a mistake, the situation returns to normal, and Alex can focus on fixing the regression.

Automating Environment Variable Updates

One problem was fixed, but we still needed a way to automatically update environment variables.

Our application defines settings provided by its running environment. Since settings can be added or removed over time, environment variables must be modified accordingly. Application settings are modified during development, while environment variables are set on a release day. These steps are usually separated by a few days, so we must remember to replicate all changes. A must-have would be to declare changes to environment variables during development. That way, all changes are prepared and can be performed automatically during the release.

We easily achieved this by adding a file called production.env, in which we declared all environment variable values, being either hard-coded values or references to an existing key vault secret. Here is an example for this file:

APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=xxxx-xxx-xxx-xxx-xxxx;IngestionEndpoint=https://applicationinsights.azure.com/;LiveEndpoint=https://monitor.azure.com/
DB_CONNECTION_STRING=secretref:dbconnectionstring
ASPNETCORE_ENVIRONMENT=Production

We then updated the release pipeline to extract values from production.env and use them while deploying a new revision (as the deploy command has a parameter to provide a set of environment variables).

We ended up with a single source of truth for environment variables that:

developers can update during development when values need to be added or removed;
is reviewed by others before merging;
is automatically deployed during the release.

First Deployment

Implementing the plan wasn't without its challenges.

We set up the necessary infrastructure on Azure, including the Registry and Container App, and modify our pipelines accordingly. However, upon our first deployment, we encountered an error explaining Container Apps only support images built in a Linux environment. This is not really an issue as .NET Core is cross-platform, so we simply built our API with Linux. However, another error occurred:

System.Security.Cryptography.CryptographicException: ASN1 corrupted data.
---> System.Formats.Asn1.AsnContentException: The provided data is tagged with 'Application' class value '13', but it should have been 'Universal' class value '16'.

It was triggered by System.Security.Cryptography.X509Certificates, a set of classes we were using to manage our certificates. After some research, we found differences in the way Windows and Linux interpret the certificate value provided.

This issue highlighted the fact that, even though frameworks and packages can be cross-platform, we should still be aware of the differences that may exist in behaviors between each platform. Therefore, we decided to do without this package for the deployed container to start up correctly, as the benefits of using Container Apps justified getting rid of it.

Scaling Challenges

Once everything was set up, we redirected the traffic to our new Container Apps.

However, a new issue emerged: our endpoints experience peak loads at certain times of the day, challenging the automatic scaling capabilities of Container Apps.

Why those peaks?

Most of our users begin their workday by opening Microsoft 365, so UpSlide triggers license checks, auto-updates, and settings retrieval. This behavior results in daily peaks of requests at certain times of the day.
As UpSlide is used in different parts of the world, these peaks occur at different times, as shown in this graph:

We expected Container Apps to handle this load by scaling automatically, based on rules Azure allows us to define. Those rules include predefined criteria, or custom criteria to configure more advanced rules. We initially only used a predefined criteria: the number of concurrent HTTP requests per second. When this value is exceeded, a new revision replica is created.

However, starting a revision takes about one minute, and Azure checks for a scaling need every 30 seconds as a fixed interval. So, by the time the Container App starts the new revisions, a large part of the peak load is already absorbed by the initial revision, and the benefits of scaling are lost.

Currently, we mitigate this by scaling the Container Apps automatically before expected peak times. This scaling is done using a custom cron rule that allows us to specify time slots during which we want to scale, and the number of replicas expected.

Next Steps

Here we are: our Container App works well, but there are still limitations on the packages that can be used in the solution and on automatic scaling. Despite this, our release process has improved and is now more flexible and comfortable for developers.

Looking ahead, we aim to improve the startup speed of our solution to enable the Container App to have better automatic scaling.

Conclusion

Azure also offers other hosting solutions, to be chosen from according to your needs. We opted for Container Apps due to their simplicity, ease of management, and seamless integration with our existing infrastructure. The abstraction of Kubernetes complexities allowed us to focus on application deployment and scalability without the overhead of managing intricate configurations.

As we continue to innovate and adapt, we remain open to exploring new solutions that can further enhance our deployment processes and overall efficiency.

What about you? What do you use to host your APIs?

Special thanks to Fabien SINQUIN and Clément MICHEL for their major contribution to this article 🙏

Ubiquitous Language: the Good, the Bad, and the Lessons

Fabien Sinquin — Thu, 02 May 2024 16:17:49 +0000

Ubiquitous Language Is Great

Ubiquitous Language is the idea of defining a common language to be used at all levels in your product: user interface, documentation, client presentations, code, etc. This language should be shared between domain experts, users, marketing, and devs.

The history of languages shows that Linguistic prescription (defining and enforcing a standard language) is tricky. For example, every time the Académie Française has tried to impose freshly minted terms to replace Anglicisms – such as email, upload etc. – it failed. Most French people kept using the English words. If only because of reluctance to change, a fully ubiquitous natural language is not realistic.

So you may wonder: is Ubiquitous Language worth the trouble? How helpful is it?

Avoid Duplicated Effort

If you are familiar with Microsoft Word, you may have noticed you have two ways to color the background of your text: “Text Highlight Color” and “Shading”.

Text Highlight Color	Shading

There is a significant overlap between both features, but they do not cover the same cases and they do not work well together. They are – most likely – two separate implementations covering a single need. A user might have a hard time deciding whether their text should rather jump off the page or just pop…

Looking at these buttons, I cannot help but think the lack of a common language resulted in waste: having to implement and maintain a feature twice.

Avoid Bugs

It is possible to open hidden presentations (without a window) in PowerPoint. When all presentation windows are closed, PowerPoint will remain active as long as a hidden presentation is opened.

In one of our sprints, we needed to implement a routine to force close all such presentations. But in our code base, we had an older method named GetHiddenPresentations that listed minimized presentations.

As you can guess, we ended up force-closing all minimized presentations. This – definitely – was not a welcomed feature! In the post-mortem that followed this bug, we decided to use “windowless” and “minimized” instead of the ambiguous “hidden”. We felt this simple wording change would have avoided the mistake from the beginning, and would have helped us spot that bug during the review.

Ubiquitous Language Is Hard

// Detect dark theme var iframe = document.getElementById('tweet-7269997868-575'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=7269997868&theme=dark" }

Ubiquitous Language sounds simple, but – since it is all about naming things – it is not. I’ve been struggling with it ever since I joined UpSlide. Please don’t tell my colleagues 😉

In 2022, we wanted to simplify the way our users apply style to their PowerPoint tables. We already had a “Table Styles” feature, so we came up with an idea: a menu that would pop up when users select tables.

It was the first time we implemented such a menu, so we had a question…

👉 What should we name this kind of menu?

Let’s Brainstorm!

Imagine you’re part of our team. You are looking for the name of “a context-dependent menu that pops up to nudge users”).

Gather a few colleagues and start throwing ideas around.

Once someone suggests “minibar 🍸”, you can all agree you have run out of ideas.

There Can Only Be One!

Now it’s time to eliminate ideas…

Let’s start with the obvious ones, “Menu” and “Suggestion” are too generic. Out!
“Popup” is not so bad, but the word has gained such a bad reputation (because of website ads) that it’s out the window. “Pop menu” removes some of that discomfort but sounds unfamiliar.
“Prompt¹” means something else to devs (Command Prompt or Javascript prompt).
From a marketing perspective, “Toolbar” / “mini toolbar²” do not spark joy. Pre-Office 2007, toolbars were the rage³, but they disappeared when the ribbon arrived.
“Context Menu” sounds OK, but it is the name commonly used for the right-click menu…

Let’s assume that you’ve settled on “Contextual menu” (like we did at the time). You can now proceed to use that term everywhere: code, documentation, discussions, etc.
And – because you want this Ubiquitous Language approach to work– you’ll make a point of correcting anyone who uses something else: “Careful, this is not a popup⁴, it’s a contextual menu.”.

#happily-ever-after

Marketing Called: They Have a Better Name…

While the feature is getting ready for the general release, our fellows from Marketing have gathered insights from users and concluded that the feature should be named a “prompt”.

To keep a Ubiquitous Language, we now have to rename all occurrences in:

Code: IDEs are great nowadays and make this step easy. (<3 JetBrains)
Documentation: this one is more painful, because:
- our documentation is spread across several tools⁵ (Notion, a bit of Zendesk for end-users, and an Azure DevOps wiki for technical topics);
- search and replace is a blunt tool.
my head: on this front, tooling cannot help… Once they have gotten used to it, people will have a hard time avoiding the now-obsolete name. So “Contextual Menu” will keep popping by in emails, and other conversations. It eventually gets better, but the transition is painful.

More Surprises 😅

Remember when I said renaming the code was easy? Well, I lied… Some occurrences of “Contextual Menu” are serialized in our user settings.

When this happens, you must choose between a breaking change and quasi-ubiquitous language.

The same kind of issue can also happen with old emails or messages: they cannot be fixed and might cause head-scratching later on.

By the time we got around calling those menus “Prompt”, ChatGPT arrived. And with it, a new meaning for “prompts” emerged. For anyone in the software industry, a “prompt” is now the input given to a Large Language Model.

So, should we rename our “prompts” to avoid confusion, or should we keep that name?

Lessons

“Well-established” Trumps “Cool”.

We are a Microsoft 365 add-in, deeply integrated within Microsoft Office. We were implementing a feature that behaves like the Office “Mini toolbar”… From a Ubiquitous Language perspective, this makes a very strong case for naming our feature “Mini toolbar”.

Name Deliberately

When we started working on the Proof of Concept for Table Styles, we delayed thinking about the feature name. It made sense because we were unsure of what we could build exactly. By not picking a name, we encountered many challenges along the way.

In retrospect, we should probably have…

Deliberately picked a dummy name for the future feature. Maybe even a silly one – say Stylinator – to make changing it easier.
Started looking for a good name as soon as the final feature behavior was clear.
Involved all parties (devs, product, marketing, domain experts) in that search.

Conclusion

Despite all your efforts, external factors will force you into renaming things. In 2022 it might have been OpenAI that changed the meaning of “prompt”. In 2023 it might have been Microsoft's decision to rename Azure AD to Entra ID. Change is inevitable.

Over the years, I have found it helpful to view Ubiquitous Language as a journey, rather than a destination. Maintaining a common vocabulary can be a pain at times, but it is often worth it. Trust me, you do not want the blood of those minimized presentations on your hands 😅

What about you? What is the worst bug you have ever met that was caused by a misunderstanding?

Notes

This was early 2022, before ChatGPT, so “prompt” was not commonly associated with AI.

Microsoft Office has a feature named “mini toolbar” that behaves like our menu.

In the 2000s, it was common for software to bundle browser toolbars, and you could end up with an unusable browser…
// Detect dark theme var iframe = document.getElementById('tweet-1585243632160092164-342'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1585243632160092164&theme=dark" }

When developing the Proof-of-Concept, the initial name we used was “popup”.

We are actively looking at reducing the number of tools we use for our documentation.

Cover photo source.

Make your Azure OpenAI apps compliant with RBAC

Thomas W. Drake — Mon, 25 Mar 2024 17:05:18 +0000

Microsoft has effectively provided developers with relevant documentation to bootstrap their AI projects using Azure OpenAI Services. But, as we delve into more advanced scenarios and start encountering edge cases, there seems to be noticeably less guidelines available.

What’s a recent example of this? Switching from using shared keys to Entra ID Authentication/Authorization.

Although shared keys are very easy to set up, you’ll likely want to avoid them for several reasons.
Firstly, if you lose the key or if someone gets their hands on it, you need to reset it. All systems that used the old key then need to be updated with the new one to keep working.
This becomes an issue when people leave the company; they might still have that shared key stored somewhere, and there is no way to revoke their permissions.
Plus, storing the key can be a security hazard in of itself.

Using Entra ID Authentication eliminates all these problems. It authenticates the user, and then delegates the authorization component to a fine-grained, configurable system.

Role-Based Access Management (RBAC) is the current standard in Azure user access management. It’s the backbone of the entire authorization component in Entra ID authentication.

Permissions on a specific resource are set via user roles. Each user role encompasses a range of permissions. But when it comes to Azure OpenAI Services, what user roles should we use?

Disclaimer: Azure OpenAI Services is still a new feature and the technology may be subject to change. The tips shared in this article work now but may become less relevant in the future.

Also, Microsoft has developed specific libraries, such as MSAL, to run the client-side authentication process. Unless you have a good reason for sending the requests yourself, you should use those for the OAuth component. I will share the different requests involved in the OAuth 2.0 implicit flow, as well as how to retrieve an access token for Azure Open AI Services using Entra ID authentication.

How to set up resources and permissions in Azure

Let’s assume you have already successfully created an Azure Open AI Services deployment. In my case, I have a text-davinci-003 deployment named MyDaVinciDeployment, inside a resource called OpenAIResource.

✅ This following process works for any model, including GPT 3.5 turbo, GPT 4 and even Dall-E.

To give users access to the AI service, you must provide them with the Cognitive Services User role by navigating to your AI resource and open the Access control (IAM) tab.

Create an app registration to access the API outside the Azure OpenAI Studio Playground.

This important step provides the Application (client) ID, so copy it and keep it safe.

The app registration is not enough to gain access to the service. It registers the application, but does not grant any permissions. The app registration must be set up to perform authentication so that it can run some operations in the user’s name, with the user’s permissions.

On the app registration page, navigate to the authentication tab and set up a platform configuration for Single-page application. Set your own callback URL, and set the token type to access token.

Next, we need to specify which permissions the authenticated user will delegate to the application. In the API permissions tab, add the Microsoft Cognitive Services > user_impersonation permission. You can find the Microsoft Cognitive Services API by searching it in the “APIs my organization uses” tab. Note that this permission might not show up if there is no AI service registered.

Easy steps for authenticating

We will be performing all of the authentication requests manually, however for testing purposes, you might want to use an API testing tool such as Postman or Insomnia.

Here is a Postman collection to get you started.

The OAuth 2.0 implicit grant flow (the simplest) works as follows:

The client sends a request to the authentication endpoint, specifying an application ID (to indicate which application is sending the request) and the desired scope - in our case: https://cognitiveservices.azure.com/.default
The authentication server returns a login page.
When the login is complete, the authentication endpoint issues an access token which can be used to request resources accessible to the logged in user and within the requested scope. In practice, the server redirects the user to a specific callback url and the token is communicated as a parameter or a fragment of that callback url.

Let's cover both of these requests individually. First, the authentication request.

To keep things minimalistic, we do not include some optional parameters, but you might want to check them out depending on your use case.

For the following request, here's how to find your tenant id.



GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id={client id}
&response_type=token
&redirect_uri={redirect uri}
&scope={https://cognitiveservices.azure.com/.default} # parameters should be URL-encoded
&response_mode=fragment

As an example, this is the request I’ll send:



GET https://login.microsoftonline.com/mycompany.com/oauth2/v2.0/authorize?
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865 # use client ID you copied earlier
&response_type=token
&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
&scope=https%3A%2F%2Fcognitiveservices.azure.com%2F.default
&response_mode=fragment

If you copy this url into a browser, you should be able to log in and eventually be redirected to your callback URL, which contains the access token as a fragment:



GET {callback url}#access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2Z...
&token_type=Bearer
&expires_in=3599
&scope=https%3A%2F%2Fcognitiveservices.azure.com%2F.default

💡 If the authentication fails, you might want to make sure that Multi-Factor Authentication is enabled. It might not work without it.
Also, you might need administrator approval for this step.

You can then use this token to interact with your deployment using Azure Open AI Service’s REST API.

As an example:



POST https://OpenAiResource.openai.azure.com/openai/deployments/MyDaVinciDeployment/
completions?api-version=2022-12-01

# Headers
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2Z...

# Body
{
    "prompt": "Once upon a time"
}

This token is valid for a limited time, after which it expires unless it is refreshed.

More AI from Microsoft

The concepts covered in this article remain virtually the same throughout the Azure platform, but you will have to adapt some parameters (namely the user roles and requested scopes) to get your apps to work in the different contexts.

Microsoft offers an array of different AI-powered products, including Azure OpenAI Service, Azure AI Search, Azure AI Speech, and their most recent Microsoft Copilot for Office 365.

Each of these services opens the door to a spectrum of exciting possibilities that we look forward to exploring.

Happy coding!

Concise Gherkin - How brevity improves BDD scenarios

Ivan Poiraudeau — Tue, 27 Feb 2024 09:42:34 +0000

💡 New to behavior-driven development? It’s a fantastic way to collaborate and produce better documentation.
Here’s an introduction, with details about its dedicated language, Gherkin.

In behavior-driven development (BDD), it’s best practice to keep your scenarios BRIEF, an acronym for:

Business language: The words used in a scenario should be drawn from the business domain.
Real data: Examples should use concrete, real data.
Intention revealing: Scenarios should reveal the intent of what the actors in the scenario are trying to achieve, rather than describing the mechanics of how they will achieve it.
Essential: The purpose of a scenario is to illustrate how a rule should behave. Any part of a scenario that does not directly contribute to this purpose are incidental and should be removed.
Focused: Most scenarios should be focused on illustrating a single rule.

Last year, my team at UpSlide overhauled our user management system through BDD. We noticed that focusing on brevity let us validate several principles at once: our scenarios were becoming more intention revealing, essential and focused.

Brevity reveals scenarios intention

Consider this login step:

Given I visit "/login"
When I enter "Bob" in the "user name" field
  And I enter "tester" in the "password" field
  And I press the "login" button
Then I should be greeted with a welcome message

This scenario is filled with unimportant and brittle implementation details. By prioritizing brevity, we can simplify it to:

When Bob logs in
Then Bob should be greeted with a welcome message

The scenario intention becomes clearer: it emphasizes the need for a welcome message upon login, without getting bogged down in implementation specifics.

Brevity keeps scenarios essential

Here is a scenario about email notifications:

Given Alice's email storage is not full
And Alice is not offline
When Alice sends an email
Then Alice should get notified that the email was sent.

If Alice’s storage is full or if she’s offline, the email indeed cannot be sent so she shouldn’t get notified that it was.

In most email happy paths however, these conditions won’t apply and the reader doesn’t need to know about them.
In the test implementation, we should instead ensure the system under test has enough message storage for Alice and operates as if it’s online. We can then streamline the scenario:

When Alice sends an email
Then Alice should get notified that the email was sent.

Considering storage space and internet connection separately lets us explore other behaviors, each with their own scenarios:

Given Alice's email storage is full
When Alice sends an email
Then Alice should be notified that the email couldn't be sent
And that she needs to free up storage

Given Alice is offline
When Alice sends an email
Then Alice should be notified that the email couldn't be sent
And that she needs to connect to the Internet

Brevity focuses scenarios

Follow this example from Monopoly:

Given the player went over the GO square [A]
When the player falls on a CHANCE square [B]
Then the player should earn 200₩
And the player should take the top CHANCE card

We can see that mixing [A] and [B] in other ways (not going over the GO square, not falling on the CHANCE square) could lead to a combinatorial explosion of scenarios.

Again, noting this scenario lacks brevity leads us to more independent scenarios:

When the player goes over the GO square
Then the player should earn 200₩

When the player falls on a CHANCE square
Then the player should take the top CHANCE card

More on BDD principles

In a process akin to other forms of writings, brevity helps me uncover the core ideas behind the system I’m specifying.

💡 If you’re keen on crafting concise scenarios, I’ve put together a step-by-step kata to assist you:

Check it here!

I didn’t talk much about the two other key principles, Business Language and Real Data. This video by Gáspár Nagy (creator of SpecFlow, a .NET BDD framework) delves deeper into them: