2aae6be7a3
It all started with UWP. The [docs](https://docs.microsoft.com/en-us/cpp/cppcx/crt-functions-not-supported-in-universal-windows-platform-apps?view=msvc-170) say: "`Environment variables are not available to UWP apps.`". And it truly won't work, I tried: linker error, the function is simply not present. So, for a year or so, we were `ifdef`ing everything enivoronment-related: console logger, environment credential, managed identity credential. And then just recently we wanted to enable our CI for UWP, including tests and samples. And it required to do more ifdefs (in vcpkg, we don't build samples or tests, so that problem did not exist). It just became more messy. Especially in samples - you can see how we would disable warning with `#pragma warning(disable : 4996)` or defining `_CRT_SECURE_NO_WARNINGS` already, but now came UWP, so we would have to add comment that `getenv()` is not available and make the sample compilation to either fail with clear message, or throw an exception. Plus we would have to detect that we are being compiled on UWP, which also adds visual clutter for reader. You can see how such an irrelevant (for a sample) thing as `getenv` was consuming more and more lines of sample code and reader's attention. But then! I read docs on more APIs for UWP. And I noticed that on .NET you can read environment variables. So I went and checked Win32 API docs for [GetEnvironmentVariable()](https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-getenvironmentvariable) - it says: "`Minimum supported client: ... UWP apps`". **GetEnvironmentVariable() works on UWP!** And so does `SetEnvironmentVariable()` (our tests use it, which means we can make all of them work and execute for UWP). That's good news, but now it would probably be more code: it usually takes more lines to invoke WinAPI, it is no more an one-liner to call `getenv()/setenv()`. So, I encapsulated that into `Azure::Core::_internal::Environment::GetVariable()` and `SetVariable()`. You can see how much less ifdefs is in our code now. Not to mention it works on UWP! Per team request, that API is SDK-internal. Samples use their own mini-helper project, `get-env-helper` that makes is so that `getenv()` works naturally on Linux and macOS, compiles without warnings and works on Win32, and compiles and works on UWP (using `GetEnvironmentStringsA()`) If it was for me, I would just make `Azure::Core::Environment::GetVariable()` public and simplify even further, I think it would be beneficial for sample readers (you can see that extra `get-env-helper` stuff adds just a little more visual clutter, compared to nothing). But I can see reasons against that, why team did not want to do it. |
||
|---|---|---|
| .. | ||
| helpers/get-env | ||
| integration | ||
| README.md | ||
Samples, Snippets, and How-To Guides
Developers like to learn by looking at code, and so the Azure SDK comes with a myriad of code samples in the form of short code snippets, sample applications, and how-to guides. This document describes where to find all these resources.
Structure of the Repository
The Azure SDK repository is organized in the following folder structure, with the main sample locations highlighted using bold font.
/samples (this folder)
README.md (this file)
/sdk (folder containing sources, samples, test for all SDK packages)
/<service> (e.g. storage)
/<package> (e.g. blobs)
README.md (package READMEs contain hello world samples)
/samples (package-specific samples)
/inc (header files)
/src (implementation)
/test
Getting Started (a.k.a. Hello World) Samples
Each package folder contains a package-specific README.md file. Most of these README files contain Hello World code samples illustrating basic usage of the the APIs contained in the package. For example, you can find Hello World samples for the azure-storage-blobs package here.
Package Samples and How-To Guides
Each package folder contains a subfolder called /samples with additional code samples. These samples can be either short programs contained in *.c files, or more complete how-to guides (code samples and some commentary) contained in *.md files. You can find shortcuts to main how-to guides in the How-To Guides List section below.
Integration Samples
Simple applications that illustrate the different approaches to integrate the Azure SDK for C++ to your application or library. Each sample contains a README with a description and explanation.
Sample Applications
Sometimes we want to illustrate how several APIs or even packages work together in a context of a more complete program. For these cases, we created sample applications that you can look at, download, compile, and execute. These application samples are located on https://docs.microsoft.com/samples/.
How-To Guide List
This section lists how-to guides for the most commonly used APIs and most common scenarios, i.e. this section does not attempt to be a complete directory of guides contained in this repository.
General How-To Guides
- How to configure, access, and analyze logging information (TODO)